Linting Engine

/**
 * Lint a commit message against provided rules
 * @param message - Commit message string to validate
 * @param rawRulesConfig - Rule configuration object (optional)
 * @param rawOpts - Linting options (optional)
 * @returns Promise resolving to detailed validation results
 */
function lint(
  message: string,
  rawRulesConfig?: QualifiedRules,
  rawOpts?: LintOptions
): Promise<LintOutcome>;

interface LintOptions {
  /** Whether to use default ignore patterns (default: true) */
  defaultIgnores?: boolean;
  /** Custom ignore functions to skip certain commits */
  ignores?: ((commit: string) => boolean)[];
  /** Parser options for conventional-commits-parser */
  parserOpts?: Options;
  /** Plugin objects providing additional rules */
  plugins?: PluginRecords;
  /** Help URL to include in error messages */
  helpUrl?: string;
}

interface LintOutcome {
  /** Original input commit message */
  input: string;
  /** Overall validation result (true if no errors) */
  valid: boolean;
  /** Array of error-level rule violations */
  errors: LintRuleOutcome[];
  /** Array of warning-level rule violations */
  warnings: LintRuleOutcome[];
}

interface LintRuleOutcome {
  /** Whether this specific rule passed validation */
  valid: boolean;
  /** Severity level of the rule (0=disabled, 1=warning, 2=error) */
  level: RuleConfigSeverity;
  /** Name of the rule that was executed */
  name: string;
  /** Human-readable message describing the violation or success */
  message: string;
}

type QualifiedRules = {
  [ruleName: string]: QualifiedRuleConfig;
};

type QualifiedRuleConfig = 
  | QualifiedRuleConfigTuple<void>
  | QualifiedRuleConfigTuple<any>;

type QualifiedRuleConfigTuple<T> = T extends void
  ? Readonly<[RuleConfigSeverity.Disabled]> | 
    Readonly<[RuleConfigSeverity, RuleConfigCondition]>
  : Readonly<[RuleConfigSeverity.Disabled]> | 
    Readonly<[RuleConfigSeverity, RuleConfigCondition, T]>;

enum RuleConfigSeverity {
  Disabled = 0,
  Warning = 1,
  Error = 2
}

type RuleConfigCondition = "always" | "never";

interface Commit {
  /** Original raw commit message */
  raw: string;
  /** Commit header (first line) */
  header: string;
  /** Commit type (e.g., 'feat', 'fix') */
  type: string | null;
  /** Commit scope (e.g., 'api', 'ui') */
  scope: string | null;
  /** Commit subject (description) */
  subject: string | null;
  /** Commit body (detailed description) */
  body: string | null;
  /** Commit footer (metadata, references) */
  footer: string | null;
  /** Breaking change notes and other notable information */
  notes: CommitNote[];
  /** Issue and PR references */
  references: CommitReference[];
  /** User mentions (@username) */
  mentions: string[];
  /** Revert commit information */
  revert: CommitRevert | null;
  /** Merge commit information */
  merge: string | null;
}

interface CommitNote {
  title: string;
  text: string;
}

interface CommitReference {
  action: string;
  owner: string | null;
  repository: string | null;
  issue: string;
  raw: string;
  prefix: string;
}

interface CommitRevert {
  header: string;
  hash: string | null;
}

type Rule<Value = never> = (
  parsed: Commit,
  when?: RuleConfigCondition,
  value?: Value
) => RuleOutcome | Promise<RuleOutcome>;

type AsyncRule<Value = never> = BaseRule<Value, "async">;
type SyncRule<Value = never> = BaseRule<Value, "sync">;

type RuleOutcome = Readonly<[boolean, string?]>;

import lint from "@commitlint/lint";

// Simple message validation
const result = await lint("feat: add user authentication");

console.log(result.valid); // true
console.log(result.errors); // []
console.log(result.warnings); // []

import lint from "@commitlint/lint";

const rules = {
  "type-enum": [2, "always", ["feat", "fix", "docs", "style"]],
  "subject-case": [2, "always", "lower-case"],
  "header-max-length": [2, "always", 72]
};

const result = await lint("FEAT: Add New Feature", rules);

console.log(result.valid); // false
console.log(result.errors); // Array of validation errors

import lint from "@commitlint/lint";

const rules = {
  "type-enum": [2, "always", ["feat", "fix", "docs"]],
  "subject-empty": [2, "never"]
};

const options = {
  defaultIgnores: true,
  ignores: [
    (commit) => commit.includes("WIP"),
    (commit) => commit.startsWith("fixup!")
  ],
  parserOpts: {
    commentChar: "#",
    headerPattern: /^(\w*)(?:\((.*)\))?: (.*)$/,
    headerCorrespondence: ["type", "scope", "subject"]
  },
  helpUrl: "https://example.com/commit-help"
};

const result = await lint("feat(api): add user endpoint", rules, options);

import lint from "@commitlint/lint";

const result = await lint("invalid commit message", rules);

if (!result.valid) {
  console.log(`Validation failed for: ${result.input}`);
  
  // Process errors
  result.errors.forEach(error => {
    console.log(`❌ ${error.name}: ${error.message}`);
  });
  
  // Process warnings
  result.warnings.forEach(warning => {
    console.log(`⚠️  ${warning.name}: ${warning.message}`);
  });
}

// Custom rule function
const customRule = (parsed, when = "always", value) => {
  const { subject } = parsed;
  const negated = when === "never";
  const hasValue = subject && subject.includes(value);
  
  return [
    negated ? !hasValue : hasValue,
    `Subject ${negated ? "must not" : "must"} contain "${value}"`
  ];
};

// Use custom rule
const rules = {
  "subject-contains-ticket": [2, "always", "JIRA-"]
};

const plugins = {
  "local": {
    rules: {
      "subject-contains-ticket": customRule
    }
  }
};

const result = await lint(
  "feat: add feature without ticket",
  rules,
  { plugins }
);

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

// Load configuration and lint message
const config = await load();
const result = await lint("feat: new feature", config.rules, {
  parserOpts: config.parserPreset?.parserOpts,
  plugins: config.plugins,
  ignores: config.ignores,
  defaultIgnores: config.defaultIgnores,
  helpUrl: config.helpUrl
});

import lint from "@commitlint/lint";

const messages = [
  "feat: add authentication",
  "fix: resolve login bug", 
  "invalid message format"
];

const rules = {
  "type-enum": [2, "always", ["feat", "fix", "docs"]],
  "subject-empty": [2, "never"]
};

// Process multiple messages
const results = await Promise.all(
  messages.map(message => lint(message, rules))
);

// Summary
const totalErrors = results.reduce((sum, result) => sum + result.errors.length, 0);
const totalWarnings = results.reduce((sum, result) => sum + result.warnings.length, 0);
const validCount = results.filter(result => result.valid).length;

console.log(`Processed ${messages.length} commits`);
console.log(`Valid: ${validCount}, Errors: ${totalErrors}, Warnings: ${totalWarnings}`);