tessl/npm-commitlint--cli

Lint your commit messages with configurable rules and conventional commit support

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Built-in Rules

Name: tessl/npm-commitlint--cli
Author: tessl

Comprehensive rule system with 25+ built-in rules covering all parts of conventional commits including type, scope, subject, body, and footer validation.

Rule System Overview

Rule Function Interface

Base interface for all commitlint rules, both built-in and custom.

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 Format

Standard configuration format for all rules.

// 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[]>;

Body Rules

Rules for validating the commit message body section.

body-case

/**
 * 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"

body-empty

/**
 * 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"

body-full-stop

/**
 * 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"

body-leading-blank

/**
 * 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"

body-max-length

/**
 * 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]

body-max-line-length

/**
 * 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]

body-min-length

/**
 * 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]

Footer Rules

Rules for validating the commit message footer section.

footer-empty

/**
 * 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>;

footer-leading-blank

/**
 * 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>;

footer-max-length

/**
 * 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>;

footer-max-line-length

/**
 * 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>;

footer-min-length

/**
 * 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>;

Header Rules

Rules for validating the entire commit header (first line).

header-case

/**
 * 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"

header-full-stop

/**
 * 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."

header-max-length

/**
 * 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

header-min-length

/**
 * 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]

header-trim

/**
 * 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 "

Scope Rules

Rules for validating the commit scope (part within parentheses).

scope-case

/**
 * 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"

scope-empty

/**
 * 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"

scope-enum

/**
 * 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"

scope-max-length

/**
 * 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>;

scope-min-length

/**
 * 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>;

Subject Rules

Rules for validating the commit subject (description part).

subject-case

/**
 * 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"

subject-empty

/**
 * 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:"

subject-full-stop

/**
 * 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."

subject-max-length

/**
 * 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>;

subject-min-length

/**
 * 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>;

Type Rules

Rules for validating the commit type (first word before colon).

type-case

/**
 * 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"

type-empty

/**
 * 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"

type-enum

/**
 * 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"

type-max-length

/**
 * 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>;

type-min-length

/**
 * 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>;

Other Rules

Additional rules for specialized commit message validation.

references-empty

/**
 * 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"

signed-off-by

/**
 * 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>"

trailer-exists

/**
 * 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"

Case Types

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

Usage Examples

Basic Rule Configuration

// 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", "."]
  }
};

Workspace-specific Rules

// 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"]
  }
};

Custom Rule Severity

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]
  }
};

docs

built-in-rules.md

cli-interface.md

commit-reading.md

configuration-presets.md

configuration-system.md

tessl/npm-commitlint--cli

built-in-rules.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Built-in Rules

Rule System Overview

Rule Function Interface

Rule Configuration Format

Body Rules

body-case

body-empty

body-full-stop

body-leading-blank

body-max-length

body-max-line-length

body-min-length

Footer Rules

footer-empty

footer-leading-blank

footer-max-length

footer-max-line-length

footer-min-length

Header Rules

header-case

header-full-stop

header-max-length

header-min-length

header-trim

Scope Rules

scope-case

scope-empty

scope-enum

scope-max-length

scope-min-length

Subject Rules

subject-case

subject-empty

subject-full-stop

subject-max-length

subject-min-length

Type Rules

type-case

type-empty

type-enum

type-max-length

type-min-length

Other Rules

references-empty

signed-off-by

trailer-exists

Case Types

Usage Examples

Basic Rule Configuration

Workspace-specific Rules

Custom Rule Severity

built-in-rules.mddocs/