CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-commitlint--load

Load shared commitlint configuration

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

@commitlint/load

@commitlint/load provides a configuration loading system for commitlint, enabling developers to load and validate shared commitlint configurations from various sources. It supports loading configurations from cosmiconfig-compatible files, resolving extends hierarchies, validating configuration schemas, and merging multiple configuration sources with proper precedence handling.

Package Information

  • Package Name: @commitlint/load
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @commitlint/load

Core Imports

import load, { resolveFrom, resolveFromSilent, resolveGlobalSilent } from "@commitlint/load";

Note: This is a pure ESM package. For CommonJS environments, use dynamic imports:

const { default: load, resolveFrom, resolveFromSilent, resolveGlobalSilent } = await import("@commitlint/load");

Basic Usage

import load from "@commitlint/load";

// Load configuration from current directory
const config = await load();

// Load with seed configuration and options
const config = await load(
  { rules: { "type-enum": [2, "always", ["feat", "fix"]] } },
  { cwd: "/path/to/project", file: ".commitlintrc.json" }
);

// Access the loaded configuration
console.log(config.rules);
console.log(config.extends);
console.log(config.formatter);

Architecture

The package is built around several key components:

  • Configuration Discovery: Uses cosmiconfig to locate configuration files across multiple file formats
  • Extension Resolution: Resolves and merges extended configurations with proper precedence
  • Plugin System: Loads and manages commitlint plugins dynamically
  • Rule Processing: Processes and validates rule configurations
  • Type Safety: Full TypeScript integration with comprehensive type definitions

Capabilities

Configuration Loading

The main load function resolves commitlint configuration from various sources and formats.

/**
 * Load and resolve commitlint configuration
 * @param seed - Override configuration object (optional)
 * @param options - Loading options including cwd and file path (optional)
 * @returns Promise resolving to fully qualified configuration
 */
export default async function load(
  seed?: UserConfig,
  options?: LoadOptions
): Promise<QualifiedConfig>;

interface LoadOptions {
  /** Current working directory for configuration resolution */
  cwd?: string;
  /** Specific configuration file path to load */
  file?: string;
}

Module Resolution

Utility functions for resolving module paths in different contexts.

/**
 * Resolve module path from a given parent directory
 * @param lookup - Name of module to resolve
 * @param parent - Parent directory to resolve from (optional)
 * @returns Resolved module path
 */
export function resolveFrom(lookup: string, parent?: string): string;

/**
 * Resolve module path silently (no errors thrown)
 * @param specifier - Name of module to resolve
 * @param parent - Parent directory to resolve from (required)
 * @returns Resolved module path or void if not found
 */
export function resolveFromSilent(specifier: string, parent: string): string | void;

/**
 * Resolve global module path silently
 * @param specifier - Name of global module to resolve
 * @returns Resolved global module path or void if not found
 */
export function resolveGlobalSilent(specifier: string): string | void;

Configuration Types

UserConfig

User-provided configuration object that can be passed to the load function.

interface UserConfig {
  /** Configurations to extend (string or array of strings) */
  extends?: string | string[];
  /** Formatter module name or path */
  formatter?: string;
  /** Rule configuration object */
  rules?: Partial<RulesConfig>;
  /** Parser preset configuration */
  parserPreset?: string | ParserPreset | Promise<ParserPreset>;
  /** Array of ignore functions for commit messages */
  ignores?: ((commit: string) => boolean)[];
  /** Whether to use default ignore patterns */
  defaultIgnores?: boolean;
  /** Array of plugin names or plugin objects */
  plugins?: (string | Plugin)[];
  /** Help documentation URL */
  helpUrl?: string;
  /** Prompt configuration for interactive mode */
  prompt?: UserPromptConfig;
  /** Additional properties */
  [key: string]: unknown;
}

QualifiedConfig

Fully resolved and processed configuration returned by the load function.

interface QualifiedConfig {
  /** Array of resolved extended configuration names */
  extends: string[];
  /** Resolved formatter module path */
  formatter: string;
  /** Processed and validated rules */
  rules: QualifiedRules;
  /** Resolved parser preset configuration */
  parserPreset?: ParserPreset;
  /** Array of ignore functions */
  ignores?: ((commit: string) => boolean)[];
  /** Whether default ignores are enabled */
  defaultIgnores?: boolean;
  /** Record of loaded plugins */
  plugins: PluginRecords;
  /** Help documentation URL */
  helpUrl: string;
  /** Prompt configuration */
  prompt: UserPromptConfig;
}

ParserPreset

Parser preset configuration for commit message parsing.

interface ParserPreset {
  /** Preset name */
  name?: string;
  /** Preset module path */
  path?: string;
  /** Parser options object */
  parserOpts?: unknown;
}

Plugin Types

Plugin-related type definitions for the plugin system.

type PluginRecords = Record<string, Plugin>;

interface Plugin {
  /** Map of rule names to rule implementations */
  rules: {
    [ruleName: string]: Rule | AsyncRule | SyncRule;
  };
}

Rule System

Rule Configuration

Rule configuration system with severity levels and conditions.

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

type RuleConfigCondition = "always" | "never";

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

enum RuleConfigQuality {
  User,
  Qualified,
}

type QualifiedRuleConfig<T> =
  | (() => RuleConfigTuple<T>)
  | (() => Promise<RuleConfigTuple<T>>)
  | RuleConfigTuple<T>;

type RuleConfig<V = RuleConfigQuality.Qualified, T = void> = V extends RuleConfigQuality.Qualified
  ? RuleConfigTuple<T>
  : QualifiedRuleConfig<T>;

type QualifiedRules = Partial<RulesConfig<RuleConfigQuality.Qualified>>;

Rule Types

Rule implementation interfaces for creating custom rules.

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

// Commit type from conventional-commits-parser
interface Commit {
  raw: string;
  header: string;
  type: string | null;
  scope: string | null;
  subject: string | null;
  merge: string | null;
  footer: string | null;
  notes: CommitNote[];
  references: CommitReference[];
  mentions: string[];
  revert: CommitRevert | null;
  body: 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> = (
  parsed: Commit,
  when?: RuleConfigCondition,
  value?: Value
) => Promise<RuleOutcome>;

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

Available Rules

Standard commitlint rules configuration options.

type CaseRuleConfig<V = RuleConfigQuality.User> = RuleConfig<V, TargetCaseType | TargetCaseType[]>;
type LengthRuleConfig<V = RuleConfigQuality.User> = RuleConfig<V, number>;
type EnumRuleConfig<V = RuleConfigQuality.User> = RuleConfig<V, string[]>;

type RulesConfig<V = RuleConfigQuality.User> = {
  // Body rules
  "body-case": CaseRuleConfig<V>;
  "body-empty": RuleConfig<V>;
  "body-full-stop": RuleConfig<V, string>;
  "body-leading-blank": RuleConfig<V>;
  "body-max-length": LengthRuleConfig<V>;
  "body-max-line-length": LengthRuleConfig<V>;
  "body-min-length": LengthRuleConfig<V>;
  
  // Footer rules
  "footer-empty": RuleConfig<V>;
  "footer-leading-blank": RuleConfig<V>;
  "footer-max-length": LengthRuleConfig<V>;
  "footer-max-line-length": LengthRuleConfig<V>;
  "footer-min-length": LengthRuleConfig<V>;
  
  // Header rules
  "header-case": CaseRuleConfig<V>;
  "header-full-stop": RuleConfig<V, string>;
  "header-max-length": LengthRuleConfig<V>;
  "header-min-length": LengthRuleConfig<V>;
  "header-trim": RuleConfig<V>;
  
  // Scope rules
  "scope-case": CaseRuleConfig<V>;
  "scope-empty": RuleConfig<V>;
  "scope-enum": EnumRuleConfig<V>;
  "scope-max-length": LengthRuleConfig<V>;
  "scope-min-length": LengthRuleConfig<V>;
  
  // Subject rules
  "subject-case": CaseRuleConfig<V>;
  "subject-empty": RuleConfig<V>;
  "subject-full-stop": RuleConfig<V, string>;
  "subject-max-length": LengthRuleConfig<V>;
  "subject-min-length": LengthRuleConfig<V>;
  
  // Type rules
  "type-case": CaseRuleConfig<V>;
  "type-empty": RuleConfig<V>;
  "type-enum": EnumRuleConfig<V>;
  "type-max-length": LengthRuleConfig<V>;
  "type-min-length": LengthRuleConfig<V>;
  
  // Other rules
  "references-empty": RuleConfig<V>;
  "signed-off-by": RuleConfig<V, string>;
  "trailer-exists": RuleConfig<V, string>;
  
  // Custom plugin rules
  [key: string]: AnyRuleConfig<V>;
};

type TargetCaseType =
  | "camel-case"
  | "kebab-case" 
  | "snake-case"
  | "pascal-case"
  | "start-case"
  | "upper-case"
  | "uppercase"
  | "sentence-case"
  | "sentencecase"
  | "lower-case"
  | "lowercase"
  | "lowerCase";

type AnyRuleConfig<V> = RuleConfig<V, unknown> | RuleConfig<V, void>;

type DeepPartial<T> = {
  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
};

Prompt Configuration

Interactive prompt configuration for commitlint CLI.

type UserPromptConfig = DeepPartial<PromptConfig>;

interface PromptConfig {
  settings: {
    scopeEnumSeparator: string;
    enableMultipleScopes: boolean;
  };
  messages: PromptMessages;
  questions: Partial<Record<PromptName, {
    description?: string;
    messages?: { [K: string]: string };
    enum?: {
      [enumName: string]: {
        description?: string;
        title?: string;
        emoji?: string;
      };
    };
  }>>;
}

interface PromptMessages {
  skip: string;
  max: string;
  min: string;
  emptyWarning: string;
  upperLimitWarning: string;
  lowerLimitWarning: string;
  [_key: string]: string;
}

type PromptName =
  | "header"
  | "type"
  | "scope"
  | "subject"
  | "body"
  | "footer"
  | "isBreaking"
  | "breakingBody"
  | "breaking"
  | "isIssueAffected"
  | "issuesBody"
  | "issues";

Configuration Discovery

The package automatically discovers configuration files in the following order:

  1. package.json (commitlint key)
  2. .commitlintrc (JSON)
  3. .commitlintrc.json
  4. .commitlintrc.yaml / .commitlintrc.yml
  5. .commitlintrc.js / .commitlintrc.cjs / .commitlintrc.mjs
  6. commitlint.config.js / commitlint.config.cjs / commitlint.config.mjs
  7. .commitlintrc.ts / .commitlintrc.cts
  8. commitlint.config.ts / commitlint.config.cts

Usage Examples

Basic Configuration Loading

import load from "@commitlint/load";

// Load configuration from current directory
const config = await load();
console.log("Loaded rules:", Object.keys(config.rules));
console.log("Extended configs:", config.extends);

Custom Configuration Override

import load from "@commitlint/load";

// Override specific rules
const config = await load({
  rules: {
    "type-enum": [2, "always", ["feat", "fix", "docs", "chore"]],
    "subject-max-length": [2, "always", 72]
  }
});

Working with Different Directories

import load from "@commitlint/load";

// Load from specific directory and file
const config = await load({}, {
  cwd: "/path/to/project",
  file: "custom-commitlint.config.js"
});

Using Resolution Utilities

import { resolveFrom, resolveFromSilent } from "@commitlint/load";

// Resolve a formatter module
try {
  const formatterPath = resolveFrom("@commitlint/format", process.cwd());
  console.log("Formatter found at:", formatterPath);
} catch {
  console.log("Formatter not found");
}

// Silent resolution (no errors)
const pluginPath = resolveFromSilent("commitlint-plugin-custom", "/project/path");
if (pluginPath) {
  console.log("Plugin found at:", pluginPath);
}

docs

index.md

tile.json