commitlint.config.mjs

// SPDX-FileCopyrightText: 2026 Anton Wiklund and Solid Memo contributors
//
// SPDX-License-Identifier: MIT

/**
 * commitlint's rules for commit messages (CONTRIBUTING.md#commit-messages):
 * Conventional Commits 1.0.0, as @commitlint/config-conventional checks
 * them, which semantic-release reads to choose each version
 * (docs/releasing.md). CI's commits job lints a pull request's commits,
 * and `npm run lint:commits` a branch's, since it left main.
 *
 * The defaults stand, the length of the body's and footer's lines aside:
 * a body is wrapped near 72 columns by hand (docs/style.md#commits), but
 * a URL, a command or Renovate's list of updates (commitBody in
 * renovate.json5), one update a line with its release notes' address,
 * runs as long as it needs. The subject's first word is lowercase
 * ("add", "keep"), the default; a name may follow it in its own case.
 *
 * A breaking change says so twice (docs/releasing.md#what-counts-as-breaking):
 * `!` after its type or scope, and a `BREAKING CHANGE:` footer that
 * tells users what to do. Either one without the other is refused. A
 * commit commitlint skips, such as a revert, may not say it at all, which
 * `npm run check:merges` refuses (scripts/checkMergeMessages.ts).
 *
 * Every commit records its decision and links its discussion (criterion
 * 6 of the Standard for Public Code, docs/standard-for-public-code.md):
 * it has a body that says why, and names an issue, a pull request or a
 * discussion by its number anywhere in the message (`Closes: #72`,
 * `Fixes #69`, `Refs: #68`). A Renovate update cannot name its pull
 * request, which has no number when the commit is written; its body
 * ends with the line that RENOVATE_WHY starts (commitBody in renovate.json5)
 * instead, and its merge commit names the pull request. Every other rule
 * still holds for it, so the release reads its header.
 *
 * A security fix is made in private (SECURITY.md) before any public
 * issue may describe what it fixes, so it names its GitHub security
 * advisory instead (`Refs: GHSA-xxxx-xxxx-xxxx`), which is published
 * once the fix is deployed.
 *
 * No commit holds one of the keywords that make GitHub skip a push's
 * workflows (`[skip ci]`, `[ci skip]`, `[no ci]`, `[skip actions]`,
 * `[actions skip]`, or a `skip-checks:` trailer), in upper or lower
 * case, anywhere in its message: CI must run on every push to main, and
 * the deploy runs only after it. A commit commitlint otherwise skips,
 * such as a revert, is checked for them too.
 *
 * No commit holds what would change how CHANGELOG.md is linted: an HTML
 * comment's `<!--`, `-->` or `--!>`, or a spell checker's directive, in
 * upper or lower case, anywhere in its message. The release copies a
 * commit's subject and its `BREAKING CHANGE:` footer into that file, whose
 * generated entries are exempt from the linters only through directives
 * in the file itself, so a directive in an entry would turn a linter back
 * on and fail CI on the release commit, after the tag and with no deploy.
 * `npm run check:merges` reads every commit's whole message for them too,
 * as commitlint skips some commits and can read only part of a message.
 *
 * A `chore(release)` header is semantic-release's alone, on the release
 * commit it pushes onto main (docs/releasing.md#what-a-release-does), so
 * a commit of a pull request or a branch may not have it. commitlint
 * would skip a header such as `chore(release): 1.2.3` unlinted, as one of
 * its default ignores takes a version for a release's, so its other
 * defaults are kept but that one.
 */

/** The start of the line commitBody in renovate.json5 ends each Renovate commit with. */
export const RENOVATE_WHY = "Why: renovate.json5 keeps every dependency current";

/**
 * A GitHub security advisory's id: `GHSA-` and three groups of four
 * characters from the alphabet GitHub draws them from.
 */
export const ADVISORY = /\bGHSA(?:-[23456789cfghjmpqrvwx]{4}){3}\b/;

/**
 * The parser reads Renovate's `Why:` line as a footer, and knows no
 * advisory id, so the whole message is searched.
 *
 * @param {{ references: unknown[], raw: string }} commit
 */
function referencesOrRenovate({ references, raw }) {
  const renovate = raw.split("\n").some((line) => line.startsWith(RENOVATE_WHY));
  return [
    references.length > 0 || renovate || ADVISORY.test(raw),
    "the message must name its issue, pull request or discussion, such as `Closes: #42`, or a security fix its advisory, such as `Refs: GHSA-xxxx-xxxx-xxxx` (CONTRIBUTING.md#commit-messages)",
  ];
}

/**
 * GitHub's keywords that skip the workflows of a push whose head commit's
 * message holds one, anywhere in it and in upper or lower case, as
 * GitHub's docs on skipping workflow runs list them.
 */
export const SKIP_KEYWORD =
  /\[\s*(?:skip\s+ci|ci\s+skip|no\s+ci|skip\s+actions|actions\s+skip)\s*\]|^\s*skip-checks\s*:/im;

/**
 * @param {{ raw: string }} commit
 */
function noSkipKeyword({ raw }) {
  return [
    !SKIP_KEYWORD.test(raw),
    "the message must not hold a keyword that makes GitHub skip CI, such as `[skip ci]` or a `skip-checks:` trailer: CI and the deploy must run on main (CONTRIBUTING.md#commit-messages)",
  ];
}

/**
 * What a linter of CHANGELOG.md would read as a directive, as
 * markdownlint and the spell checker write them: an HTML comment, or
 * the spell checker's own marker, which it reads outside a comment too.
 * A comment ends at `--!>` as well as `-->`, as browsers read it.
 * The marker starts at a word boundary, except that the end of the
 * `cspell:disable` region the file opens is read straight after a word.
 */
export const CHANGELOG_DIRECTIVE = /<!--|--!?>|\b(?:spell-?checker|c?spell)::?|cspell:\s*enable\b/i;

/**
 * @param {{ raw: string }} commit
 */
function noChangelogDirective({ raw }) {
  return [
    !CHANGELOG_DIRECTIVE.test(raw),
    "the message must not hold an HTML comment's `<!--`, `-->` or `--!>`, or a spell checker's directive: the release copies it into CHANGELOG.md, whose linters would read it (CONTRIBUTING.md#commit-messages)",
  ];
}

/**
 * The header semantic-release titles its release commit with
 * (release.config.mjs), in upper or lower case and with or without a `!`.
 *
 * @param {{ header: string | null }} commit
 */
function notARelease({ header }) {
  return [
    !/^chore\(release\)/i.test(header ?? ""),
    "the header `chore(release)` is semantic-release's, for the release commit it makes on main: use another type or scope (CONTRIBUTING.md#commit-messages)",
  ];
}

/**
 * commitlint's default ignores (@commitlint/is-ignored), but a header
 * that is a version: merges, which CI and `npm run lint:commits` refuse
 * on their own, reverts, reapplies, and fixups. They are matched against
 * the header alone, so a line of the body cannot make a commit skip
 * every rule. A message with a skip keyword is never skipped, so that
 * the rule against them holds for every commit.
 */
const IGNORED = [
  /^((Merge pull request)|(Merge (.*?) into (.*?)|(Merge branch (.*?)))$)/,
  /^(Merge tag (.*?))$/,
  /^(R|r)evert (.*)/,
  /^(R|r)eapply (.*)/,
  /^(amend|fixup|squash)!/,
  /^(Merged (.*?)(in|into) (.*)|Merged PR (.*): (.*))/,
  /^Merge remote-tracking branch(\s*)(.*)/,
  /^Automatic merge(.*)/,
  /^Auto-merged (.*?) into (.*)/,
];

/**
 * Whether commitlint skips a message, every rule above with it.
 *
 * @param {string} message
 */
export function skippedByCommitlint(message) {
  const header = message.split(/\r?\n/, 1)[0];
  return !SKIP_KEYWORD.test(message) && IGNORED.some((pattern) => pattern.test(header));
}

export default {
  defaultIgnores: false,
  ignores: [skippedByCommitlint],
  extends: ["@commitlint/config-conventional"],
  plugins: [
    {
      rules: {
        "references-or-renovate": referencesOrRenovate,
        "not-a-release": notARelease,
        "no-skip-keyword": noSkipKeyword,
        "no-changelog-directive": noChangelogDirective,
      },
    },
  ],
  rules: {
    "body-max-line-length": [0],
    "footer-max-line-length": [0],
    "breaking-change-exclamation-mark": [2, "always"],
    "body-empty": [2, "never"],
    "references-or-renovate": [2, "always"],
    "not-a-release": [2, "always"],
    "no-skip-keyword": [2, "always"],
    "no-changelog-directive": [2, "always"],
  },
};