@mark1russell7/conventions 0.26.0 → 0.27.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +18 -15
- package/build/cli.js +1 -1
- package/build/index.d.ts +2 -1
- package/build/index.d.ts.map +1 -1
- package/build/index.js +1 -1
- package/build/{run-DORqvzBZ.js → run-D8BNQq3y.js} +439 -33
- package/build/run-D8BNQq3y.js.map +1 -0
- package/package.json +2 -2
- package/build/run-DORqvzBZ.js.map +0 -1
|
@@ -1052,7 +1052,7 @@ const changelogVersion = {
|
|
|
1052
1052
|
doc: "the train plans a PATCH for a change of a dependency range"
|
|
1053
1053
|
},
|
|
1054
1054
|
{
|
|
1055
|
-
repo: "
|
|
1055
|
+
repo: "private",
|
|
1056
1056
|
rule: "semver",
|
|
1057
1057
|
doc: "the global CLAUDE.md, npm packages use Semantic Versioning"
|
|
1058
1058
|
}
|
|
@@ -1210,17 +1210,17 @@ const cuePreset = {
|
|
|
1210
1210
|
doc: "CLAUDE.md:64"
|
|
1211
1211
|
},
|
|
1212
1212
|
{
|
|
1213
|
-
repo: "
|
|
1213
|
+
repo: "private",
|
|
1214
1214
|
rule: "cue-preset-strict",
|
|
1215
1215
|
doc: "docs/architecture/ecosystem-and-structure.md:58"
|
|
1216
1216
|
},
|
|
1217
1217
|
{
|
|
1218
|
-
repo: "
|
|
1218
|
+
repo: "private",
|
|
1219
1219
|
rule: "strict-preset",
|
|
1220
1220
|
doc: "docs/architecture/ecosystem-and-structure.md:58"
|
|
1221
1221
|
},
|
|
1222
1222
|
{
|
|
1223
|
-
repo: "
|
|
1223
|
+
repo: "private",
|
|
1224
1224
|
rule: "new-package-via-cli",
|
|
1225
1225
|
doc: "CLAUDE.md:14"
|
|
1226
1226
|
},
|
|
@@ -1351,6 +1351,20 @@ function childKeys(lines, index) {
|
|
|
1351
1351
|
for (let i = index + 1; i < blockEnd(lines, index); i++) if ((lines[i] ?? "").trim() !== "" && indentOf$1(lines[i] ?? "") === indent) keys.push(i);
|
|
1352
1352
|
return keys;
|
|
1353
1353
|
}
|
|
1354
|
+
/**
|
|
1355
|
+
* This function applies changes to the lines of `text`, and keeps its line ends. The changes go from the end to the
|
|
1356
|
+
* start, so each index stays correct. At one index, a splice that removes lines goes first, so it removes only the old
|
|
1357
|
+
* lines. Then the inserts go in, the later one first, so they keep their order.
|
|
1358
|
+
*/
|
|
1359
|
+
function applySplices(text, splices) {
|
|
1360
|
+
const eol = text.includes("\r\n") ? "\r\n" : "\n";
|
|
1361
|
+
const out = text.split(/\r?\n/);
|
|
1362
|
+
for (const item of splices.map((value, order) => ({
|
|
1363
|
+
...value,
|
|
1364
|
+
order
|
|
1365
|
+
})).sort((a, b) => b.at - a.at || b.remove - a.remove || b.order - a.order)) out.splice(item.at, item.remove, ...item.insert);
|
|
1366
|
+
return out.join(eol);
|
|
1367
|
+
}
|
|
1354
1368
|
/** This function gives the text of a block scalar (`|`, `|-`, `>`, `>-`) under the line `index`. */
|
|
1355
1369
|
function scalar(lines, index, style) {
|
|
1356
1370
|
const body = lines.slice(index + 1, blockEnd(lines, index));
|
|
@@ -1530,7 +1544,7 @@ const mainRunsFinish = {
|
|
|
1530
1544
|
fix: `Set \`cancel-in-progress: ${PULL_REQUEST_ONLY}\`, and end the concurrency group with \`${OWN_GROUP}\`. In one group, GitHub cancels a run that waits when a newer run comes, whatever \`cancel-in-progress\` says.`,
|
|
1531
1545
|
sources: [
|
|
1532
1546
|
{
|
|
1533
|
-
repo: "
|
|
1547
|
+
repo: "private",
|
|
1534
1548
|
rule: "main-runs-finish",
|
|
1535
1549
|
doc: "docs/STRATEGY.md (2026-11-03, a run of main ends)"
|
|
1536
1550
|
},
|
|
@@ -1669,8 +1683,6 @@ const ifValue = (expression) => {
|
|
|
1669
1683
|
* person must convert the workflow.
|
|
1670
1684
|
*/
|
|
1671
1685
|
function convertGate(text, file, commit = ACTIONS_COMMIT) {
|
|
1672
|
-
const eol = text.includes("\r\n") ? "\r\n" : "\n";
|
|
1673
|
-
const original = text.split(/\r?\n/);
|
|
1674
1686
|
const lines = workflowLines(text);
|
|
1675
1687
|
const top = (key) => lines.findIndex((line) => indentOf$1(line) === 0 && keyValue(line, key) !== void 0);
|
|
1676
1688
|
const on = top("on");
|
|
@@ -1838,12 +1850,7 @@ function convertGate(text, file, commit = ACTIONS_COMMIT) {
|
|
|
1838
1850
|
remove: 0,
|
|
1839
1851
|
insert: summary
|
|
1840
1852
|
});
|
|
1841
|
-
|
|
1842
|
-
for (const item of splices.map((value, order) => ({
|
|
1843
|
-
...value,
|
|
1844
|
-
order
|
|
1845
|
-
})).sort((a, b) => b.at - a.at || b.remove - a.remove || b.order - a.order)) out.splice(item.at, item.remove, ...item.insert);
|
|
1846
|
-
return { text: out.join(eol) };
|
|
1853
|
+
return { text: applySplices(text, splices) };
|
|
1847
1854
|
}
|
|
1848
1855
|
const gateTrigger = {
|
|
1849
1856
|
id: "gate-trigger",
|
|
@@ -1851,7 +1858,7 @@ const gateTrigger = {
|
|
|
1851
1858
|
reason: "The ruleset requires the summary check \"<Name> OK\" of each gate. A workflow with a path filter does not start on a pull request that changes no file of the filter, so its check is not there, and the ruleset cannot require it. Then a pull request can merge before such a gate ends. On 2026-11-02, 19 such workflows in 11 repositories fed no required check.",
|
|
1852
1859
|
fix: "Remove the paths from on.pull_request. Add a job \"changes\" with the action mark1russell7/template/.github/actions/changes and the same paths, and \"if: needs.changes.outputs.match == 'true'\" on each gate job. Add a job \"<Name> OK\" with \"if: always()\", \"needs\" with each job, and the action gate-summary (CI.md, \"A gate with paths\"). Then start ruleset-ci-ok.ts again. A workflow that is not a gate can go in the option allow.",
|
|
1853
1860
|
sources: [{
|
|
1854
|
-
repo: "
|
|
1861
|
+
repo: "private",
|
|
1855
1862
|
rule: "gate-trigger",
|
|
1856
1863
|
doc: "docs/STRATEGY.md (2026-11-02, a gate with paths feeds a required summary)"
|
|
1857
1864
|
}],
|
|
@@ -6789,7 +6796,7 @@ const HOME_EXPORTS = {
|
|
|
6789
6796
|
// src/map.ts
|
|
6790
6797
|
/** The rule of the map. Each session and each review applies it. */
|
|
6791
6798
|
const MAP_RULE = "Before you write a helper, find its home in this map. If the home does not have the function, add it to the home, in a pull request of the home repository. Do not make a local copy, a new package or a new repository for an area that has a home: that needs the strategist. A home that is not on npm is used with workspace:* or a github: specifier pinned to a commit. If no area fits, ask the strategist for a home before you write the code.";
|
|
6792
|
-
/** The public homes. Each package
|
|
6799
|
+
/** The public homes. Each package that other code can use has one area. */
|
|
6793
6800
|
const HOMES = [
|
|
6794
6801
|
{
|
|
6795
6802
|
area: "statistics",
|
|
@@ -7561,10 +7568,10 @@ function messageOf(file, name, home) {
|
|
|
7561
7568
|
const homePackage = {
|
|
7562
7569
|
id: "home-package",
|
|
7563
7570
|
title: "A change does not add a function that belongs in the home of another area: a name that a home of the map of homes gives as its signature.",
|
|
7564
|
-
reason: "Each area of code has one home package (conventions map). A local copy of a helper of another area drifts from the home and splits the fixes: on 2026-11-02 the
|
|
7571
|
+
reason: "Each area of code has one home package (conventions map). A local copy of a helper of another area drifts from the home and splits the fixes: on 2026-11-02 the repositories had 68 local statistics functions (median, quantile, bootstrap and more) in 14 repositories, while @mark1russell7/rigor-statistics was on npm. The check examines only the lines that a change adds, so the copies that exist do not break, and the count can only go down.",
|
|
7565
7572
|
fix: "Import the function from its home. If the home does not have it, add it to the home in a pull request of the home repository, then import it. A function that only has the name of a signature and does another thing gets a new name.",
|
|
7566
7573
|
sources: [{
|
|
7567
|
-
repo: "
|
|
7574
|
+
repo: "private",
|
|
7568
7575
|
rule: "direction-18",
|
|
7569
7576
|
doc: "docs/STRATEGY.md (2026-11-02, one map of homes, checked when the code is written)"
|
|
7570
7577
|
}],
|
|
@@ -7894,7 +7901,7 @@ const mainCheck = {
|
|
|
7894
7901
|
reason: "Through a link, `process.argv[1]` has the path of the link, and the module has the real path. The compare is false, so the script does nothing and ends with exit code 0: a check that looks done but did not start.",
|
|
7895
7902
|
fix: "Write `if (import.meta.main)` when `engines.node` allows only versions that have it (`^22.18`, `>=24.2`). Else compare `realpathSync(process.argv[1])` with `realpathSync(fileURLToPath(import.meta.url))`. `conventions fix` writes the one that fits.",
|
|
7896
7903
|
sources: [{
|
|
7897
|
-
repo: "
|
|
7904
|
+
repo: "private",
|
|
7898
7905
|
rule: "main-check",
|
|
7899
7906
|
doc: "docs/STRATEGY.md (2026-11-02, the main check through a link)"
|
|
7900
7907
|
}],
|
|
@@ -8248,12 +8255,12 @@ const pinnedGitDeps = {
|
|
|
8248
8255
|
doc: "CLAUDE.md:38"
|
|
8249
8256
|
},
|
|
8250
8257
|
{
|
|
8251
|
-
repo: "
|
|
8258
|
+
repo: "private",
|
|
8252
8259
|
rule: "github-dep-full-sha",
|
|
8253
8260
|
doc: "docs/decisions.md:1384"
|
|
8254
8261
|
},
|
|
8255
8262
|
{
|
|
8256
|
-
repo: "
|
|
8263
|
+
repo: "private",
|
|
8257
8264
|
rule: "github-dep-pinned",
|
|
8258
8265
|
doc: "docs/decisions.md:1384"
|
|
8259
8266
|
},
|
|
@@ -8292,6 +8299,404 @@ const pinnedGitDeps = {
|
|
|
8292
8299
|
return breaks;
|
|
8293
8300
|
}
|
|
8294
8301
|
};
|
|
8302
|
+
// src/rules/push-main-only.ts
|
|
8303
|
+
/**
|
|
8304
|
+
* The rule `push-main-only`: a workflow that starts on `push` and on `pull_request` limits `push` to the default branch.
|
|
8305
|
+
* It also has `workflow_dispatch`. Then a commit of a branch with an open pull request starts one run, not two. A person
|
|
8306
|
+
* can still start a run on a branch with no pull request.
|
|
8307
|
+
*/
|
|
8308
|
+
/** The file of the release flow. A person changes it, with the rule `release-files`, so the fix does not write it. */
|
|
8309
|
+
const RELEASE_FILE = "release.yml";
|
|
8310
|
+
/** The patterns that match each branch. */
|
|
8311
|
+
const EACH_BRANCH = /* @__PURE__ */ new Set(["*", "**"]);
|
|
8312
|
+
/** A key of a block, in the quoted forms too. */
|
|
8313
|
+
const KEY = /^\s*(?:"([^"]*)"|'([^']*)'|([^\s:]+))\s*:(\s.*)?$/;
|
|
8314
|
+
/** A value with no filters: `{}`, `~` or `null`. */
|
|
8315
|
+
const NO_FILTERS = /^(\{\s*\}|~|null)$/;
|
|
8316
|
+
/** A text that shows that a workflow reads the tag of a run. */
|
|
8317
|
+
const READS_TAGS = /refs\/tags|ref_type/i;
|
|
8318
|
+
/** A workflow of the repository that a job calls. */
|
|
8319
|
+
const LOCAL_CALL = /uses:\s*["']?\.\/(\.github\/workflows\/[^\s"'@]+)/g;
|
|
8320
|
+
/** A text that names a branch: `refs/heads/<branch>`, or `ref_name == '<branch>'`. */
|
|
8321
|
+
const NAMED_BRANCH = /refs\/heads\/([\w./-]+)|ref_name\s*[!=]=\s*["']([^"']+)["']/gi;
|
|
8322
|
+
/** This function tells if the brackets of a flow value are closed. */
|
|
8323
|
+
function closed(text) {
|
|
8324
|
+
let depth = 0;
|
|
8325
|
+
let quote = "";
|
|
8326
|
+
for (const char of text) if (quote !== "") {
|
|
8327
|
+
if (char === quote) quote = "";
|
|
8328
|
+
} else if (char === "\"" || char === "'") quote = char;
|
|
8329
|
+
else if (char === "[" || char === "{") depth += 1;
|
|
8330
|
+
else if (char === "]" || char === "}") depth -= 1;
|
|
8331
|
+
return depth <= 0;
|
|
8332
|
+
}
|
|
8333
|
+
/** This function gives the whole text of a flow value that starts on the line `index`, and the index after its last line. */
|
|
8334
|
+
function flowValue(lines, index, value) {
|
|
8335
|
+
let text = value;
|
|
8336
|
+
let end = index + 1;
|
|
8337
|
+
while (!closed(text) && end < lines.length) {
|
|
8338
|
+
text += ` ${valueOf$1(lines[end] ?? "")}`;
|
|
8339
|
+
end += 1;
|
|
8340
|
+
}
|
|
8341
|
+
return {
|
|
8342
|
+
text,
|
|
8343
|
+
end
|
|
8344
|
+
};
|
|
8345
|
+
}
|
|
8346
|
+
/** This function splits the text in the outer brackets of a flow value, at each comma of the first level. */
|
|
8347
|
+
function flowParts(text) {
|
|
8348
|
+
const parts = [];
|
|
8349
|
+
let depth = 0;
|
|
8350
|
+
let quote = "";
|
|
8351
|
+
let part = "";
|
|
8352
|
+
for (const char of text.slice(1, -1)) {
|
|
8353
|
+
if (quote !== "") {
|
|
8354
|
+
if (char === quote) quote = "";
|
|
8355
|
+
} else if (char === "\"" || char === "'") quote = char;
|
|
8356
|
+
else if (char === "[" || char === "{") depth += 1;
|
|
8357
|
+
else if (char === "]" || char === "}") depth -= 1;
|
|
8358
|
+
else if (char === "," && depth === 0) {
|
|
8359
|
+
parts.push(part);
|
|
8360
|
+
part = "";
|
|
8361
|
+
continue;
|
|
8362
|
+
}
|
|
8363
|
+
part += char;
|
|
8364
|
+
}
|
|
8365
|
+
parts.push(part);
|
|
8366
|
+
return parts.map((item) => item.trim()).filter((item) => item !== "");
|
|
8367
|
+
}
|
|
8368
|
+
/** This function gives the key and the value of an entry of a flow map. */
|
|
8369
|
+
function flowEntry(part) {
|
|
8370
|
+
const colon = part.search(/:(\s|$)/);
|
|
8371
|
+
return colon < 0 ? {
|
|
8372
|
+
key: valueOf$1(part),
|
|
8373
|
+
value: ""
|
|
8374
|
+
} : {
|
|
8375
|
+
key: valueOf$1(part.slice(0, colon)),
|
|
8376
|
+
value: valueOf$1(part.slice(colon + 1))
|
|
8377
|
+
};
|
|
8378
|
+
}
|
|
8379
|
+
/** This function gives the key and the value of a line of a block. */
|
|
8380
|
+
function keyOf(line) {
|
|
8381
|
+
const found = KEY.exec(line);
|
|
8382
|
+
if (found === null) return void 0;
|
|
8383
|
+
return {
|
|
8384
|
+
key: found[1] ?? found[2] ?? found[3] ?? "",
|
|
8385
|
+
value: valueOf$1(found[4] ?? "")
|
|
8386
|
+
};
|
|
8387
|
+
}
|
|
8388
|
+
const isItem = (line) => line.trimStart().startsWith("- ");
|
|
8389
|
+
/** This function reads the triggers of a workflow, in each form of `on`. */
|
|
8390
|
+
function readTriggers(lines) {
|
|
8391
|
+
const on = lines.findIndex((line) => indentOf$1(line) === 0 && keyValue(line, "on") !== void 0);
|
|
8392
|
+
if (on < 0) return void 0;
|
|
8393
|
+
const value = keyValue(lines[on] ?? "", "on") ?? "";
|
|
8394
|
+
if (value === "") {
|
|
8395
|
+
const next = lines.findIndex((line, index) => index > on && line.trim() !== "");
|
|
8396
|
+
const first = lines[next] ?? "";
|
|
8397
|
+
if (next >= 0 && isItem(first)) {
|
|
8398
|
+
const list = [];
|
|
8399
|
+
for (let index = next; index < lines.length; index++) {
|
|
8400
|
+
const line = lines[index] ?? "";
|
|
8401
|
+
if (line.trim() === "") continue;
|
|
8402
|
+
if (!isItem(line) || indentOf$1(line) !== indentOf$1(first)) break;
|
|
8403
|
+
list.push({
|
|
8404
|
+
name: valueOf$1(line.trimStart().slice(2)),
|
|
8405
|
+
at: index,
|
|
8406
|
+
value: ""
|
|
8407
|
+
});
|
|
8408
|
+
}
|
|
8409
|
+
return {
|
|
8410
|
+
form: "items",
|
|
8411
|
+
on,
|
|
8412
|
+
end: on + 1,
|
|
8413
|
+
list
|
|
8414
|
+
};
|
|
8415
|
+
}
|
|
8416
|
+
const list = childKeys(lines, on).flatMap((at) => {
|
|
8417
|
+
const entry = keyOf(lines[at] ?? "");
|
|
8418
|
+
return entry === void 0 ? [] : [{
|
|
8419
|
+
name: entry.key,
|
|
8420
|
+
at,
|
|
8421
|
+
value: entry.value
|
|
8422
|
+
}];
|
|
8423
|
+
});
|
|
8424
|
+
return {
|
|
8425
|
+
form: "keys",
|
|
8426
|
+
on,
|
|
8427
|
+
end: on + 1,
|
|
8428
|
+
list
|
|
8429
|
+
};
|
|
8430
|
+
}
|
|
8431
|
+
const flow = flowValue(lines, on, value);
|
|
8432
|
+
if (value.startsWith("[")) return {
|
|
8433
|
+
form: "flow",
|
|
8434
|
+
on,
|
|
8435
|
+
end: flow.end,
|
|
8436
|
+
list: flowParts(flow.text).map((part) => ({
|
|
8437
|
+
name: valueOf$1(part),
|
|
8438
|
+
at: on,
|
|
8439
|
+
value: ""
|
|
8440
|
+
}))
|
|
8441
|
+
};
|
|
8442
|
+
if (value.startsWith("{")) {
|
|
8443
|
+
const list = flowParts(flow.text).map((part) => {
|
|
8444
|
+
const entry = flowEntry(part);
|
|
8445
|
+
return {
|
|
8446
|
+
name: entry.key,
|
|
8447
|
+
at: on,
|
|
8448
|
+
value: entry.value
|
|
8449
|
+
};
|
|
8450
|
+
});
|
|
8451
|
+
return {
|
|
8452
|
+
form: "map",
|
|
8453
|
+
on,
|
|
8454
|
+
end: flow.end,
|
|
8455
|
+
list
|
|
8456
|
+
};
|
|
8457
|
+
}
|
|
8458
|
+
return {
|
|
8459
|
+
form: "flow",
|
|
8460
|
+
on,
|
|
8461
|
+
end: on + 1,
|
|
8462
|
+
list: [{
|
|
8463
|
+
name: value,
|
|
8464
|
+
at: on,
|
|
8465
|
+
value: ""
|
|
8466
|
+
}]
|
|
8467
|
+
};
|
|
8468
|
+
}
|
|
8469
|
+
/** This function gives the filters of a trigger, in the block form and in the flow form. */
|
|
8470
|
+
function filtersOf(lines, trigger) {
|
|
8471
|
+
if (trigger.value.startsWith("{")) {
|
|
8472
|
+
const flow = flowValue(lines, trigger.at, trigger.value);
|
|
8473
|
+
return flowParts(flow.text).map((part) => {
|
|
8474
|
+
const entry = flowEntry(part);
|
|
8475
|
+
const items = entry.value.startsWith("[") ? flowParts(entry.value).map(valueOf$1) : [entry.value];
|
|
8476
|
+
return {
|
|
8477
|
+
key: entry.key,
|
|
8478
|
+
at: trigger.at,
|
|
8479
|
+
end: flow.end,
|
|
8480
|
+
items
|
|
8481
|
+
};
|
|
8482
|
+
});
|
|
8483
|
+
}
|
|
8484
|
+
if (trigger.value !== "") return [];
|
|
8485
|
+
return childKeys(lines, trigger.at).flatMap((at) => {
|
|
8486
|
+
const entry = keyOf(lines[at] ?? "");
|
|
8487
|
+
if (entry === void 0) return [];
|
|
8488
|
+
const list = listItems(lines, at, entry.value);
|
|
8489
|
+
if (list !== void 0) return [{
|
|
8490
|
+
key: entry.key,
|
|
8491
|
+
at,
|
|
8492
|
+
end: list.end,
|
|
8493
|
+
items: list.items
|
|
8494
|
+
}];
|
|
8495
|
+
return [{
|
|
8496
|
+
key: entry.key,
|
|
8497
|
+
at,
|
|
8498
|
+
end: at + 1,
|
|
8499
|
+
items: /^[[{]/.test(entry.value) ? void 0 : [entry.value]
|
|
8500
|
+
}];
|
|
8501
|
+
});
|
|
8502
|
+
}
|
|
8503
|
+
/** This function gives the break of a workflow, or undefined when the rule leaves the workflow alone. */
|
|
8504
|
+
function findBreak(text, facts) {
|
|
8505
|
+
const lines = workflowLines(text);
|
|
8506
|
+
const triggers = readTriggers(lines);
|
|
8507
|
+
if (triggers === void 0) return void 0;
|
|
8508
|
+
const push = triggers.list.find((trigger) => trigger.name === "push");
|
|
8509
|
+
const pull = triggers.list.find((trigger) => trigger.name === "pull_request");
|
|
8510
|
+
if (push === void 0 || pull === void 0) return void 0;
|
|
8511
|
+
const types = filtersOf(lines, pull).find((filter) => filter.key === "types");
|
|
8512
|
+
if (types?.items !== void 0 && !types.items.includes("synchronize")) return void 0;
|
|
8513
|
+
const filters = filtersOf(lines, push);
|
|
8514
|
+
const has = (key) => filters.find((filter) => filter.key === key);
|
|
8515
|
+
const branches = has("branches");
|
|
8516
|
+
if (branches === void 0 && has("branches-ignore") === void 0 && (has("tags") ?? has("tags-ignore")) !== void 0) return void 0;
|
|
8517
|
+
const allowed = [facts.branch, ...facts.more];
|
|
8518
|
+
const items = branches?.items;
|
|
8519
|
+
const wide = items === void 0 || items.length === 0 || !items.every((item) => allowed.includes(item));
|
|
8520
|
+
const noDispatch = !triggers.list.some((trigger) => trigger.name === "workflow_dispatch");
|
|
8521
|
+
if (!wide && !noDispatch) return void 0;
|
|
8522
|
+
return {
|
|
8523
|
+
lines,
|
|
8524
|
+
triggers,
|
|
8525
|
+
push,
|
|
8526
|
+
filters,
|
|
8527
|
+
wide,
|
|
8528
|
+
noDispatch
|
|
8529
|
+
};
|
|
8530
|
+
}
|
|
8531
|
+
/** This function gives the reason why a person must change the workflow, or undefined when the fix can write it. */
|
|
8532
|
+
function refusal(file, text, finding, facts) {
|
|
8533
|
+
if (file.slice(file.lastIndexOf("/") + 1) === RELEASE_FILE) return `${RELEASE_FILE} belongs to the release flow`;
|
|
8534
|
+
const { triggers, filters, wide } = finding;
|
|
8535
|
+
if (triggers.form === "map") return "on has the flow form of a map";
|
|
8536
|
+
if (triggers.end > triggers.on + 1) return "on is a flow value of more than one line";
|
|
8537
|
+
if (!wide) return void 0;
|
|
8538
|
+
if (filters.some((filter) => filter.key === "branches-ignore")) return "on.push has branches-ignore, and only a person can tell which ignored branches stay";
|
|
8539
|
+
const allowed = [facts.branch, ...facts.more];
|
|
8540
|
+
const branches = filters.find((filter) => filter.key === "branches");
|
|
8541
|
+
if (branches !== void 0) {
|
|
8542
|
+
if (branches.items === void 0) return "the rule cannot read on.push.branches";
|
|
8543
|
+
if (branches.at === finding.push.at) return "on.push.branches is in the flow form of a map";
|
|
8544
|
+
const named = branches.items.filter((item) => !EACH_BRANCH.has(item) && !allowed.includes(item));
|
|
8545
|
+
if (named.length > 0 || branches.items.length === 0) return `on.push.branches names ${named.join(", ") || "no branch"}. Remove them, or add them to the option branches of the rule`;
|
|
8546
|
+
}
|
|
8547
|
+
const others = [...`${workflowLines(text).join("\n")}\n${facts.called(text)}`.matchAll(NAMED_BRANCH)].map((match) => match[1] ?? match[2] ?? "").filter((name) => !allowed.includes(name));
|
|
8548
|
+
if (others.length > 0) return `the workflow reads the branch ${[...new Set(others)].join(", ")}, so a limit on push can stop a job`;
|
|
8549
|
+
}
|
|
8550
|
+
/** This function gives a comment at the end of a line, with its space, or an empty text. */
|
|
8551
|
+
const commentOf = (line) => /\s+#.*$/.exec(line)?.[0] ?? "";
|
|
8552
|
+
/** This function writes the fix of a break: the new filter of `push`, and `workflow_dispatch`. Each other line stays. */
|
|
8553
|
+
function convert(text, file, finding, facts) {
|
|
8554
|
+
const { lines, triggers, push, filters, wide, noDispatch } = finding;
|
|
8555
|
+
const original = text.split(/\r?\n/);
|
|
8556
|
+
const branches = filters.find((filter) => filter.key === "branches");
|
|
8557
|
+
const tags = wide && branches === void 0 && READS_TAGS.test(`${workflowLines(text).join("\n")}\n${facts.called(text)}`);
|
|
8558
|
+
const limit = `branches: [${facts.branch}]`;
|
|
8559
|
+
const limits = (pad) => wide ? [`${pad}${limit}`, ...tags ? [`${pad}tags: ["**"]`] : []] : [];
|
|
8560
|
+
const name = file.slice(file.lastIndexOf("/") + 1);
|
|
8561
|
+
const dispatch = (pad) => noDispatch ? [`${pad}# A person starts a run on a branch with no pull request: gh workflow run ${name} --ref <branch>`, `${pad}workflow_dispatch:`] : [];
|
|
8562
|
+
const splices = [];
|
|
8563
|
+
if (triggers.form === "flow") {
|
|
8564
|
+
const line = original[triggers.on] ?? "";
|
|
8565
|
+
const body = triggers.list.flatMap((trigger) => [` ${trigger.name}:`, ...trigger === push ? limits(" ") : []]);
|
|
8566
|
+
splices.push({
|
|
8567
|
+
at: triggers.on,
|
|
8568
|
+
remove: 1,
|
|
8569
|
+
insert: [
|
|
8570
|
+
`${line.slice(0, line.indexOf(":") + 1)}${commentOf(line)}`,
|
|
8571
|
+
...body,
|
|
8572
|
+
...dispatch(" ")
|
|
8573
|
+
]
|
|
8574
|
+
});
|
|
8575
|
+
} else if (triggers.form === "items") {
|
|
8576
|
+
const pad = " ".repeat(Math.max(indentOf$1(lines[triggers.list[0]?.at ?? 0] ?? ""), 2));
|
|
8577
|
+
for (const trigger of triggers.list) splices.push({
|
|
8578
|
+
at: trigger.at,
|
|
8579
|
+
remove: 1,
|
|
8580
|
+
insert: [`${pad}${trigger.name}:${commentOf(original[trigger.at] ?? "")}`, ...trigger === push ? limits(`${pad} `) : []]
|
|
8581
|
+
});
|
|
8582
|
+
splices.push({
|
|
8583
|
+
at: (triggers.list.at(-1)?.at ?? triggers.on) + 1,
|
|
8584
|
+
remove: 0,
|
|
8585
|
+
insert: dispatch(pad)
|
|
8586
|
+
});
|
|
8587
|
+
} else {
|
|
8588
|
+
const line = original[push.at] ?? "";
|
|
8589
|
+
const pad = indentOf$1(lines[push.at] ?? "");
|
|
8590
|
+
const inner = " ".repeat(childIndent(lines, push.at) ?? pad + Math.max(pad - indentOf$1(lines[triggers.on] ?? ""), 2));
|
|
8591
|
+
if (wide && branches !== void 0) splices.push({
|
|
8592
|
+
at: branches.at,
|
|
8593
|
+
remove: branches.end - branches.at,
|
|
8594
|
+
insert: [`${" ".repeat(indentOf$1(lines[branches.at] ?? ""))}${limit}${commentOf(original[branches.at] ?? "")}`]
|
|
8595
|
+
});
|
|
8596
|
+
else if (wide && push.value !== "" && !NO_FILTERS.test(push.value)) {
|
|
8597
|
+
const added = [limit, ...tags ? ["tags: [\"**\"]"] : []].join(", ");
|
|
8598
|
+
splices.push({
|
|
8599
|
+
at: push.at,
|
|
8600
|
+
remove: 1,
|
|
8601
|
+
insert: [line.replace(/\{\s*/, () => `{ ${added}, `)]
|
|
8602
|
+
});
|
|
8603
|
+
} else if (wide) splices.push({
|
|
8604
|
+
at: push.at,
|
|
8605
|
+
remove: 1,
|
|
8606
|
+
insert: [line.replace(/:\s+(\{\s*\}|~|null)/, ":"), ...limits(inner)]
|
|
8607
|
+
});
|
|
8608
|
+
const last = triggers.list.at(-1)?.at ?? triggers.on;
|
|
8609
|
+
let end = blockEnd(lines, last);
|
|
8610
|
+
while (end > last + 1 && (lines[end - 1] ?? "").trim() === "") end -= 1;
|
|
8611
|
+
splices.push({
|
|
8612
|
+
at: end,
|
|
8613
|
+
remove: 0,
|
|
8614
|
+
insert: dispatch(" ".repeat(pad))
|
|
8615
|
+
});
|
|
8616
|
+
}
|
|
8617
|
+
return applySplices(text, splices);
|
|
8618
|
+
}
|
|
8619
|
+
/** This function gives the default branch: the event file of GitHub Actions, the `HEAD` of the remote, or else `main`. */
|
|
8620
|
+
function defaultBranch(context) {
|
|
8621
|
+
const file = context.env["GITHUB_EVENT_PATH"];
|
|
8622
|
+
if (file !== void 0 && file !== "") try {
|
|
8623
|
+
const branch = JSON.parse(readFileSync(file, "utf8")).repository?.default_branch;
|
|
8624
|
+
if (typeof branch === "string" && branch !== "") return branch;
|
|
8625
|
+
} catch {}
|
|
8626
|
+
const head = context.git([
|
|
8627
|
+
"symbolic-ref",
|
|
8628
|
+
"--quiet",
|
|
8629
|
+
"--short",
|
|
8630
|
+
"refs/remotes/origin/HEAD"
|
|
8631
|
+
])?.trim();
|
|
8632
|
+
return head === void 0 || head === "" ? "main" : head.replace(/^origin\//, "");
|
|
8633
|
+
}
|
|
8634
|
+
const pushMainOnly = {
|
|
8635
|
+
id: "push-main-only",
|
|
8636
|
+
title: "A workflow that starts on push and on pull_request limits push to the default branch with branches, and has workflow_dispatch.",
|
|
8637
|
+
reason: "A commit on a branch with an open pull request starts such a workflow two times: one run for push and one run for pull_request. On 2026-11-04 the CI queue held about 263 jobs, and a rough estimate puts about 65 of them in such second runs. The run for pull_request gives the required checks, so the run for push adds nothing. With workflow_dispatch, a person can still start a run on a branch with no pull request.",
|
|
8638
|
+
fix: "Add `branches: [<default branch>]` under `on.push`, and add `workflow_dispatch:` under `on` (CI.md, \"One run for each commit\"). A push with only a tag filter, or a pull request trigger with no `synchronize`, is not a break. For a long-lived branch, add the branch to the option branches.",
|
|
8639
|
+
sources: [
|
|
8640
|
+
{
|
|
8641
|
+
repo: "template",
|
|
8642
|
+
rule: "push-main-only",
|
|
8643
|
+
doc: ".github/workflows/security.yml (push has branches: [main], and the file has workflow_dispatch)"
|
|
8644
|
+
},
|
|
8645
|
+
{
|
|
8646
|
+
repo: "crawler",
|
|
8647
|
+
rule: "push-main-only",
|
|
8648
|
+
doc: ".github/workflows/ci.yml (push has branches: [main], and the file has workflow_dispatch)"
|
|
8649
|
+
},
|
|
8650
|
+
{
|
|
8651
|
+
repo: "systems",
|
|
8652
|
+
rule: "push-main-only",
|
|
8653
|
+
doc: ".github/workflows/process.yml (push has branches: [main], and the file has workflow_dispatch)"
|
|
8654
|
+
}
|
|
8655
|
+
],
|
|
8656
|
+
options: { branches: {
|
|
8657
|
+
type: "strings",
|
|
8658
|
+
default: [],
|
|
8659
|
+
description: "More branches that `on.push.branches` can name, for example a long-lived release branch."
|
|
8660
|
+
} },
|
|
8661
|
+
check(context, options) {
|
|
8662
|
+
const files = context.gitFiles();
|
|
8663
|
+
if (files === void 0) return { skipped: "the root is not in a git repository" };
|
|
8664
|
+
const workflows = files.filter((path) => WORKFLOW$1.test(path)).sort(byCode);
|
|
8665
|
+
if (workflows.length === 0) return { skipped: "the repository has no workflow" };
|
|
8666
|
+
const read = (file) => {
|
|
8667
|
+
try {
|
|
8668
|
+
return readFileSync(join(context.root, file), "utf8");
|
|
8669
|
+
} catch {
|
|
8670
|
+
return "";
|
|
8671
|
+
}
|
|
8672
|
+
};
|
|
8673
|
+
const facts = {
|
|
8674
|
+
branch: defaultBranch(context),
|
|
8675
|
+
more: Array.isArray(options["branches"]) ? options["branches"] : [],
|
|
8676
|
+
called: (text) => [...text.matchAll(LOCAL_CALL)].map((match) => workflowLines(read(match[1] ?? "")).join("\n")).join("\n")
|
|
8677
|
+
};
|
|
8678
|
+
const breaks = [];
|
|
8679
|
+
for (const file of workflows) {
|
|
8680
|
+
const text = read(file);
|
|
8681
|
+
const finding = findBreak(text, facts);
|
|
8682
|
+
if (finding === void 0) continue;
|
|
8683
|
+
const parts = [...finding.wide ? [`push starts on more branches than ${[facts.branch, ...facts.more].join(", ")}, so a commit of a pull request starts it two times`] : [], ...finding.noDispatch ? ["it has no workflow_dispatch, so a person cannot start a run on a branch"] : []];
|
|
8684
|
+
const reason = refusal(file, text, finding, facts);
|
|
8685
|
+
const after = reason === void 0 ? convert(text, file, finding, facts) : void 0;
|
|
8686
|
+
breaks.push({
|
|
8687
|
+
file,
|
|
8688
|
+
line: finding.push.at + 1,
|
|
8689
|
+
message: `${file} starts on push and on pull_request: ${parts.join(", and ")}.`,
|
|
8690
|
+
...after !== void 0 && findBreak(after, facts) === void 0 ? { edits: [{
|
|
8691
|
+
file,
|
|
8692
|
+
before: text,
|
|
8693
|
+
after
|
|
8694
|
+
}] } : { fix: `A person must change it, because ${reason ?? "the fix does not end the break"}. ${pushMainOnly.fix}` }
|
|
8695
|
+
});
|
|
8696
|
+
}
|
|
8697
|
+
return breaks;
|
|
8698
|
+
}
|
|
8699
|
+
};
|
|
8295
8700
|
// src/rules/release-files.ts
|
|
8296
8701
|
/**
|
|
8297
8702
|
* The rule `release-files`: a pull request changes a file of the release flow only with a reason
|
|
@@ -8456,7 +8861,7 @@ const requiredScripts = {
|
|
|
8456
8861
|
doc: "CLAUDE.md:5"
|
|
8457
8862
|
},
|
|
8458
8863
|
{
|
|
8459
|
-
repo: "
|
|
8864
|
+
repo: "private",
|
|
8460
8865
|
rule: "ste-prose",
|
|
8461
8866
|
doc: "CLAUDE.md:5"
|
|
8462
8867
|
},
|
|
@@ -8592,7 +8997,7 @@ const roadmapParses = {
|
|
|
8592
8997
|
reason: "Only the Pages job on main reads the roadmap. A pull request with a bad table row passes each check, and then the build of the site stops and the site stays stale. On 2026-10-30, one repository had 3 red Pages runs in a row because of one row with 2 cells under a header with 4. A site with no roadmap is the same fault with no error: its Status page shows no item of the plan, and each check is green. On 2026-10-30, 2 repositories had a site with no roadmap.",
|
|
8593
8998
|
fix: "Give the roadmap file to the Pages workflow (`roadmap: docs/ROADMAP.md`). Correct the row or the heading that the message names. Each table row has one cell for each column of its header, and the file has a table with an ID column and a Status column, or a heading \"### `id`: Title\".",
|
|
8594
8999
|
sources: [{
|
|
8595
|
-
repo: "
|
|
9000
|
+
repo: "private",
|
|
8596
9001
|
rule: "fail-closed",
|
|
8597
9002
|
doc: "docs/STRATEGY.md (2026-10-30, gates and probes fail closed)"
|
|
8598
9003
|
}],
|
|
@@ -8865,7 +9270,7 @@ const runnerBudget = {
|
|
|
8865
9270
|
reason: "All repositories of the account share 40 runners, and heavy work keeps at most 28 of them. On 2026-10-30, a matrix with no max-parallel and the sync pull requests of about 20 repositories filled 39 of the 40 runners, with 88 jobs in the queue. Each repository copied the weekly scan at `23 5 * * 1`, so all scans started at the same minute. A workflow with no concurrency group starts a new run on each push, and the old runs keep their runners.",
|
|
8866
9271
|
fix: "Add `max-parallel: 3` (or less) under `strategy`. Add a concurrency group at the top of the workflow (`concurrency: { group: <name>-${{ github.event_name == 'pull_request' && github.ref || github.sha }}, cancel-in-progress: ${{ github.event_name == 'pull_request' }} }`), or in each job. Change the minute of each `cron` to the minute that the message gives; the hour and the days stay.",
|
|
8867
9272
|
sources: [{
|
|
8868
|
-
repo: "
|
|
9273
|
+
repo: "private",
|
|
8869
9274
|
rule: "runner-slots",
|
|
8870
9275
|
doc: "docs/STRATEGY.md (2026-10-30, the runner slots: a cap of 40, heavy work at most 28)"
|
|
8871
9276
|
}],
|
|
@@ -9293,12 +9698,12 @@ const sourceMain = {
|
|
|
9293
9698
|
doc: "CLAUDE.md:41"
|
|
9294
9699
|
},
|
|
9295
9700
|
{
|
|
9296
|
-
repo: "
|
|
9701
|
+
repo: "private",
|
|
9297
9702
|
rule: "new-package-main-index",
|
|
9298
9703
|
doc: "CLAUDE.md:15"
|
|
9299
9704
|
},
|
|
9300
9705
|
{
|
|
9301
|
-
repo: "
|
|
9706
|
+
repo: "private",
|
|
9302
9707
|
rule: "source-package-main",
|
|
9303
9708
|
doc: "CLAUDE.md:15"
|
|
9304
9709
|
},
|
|
@@ -9520,10 +9925,10 @@ function removeOption(context, files, file, text, index) {
|
|
|
9520
9925
|
const testsRequired = {
|
|
9521
9926
|
id: "tests-required",
|
|
9522
9927
|
title: "No test runner passes when it finds no test: no `passWithNoTests: true` in a config, and no `--passWithNoTests` in a script.",
|
|
9523
|
-
reason: "With the option, a test step that finds 0 tests passes. A broken include pattern, a moved folder or a renamed file then turns the gate green with no test run. In
|
|
9928
|
+
reason: "With the option, a test step that finds 0 tests passes. A broken include pattern, a moved folder or a renamed file then turns the gate green with no test run. In an audit of 2026-10-30, vex had the option in all 9 vitest configs and client in 2 packages that have tests.",
|
|
9524
9929
|
fix: "Remove the option. A package with no tests has no test script, so the shared CI skips it. A package whose tests a later change adds keeps no test script until then.",
|
|
9525
9930
|
sources: [{
|
|
9526
|
-
repo: "
|
|
9931
|
+
repo: "private",
|
|
9527
9932
|
rule: "fail-closed",
|
|
9528
9933
|
doc: "docs/STRATEGY.md (2026-10-30, gates and probes fail closed)"
|
|
9529
9934
|
}],
|
|
@@ -9807,10 +10212,10 @@ const fromRoot = (root, file) => relative(root, file).split("\\").join("/");
|
|
|
9807
10212
|
const typedFiles = {
|
|
9808
10213
|
id: "typed-files",
|
|
9809
10214
|
title: "Each TypeScript file that git keeps is in a tsconfig that a `typecheck` script examines: the tests, the e2e specs, the scripts, the benches and the configs too.",
|
|
9810
|
-
reason: "A file that no tsconfig of a typecheck holds has no type check. Its type errors hide until it runs, and a broken test or script can pass a gate. A test runner such as vitest strips the types, so it does not examine them. In
|
|
10215
|
+
reason: "A file that no tsconfig of a typecheck holds has no type check. Its type errors hide until it runs, and a broken test or script can pass a gate. A test runner such as vitest strips the types, so it does not examine them. In an audit of 2026-10-30, every repository had such files (in one, 90 of 612 files, its e2e specs among them), and the new checks found real defects.",
|
|
9811
10216
|
fix: "Add the file to the `include` of a tsconfig that the `typecheck` script names (for example `tsconfig.test.json`, with `*.config.ts`, `scripts/**`, `bench/**` and `e2e/**`). A config file at the root of a package needs `rootDir: \".\"` there. For the files at the root of the repository, add a `tsconfig.repo.json` and name it in the root `typecheck`. A file that cannot be in a typecheck (it imports a module that only a tool makes) goes in `ignore` with its reason.",
|
|
9812
10217
|
sources: [{
|
|
9813
|
-
repo: "
|
|
10218
|
+
repo: "private",
|
|
9814
10219
|
rule: "fail-closed",
|
|
9815
10220
|
doc: "docs/STRATEGY.md (2026-10-30, gates and probes fail closed)"
|
|
9816
10221
|
}],
|
|
@@ -9936,7 +10341,7 @@ const typedScripts = {
|
|
|
9936
10341
|
reason: "A script has bugs like the code, and types and tests find them. Node 22.18 and later runs a `.ts` file directly, so a script in JavaScript or in a shell language has no cost to save and no check. A shell file stays only as a launcher of one line.",
|
|
9937
10342
|
fix: "Rename the file to `.ts`, add the types, and check it with `tsc --noEmit` and a test. Move the logic of a shell script into a `.ts` file, and keep the shell file as one line that starts it, or remove it. A file that must stay (generated output, vendored code, a configuration that a tool reads only as JavaScript) goes in `ignore` with its reason.",
|
|
9938
10343
|
sources: [{
|
|
9939
|
-
repo: "
|
|
10344
|
+
repo: "private",
|
|
9940
10345
|
rule: "typed-everything",
|
|
9941
10346
|
doc: "docs/STRATEGY.md:78"
|
|
9942
10347
|
}],
|
|
@@ -10075,7 +10480,7 @@ const trustPolicy = {
|
|
|
10075
10480
|
reason: "A stolen npm token can publish a version with no provenance, and the next install takes it. With `no-downgrade`, pnpm refuses a version with less trust evidence than an earlier version. The release age of pnpm keeps out the versions of the last day; this check covers the next days. The release train updates our own scopes at once and checks their provenance itself.",
|
|
10076
10481
|
fix: "Add `trustPolicy: no-downgrade`, `trustPolicyIgnoreAfter: 10080` and a `trustPolicyExclude` with the scopes of the option `exclude` to `pnpm-workspace.yaml`. `conventions fix` writes them.",
|
|
10077
10482
|
sources: [{
|
|
10078
|
-
repo: "
|
|
10483
|
+
repo: "private",
|
|
10079
10484
|
rule: "trust-policy",
|
|
10080
10485
|
doc: "docs/STRATEGY.md (2026-11-01, release age and trust policy)"
|
|
10081
10486
|
}],
|
|
@@ -10502,6 +10907,7 @@ const RULES = [
|
|
|
10502
10907
|
roadmapParses,
|
|
10503
10908
|
runnerBudget,
|
|
10504
10909
|
mainRunsFinish,
|
|
10910
|
+
pushMainOnly,
|
|
10505
10911
|
gateTrigger,
|
|
10506
10912
|
homePackage,
|
|
10507
10913
|
licenseFile,
|
|
@@ -10909,6 +11315,6 @@ function runMap(args, io) {
|
|
|
10909
11315
|
else io.stdout(mapText(found));
|
|
10910
11316
|
return 0;
|
|
10911
11317
|
}
|
|
10912
|
-
export {
|
|
11318
|
+
export { noBuildOutput as $, pathsOf as A, DEPENDENCY_FIELDS as At, roadmapParses as B, replaceLine as Bt, configsOfScript as C, convertGate as Ct, hasTests as D, readWorkflow as Dt, testsRequired as E, summaryName as Et, sharedDocsRule as F, keyLine as Ft, isPinned as G, packageFolders as Gt, releaseFiles as H, specifiersOf as Ht, repositoryOfRemote as I, lineOf as It, pagesCalls as J, parseConfig as Jt, pinnedGitDeps as K, workspaceGlobs as Kt, runnerBudget as L, matchesAny as Lt, HOME_TIMEOUT_MS as M, codePackages as Mt, blockHash as N, hasFile as Nt, tsconfigTest as O, STRICT_OPTIONS as Ot, githubFetch as P, inFolder as Pt, noLocalPaths as Q, scheduleMinute as R, parseJsonc as Rt, typedScripts as S, ACTIONS_COMMIT as St, typedFiles as T, prPathFilters as Tt, pushMainOnly as U, globFolders as Ut, requiredScripts as V, runGit as Vt, isGitSpecifier as W, globToRegExp as Wt, DEFAULT_ALLOWED as X, pagesSite as Y, HOME_PATTERNS as Z, unreleasedChange as _, mapMarkdown as _t, listRules as a, licenseFile as at, TRAIN_SCOPES as b, readOverlay as bt, runCli as c, repositoryIsPublic as ct, RULES as d, messageOf as dt, REAL_COMPARE as et, workspaceProtocol as f, repoOf as ft, npmLookup as g, findHomes as gt, UNSHIPPED_FILES as h, MAP_RULE as ht, formatResult as i, authorOf as it, sourceMain as j, cleanPath as jt, isSourcePath as k, cuePreset as kt, runFix as l, declaredName as lt, SHIPPED_FIELDS as m, HOMES as mt, annotations as n, mainCheck as nt, readConfig as o, licenseFileOf as ot, NPM_REGISTRY as p, signaturesOf as pt, PAGES_WORKFLOWS as q, defaultOptions as qt, createContext as r, LICENSE_TEXTS as rt, runChecks as s, mitText as st, USAGE as t, hasImportMetaMain as tt, summaryMarkdown as u, homePackage as ut, unreleasedChangeRule as v, mapText as vt, scriptsOf as w, gateTrigger as wt, trustPolicy as x, HOME_EXPORTS as xt, IGNORE_AFTER as y, mergeHomes as yt, roadmapOfLine as z, readJsonc as zt };
|
|
10913
11319
|
|
|
10914
|
-
//# sourceMappingURL=run-
|
|
11320
|
+
//# sourceMappingURL=run-D8BNQq3y.js.map
|