Repository navigation
Expand file tree
/
Copy pathcommitlint.config.mjs
More file actions
275 lines (258 loc) · 11.4 KB
/
Copy pathcommitlint.config.mjs
File metadata and controls
275 lines (258 loc) · 11.4 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
// 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)",
];
}
/**
* 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)`, ``, `[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 `!`.
*
* @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,
"no-changelog-link": noChangelogLink,
},
},
],
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"],
"no-changelog-link": [2, "always"],
},
};