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([]);