@commitlint/lint

Lint a string against commitlint rules

Install

npm install --save @commitlint/lint

Signature

type RuleLevel = 0 | 1 | 2;
type RuleCondition = 'always' | 'never';
type RuleOption = any;
type PrimitiveRule = [RuleLevel, RuleCondition, RuleOption?];
type AsyncRule = Promise<PrimitiveRule>;
type FunctionRule = () => PrimitiveRule;
type AsyncFunctionRule = () => Promise<PrimitiveRule>;
type Rule = PrimitiveRule | FunctionRule | AsyncFunctionRule;

type Problem = {
  level: number;
  valid: boolean;
  name: string;
  message: string;
}

type Report = {
  valid: boolean;
  errors: Problem[];
  warnings: Problem[];
}

type Options = {
  parserOpts?: any;
};

lint(message: string, rules: {[ruleName: string]: Rule}, opts?: Options) => Promise<Report>;

Basic Examples

Import

import lint from "@commitlint/lint";

Usage without config

const report = await lint("foo: bar");
console.log(report);
// => { valid: true, errors: [], warnings: [] }

Usage with type-enum rules and valid message

const report = await lint("foo: bar", { "type-enum": [1, "always", ["foo"]] });
console.log(report);
// => { valid: true, errors: [], warnings: [] }

Usage with type-enum rules and invalid message

const report = await lint("foo: bar", { "type-enum": [1, "always", ["bar"]] });
console.log(report);
/* => 
{ 
  valid: false,
  errors: [],
  warnings: [ 
    { 
      level: 1,
      valid: false,
      name: 'type-enum',
      message: 'type must be one of [bar]' 
    } 
  ]
}
*/

Usage with custom parser options

const opts = {
  parserOpts: {
    headerPattern: /^(\w*)-(\w*)/,
    headerCorrespondence: ["type", "scope"],
  },
};

const report = await lint(
  "foo-bar",
  { "type-enum": [2, "always", ["foo"]] },
  opts,
);
console.log(report);
// => { valid: true, errors: [], warnings: [] }

Load configuration

import load from "@commitlint/load";
import lint from "@commitlint/lint";

const CONFIG = {
  extends: ["@commitlint/config-conventional"],
};

const opts = await load(CONFIG);
const report = await lint(
  "foo: bar",
  opts.rules,
  opts.parserPreset ? { parserOpts: opts.parserPreset.parserOpts } : {},
);
console.log(report);
/* => 
{ 
  valid: false,
  errors: [ 
    { 
      level: 2,
      valid: false,
      name: 'type-enum',
      message: 'type must be one of [build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test]' 
    } 
  ],
  warnings: [] 
}
*/

Read git history

import lint from "@commitlint/lint";
import read from "@commitlint/read";

const RULES = {
  "type-enum": [2, "always", ["foo"]],
};

const commits = await read({ to: "HEAD", from: "HEAD~2" });

console.info(commits.map((commit) => lint(commit, RULES)));

Simplified last-commit checker

import load from "@commitlint/load";
import read from "@commitlint/read";
import lint from "@commitlint/lint";

const { rules, parserPreset } = load();
const [commit] = await read({ from: "HEAD~1" });

const report = await lint(
  commit,
  rules,
  parserPreset ? { parserOpts: parserPreset.parserOpts } : {},
);

console.log(JSON.stringify(result.valid));