@mark1russell7/conventions 0.17.0 → 0.19.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.
@@ -2,6 +2,7 @@ import { createRequire } from "node:module";
2
2
  import { spawnSync } from "node:child_process";
3
3
  import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
4
4
  import { basename, dirname, extname, join, posix, relative, resolve, sep } from "node:path";
5
+ import { createHash } from "node:crypto";
5
6
  // src/config.ts
6
7
  /** The fields of the configuration of a rule that are not options. */
7
8
  const RULE_FIELDS = [
@@ -854,8 +855,41 @@ const gateTrigger = {
854
855
  }
855
856
  };
856
857
  // src/change.ts
857
- /** This function gives the range of the change: the option `--base`, or the merge commit of a pull request. */
858
- function rangeOf(context) {
858
+ /**
859
+ * The change that a check examines: the option `--base`, the merge commit of a pull request, or a push to the default
860
+ * branch. The rule release-files reads its changed files, and the runner reads the files that it adds.
861
+ */
862
+ /** This function gives the range of the commits of a push to the default branch, from the event file of GitHub Actions. */
863
+ function pushRange(context) {
864
+ const file = context.env["GITHUB_EVENT_PATH"];
865
+ let event;
866
+ try {
867
+ event = file === void 0 || file === "" || !existsSync(file) ? void 0 : JSON.parse(readFileSync(file, "utf8"));
868
+ } catch {
869
+ event = void 0;
870
+ }
871
+ if (event === void 0) return { skipped: "the push has no event file (GITHUB_EVENT_PATH)" };
872
+ const branch = event.repository?.default_branch;
873
+ if (typeof branch !== "string" || event.ref !== `refs/heads/${branch}`) return { skipped: "the push is not to the default branch: the pull request of the branch has the change" };
874
+ const before = typeof event.before === "string" ? event.before : "";
875
+ if (!/^[0-9a-f]{40,64}$/.test(before) || /^0+$/.test(before)) return { skipped: "the push has no commit before it" };
876
+ if (context.git([
877
+ "rev-parse",
878
+ "--verify",
879
+ "--quiet",
880
+ `${before}^{commit}`
881
+ ]) === void 0) return { skipped: `the checkout does not have ${before}, the commit before the push: fetch it, or set fetch-depth to 0` };
882
+ return {
883
+ diff: [before, "HEAD"],
884
+ log: [`${before}..HEAD`],
885
+ ends: [before, "HEAD"]
886
+ };
887
+ }
888
+ /**
889
+ * This function gives the range of the change: the option `--base`, or the merge commit of a pull request. With the
890
+ * option `push`, a push to the default branch gives the commits of the push: from the commit before the push to HEAD.
891
+ */
892
+ function rangeOf(context, options = {}) {
859
893
  if (context.base !== void 0) {
860
894
  if (context.git([
861
895
  "rev-parse",
@@ -870,6 +904,7 @@ function rangeOf(context) {
870
904
  };
871
905
  }
872
906
  const event = context.env["GITHUB_EVENT_NAME"];
907
+ if (event === "push" && options.push === true) return pushRange(context);
873
908
  if (event !== "pull_request" && event !== "pull_request_target") return { skipped: "no base: the rule runs on a pull request, or with --base <ref>" };
874
909
  if ((context.git([
875
910
  "rev-list",
@@ -8420,6 +8455,321 @@ const runnerBudget = {
8420
8455
  return breaks;
8421
8456
  }
8422
8457
  };
8458
+ // src/rules/shared-docs.ts
8459
+ /**
8460
+ * The rule `shared-docs`: each shared block of a document agrees with its lock, and each linked block points to its
8461
+ * home at a pinned commit.
8462
+ */
8463
+ /** The time in milliseconds that the rule waits for one home. A home that does not answer in this time is a break. */
8464
+ const HOME_TIMEOUT_MS = 3e4;
8465
+ /** The script that `githubFetch` starts in a child process of Node, so that the rule stays synchronous. */
8466
+ const FETCH_SCRIPT = `
8467
+ const [timeout, ...urls] = process.argv.slice(1);
8468
+ Promise.all(urls.map(async (url) => {
8469
+ try {
8470
+ const response = await fetch(url, { signal: AbortSignal.timeout(Number(timeout)) });
8471
+ if (!response.ok) return [url, { error: "HTTP " + response.status }];
8472
+ return [url, { text: await response.text() }];
8473
+ } catch (error) {
8474
+ return [url, { error: String(error && error.message ? error.message : error) }];
8475
+ }
8476
+ })).then((entries) => process.stdout.write(JSON.stringify(Object.fromEntries(entries))));
8477
+ `;
8478
+ /** This function downloads each URL in one child process of Node. Each download stops after `HOME_TIMEOUT_MS`. */
8479
+ const githubFetch = (urls) => {
8480
+ const fail = (error) => new Map(urls.map((url) => [url, { error }]));
8481
+ if (urls.length === 0) return /* @__PURE__ */ new Map();
8482
+ const result = spawnSync(process.execPath, [
8483
+ "-e",
8484
+ FETCH_SCRIPT,
8485
+ String(HOME_TIMEOUT_MS),
8486
+ ...urls
8487
+ ], {
8488
+ encoding: "utf8",
8489
+ timeout: 4e4,
8490
+ maxBuffer: 67108864,
8491
+ windowsHide: true
8492
+ });
8493
+ if (result.error !== void 0 || result.status !== 0) return fail(result.error?.message ?? `the download ended with exit code ${String(result.status)}`);
8494
+ try {
8495
+ const answers = JSON.parse(result.stdout);
8496
+ return new Map(urls.map((url) => [url, answers[url] ?? { error: "no answer" }]));
8497
+ } catch {
8498
+ return fail("the download gave no JSON");
8499
+ }
8500
+ };
8501
+ /** This function gives the SHA-256 of the lines of a block: the lines with LF line ends, and a last LF. */
8502
+ const blockHash = (body) => createHash("sha256").update(`${body.join("\n")}\n`).digest("hex");
8503
+ /**
8504
+ * This function reads the blocks of one kind (`shared` or `linked`) of a text. A block is the text between
8505
+ * `<!-- <kind>:<id> -->` and `<!-- /<kind>:<id> -->`, each alone on its line.
8506
+ */
8507
+ function blocksOf(text, kind, problems) {
8508
+ const lines = text.replace(/\r\n/g, "\n").split("\n");
8509
+ const blocks = /* @__PURE__ */ new Map();
8510
+ const start = new RegExp(`^<!-- ${kind}:([a-z0-9-]+) -->$`);
8511
+ const end = new RegExp(`^<!-- /${kind}:([a-z0-9-]+) -->$`);
8512
+ const loose = new RegExp(`^\\s*<!-- /?${kind}:`);
8513
+ let open;
8514
+ let body = [];
8515
+ lines.forEach((line, index) => {
8516
+ const s = start.exec(line);
8517
+ const e = end.exec(line);
8518
+ if (s) {
8519
+ if (open !== void 0) problems.push({
8520
+ line: index + 1,
8521
+ message: `the ${kind} block "${s[1] ?? ""}" starts inside the block "${open.id}".`
8522
+ });
8523
+ open = {
8524
+ id: s[1] ?? "",
8525
+ line: index + 1
8526
+ };
8527
+ body = [];
8528
+ } else if (e) {
8529
+ if (open === void 0 || open.id !== e[1]) problems.push({
8530
+ line: index + 1,
8531
+ message: `the end of "${e[1] ?? ""}" does not close the open block "${open?.id ?? "(none)"}".`
8532
+ });
8533
+ else if (blocks.has(open.id)) problems.push({
8534
+ line: index + 1,
8535
+ message: `the ${kind} block "${open.id}" occurs two times.`
8536
+ });
8537
+ else blocks.set(open.id, {
8538
+ body,
8539
+ line: open.line
8540
+ });
8541
+ open = void 0;
8542
+ } else if (open !== void 0) body.push(line);
8543
+ else if (loose.test(line)) problems.push({
8544
+ line: index + 1,
8545
+ message: `a ${kind} marker must be alone on its line.`
8546
+ });
8547
+ });
8548
+ if (open !== void 0) problems.push({
8549
+ line: open.line,
8550
+ message: `the ${kind} block "${open.id}" has no end marker.`
8551
+ });
8552
+ return blocks;
8553
+ }
8554
+ const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
8555
+ const linkOf = (l) => `https://github.com/${l.repo}/blob/${l.commit}/${l.path}`;
8556
+ const rawOf = (l) => `https://raw.githubusercontent.com/${l.repo}/${l.commit}/${l.path}`;
8557
+ /** This function tells if the rule downloads the homes, from the option `remote` and the environment. */
8558
+ function downloads(remote, env) {
8559
+ if (remote === "always") return true;
8560
+ if (remote === "never") return false;
8561
+ return env["CI"] === "true";
8562
+ }
8563
+ /** This function makes the rule with the download function `fetchHomes`. The tests give a fake function. */
8564
+ function sharedDocsRule(fetchHomes = githubFetch) {
8565
+ return {
8566
+ id: "shared-docs",
8567
+ title: "Each shared block of a document agrees with its lock file, and each linked block has the link to its home at the pinned commit, with the hash of the home block.",
8568
+ reason: "Three repositories kept copies of the same blocks of docs/PROMOTION.md, each with its own copy of a check script. A change in one copy did not get to the others: on 2026-11-03 the block win-test of three repositories had a hash that the home in rigor did not have. A linked block keeps one copy, in its home, and pins the commit, so a change of the home is a deliberate update of the lock.",
8569
+ fix: "Make the block agree with the lock, or update the lock in each repository that keeps a copy. For a block with a home in another repository, remove the copy, write `<!-- linked:<id> -->` with the link https://github.com/<repo>/blob/<commit>/<path>, and give `{repo, path, commit, sha256}` in the field \"linked\" of the lock.",
8570
+ sources: [
8571
+ {
8572
+ repo: "layout-contract",
8573
+ rule: "check-shared",
8574
+ doc: "scripts/check-shared.mjs (#155, the linked form of a shared block)"
8575
+ },
8576
+ {
8577
+ repo: "packing",
8578
+ rule: "check-shared",
8579
+ doc: "scripts/check-shared.mjs (the same script)"
8580
+ },
8581
+ {
8582
+ repo: "highways",
8583
+ rule: "check-shared",
8584
+ doc: "scripts/check-shared.mjs (the same script)"
8585
+ }
8586
+ ],
8587
+ options: {
8588
+ locks: {
8589
+ type: "strings",
8590
+ default: [],
8591
+ description: "The lock files to check. With no value, the rule checks each tracked file with the name `shared.lock.json`."
8592
+ },
8593
+ remote: {
8594
+ type: "string",
8595
+ default: "ci",
8596
+ description: "When the rule downloads the home of each linked block and compares its hash: \"ci\" (only when the variable CI is \"true\"), \"always\" or \"never\"."
8597
+ }
8598
+ },
8599
+ check(context, options) {
8600
+ const named = options["locks"];
8601
+ let locks;
8602
+ if (named.length > 0) locks = named.map(cleanPath);
8603
+ else {
8604
+ const files = context.gitFiles();
8605
+ if (files === void 0) return { skipped: "the root is not in a git repository" };
8606
+ locks = files.filter((file) => file === "shared.lock.json" || file.endsWith("/shared.lock.json")).sort(byCode);
8607
+ }
8608
+ if (locks.length === 0) return { skipped: "the repository has no file shared.lock.json" };
8609
+ const breaks = [];
8610
+ const remote = [];
8611
+ for (const lockPath of locks) {
8612
+ if (!existsSync(join(context.root, lockPath))) {
8613
+ breaks.push({
8614
+ file: lockPath,
8615
+ message: `the option locks names ${lockPath}, and the file does not exist.`
8616
+ });
8617
+ continue;
8618
+ }
8619
+ let lockFile;
8620
+ try {
8621
+ lockFile = JSON.parse(readFileSync(join(context.root, lockPath), "utf8"));
8622
+ } catch (error) {
8623
+ breaks.push({
8624
+ file: lockPath,
8625
+ message: `${lockPath} is not JSON: ${error instanceof Error ? error.message : String(error)}`
8626
+ });
8627
+ continue;
8628
+ }
8629
+ if (!isRecord(lockFile)) {
8630
+ breaks.push({
8631
+ file: lockPath,
8632
+ message: `${lockPath} is not a JSON object.`
8633
+ });
8634
+ continue;
8635
+ }
8636
+ if (typeof lockFile["file"] !== "string") {
8637
+ breaks.push({
8638
+ file: lockPath,
8639
+ message: `${lockPath} has no field "file": the document of its blocks.`
8640
+ });
8641
+ continue;
8642
+ }
8643
+ if (!isRecord(lockFile["blocks"]) && !isRecord(lockFile["linked"])) {
8644
+ breaks.push({
8645
+ file: lockPath,
8646
+ message: `${lockPath} has no field "blocks" and no field "linked", so it locks nothing.`
8647
+ });
8648
+ continue;
8649
+ }
8650
+ const lock = isRecord(lockFile["blocks"]) ? lockFile["blocks"] : {};
8651
+ const links = isRecord(lockFile["linked"]) ? lockFile["linked"] : {};
8652
+ const doc = cleanPath(lockFile["file"]);
8653
+ if (!existsSync(join(context.root, doc))) {
8654
+ breaks.push({
8655
+ file: lockPath,
8656
+ message: `${lockPath} locks the blocks of ${doc}, and the file does not exist.`
8657
+ });
8658
+ continue;
8659
+ }
8660
+ const problems = [];
8661
+ const text = readFileSync(join(context.root, doc), "utf8");
8662
+ const shared = blocksOf(text, "shared", problems);
8663
+ const linked = blocksOf(text, "linked", problems);
8664
+ for (const p of problems) breaks.push({
8665
+ file: doc,
8666
+ ...p.line !== void 0 ? { line: p.line } : {},
8667
+ message: p.message
8668
+ });
8669
+ for (const [id, hash] of Object.entries(lock).sort(([a], [b]) => byCode(a, b))) {
8670
+ const block = shared.get(id);
8671
+ if (block === void 0) breaks.push({
8672
+ file: doc,
8673
+ message: `the shared block "${id}" of ${lockPath} is missing in ${doc}.`
8674
+ });
8675
+ else if (blockHash(block.body) !== hash) breaks.push({
8676
+ file: doc,
8677
+ line: block.line,
8678
+ message: `the shared block "${id}" differs from ${lockPath}: its hash is ${blockHash(block.body)}.`
8679
+ });
8680
+ }
8681
+ for (const [id, block] of shared) if (!(id in lock)) breaks.push({
8682
+ file: doc,
8683
+ line: block.line,
8684
+ message: `the shared block "${id}" is not in ${lockPath}.`
8685
+ });
8686
+ for (const [id, value] of Object.entries(links).sort(([a], [b]) => byCode(a, b))) {
8687
+ if (!isRecord(value)) {
8688
+ breaks.push({
8689
+ file: lockPath,
8690
+ message: `the linked block "${id}" of ${lockPath} is not an object {repo, path, commit, sha256}.`
8691
+ });
8692
+ continue;
8693
+ }
8694
+ const entry = {
8695
+ repo: String(value["repo"] ?? ""),
8696
+ path: String(value["path"] ?? ""),
8697
+ commit: String(value["commit"] ?? ""),
8698
+ sha256: String(value["sha256"] ?? "")
8699
+ };
8700
+ const before = breaks.length;
8701
+ if (!/^[\w.-]+\/[\w.-]+$/.test(entry.repo)) breaks.push({
8702
+ file: lockPath,
8703
+ message: `the linked block "${id}" needs a repository "<owner>/<name>", not "${entry.repo}".`
8704
+ });
8705
+ if (entry.path === "") breaks.push({
8706
+ file: lockPath,
8707
+ message: `the linked block "${id}" needs the path of its file in the home.`
8708
+ });
8709
+ if (!/^[0-9a-f]{40}$/.test(entry.commit)) breaks.push({
8710
+ file: lockPath,
8711
+ message: `the linked block "${id}" needs a full commit of 40 hex digits, not "${entry.commit}".`
8712
+ });
8713
+ if (!/^[0-9a-f]{64}$/.test(entry.sha256)) breaks.push({
8714
+ file: lockPath,
8715
+ message: `the linked block "${id}" needs a SHA-256 of 64 hex digits.`
8716
+ });
8717
+ const copy = shared.get(id);
8718
+ if (copy !== void 0) breaks.push({
8719
+ file: doc,
8720
+ line: copy.line,
8721
+ message: `the linked block "${id}" also has a copy in ${doc}. Remove the copy.`
8722
+ });
8723
+ const block = linked.get(id);
8724
+ if (block === void 0) breaks.push({
8725
+ file: doc,
8726
+ message: `the linked block "${id}" of ${lockPath} has no "<!-- linked:${id} -->" block in ${doc}.`
8727
+ });
8728
+ else if (!block.body.join("\n").includes(linkOf(entry))) breaks.push({
8729
+ file: doc,
8730
+ line: block.line,
8731
+ message: `the linked block "${id}" does not contain the link ${linkOf(entry)}.`
8732
+ });
8733
+ if (breaks.length === before) remote.push({
8734
+ lock: lockPath,
8735
+ id,
8736
+ entry
8737
+ });
8738
+ }
8739
+ for (const [id, block] of linked) if (!(id in links)) breaks.push({
8740
+ file: doc,
8741
+ line: block.line,
8742
+ message: `the linked block "${id}" is not in the field "linked" of ${lockPath}.`
8743
+ });
8744
+ }
8745
+ if (remote.length > 0 && downloads(String(options["remote"]), context.env)) {
8746
+ const answers = fetchHomes([...new Set(remote.map(({ entry }) => rawOf(entry)))]);
8747
+ for (const { lock, id, entry } of remote) {
8748
+ const url = rawOf(entry);
8749
+ const answer = answers.get(url) ?? { error: "no answer" };
8750
+ if ("error" in answer) {
8751
+ breaks.push({
8752
+ file: lock,
8753
+ message: `the home of the linked block "${id}" did not answer at ${url}: ${answer.error}.`
8754
+ });
8755
+ continue;
8756
+ }
8757
+ const home = blocksOf(answer.text, "shared", []).get(id);
8758
+ if (home === void 0) breaks.push({
8759
+ file: lock,
8760
+ message: `the home ${url} has no shared block "${id}".`
8761
+ });
8762
+ else if (blockHash(home.body) !== entry.sha256) breaks.push({
8763
+ file: lock,
8764
+ message: `the linked block "${id}" at ${url} has the hash ${blockHash(home.body)}, not the hash of ${lock}.`
8765
+ });
8766
+ }
8767
+ }
8768
+ return breaks;
8769
+ }
8770
+ };
8771
+ }
8772
+ const sharedDocs = sharedDocsRule();
8423
8773
  // src/rules/source-main.ts
8424
8774
  /**
8425
8775
  * The rule `source-main`: a workspace package is a source package, and a public package moves its
@@ -9333,6 +9683,273 @@ const trustPolicy = {
9333
9683
  return breaks;
9334
9684
  }
9335
9685
  };
9686
+ // src/rules/unreleased-change.ts
9687
+ /**
9688
+ * The rule `unreleased-change`: a change does not set a version that npm has. With the option `versionEachChange`, a
9689
+ * change of the files that a published package ships also raises its version. Else the release skips the change.
9690
+ */
9691
+ /** The registry of npm. */
9692
+ const NPM_REGISTRY = "https://registry.npmjs.org";
9693
+ /** The globs of the files of a package, relative to its folder, that do not ship: tests, fixtures, docs and configs. */
9694
+ const UNSHIPPED_FILES = [
9695
+ "**/*.md",
9696
+ "**/*.{test,spec}.*",
9697
+ "**/{test,tests,__tests__,fixtures,__fixtures__,__snapshots__,bench,benches,benchmarks,e2e}/**",
9698
+ "**/*.{bench,e2e}.*",
9699
+ "**/.*/**",
9700
+ "**/tsconfig*.json",
9701
+ "**/*.config.*",
9702
+ "docs/**",
9703
+ "examples/**",
9704
+ "scripts/**",
9705
+ "site/**",
9706
+ "LICENSE*",
9707
+ "pnpm-lock.yaml",
9708
+ "pnpm-workspace.yaml"
9709
+ ];
9710
+ /** The fields of `package.json` that change what the package gives to a user. A change of the dependencies is not here. */
9711
+ const SHIPPED_FIELDS = [
9712
+ "main",
9713
+ "module",
9714
+ "types",
9715
+ "typings",
9716
+ "exports",
9717
+ "imports",
9718
+ "bin",
9719
+ "files",
9720
+ "type",
9721
+ "publishConfig",
9722
+ "sideEffects",
9723
+ "browser"
9724
+ ];
9725
+ /** The script that `npmLookup` starts in a child process of Node, so that the rule stays synchronous. */
9726
+ const LOOKUP_SCRIPT = `
9727
+ const [registry, ...names] = process.argv.slice(1);
9728
+ let base = registry;
9729
+ while (base.endsWith("/")) base = base.slice(0, -1);
9730
+ Promise.all(names.map(async (name) => {
9731
+ try {
9732
+ const response = await fetch(base + "/" + name.replace("/", "%2f"), { headers: { accept: "application/json" }, signal: AbortSignal.timeout(20000) });
9733
+ if (response.status === 404) return [name, { versions: [] }];
9734
+ if (!response.ok) return [name, { error: "HTTP " + response.status }];
9735
+ const data = await response.json();
9736
+ const times = Object.fromEntries(Object.entries(data.time ?? {}).filter(([key]) => key !== "created" && key !== "modified"));
9737
+ return [name, { versions: [...new Set([...Object.keys(data.versions ?? {}), ...Object.keys(times)])], times }];
9738
+ } catch (error) {
9739
+ return [name, { error: String(error && error.message ? error.message : error) }];
9740
+ }
9741
+ })).then((entries) => process.stdout.write(JSON.stringify(Object.fromEntries(entries))));
9742
+ `;
9743
+ /**
9744
+ * This function asks the registry for the versions of each package, in one child process of Node. A version that npm
9745
+ * removed stays in the answer, because npm does not accept it again.
9746
+ */
9747
+ const npmLookup = (names, registry) => {
9748
+ const fail = (error) => new Map(names.map((name) => [name, { error }]));
9749
+ if (names.length === 0) return /* @__PURE__ */ new Map();
9750
+ const result = spawnSync(process.execPath, [
9751
+ "-e",
9752
+ LOOKUP_SCRIPT,
9753
+ registry,
9754
+ ...names
9755
+ ], {
9756
+ encoding: "utf8",
9757
+ timeout: 6e4,
9758
+ windowsHide: true
9759
+ });
9760
+ if (result.error !== void 0 || result.status !== 0) return fail(result.error?.message ?? `the lookup ended with exit code ${String(result.status)}`);
9761
+ try {
9762
+ const answers = JSON.parse(result.stdout);
9763
+ return new Map(names.map((name) => [name, answers[name] ?? { error: "no answer" }]));
9764
+ } catch {
9765
+ return fail("the lookup gave no JSON");
9766
+ }
9767
+ };
9768
+ /** This function gives the strings of a field of `package.json` that is a list of strings. */
9769
+ const stringsOf = (manifest, field) => {
9770
+ const value = manifest[field];
9771
+ return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
9772
+ };
9773
+ /** This function tells if a path relative to the root is in the folder `folder`. The root is `""`. */
9774
+ const inside = (folder, path) => folder === "" || path.startsWith(`${folder}/`);
9775
+ /** This function gives the globs of an entry of the field `files`: the entry, and each path under it. */
9776
+ const entryGlobs = (entry) => {
9777
+ let glob = cleanPath(entry);
9778
+ while (glob.endsWith("/")) glob = glob.slice(0, -1);
9779
+ return [glob, `${glob}/**`];
9780
+ };
9781
+ /** This function reads the manifest of the text of a `package.json` file, or gives undefined. */
9782
+ function parseManifest(text) {
9783
+ if (text === void 0) return void 0;
9784
+ try {
9785
+ const parsed = JSON.parse(text);
9786
+ return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : void 0;
9787
+ } catch {
9788
+ return;
9789
+ }
9790
+ }
9791
+ /** This function tells if a version is a placeholder before the first release: `0.0.0` or `0.0.0-<stage>`. */
9792
+ const isPlaceholder = (version) => /^0\.0\.0(?:[-+].*)?$/.test(version);
9793
+ /** The published packages of the repository: the root package and the code packages that are not private and have a name and a version. */
9794
+ function publishedOf(context) {
9795
+ const all = [context.rootPackage, ...codePackages(context)];
9796
+ 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");
9797
+ }
9798
+ /** This function gives the time of the push in milliseconds, from the field `repository.pushed_at` of the event file. */
9799
+ function pushedAt(context) {
9800
+ const file = context.env["GITHUB_EVENT_PATH"];
9801
+ if (file === void 0 || file === "" || !existsSync(file)) return void 0;
9802
+ try {
9803
+ const value = JSON.parse(readFileSync(file, "utf8")).repository?.pushed_at;
9804
+ if (typeof value === "number") return value * 1e3;
9805
+ return typeof value === "string" && !Number.isNaN(Date.parse(value)) ? Date.parse(value) : void 0;
9806
+ } catch {
9807
+ return;
9808
+ }
9809
+ }
9810
+ /** This function gives the shipped files of `pkg` in the list `changed`, relative to the folder of the package. */
9811
+ function shippedFiles(pkg, changed, before, context, unshipped, fields) {
9812
+ const folders = context.packages.map((other) => other.folder).filter((folder) => folder !== "");
9813
+ const own = (path) => inside(pkg.folder, path) && (pkg.folder !== "" || !folders.some((folder) => inside(folder, path)));
9814
+ const relative = (path) => pkg.folder === "" ? path : path.slice(pkg.folder.length + 1);
9815
+ const entries = stringsOf(pkg.manifest, "files");
9816
+ const positive = entries.filter((entry) => !entry.startsWith("!"));
9817
+ const negative = entries.filter((entry) => entry.startsWith("!")).flatMap((entry) => entryGlobs(entry.slice(1)));
9818
+ const ownTracked = (context.gitFiles() ?? []).filter(own).map(relative);
9819
+ const whitelist = positive.length > 0 && positive.every((entry) => ownTracked.some((path) => matchesAny(path, entryGlobs(entry))));
9820
+ const ships = (path) => path !== "package.json" && !matchesAny(path, unshipped) && (!whitelist || positive.some((entry) => matchesAny(path, entryGlobs(entry))) && !matchesAny(path, negative));
9821
+ const files = changed.filter(own).map(relative).filter(ships);
9822
+ if (changed.includes(pkg.file) && before !== void 0 && fields.some((field) => JSON.stringify(before[field]) !== JSON.stringify(pkg.manifest[field]))) files.push("package.json");
9823
+ return files;
9824
+ }
9825
+ /** This function makes the rule with the registry lookup `lookup`. The tests give a fake lookup. */
9826
+ function unreleasedChangeRule(lookup = npmLookup) {
9827
+ return {
9828
+ id: "unreleased-change",
9829
+ title: "A change does not set a version that npm has. With `versionEachChange`, a change of the shipped files also raises the version.",
9830
+ 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).",
9831
+ 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.",
9832
+ sources: [{
9833
+ repo: "rigor",
9834
+ rule: "unreleased-change",
9835
+ doc: "pull requests #18 and #20 (2026-11-02): two pull requests set the same version"
9836
+ }, ...[
9837
+ "crawler",
9838
+ "coeval",
9839
+ "template"
9840
+ ].map((repo) => ({
9841
+ repo,
9842
+ rule: "unreleased-change",
9843
+ doc: ".github/workflows/release.yml (it starts on a change of a version, and it skips each version that npm has)"
9844
+ }))],
9845
+ options: {
9846
+ versionEachChange: {
9847
+ type: "boolean",
9848
+ default: false,
9849
+ 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."
9850
+ },
9851
+ unshipped: {
9852
+ type: "strings",
9853
+ default: UNSHIPPED_FILES,
9854
+ description: "With `versionEachChange`: the globs of the files of a package, relative to its folder, that do not ship."
9855
+ },
9856
+ fields: {
9857
+ type: "strings",
9858
+ default: SHIPPED_FIELDS,
9859
+ description: "With `versionEachChange`: the fields of `package.json` whose change ships. The dependencies are not in the default list."
9860
+ },
9861
+ registry: {
9862
+ type: "string",
9863
+ default: NPM_REGISTRY,
9864
+ description: "The URL of the registry that has the versions."
9865
+ }
9866
+ },
9867
+ check(context, options) {
9868
+ if (hasFile(context.root, ".changeset/config.json")) return { skipped: "the repository uses Changesets: the changesets raise the versions, and the changeset check examines them" };
9869
+ const published = publishedOf(context).filter((pkg) => !isPlaceholder(String(pkg.manifest["version"])));
9870
+ if (published.length === 0) return { skipped: "the repository has no published package with a release version" };
9871
+ const range = rangeOf(context, { push: true });
9872
+ if ("skipped" in range) return range;
9873
+ const strict = options["versionEachChange"] === true;
9874
+ const push = context.base === void 0 && context.env["GITHUB_EVENT_NAME"] === "push";
9875
+ const out = strict ? context.git([
9876
+ "diff",
9877
+ "--name-only",
9878
+ "--no-renames",
9879
+ ...range.diff
9880
+ ]) : "";
9881
+ if (out === void 0) return { skipped: "git cannot give the changed files of the change" };
9882
+ const changed = out.split(/\r?\n/).filter((file) => file !== "");
9883
+ const unshipped = Array.isArray(options["unshipped"]) ? options["unshipped"] : UNSHIPPED_FILES;
9884
+ const fields = Array.isArray(options["fields"]) ? options["fields"] : SHIPPED_FIELDS;
9885
+ const registry = typeof options["registry"] === "string" ? options["registry"] : NPM_REGISTRY;
9886
+ const fork = push ? range.ends[0] : context.git(["merge-base", ...range.ends])?.trim();
9887
+ const notes = [];
9888
+ 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`);
9889
+ const manifestAt = (ref, pkg) => ref === "HEAD" ? pkg.manifest : parseManifest(context.git(["show", `${ref}:${pkg.file}`]));
9890
+ const versionOf = (manifest) => typeof manifest?.["version"] === "string" ? manifest["version"] : void 0;
9891
+ const candidates = [];
9892
+ for (const pkg of published) {
9893
+ const atStart = manifestAt(range.ends[0], pkg);
9894
+ const set = versionOf(manifestAt(range.ends[1], pkg));
9895
+ const before = fork === void 0 ? void 0 : versionOf(fork === range.ends[0] ? atStart : manifestAt(fork, pkg));
9896
+ const sets = fork !== void 0 && set !== void 0 && !isPlaceholder(set) && set !== before ? set : void 0;
9897
+ const files = strict ? shippedFiles(pkg, changed, atStart, context, unshipped, fields) : [];
9898
+ if (sets === void 0 && files.length === 0) continue;
9899
+ candidates.push({
9900
+ pkg,
9901
+ name: String(pkg.manifest["name"]),
9902
+ version: String(pkg.manifest["version"]),
9903
+ sets,
9904
+ start: versionOf(atStart),
9905
+ files
9906
+ });
9907
+ }
9908
+ if (candidates.length === 0) return notes.length > 0 ? { skipped: notes.join("; ") } : [];
9909
+ const answers = lookup(candidates.map((candidate) => candidate.name), registry);
9910
+ const pushTime = push ? pushedAt(context) : void 0;
9911
+ const breaks = [];
9912
+ for (const candidate of candidates) {
9913
+ const answer = answers.get(candidate.name) ?? { error: "no answer" };
9914
+ if ("error" in answer) {
9915
+ notes.push(`the registry did not answer for ${candidate.name}: ${answer.error}`);
9916
+ continue;
9917
+ }
9918
+ const line = lineOf(candidate.pkg.text, "\"version\"");
9919
+ const at = {
9920
+ file: candidate.pkg.file,
9921
+ ...line === void 0 ? {} : { line }
9922
+ };
9923
+ if (candidate.sets !== void 0) {
9924
+ const sets = candidate.sets;
9925
+ if (!answer.versions.includes(sets)) continue;
9926
+ if (push) {
9927
+ const time = Date.parse(answer.times?.[sets] ?? "");
9928
+ if (pushTime === void 0 || Number.isNaN(time)) {
9929
+ notes.push(`the rule cannot tell if npm had ${candidate.name}@${sets} before the push`);
9930
+ continue;
9931
+ }
9932
+ if (time >= pushTime) continue;
9933
+ }
9934
+ breaks.push({
9935
+ ...at,
9936
+ message: `${candidate.name}: the change sets the version ${sets}, but ${sets} is on npm already. Raise the version (SemVer) in a pull request.`
9937
+ });
9938
+ } else if (strict && candidate.files.length > 0 && candidate.start === candidate.version && answer.versions.includes(candidate.version)) {
9939
+ const shown = candidate.files.slice(0, 3).map((file) => candidate.pkg.folder === "" ? file : `${candidate.pkg.folder}/${file}`);
9940
+ const more = candidate.files.length > shown.length ? ` and ${String(candidate.files.length - shown.length)} more` : "";
9941
+ breaks.push({
9942
+ ...at,
9943
+ 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}.`
9944
+ });
9945
+ }
9946
+ }
9947
+ if (breaks.length === 0 && notes.length > 0) return { skipped: notes.join("; ") };
9948
+ return breaks;
9949
+ }
9950
+ };
9951
+ }
9952
+ const unreleasedChange = unreleasedChangeRule();
9336
9953
  // src/rules/workspace-protocol.ts
9337
9954
  /**
9338
9955
  * The rule `workspace-protocol`: a package uses another package of the workspace through `workspace:`.
@@ -9410,6 +10027,7 @@ const RULES = [
9410
10027
  noBuildOutput,
9411
10028
  noLocalPaths,
9412
10029
  releaseFiles,
10030
+ unreleasedChange,
9413
10031
  typedScripts,
9414
10032
  typedFiles,
9415
10033
  mainCheck,
@@ -9419,7 +10037,8 @@ const RULES = [
9419
10037
  gateTrigger,
9420
10038
  homePackage,
9421
10039
  licenseFile,
9422
- pagesSite
10040
+ pagesSite,
10041
+ sharedDocs
9423
10042
  ];
9424
10043
  // src/run.ts
9425
10044
  /**
@@ -9815,6 +10434,6 @@ function runMap(args, io) {
9815
10434
  else io.stdout(mapText(found));
9816
10435
  return 0;
9817
10436
  }
9818
- export { homePackage as $, roadmapParses as A, specifiersOf as At, HOME_PATTERNS as B, isSourcePath as C, keyLine as Ct, runnerBudget as D, readJsonc as Dt, repositoryOfRemote as E, parseJsonc as Et, pinnedGitDeps as F, defaultOptions as Ft, mainCheck as G, noBuildOutput as H, PAGES_WORKFLOWS as I, parseConfig as It, licenseFile as J, LICENSE_TEXTS as K, pagesCalls as L, releaseFiles as M, globToRegExp as Mt, isGitSpecifier as N, packageFolders as Nt, scheduleMinute as O, replaceLine as Ot, isPinned as P, workspaceGlobs as Pt, declaredName as Q, pagesSite as R, tsconfigTest as S, inFolder as St, sourceMain as T, matchesAny as Tt, REAL_COMPARE as U, noLocalPaths as V, hasImportMetaMain as W, mitText as X, licenseFileOf as Y, repositoryIsPublic as Z, configsOfScript as _, cuePreset as _t, listRules as a, findHomes as at, testsRequired as b, codePackages as bt, runCli as c, mergeHomes as ct, RULES as d, ACTIONS_COMMIT as dt, messageOf as et, workspaceProtocol as f, convertGate as ft, typedScripts as g, STRICT_OPTIONS as gt, trustPolicy as h, summaryName as ht, formatResult as i, MAP_RULE as it, requiredScripts as j, globFolders as jt, roadmapOfLine as k, runGit as kt, runFix as l, readOverlay as lt, TRAIN_SCOPES as m, prPathFilters as mt, annotations as n, signaturesOf as nt, readConfig as o, mapMarkdown as ot, IGNORE_AFTER as p, gateTrigger as pt, authorOf as q, createContext as r, HOMES as rt, runChecks as s, mapText as st, USAGE as t, repoOf as tt, summaryMarkdown as u, HOME_EXPORTS as ut, scriptsOf as v, DEPENDENCY_FIELDS as vt, pathsOf as w, lineOf as wt, hasTests as x, hasFile as xt, typedFiles as y, cleanPath as yt, DEFAULT_ALLOWED as z };
10437
+ export { REAL_COMPARE as $, pathsOf as A, codePackages as At, roadmapParses as B, specifiersOf as Bt, configsOfScript as C, gateTrigger as Ct, hasTests as D, cuePreset as Dt, testsRequired as E, STRICT_OPTIONS as Et, sharedDocsRule as F, matchesAny as Ft, pinnedGitDeps as G, defaultOptions as Gt, releaseFiles as H, globToRegExp as Ht, repositoryOfRemote as I, parseJsonc as It, pagesSite as J, PAGES_WORKFLOWS as K, parseConfig as Kt, runnerBudget as L, readJsonc as Lt, HOME_TIMEOUT_MS as M, inFolder as Mt, blockHash as N, keyLine as Nt, tsconfigTest as O, DEPENDENCY_FIELDS as Ot, githubFetch as P, lineOf as Pt, noBuildOutput as Q, scheduleMinute as R, replaceLine as Rt, typedScripts as S, convertGate as St, typedFiles as T, summaryName as Tt, isGitSpecifier as U, packageFolders as Ut, requiredScripts as V, globFolders as Vt, isPinned as W, workspaceGlobs as Wt, HOME_PATTERNS as X, DEFAULT_ALLOWED as Y, noLocalPaths as Z, unreleasedChange as _, mapText as _t, listRules as a, licenseFileOf as at, TRAIN_SCOPES as b, HOME_EXPORTS as bt, runCli as c, declaredName as ct, RULES as d, repoOf as dt, hasImportMetaMain as et, workspaceProtocol as f, signaturesOf as ft, npmLookup as g, mapMarkdown as gt, UNSHIPPED_FILES as h, findHomes as ht, formatResult as i, licenseFile as it, sourceMain as j, hasFile as jt, isSourcePath as k, cleanPath as kt, runFix as l, homePackage as lt, SHIPPED_FIELDS as m, MAP_RULE as mt, annotations as n, LICENSE_TEXTS as nt, readConfig as o, mitText as ot, NPM_REGISTRY as p, HOMES as pt, pagesCalls as q, createContext as r, authorOf as rt, runChecks as s, repositoryIsPublic as st, USAGE as t, mainCheck as tt, summaryMarkdown as u, messageOf as ut, unreleasedChangeRule as v, mergeHomes as vt, scriptsOf as w, prPathFilters as wt, trustPolicy as x, ACTIONS_COMMIT as xt, IGNORE_AFTER as y, readOverlay as yt, roadmapOfLine as z, runGit as zt };
9819
10438
 
9820
- //# sourceMappingURL=run-CyH0BncB.js.map
10439
+ //# sourceMappingURL=run-D0ua_8Tj.js.map