CLI Interface

/**
 * Commitlint CLI binary
 * Usage: commitlint [options] [input]
 * Binary path: ./cli.js
 */
interface CliFlags {
  /** Toggle colored output (default: true) */
  color: boolean;
  /** Path to the config file; result code 9 if config is missing */
  config?: string;
  /** Print resolved config ('text' | 'json' | '') */
  "print-config"?: string;
  /** Directory to execute in (default: working directory) */
  cwd: string;
  /** Read last commit message from specified file or .git/COMMIT_EDITMSG */
  edit?: string | boolean;
  /** Check message in file at path given by environment variable value */
  env?: string;
  /** Array of shareable configurations to extend */
  extends?: (string | number)[];
  /** Show help information */
  help?: boolean;
  /** Help URL in error message */
  "help-url"?: string;
  /** Lower end of the commit range to lint; applies if edit=false */
  from?: string;
  /** Uses last tag as lower end of commit range; applies if edit=false and from is not set */
  "from-last-tag"?: boolean;
  /** Additional git log arguments as space separated string */
  "git-log-args"?: string;
  /** Just analyze the last commit; applies if edit=false */
  last?: boolean;
  /** Output format of the results */
  format?: string;
  /** Configuration preset to use for conventional-commits-parser */
  "parser-preset"?: string;
  /** Toggle console output (default: false) */
  quiet: boolean;
  /** Upper end of the commit range to lint; applies if edit=false */
  to?: string;
  /** Show version information */
  version?: boolean;
  /** Enable verbose output for reports without problems */
  verbose?: boolean;
  /** Enable strict mode; result code 2 for warnings, 3 for errors */
  strict?: boolean;
  /** Positional arguments from yargs */
  _: (string | number)[];
  /** Script name from yargs */
  $0: string;
}

enum ExitCode {
  /** Successful validation or operation */
  CommitlintDefault = 0,
  /** General error or validation failure */
  CommitlintErrorDefault = 1,
  /** Warning in strict mode */
  CommitLintWarning = 2,
  /** Error in strict mode */
  CommitLintError = 3,
  /** Invalid argument or missing configuration */
  CommitlintInvalidArgument = 9
}

/**
 * Main CLI execution function
 * @param args - CLI arguments object or promise resolving to arguments
 * @returns Promise resolving when CLI execution completes
 * @throws CliError with appropriate exit code on validation failure
 */
async function main(args: MainArgs): Promise<void>;

type MainArgsObject = {
  [key in keyof Arguments<CliFlags>]: Arguments<CliFlags>[key];
};
type MainArgsPromise = Promise<MainArgsObject>;
type MainArgs = MainArgsObject | MainArgsPromise;

class CliError extends Error {
  constructor(
    message: string,
    type: string,
    error_code?: ExitCode
  );
  
  readonly type: string;
  readonly error_code: ExitCode;
}

# Lint message from stdin
echo "feat: add user authentication" | commitlint

# Lint with custom configuration
echo "feat: add auth" | commitlint --config ./custom.config.js

# Print configuration in JSON format
commitlint --print-config json

# Lint commits in range
commitlint --from=HEAD~5 --to=HEAD

# Lint from last tag to HEAD
commitlint --from-last-tag

# Lint only the last commit
commitlint --last

# Lint from edit file (useful with Git hooks)
commitlint --edit

# Lint from specific file
commitlint --edit /path/to/commit-msg-file

# Lint from environment variable
export COMMIT_MSG="feat: new feature"
commitlint --env COMMIT_MSG

# Strict mode with specific exit codes
commitlint --strict --last

# Custom output formatting
commitlint --format json --last

# Verbose output with help URL
commitlint --verbose --help-url "https://example.com/commit-help"

# Additional git log arguments
commitlint --from=HEAD~10 --git-log-args "--first-parent --no-merges"

# Extend specific configurations
commitlint --extends @commitlint/config-angular --extends ./custom-rules

# Use parser preset
commitlint --parser-preset angular --last

# Specify working directory
commitlint --cwd /path/to/project --last

# Git hook integration (pre-commit)
#!/bin/sh
npx commitlint --edit "$1"

# CI/CD pipeline
commitlint --from=origin/main --to=HEAD

# Husky integration
npx commitlint --edit "$HUSKY_GIT_PARAMS"