commitlint.config.mjs

/**
 * Conventional Commits enforcement (git-workflow-standards §3.2, §4.2).
 *
 * Why this file is `.mjs` and not `.js`: package.json declares `"type": "commonjs"`, and Node 24 changed module
 * loading such that commitlint fails to read a CommonJS-named config in that setup ("Please add rules to your
 * commitlint.config.js"). The explicit `.mjs` extension sidesteps it without flipping the whole package to ESM,
 * which would break the vitest/jsdom frontend suite that currently relies on CommonJS `require` in its helpers.
 *
 * Why it is enforced in CI rather than trusted: the release tooling derives the CHANGELOG and the version bump
 * from these messages, and it *silently skips* commits it cannot parse. An unlinted message is therefore not a
 * style problem — it is a change that quietly never appears in a release note. The lint is part of the release
 * system, not cosmetics.
 *
 * Deliberately kept at the stock `config-conventional` ruleset: this repo has no bespoke commit vocabulary, and
 * a custom rule set is one more thing to maintain and to explain to a first-time contributor.
 */
export default {
  extends: ['@commitlint/config-conventional'],
  rules: {
    // The subject line is what lands in `main` on a squash merge and what a future `git log --oneline` reader
    // sees; 72 keeps it readable in a terminal and in the GitHub/GitLab commit list without truncation.
    'header-max-length': [2, 'always', 72],
    // Scope is optional here on purpose. This is a single-artifact plugin, not a monorepo: mandating a scope
    // would produce noise like `chore(repo):` rather than information.
    'body-max-line-length': [2, 'always', 100],
  },
  ignores: [
    // Merge commits are generated by the forge/GitFlow merges and are not authored messages. `--no-ff` release
    // merges are the repo's integration mechanism (see docs/adr/0001), so linting them would fail every release.
    (message) => message.startsWith('Merge '),
    // `git revert` generates its own subject from the reverted commit; rewriting it by hand loses the SHA
    // reference that makes the revert traceable.
    (message) => message.startsWith('Revert "'),
  ],
};