Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
10 changes: 8 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
82 changes: 82 additions & 0 deletions commitlint.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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 = /\][([:]|<file:|\bfile:\/\//i;

/**
* Whether the text holds an HTML tag with an attribute, which the link
* check reads for any attribute and on any element. Its name is read as
* HTML reads it: a letter after `<`, then anything up to a space, a `/`
* or a `>`. 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<b and c`, is left alone. It
* reads each character once, however many tags never close.
*
* @param {string} text
*/
function holdsTagWithAttribute(text) {
const end = text.lastIndexOf(">");
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 `!`.
Expand Down Expand Up @@ -177,6 +257,7 @@ export default {
"not-a-release": notARelease,
"no-skip-keyword": noSkipKeyword,
"no-changelog-directive": noChangelogDirective,
"no-changelog-link": noChangelogLink,
},
},
],
Expand All @@ -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"],
},
};
10 changes: 10 additions & 0 deletions docs/releasing.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 4 additions & 1 deletion docs/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 2 additions & 1 deletion lychee.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
50 changes: 50 additions & 0 deletions scripts/checkMergeMessages.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 <file:docs/studio.md> says",
'fix: show <img srcset="docs/no-such-image.png">',
'fix: keep the order, as <a title=">" href="docs/x.md">the page</a> 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);
});
Expand Down
21 changes: 13 additions & 8 deletions scripts/checkMergeMessages.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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[] {
Expand All @@ -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;
}

Expand Down
106 changes: 104 additions & 2 deletions scripts/commitlintConfig.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<string[]> {
Expand Down Expand Up @@ -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 <file:docs/studio.md> says",
"as file:///docs/studio.md says",
'as <a href="docs/studio.md">the Studio page</a> says',
"as <IMG SRC=docs/no-such-image.png> shows",
'with <img srcset="docs/no-such-image.png">',
'as <blockquote cite="docs/studio.md">it</blockquote> says',
'with <object data="docs/no-such-file.pdf"></object>',
'with <video poster="docs/no-such-image.png"></video>',
'with <form action="docs/studio.md"></form>',
'as <a title=">" href="docs/studio.md">the Studio page</a> says',
"as <img/src=docs/no-such-image.png> 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 <a\nhref="docs/studio.md">the Studio page</a> says',
// HTML ends a tag's name only at a space, a `/` or a `>`.
'BREAKING CHANGE: keep the order\n<div>\n<x:a href="docs/no-such-page.md">the page</x:a>\n</div>',
'BREAKING CHANGE: keep the order\n<div>\n<a" href="docs/no-such-page.md">the page</a>\n</div>',
'BREAKING CHANGE: keep the order\n<div>\n<a_b href="docs/no-such-page.md">the page</a_b>\n</div>',
]) {
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 <dialog>",
"keep x<y and z",
"keep a <br/> and a <br />",
]) {
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: ${"<a b".repeat(runs)}`;
const started = performance.now();
expect(holdsChangelogLink(message)).toBe(false);
expect(holdsChangelogLink(`${message}>`)).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([]);
Expand Down
Loading