Configuration System

/**
 * Load and resolve commitlint configuration
 * @param seed - Optional initial configuration to merge
 * @param options - Loading options including working directory and config file path
 * @returns Promise resolving to qualified configuration object
 */
function load(
  seed?: UserConfig,
  options?: LoadOptions
): Promise<QualifiedConfig>;

interface LoadOptions {
  /** Working directory for configuration resolution (default: process.cwd()) */
  cwd?: string;
  /** Specific configuration file path to load */
  file?: string;
}

interface UserConfig {
  /** Shareable configuration to extend (string or array of strings) */
  extends?: string | string[];
  /** Custom formatter for output (module path or name) */
  formatter?: string;
  /** Rule configuration object with rule names and settings */
  rules?: Partial<RulesConfig>;
  /** Parser preset for conventional-commits-parser */
  parserPreset?: string | ParserPreset | Promise<ParserPreset>;
  /** Functions to determine if commits should be ignored */
  ignores?: ((commit: string) => boolean)[];
  /** Whether to use default ignore patterns (default: true) */
  defaultIgnores?: boolean;
  /** Plugins providing additional rules (array of names or plugin objects) */
  plugins?: (string | Plugin)[];
  /** Help URL to include in error messages */
  helpUrl?: string;
  /** Interactive prompt configuration */
  prompt?: UserPromptConfig;
  /** Additional properties for extensibility */
  [key: string]: unknown;
}

interface QualifiedConfig {
  /** Resolved array of extended configuration names */
  extends: string[];
  /** Resolved formatter module path */
  formatter: string;
  /** Fully qualified rules configuration */
  rules: QualifiedRules;
  /** Resolved parser preset configuration */
  parserPreset?: ParserPreset;
  /** Array of ignore functions */
  ignores?: ((commit: string) => boolean)[];
  /** Whether default ignores are enabled */
  defaultIgnores?: boolean;
  /** Resolved plugin objects mapped by name */
  plugins: PluginRecords;
  /** Help URL for error messages */
  helpUrl: string;
  /** Prompt configuration for interactive mode */
  prompt: UserPromptConfig;
}

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 ParserPreset {
  name?: string;
  path?: string;
  parserOpts?: unknown;
}

interface Options {
  /** Character used for comments in commit messages */
  commentChar?: string;
  /** Header pattern regex for parsing commits */
  headerPattern?: RegExp;
  /** Correspondence between regex groups and commit properties */
  headerCorrespondence?: string[];
  /** Reference actions that indicate issue closure */
  referenceActions?: string[];
  /** Prefixes for issue references */
  issuePrefixes?: string[];
  /** Notable words that trigger commit notes */
  noteKeywords?: string[];
  /** Field patterns for commit notes */
  fieldPattern?: RegExp;
  /** Revert pattern for detecting revert commits */
  revertPattern?: RegExp;
  /** Correspondence for revert commit parsing */
  revertCorrespondence?: string[];
  /** Warning patterns for commit parsing */
  warn?: boolean;
  /** Merge pattern for detecting merge commits */
  mergePattern?: RegExp;
  /** Correspondence for merge commit parsing */
  mergeCorrespondence?: string[];
}

interface Plugin {
  /** Object mapping rule names to rule functions */
  rules: {
    [ruleName: string]: Rule | AsyncRule | SyncRule;
  };
}

type PluginRecords = Record<string, Plugin>;

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

/**
 * Resolve module from specified path
 * @param id - Module identifier or path
 * @param options - Resolution options including paths
 * @returns Resolved module path or null if not found
 */
function resolveFrom(id: string, fromDir: string): string;

/**
 * Silent version of resolveFrom that returns null instead of throwing
 * @param id - Module identifier or path
 * @param fromDir - Directory to resolve from
 * @returns Resolved module path or null if not found
 */
function resolveFromSilent(id: string, fromDir: string): string | null;

/**
 * Resolve module from global node_modules
 * @param id - Module identifier
 * @returns Resolved module path or null if not found
 */
function resolveGlobalSilent(id: string): string | null;

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

// Load configuration from default sources
const config = await load();

// Load with custom working directory
const config = await load(undefined, { cwd: "/path/to/project" });

// Load specific configuration file
const config = await load(undefined, { file: "./custom.config.js" });

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

// Provide initial configuration
const seed = {
  extends: ["@commitlint/config-conventional"],
  rules: {
    "subject-case": [2, "always", "lower-case"]
  }
};

const config = await load(seed);

// commitlint.config.js
module.exports = {
  extends: ["@commitlint/config-conventional"],
  rules: {
    "type-enum": [2, "always", [
      "build", "chore", "ci", "docs", "feat", 
      "fix", "perf", "refactor", "revert", "style", "test"
    ]],
    "subject-case": [2, "always", "lower-case"],
    "header-max-length": [2, "always", 100]
  },
  ignores: [
    (commit) => commit.includes("WIP"),
    (commit) => commit.includes("fixup!")
  ],
  defaultIgnores: true,
  helpUrl: "https://github.com/conventional-changelog/commitlint/#what-is-commitlint"
};

// .commitlintrc.json
{
  "extends": ["@commitlint/config-angular"],
  "rules": {
    "header-max-length": [2, "always", 72],
    "scope-enum": [2, "always", ["core", "common", "forms", "http"]]
  }
}

// commitlint.config.js with custom parser
module.exports = {
  parserPreset: {
    parserOpts: {
      headerPattern: /^(\w*)(?:\((.*)\))?: (.*)$/,
      headerCorrespondence: ["type", "scope", "subject"],
      commentChar: "#",
      noteKeywords: ["BREAKING CHANGE", "BREAKING CHANGES"]
    }
  },
  rules: {
    // Custom rules for the parser format
  }
};

// commitlint.config.js with plugins
module.exports = {
  plugins: [
    "./local-plugin.js",
    "@commitlint/plugin-custom-rules"
  ],
  extends: ["@commitlint/config-conventional"],
  rules: {
    // Built-in rules
    "type-enum": [2, "always", ["feat", "fix", "docs"]],
    // Plugin rules
    "custom-rule-name": [2, "always", "some-value"]
  }
};