From 7fdfccdbf0c8d81905c6ca8e8694fab0b2c1fc3e Mon Sep 17 00:00:00 2001 From: Anton Wiklund Date: Sun, 15 Nov 2026 23:48:33 +0100 Subject: [PATCH] fix(ci): keep links out of the changelog's entries The release copies each commit's header and a breaking change's footer into CHANGELOG.md as Markdown, and CI's docs job checks every local link of every Markdown file on each pull request and merge queue run. The commit checks refused HTML comments and spell checker directives there, but not links. A link in a header whose target did not resolve passed every check, since CHANGELOG.md is written only at release time, and after the release the docs job failed on CHANGELOG.md for every later change until the file was edited by hand. commitlint and check:merges now refuse, in a header or a breaking change's footer, a Markdown link or image in its inline and reference-style forms, a reference's definition wherever it stands, a file: address and an HTML tag with any attribute, as the link check reads more attributes than href and src. The header is found as the commit parser that commitlint and the release share finds it, past leading blank lines and gpg: lines, so the check reads the header the release writes. A tag's name is read as HTML reads it, up to a space, a slash or a closing angle bracket, and the tag check reads each character once. The body may still link, as the release leaves it out. The docs job leaves CHANGELOG.md out of its offline link check, so an entry already released cannot block merges; the weekly link run still checks it. Tests cover each form, a header after blank and gpg: lines, tag names that HTML reads but Markdown does not, a long message of tags that never close, and ordinary brackets, parentheses and angle brackets, and CONTRIBUTING.md, releasing.md and testing.md say so. Refs: GHSA-85mm-6qq5-qxrc --- .github/workflows/ci.yml | 5 +- CONTRIBUTING.md | 10 ++- commitlint.config.mjs | 82 ++++++++++++++++++++++ docs/releasing.md | 10 +++ docs/testing.md | 5 +- lychee.toml | 3 +- scripts/checkMergeMessages.test.ts | 50 ++++++++++++++ scripts/checkMergeMessages.ts | 21 +++--- scripts/commitlintConfig.test.ts | 106 ++++++++++++++++++++++++++++- 9 files changed, 277 insertions(+), 15 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a212e04f8..65a7da07f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1206,9 +1206,12 @@ jobs: # files are there to check. - run: pip install --require-hashes -r scripts/requirements-lint.txt - run: npm run lint:reuse + # CHANGELOG.md is left out: the release writes it on main, after the + # change that wrote an entry passed, so a link there that failed + # would fail every later change instead. links.yml checks it weekly. - uses: lycheeverse/lychee-action@e7477775783ea5526144ba13e8db5eec57747ce8 # v2.9.0 with: - args: --offline '**/*.md' + args: --offline --exclude-path '^CHANGELOG\.md$' '**/*.md' output: ${{ runner.temp }}/lychee.md jobSummary: false - uses: ./.github/actions/publiccode diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f1c6fe30f..de60bd1e0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -137,14 +137,20 @@ they refuse a message that holds one of GitHub's keywords that skip CI case: CI runs on every push to `main`, and the deploy only after it. They refuse an HTML comment's `` or `--!>` and a spell checker's directive anywhere in a message too: the release copies the message -into `CHANGELOG.md`, whose linters would read them. +into `CHANGELOG.md`, whose linters would read them. And they refuse a +Markdown link, image or reference definition, such as +`[text](docs/page.md)` or `[text]: docs/page.md`, or an HTML tag with an +attribute, in a header or a breaking change's footer, the parts the +release copies, and inside a code span there too: name the page in +plain text there, and link it in the body. The merge queue refuses those keywords, comment markers and directives in a pull request's title too, and a title that starts as a breaking change's footer, as the merge commit holds the title ([docs/releasing.md](docs/releasing.md#what-a-merge-commit-decides)). A commit commitlint skips, such as a revert, may not say it breaks. `npm run check:merges` reads every commit's whole message for a comment -marker or a directive, as commitlint can miss part of one. +marker or a directive, as commitlint can miss part of one, and every +commit's header and breaking change's footer for a link. `npm run lint:commits` lints the commits since `origin/main`, so from a fork, sync the fork's `main` with this repository's first, or run `npx commitlint --from upstream/main --to HEAD`, with `upstream` the diff --git a/commitlint.config.mjs b/commitlint.config.mjs index b8ee8122c..81bc167a0 100644 --- a/commitlint.config.mjs +++ b/commitlint.config.mjs @@ -123,6 +123,86 @@ function noChangelogDirective({ raw }) { ]; } +/** + * What the release copies from a message into CHANGELOG.md: the header, + * and a breaking change's footer, from the first line that starts one + * (as release.config.mjs's notesPattern finds it) to the end. The header + * is found as conventional-commits-parser finds it, which both commitlint + * and the release use: it drops every line that starts with `gpg:`, as + * git writes a signature's check, and the blank lines before the first + * other one. A line of spaces counts as blank here, so the check reads + * one line too many, never one too few. + * + * @param {string} message + */ +function changelogTextOf(message) { + const lines = message.split(/\r?\n/).filter((line) => !/^\s*gpg:/.test(line)); + const header = lines.findIndex((line) => line.trim() !== ""); + const footer = lines.findIndex((line) => /^BREAKING[ -]CHANGE:/.test(line)); + return [lines[header] ?? "", ...(footer === -1 ? [] : lines.slice(footer))].join("\n"); +} + +/** + * What CHANGELOG.md would render as a link or an image, whose target CI's + * link check reads: an inline or reference-style link or image + * (`[text](target)`, `![alt](target)`, `[text][ref]`), a reference's + * definition (`[ref]: target`) or a `file:` address. A definition is + * refused wherever it stands, not only at the start of a line: the + * release puts each entry in a list item, so one may follow a list + * marker, a quote's `>` or any indentation, and it then makes a shortcut + * `[ref]` anywhere in the file a link. + */ +const MARKDOWN_LINK = /\][([:]|`. The tag is found by the space after its name and any later + * `>`, so a quoted `>` in an earlier attribute cannot hide a later one, + * while a `<` that never closes, as in `a"); + let at = 0; + while (at < end) { + const open = text.indexOf("<", at); + if (open === -1 || open >= end) return false; + at = open + 1; + if (!/[a-z]/i.test(text[at])) continue; + // Both runs stop at the last `>` at the latest. + while (!/[\s/>]/.test(text[at])) at++; + const name = at; + while (/[\s/]/.test(text[at])) at++; + if (at > name && text[at] !== ">") return true; + } + return false; +} + +/** + * Whether the text the release copies from a message into CHANGELOG.md + * holds a link or an image. + * + * @param {string} message + */ +export function holdsChangelogLink(message) { + const text = changelogTextOf(message); + return MARKDOWN_LINK.test(text) || holdsTagWithAttribute(text); +} + +/** + * @param {{ raw: string }} commit + */ +function noChangelogLink({ raw }) { + return [ + !holdsChangelogLink(raw), + "the header and a breaking change's footer must not hold a Markdown link, image or reference definition, such as `[text](docs/page.md)` or `[text]: docs/page.md`, or an HTML tag with an attribute: the release copies them into CHANGELOG.md, whose link check would read it; name the page in plain text instead (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 `!`. @@ -177,6 +257,7 @@ export default { "not-a-release": notARelease, "no-skip-keyword": noSkipKeyword, "no-changelog-directive": noChangelogDirective, + "no-changelog-link": noChangelogLink, }, }, ], @@ -189,5 +270,6 @@ export default { "not-a-release": [2, "always"], "no-skip-keyword": [2, "always"], "no-changelog-directive": [2, "always"], + "no-changelog-link": [2, "always"], }, }; diff --git a/docs/releasing.md b/docs/releasing.md index 651ad7631..04cf7c360 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -233,6 +233,16 @@ a number counts as an issue ([release.config.mjs](../release.config.mjs)'s The site's footer links to the changelog on `main` ([Footer.tsx](../packages/ui/src/ui/Footer.tsx)). +The notes keep a commit's header and a breaking change's footer as +Markdown, so a link or an image there stays one in `CHANGELOG.md`. +commitlint and `npm run check:merges` refuse there +`[text](target)`, `![alt](target)`, `[text][ref]`, a reference's +definition `[ref]:` wherever it stands, a `file:` address, and an HTML +tag with any attribute, its name read as HTML reads it. The body may +link, as the notes leave it out. CI's `docs` job leaves `CHANGELOG.md` +out of its link check too ([testing.md](testing.md#documentation)), so +an entry already released can't fail every later pull request. + A subject says, in plain words, what changed for users, other apps or people who run their own copy. Nobody edits an entry by hand: a mistake stays, and the next version's entry can correct it. The header is diff --git a/docs/testing.md b/docs/testing.md index a6612ee9b..77992ddd2 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -1314,7 +1314,10 @@ the pages in `docs/`, and CI's `docs` job the rest: ([lychee.toml](../lychee.toml)). The [Links workflow](../.github/workflows/links.yml) checks the web's addresses weekly and by hand, apart from any change. A broken one is - fixed, or excluded in `lychee.toml` with a reason. + fixed, or excluded in `lychee.toml` with a reason. `CHANGELOG.md` is + checked only there: the release writes it on `main`, so a link of a + released entry that failed would fail every change after it + ([releasing.md](releasing.md#the-changelog)). - **publiccode.yml**: once the repository has one, the [publiccode.yml parser](https://github.com/italia/publiccode-parser-go) validates it against the standard, and the files it names. The Links diff --git a/lychee.toml b/lychee.toml index 5dc40f31f..caab04bb2 100644 --- a/lychee.toml +++ b/lychee.toml @@ -5,7 +5,8 @@ # lychee's settings for the links in the project's Markdown # (docs/testing.md#documentation): CI checks the files and anchors they # point at on every change (--offline), and every web address weekly -# (.github/workflows/links.yml). +# (.github/workflows/links.yml). The weekly run checks CHANGELOG.md too, +# which the run on every change leaves out (.github/workflows/ci.yml). # A link to a heading must find it. include_fragments = "full" diff --git a/scripts/checkMergeMessages.test.ts b/scripts/checkMergeMessages.test.ts index efc758762..077b32f6c 100644 --- a/scripts/checkMergeMessages.test.ts +++ b/scripts/checkMergeMessages.test.ts @@ -125,6 +125,56 @@ describe("problemsOf", () => { expect(problemsOf("fix: the misspell: rule, a -> b\n\nRefs: #1", false)).toEqual([]); }); + // The release writes a commit's header and a breaking change's footer + // into CHANGELOG.md as Markdown, and the docs job checks its links. + const link = "holds a link or an image in its header or a breaking change's footer"; + + it.each([ + "fix(studio): keep the order, as [the Studio page](docs/no-such-page.md) says", + "fix(studio): keep the order, as [the Studio page](docs/studio.md#no-such-heading) says", + "fix: show ![a picture](docs/no-such-image.png)", + "fix: keep the order, as [the Studio page][studio] says", + "fix: keep the order, as says", + 'fix: show ', + 'fix: keep the order, as the page says', + "fix: keep [x]: docs/x.md", + ])("refuses a link or an image in a header: %s", (header) => { + expect(problemsOf(`${header}\n\nRefs: #1`, false)).toEqual([link]); + expect(problemsOf(`Revert "${header}"`, false)).toEqual([link]); + }); + + it("refuses a link in the header the parser finds after gpg: or blank lines", () => { + for (const before of ["gpg: Signature made today\n", "\n"]) { + expect( + problemsOf( + `${before}fix(studio): keep [the page](docs/no-such.md) in order\n\nRefs: #1`, + false, + ), + ).toEqual([link]); + } + }); + + it("refuses a link in a breaking change's footer, on any of its lines", () => { + expect( + problemsOf("fix!: tidy\n\nKeep it.\n\nBREAKING CHANGE: see [the page](docs/x.md)", false), + ).toEqual([link]); + expect( + problemsOf( + "fix!: tidy\n\nKeep it.\n\nBREAKING CHANGE: see [the page]\n[the page]: docs/x.md", + false, + ), + ).toEqual([link]); + expect( + problemsOf("fix!: tidy\n\nKeep it.\n\nBREAKING CHANGE: see [r]\n\n [r]: docs/x.md", false), + ).toEqual([link]); + }); + + it("passes a link in the body, and brackets and parentheses that are no link", () => { + expect(problemsOf("fix: tidy\n\nSee [the page](docs/x.md).\n\nRefs: #1", false)).toEqual([]); + expect(problemsOf("fix: keep [front] and (back), arr[0] (x)\n\nRefs: #1", false)).toEqual([]); + expect(problemsOf(merge("fix: keep [front] (docs/x.md)"), true)).toEqual([]); + }); + it("says both when both are there", () => { expect(problemsOf(merge("BREAKING CHANGE: tidy [skip ci]"), true)).toHaveLength(2); }); diff --git a/scripts/checkMergeMessages.ts b/scripts/checkMergeMessages.ts index 8a52f7710..4c163fbda 100644 --- a/scripts/checkMergeMessages.ts +++ b/scripts/checkMergeMessages.ts @@ -27,7 +27,10 @@ * commit's subject and footer there, so an HTML comment or a spell * checker's directive would fail CI on the release commit. The check * reads every commit's whole message for that, the ones commitlint reads - * included, as commitlint can read only part of a message. + * included, as commitlint can read only part of a message. Nor may the + * header or a breaking change's footer, the text the release copies there, + * hold a link or an image (holdsChangelogLink, from the same file), whose + * target the link check would read. * * With `--queue` the range must hold a merge commit, as each run of the * queue builds one. The release leaves out merge commits by their @@ -43,13 +46,13 @@ import { resolve } from "node:path"; import { parseArgs } from "node:util"; import { saysBreaking } from "./checkBreaking.ts"; -const { CHANGELOG_DIRECTIVE, SKIP_KEYWORD, skippedByCommitlint } = (await import( - new URL("../commitlint.config.mjs", import.meta.url).href -)) as { - CHANGELOG_DIRECTIVE: RegExp; - SKIP_KEYWORD: RegExp; - skippedByCommitlint(message: string): boolean; -}; +const { CHANGELOG_DIRECTIVE, SKIP_KEYWORD, holdsChangelogLink, skippedByCommitlint } = + (await import(new URL("../commitlint.config.mjs", import.meta.url).href)) as { + CHANGELOG_DIRECTIVE: RegExp; + SKIP_KEYWORD: RegExp; + holdsChangelogLink(message: string): boolean; + skippedByCommitlint(message: string): boolean; + }; /** What is wrong with a merge commit's message, if anything. */ function problemsOfMerge(message: string): string[] { @@ -72,6 +75,8 @@ export function problemsOf(message: string, merge: boolean): string[] { const problems = merge ? problemsOfMerge(message) : problemsOfCommit(message); if (CHANGELOG_DIRECTIVE.test(message)) problems.push("holds an HTML comment or a spell checker's directive"); + if (holdsChangelogLink(message)) + problems.push("holds a link or an image in its header or a breaking change's footer"); return problems; } diff --git a/scripts/commitlintConfig.test.ts b/scripts/commitlintConfig.test.ts index bee82bf9c..dbc64a430 100644 --- a/scripts/commitlintConfig.test.ts +++ b/scripts/commitlintConfig.test.ts @@ -17,9 +17,9 @@ import { describe, expect, it } from "vitest"; const ROOT = join(import.meta.dirname, ".."); -const { RENOVATE_WHY } = (await import( +const { RENOVATE_WHY, holdsChangelogLink } = (await import( new URL("../commitlint.config.mjs", import.meta.url).href -)) as { RENOVATE_WHY: string }; +)) as { RENOVATE_WHY: string; holdsChangelogLink(message: string): boolean }; const config = await load({}, { cwd: ROOT }); async function errors(message: string): Promise { @@ -208,6 +208,108 @@ Refs: #1`), } }); + // CHANGELOG.md renders the header and a breaking change's footer as + // Markdown, and CI's link check reads every link and image there. + const links = [ + "as [the Studio page](docs/no-such-page.md) says", + "as [the Studio page](docs/studio.md#no-such-heading) says", + "with ![a picture](docs/no-such-image.png)", + "as [the Studio page][studio] says", + "as [the Studio page][] says", + "as says", + "as file:///docs/studio.md says", + 'as the Studio page says', + "as shows", + 'with ', + 'as
it
says', + 'with ', + 'with ', + 'with
', + 'as the Studio page says', + "as shows", + "with [studio]: docs/studio.md", + ]; + + it("fails a link or an image in the header", async () => { + for (const link of links) { + expect(await errors(`fix(studio): keep the order, ${link}\n\n${why}\n\nCloses: #1`)).toEqual([ + "no-changelog-link", + ]); + } + }); + + // The parser that commitlint and the release share drops `gpg:` lines + // and leading blank lines before it reads the header. + it("fails a link in the header the parser finds after gpg: or blank lines", async () => { + for (const before of ["gpg: Signature made today\n", "\n", "\n\n", "\n gpg: x\ngpg: y\n"]) { + expect( + await errors( + `${before}fix(studio): keep [the Studio page](docs/no-such-page.md) in order\n\n${why}\n\nCloses: #1`, + ), + ).toEqual(["no-changelog-link"]); + } + expect(holdsChangelogLink("gpg: [the page](docs/x.md)\n\n")).toBe(false); + }); + + it("fails a link or an image in a breaking change's footer, on any of its lines", async () => { + for (const footer of [ + ...links.map((link) => `BREAKING CHANGE: keep the order, ${link}`), + "BREAKING-CHANGE: keep the order, as [the Studio page] says\n[the Studio page]: docs/studio.md", + "BREAKING CHANGE: keep the order, as [studio] says\n\n [studio]: docs/studio.md", + "BREAKING CHANGE: keep the order, as [studio] says\n\t[studio]: docs/studio.md", + "BREAKING CHANGE: keep the order, as [studio] says\n> - [studio]: docs/studio.md", + "BREAKING CHANGE: keep the order, as [studio] says\n1. [studio\n]: docs/studio.md", + 'BREAKING CHANGE: keep the order, as the Studio page says', + // HTML ends a tag's name only at a space, a `/` or a `>`. + 'BREAKING CHANGE: keep the order\n
\nthe page\n
', + 'BREAKING CHANGE: keep the order\n
\nthe page\n
', + 'BREAKING CHANGE: keep the order\n
\nthe page\n
', + ]) { + expect( + await errors(`fix(studio)!: keep the order\n\n${why}\n\n${footer}\nCloses: #1`), + ).toEqual(["no-changelog-link"]); + } + }); + + it("passes a link in the body, which the release leaves out of CHANGELOG.md", async () => { + expect( + await errors( + `fix(studio): keep the order\n\n${why} See [the Studio page](docs/studio.md).\n[studio]: docs/studio.md\n\nCloses: #1`, + ), + ).toEqual([]); + }); + + it("passes brackets and parentheses that are no link", async () => { + for (const words of [ + "keep a card's [front] and (back)", + "read arr[0] (the first)", + "keep the order (docs/studio.md)", + "keep the order, as [the Studio page] (docs/studio.md) says", + "name the file: docs/studio.md, in a ", + "keep x and a
", + ]) { + expect(await errors(`fix(ui): ${words}\n\n${why}\n\nCloses: #1`)).toEqual([]); + expect( + await errors(`fix(ui)!: ${words}\n\n${why}\n\nBREAKING CHANGE: ${words}\nCloses: #1`), + ).toEqual([]); + } + }); + + it("reads a long message of tags that never close in linear time", () => { + const timed = (runs: number) => { + const message = `fix(ui)!: keep the order\n\n${why}\n\nBREAKING CHANGE: ${"`)).toBe(true); + return performance.now() - started; + }; + timed(20_000); + // Ten times the input takes about ten times as long, where a check + // that read each tag again would take about a hundred times as long. + expect(timed(200_000)).toBeLessThan(40 * timed(20_000) + 50); + }); + it("still skips a revert and a fixup, as commitlint does by default", async () => { expect(await errors('Revert "fix: keep the deck\'s title"')).toEqual([]); expect(await errors("fixup! fix: keep the deck's title")).toEqual([]);