or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

case-validation.mdconfiguration.mdformatting.mdindex.mdlinting.mdparsing.mdplugins.mdprompts.mdrules-config.md
tile.json

configuration.mddocs/

Configuration Loading

The configuration system provides types for loading, processing, and validating commitlint configuration files. This includes support for extending configurations, loading presets, and integrating plugins.

User Configuration

User Config Interface

interface UserConfig {
  extends?: string | string[];
  formatter?: string;
  rules?: Partial<RulesConfig>;
  parserPreset?: string | ParserPreset | Promise<ParserPreset>;
  ignores?: ((commit: string) => boolean)[];
  defaultIgnores?: boolean;
  plugins?: (string | Plugin)[];
  helpUrl?: string;
  prompt?: UserPromptConfig;
  [key: string]: unknown;
}

User-provided configuration that can be loaded from .commitlintrc, package.json, or configuration files:

  • extends: Base configurations to extend (single string or array)
  • formatter: Custom formatter module name or path
  • rules: Rule overrides and custom rules
  • parserPreset: Parser configuration (string name, object, or promise)
  • ignores: Custom ignore functions
  • defaultIgnores: Whether to use default ignore patterns
  • plugins: Plugin modules to load (string names or objects)
  • helpUrl: URL for additional help documentation
  • prompt: Interactive prompt configuration
  • [key: string]: Extensible for plugin-specific configuration

Load Options

interface LoadOptions {
  cwd?: string;
  file?: string;
}

Options for loading configuration:

  • cwd: Current working directory for resolving configuration files
  • file: Specific configuration file to load

Qualified Configuration

Qualified Config Interface

interface QualifiedConfig {
  extends: string[];
  formatter: string;
  rules: QualifiedRules;
  parserPreset?: ParserPreset;
  ignores?: ((commit: string) => boolean)[];
  defaultIgnores?: boolean;
  plugins: PluginRecords;
  helpUrl: string;
  prompt: UserPromptConfig;
}

Fully processed and resolved configuration after loading and extending:

  • All optional fields have default values
  • Plugin strings are resolved to Plugin objects
  • Rule configurations are qualified
  • Extends array is flattened and resolved

Qualified Rules

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

Rules configuration where all rule values are resolved to their final tuple form (no functions or promises).

Parser Presets

Parser Preset Interface

interface ParserPreset {
  name?: string;
  path?: string;
  parserOpts?: unknown;
}

Configuration for conventional-commits-parser integration:

  • name: Name of the preset (e.g., "conventional-changelog-angular")
  • path: File path to custom parser preset
  • parserOpts: Parser-specific options (typed as unknown for flexibility)

Plugin System

Plugin Interface

interface Plugin {
  rules: {
    [ruleName: string]: Rule | AsyncRule | SyncRule;
  };
}

Plugin structure containing custom rules:

  • rules: Record mapping rule names to rule implementation functions

Plugin Records

type PluginRecords = Record<string, Plugin>;

Registry of loaded plugins mapped by plugin name.

Usage Examples

Basic Configuration

import { UserConfig } from "@commitlint/types";

const config: UserConfig = {
  extends: ["@commitlint/config-conventional"],
  rules: {
    "type-enum": [2, "always", ["feat", "fix", "docs", "style", "refactor"]],
    "subject-max-length": [1, "always", 50]
  },
  helpUrl: "https://commitlint.js.org/"
};

Advanced Configuration with Plugins

import { UserConfig, Plugin } from "@commitlint/types";

// Custom plugin
const customPlugin: Plugin = {
  rules: {
    "custom-rule": (parsed, when, value) => {
      // Rule implementation
      return [true];
    }
  }
};

const config: UserConfig = {
  extends: ["@commitlint/config-conventional"],
  plugins: [
    "@commitlint/plugin-custom",
    customPlugin
  ],
  rules: {
    "custom-rule": [2, "always", { someOption: true }]
  },
  ignores: [
    (commit) => commit.includes("[skip ci]"),
    (commit) => commit.startsWith("WIP:")
  ],
  defaultIgnores: false
};

Parser Preset Configuration

import { UserConfig, ParserPreset } from "@commitlint/types";

// String preset
const simpleConfig: UserConfig = {
  parserPreset: "conventional-changelog-angular"
};

// Object preset
const objectPreset: ParserPreset = {
  name: "custom-preset",
  parserOpts: {
    headerPattern: /^(\w*)(?:\(([\w$.\-* ]*)\))?: (.*)$/,
    headerCorrespondence: ["type", "scope", "subject"],
    noteKeywords: ["BREAKING CHANGE", "BREAKING CHANGES"]
  }
};

const advancedConfig: UserConfig = {
  parserPreset: objectPreset
};

// Promise preset (for async loading)
const promiseConfig: UserConfig = {
  parserPreset: import("./custom-preset").then(m => m.preset)
};

Configuration Loading

import { LoadOptions, QualifiedConfig } from "@commitlint/types";

// Load options
const loadOptions: LoadOptions = {
  cwd: process.cwd(),
  file: ".commitlintrc.json"
};

// Processing qualified config
function processQualifiedConfig(config: QualifiedConfig): void {
  console.log(`Using formatter: ${config.formatter}`);
  console.log(`Extended from: ${config.extends.join(", ")}`);
  console.log(`Help URL: ${config.helpUrl}`);
  
  // Process rules
  Object.entries(config.rules).forEach(([ruleName, ruleConfig]) => {
    console.log(`Rule ${ruleName}:`, ruleConfig);
  });
  
  // Process plugins
  Object.keys(config.plugins).forEach(pluginName => {
    console.log(`Plugin loaded: ${pluginName}`);
  });
}

Extending Configurations

import { UserConfig } from "@commitlint/types";

// Single extend
const singleExtend: UserConfig = {
  extends: "@commitlint/config-conventional"
};

// Multiple extends (processed in order)
const multipleExtends: UserConfig = {
  extends: [
    "@commitlint/config-conventional",
    "@commitlint/config-lerna-scopes",
    "./custom-rules"
  ]
};

// Override extended rules
const withOverrides: UserConfig = {
  extends: "@commitlint/config-conventional",
  rules: {
    // Override the conventional config's type-enum rule
    "type-enum": [2, "always", ["feat", "fix", "docs", "custom"]],
    // Add new rule not in conventional config
    "custom-rule": [1, "always"]
  }
};

Configuration Validation

import { UserConfig, QualifiedConfig } from "@commitlint/types";

function validateUserConfig(config: UserConfig): string[] {
  const errors: string[] = [];
  
  // Validate extends
  if (config.extends) {
    const extends_ = Array.isArray(config.extends) ? config.extends : [config.extends];
    extends_.forEach(extend => {
      if (typeof extend !== "string") {
        errors.push(`Invalid extends value: ${extend}`);
      }
    });
  }
  
  // Validate formatter
  if (config.formatter && typeof config.formatter !== "string") {
    errors.push("Formatter must be a string");
  }
  
  // Validate ignores
  if (config.ignores) {
    config.ignores.forEach((ignore, index) => {
      if (typeof ignore !== "function") {
        errors.push(`Ignore at index ${index} must be a function`);
      }
    });
  }
  
  return errors;
}