Built-in Rules

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

type RuleConfigCondition = "always" | "never";
type RuleOutcome = Readonly<[boolean, string?]>;

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

// Rule configuration tuple: [severity, condition, value?]
type RuleConfigTuple<T> = T extends void
  ? Readonly<[RuleConfigSeverity.Disabled]> | 
    Readonly<[RuleConfigSeverity, RuleConfigCondition]>
  : Readonly<[RuleConfigSeverity.Disabled]> | 
    Readonly<[RuleConfigSeverity, RuleConfigCondition, T]>;

// Case rule configuration
type CaseRuleConfig<V = RuleConfigQuality.User> = RuleConfig<V, TargetCaseType>;

// Length rule configuration  
type LengthRuleConfig<V = RuleConfigQuality.User> = RuleConfig<V, number>;

// Enum rule configuration
type EnumRuleConfig<V = RuleConfigQuality.User> = RuleConfig<V, string[]>;

/**
 * Enforce case for commit body text
 * @param parsed - Parsed commit object
 * @param when - "always" or "never"
 * @param value - Target case type
 * @returns Rule validation result
 */
const bodyCase: Rule<TargetCaseType>;

// Configuration: [2, "always", "lower-case"]
// Example valid: "implement user authentication using jwt tokens"
// Example invalid: "Implement User Authentication Using JWT Tokens"

/**
 * Control if body must be empty or non-empty
 * @param parsed - Parsed commit object
 * @param when - "always" (must be empty) or "never" (must not be empty)
 * @returns Rule validation result
 */
const bodyEmpty: Rule<void>;

// Configuration: [2, "never"] - body must not be empty
// Example valid: "feat: add auth\n\nImplement OAuth2 flow"
// Example invalid: "feat: add auth"

/**
 * Control full stop at end of body
 * @param parsed - Parsed commit object
 * @param when - "always" (must end with) or "never" (must not end with)
 * @param value - Full stop character (default: ".")
 * @returns Rule validation result
 */
const bodyFullStop: Rule<string>;

// Configuration: [2, "always", "."]
// Example valid: "Detailed explanation of changes."
// Example invalid: "Detailed explanation of changes"

/**
 * Require leading blank line before body
 * @param parsed - Parsed commit object
 * @param when - "always" (require) or "never" (forbid)
 * @returns Rule validation result
 */
const bodyLeadingBlank: Rule<void>;

// Configuration: [2, "always"]
// Example valid: "feat: add auth\n\nDetailed body"
// Example invalid: "feat: add auth\nDetailed body"

/**
 * Enforce maximum body length
 * @param parsed - Parsed commit object
 * @param when - "always" or "never"
 * @param value - Maximum character count
 * @returns Rule validation result
 */
const bodyMaxLength: Rule<number>;

// Configuration: [2, "always", 500]

/**
 * Enforce maximum line length in body
 * @param parsed - Parsed commit object
 * @param when - "always" or "never"
 * @param value - Maximum characters per line
 * @returns Rule validation result
 */
const bodyMaxLineLength: Rule<number>;

// Configuration: [2, "always", 100]

/**
 * Enforce minimum body length
 * @param parsed - Parsed commit object
 * @param when - "always" or "never"
 * @param value - Minimum character count
 * @returns Rule validation result
 */
const bodyMinLength: Rule<number>;

// Configuration: [2, "always", 20]

/**
 * Control if footer must be empty or non-empty
 * @param parsed - Parsed commit object
 * @param when - "always" (must be empty) or "never" (must not be empty)
 * @returns Rule validation result
 */
const footerEmpty: Rule<void>;

/**
 * Require leading blank line before footer
 * @param parsed - Parsed commit object
 * @param when - "always" (require) or "never" (forbid)
 * @returns Rule validation result
 */
const footerLeadingBlank: Rule<void>;

/**
 * Enforce maximum footer length
 * @param parsed - Parsed commit object
 * @param when - "always" or "never"
 * @param value - Maximum character count
 * @returns Rule validation result
 */
const footerMaxLength: Rule<number>;

/**
 * Enforce maximum line length in footer
 * @param parsed - Parsed commit object
 * @param when - "always" or "never"
 * @param value - Maximum characters per line
 * @returns Rule validation result
 */
const footerMaxLineLength: Rule<number>;

/**
 * Enforce minimum footer length
 * @param parsed - Parsed commit object
 * @param when - "always" or "never"
 * @param value - Minimum character count
 * @returns Rule validation result
 */
const footerMinLength: Rule<number>;

/**
 * Enforce case for entire header
 * @param parsed - Parsed commit object
 * @param when - "always" or "never"
 * @param value - Target case type
 * @returns Rule validation result
 */
const headerCase: Rule<TargetCaseType>;

// Configuration: [2, "always", "lower-case"]
// Example valid: "feat(api): add user authentication"
// Example invalid: "Feat(API): Add User Authentication"

/**
 * Control full stop at end of header
 * @param parsed - Parsed commit object
 * @param when - "always" (must end with) or "never" (must not end with)
 * @param value - Full stop character
 * @returns Rule validation result
 */
const headerFullStop: Rule<string>;

// Configuration: [2, "never", "."]
// Example valid: "feat: add user authentication"
// Example invalid: "feat: add user authentication."

/**
 * Enforce maximum header length
 * @param parsed - Parsed commit object
 * @param when - "always" or "never"
 * @param value - Maximum character count
 * @returns Rule validation result
 */
const headerMaxLength: Rule<number>;

// Configuration: [2, "always", 100]
// Most common setting for conventional commits

/**
 * Enforce minimum header length
 * @param parsed - Parsed commit object
 * @param when - "always" or "never"
 * @param value - Minimum character count
 * @returns Rule validation result
 */
const headerMinLength: Rule<number>;

// Configuration: [2, "always", 10]

/**
 * Require trimmed header (no leading/trailing spaces)
 * @param parsed - Parsed commit object
 * @param when - "always" or "never"
 * @returns Rule validation result
 */
const headerTrim: Rule<void>;

// Configuration: [2, "always"]
// Example valid: "feat: add feature"
// Example invalid: " feat: add feature " or "feat: add feature "

/**
 * Enforce case for scope
 * @param parsed - Parsed commit object
 * @param when - "always" or "never"
 * @param value - Target case type
 * @returns Rule validation result
 */
const scopeCase: Rule<TargetCaseType>;

// Configuration: [2, "always", "lower-case"]
// Example valid: "feat(api): add endpoint"
// Example invalid: "feat(API): add endpoint"

/**
 * Control if scope must be empty or non-empty
 * @param parsed - Parsed commit object
 * @param when - "always" (must be empty) or "never" (must not be empty)
 * @returns Rule validation result
 */
const scopeEmpty: Rule<void>;

// Configuration: [2, "never"] - scope must be provided
// Example valid: "feat(auth): add login"
// Example invalid: "feat: add login"

/**
 * Restrict scope to enumerated values
 * @param parsed - Parsed commit object
 * @param when - "always" (must be in list) or "never" (must not be in list)
 * @param value - Array of allowed scope values
 * @returns Rule validation result
 */
const scopeEnum: Rule<string[]>;

// Configuration: [2, "always", ["api", "ui", "core", "docs"]]
// Example valid: "feat(api): add endpoint"
// Example invalid: "feat(backend): add endpoint"

/**
 * Enforce maximum scope length
 * @param parsed - Parsed commit object
 * @param when - "always" or "never"
 * @param value - Maximum character count
 * @returns Rule validation result
 */
const scopeMaxLength: Rule<number>;

/**
 * Enforce minimum scope length
 * @param parsed - Parsed commit object
 * @param when - "always" or "never"
 * @param value - Minimum character count
 * @returns Rule validation result
 */
const scopeMinLength: Rule<number>;

/**
 * Enforce case for subject
 * @param parsed - Parsed commit object
 * @param when - "always" or "never"
 * @param value - Target case type or array of case types
 * @returns Rule validation result
 */
const subjectCase: Rule<TargetCaseType | TargetCaseType[]>;

// Configuration: [2, "always", "lower-case"]
// Example valid: "feat: add user authentication"
// Example invalid: "feat: Add User Authentication"

/**
 * Control if subject must be empty or non-empty
 * @param parsed - Parsed commit object
 * @param when - "always" (must be empty) or "never" (must not be empty)
 * @returns Rule validation result
 */
const subjectEmpty: Rule<void>;

// Configuration: [2, "never"] - subject must be provided
// Example valid: "feat: add feature"
// Example invalid: "feat:"

/**
 * Control full stop at end of subject
 * @param parsed - Parsed commit object
 * @param when - "always" (must end with) or "never" (must not end with)
 * @param value - Full stop character
 * @returns Rule validation result
 */
const subjectFullStop: Rule<string>;

// Configuration: [2, "never", "."]
// Example valid: "feat: add authentication"
// Example invalid: "feat: add authentication."

/**
 * Enforce maximum subject length
 * @param parsed - Parsed commit object
 * @param when - "always" or "never"
 * @param value - Maximum character count
 * @returns Rule validation result
 */
const subjectMaxLength: Rule<number>;

/**
 * Enforce minimum subject length
 * @param parsed - Parsed commit object
 * @param when - "always" or "never"
 * @param value - Minimum character count
 * @returns Rule validation result
 */
const subjectMinLength: Rule<number>;

/**
 * Enforce case for type
 * @param parsed - Parsed commit object
 * @param when - "always" or "never"
 * @param value - Target case type
 * @returns Rule validation result
 */
const typeCase: Rule<TargetCaseType>;

// Configuration: [2, "always", "lower-case"]
// Example valid: "feat: add feature"
// Example invalid: "FEAT: add feature"

/**
 * Control if type must be empty or non-empty
 * @param parsed - Parsed commit object
 * @param when - "always" (must be empty) or "never" (must not be empty)
 * @returns Rule validation result
 */
const typeEmpty: Rule<void>;

// Configuration: [2, "never"] - type must be provided
// Example valid: "feat: add feature"
// Example invalid: ": add feature"

/**
 * Restrict type to enumerated values
 * @param parsed - Parsed commit object
 * @param when - "always" (must be in list) or "never" (must not be in list)
 * @param value - Array of allowed type values
 * @returns Rule validation result
 */
const typeEnum: Rule<string[]>;

// Configuration: [2, "always", ["feat", "fix", "docs", "style", "refactor", "test", "chore"]]
// Example valid: "feat: add feature"
// Example invalid: "feature: add feature"

/**
 * Enforce maximum type length
 * @param parsed - Parsed commit object
 * @param when - "always" or "never"
 * @param value - Maximum character count
 * @returns Rule validation result
 */
const typeMaxLength: Rule<number>;

/**
 * Enforce minimum type length
 * @param parsed - Parsed commit object
 * @param when - "always" or "never"
 * @param value - Minimum character count
 * @returns Rule validation result
 */
const typeMinLength: Rule<number>;

/**
 * Control if references must be empty or non-empty
 * @param parsed - Parsed commit object
 * @param when - "always" (must be empty) or "never" (must not be empty)
 * @returns Rule validation result
 */
const referencesEmpty: Rule<void>;

// Configuration: [2, "never"] - references must be provided
// Example valid: "fix: resolve bug\n\nCloses #123"
// Example invalid: "fix: resolve bug"

/**
 * Require signed-off-by trailer
 * @param parsed - Parsed commit object
 * @param when - "always" (must have) or "never" (must not have)
 * @param value - Required sign-off string
 * @returns Rule validation result
 */
const signedOffBy: Rule<string>;

// Configuration: [2, "always", "Signed-off-by:"]
// Example valid: "feat: add feature\n\nSigned-off-by: John Doe <john@example.com>"

/**
 * Require specific trailer
 * @param parsed - Parsed commit object
 * @param when - "always" (must exist) or "never" (must not exist)
 * @param value - Required trailer key
 * @returns Rule validation result
 */
const trailerExists: Rule<string>;

// Configuration: [2, "always", "Reviewed-by"]
// Example valid: "feat: add feature\n\nReviewed-by: Jane Smith"

type TargetCaseType = 
  | "camel-case"      // camelCase
  | "kebab-case"      // kebab-case
  | "snake-case"      // snake_case
  | "pascal-case"     // PascalCase
  | "start-case"      // Start Case
  | "upper-case"      // UPPER CASE
  | "uppercase"       // UPPERCASE
  | "sentence-case"   // Sentence case
  | "sentencecase"    // Sentencecase
  | "lower-case"      // lower case
  | "lowercase"       // lowercase
  | "lowerCase";      // lowerCase

// commitlint.config.js
module.exports = {
  rules: {
    // Type must be one of specified values
    "type-enum": [2, "always", [
      "build", "chore", "ci", "docs", "feat", 
      "fix", "perf", "refactor", "revert", "style", "test"
    ]],
    
    // Type must be lowercase
    "type-case": [2, "always", "lower-case"],
    
    // Type cannot be empty
    "type-empty": [2, "never"],
    
    // Subject must be lowercase
    "subject-case": [2, "always", "lower-case"],
    
    // Subject cannot be empty
    "subject-empty": [2, "never"],
    
    // Header cannot exceed 100 characters
    "header-max-length": [2, "always", 100],
    
    // Header cannot end with period
    "header-full-stop": [2, "never", "."]
  }
};

// Multi-package repository
module.exports = {
  rules: {
    "scope-enum": [2, "always", [
      "api", "ui", "shared", "cli", "docs", "build"
    ]],
    "scope-empty": [2, "never"], // Scope is required
    "scope-case": [2, "always", "lower-case"]
  }
};

module.exports = {
  rules: {
    // Error level - will fail commit
    "type-enum": [2, "always", ["feat", "fix", "docs"]],
    
    // Warning level - will warn but allow commit
    "body-max-length": [1, "always", 500],
    
    // Disabled - rule will not run
    "footer-empty": [0]
  }
};