@mark1russell7/conventions 0.29.4 → 0.31.0

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.
@@ -8928,118 +8928,6 @@ const pagesSite = {
8928
8928
  }];
8929
8929
  }
8930
8930
  };
8931
- // src/rules/pinned-git-deps.ts
8932
- /**
8933
- * The rule `pinned-git-deps`: a dependency from git names a full commit.
8934
- */
8935
- /** The fields of the root `package.json` that replace the specifiers of dependencies. */
8936
- const OVERRIDE_FIELDS = ["overrides", "resolutions"];
8937
- /** This function tells if a specifier gets the package from git, not from a registry or the workspace. */
8938
- function isGitSpecifier(spec) {
8939
- const value = spec.trim();
8940
- if (/^(github|gitlab|bitbucket|gist):/i.test(value)) return true;
8941
- if (/^git(\+[a-z]+)?:/i.test(value) || /^git@/i.test(value)) return true;
8942
- if (/^https?:\/\/(www\.)?(github\.com|gitlab\.com|bitbucket\.org|codeload\.github\.com)\//i.test(value)) return true;
8943
- return /^[\w-][\w.-]*\/[\w.-]+(#.*)?$/.test(value) && !value.startsWith("@");
8944
- }
8945
- /**
8946
- * This function tells if a git specifier names a commit. A specifier names a commit when its ref
8947
- * (after `#`) is a commit SHA, or when a tarball URL has the SHA in its path.
8948
- */
8949
- function isPinned(spec, fullSha) {
8950
- const sha = fullSha ? /^[0-9a-f]{40}$/i : /^[0-9a-f]{7,40}$/i;
8951
- const hash = spec.indexOf("#");
8952
- if (hash >= 0) return spec.slice(hash + 1).split("&").some((part) => sha.test(part.replace(/^commit=/, "")));
8953
- const path = /^https?:\/\/[^/]+\/(.*)$/i.exec(spec.trim())?.[1];
8954
- return path !== void 0 && path.split(/[/.]/).some((part) => sha.test(part));
8955
- }
8956
- /** This function gives the specifiers of the fields of overrides, also the field `overrides` of `pnpm`. */
8957
- function overridesOf(manifest) {
8958
- const out = [];
8959
- for (const field of OVERRIDE_FIELDS) for (const [name, spec] of specifiersOf(manifest, field)) out.push([
8960
- field,
8961
- name,
8962
- spec
8963
- ]);
8964
- const pnpm = manifest["pnpm"];
8965
- if (typeof pnpm === "object" && pnpm !== null) for (const [name, spec] of specifiersOf(pnpm, "overrides")) out.push([
8966
- "pnpm",
8967
- name,
8968
- spec
8969
- ]);
8970
- return out;
8971
- }
8972
- const pinnedGitDeps = {
8973
- id: "pinned-git-deps",
8974
- title: "A dependency from git (github:, git+https: or owner/repo) names a full commit SHA.",
8975
- reason: "A git ref without a commit moves with the branch. Then an install today and an install tomorrow get different code, and the lockfile hides the change.",
8976
- fix: "Use the npm version, `workspace:*` for a package of this repository, or `github:owner/repo#<full commit SHA>`.",
8977
- sources: [
8978
- {
8979
- repo: "coeval",
8980
- rule: "pinned-deps",
8981
- doc: "CLAUDE.md:41"
8982
- },
8983
- {
8984
- repo: "coeval",
8985
- rule: "unpublished-dep-pinned",
8986
- doc: "CLAUDE.md:41"
8987
- },
8988
- {
8989
- repo: "headroom",
8990
- rule: "non-npm-deps-pinned",
8991
- doc: "CLAUDE.md:38"
8992
- },
8993
- {
8994
- repo: "headroom",
8995
- rule: "pinned-github-specifier",
8996
- doc: "CLAUDE.md:38"
8997
- },
8998
- {
8999
- repo: "private",
9000
- rule: "github-dep-full-sha",
9001
- doc: "docs/decisions.md:1384"
9002
- },
9003
- {
9004
- repo: "private",
9005
- rule: "github-dep-pinned",
9006
- doc: "docs/decisions.md:1384"
9007
- },
9008
- {
9009
- repo: "client",
9010
- rule: "general-npm-version",
9011
- doc: "CLAUDE.md:54"
9012
- }
9013
- ],
9014
- options: { fullSha: {
9015
- type: "boolean",
9016
- default: true,
9017
- description: "When false, a short SHA of 7 or more characters is also a commit."
9018
- } },
9019
- check(context, options) {
9020
- const fullSha = options["fullSha"] !== false;
9021
- const breaks = [];
9022
- for (const info of [context.rootPackage, ...context.packages]) {
9023
- const found = [];
9024
- for (const field of DEPENDENCY_FIELDS) for (const [name, spec] of specifiersOf(info.manifest, field)) found.push([
9025
- field,
9026
- name,
9027
- spec
9028
- ]);
9029
- found.push(...overridesOf(info.manifest));
9030
- for (const [field, name, spec] of found) {
9031
- if (!isGitSpecifier(spec) || isPinned(spec, fullSha)) continue;
9032
- const line = keyLine(info.text, field, name);
9033
- breaks.push({
9034
- file: info.file,
9035
- ...line === void 0 ? {} : { line },
9036
- message: `${field} "${name}" is "${spec}": a git dependency without a ${fullSha ? "full " : ""}commit SHA.`
9037
- });
9038
- }
9039
- }
9040
- return breaks;
9041
- }
9042
- };
9043
8931
  // src/rules/push-main-only.ts
9044
8932
  /**
9045
8933
  * The rule `push-main-only`: a workflow that starts on `push` and on `pull_request` limits `push` to the default branch.
@@ -9047,7 +8935,7 @@ const pinnedGitDeps = {
9047
8935
  * can still start a run on a branch with no pull request.
9048
8936
  */
9049
8937
  /** The file of the release flow. A person changes it, with the rule `release-files`, so the fix does not write it. */
9050
- const RELEASE_FILE = "release.yml";
8938
+ const RELEASE_FILE$1 = "release.yml";
9051
8939
  /** The patterns that match each branch. */
9052
8940
  const EACH_BRANCH = /* @__PURE__ */ new Set(["*", "**"]);
9053
8941
  /** A key of a block, in the quoted forms too. */
@@ -9271,7 +9159,7 @@ function findBreak(text, facts) {
9271
9159
  }
9272
9160
  /** This function gives the reason why a person must change the workflow, or undefined when the fix can write it. */
9273
9161
  function refusal(file, text, finding, facts) {
9274
- if (file.slice(file.lastIndexOf("/") + 1) === RELEASE_FILE) return `${RELEASE_FILE} belongs to the release flow`;
9162
+ if (file.slice(file.lastIndexOf("/") + 1) === RELEASE_FILE$1) return `${RELEASE_FILE$1} belongs to the release flow`;
9275
9163
  const { triggers, filters, wide } = finding;
9276
9164
  if (triggers.form === "map") return "on has the flow form of a map";
9277
9165
  if (triggers.end > triggers.on + 1) return "on is a flow value of more than one line";
@@ -9438,1045 +9326,1547 @@ const pushMainOnly = {
9438
9326
  return breaks;
9439
9327
  }
9440
9328
  };
9441
- // src/rules/unreleased-change.ts
9329
+ // src/rules/runner-budget.ts
9442
9330
  /**
9443
- * The rule `unreleased-change`: a change does not set a version that npm has. With the option `versionEachChange`, a
9444
- * change of the files that a published package ships also raises its version. Else the release skips the change.
9331
+ * The rule `runner-budget`: the workflows share the runners of the account. Each matrix has a `max-parallel`, each
9332
+ * workflow has a concurrency group, and each schedule starts at the minute of its repository and file.
9445
9333
  */
9446
- /** The registry of npm. */
9447
- const NPM_REGISTRY = "https://registry.npmjs.org";
9448
- /** The globs of the files of a package, relative to its folder, that do not ship: tests, fixtures, docs and configs. */
9449
- const UNSHIPPED_FILES = [
9450
- "**/*.md",
9451
- "**/*.{test,spec}.*",
9452
- "**/{test,tests,__tests__,fixtures,__fixtures__,__snapshots__,bench,benches,benchmarks,e2e}/**",
9453
- "**/*.{bench,e2e}.*",
9454
- "**/.*/**",
9455
- "**/tsconfig*.json",
9456
- "**/*.config.*",
9457
- "docs/**",
9458
- "examples/**",
9459
- "scripts/**",
9460
- "site/**",
9461
- "LICENSE*",
9462
- "pnpm-lock.yaml",
9463
- "pnpm-workspace.yaml"
9464
- ];
9465
- /** The fields of `package.json` that change what the package gives to a user. A change of the dependencies is not here. */
9466
- const SHIPPED_FIELDS = [
9467
- "main",
9468
- "module",
9469
- "types",
9470
- "typings",
9471
- "exports",
9472
- "imports",
9473
- "bin",
9474
- "files",
9475
- "type",
9476
- "publishConfig",
9477
- "sideEffects",
9478
- "browser"
9479
- ];
9480
- /** The script that `npmLookup` starts in a child process of Node, so that the rule stays synchronous. */
9481
- const LOOKUP_SCRIPT = `
9482
- const [registry, ...names] = process.argv.slice(1);
9483
- let base = registry;
9484
- while (base.endsWith("/")) base = base.slice(0, -1);
9485
- Promise.all(names.map(async (name) => {
9486
- try {
9487
- const response = await fetch(base + "/" + name.replace("/", "%2f"), { headers: { accept: "application/json" }, signal: AbortSignal.timeout(20000) });
9488
- if (response.status === 404) return [name, { versions: [] }];
9489
- if (!response.ok) return [name, { error: "HTTP " + response.status }];
9490
- const data = await response.json();
9491
- const times = Object.fromEntries(Object.entries(data.time ?? {}).filter(([key]) => key !== "created" && key !== "modified"));
9492
- return [name, { versions: [...new Set([...Object.keys(data.versions ?? {}), ...Object.keys(times)])], times, latest: data["dist-tags"]?.latest }];
9493
- } catch (error) {
9494
- return [name, { error: String(error && error.message ? error.message : error) }];
9495
- }
9496
- })).then((entries) => process.stdout.write(JSON.stringify(Object.fromEntries(entries))));
9497
- `;
9498
9334
  /**
9499
- * This function asks the registry for the versions of each package, in one child process of Node. A version that npm
9500
- * removed stays in the answer, because npm does not accept it again.
9335
+ * This function gives the minute (1 to 59) of the schedules of a workflow: the FNV-1a hash of the repository and the
9336
+ * file. Two repositories with the same workflow thus start at different minutes, and no schedule starts at minute 0,
9337
+ * where GitHub has the most load.
9501
9338
  */
9502
- const npmLookup = (names, registry) => {
9503
- const fail = (error) => new Map(names.map((name) => [name, { error }]));
9504
- if (names.length === 0) return /* @__PURE__ */ new Map();
9505
- const result = spawnSync(process.execPath, [
9506
- "-e",
9507
- LOOKUP_SCRIPT,
9508
- registry,
9509
- ...names
9510
- ], {
9511
- encoding: "utf8",
9512
- timeout: 6e4,
9513
- windowsHide: true
9514
- });
9515
- if (result.error !== void 0 || result.status !== 0) return fail(result.error?.message ?? `the lookup ended with exit code ${String(result.status)}`);
9516
- try {
9517
- const answers = JSON.parse(result.stdout);
9518
- return new Map(names.map((name) => [name, answers[name] ?? { error: "no answer" }]));
9519
- } catch {
9520
- return fail("the lookup gave no JSON");
9521
- }
9522
- };
9523
- /** This function gives the strings of a field of `package.json` that is a list of strings. */
9524
- const stringsOf = (manifest, field) => {
9525
- const value = manifest[field];
9526
- return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
9527
- };
9528
- /** This function tells if a path relative to the root is in the folder `folder`. The root is `""`. */
9529
- const inside = (folder, path) => folder === "" || path.startsWith(`${folder}/`);
9530
- /** This function gives the globs of an entry of the field `files`: the entry, and each path under it. */
9531
- const entryGlobs = (entry) => {
9532
- let glob = cleanPath(entry);
9533
- while (glob.endsWith("/")) glob = glob.slice(0, -1);
9534
- return [glob, `${glob}/**`];
9535
- };
9536
- /** This function reads the manifest of the text of a `package.json` file, or gives undefined. */
9537
- function parseManifest(text) {
9538
- if (text === void 0) return void 0;
9539
- try {
9540
- const parsed = JSON.parse(text);
9541
- return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : void 0;
9542
- } catch {
9543
- return;
9339
+ function scheduleMinute(repository, file) {
9340
+ let hash = 2166136261;
9341
+ for (const char of `${repository.toLowerCase()}/${file}`) {
9342
+ hash ^= char.codePointAt(0) ?? 0;
9343
+ hash = Math.imul(hash, 16777619) >>> 0;
9544
9344
  }
9345
+ return hash % 59 + 1;
9545
9346
  }
9546
- /** This function tells if a version is a placeholder before the first release: `0.0.0` or `0.0.0-<stage>`. */
9547
- const isPlaceholder = (version) => /^0\.0\.0(?:[-+].*)?$/.test(version);
9548
- /** The published packages of the repository: the root package and the code packages that are not private and have a name and a version. */
9549
- function publishedOf(context) {
9550
- const all = [context.rootPackage, ...codePackages(context)];
9551
- return all.filter((pkg, index) => all.findIndex((other) => other.file === pkg.file) === index).filter((pkg) => pkg.manifest["private"] !== true && typeof pkg.manifest["name"] === "string" && typeof pkg.manifest["version"] === "string");
9552
- }
9553
- /** This function gives the time of the push in milliseconds, from the field `repository.pushed_at` of the event file. */
9554
- function pushedAt(context) {
9555
- const file = context.env["GITHUB_EVENT_PATH"];
9556
- if (file === void 0 || file === "" || !existsSync(file)) return void 0;
9557
- try {
9558
- const value = JSON.parse(readFileSync(file, "utf8")).repository?.pushed_at;
9559
- if (typeof value === "number") return value * 1e3;
9560
- return typeof value === "string" && !Number.isNaN(Date.parse(value)) ? Date.parse(value) : void 0;
9561
- } catch {
9562
- return;
9347
+ /** This function gives `owner/name` from a git remote URL, or undefined for a URL that is not of GitHub. */
9348
+ function repositoryOfRemote(url) {
9349
+ const text = url.trim();
9350
+ for (const prefix of [
9351
+ "git@github.com:",
9352
+ "ssh://git@github.com/",
9353
+ "https://github.com/",
9354
+ "http://github.com/",
9355
+ "git+https://github.com/"
9356
+ ]) {
9357
+ if (!text.startsWith(prefix)) continue;
9358
+ let rest = text.slice(prefix.length);
9359
+ if (rest.endsWith("/")) rest = rest.slice(0, -1);
9360
+ if (rest.endsWith(".git")) rest = rest.slice(0, -4);
9361
+ const parts = rest.split("/");
9362
+ return parts.length === 2 && parts.every((part) => part !== "") ? rest : void 0;
9563
9363
  }
9564
9364
  }
9565
- /** This function gives the shipped files of `pkg` in the list `changed`, relative to the folder of the package. */
9566
- function shippedFiles(pkg, changed, before, context, unshipped, fields) {
9567
- const folders = context.packages.map((other) => other.folder).filter((folder) => folder !== "");
9568
- const own = (path) => inside(pkg.folder, path) && (pkg.folder !== "" || !folders.some((folder) => inside(folder, path)));
9569
- const relative = (path) => pkg.folder === "" ? path : path.slice(pkg.folder.length + 1);
9570
- const entries = stringsOf(pkg.manifest, "files");
9571
- const positive = entries.filter((entry) => !entry.startsWith("!"));
9572
- const negative = entries.filter((entry) => entry.startsWith("!")).flatMap((entry) => entryGlobs(entry.slice(1)));
9573
- const ownTracked = (context.gitFiles() ?? []).filter(own).map(relative);
9574
- const whitelist = positive.length > 0 && positive.every((entry) => ownTracked.some((path) => matchesAny(path, entryGlobs(entry))));
9575
- const ships = (path) => path !== "package.json" && !matchesAny(path, unshipped) && (!whitelist || positive.some((entry) => matchesAny(path, entryGlobs(entry))) && !matchesAny(path, negative));
9576
- const files = changed.filter(own).map(relative).filter(ships);
9577
- if (changed.includes(pkg.file) && before !== void 0 && fields.some((field) => JSON.stringify(before[field]) !== JSON.stringify(pkg.manifest[field]))) files.push("package.json");
9578
- return files;
9365
+ /** This function tells if a workflow is a shared workflow (`on: workflow_call`). Its caller gives the concurrency group. */
9366
+ function isShared(lines) {
9367
+ return lines.some((line) => {
9368
+ const text = line.trimStart();
9369
+ return text.startsWith("workflow_call:") || text === "workflow_call" || text === "- workflow_call" || text.startsWith("on:") && text.includes("workflow_call");
9370
+ });
9579
9371
  }
9580
- /** This function makes the rule with the registry lookup `lookup`. The tests give a fake lookup. */
9581
- function unreleasedChangeRule(lookup = npmLookup) {
9582
- return {
9583
- id: "unreleased-change",
9584
- changeScoped: true,
9585
- title: "A change does not set a version that npm has. With `versionEachChange`, a change of the shipped files also raises the version.",
9586
- reason: "The release workflow publishes each version that npm does not have, and it skips the others. When two pull requests set the same version, the second merge changes the code but no version, and nothing fails (rigor #18 and #20, 2026-11-02).",
9587
- fix: "Raise the version of the package in a pull request to a version that npm does not have, with the SemVer rules (RELEASING.md). Then the release workflow publishes the change.",
9588
- sources: [{
9589
- repo: "rigor",
9590
- rule: "unreleased-change",
9591
- doc: "pull requests #18 and #20 (2026-11-02): two pull requests set the same version"
9592
- }, ...[
9593
- "crawler",
9594
- "coeval",
9595
- "template"
9596
- ].map((repo) => ({
9597
- repo,
9598
- rule: "unreleased-change",
9599
- doc: ".github/workflows/release.yml (it starts on a change of a version, and it skips each version that npm has)"
9600
- }))],
9601
- options: {
9602
- versionEachChange: {
9603
- type: "boolean",
9604
- default: false,
9605
- description: "True when each pull request sets its version: a change of the shipped files with a version that npm has breaks, also on a push. False when a separate pull request raises the version."
9606
- },
9607
- unshipped: {
9608
- type: "strings",
9609
- default: UNSHIPPED_FILES,
9610
- description: "With `versionEachChange`: the globs of the files of a package, relative to its folder, that do not ship."
9611
- },
9612
- fields: {
9613
- type: "strings",
9614
- default: SHIPPED_FIELDS,
9615
- description: "With `versionEachChange`: the fields of `package.json` whose change ships. The dependencies are not in the default list."
9616
- },
9617
- registry: {
9618
- type: "string",
9619
- default: NPM_REGISTRY,
9620
- description: "The URL of the registry that has the versions."
9621
- }
9622
- },
9623
- check(context, options) {
9624
- if (hasFile(context.root, ".changeset/config.json")) return { skipped: "the repository uses Changesets: the changesets raise the versions, and the changeset check examines them" };
9625
- const published = publishedOf(context).filter((pkg) => !isPlaceholder(String(pkg.manifest["version"])));
9626
- if (published.length === 0) return { skipped: "the repository has no published package with a release version" };
9627
- const range = rangeOf(context, { push: true });
9628
- if ("skipped" in range) return range;
9629
- const strict = options["versionEachChange"] === true;
9630
- const push = context.base === void 0 && context.env["GITHUB_EVENT_NAME"] === "push";
9631
- const out = strict ? context.git([
9632
- "diff",
9633
- "--name-only",
9634
- "--no-renames",
9635
- ...range.diff
9636
- ]) : "";
9637
- if (out === void 0) return { skipped: "git cannot give the changed files of the change" };
9638
- const changed = out.split(/\r?\n/).filter((file) => file !== "");
9639
- const unshipped = Array.isArray(options["unshipped"]) ? options["unshipped"] : UNSHIPPED_FILES;
9640
- const fields = Array.isArray(options["fields"]) ? options["fields"] : SHIPPED_FIELDS;
9641
- const registry = typeof options["registry"] === "string" ? options["registry"] : NPM_REGISTRY;
9642
- const fork = push ? range.ends[0] : context.git(["merge-base", ...range.ends])?.trim();
9643
- const notes = [];
9644
- if (fork === void 0) notes.push(`the checkout does not have the merge base of ${range.ends.join(" and ")}, so the rule cannot tell if the change sets a version`);
9645
- const manifestAt = (ref, pkg) => ref === "HEAD" ? pkg.manifest : parseManifest(context.git(["show", `${ref}:${pkg.file}`]));
9646
- const versionOf = (manifest) => typeof manifest?.["version"] === "string" ? manifest["version"] : void 0;
9647
- const candidates = [];
9648
- for (const pkg of published) {
9649
- const atStart = manifestAt(range.ends[0], pkg);
9650
- const set = versionOf(manifestAt(range.ends[1], pkg));
9651
- const before = fork === void 0 ? void 0 : versionOf(fork === range.ends[0] ? atStart : manifestAt(fork, pkg));
9652
- const sets = fork !== void 0 && set !== void 0 && !isPlaceholder(set) && set !== before ? set : void 0;
9653
- const files = strict ? shippedFiles(pkg, changed, atStart, context, unshipped, fields) : [];
9654
- if (sets === void 0 && files.length === 0) continue;
9655
- candidates.push({
9656
- pkg,
9657
- name: String(pkg.manifest["name"]),
9658
- version: String(pkg.manifest["version"]),
9659
- sets,
9660
- start: versionOf(atStart),
9661
- files
9662
- });
9663
- }
9664
- if (candidates.length === 0) return notes.length > 0 ? { skipped: notes.join("; ") } : [];
9665
- const answers = lookup(candidates.map((candidate) => candidate.name), registry);
9666
- const pushTime = push ? pushedAt(context) : void 0;
9667
- const breaks = [];
9668
- for (const candidate of candidates) {
9669
- const answer = answers.get(candidate.name) ?? { error: "no answer" };
9670
- if ("error" in answer) {
9671
- notes.push(`the registry did not answer for ${candidate.name}: ${answer.error}`);
9672
- continue;
9673
- }
9674
- const line = lineOf(candidate.pkg.text, "\"version\"");
9675
- const at = {
9676
- file: candidate.pkg.file,
9677
- ...line === void 0 ? {} : { line }
9678
- };
9679
- if (candidate.sets !== void 0) {
9680
- const sets = candidate.sets;
9681
- if (!answer.versions.includes(sets)) continue;
9682
- if (push) {
9683
- const time = Date.parse(answer.times?.[sets] ?? "");
9684
- if (pushTime === void 0 || Number.isNaN(time)) {
9685
- notes.push(`the rule cannot tell if npm had ${candidate.name}@${sets} before the push`);
9686
- continue;
9687
- }
9688
- if (time >= pushTime) continue;
9689
- }
9690
- breaks.push({
9691
- ...at,
9692
- message: `${candidate.name}: the change sets the version ${sets}, but ${sets} is on npm already. Raise the version (SemVer) in a pull request.`
9693
- });
9694
- } else if (strict && candidate.files.length > 0 && candidate.start === candidate.version && answer.versions.includes(candidate.version)) {
9695
- const shown = candidate.files.slice(0, 3).map((file) => candidate.pkg.folder === "" ? file : `${candidate.pkg.folder}/${file}`);
9696
- const more = candidate.files.length > shown.length ? ` and ${String(candidate.files.length - shown.length)} more` : "";
9697
- breaks.push({
9698
- ...at,
9699
- message: `${candidate.name}: the change is not released, because ${candidate.version} is on npm already. Raise the version (SemVer) in a pull request. The change ships ${shown.join(", ")}${more}.`
9700
- });
9701
- }
9702
- }
9703
- if (breaks.length === 0 && notes.length > 0) return { skipped: notes.join("; ") };
9704
- return breaks;
9705
- }
9706
- };
9372
+ /** This function gives the jobs of a workflow. */
9373
+ function jobsOf(lines) {
9374
+ const jobs = lines.findIndex((line) => indentOf$1(line) === 0 && line.startsWith("jobs:"));
9375
+ if (jobs < 0) return [];
9376
+ const jobIndent = childIndent(lines, jobs);
9377
+ const end = blockEnd(lines, jobs);
9378
+ const found = [];
9379
+ for (let i = jobs + 1; i < end; i++) {
9380
+ const line = lines[i] ?? "";
9381
+ if (line.trim() === "" || indentOf$1(line) !== jobIndent) continue;
9382
+ const keyIndent = childIndent(lines, i);
9383
+ const keys = lines.slice(i + 1, blockEnd(lines, i)).filter((text) => indentOf$1(text) === keyIndent);
9384
+ const uses = keys.map((text) => keyValue(text, "uses")).find((value) => value !== void 0);
9385
+ const at = uses === void 0 ? -1 : uses.indexOf(".github/workflows/");
9386
+ const calls = uses === void 0 || at < 0 ? void 0 : uses.slice(at + 18).split("@")[0] ?? "";
9387
+ found.push({
9388
+ name: line.trim().replace(/:$/, ""),
9389
+ line: i + 1,
9390
+ grouped: keys.some((text) => keyValue(text, "concurrency") !== void 0),
9391
+ ...calls === void 0 ? {} : { calls }
9392
+ });
9393
+ }
9394
+ return found;
9707
9395
  }
9708
- const unreleasedChange = unreleasedChangeRule();
9709
- // src/rules/published-minor.ts
9396
+ const hasTopGroup = (lines) => lines.some((line) => indentOf$1(line) === 0 && line.startsWith("concurrency:"));
9710
9397
  /**
9711
- * The rule `published-minor`: a consumer does not stay behind the newest published minor of a package that the option
9712
- * `packages` names. A caret range of a `0.x` version cannot reach the next minor, so such a consumer stays behind with
9713
- * no failure. The lockfile can also hold an old version that the range admits.
9398
+ * This function gives the edit that adds a concurrency group at the top of a workflow, before `jobs:`. A new run of a pull
9399
+ * request stops the old run. A run of another event has the group of its commit, so that no release or scheduled run stops.
9714
9400
  */
9715
- /** This function gives the major and the minor of a release version, or undefined for a pre-release and for other text. */
9716
- function minorOf(version) {
9717
- const release = version.trim().split("(", 1)[0]?.split("+", 1)[0] ?? "";
9718
- const match = /^(\d+)\.(\d+)\.\d+$/.exec(release);
9719
- return match === null ? void 0 : [Number(match[1]), Number(match[2])];
9401
+ function groupEdits(file, text, lines) {
9402
+ const jobs = lines.findIndex((line) => indentOf$1(line) === 0 && line.startsWith("jobs:"));
9403
+ if (jobs < 0) return [];
9404
+ const pad = " ".repeat(childIndent(lines, jobs) ?? 2);
9405
+ const original = text.split(/\r?\n/)[jobs] ?? "jobs:";
9406
+ const group = [
9407
+ "concurrency:",
9408
+ pad + "group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.ref || github.sha }}",
9409
+ pad + "cancel-in-progress: ${{ github.event_name == 'pull_request' }}",
9410
+ "",
9411
+ original
9412
+ ];
9413
+ return [{
9414
+ file,
9415
+ before: text,
9416
+ after: replaceLine(text, jobs + 1, group)
9417
+ }];
9720
9418
  }
9721
9419
  /**
9722
- * This function gives the highest minor that a range can reach. It gives undefined for a form that the rule does not read.
9723
- * These forms are a `workspace:` or `github:` specifier, a tag, a partial version and a compound range. Below `1.0.0`, a caret stays in
9724
- * its minor. From `1.0.0`, a caret reaches each minor of its major.
9420
+ * This function gives the breaks of the concurrency groups. A workflow with no group at the top needs one in each job.
9421
+ * A job that calls a shared workflow of `grouped` gets its group from the jobs of that workflow. A shared workflow gets
9422
+ * its group from its caller, but a shared workflow of `grouped` has a group in each job.
9725
9423
  */
9726
- function reachOf(specifier) {
9727
- const match = /^([\^~]?)(\d+)\.(\d+)\.\d+(?:[-+].*)?$/.exec(specifier.trim());
9728
- if (match === null) return void 0;
9729
- const major = Number(match[2]);
9730
- return match[1] === "^" && major > 0 ? [major, Number.POSITIVE_INFINITY] : [major, Number(match[3])];
9731
- }
9732
- /** This function tells if the minor `have` is before the minor `other`. */
9733
- const behind = (have, other) => have[0] < other[0] || have[0] === other[0] && have[1] < other[1];
9734
- /** This function gives the indent, the key and the value of one line of YAML. It cuts the line by position, with no pattern. */
9735
- function yamlEntry(line) {
9736
- const text = line.trimEnd();
9737
- const body = text.trimStart();
9738
- const colon = body.indexOf(": ");
9739
- const key = colon >= 0 ? body.slice(0, colon) : body.endsWith(":") ? body.slice(0, -1) : "";
9740
- return key === "" ? void 0 : {
9741
- indent: text.length - body.length,
9742
- key,
9743
- value: colon >= 0 ? body.slice(colon + 2) : ""
9744
- };
9424
+ function concurrencyBreaks(file, text, lines, grouped) {
9425
+ const name = file.slice(file.lastIndexOf("/") + 1);
9426
+ const jobs = jobsOf(lines);
9427
+ if (isShared(lines)) {
9428
+ if (!grouped.includes(name)) return [];
9429
+ return jobs.filter((job) => !job.grouped).map((job) => ({
9430
+ file,
9431
+ line: job.line,
9432
+ message: `${file}: the job ${job.name} has no concurrency group, and its callers rely on it (the option grouped).`
9433
+ }));
9434
+ }
9435
+ if (hasTopGroup(lines)) return [];
9436
+ const missing = jobs.filter((job) => !job.grouped && !(job.calls !== void 0 && grouped.includes(job.calls)));
9437
+ const edits = missing.length === 0 ? [] : groupEdits(file, text, lines);
9438
+ return missing.map((job) => ({
9439
+ file,
9440
+ line: job.line,
9441
+ message: `${file}: the job ${job.name} has no concurrency group, and the workflow has none.`,
9442
+ edits
9443
+ }));
9745
9444
  }
9746
- /**
9747
- * This function gives the locked version of each dependency of each importer of the text of a `pnpm-lock.yaml` file. The
9748
- * key of the outer map is the folder of the importer, with `""` for the root.
9749
- */
9750
- function lockedVersions(text) {
9751
- const importers = /* @__PURE__ */ new Map();
9752
- let inside = false;
9753
- let importer;
9754
- let name;
9755
- for (const line of text.split(/\r?\n/)) {
9756
- if (/^\S/.test(line)) inside = line.trimEnd() === "importers:";
9757
- if (!inside) continue;
9758
- const entry = yamlEntry(line);
9759
- if (entry === void 0) continue;
9760
- const { indent, value } = entry;
9761
- const key = entry.key.replace(/^['"]|['"]$/g, "");
9762
- if (indent === 2) {
9763
- importer = /* @__PURE__ */ new Map();
9764
- importers.set(key === "." ? "" : key, importer);
9765
- } else if (indent === 6) name = key;
9766
- else if (indent === 8 && key === "version" && name !== void 0) importer?.set(name, value);
9767
- }
9768
- return importers;
9769
- }
9770
- /** This function gives the time in milliseconds of the first release that `have` is behind, or undefined when npm gives no time. */
9771
- function firstAhead(answer, have) {
9772
- const times = Object.entries(answer.times ?? {}).flatMap(([version, time]) => {
9773
- const minor = minorOf(version);
9774
- return minor !== void 0 && behind(have, minor) && !Number.isNaN(Date.parse(time)) ? [Date.parse(time)] : [];
9445
+ /** This function gives the breaks of the matrices: each `strategy` with a `matrix` has a `max-parallel` of `limit` or less. */
9446
+ function matrixBreaks(file, text, lines, limit) {
9447
+ const breaks = [];
9448
+ const originals = text.split(/\r?\n/);
9449
+ lines.forEach((line, index) => {
9450
+ if (keyValue(line, "strategy") === void 0) return;
9451
+ const keyIndent = childIndent(lines, index);
9452
+ if (keyIndent === void 0) return;
9453
+ const keys = [];
9454
+ for (let i = index + 1; i < blockEnd(lines, index); i++) if ((lines[i] ?? "").trim() !== "" && indentOf$1(lines[i] ?? "") === keyIndent) keys.push(i);
9455
+ if (!keys.some((i) => keyValue(lines[i] ?? "", "matrix") !== void 0)) return;
9456
+ const at = keys.find((i) => keyValue(lines[i] ?? "", "max-parallel") !== void 0);
9457
+ const raw = at === void 0 ? void 0 : keyValue(lines[at] ?? "", "max-parallel");
9458
+ const value = raw === void 0 ? NaN : Number(raw);
9459
+ const wanted = `${" ".repeat(keyIndent)}max-parallel: ${String(limit)}`;
9460
+ if (at === void 0 || raw === void 0) {
9461
+ const after = replaceLine(text, index + 1, [originals[index] ?? line, wanted]);
9462
+ breaks.push({
9463
+ file,
9464
+ line: index + 1,
9465
+ message: `${file}: a matrix has no max-parallel.`,
9466
+ edits: [{
9467
+ file,
9468
+ before: text,
9469
+ after
9470
+ }]
9471
+ });
9472
+ } else if (!Number.isInteger(value) || value < 1 || value > limit) {
9473
+ const after = replaceLine(text, at + 1, [wanted]);
9474
+ breaks.push({
9475
+ file,
9476
+ line: index + 1,
9477
+ message: `${file}: a matrix has max-parallel ${raw}, and the most is ${String(limit)}.`,
9478
+ edits: [{
9479
+ file,
9480
+ before: text,
9481
+ after
9482
+ }]
9483
+ });
9484
+ }
9775
9485
  });
9776
- return times.length === 0 ? void 0 : Math.min(...times);
9486
+ return breaks;
9777
9487
  }
9778
- /** This function makes the rule with the registry lookup `lookup` and the clock `now`. The tests give fakes. */
9779
- function publishedMinorRule(lookup = npmLookup, now = Date.now) {
9780
- return {
9781
- id: "published-minor",
9782
- title: "A consumer does not stay behind the newest published minor of a package that the option `packages` names.",
9783
- reason: "A caret range of a 0.x version cannot reach the next minor, and a lockfile can hold an old version that a range admits. A test that holds the choices of today does not show it, so a consumer can stay behind for many releases with no failure.",
9784
- fix: "Raise the range of the dependency to the newest published minor, and update the lockfile. Read the changes of the release first.",
9785
- sources: [{
9786
- repo: "private",
9787
- rule: "published-minor",
9788
- doc: "docs/STRATEGY.md (2026-11-04, a consumer behind a published minor)"
9789
- }],
9790
- options: {
9791
- packages: {
9792
- type: "strings",
9793
- default: [],
9794
- description: "The patterns of the package names that the rule examines, for example `@scope/*`. With no pattern, the rule does not start."
9795
- },
9796
- graceDays: {
9797
- type: "number",
9798
- default: 0,
9799
- description: "The days that a consumer has, from the first publish of a minor that it does not have."
9800
- },
9801
- registry: {
9802
- type: "string",
9803
- default: NPM_REGISTRY,
9804
- description: "The URL of the registry that has the versions."
9805
- }
9488
+ /**
9489
+ * This function gives the minute field of a schedule that starts `perHour` times in each hour, at equal steps. One start is at
9490
+ * `minute`: `"18"` for 1, `"18,48"` for 2. The list is in the order of the numbers.
9491
+ */
9492
+ function minuteField(minute, perHour) {
9493
+ const step = 60 / perHour;
9494
+ return Array.from({ length: perHour }, (_, k) => (minute + k * step) % 60).sort((a, b) => a - b).join(",");
9495
+ }
9496
+ /** This function gives the number of starts in each hour of a minute field (`"*\/30"` or `"5,35"` give 2), or 1 when it cannot tell. */
9497
+ function startsPerHour(field) {
9498
+ const step = /^\*\/(\d+)$/.exec(field);
9499
+ const count = step ? 60 / Number(step[1]) : field.split(",").length;
9500
+ return Number.isInteger(count) && count >= 1 && 60 % count === 0 ? count : 1;
9501
+ }
9502
+ /**
9503
+ * This function gives the breaks of the schedules: the minute of each `cron` is the minute of the repository and the file. A
9504
+ * schedule that starts more than once in each hour starts at equal steps from that minute (`18,48` for each 30 minutes).
9505
+ */
9506
+ function cronBreaks(file, text, minute) {
9507
+ const breaks = [];
9508
+ const originals = text.split(/\r?\n/);
9509
+ for (const { line, cron: value } of cronLines(text)) {
9510
+ const fields = value.split(" ").filter((field) => field !== "");
9511
+ const wanted = minuteField(minute, startsPerHour(fields[0] ?? ""));
9512
+ if (fields[0] === wanted) continue;
9513
+ const expected = [wanted, ...fields.slice(1)].join(" ");
9514
+ const original = originals[line - 1] ?? "";
9515
+ const edits = original.includes(value) ? [{
9516
+ file,
9517
+ before: text,
9518
+ after: replaceLine(text, line, [original.replace(value, () => expected)])
9519
+ }] : [];
9520
+ breaks.push({
9521
+ file,
9522
+ line,
9523
+ message: `${file}: the schedule "${value}" starts at minute ${fields[0] ?? "?"}, and the minute of this repository and file is ${String(minute)}.`,
9524
+ fix: `cron: "${expected}"`,
9525
+ edits
9526
+ });
9527
+ }
9528
+ return breaks;
9529
+ }
9530
+ const runnerBudget = {
9531
+ id: "runner-budget",
9532
+ title: "Each matrix has a max-parallel of 3 or less, each workflow has a concurrency group, and each schedule starts at the minute that the repository and the file give.",
9533
+ 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.",
9534
+ 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.",
9535
+ sources: [{
9536
+ repo: "private",
9537
+ rule: "runner-slots",
9538
+ doc: "docs/STRATEGY.md (2026-10-30, the runner slots: a cap of 40, heavy work at most 28)"
9539
+ }],
9540
+ options: {
9541
+ maxParallel: {
9542
+ type: "number",
9543
+ default: 3,
9544
+ description: "The largest max-parallel of a matrix."
9806
9545
  },
9807
- check(context, options) {
9808
- const patterns = Array.isArray(options["packages"]) ? options["packages"] : [];
9809
- if (patterns.length === 0) return { skipped: "the option `packages` names no package" };
9810
- const all = [context.rootPackage, ...context.packages];
9811
- const consumers = all.filter((pkg, index) => all.findIndex((other) => other.file === pkg.file) === index);
9812
- const uses = [];
9813
- for (const pkg of consumers) for (const field of DEPENDENCY_FIELDS) for (const [name, specifier] of specifiersOf(pkg.manifest, field)) {
9814
- const reach = reachOf(specifier);
9815
- if (reach !== void 0 && matchesAny(name, patterns)) uses.push({
9816
- pkg,
9817
- field,
9818
- name,
9819
- reach
9820
- });
9546
+ minute: {
9547
+ type: "boolean",
9548
+ default: true,
9549
+ description: "When false, the rule does not examine the minute of the schedules."
9550
+ },
9551
+ grouped: {
9552
+ type: "strings",
9553
+ default: ["reusable-ai-review.yml", "reusable-codex-review.yml"],
9554
+ description: "The shared workflows that give a concurrency group in each of their jobs. A job that calls one needs no group of its own."
9555
+ }
9556
+ },
9557
+ check(context, options) {
9558
+ const files = context.gitFiles();
9559
+ if (files === void 0) return { skipped: "the root is not in a git repository" };
9560
+ const workflows = files.filter((path) => WORKFLOW$1.test(path)).sort(byCode);
9561
+ if (workflows.length === 0) return { skipped: "the repository has no workflow" };
9562
+ const remote = context.git([
9563
+ "remote",
9564
+ "get-url",
9565
+ "origin"
9566
+ ]);
9567
+ const repository = context.env["GITHUB_REPOSITORY"] ?? (remote === void 0 ? void 0 : repositoryOfRemote(remote));
9568
+ const limit = Number(options["maxParallel"]);
9569
+ const grouped = Array.isArray(options["grouped"]) ? options["grouped"] : [];
9570
+ const breaks = [];
9571
+ for (const file of workflows) {
9572
+ let text;
9573
+ try {
9574
+ text = readFileSync(join(context.root, file), "utf8");
9575
+ } catch {
9576
+ continue;
9821
9577
  }
9822
- if (uses.length === 0) return { skipped: "no dependency has a range and a name that the option `packages` names" };
9823
- const answers = lookup([...new Set(uses.map((use) => use.name))], typeof options["registry"] === "string" ? options["registry"] : NPM_REGISTRY);
9824
- const locked = hasFile(context.root, "pnpm-lock.yaml") ? lockedVersions(readFileSync(join(context.root, "pnpm-lock.yaml"), "utf8")) : /* @__PURE__ */ new Map();
9825
- const grace = (typeof options["graceDays"] === "number" ? options["graceDays"] : 0) * 864e5;
9826
- const breaks = [];
9827
- const notes = /* @__PURE__ */ new Set();
9828
- for (const { pkg, field, name, reach } of uses) {
9829
- const answer = answers.get(name) ?? { error: "no answer" };
9830
- if ("error" in answer) {
9831
- notes.add(`the registry did not answer for ${name}: ${answer.error}`);
9832
- continue;
9833
- }
9834
- const latest = answer.latest === void 0 ? void 0 : minorOf(answer.latest);
9835
- if (latest === void 0) continue;
9836
- const version = locked.get(pkg.folder)?.get(name);
9837
- const lockMinor = version === void 0 ? void 0 : minorOf(version);
9838
- const have = behind(reach, latest) ? reach : lockMinor;
9839
- if (have === void 0 || !behind(have, latest)) continue;
9840
- const since = firstAhead(answer, have);
9841
- if (grace > 0 && since !== void 0 && now() - since < grace) continue;
9842
- const line = keyLine(pkg.text, field, name);
9843
- const at = {
9844
- file: pkg.file,
9845
- ...line === void 0 ? {} : { line }
9846
- };
9847
- const message = have === reach ? `${name}: the range in ${field} cannot reach ${String(answer.latest)}, the newest version on npm. Raise the range.` : `${name}: the lockfile holds ${String(version)}, and npm has ${String(answer.latest)}. Update the lockfile.`;
9848
- breaks.push({
9849
- ...at,
9850
- message
9578
+ const lines = workflowLines(text);
9579
+ breaks.push(...matrixBreaks(file, text, lines, limit), ...concurrencyBreaks(file, text, lines, grouped));
9580
+ if (options["minute"] !== false) {
9581
+ if (cronLines(text).length > 0 && repository === void 0) breaks.push({
9582
+ file,
9583
+ message: `${file} has a schedule, and the rule cannot find the repository (GITHUB_REPOSITORY, or a GitHub URL of the remote origin).`
9851
9584
  });
9585
+ else if (repository !== void 0) breaks.push(...cronBreaks(file, text, scheduleMinute(repository, file)));
9852
9586
  }
9853
- if (breaks.length === 0 && notes.size > 0) return { skipped: [...notes].join("; ") };
9854
- return breaks;
9855
9587
  }
9856
- };
9857
- }
9858
- const publishedMinor = publishedMinorRule();
9859
- // src/rules/release-files.ts
9588
+ return breaks;
9589
+ }
9590
+ };
9591
+ // src/rules/pages-after-release.ts
9860
9592
  /**
9861
- * The rule `release-files`: a pull request changes a file of the release flow only with a reason
9862
- * that everyone can see.
9593
+ * The rule `pages-after-release`: a repository that publishes a package and deploys a site starts its Pages workflow
9594
+ * after each release, and each day. Without this, the Releases page is behind npm until the next push.
9863
9595
  */
9864
- /** This function gives the pull request of the event file of GitHub Actions. With no event file, the body is empty. */
9865
- function pullRequestOf(context) {
9866
- const file = context.env["GITHUB_EVENT_PATH"];
9867
- if (file === void 0 || file === "" || !existsSync(file)) return { body: "" };
9868
- try {
9869
- const event = JSON.parse(readFileSync(file, "utf8"));
9870
- const body = typeof event.pull_request?.body === "string" ? event.pull_request.body : "";
9871
- const commits = event.pull_request?.commits;
9872
- return typeof commits === "number" ? {
9873
- body,
9874
- commits
9875
- } : { body };
9876
- } catch {
9877
- return { body: "" };
9596
+ /** The file of the release flow. */
9597
+ const RELEASE_FILE = ".github/workflows/release.yml";
9598
+ /** The hour (UTC) of a daily build that the fix adds. */
9599
+ const DAILY_HOUR = 5;
9600
+ /** A job that deploys a site with its own steps, and not with the Pages workflow of the template. */
9601
+ const OWN_DEPLOY = /^\s*(?:-\s*)?uses:\s*["']?actions\/deploy-pages@/m;
9602
+ /** This function tells if a line is the key `on` at the top of a workflow. */
9603
+ const onKey = (line) => indentOf$1(line) === 0 && /^["']?on["']?\s*:/.test(line);
9604
+ /** This function gives the name of a workflow: its key `name` at the top of the file. */
9605
+ function workflowName(text) {
9606
+ for (const line of workflowLines(text)) {
9607
+ if (indentOf$1(line) !== 0) continue;
9608
+ const name = keyValue(line, "name");
9609
+ if (name !== void 0 && name !== "") return name;
9878
9610
  }
9879
9611
  }
9880
- /** This function escapes the special characters of a regular expression. */
9881
- const escape = (text) => text.replace(/[\\^$.|?*+()[\]{}]/g, "\\$&");
9882
- const releaseFiles = {
9883
- id: "release-files",
9884
- title: "A pull request changes `.github/workflows/release.yml` or `scripts/release/` only with a `Release-Edit: <reason>` line.",
9885
- reason: "The release flow publishes to npm with trusted publishing. A change of its files by a session that does not own the release can stop or break each release.",
9886
- fix: "Revert the change of the release files. When the owner asked for the change, add the line `Release-Edit: <reason>` to the last commit message or to the body of the pull request. A re-run of a job reads the body of the event that started the run, so after a change of the body, push a commit.",
9612
+ /** This function tells if a cron line starts on each day of each month. */
9613
+ function isDaily(cron) {
9614
+ const fields = cron.split(" ").filter((field) => field !== "");
9615
+ return fields.length === 5 && fields.slice(2).every((field) => field === "*");
9616
+ }
9617
+ /** This function gives the index of the key `name` under the key `on`, or undefined. */
9618
+ function triggerKey(lines, on, name) {
9619
+ return childKeys(lines, on).find((index) => keyValue(lines[index] ?? "", name) !== void 0);
9620
+ }
9621
+ /** This function gives the workflows that the trigger `workflow_run` names, or undefined when the rule cannot read them. */
9622
+ function runWorkflows(lines, on) {
9623
+ const run = triggerKey(lines, on, "workflow_run");
9624
+ if (run === void 0) return void 0;
9625
+ const at = childKeys(lines, run).find((index) => keyValue(lines[index] ?? "", "workflows") !== void 0);
9626
+ if (at === void 0) return void 0;
9627
+ const list = listItems(lines, at, keyValue(lines[at] ?? "", "workflows") ?? "");
9628
+ return list === void 0 ? void 0 : {
9629
+ at,
9630
+ items: list.items
9631
+ };
9632
+ }
9633
+ /** This function reads the two triggers of the text of a workflow. A form of `on` on one line has neither. */
9634
+ function pagesTriggers(text, release = "Release") {
9635
+ const lines = workflowLines(text);
9636
+ const on = lines.findIndex(onKey);
9637
+ const daily = cronLines(text).some(({ cron }) => isDaily(cron));
9638
+ if (on < 0) return {
9639
+ afterRelease: false,
9640
+ daily
9641
+ };
9642
+ return {
9643
+ afterRelease: runWorkflows(lines, on)?.items.includes(release) === true,
9644
+ daily
9645
+ };
9646
+ }
9647
+ /** This function gives the index after the last line with text of the block of the key at `index`. */
9648
+ function blockTextEnd(lines, index) {
9649
+ let end = blockEnd(lines, index);
9650
+ while (end > index + 1 && (lines[end - 1] ?? "").trim() === "") end -= 1;
9651
+ return end;
9652
+ }
9653
+ /** This function gives the text with the missing triggers, or undefined when the fix cannot write them. */
9654
+ function addPagesTriggers(text, facts) {
9655
+ const lines = workflowLines(text);
9656
+ const on = lines.findIndex(onKey);
9657
+ if (on < 0 || (keyValue(lines[on] ?? "", "on") ?? "") !== "") return void 0;
9658
+ const keys = childKeys(lines, on);
9659
+ const first = keys[0];
9660
+ if (first === void 0) return void 0;
9661
+ const pad = " ".repeat(indentOf$1(lines[first] ?? ""));
9662
+ const inner = `${pad} `;
9663
+ const splices = [];
9664
+ const found = pagesTriggers(text, facts.release);
9665
+ if (!found.afterRelease) {
9666
+ if (triggerKey(lines, on, "workflow_run") === void 0) {
9667
+ const after = triggerKey(lines, on, "push") ?? keys.at(-1) ?? first;
9668
+ splices.push({
9669
+ at: blockTextEnd(lines, after),
9670
+ remove: 0,
9671
+ insert: [
9672
+ `${pad}# After a release, so that the Releases page has the new version`,
9673
+ `${pad}workflow_run:`,
9674
+ `${inner}workflows: [${facts.release}]`,
9675
+ `${inner}types: [completed]`,
9676
+ `${inner}branches: [${facts.branch}]`
9677
+ ]
9678
+ });
9679
+ } else {
9680
+ const named = runWorkflows(lines, on);
9681
+ if (named === void 0) return void 0;
9682
+ if ((keyValue(lines[named.at] ?? "", "workflows") ?? "") === "") {
9683
+ const end = blockTextEnd(lines, named.at);
9684
+ splices.push({
9685
+ at: end,
9686
+ remove: 0,
9687
+ insert: [`${" ".repeat(indentOf$1(lines[end - 1] ?? ""))}- ${facts.release}`]
9688
+ });
9689
+ } else {
9690
+ const original = text.split(/\r?\n/)[named.at] ?? "";
9691
+ const close = original.indexOf("]");
9692
+ if (close < 0) return void 0;
9693
+ splices.push({
9694
+ at: named.at,
9695
+ remove: 1,
9696
+ insert: [`${original.slice(0, close)}, ${facts.release}${original.slice(close)}`]
9697
+ });
9698
+ }
9699
+ }
9700
+ }
9701
+ if (!found.daily) {
9702
+ if (facts.minute === void 0) return void 0;
9703
+ const cron = `"${String(facts.minute)} ${String(DAILY_HOUR)} * * *"`;
9704
+ const schedule = triggerKey(lines, on, "schedule");
9705
+ if (schedule === void 0) {
9706
+ const at = blockTextEnd(lines, keys.at(-1) ?? first);
9707
+ splices.push({
9708
+ at,
9709
+ remove: 0,
9710
+ insert: [
9711
+ `${pad}# Each day, in case a release fails after it publishes`,
9712
+ `${pad}schedule:`,
9713
+ `${inner}- cron: ${cron}`
9714
+ ]
9715
+ });
9716
+ } else {
9717
+ const end = blockTextEnd(lines, schedule);
9718
+ const indent = childIndent(lines, schedule) ?? indentOf$1(lines[schedule] ?? "") + 2;
9719
+ splices.push({
9720
+ at: end,
9721
+ remove: 0,
9722
+ insert: [`${" ".repeat(indent)}- cron: ${cron}`]
9723
+ });
9724
+ }
9725
+ }
9726
+ return applySplices(text, splices);
9727
+ }
9728
+ /** This function tells if the repository has a package that it publishes. */
9729
+ function publishes(context) {
9730
+ return [context.rootPackage, ...context.packages].some((info) => info.manifest["private"] !== true);
9731
+ }
9732
+ const pagesAfterRelease = {
9733
+ id: "pages-after-release",
9734
+ title: "A repository with a public package and a release workflow starts its Pages workflow after a release and on each day.",
9735
+ reason: "A release starts no Pages run, so a Releases page is behind npm until the next push. On 2026-11-04 four sites showed an older version than npm for this reason. A release can also fail after it publishes, and then only a daily build shows the version.",
9736
+ fix: "Add `workflow_run` with `workflows: [Release]`, `types: [completed]` and `branches: [<default branch>]` under `on`, and a daily `schedule` (CI.md, \"Pages\"). A workflow that deploys with its own steps also needs a condition that stops a run after a failed release.",
9887
9737
  sources: [
9888
9738
  {
9889
- repo: "coeval",
9890
- rule: "no-release-edit",
9891
- doc: "CLAUDE.md:40"
9892
- },
9893
- {
9894
- repo: "coeval",
9895
- rule: "no-release-edits",
9896
- doc: "CLAUDE.md:40"
9897
- },
9898
- {
9899
- repo: "crawler",
9900
- rule: "no-release-edit",
9901
- doc: "CLAUDE.md:80"
9902
- },
9903
- {
9904
- repo: "crawler",
9905
- rule: "no-release-edits",
9906
- doc: "CLAUDE.md:80"
9739
+ repo: "template",
9740
+ rule: "pages-after-release",
9741
+ doc: ".github/workflows/pages.yml (workflow_run of Release, and a schedule)"
9907
9742
  },
9908
9743
  {
9909
- repo: "headroom",
9910
- rule: "no-release-edits",
9911
- doc: "CLAUDE.md:37"
9744
+ repo: "packing",
9745
+ rule: "pages-after-release",
9746
+ doc: ".github/workflows/pages.yml (workflow_run of Release, and a schedule)"
9912
9747
  },
9913
9748
  {
9914
- repo: "headroom",
9915
- rule: "release-files-frozen",
9916
- doc: "CLAUDE.md:37"
9749
+ repo: "ireko",
9750
+ rule: "pages-after-release",
9751
+ doc: ".github/workflows/pages.yml (workflow_run of CI and Release, and a schedule)"
9917
9752
  }
9918
9753
  ],
9919
- options: {
9920
- paths: {
9921
- type: "strings",
9922
- default: [".github/workflows/release.yml", "scripts/release/**"],
9923
- description: "The globs of the files that the release flow owns."
9924
- },
9925
- trailer: {
9926
- type: "string",
9927
- default: "Release-Edit",
9928
- description: "The key of the line that gives the reason of a change."
9929
- },
9930
- authors: {
9931
- type: "strings",
9932
- default: ["mark1russell7-release-train[bot]"],
9933
- description: "The authors of the release flow. A change of the release files in commits of only these authors (the sync of the template) needs no reason."
9934
- }
9935
- },
9754
+ options: { workflows: {
9755
+ type: "strings",
9756
+ default: PAGES_WORKFLOWS,
9757
+ description: "The workflows that deploy a site, without the ref after `@`."
9758
+ } },
9936
9759
  check(context, options) {
9937
- const range = rangeOf(context);
9938
- if ("skipped" in range) return range;
9939
- const globs = Array.isArray(options["paths"]) ? options["paths"] : [];
9940
- const changed = (context.git([
9941
- "diff",
9942
- "--name-only",
9943
- ...range.diff
9944
- ]) ?? "").split(/\r?\n/).filter((file) => file !== "" && matchesAny(file, globs));
9945
- if (changed.length === 0) return [];
9946
- const trailer = typeof options["trailer"] === "string" ? options["trailer"] : "Release-Edit";
9947
- const line = new RegExp(`^${escape(trailer)}:[ \\t]*\\S`, "im");
9948
- const pullRequest = pullRequestOf(context);
9949
- if (line.test(pullRequest.body)) return [];
9950
- if (!(pullRequest.commits === 1 && context.git([
9951
- "rev-parse",
9952
- "--verify",
9953
- "--quiet",
9954
- `${range.ends[1]}^2`
9955
- ]) === void 0) && context.git(["merge-base", ...range.ends]) === void 0) throw new Error(`The checkout does not have the merge base of ${range.ends.join(" and ")}, so the rule cannot read each commit of the change. Use fetch-depth 0, or the CI of the template, which deepens the checkout of a pull request to its merge base.`);
9956
- const messages = context.git([
9957
- "log",
9958
- "--no-merges",
9959
- "--format=%B",
9960
- ...range.log
9961
- ]) ?? "";
9962
- if (line.test(messages)) return [];
9963
- const authors = new Set(Array.isArray(options["authors"]) ? options["authors"] : []);
9964
- const changers = (context.git([
9965
- "log",
9966
- "--no-merges",
9967
- "--format=%an",
9968
- ...range.log,
9969
- "--",
9970
- ...changed
9971
- ]) ?? "").split(/\r?\n/).filter((name) => name !== "");
9972
- if (changers.length > 0 && changers.every((name) => authors.has(name))) return [];
9973
- return changed.map((file) => ({
9974
- file,
9975
- message: `The change edits ${file}, a file of the release flow, with no "${trailer}: <reason>" line.`
9976
- }));
9760
+ const files = context.gitFiles();
9761
+ if (files === void 0) return { skipped: "the root is not in a git repository" };
9762
+ if (!files.includes(RELEASE_FILE) || !publishes(context)) return [];
9763
+ const read = (file) => readFileSync(join(context.root, file), "utf8");
9764
+ const release = workflowName(read(RELEASE_FILE)) ?? "Release";
9765
+ const remote = context.git([
9766
+ "remote",
9767
+ "get-url",
9768
+ "origin"
9769
+ ]);
9770
+ const repository = context.env["GITHUB_REPOSITORY"] ?? (remote === void 0 ? void 0 : repositoryOfRemote(remote));
9771
+ const breaks = [];
9772
+ for (const file of files.filter((path) => WORKFLOW$1.test(path)).sort(byCode)) {
9773
+ const text = read(file);
9774
+ const calls = pagesCalls(text, options["workflows"]).filter((call) => call.deploys);
9775
+ const own = calls.length === 0 && OWN_DEPLOY.test(workflowLines(text).join("\n")) && !/^\s*workflow_call\s*:/m.test(workflowLines(text).join("\n"));
9776
+ if (calls.length === 0 && !own) continue;
9777
+ const found = pagesTriggers(text, release);
9778
+ if (found.afterRelease && found.daily) continue;
9779
+ const message = `${file} deploys a site, and ${[...found.afterRelease ? [] : [`it does not start after the workflow ${release}`], ...found.daily ? [] : ["it has no schedule with a start on each day"]].join(", and ")}.`;
9780
+ const after = own ? void 0 : addPagesTriggers(text, {
9781
+ release,
9782
+ branch: defaultBranch(context),
9783
+ minute: repository === void 0 ? void 0 : scheduleMinute(repository, file)
9784
+ });
9785
+ const ok = after !== void 0 && after !== text && pagesTriggers(after, release).afterRelease && pagesTriggers(after, release).daily;
9786
+ breaks.push({
9787
+ file,
9788
+ line: 1,
9789
+ message,
9790
+ ...ok ? { edits: [{
9791
+ file,
9792
+ before: text,
9793
+ after
9794
+ }] } : own ? { fix: "A person must change it, because this workflow has its own steps. Add the triggers, and stop a run after a failed release with a condition on `github.event.workflow_run.conclusion`." } : {}
9795
+ });
9796
+ }
9797
+ return breaks;
9977
9798
  }
9978
9799
  };
9979
- // src/rules/required-scripts.ts
9800
+ // src/rules/pinned-git-deps.ts
9980
9801
  /**
9981
- * The rule `required-scripts`: the root `package.json` keeps the scripts that the shared CI starts.
9802
+ * The rule `pinned-git-deps`: a dependency from git names a full commit.
9982
9803
  */
9983
- /** The package of the STE linter. */
9984
- const STE_LINT = "@mark1russell7/ste-lint";
9985
- /** The configuration file of the STE linter. */
9986
- const STE_CONFIG = "ste.config.json";
9987
- /** The examples of the scripts that the fix shows. */
9988
- const EXAMPLES = {
9989
- "lint:ste": "ste-lint",
9990
- typecheck: "pnpm -r run typecheck"
9991
- };
9804
+ /** The fields of the root `package.json` that replace the specifiers of dependencies. */
9805
+ const OVERRIDE_FIELDS = ["overrides", "resolutions"];
9806
+ /** This function tells if a specifier gets the package from git, not from a registry or the workspace. */
9807
+ function isGitSpecifier(spec) {
9808
+ const value = spec.trim();
9809
+ if (/^(github|gitlab|bitbucket|gist):/i.test(value)) return true;
9810
+ if (/^git(\+[a-z]+)?:/i.test(value) || /^git@/i.test(value)) return true;
9811
+ if (/^https?:\/\/(www\.)?(github\.com|gitlab\.com|bitbucket\.org|codeload\.github\.com)\//i.test(value)) return true;
9812
+ return /^[\w-][\w.-]*\/[\w.-]+(#.*)?$/.test(value) && !value.startsWith("@");
9813
+ }
9992
9814
  /**
9993
- * This function tells if the repository uses the STE prose standard: the root `package.json` has a
9994
- * dependency on `@mark1russell7/ste-lint`, or the root has a `ste.config.json`.
9815
+ * This function tells if a git specifier names a commit. A specifier names a commit when its ref
9816
+ * (after `#`) is a commit SHA, or when a tarball URL has the SHA in its path.
9995
9817
  */
9996
- function usesSteLint(context) {
9997
- const manifest = context.rootPackage.manifest;
9998
- if (DEPENDENCY_FIELDS.some((field) => specifiersOf(manifest, field).some(([name]) => name === STE_LINT))) return true;
9999
- return hasFile(context.root, STE_CONFIG);
9818
+ function isPinned(spec, fullSha) {
9819
+ const sha = fullSha ? /^[0-9a-f]{40}$/i : /^[0-9a-f]{7,40}$/i;
9820
+ const hash = spec.indexOf("#");
9821
+ if (hash >= 0) return spec.slice(hash + 1).split("&").some((part) => sha.test(part.replace(/^commit=/, "")));
9822
+ const path = /^https?:\/\/[^/]+\/(.*)$/i.exec(spec.trim())?.[1];
9823
+ return path !== void 0 && path.split(/[/.]/).some((part) => sha.test(part));
10000
9824
  }
10001
- const requiredScripts = {
10002
- id: "required-scripts",
10003
- title: "The root `package.json` has the script `typecheck`, and also `lint:ste` when the repository uses `ste-lint`.",
10004
- reason: "The shared CI starts each script of its list that `package.json` has, and it skips the others. Thus a removed script turns its check off, and nothing shows it.",
10005
- fix: "Add the script, for example `\"lint:ste\": \"ste-lint\"` or `\"typecheck\": \"pnpm -r run typecheck\"`.",
9825
+ /** This function gives the specifiers of the fields of overrides, also the field `overrides` of `pnpm`. */
9826
+ function overridesOf(manifest) {
9827
+ const out = [];
9828
+ for (const field of OVERRIDE_FIELDS) for (const [name, spec] of specifiersOf(manifest, field)) out.push([
9829
+ field,
9830
+ name,
9831
+ spec
9832
+ ]);
9833
+ const pnpm = manifest["pnpm"];
9834
+ if (typeof pnpm === "object" && pnpm !== null) for (const [name, spec] of specifiersOf(pnpm, "overrides")) out.push([
9835
+ "pnpm",
9836
+ name,
9837
+ spec
9838
+ ]);
9839
+ return out;
9840
+ }
9841
+ const pinnedGitDeps = {
9842
+ id: "pinned-git-deps",
9843
+ title: "A dependency from git (github:, git+https: or owner/repo) names a full commit SHA.",
9844
+ reason: "A git ref without a commit moves with the branch. Then an install today and an install tomorrow get different code, and the lockfile hides the change.",
9845
+ fix: "Use the npm version, `workspace:*` for a package of this repository, or `github:owner/repo#<full commit SHA>`.",
10006
9846
  sources: [
10007
- {
10008
- repo: "client",
10009
- rule: "ste-prose",
10010
- doc: "CLAUDE.md:5"
10011
- },
10012
9847
  {
10013
9848
  repo: "coeval",
10014
- rule: "ste-prose",
10015
- doc: "CLAUDE.md:5"
10016
- },
10017
- {
10018
- repo: "crawler",
10019
- rule: "ste-prose",
10020
- doc: "CLAUDE.md:5"
9849
+ rule: "pinned-deps",
9850
+ doc: "CLAUDE.md:41"
10021
9851
  },
10022
9852
  {
10023
- repo: "private",
10024
- rule: "ste-prose",
10025
- doc: "CLAUDE.md:5"
9853
+ repo: "coeval",
9854
+ rule: "unpublished-dep-pinned",
9855
+ doc: "CLAUDE.md:41"
10026
9856
  },
10027
9857
  {
10028
9858
  repo: "headroom",
10029
- rule: "ste-prose",
10030
- doc: "CLAUDE.md:19"
10031
- },
10032
- {
10033
- repo: "systems",
10034
- rule: "lint-ste-in-ci",
10035
- doc: "CLAUDE.md:24"
9859
+ rule: "non-npm-deps-pinned",
9860
+ doc: "CLAUDE.md:38"
10036
9861
  },
10037
9862
  {
10038
- repo: "Vex",
10039
- rule: "ste-prose",
10040
- doc: "CLAUDE.md:5"
9863
+ repo: "headroom",
9864
+ rule: "pinned-github-specifier",
9865
+ doc: "CLAUDE.md:38"
10041
9866
  },
10042
9867
  {
10043
- repo: "coeval",
10044
- rule: "tsconfig-test",
10045
- doc: "CLAUDE.md:18"
9868
+ repo: "private",
9869
+ rule: "github-dep-full-sha",
9870
+ doc: "docs/decisions.md:1384"
10046
9871
  },
10047
9872
  {
10048
- repo: "crawler",
10049
- rule: "tsconfig-test",
10050
- doc: "CLAUDE.md:18"
9873
+ repo: "private",
9874
+ rule: "github-dep-pinned",
9875
+ doc: "docs/decisions.md:1384"
10051
9876
  },
10052
9877
  {
10053
- repo: "headroom",
10054
- rule: "tsconfig-test",
10055
- doc: "CLAUDE.md:32"
10056
- },
10057
- {
10058
- repo: "Vex",
10059
- rule: "tsconfig-test",
10060
- doc: "CLAUDE.md:23"
9878
+ repo: "client",
9879
+ rule: "general-npm-version",
9880
+ doc: "CLAUDE.md:54"
10061
9881
  }
10062
9882
  ],
10063
- options: {
10064
- scripts: {
10065
- type: "strings",
10066
- default: ["typecheck"],
10067
- description: "The scripts that the root `package.json` has."
10068
- },
10069
- steScripts: {
10070
- type: "strings",
10071
- default: ["lint:ste"],
10072
- description: "The scripts that the root `package.json` has when the repository uses `ste-lint` (a dependency on `@mark1russell7/ste-lint`, or a `ste.config.json` at the root)."
10073
- }
10074
- },
9883
+ options: { fullSha: {
9884
+ type: "boolean",
9885
+ default: true,
9886
+ description: "When false, a short SHA of 7 or more characters is also a commit."
9887
+ } },
10075
9888
  check(context, options) {
10076
- const always = Array.isArray(options["scripts"]) ? options["scripts"] : ["typecheck"];
10077
- const ste = Array.isArray(options["steScripts"]) ? options["steScripts"] : ["lint:ste"];
10078
- const wanted = [.../* @__PURE__ */ new Set([...always, ...usesSteLint(context) ? ste : []])];
10079
- const value = context.rootPackage.manifest["scripts"];
10080
- const scripts = typeof value === "object" && value !== null ? value : {};
10081
- const line = lineOf(context.rootPackage.text, "\"scripts\"");
10082
- return wanted.filter((name) => typeof scripts[name] !== "string" || scripts[name] === "").map((name) => {
10083
- const example = EXAMPLES[name];
10084
- const why = ste.includes(name) && !always.includes(name) ? " The repository uses ste-lint." : "";
10085
- return {
10086
- file: context.rootPackage.file,
10087
- ...line === void 0 ? {} : { line },
10088
- message: `The root package.json has no script "${name}".${why}`,
10089
- fix: example === void 0 ? `Add the script "${name}".` : `Add the script, for example "${name}": "${example}".`
10090
- };
10091
- });
9889
+ const fullSha = options["fullSha"] !== false;
9890
+ const breaks = [];
9891
+ for (const info of [context.rootPackage, ...context.packages]) {
9892
+ const found = [];
9893
+ for (const field of DEPENDENCY_FIELDS) for (const [name, spec] of specifiersOf(info.manifest, field)) found.push([
9894
+ field,
9895
+ name,
9896
+ spec
9897
+ ]);
9898
+ found.push(...overridesOf(info.manifest));
9899
+ for (const [field, name, spec] of found) {
9900
+ if (!isGitSpecifier(spec) || isPinned(spec, fullSha)) continue;
9901
+ const line = keyLine(info.text, field, name);
9902
+ breaks.push({
9903
+ file: info.file,
9904
+ ...line === void 0 ? {} : { line },
9905
+ message: `${field} "${name}" is "${spec}": a git dependency without a ${fullSha ? "full " : ""}commit SHA.`
9906
+ });
9907
+ }
9908
+ }
9909
+ return breaks;
10092
9910
  }
10093
9911
  };
10094
- // src/rules/roadmap-parses.ts
9912
+ // src/rules/pipe-fails.ts
10095
9913
  /**
10096
- * The rule `roadmap-parses`: each roadmap that a workflow gives to the Status page parses, on the pull request.
9914
+ * The rule `pipe-fails`: a failure on the left of a pipe fails its step. With no `shell` key, GitHub starts a step with
9915
+ * `bash -e {0}`, which has no `pipefail`. So `tests | tee out.txt` gives the exit code of `tee`, and the step passes when the tests fail.
9916
+ * The key `shell: bash` starts it with `bash --noprofile --norc -eo pipefail {0}`.
10097
9917
  */
10098
- /** A workflow file. */
10099
- const WORKFLOW = /^\.github\/workflows\/[^/]+\.ya?ml$/;
10100
- /** This function tells if a line calls the Pages workflow of the template (`uses: ...reusable-pages.yml`). */
10101
- function callsPages(line) {
10102
- let text = line.trimStart();
10103
- if (text.startsWith("- ")) text = text.slice(2).trimStart();
10104
- if (!text.startsWith("uses:")) return false;
10105
- const value = text.slice(5).trim();
10106
- return /(?:^|\/)reusable-pages\.ya?ml(?:@|$|\s)/.test(value);
10107
- }
10108
- const indentOf = (line) => line.length - line.trimStart().length;
10109
- /** This function tells if a line is `site-pages: false`: the site has no Status page. */
10110
- function noStatusPage(line) {
10111
- const text = line.trimStart();
10112
- if (!text.startsWith("site-pages:")) return false;
10113
- let value = text.slice(11);
10114
- const comment = value.indexOf(" #");
10115
- if (comment >= 0) value = value.slice(0, comment);
10116
- return [
10117
- "false",
10118
- "\"false\"",
10119
- "'false'"
10120
- ].includes(value.trim());
9918
+ /** This function gives the words that end the here-documents of a line of a script. */
9919
+ function hereWords(line) {
9920
+ return [...line.matchAll(/<<-?\s*["']?([A-Za-z_][A-Za-z0-9_]*)["']?/g)].map((match) => match[1] ?? "");
10121
9921
  }
10122
9922
  /**
10123
- * This function gives the line numbers of each call of the Pages workflow that gives no `roadmap` key. The key is in the
10124
- * job of the call: the lines around it with the same indent or more. A job with `site-pages: false` has no Status page.
9923
+ * This function tells if a script has a pipe. It does not read the text of quotes, of comments and of here-documents, and an `||` is not a pipe.
9924
+ * A `|` of a `case` pattern counts as a pipe. The fix for such a script is harmless.
10125
9925
  */
10126
- function callsWithoutRoadmap(lines) {
9926
+ function hasPipe(script) {
9927
+ let quote = "";
9928
+ let until = [];
9929
+ for (const line of script.split(/\r?\n/)) {
9930
+ if (until.length > 0) {
9931
+ if (line.trim() === until[0]) until = until.slice(1);
9932
+ continue;
9933
+ }
9934
+ for (let i = 0; i < line.length; i++) {
9935
+ const char = line.charAt(i);
9936
+ if (quote !== "") {
9937
+ if (char === "\\" && quote === "\"") i += 1;
9938
+ else if (char === quote) quote = "";
9939
+ } else if (char === "\\") i += 1;
9940
+ else if (char === "\"" || char === "'") quote = char;
9941
+ else if (char === "#" && (i === 0 || /\s/.test(line.charAt(i - 1)))) break;
9942
+ else if (char === "|") {
9943
+ if (line.charAt(i + 1) !== "|") return true;
9944
+ i += 1;
9945
+ }
9946
+ }
9947
+ if (quote === "") until = hereWords(line);
9948
+ }
9949
+ return false;
9950
+ }
9951
+ /** This function gives the value of `defaults.run.shell` in the block under the line `index`. The value `-1` reads the top of the file. */
9952
+ function defaultShell(lines, index) {
9953
+ const defaults = (index < 0 ? lines.flatMap((line, at) => line.trim() !== "" && indentOf$1(line) === 0 ? [at] : []) : childKeys(lines, index)).find((at) => keyValue(lines[at] ?? "", "defaults") !== void 0);
9954
+ if (defaults === void 0) return void 0;
9955
+ const run = childKeys(lines, defaults).find((at) => keyValue(lines[at] ?? "", "run") !== void 0);
9956
+ if (run === void 0) return void 0;
9957
+ for (const at of childKeys(lines, run)) {
9958
+ const value = keyValue(lines[at] ?? "", "shell");
9959
+ if (value !== void 0) return value;
9960
+ }
9961
+ }
9962
+ /** This function gives the steps with a `run` key. It reads only the steps of the jobs. */
9963
+ function runSteps(lines) {
9964
+ const jobs = lines.findIndex((line) => indentOf$1(line) === 0 && keyValue(line, "jobs") !== void 0);
9965
+ if (jobs < 0) return [];
10127
9966
  const found = [];
10128
- lines.forEach((line, index) => {
10129
- if (!callsPages(line)) return;
10130
- const indent = indentOf(line);
10131
- const inJob = (text) => text.trim() === "" || indentOf(text) >= indent;
10132
- let first = index;
10133
- while (first > 0 && inJob(lines[first - 1] ?? "")) first -= 1;
10134
- let last = index;
10135
- while (last < lines.length - 1 && inJob(lines[last + 1] ?? "")) last += 1;
10136
- if (!lines.slice(first, last + 1).some((text) => text.trimStart().startsWith("roadmap:") || noStatusPage(text))) found.push(index + 1);
10137
- });
9967
+ const workflowShell = defaultShell(lines, -1);
9968
+ for (const job of childKeys(lines, jobs)) {
9969
+ const jobShell = defaultShell(lines, job);
9970
+ const steps = childKeys(lines, job).find((at) => keyValue(lines[at] ?? "", "steps") !== void 0);
9971
+ if (steps === void 0) continue;
9972
+ const dashes = stepStarts(lines, steps);
9973
+ dashes.forEach((dash, order) => {
9974
+ const end = dashes[order + 1] ?? blockAfter(lines, steps);
9975
+ const indent = indentOf$1(lines[dash] ?? "") + 2;
9976
+ let run;
9977
+ let shell;
9978
+ for (let at = dash; at < end; at++) {
9979
+ const line = lines[at] ?? "";
9980
+ if (!(at === dash || line.trim() !== "" && indentOf$1(line) === indent)) continue;
9981
+ if (keyValue(line, "run") !== void 0) run = at;
9982
+ shell = keyValue(line, "shell") ?? shell;
9983
+ }
9984
+ if (run === void 0) return;
9985
+ const value = keyValue(lines[run] ?? "", "run") ?? "";
9986
+ const scalar = /^[|>]/.test(value);
9987
+ const body = scalar ? [] : [value];
9988
+ if (scalar) for (let at = run + 1; at < end; at++) {
9989
+ const line = lines[at] ?? "";
9990
+ if (line.trim() !== "" && indentOf$1(line) <= indent) break;
9991
+ body.push(line);
9992
+ }
9993
+ found.push({
9994
+ line: run,
9995
+ script: body.join("\n"),
9996
+ shell: shell ?? jobShell ?? workflowShell
9997
+ });
9998
+ });
9999
+ }
10138
10000
  return found;
10139
10001
  }
10140
- /** This function gives the value of a `roadmap: <file>` line, or undefined for another line, an empty value or an expression. */
10141
- function roadmapOfLine(line) {
10142
- const text = line.trimStart();
10143
- if (!text.startsWith("roadmap:")) return void 0;
10144
- let value = text.slice(8);
10145
- const comment = value.indexOf(" #");
10146
- if (comment >= 0) value = value.slice(0, comment);
10147
- value = value.trim();
10148
- const quote = value.charAt(0);
10149
- if (value.length >= 2 && (quote === "\"" || quote === "'") && value.endsWith(quote)) value = value.slice(1, -1).trim();
10150
- if (value === "" || value.includes("${{")) return void 0;
10151
- return cleanPath(value);
10002
+ /** This function gives the end of the list of steps under the key at the line `steps`. A list can have the same indent as its key. */
10003
+ function blockAfter(lines, steps) {
10004
+ const indent = indentOf$1(lines[steps] ?? "");
10005
+ for (let at = steps + 1; at < lines.length; at++) {
10006
+ const line = lines[at] ?? "";
10007
+ if (line.trim() === "") continue;
10008
+ if (indentOf$1(line) < indent || indentOf$1(line) === indent && !line.trimStart().startsWith("- ")) return at;
10009
+ }
10010
+ return lines.length;
10152
10011
  }
10153
- const roadmapParses = {
10154
- id: "roadmap-parses",
10155
- title: "Each call of the Pages workflow gives a roadmap, and each roadmap that a workflow gives to the Status page (the input `roadmap`) parses as site-pages reads it.",
10156
- 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.",
10157
- 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\".",
10158
- sources: [{
10159
- repo: "private",
10160
- rule: "fail-closed",
10161
- doc: "docs/STRATEGY.md (2026-10-30, gates and probes fail closed)"
10162
- }],
10163
- options: { roadmaps: {
10164
- type: "strings",
10165
- default: [],
10166
- description: "More roadmap files to check: a roadmap that no workflow names with a `roadmap:` key."
10167
- } },
10168
- check(context, options) {
10012
+ /** This function gives the lines of the items of the list of steps. */
10013
+ function stepStarts(lines, steps) {
10014
+ const end = blockAfter(lines, steps);
10015
+ let indent;
10016
+ const starts = [];
10017
+ for (let at = steps + 1; at < end; at++) {
10018
+ const line = lines[at] ?? "";
10019
+ if (line.trim() === "") continue;
10020
+ indent ??= indentOf$1(line);
10021
+ if (indentOf$1(line) === indent && line.trimStart().startsWith("- ")) starts.push(at);
10022
+ }
10023
+ return starts;
10024
+ }
10025
+ /** This function tells if a shell hides a failure on the left of a pipe. A shell that is not bash or sh has other rules, and the rule does not read it. */
10026
+ function hidesFailure(shell) {
10027
+ if (shell === void 0) return true;
10028
+ if (shell === "bash" || shell.includes("pipefail")) return false;
10029
+ return /^(bash|sh)(\s|$)/.test(shell);
10030
+ }
10031
+ /** This function gives the text with `defaults.run.shell` before its key `jobs`, or undefined when the file has its own `defaults`. */
10032
+ function withBashDefault(text) {
10033
+ const eol = text.includes("\r\n") ? "\r\n" : "\n";
10034
+ const lines = text.split(/\r?\n/);
10035
+ if (lines.some((line) => indentOf$1(line) === 0 && keyValue(line, "defaults") !== void 0)) return void 0;
10036
+ const jobs = lines.findIndex((line) => indentOf$1(line) === 0 && keyValue(line, "jobs") !== void 0);
10037
+ if (jobs < 0) return void 0;
10038
+ lines.splice(jobs, 0, "defaults:", " run:", " shell: bash", "");
10039
+ return lines.join(eol);
10040
+ }
10041
+ const pipeFails = {
10042
+ id: "pipe-fails",
10043
+ title: "A failure on the left of a pipe fails its step: each step with a pipe has `pipefail`.",
10044
+ reason: "With no `shell` key, GitHub has no `pipefail`, so `tests | tee out.txt` passes when the tests fail. On 2026-11-05 a read of 99 jobs of a merge gate found 8 failed tests in jobs that concluded success.",
10045
+ fix: "Add `defaults: { run: { shell: bash } }` to the workflow, or `shell: bash` to the step, or `set -o pipefail` to the script. Then read the next run: a step that turns red had a failure that the pipe hid.",
10046
+ sources: [
10047
+ {
10048
+ repo: "coeval",
10049
+ rule: "measure",
10050
+ doc: "K228 (2026-11-05): a merge gate with no pipefail concluded success on 8 of 99 jobs with a failed test"
10051
+ },
10052
+ {
10053
+ repo: "packing",
10054
+ rule: "predicates",
10055
+ doc: "run 41547266012 (2026-11-03): the join failed behind a pipe, and its job concluded success"
10056
+ },
10057
+ {
10058
+ repo: "systems",
10059
+ rule: "kind",
10060
+ doc: "kind.yml (2026-11-05): a failed command behind a pipe left a diagnostic of the borders with no line"
10061
+ }
10062
+ ],
10063
+ options: {},
10064
+ check(context) {
10169
10065
  const files = context.gitFiles();
10170
10066
  if (files === void 0) return { skipped: "the root is not in a git repository" };
10171
- const named = [];
10172
10067
  const breaks = [];
10173
- for (const file of files.filter((path) => WORKFLOW.test(path)).sort(byCode)) {
10174
- const lines = readFileSync(join(context.root, file), "utf8").split(/\r?\n/);
10175
- lines.forEach((line, index) => {
10176
- const roadmap = roadmapOfLine(line);
10177
- if (roadmap !== void 0) named.push({
10178
- roadmap,
10068
+ for (const file of files.filter((path) => WORKFLOW$1.test(path)).sort(byCode)) {
10069
+ let text;
10070
+ try {
10071
+ text = readFileSync(join(context.root, file), "utf8");
10072
+ } catch {
10073
+ continue;
10074
+ }
10075
+ const after = withBashDefault(text);
10076
+ for (const step of runSteps(workflowLines(text))) {
10077
+ if (!hidesFailure(step.shell) || !hasPipe(step.script) || step.script.includes("pipefail")) continue;
10078
+ breaks.push({
10179
10079
  file,
10180
- line: index + 1
10080
+ line: step.line + 1,
10081
+ message: `A step of ${file} has a pipe and no \`pipefail\`. The step passes when a command on the left of the pipe fails.`,
10082
+ ...after === void 0 ? {} : { edits: [{
10083
+ file,
10084
+ before: text,
10085
+ after
10086
+ }] }
10181
10087
  });
10182
- });
10183
- for (const line of callsWithoutRoadmap(lines)) breaks.push({
10184
- file,
10185
- line,
10186
- message: `${file} builds the site with the Pages workflow and gives no roadmap, so the Status page shows no roadmap item.`
10187
- });
10088
+ }
10188
10089
  }
10189
- for (const roadmap of options["roadmaps"]) named.push({
10190
- roadmap: cleanPath(roadmap),
10191
- file: "the option roadmaps",
10192
- line: 0
10193
- });
10194
- if (named.length === 0 && breaks.length === 0) return { skipped: "no workflow builds a site with the Pages workflow, and no workflow names a roadmap" };
10195
- const seen = /* @__PURE__ */ new Set();
10196
- for (const { roadmap, file, line } of named) {
10197
- if (seen.has(roadmap)) continue;
10198
- seen.add(roadmap);
10199
- if (!existsSync(join(context.root, roadmap))) {
10200
- breaks.push({
10201
- file: line > 0 ? file : roadmap,
10202
- ...line > 0 ? { line } : {},
10203
- message: `${file} names the roadmap ${roadmap}, and the file does not exist.`
10090
+ return breaks;
10091
+ }
10092
+ };
10093
+ // src/rules/unreleased-change.ts
10094
+ /**
10095
+ * The rule `unreleased-change`: a change does not set a version that npm has. With the option `versionEachChange`, a
10096
+ * change of the files that a published package ships also raises its version. Else the release skips the change.
10097
+ */
10098
+ /** The registry of npm. */
10099
+ const NPM_REGISTRY = "https://registry.npmjs.org";
10100
+ /** The globs of the files of a package, relative to its folder, that do not ship: tests, fixtures, docs and configs. */
10101
+ const UNSHIPPED_FILES = [
10102
+ "**/*.md",
10103
+ "**/*.{test,spec}.*",
10104
+ "**/{test,tests,__tests__,fixtures,__fixtures__,__snapshots__,bench,benches,benchmarks,e2e}/**",
10105
+ "**/*.{bench,e2e}.*",
10106
+ "**/.*/**",
10107
+ "**/tsconfig*.json",
10108
+ "**/*.config.*",
10109
+ "docs/**",
10110
+ "examples/**",
10111
+ "scripts/**",
10112
+ "site/**",
10113
+ "LICENSE*",
10114
+ "pnpm-lock.yaml",
10115
+ "pnpm-workspace.yaml"
10116
+ ];
10117
+ /** The fields of `package.json` that change what the package gives to a user. A change of the dependencies is not here. */
10118
+ const SHIPPED_FIELDS = [
10119
+ "main",
10120
+ "module",
10121
+ "types",
10122
+ "typings",
10123
+ "exports",
10124
+ "imports",
10125
+ "bin",
10126
+ "files",
10127
+ "type",
10128
+ "publishConfig",
10129
+ "sideEffects",
10130
+ "browser"
10131
+ ];
10132
+ /** The script that `npmLookup` starts in a child process of Node, so that the rule stays synchronous. */
10133
+ const LOOKUP_SCRIPT = `
10134
+ const [registry, ...names] = process.argv.slice(1);
10135
+ let base = registry;
10136
+ while (base.endsWith("/")) base = base.slice(0, -1);
10137
+ Promise.all(names.map(async (name) => {
10138
+ try {
10139
+ const response = await fetch(base + "/" + name.replace("/", "%2f"), { headers: { accept: "application/json" }, signal: AbortSignal.timeout(20000) });
10140
+ if (response.status === 404) return [name, { versions: [] }];
10141
+ if (!response.ok) return [name, { error: "HTTP " + response.status }];
10142
+ const data = await response.json();
10143
+ const times = Object.fromEntries(Object.entries(data.time ?? {}).filter(([key]) => key !== "created" && key !== "modified"));
10144
+ return [name, { versions: [...new Set([...Object.keys(data.versions ?? {}), ...Object.keys(times)])], times, latest: data["dist-tags"]?.latest }];
10145
+ } catch (error) {
10146
+ return [name, { error: String(error && error.message ? error.message : error) }];
10147
+ }
10148
+ })).then((entries) => process.stdout.write(JSON.stringify(Object.fromEntries(entries))));
10149
+ `;
10150
+ /**
10151
+ * This function asks the registry for the versions of each package, in one child process of Node. A version that npm
10152
+ * removed stays in the answer, because npm does not accept it again.
10153
+ */
10154
+ const npmLookup = (names, registry) => {
10155
+ const fail = (error) => new Map(names.map((name) => [name, { error }]));
10156
+ if (names.length === 0) return /* @__PURE__ */ new Map();
10157
+ const result = spawnSync(process.execPath, [
10158
+ "-e",
10159
+ LOOKUP_SCRIPT,
10160
+ registry,
10161
+ ...names
10162
+ ], {
10163
+ encoding: "utf8",
10164
+ timeout: 6e4,
10165
+ windowsHide: true
10166
+ });
10167
+ if (result.error !== void 0 || result.status !== 0) return fail(result.error?.message ?? `the lookup ended with exit code ${String(result.status)}`);
10168
+ try {
10169
+ const answers = JSON.parse(result.stdout);
10170
+ return new Map(names.map((name) => [name, answers[name] ?? { error: "no answer" }]));
10171
+ } catch {
10172
+ return fail("the lookup gave no JSON");
10173
+ }
10174
+ };
10175
+ /** This function gives the strings of a field of `package.json` that is a list of strings. */
10176
+ const stringsOf = (manifest, field) => {
10177
+ const value = manifest[field];
10178
+ return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
10179
+ };
10180
+ /** This function tells if a path relative to the root is in the folder `folder`. The root is `""`. */
10181
+ const inside = (folder, path) => folder === "" || path.startsWith(`${folder}/`);
10182
+ /** This function gives the globs of an entry of the field `files`: the entry, and each path under it. */
10183
+ const entryGlobs = (entry) => {
10184
+ let glob = cleanPath(entry);
10185
+ while (glob.endsWith("/")) glob = glob.slice(0, -1);
10186
+ return [glob, `${glob}/**`];
10187
+ };
10188
+ /** This function reads the manifest of the text of a `package.json` file, or gives undefined. */
10189
+ function parseManifest(text) {
10190
+ if (text === void 0) return void 0;
10191
+ try {
10192
+ const parsed = JSON.parse(text);
10193
+ return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : void 0;
10194
+ } catch {
10195
+ return;
10196
+ }
10197
+ }
10198
+ /** This function tells if a version is a placeholder before the first release: `0.0.0` or `0.0.0-<stage>`. */
10199
+ const isPlaceholder = (version) => /^0\.0\.0(?:[-+].*)?$/.test(version);
10200
+ /** The published packages of the repository: the root package and the code packages that are not private and have a name and a version. */
10201
+ function publishedOf(context) {
10202
+ const all = [context.rootPackage, ...codePackages(context)];
10203
+ return all.filter((pkg, index) => all.findIndex((other) => other.file === pkg.file) === index).filter((pkg) => pkg.manifest["private"] !== true && typeof pkg.manifest["name"] === "string" && typeof pkg.manifest["version"] === "string");
10204
+ }
10205
+ /** This function gives the time of the push in milliseconds, from the field `repository.pushed_at` of the event file. */
10206
+ function pushedAt(context) {
10207
+ const file = context.env["GITHUB_EVENT_PATH"];
10208
+ if (file === void 0 || file === "" || !existsSync(file)) return void 0;
10209
+ try {
10210
+ const value = JSON.parse(readFileSync(file, "utf8")).repository?.pushed_at;
10211
+ if (typeof value === "number") return value * 1e3;
10212
+ return typeof value === "string" && !Number.isNaN(Date.parse(value)) ? Date.parse(value) : void 0;
10213
+ } catch {
10214
+ return;
10215
+ }
10216
+ }
10217
+ /** This function gives the shipped files of `pkg` in the list `changed`, relative to the folder of the package. */
10218
+ function shippedFiles(pkg, changed, before, context, unshipped, fields) {
10219
+ const folders = context.packages.map((other) => other.folder).filter((folder) => folder !== "");
10220
+ const own = (path) => inside(pkg.folder, path) && (pkg.folder !== "" || !folders.some((folder) => inside(folder, path)));
10221
+ const relative = (path) => pkg.folder === "" ? path : path.slice(pkg.folder.length + 1);
10222
+ const entries = stringsOf(pkg.manifest, "files");
10223
+ const positive = entries.filter((entry) => !entry.startsWith("!"));
10224
+ const negative = entries.filter((entry) => entry.startsWith("!")).flatMap((entry) => entryGlobs(entry.slice(1)));
10225
+ const ownTracked = (context.gitFiles() ?? []).filter(own).map(relative);
10226
+ const whitelist = positive.length > 0 && positive.every((entry) => ownTracked.some((path) => matchesAny(path, entryGlobs(entry))));
10227
+ const ships = (path) => path !== "package.json" && !matchesAny(path, unshipped) && (!whitelist || positive.some((entry) => matchesAny(path, entryGlobs(entry))) && !matchesAny(path, negative));
10228
+ const files = changed.filter(own).map(relative).filter(ships);
10229
+ if (changed.includes(pkg.file) && before !== void 0 && fields.some((field) => JSON.stringify(before[field]) !== JSON.stringify(pkg.manifest[field]))) files.push("package.json");
10230
+ return files;
10231
+ }
10232
+ /** This function makes the rule with the registry lookup `lookup`. The tests give a fake lookup. */
10233
+ function unreleasedChangeRule(lookup = npmLookup) {
10234
+ return {
10235
+ id: "unreleased-change",
10236
+ changeScoped: true,
10237
+ title: "A change does not set a version that npm has. With `versionEachChange`, a change of the shipped files also raises the version.",
10238
+ reason: "The release workflow publishes each version that npm does not have, and it skips the others. When two pull requests set the same version, the second merge changes the code but no version, and nothing fails (rigor #18 and #20, 2026-11-02).",
10239
+ fix: "Raise the version of the package in a pull request to a version that npm does not have, with the SemVer rules (RELEASING.md). Then the release workflow publishes the change.",
10240
+ sources: [{
10241
+ repo: "rigor",
10242
+ rule: "unreleased-change",
10243
+ doc: "pull requests #18 and #20 (2026-11-02): two pull requests set the same version"
10244
+ }, ...[
10245
+ "crawler",
10246
+ "coeval",
10247
+ "template"
10248
+ ].map((repo) => ({
10249
+ repo,
10250
+ rule: "unreleased-change",
10251
+ doc: ".github/workflows/release.yml (it starts on a change of a version, and it skips each version that npm has)"
10252
+ }))],
10253
+ options: {
10254
+ versionEachChange: {
10255
+ type: "boolean",
10256
+ default: false,
10257
+ description: "True when each pull request sets its version: a change of the shipped files with a version that npm has breaks, also on a push. False when a separate pull request raises the version."
10258
+ },
10259
+ unshipped: {
10260
+ type: "strings",
10261
+ default: UNSHIPPED_FILES,
10262
+ description: "With `versionEachChange`: the globs of the files of a package, relative to its folder, that do not ship."
10263
+ },
10264
+ fields: {
10265
+ type: "strings",
10266
+ default: SHIPPED_FIELDS,
10267
+ description: "With `versionEachChange`: the fields of `package.json` whose change ships. The dependencies are not in the default list."
10268
+ },
10269
+ registry: {
10270
+ type: "string",
10271
+ default: NPM_REGISTRY,
10272
+ description: "The URL of the registry that has the versions."
10273
+ }
10274
+ },
10275
+ check(context, options) {
10276
+ if (hasFile(context.root, ".changeset/config.json")) return { skipped: "the repository uses Changesets: the changesets raise the versions, and the changeset check examines them" };
10277
+ const published = publishedOf(context).filter((pkg) => !isPlaceholder(String(pkg.manifest["version"])));
10278
+ if (published.length === 0) return { skipped: "the repository has no published package with a release version" };
10279
+ const range = rangeOf(context, { push: true });
10280
+ if ("skipped" in range) return range;
10281
+ const strict = options["versionEachChange"] === true;
10282
+ const push = context.base === void 0 && context.env["GITHUB_EVENT_NAME"] === "push";
10283
+ const out = strict ? context.git([
10284
+ "diff",
10285
+ "--name-only",
10286
+ "--no-renames",
10287
+ ...range.diff
10288
+ ]) : "";
10289
+ if (out === void 0) return { skipped: "git cannot give the changed files of the change" };
10290
+ const changed = out.split(/\r?\n/).filter((file) => file !== "");
10291
+ const unshipped = Array.isArray(options["unshipped"]) ? options["unshipped"] : UNSHIPPED_FILES;
10292
+ const fields = Array.isArray(options["fields"]) ? options["fields"] : SHIPPED_FIELDS;
10293
+ const registry = typeof options["registry"] === "string" ? options["registry"] : NPM_REGISTRY;
10294
+ const fork = push ? range.ends[0] : context.git(["merge-base", ...range.ends])?.trim();
10295
+ const notes = [];
10296
+ if (fork === void 0) notes.push(`the checkout does not have the merge base of ${range.ends.join(" and ")}, so the rule cannot tell if the change sets a version`);
10297
+ const manifestAt = (ref, pkg) => ref === "HEAD" ? pkg.manifest : parseManifest(context.git(["show", `${ref}:${pkg.file}`]));
10298
+ const versionOf = (manifest) => typeof manifest?.["version"] === "string" ? manifest["version"] : void 0;
10299
+ const candidates = [];
10300
+ for (const pkg of published) {
10301
+ const atStart = manifestAt(range.ends[0], pkg);
10302
+ const set = versionOf(manifestAt(range.ends[1], pkg));
10303
+ const before = fork === void 0 ? void 0 : versionOf(fork === range.ends[0] ? atStart : manifestAt(fork, pkg));
10304
+ const sets = fork !== void 0 && set !== void 0 && !isPlaceholder(set) && set !== before ? set : void 0;
10305
+ const files = strict ? shippedFiles(pkg, changed, atStart, context, unshipped, fields) : [];
10306
+ if (sets === void 0 && files.length === 0) continue;
10307
+ candidates.push({
10308
+ pkg,
10309
+ name: String(pkg.manifest["name"]),
10310
+ version: String(pkg.manifest["version"]),
10311
+ sets,
10312
+ start: versionOf(atStart),
10313
+ files
10204
10314
  });
10205
- continue;
10206
10315
  }
10207
- try {
10208
- parseRoadmap(readFileSync(join(context.root, roadmap), "utf8"), { file: roadmap });
10209
- } catch (error) {
10210
- if (!(error instanceof RoadmapParseError)) throw error;
10211
- const at = /^[^:]+:(\d+): /.exec(error.message);
10212
- const rest = at ? error.message.slice(at[0].length) : error.message.slice(error.message.indexOf(": ") + 2);
10213
- breaks.push({
10214
- file: roadmap,
10215
- ...at ? { line: Number(at[1]) } : {},
10216
- message: `${roadmap}: ${rest}`
10217
- });
10316
+ if (candidates.length === 0) return notes.length > 0 ? { skipped: notes.join("; ") } : [];
10317
+ const answers = lookup(candidates.map((candidate) => candidate.name), registry);
10318
+ const pushTime = push ? pushedAt(context) : void 0;
10319
+ const breaks = [];
10320
+ for (const candidate of candidates) {
10321
+ const answer = answers.get(candidate.name) ?? { error: "no answer" };
10322
+ if ("error" in answer) {
10323
+ notes.push(`the registry did not answer for ${candidate.name}: ${answer.error}`);
10324
+ continue;
10325
+ }
10326
+ const line = lineOf(candidate.pkg.text, "\"version\"");
10327
+ const at = {
10328
+ file: candidate.pkg.file,
10329
+ ...line === void 0 ? {} : { line }
10330
+ };
10331
+ if (candidate.sets !== void 0) {
10332
+ const sets = candidate.sets;
10333
+ if (!answer.versions.includes(sets)) continue;
10334
+ if (push) {
10335
+ const time = Date.parse(answer.times?.[sets] ?? "");
10336
+ if (pushTime === void 0 || Number.isNaN(time)) {
10337
+ notes.push(`the rule cannot tell if npm had ${candidate.name}@${sets} before the push`);
10338
+ continue;
10339
+ }
10340
+ if (time >= pushTime) continue;
10341
+ }
10342
+ breaks.push({
10343
+ ...at,
10344
+ message: `${candidate.name}: the change sets the version ${sets}, but ${sets} is on npm already. Raise the version (SemVer) in a pull request.`
10345
+ });
10346
+ } else if (strict && candidate.files.length > 0 && candidate.start === candidate.version && answer.versions.includes(candidate.version)) {
10347
+ const shown = candidate.files.slice(0, 3).map((file) => candidate.pkg.folder === "" ? file : `${candidate.pkg.folder}/${file}`);
10348
+ const more = candidate.files.length > shown.length ? ` and ${String(candidate.files.length - shown.length)} more` : "";
10349
+ breaks.push({
10350
+ ...at,
10351
+ message: `${candidate.name}: the change is not released, because ${candidate.version} is on npm already. Raise the version (SemVer) in a pull request. The change ships ${shown.join(", ")}${more}.`
10352
+ });
10353
+ }
10218
10354
  }
10355
+ if (breaks.length === 0 && notes.length > 0) return { skipped: notes.join("; ") };
10356
+ return breaks;
10219
10357
  }
10220
- return breaks;
10221
- }
10222
- };
10223
- // src/rules/runner-budget.ts
10358
+ };
10359
+ }
10360
+ const unreleasedChange = unreleasedChangeRule();
10361
+ // src/rules/published-minor.ts
10224
10362
  /**
10225
- * The rule `runner-budget`: the workflows share the runners of the account. Each matrix has a `max-parallel`, each
10226
- * workflow has a concurrency group, and each schedule starts at the minute of its repository and file.
10363
+ * The rule `published-minor`: a consumer does not stay behind the newest published minor of a package that the option
10364
+ * `packages` names. A caret range of a `0.x` version cannot reach the next minor, so such a consumer stays behind with
10365
+ * no failure. The lockfile can also hold an old version that the range admits.
10227
10366
  */
10367
+ /** This function gives the major and the minor of a release version, or undefined for a pre-release and for other text. */
10368
+ function minorOf(version) {
10369
+ const release = version.trim().split("(", 1)[0]?.split("+", 1)[0] ?? "";
10370
+ const match = /^(\d+)\.(\d+)\.\d+$/.exec(release);
10371
+ return match === null ? void 0 : [Number(match[1]), Number(match[2])];
10372
+ }
10228
10373
  /**
10229
- * This function gives the minute (1 to 59) of the schedules of a workflow: the FNV-1a hash of the repository and the
10230
- * file. Two repositories with the same workflow thus start at different minutes, and no schedule starts at minute 0,
10231
- * where GitHub has the most load.
10374
+ * This function gives the highest minor that a range can reach. It gives undefined for a form that the rule does not read.
10375
+ * These forms are a `workspace:` or `github:` specifier, a tag, a partial version and a compound range. Below `1.0.0`, a caret stays in
10376
+ * its minor. From `1.0.0`, a caret reaches each minor of its major.
10232
10377
  */
10233
- function scheduleMinute(repository, file) {
10234
- let hash = 2166136261;
10235
- for (const char of `${repository.toLowerCase()}/${file}`) {
10236
- hash ^= char.codePointAt(0) ?? 0;
10237
- hash = Math.imul(hash, 16777619) >>> 0;
10238
- }
10239
- return hash % 59 + 1;
10378
+ function reachOf(specifier) {
10379
+ const match = /^([\^~]?)(\d+)\.(\d+)\.\d+(?:[-+].*)?$/.exec(specifier.trim());
10380
+ if (match === null) return void 0;
10381
+ const major = Number(match[2]);
10382
+ return match[1] === "^" && major > 0 ? [major, Number.POSITIVE_INFINITY] : [major, Number(match[3])];
10240
10383
  }
10241
- /** This function gives `owner/name` from a git remote URL, or undefined for a URL that is not of GitHub. */
10242
- function repositoryOfRemote(url) {
10243
- const text = url.trim();
10244
- for (const prefix of [
10245
- "git@github.com:",
10246
- "ssh://git@github.com/",
10247
- "https://github.com/",
10248
- "http://github.com/",
10249
- "git+https://github.com/"
10250
- ]) {
10251
- if (!text.startsWith(prefix)) continue;
10252
- let rest = text.slice(prefix.length);
10253
- if (rest.endsWith("/")) rest = rest.slice(0, -1);
10254
- if (rest.endsWith(".git")) rest = rest.slice(0, -4);
10255
- const parts = rest.split("/");
10256
- return parts.length === 2 && parts.every((part) => part !== "") ? rest : void 0;
10384
+ /** This function tells if the minor `have` is before the minor `other`. */
10385
+ const behind = (have, other) => have[0] < other[0] || have[0] === other[0] && have[1] < other[1];
10386
+ /** This function gives the indent, the key and the value of one line of YAML. It cuts the line by position, with no pattern. */
10387
+ function yamlEntry(line) {
10388
+ const text = line.trimEnd();
10389
+ const body = text.trimStart();
10390
+ const colon = body.indexOf(": ");
10391
+ const key = colon >= 0 ? body.slice(0, colon) : body.endsWith(":") ? body.slice(0, -1) : "";
10392
+ return key === "" ? void 0 : {
10393
+ indent: text.length - body.length,
10394
+ key,
10395
+ value: colon >= 0 ? body.slice(colon + 2) : ""
10396
+ };
10397
+ }
10398
+ /**
10399
+ * This function gives the locked version of each dependency of each importer of the text of a `pnpm-lock.yaml` file. The
10400
+ * key of the outer map is the folder of the importer, with `""` for the root.
10401
+ */
10402
+ function lockedVersions(text) {
10403
+ const importers = /* @__PURE__ */ new Map();
10404
+ let inside = false;
10405
+ let importer;
10406
+ let name;
10407
+ for (const line of text.split(/\r?\n/)) {
10408
+ if (/^\S/.test(line)) inside = line.trimEnd() === "importers:";
10409
+ if (!inside) continue;
10410
+ const entry = yamlEntry(line);
10411
+ if (entry === void 0) continue;
10412
+ const { indent, value } = entry;
10413
+ const key = entry.key.replace(/^['"]|['"]$/g, "");
10414
+ if (indent === 2) {
10415
+ importer = /* @__PURE__ */ new Map();
10416
+ importers.set(key === "." ? "" : key, importer);
10417
+ } else if (indent === 6) name = key;
10418
+ else if (indent === 8 && key === "version" && name !== void 0) importer?.set(name, value);
10257
10419
  }
10420
+ return importers;
10258
10421
  }
10259
- /** This function tells if a workflow is a shared workflow (`on: workflow_call`). Its caller gives the concurrency group. */
10260
- function isShared(lines) {
10261
- return lines.some((line) => {
10262
- const text = line.trimStart();
10263
- return text.startsWith("workflow_call:") || text === "workflow_call" || text === "- workflow_call" || text.startsWith("on:") && text.includes("workflow_call");
10422
+ /** This function gives the time in milliseconds of the first release that `have` is behind, or undefined when npm gives no time. */
10423
+ function firstAhead(answer, have) {
10424
+ const times = Object.entries(answer.times ?? {}).flatMap(([version, time]) => {
10425
+ const minor = minorOf(version);
10426
+ return minor !== void 0 && behind(have, minor) && !Number.isNaN(Date.parse(time)) ? [Date.parse(time)] : [];
10264
10427
  });
10428
+ return times.length === 0 ? void 0 : Math.min(...times);
10265
10429
  }
10266
- /** This function gives the jobs of a workflow. */
10267
- function jobsOf(lines) {
10268
- const jobs = lines.findIndex((line) => indentOf$1(line) === 0 && line.startsWith("jobs:"));
10269
- if (jobs < 0) return [];
10270
- const jobIndent = childIndent(lines, jobs);
10271
- const end = blockEnd(lines, jobs);
10272
- const found = [];
10273
- for (let i = jobs + 1; i < end; i++) {
10274
- const line = lines[i] ?? "";
10275
- if (line.trim() === "" || indentOf$1(line) !== jobIndent) continue;
10276
- const keyIndent = childIndent(lines, i);
10277
- const keys = lines.slice(i + 1, blockEnd(lines, i)).filter((text) => indentOf$1(text) === keyIndent);
10278
- const uses = keys.map((text) => keyValue(text, "uses")).find((value) => value !== void 0);
10279
- const at = uses === void 0 ? -1 : uses.indexOf(".github/workflows/");
10280
- const calls = uses === void 0 || at < 0 ? void 0 : uses.slice(at + 18).split("@")[0] ?? "";
10281
- found.push({
10282
- name: line.trim().replace(/:$/, ""),
10283
- line: i + 1,
10284
- grouped: keys.some((text) => keyValue(text, "concurrency") !== void 0),
10285
- ...calls === void 0 ? {} : { calls }
10286
- });
10287
- }
10288
- return found;
10430
+ /** This function makes the rule with the registry lookup `lookup` and the clock `now`. The tests give fakes. */
10431
+ function publishedMinorRule(lookup = npmLookup, now = Date.now) {
10432
+ return {
10433
+ id: "published-minor",
10434
+ title: "A consumer does not stay behind the newest published minor of a package that the option `packages` names.",
10435
+ reason: "A caret range of a 0.x version cannot reach the next minor, and a lockfile can hold an old version that a range admits. A test that holds the choices of today does not show it, so a consumer can stay behind for many releases with no failure.",
10436
+ fix: "Raise the range of the dependency to the newest published minor, and update the lockfile. Read the changes of the release first.",
10437
+ sources: [{
10438
+ repo: "private",
10439
+ rule: "published-minor",
10440
+ doc: "docs/STRATEGY.md (2026-11-04, a consumer behind a published minor)"
10441
+ }],
10442
+ options: {
10443
+ packages: {
10444
+ type: "strings",
10445
+ default: [],
10446
+ description: "The patterns of the package names that the rule examines, for example `@scope/*`. With no pattern, the rule does not start."
10447
+ },
10448
+ graceDays: {
10449
+ type: "number",
10450
+ default: 0,
10451
+ description: "The days that a consumer has, from the first publish of a minor that it does not have."
10452
+ },
10453
+ registry: {
10454
+ type: "string",
10455
+ default: NPM_REGISTRY,
10456
+ description: "The URL of the registry that has the versions."
10457
+ }
10458
+ },
10459
+ check(context, options) {
10460
+ const patterns = Array.isArray(options["packages"]) ? options["packages"] : [];
10461
+ if (patterns.length === 0) return { skipped: "the option `packages` names no package" };
10462
+ const all = [context.rootPackage, ...context.packages];
10463
+ const consumers = all.filter((pkg, index) => all.findIndex((other) => other.file === pkg.file) === index);
10464
+ const uses = [];
10465
+ for (const pkg of consumers) for (const field of DEPENDENCY_FIELDS) for (const [name, specifier] of specifiersOf(pkg.manifest, field)) {
10466
+ const reach = reachOf(specifier);
10467
+ if (reach !== void 0 && matchesAny(name, patterns)) uses.push({
10468
+ pkg,
10469
+ field,
10470
+ name,
10471
+ reach
10472
+ });
10473
+ }
10474
+ if (uses.length === 0) return { skipped: "no dependency has a range and a name that the option `packages` names" };
10475
+ const answers = lookup([...new Set(uses.map((use) => use.name))], typeof options["registry"] === "string" ? options["registry"] : NPM_REGISTRY);
10476
+ const locked = hasFile(context.root, "pnpm-lock.yaml") ? lockedVersions(readFileSync(join(context.root, "pnpm-lock.yaml"), "utf8")) : /* @__PURE__ */ new Map();
10477
+ const grace = (typeof options["graceDays"] === "number" ? options["graceDays"] : 0) * 864e5;
10478
+ const breaks = [];
10479
+ const notes = /* @__PURE__ */ new Set();
10480
+ for (const { pkg, field, name, reach } of uses) {
10481
+ const answer = answers.get(name) ?? { error: "no answer" };
10482
+ if ("error" in answer) {
10483
+ notes.add(`the registry did not answer for ${name}: ${answer.error}`);
10484
+ continue;
10485
+ }
10486
+ const latest = answer.latest === void 0 ? void 0 : minorOf(answer.latest);
10487
+ if (latest === void 0) continue;
10488
+ const version = locked.get(pkg.folder)?.get(name);
10489
+ const lockMinor = version === void 0 ? void 0 : minorOf(version);
10490
+ const have = behind(reach, latest) ? reach : lockMinor;
10491
+ if (have === void 0 || !behind(have, latest)) continue;
10492
+ const since = firstAhead(answer, have);
10493
+ if (grace > 0 && since !== void 0 && now() - since < grace) continue;
10494
+ const line = keyLine(pkg.text, field, name);
10495
+ const at = {
10496
+ file: pkg.file,
10497
+ ...line === void 0 ? {} : { line }
10498
+ };
10499
+ const message = have === reach ? `${name}: the range in ${field} cannot reach ${String(answer.latest)}, the newest version on npm. Raise the range.` : `${name}: the lockfile holds ${String(version)}, and npm has ${String(answer.latest)}. Update the lockfile.`;
10500
+ breaks.push({
10501
+ ...at,
10502
+ message
10503
+ });
10504
+ }
10505
+ if (breaks.length === 0 && notes.size > 0) return { skipped: [...notes].join("; ") };
10506
+ return breaks;
10507
+ }
10508
+ };
10289
10509
  }
10290
- const hasTopGroup = (lines) => lines.some((line) => indentOf$1(line) === 0 && line.startsWith("concurrency:"));
10510
+ const publishedMinor = publishedMinorRule();
10511
+ // src/rules/release-files.ts
10291
10512
  /**
10292
- * This function gives the edit that adds a concurrency group at the top of a workflow, before `jobs:`. A new run of a pull
10293
- * request stops the old run. A run of another event has the group of its commit, so that no release or scheduled run stops.
10513
+ * The rule `release-files`: a pull request changes a file of the release flow only with a reason
10514
+ * that everyone can see.
10294
10515
  */
10295
- function groupEdits(file, text, lines) {
10296
- const jobs = lines.findIndex((line) => indentOf$1(line) === 0 && line.startsWith("jobs:"));
10297
- if (jobs < 0) return [];
10298
- const pad = " ".repeat(childIndent(lines, jobs) ?? 2);
10299
- const original = text.split(/\r?\n/)[jobs] ?? "jobs:";
10300
- const group = [
10301
- "concurrency:",
10302
- pad + "group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.ref || github.sha }}",
10303
- pad + "cancel-in-progress: ${{ github.event_name == 'pull_request' }}",
10304
- "",
10305
- original
10306
- ];
10307
- return [{
10308
- file,
10309
- before: text,
10310
- after: replaceLine(text, jobs + 1, group)
10311
- }];
10516
+ /** This function gives the pull request of the event file of GitHub Actions. With no event file, the body is empty. */
10517
+ function pullRequestOf(context) {
10518
+ const file = context.env["GITHUB_EVENT_PATH"];
10519
+ if (file === void 0 || file === "" || !existsSync(file)) return { body: "" };
10520
+ try {
10521
+ const event = JSON.parse(readFileSync(file, "utf8"));
10522
+ const body = typeof event.pull_request?.body === "string" ? event.pull_request.body : "";
10523
+ const commits = event.pull_request?.commits;
10524
+ return typeof commits === "number" ? {
10525
+ body,
10526
+ commits
10527
+ } : { body };
10528
+ } catch {
10529
+ return { body: "" };
10530
+ }
10312
10531
  }
10313
- /**
10314
- * This function gives the breaks of the concurrency groups. A workflow with no group at the top needs one in each job.
10315
- * A job that calls a shared workflow of `grouped` gets its group from the jobs of that workflow. A shared workflow gets
10316
- * its group from its caller, but a shared workflow of `grouped` has a group in each job.
10317
- */
10318
- function concurrencyBreaks(file, text, lines, grouped) {
10319
- const name = file.slice(file.lastIndexOf("/") + 1);
10320
- const jobs = jobsOf(lines);
10321
- if (isShared(lines)) {
10322
- if (!grouped.includes(name)) return [];
10323
- return jobs.filter((job) => !job.grouped).map((job) => ({
10532
+ /** This function escapes the special characters of a regular expression. */
10533
+ const escape = (text) => text.replace(/[\\^$.|?*+()[\]{}]/g, "\\$&");
10534
+ const releaseFiles = {
10535
+ id: "release-files",
10536
+ title: "A pull request changes `.github/workflows/release.yml` or `scripts/release/` only with a `Release-Edit: <reason>` line.",
10537
+ reason: "The release flow publishes to npm with trusted publishing. A change of its files by a session that does not own the release can stop or break each release.",
10538
+ fix: "Revert the change of the release files. When the owner asked for the change, add the line `Release-Edit: <reason>` to the last commit message or to the body of the pull request. A re-run of a job reads the body of the event that started the run, so after a change of the body, push a commit.",
10539
+ sources: [
10540
+ {
10541
+ repo: "coeval",
10542
+ rule: "no-release-edit",
10543
+ doc: "CLAUDE.md:40"
10544
+ },
10545
+ {
10546
+ repo: "coeval",
10547
+ rule: "no-release-edits",
10548
+ doc: "CLAUDE.md:40"
10549
+ },
10550
+ {
10551
+ repo: "crawler",
10552
+ rule: "no-release-edit",
10553
+ doc: "CLAUDE.md:80"
10554
+ },
10555
+ {
10556
+ repo: "crawler",
10557
+ rule: "no-release-edits",
10558
+ doc: "CLAUDE.md:80"
10559
+ },
10560
+ {
10561
+ repo: "headroom",
10562
+ rule: "no-release-edits",
10563
+ doc: "CLAUDE.md:37"
10564
+ },
10565
+ {
10566
+ repo: "headroom",
10567
+ rule: "release-files-frozen",
10568
+ doc: "CLAUDE.md:37"
10569
+ }
10570
+ ],
10571
+ options: {
10572
+ paths: {
10573
+ type: "strings",
10574
+ default: [".github/workflows/release.yml", "scripts/release/**"],
10575
+ description: "The globs of the files that the release flow owns."
10576
+ },
10577
+ trailer: {
10578
+ type: "string",
10579
+ default: "Release-Edit",
10580
+ description: "The key of the line that gives the reason of a change."
10581
+ },
10582
+ authors: {
10583
+ type: "strings",
10584
+ default: ["mark1russell7-release-train[bot]"],
10585
+ description: "The authors of the release flow. A change of the release files in commits of only these authors (the sync of the template) needs no reason."
10586
+ }
10587
+ },
10588
+ check(context, options) {
10589
+ const range = rangeOf(context);
10590
+ if ("skipped" in range) return range;
10591
+ const globs = Array.isArray(options["paths"]) ? options["paths"] : [];
10592
+ const changed = (context.git([
10593
+ "diff",
10594
+ "--name-only",
10595
+ ...range.diff
10596
+ ]) ?? "").split(/\r?\n/).filter((file) => file !== "" && matchesAny(file, globs));
10597
+ if (changed.length === 0) return [];
10598
+ const trailer = typeof options["trailer"] === "string" ? options["trailer"] : "Release-Edit";
10599
+ const line = new RegExp(`^${escape(trailer)}:[ \\t]*\\S`, "im");
10600
+ const pullRequest = pullRequestOf(context);
10601
+ if (line.test(pullRequest.body)) return [];
10602
+ if (!(pullRequest.commits === 1 && context.git([
10603
+ "rev-parse",
10604
+ "--verify",
10605
+ "--quiet",
10606
+ `${range.ends[1]}^2`
10607
+ ]) === void 0) && context.git(["merge-base", ...range.ends]) === void 0) throw new Error(`The checkout does not have the merge base of ${range.ends.join(" and ")}, so the rule cannot read each commit of the change. Use fetch-depth 0, or the CI of the template, which deepens the checkout of a pull request to its merge base.`);
10608
+ const messages = context.git([
10609
+ "log",
10610
+ "--no-merges",
10611
+ "--format=%B",
10612
+ ...range.log
10613
+ ]) ?? "";
10614
+ if (line.test(messages)) return [];
10615
+ const authors = new Set(Array.isArray(options["authors"]) ? options["authors"] : []);
10616
+ const changers = (context.git([
10617
+ "log",
10618
+ "--no-merges",
10619
+ "--format=%an",
10620
+ ...range.log,
10621
+ "--",
10622
+ ...changed
10623
+ ]) ?? "").split(/\r?\n/).filter((name) => name !== "");
10624
+ if (changers.length > 0 && changers.every((name) => authors.has(name))) return [];
10625
+ return changed.map((file) => ({
10324
10626
  file,
10325
- line: job.line,
10326
- message: `${file}: the job ${job.name} has no concurrency group, and its callers rely on it (the option grouped).`
10627
+ message: `The change edits ${file}, a file of the release flow, with no "${trailer}: <reason>" line.`
10327
10628
  }));
10328
10629
  }
10329
- if (hasTopGroup(lines)) return [];
10330
- const missing = jobs.filter((job) => !job.grouped && !(job.calls !== void 0 && grouped.includes(job.calls)));
10331
- const edits = missing.length === 0 ? [] : groupEdits(file, text, lines);
10332
- return missing.map((job) => ({
10333
- file,
10334
- line: job.line,
10335
- message: `${file}: the job ${job.name} has no concurrency group, and the workflow has none.`,
10336
- edits
10337
- }));
10630
+ };
10631
+ // src/rules/required-scripts.ts
10632
+ /**
10633
+ * The rule `required-scripts`: the root `package.json` keeps the scripts that the shared CI starts.
10634
+ */
10635
+ /** The package of the STE linter. */
10636
+ const STE_LINT = "@mark1russell7/ste-lint";
10637
+ /** The configuration file of the STE linter. */
10638
+ const STE_CONFIG = "ste.config.json";
10639
+ /** The examples of the scripts that the fix shows. */
10640
+ const EXAMPLES = {
10641
+ "lint:ste": "ste-lint",
10642
+ typecheck: "pnpm -r run typecheck"
10643
+ };
10644
+ /**
10645
+ * This function tells if the repository uses the STE prose standard: the root `package.json` has a
10646
+ * dependency on `@mark1russell7/ste-lint`, or the root has a `ste.config.json`.
10647
+ */
10648
+ function usesSteLint(context) {
10649
+ const manifest = context.rootPackage.manifest;
10650
+ if (DEPENDENCY_FIELDS.some((field) => specifiersOf(manifest, field).some(([name]) => name === STE_LINT))) return true;
10651
+ return hasFile(context.root, STE_CONFIG);
10338
10652
  }
10339
- /** This function gives the breaks of the matrices: each `strategy` with a `matrix` has a `max-parallel` of `limit` or less. */
10340
- function matrixBreaks(file, text, lines, limit) {
10341
- const breaks = [];
10342
- const originals = text.split(/\r?\n/);
10343
- lines.forEach((line, index) => {
10344
- if (keyValue(line, "strategy") === void 0) return;
10345
- const keyIndent = childIndent(lines, index);
10346
- if (keyIndent === void 0) return;
10347
- const keys = [];
10348
- for (let i = index + 1; i < blockEnd(lines, index); i++) if ((lines[i] ?? "").trim() !== "" && indentOf$1(lines[i] ?? "") === keyIndent) keys.push(i);
10349
- if (!keys.some((i) => keyValue(lines[i] ?? "", "matrix") !== void 0)) return;
10350
- const at = keys.find((i) => keyValue(lines[i] ?? "", "max-parallel") !== void 0);
10351
- const raw = at === void 0 ? void 0 : keyValue(lines[at] ?? "", "max-parallel");
10352
- const value = raw === void 0 ? NaN : Number(raw);
10353
- const wanted = `${" ".repeat(keyIndent)}max-parallel: ${String(limit)}`;
10354
- if (at === void 0 || raw === void 0) {
10355
- const after = replaceLine(text, index + 1, [originals[index] ?? line, wanted]);
10356
- breaks.push({
10357
- file,
10358
- line: index + 1,
10359
- message: `${file}: a matrix has no max-parallel.`,
10360
- edits: [{
10361
- file,
10362
- before: text,
10363
- after
10364
- }]
10365
- });
10366
- } else if (!Number.isInteger(value) || value < 1 || value > limit) {
10367
- const after = replaceLine(text, at + 1, [wanted]);
10368
- breaks.push({
10369
- file,
10370
- line: index + 1,
10371
- message: `${file}: a matrix has max-parallel ${raw}, and the most is ${String(limit)}.`,
10372
- edits: [{
10373
- file,
10374
- before: text,
10375
- after
10376
- }]
10377
- });
10653
+ const requiredScripts = {
10654
+ id: "required-scripts",
10655
+ title: "The root `package.json` has the script `typecheck`, and also `lint:ste` when the repository uses `ste-lint`.",
10656
+ reason: "The shared CI starts each script of its list that `package.json` has, and it skips the others. Thus a removed script turns its check off, and nothing shows it.",
10657
+ fix: "Add the script, for example `\"lint:ste\": \"ste-lint\"` or `\"typecheck\": \"pnpm -r run typecheck\"`.",
10658
+ sources: [
10659
+ {
10660
+ repo: "client",
10661
+ rule: "ste-prose",
10662
+ doc: "CLAUDE.md:5"
10663
+ },
10664
+ {
10665
+ repo: "coeval",
10666
+ rule: "ste-prose",
10667
+ doc: "CLAUDE.md:5"
10668
+ },
10669
+ {
10670
+ repo: "crawler",
10671
+ rule: "ste-prose",
10672
+ doc: "CLAUDE.md:5"
10673
+ },
10674
+ {
10675
+ repo: "private",
10676
+ rule: "ste-prose",
10677
+ doc: "CLAUDE.md:5"
10678
+ },
10679
+ {
10680
+ repo: "headroom",
10681
+ rule: "ste-prose",
10682
+ doc: "CLAUDE.md:19"
10683
+ },
10684
+ {
10685
+ repo: "systems",
10686
+ rule: "lint-ste-in-ci",
10687
+ doc: "CLAUDE.md:24"
10688
+ },
10689
+ {
10690
+ repo: "Vex",
10691
+ rule: "ste-prose",
10692
+ doc: "CLAUDE.md:5"
10693
+ },
10694
+ {
10695
+ repo: "coeval",
10696
+ rule: "tsconfig-test",
10697
+ doc: "CLAUDE.md:18"
10698
+ },
10699
+ {
10700
+ repo: "crawler",
10701
+ rule: "tsconfig-test",
10702
+ doc: "CLAUDE.md:18"
10703
+ },
10704
+ {
10705
+ repo: "headroom",
10706
+ rule: "tsconfig-test",
10707
+ doc: "CLAUDE.md:32"
10708
+ },
10709
+ {
10710
+ repo: "Vex",
10711
+ rule: "tsconfig-test",
10712
+ doc: "CLAUDE.md:23"
10378
10713
  }
10379
- });
10380
- return breaks;
10381
- }
10714
+ ],
10715
+ options: {
10716
+ scripts: {
10717
+ type: "strings",
10718
+ default: ["typecheck"],
10719
+ description: "The scripts that the root `package.json` has."
10720
+ },
10721
+ steScripts: {
10722
+ type: "strings",
10723
+ default: ["lint:ste"],
10724
+ description: "The scripts that the root `package.json` has when the repository uses `ste-lint` (a dependency on `@mark1russell7/ste-lint`, or a `ste.config.json` at the root)."
10725
+ }
10726
+ },
10727
+ check(context, options) {
10728
+ const always = Array.isArray(options["scripts"]) ? options["scripts"] : ["typecheck"];
10729
+ const ste = Array.isArray(options["steScripts"]) ? options["steScripts"] : ["lint:ste"];
10730
+ const wanted = [.../* @__PURE__ */ new Set([...always, ...usesSteLint(context) ? ste : []])];
10731
+ const value = context.rootPackage.manifest["scripts"];
10732
+ const scripts = typeof value === "object" && value !== null ? value : {};
10733
+ const line = lineOf(context.rootPackage.text, "\"scripts\"");
10734
+ return wanted.filter((name) => typeof scripts[name] !== "string" || scripts[name] === "").map((name) => {
10735
+ const example = EXAMPLES[name];
10736
+ const why = ste.includes(name) && !always.includes(name) ? " The repository uses ste-lint." : "";
10737
+ return {
10738
+ file: context.rootPackage.file,
10739
+ ...line === void 0 ? {} : { line },
10740
+ message: `The root package.json has no script "${name}".${why}`,
10741
+ fix: example === void 0 ? `Add the script "${name}".` : `Add the script, for example "${name}": "${example}".`
10742
+ };
10743
+ });
10744
+ }
10745
+ };
10746
+ // src/rules/roadmap-parses.ts
10382
10747
  /**
10383
- * This function gives the minute field of a schedule that starts `perHour` times in each hour, at equal steps. One start is at
10384
- * `minute`: `"18"` for 1, `"18,48"` for 2. The list is in the order of the numbers.
10748
+ * The rule `roadmap-parses`: each roadmap that a workflow gives to the Status page parses, on the pull request.
10385
10749
  */
10386
- function minuteField(minute, perHour) {
10387
- const step = 60 / perHour;
10388
- return Array.from({ length: perHour }, (_, k) => (minute + k * step) % 60).sort((a, b) => a - b).join(",");
10750
+ /** A workflow file. */
10751
+ const WORKFLOW = /^\.github\/workflows\/[^/]+\.ya?ml$/;
10752
+ /** This function tells if a line calls the Pages workflow of the template (`uses: ...reusable-pages.yml`). */
10753
+ function callsPages(line) {
10754
+ let text = line.trimStart();
10755
+ if (text.startsWith("- ")) text = text.slice(2).trimStart();
10756
+ if (!text.startsWith("uses:")) return false;
10757
+ const value = text.slice(5).trim();
10758
+ return /(?:^|\/)reusable-pages\.ya?ml(?:@|$|\s)/.test(value);
10389
10759
  }
10390
- /** This function gives the number of starts in each hour of a minute field (`"*\/30"` or `"5,35"` give 2), or 1 when it cannot tell. */
10391
- function startsPerHour(field) {
10392
- const step = /^\*\/(\d+)$/.exec(field);
10393
- const count = step ? 60 / Number(step[1]) : field.split(",").length;
10394
- return Number.isInteger(count) && count >= 1 && 60 % count === 0 ? count : 1;
10760
+ const indentOf = (line) => line.length - line.trimStart().length;
10761
+ /** This function tells if a line is `site-pages: false`: the site has no Status page. */
10762
+ function noStatusPage(line) {
10763
+ const text = line.trimStart();
10764
+ if (!text.startsWith("site-pages:")) return false;
10765
+ let value = text.slice(11);
10766
+ const comment = value.indexOf(" #");
10767
+ if (comment >= 0) value = value.slice(0, comment);
10768
+ return [
10769
+ "false",
10770
+ "\"false\"",
10771
+ "'false'"
10772
+ ].includes(value.trim());
10395
10773
  }
10396
10774
  /**
10397
- * This function gives the breaks of the schedules: the minute of each `cron` is the minute of the repository and the file. A
10398
- * schedule that starts more than once in each hour starts at equal steps from that minute (`18,48` for each 30 minutes).
10775
+ * This function gives the line numbers of each call of the Pages workflow that gives no `roadmap` key. The key is in the
10776
+ * job of the call: the lines around it with the same indent or more. A job with `site-pages: false` has no Status page.
10399
10777
  */
10400
- function cronBreaks(file, text, minute) {
10401
- const breaks = [];
10402
- const originals = text.split(/\r?\n/);
10403
- for (const { line, cron: value } of cronLines(text)) {
10404
- const fields = value.split(" ").filter((field) => field !== "");
10405
- const wanted = minuteField(minute, startsPerHour(fields[0] ?? ""));
10406
- if (fields[0] === wanted) continue;
10407
- const expected = [wanted, ...fields.slice(1)].join(" ");
10408
- const original = originals[line - 1] ?? "";
10409
- const edits = original.includes(value) ? [{
10410
- file,
10411
- before: text,
10412
- after: replaceLine(text, line, [original.replace(value, () => expected)])
10413
- }] : [];
10414
- breaks.push({
10415
- file,
10416
- line,
10417
- message: `${file}: the schedule "${value}" starts at minute ${fields[0] ?? "?"}, and the minute of this repository and file is ${String(minute)}.`,
10418
- fix: `cron: "${expected}"`,
10419
- edits
10420
- });
10421
- }
10422
- return breaks;
10778
+ function callsWithoutRoadmap(lines) {
10779
+ const found = [];
10780
+ lines.forEach((line, index) => {
10781
+ if (!callsPages(line)) return;
10782
+ const indent = indentOf(line);
10783
+ const inJob = (text) => text.trim() === "" || indentOf(text) >= indent;
10784
+ let first = index;
10785
+ while (first > 0 && inJob(lines[first - 1] ?? "")) first -= 1;
10786
+ let last = index;
10787
+ while (last < lines.length - 1 && inJob(lines[last + 1] ?? "")) last += 1;
10788
+ if (!lines.slice(first, last + 1).some((text) => text.trimStart().startsWith("roadmap:") || noStatusPage(text))) found.push(index + 1);
10789
+ });
10790
+ return found;
10423
10791
  }
10424
- const runnerBudget = {
10425
- id: "runner-budget",
10426
- title: "Each matrix has a max-parallel of 3 or less, each workflow has a concurrency group, and each schedule starts at the minute that the repository and the file give.",
10427
- 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.",
10428
- 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.",
10792
+ /** This function gives the value of a `roadmap: <file>` line, or undefined for another line, an empty value or an expression. */
10793
+ function roadmapOfLine(line) {
10794
+ const text = line.trimStart();
10795
+ if (!text.startsWith("roadmap:")) return void 0;
10796
+ let value = text.slice(8);
10797
+ const comment = value.indexOf(" #");
10798
+ if (comment >= 0) value = value.slice(0, comment);
10799
+ value = value.trim();
10800
+ const quote = value.charAt(0);
10801
+ if (value.length >= 2 && (quote === "\"" || quote === "'") && value.endsWith(quote)) value = value.slice(1, -1).trim();
10802
+ if (value === "" || value.includes("${{")) return void 0;
10803
+ return cleanPath(value);
10804
+ }
10805
+ const roadmapParses = {
10806
+ id: "roadmap-parses",
10807
+ title: "Each call of the Pages workflow gives a roadmap, and each roadmap that a workflow gives to the Status page (the input `roadmap`) parses as site-pages reads it.",
10808
+ 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.",
10809
+ 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\".",
10429
10810
  sources: [{
10430
10811
  repo: "private",
10431
- rule: "runner-slots",
10432
- doc: "docs/STRATEGY.md (2026-10-30, the runner slots: a cap of 40, heavy work at most 28)"
10812
+ rule: "fail-closed",
10813
+ doc: "docs/STRATEGY.md (2026-10-30, gates and probes fail closed)"
10433
10814
  }],
10434
- options: {
10435
- maxParallel: {
10436
- type: "number",
10437
- default: 3,
10438
- description: "The largest max-parallel of a matrix."
10439
- },
10440
- minute: {
10441
- type: "boolean",
10442
- default: true,
10443
- description: "When false, the rule does not examine the minute of the schedules."
10444
- },
10445
- grouped: {
10446
- type: "strings",
10447
- default: ["reusable-ai-review.yml", "reusable-codex-review.yml"],
10448
- description: "The shared workflows that give a concurrency group in each of their jobs. A job that calls one needs no group of its own."
10449
- }
10450
- },
10815
+ options: { roadmaps: {
10816
+ type: "strings",
10817
+ default: [],
10818
+ description: "More roadmap files to check: a roadmap that no workflow names with a `roadmap:` key."
10819
+ } },
10451
10820
  check(context, options) {
10452
10821
  const files = context.gitFiles();
10453
10822
  if (files === void 0) return { skipped: "the root is not in a git repository" };
10454
- const workflows = files.filter((path) => WORKFLOW$1.test(path)).sort(byCode);
10455
- if (workflows.length === 0) return { skipped: "the repository has no workflow" };
10456
- const remote = context.git([
10457
- "remote",
10458
- "get-url",
10459
- "origin"
10460
- ]);
10461
- const repository = context.env["GITHUB_REPOSITORY"] ?? (remote === void 0 ? void 0 : repositoryOfRemote(remote));
10462
- const limit = Number(options["maxParallel"]);
10463
- const grouped = Array.isArray(options["grouped"]) ? options["grouped"] : [];
10823
+ const named = [];
10464
10824
  const breaks = [];
10465
- for (const file of workflows) {
10466
- let text;
10467
- try {
10468
- text = readFileSync(join(context.root, file), "utf8");
10469
- } catch {
10825
+ for (const file of files.filter((path) => WORKFLOW.test(path)).sort(byCode)) {
10826
+ const lines = readFileSync(join(context.root, file), "utf8").split(/\r?\n/);
10827
+ lines.forEach((line, index) => {
10828
+ const roadmap = roadmapOfLine(line);
10829
+ if (roadmap !== void 0) named.push({
10830
+ roadmap,
10831
+ file,
10832
+ line: index + 1
10833
+ });
10834
+ });
10835
+ for (const line of callsWithoutRoadmap(lines)) breaks.push({
10836
+ file,
10837
+ line,
10838
+ message: `${file} builds the site with the Pages workflow and gives no roadmap, so the Status page shows no roadmap item.`
10839
+ });
10840
+ }
10841
+ for (const roadmap of options["roadmaps"]) named.push({
10842
+ roadmap: cleanPath(roadmap),
10843
+ file: "the option roadmaps",
10844
+ line: 0
10845
+ });
10846
+ if (named.length === 0 && breaks.length === 0) return { skipped: "no workflow builds a site with the Pages workflow, and no workflow names a roadmap" };
10847
+ const seen = /* @__PURE__ */ new Set();
10848
+ for (const { roadmap, file, line } of named) {
10849
+ if (seen.has(roadmap)) continue;
10850
+ seen.add(roadmap);
10851
+ if (!existsSync(join(context.root, roadmap))) {
10852
+ breaks.push({
10853
+ file: line > 0 ? file : roadmap,
10854
+ ...line > 0 ? { line } : {},
10855
+ message: `${file} names the roadmap ${roadmap}, and the file does not exist.`
10856
+ });
10470
10857
  continue;
10471
10858
  }
10472
- const lines = workflowLines(text);
10473
- breaks.push(...matrixBreaks(file, text, lines, limit), ...concurrencyBreaks(file, text, lines, grouped));
10474
- if (options["minute"] !== false) {
10475
- if (cronLines(text).length > 0 && repository === void 0) breaks.push({
10476
- file,
10477
- message: `${file} has a schedule, and the rule cannot find the repository (GITHUB_REPOSITORY, or a GitHub URL of the remote origin).`
10859
+ try {
10860
+ parseRoadmap(readFileSync(join(context.root, roadmap), "utf8"), { file: roadmap });
10861
+ } catch (error) {
10862
+ if (!(error instanceof RoadmapParseError)) throw error;
10863
+ const at = /^[^:]+:(\d+): /.exec(error.message);
10864
+ const rest = at ? error.message.slice(at[0].length) : error.message.slice(error.message.indexOf(": ") + 2);
10865
+ breaks.push({
10866
+ file: roadmap,
10867
+ ...at ? { line: Number(at[1]) } : {},
10868
+ message: `${roadmap}: ${rest}`
10478
10869
  });
10479
- else if (repository !== void 0) breaks.push(...cronBreaks(file, text, scheduleMinute(repository, file)));
10480
10870
  }
10481
10871
  }
10482
10872
  return breaks;
@@ -11799,10 +12189,12 @@ const RULES = [
11799
12189
  runnerBudget,
11800
12190
  mainRunsFinish,
11801
12191
  pushMainOnly,
12192
+ pipeFails,
11802
12193
  gateTrigger,
11803
12194
  homePackage,
11804
12195
  licenseFile,
11805
12196
  pagesSite,
12197
+ pagesAfterRelease,
11806
12198
  sharedDocs
11807
12199
  ];
11808
12200
  // src/run.ts
@@ -12235,6 +12627,6 @@ function runMap(args, io) {
12235
12627
  else io.stdout(mapText(found));
12236
12628
  return 0;
12237
12629
  }
12238
- export { pagesCalls as $, defaultOptions as $t, repositoryOfRemote as A, gateTrigger as At, publishedMinorRule as B, inFolder as Bt, isSourcePath as C, mapMarkdown as Ct, blockHash as D, HOME_EXPORTS as Dt, HOME_TIMEOUT_MS as E, readOverlay as Et, requiredScripts as F, cuePreset as Ft, npmLookup as G, readJsonc as Gt, NPM_REGISTRY as H, lineOf as Ht, releaseFiles as I, DEPENDENCY_FIELDS as It, pushMainOnly as J, specifiersOf as Jt, unreleasedChange as K, replaceLine as Kt, lockedVersions as L, cleanPath as Lt, scheduleMinute as M, summaryName as Mt, roadmapOfLine as N, readWorkflow as Nt, githubFetch as O, ACTIONS_COMMIT as Ot, roadmapParses as P, STRICT_OPTIONS as Pt, PAGES_WORKFLOWS as Q, workspaceGlobs as Qt, minorOf as R, codePackages as Rt, tsconfigTest as S, findHomes as St, sourceMain as T, mergeHomes as Tt, SHIPPED_FIELDS as U, matchesAny as Ut, reachOf as V, keyLine as Vt, UNSHIPPED_FILES as W, parseJsonc as Wt, isPinned as X, globToRegExp as Xt, isGitSpecifier as Y, globFolders as Yt, pinnedGitDeps as Z, packageFolders as Zt, configsOfScript as _, messageOf as _t, listRules as a, noBuildOutput as at, testsRequired as b, HOMES as bt, runCli as c, mainCheck as ct, RULES as d, licenseFile as dt, parseConfig as en, pagesSite as et, workspaceProtocol as f, licenseFileOf as ft, typedScripts as g, homePackage as gt, trustPolicy as h, declaredName as ht, formatResult as i, noLocalPaths as it, runnerBudget as j, prPathFilters as jt, sharedDocsRule as k, convertGate as kt, runFix as l, LICENSE_TEXTS as lt, TRAIN_SCOPES as m, repositoryIsPublic as mt, annotations as n, DEFAULT_ALLOWED as nt, readConfig as o, REAL_COMPARE as ot, IGNORE_AFTER as p, mitText as pt, unreleasedChangeRule as q, runGit as qt, createContext as r, HOME_PATTERNS as rt, runChecks as s, hasImportMetaMain as st, USAGE as t, apiReportScript as tt, summaryMarkdown as u, authorOf as ut, scriptsOf as v, repoOf as vt, pathsOf as w, mapText as wt, hasTests as x, MAP_RULE as xt, typedFiles as y, signaturesOf as yt, publishedMinor as z, hasFile as zt };
12630
+ export { pushMainOnly as $, packageFolders as $t, roadmapOfLine as A, ACTIONS_COMMIT as At, SHIPPED_FIELDS as B, codePackages as Bt, isSourcePath as C, MAP_RULE as Ct, blockHash as D, mergeHomes as Dt, HOME_TIMEOUT_MS as E, mapText as Et, minorOf as F, readWorkflow as Ft, pipeFails as G, matchesAny as Gt, npmLookup as H, inFolder as Ht, publishedMinor as I, STRICT_OPTIONS as It, pinnedGitDeps as J, replaceLine as Jt, isGitSpecifier as K, parseJsonc as Kt, publishedMinorRule as L, cuePreset as Lt, requiredScripts as M, gateTrigger as Mt, releaseFiles as N, prPathFilters as Nt, githubFetch as O, readOverlay as Ot, lockedVersions as P, summaryName as Pt, scheduleMinute as Q, globToRegExp as Qt, reachOf as R, DEPENDENCY_FIELDS as Rt, tsconfigTest as S, HOMES as St, sourceMain as T, mapMarkdown as Tt, unreleasedChange as U, keyLine as Ut, UNSHIPPED_FILES as V, hasFile as Vt, unreleasedChangeRule as W, lineOf as Wt, repositoryOfRemote as X, specifiersOf as Xt, pagesAfterRelease as Y, runGit as Yt, runnerBudget as Z, globFolders as Zt, configsOfScript as _, declaredName as _t, listRules as a, HOME_PATTERNS as at, testsRequired as b, repoOf as bt, runCli as c, REAL_COMPARE as ct, RULES as d, LICENSE_TEXTS as dt, workspaceGlobs as en, PAGES_WORKFLOWS as et, workspaceProtocol as f, authorOf as ft, typedScripts as g, repositoryIsPublic as gt, trustPolicy as h, mitText as ht, formatResult as i, DEFAULT_ALLOWED as it, roadmapParses as j, convertGate as jt, sharedDocsRule as k, HOME_EXPORTS as kt, runFix as l, hasImportMetaMain as lt, TRAIN_SCOPES as m, licenseFileOf as mt, annotations as n, parseConfig as nn, pagesSite as nt, readConfig as o, noLocalPaths as ot, IGNORE_AFTER as p, licenseFile as pt, isPinned as q, readJsonc as qt, createContext as r, apiReportScript as rt, runChecks as s, noBuildOutput as st, USAGE as t, defaultOptions as tn, pagesCalls as tt, summaryMarkdown as u, mainCheck as ut, scriptsOf as v, homePackage as vt, pathsOf as w, findHomes as wt, hasTests as x, signaturesOf as xt, typedFiles as y, messageOf as yt, NPM_REGISTRY as z, cleanPath as zt };
12239
12631
 
12240
- //# sourceMappingURL=run-D9GKNsry.js.map
12632
+ //# sourceMappingURL=run-BzGyrL7o.js.map