@mark1russell7/conventions 0.18.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.
- package/README.md +3 -0
- package/build/cli.js +1 -1
- package/build/index.d.ts +17 -1
- package/build/index.d.ts.map +1 -1
- package/build/index.js +1 -1
- package/build/{run-C1iqxBTB.js → run-D0ua_8Tj.js} +320 -3
- package/build/run-D0ua_8Tj.js.map +1 -0
- package/package.json +2 -2
- package/build/run-C1iqxBTB.js.map +0 -1
package/README.md
CHANGED
|
@@ -58,6 +58,7 @@ The rules come from the invariants audit of 2026-10-26 (strategy item s38). The
|
|
|
58
58
|
| `license-file` | Each public package has a license field, and a license file with the same license in its own folder. A public repository, or a repository with a public package, has a license file at its root. In a GitHub Actions run, the event file tells if the repository is public, and the option `license` (MIT by default) is the license of a root with no public package. npm packs only the license file of the folder of the package, and GitHub reads only the one of the root: on 2026-11-02 five public repositories showed no license on GitHub while npm said MIT. `conventions fix` writes the missing files. | fleet strategy (2026-11-02). |
|
|
59
59
|
| `home-package` | A change does not add a function with a signature name of another home of the map (for example `median`, `mulberry32` or `writeFileAtomic`). A local copy drifts from the home and splits the fixes. On 2026-11-02 the fleet had 68 local statistics functions in 14 repositories. The rule examines only the lines that the change adds, so the copies that exist do not break. | fleet direction 18 (STRATEGY.md, 2026-11-02). |
|
|
60
60
|
| `pages-site` | A public repository has a workflow that calls the Pages workflow of the template (`mark1russell7/template/.github/workflows/reusable-pages.yml`, any ref), and the call deploys. A call with `deploy: false` makes a test site only. In a GitHub Actions run, the event file tells if the repository is public. Outside a run, the rule shows `skip`. On 2026-11-02 eight public repositories had no site with a Releases page and a Status page. | vex, crawler, client, coeval `pages.yml`. |
|
|
61
|
+
| `shared-docs` | Each lock file `shared.lock.json` names a document in its field `file`. Each shared block of the document (`<!-- shared:<id> -->` to `<!-- /shared:<id> -->`) has the SHA-256 that the lock gives, and the lock has each block. A linked block has its home in another repository. Its lock entry gives `{repo, path, commit, sha256}`, with a full commit. The document has a `<!-- linked:<id> -->` block with the link to the home at that commit, and no copy. In CI, the rule downloads each home and compares the hash. A home that does not answer in 30 seconds is a break. On 2026-11-03 three repositories kept copies of a block whose home in rigor had a different hash. | layout-contract `scripts/check-shared.mjs` (#155). |
|
|
61
62
|
|
|
62
63
|
The rule `release-files` needs the base of the change. On a pull request, the checkout is a merge commit, and the rule reads its two parents (`fetch-depth` 2 or more). In other runs, give `--base <ref>`. Without a base, the rule shows `skip`. The rule also needs each commit of the change. A shallow checkout can end inside the change. Then the authors and the messages that the rule reads are not those of the change, so the rule shows `error`. A pull request of one commit is complete at depth 2. For a longer one, the CI of the template deepens the checkout to the merge base.
|
|
63
64
|
|
|
@@ -123,6 +124,8 @@ An unknown rule, an unknown option, or an exception or a changed option without
|
|
|
123
124
|
| `runner-budget.grouped` | `["reusable-ai-review.yml", "reusable-codex-review.yml"]` | The shared workflows that give a concurrency group in each of their jobs. |
|
|
124
125
|
| `gate-trigger.allow` | `[]` | The file names of the workflows that can filter pull requests by path, because they are not a gate (for example a preview). |
|
|
125
126
|
| `home-package.scope` | `"change"` | `"change"`: only the lines that a pull request or `--base` adds. `"all"`: each line of each tracked file, for a sweep of the copies that exist. |
|
|
127
|
+
| `shared-docs.locks` | `[]` | The lock files to check. With no value, the rule checks each tracked file `shared.lock.json`. |
|
|
128
|
+
| `shared-docs.remote` | `"ci"` | When the rule downloads the homes of the linked blocks: `"ci"` (only when `CI` is `"true"`), `"always"` or `"never"`. |
|
|
126
129
|
|
|
127
130
|
## Commands
|
|
128
131
|
|
package/build/cli.js
CHANGED
package/build/index.d.ts
CHANGED
|
@@ -288,6 +288,22 @@ export declare function scheduleMinute(repository: string, file: string): number
|
|
|
288
288
|
/** This function gives `owner/name` from a git remote URL, or undefined for a URL that is not of GitHub. */
|
|
289
289
|
export declare function repositoryOfRemote(url: string): string | undefined;
|
|
290
290
|
export declare const runnerBudget: Rule;
|
|
291
|
+
/** The answer for one URL: the text of the file, or the reason why there is no text. */
|
|
292
|
+
type HomeAnswer = {
|
|
293
|
+
readonly text: string;
|
|
294
|
+
} | {
|
|
295
|
+
readonly error: string;
|
|
296
|
+
};
|
|
297
|
+
/** A function that downloads each URL, and gives the answer for each URL. */
|
|
298
|
+
type HomeFetch = (urls: readonly string[]) => ReadonlyMap<string, HomeAnswer>;
|
|
299
|
+
/** The time in milliseconds that the rule waits for one home. A home that does not answer in this time is a break. */
|
|
300
|
+
export declare const HOME_TIMEOUT_MS = 3e4;
|
|
301
|
+
/** This function downloads each URL in one child process of Node. Each download stops after `HOME_TIMEOUT_MS`. */
|
|
302
|
+
export declare const githubFetch: HomeFetch;
|
|
303
|
+
/** This function gives the SHA-256 of the lines of a block: the lines with LF line ends, and a last LF. */
|
|
304
|
+
export declare const blockHash: (body: readonly string[]) => string;
|
|
305
|
+
/** This function makes the rule with the download function `fetchHomes`. The tests give a fake function. */
|
|
306
|
+
export declare function sharedDocsRule(fetchHomes?: HomeFetch): Rule;
|
|
291
307
|
/** This function gives each path in the value of an entry field (a string, or the strings in an object). */
|
|
292
308
|
export declare function pathsOf(value: unknown): string[];
|
|
293
309
|
/** This function tells if a path is a source file: a file in `src/`, or a TypeScript file that is not a declaration file. */
|
|
@@ -440,5 +456,5 @@ export declare function workspaceGlobs(root: string): string[] | undefined;
|
|
|
440
456
|
* The result has absolute paths, in the order of the code units.
|
|
441
457
|
*/
|
|
442
458
|
export declare function packageFolders(root: string, globs?: readonly string[] | undefined): string[];
|
|
443
|
-
export type { AuditSource, Break, CheckOptions, CheckResult, CliIo, ConventionsConfig, Edit, FixResult, Home, HomeState, Manifest, OptionSpec, OptionValue, Options, PackageInfo, PagesCall, PathFilter, RegistryAnswer, RegistryLookup, Rule, RuleConfig, RuleContext, RuleOutcome, RuleResult };
|
|
459
|
+
export type { AuditSource, Break, CheckOptions, CheckResult, CliIo, ConventionsConfig, Edit, FixResult, Home, HomeAnswer, HomeFetch, HomeState, Manifest, OptionSpec, OptionValue, Options, PackageInfo, PagesCall, PathFilter, RegistryAnswer, RegistryLookup, Rule, RuleConfig, RuleContext, RuleOutcome, RuleResult };
|
|
444
460
|
//# sourceMappingURL=index.d.ts.map
|
package/build/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","names":[],"sources":["../src/rule.ts","../src/config.ts","../src/rules/cue-preset.ts","../src/rules/gate-trigger.ts","../src/map.ts","../src/rules/home-package.ts","../src/rules/license-file.ts","../src/rules/main-check.ts","../src/rules/no-build-output.ts","../src/rules/no-local-paths.ts","../src/rules/pages-site.ts","../src/rules/pinned-git-deps.ts","../src/rules/release-files.ts","../src/rules/required-scripts.ts","../src/rules/roadmap-parses.ts","../src/rules/runner-budget.ts","../src/rules/source-main.ts","../src/rules/tests-required.ts","../src/rules/tsconfig-test.ts","../src/rules/typed-files.ts","../src/rules/typed-scripts.ts","../src/rules/trust-policy.ts","../src/rules/unreleased-change.ts","../src/rules/workspace-protocol.ts","../src/rules/index.ts","../src/home-exports.ts","../src/run.ts","../src/workspace.ts"],"mappings":";UASiB;WACN;WACA;WACA;;;UAIM;;WAEN;;WAEA;WACA;;WAEA;;WAEA,iBAAiB;;;;;;UAOX;;WAEN;;WAEA;;WAEA;;;wBAIK,YAAY,cAAc,cAAc;;KAQ5C;;KAGA,UAAU,SAAS,eAAe;;UAG7B;WACN;WACA,SAAS;WACT;;;KAIC,WAAW,SAAS;;UAGf;;WAEN;;WAEA;;WAEA;;WAEA;WACA,UAAU;;;UAIJ;;WAEN;;WAEA,aAAa;;WAEb,mBAAmB;;WAEnB,KAAK,SAAS;;WAEd;;EAET;;EAEA,IAAI;;;KAIM,uBAAuB;WAAqB;;;UAGvC;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA,kBAAkB;;WAElB,SAAS,SAAS,eAAe;EAC1C,MAAM,SAAS,aAAa,SAAS,UAAU;;;qBAIpC;;wBAGG,aAAa,UAAU,UAAU;;wBAOjC,OAAO,cAAc,gBAAgB;;wBAOrC,QAAQ,cAAc,eAAe;;qBAMxC,WAAY,gBAAgB;;qBAG5B,YAAa;;wBAGV,WAAW,cAAc;;;;;;wBASzB,WAAW;;wBA2BX,UAAU;;wBAUV,OAAO,cAAc;;qBAOxB,UAAW,aAAa;;;;;wBAMrB,aAAa,SAAS,KAAK,oDAAoD;;UCrM9E;;WAEN;;WAEA;;WAEA;;WAEA,SAAS;;;UAIH;;WAEN;;WAEA,OAAO,SAAS,eAAe;;;wBAW1B,eAAe,MAAM,OAAO;;;;;;;wBAU5B,YAAY,gBAAgB,gBAAgB,SAAS;;qBCnCxD;qBA2FA,WAAW;;UCtFP;WACN;WACA;WACA;;;wBAIK,cAAc,eAAe;;qBAoBhC;;wBAgCG,YAAY;;;;;;;wBAkBZ,YAAY,cAAc,cAAc;EAAoC;;EAAmB;;qBA8IlG,aAAa;;KCtOd;;UAGK;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA,OAAO;;WAEP;;;;;;WAMA;;WAEA;;;qBAIE;;qBAIA,gBAAgB;;wBAmRb,YAAY,wBAAwB;;wBAUpC,WAAW,eAAe,QAAQ,gBAAgB,kBAAkB;;wBAMpE,UAAU,eAAe,iBAAgB,kBAA0B;;wBAkBnE,YAAY,iBAAgB;;wBAW5B,QAAQ,gBAAgB;;UClV9B;WACC,MAAM;WACN,SAAS;;;wBAIJ,aAAa,gBAAgB,SAAS;;wBAKtC,aAAa;;wBAMb,OAAO,SAAS;;wBAShB,UAAU,cAAc,cAAc,MAAM;qBAS/C,aAAa;;qBC1Cb,eAAe,SAAS,eAAe;;wBAQpC,cAAc;;wBAMd,SAAS;;wBAWT,QAAQ,cAAc;;;;;wBA+BtB,mBAAmB,SAAS;qBAW/B,aAAa;;qBC/Db;;wBA6BG,kBAAkB;qBAiFrB,WAAW;qBCxHX,eAAe;;qBCYf;;qBAGA,wBAAwB;qBAOxB,cAAc;;qBChBd;;UAGI;WACN;WACA;;;wBAIK,WAAW,cAAc,gCAAiD;qBAgB7E,WAAW;;wBC5BR,eAAe;;;;;wBAaf,SAAS,cAAc;qBAqB1B,eAAe;qBCVf,cAAc;qBCTd,iBAAiB;;wBCqCd,cAAc;qBAajB,eAAe;;;;;;wBC3DZ,eAAe,oBAAoB;;wBAUnC,mBAAmB;qBAsJtB,cAAc;;
|
|
1
|
+
{"version":3,"file":"index.d.ts","names":[],"sources":["../src/rule.ts","../src/config.ts","../src/rules/cue-preset.ts","../src/rules/gate-trigger.ts","../src/map.ts","../src/rules/home-package.ts","../src/rules/license-file.ts","../src/rules/main-check.ts","../src/rules/no-build-output.ts","../src/rules/no-local-paths.ts","../src/rules/pages-site.ts","../src/rules/pinned-git-deps.ts","../src/rules/release-files.ts","../src/rules/required-scripts.ts","../src/rules/roadmap-parses.ts","../src/rules/runner-budget.ts","../src/rules/shared-docs.ts","../src/rules/source-main.ts","../src/rules/tests-required.ts","../src/rules/tsconfig-test.ts","../src/rules/typed-files.ts","../src/rules/typed-scripts.ts","../src/rules/trust-policy.ts","../src/rules/unreleased-change.ts","../src/rules/workspace-protocol.ts","../src/rules/index.ts","../src/home-exports.ts","../src/run.ts","../src/workspace.ts"],"mappings":"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"}
|
package/build/index.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export {
|
|
1
|
+
export { xt as ACTIONS_COMMIT, Y as DEFAULT_ALLOWED, Ot as DEPENDENCY_FIELDS, pt as HOMES, bt as HOME_EXPORTS, X as HOME_PATTERNS, M as HOME_TIMEOUT_MS, y as IGNORE_AFTER, nt as LICENSE_TEXTS, mt as MAP_RULE, p as NPM_REGISTRY, K as PAGES_WORKFLOWS, $ as REAL_COMPARE, d as RULES, m as SHIPPED_FIELDS, Et as STRICT_OPTIONS, b as TRAIN_SCOPES, h as UNSHIPPED_FILES, t as USAGE, n as annotations, rt as authorOf, N as blockHash, kt as cleanPath, At as codePackages, C as configsOfScript, St as convertGate, r as createContext, Dt as cuePreset, ct as declaredName, Gt as defaultOptions, ht as findHomes, i as formatResult, Ct as gateTrigger, P as githubFetch, Vt as globFolders, Ht as globToRegExp, jt as hasFile, et as hasImportMetaMain, D as hasTests, lt as homePackage, Mt as inFolder, U as isGitSpecifier, W as isPinned, k as isSourcePath, Nt as keyLine, it as licenseFile, at as licenseFileOf, Pt as lineOf, a as listRules, tt as mainCheck, gt as mapMarkdown, _t as mapText, Ft as matchesAny, vt as mergeHomes, ut as messageOf, ot as mitText, Q as noBuildOutput, Z as noLocalPaths, g as npmLookup, Ut as packageFolders, q as pagesCalls, J as pagesSite, Kt as parseConfig, It as parseJsonc, A as pathsOf, G as pinnedGitDeps, wt as prPathFilters, o as readConfig, Lt as readJsonc, yt as readOverlay, H as releaseFiles, Rt as replaceLine, dt as repoOf, st as repositoryIsPublic, I as repositoryOfRemote, V as requiredScripts, z as roadmapOfLine, B as roadmapParses, s as runChecks, c as runCli, l as runFix, zt as runGit, L as runnerBudget, R as scheduleMinute, w as scriptsOf, F as sharedDocsRule, ft as signaturesOf, j as sourceMain, Bt as specifiersOf, u as summaryMarkdown, Tt as summaryName, E as testsRequired, x as trustPolicy, O as tsconfigTest, T as typedFiles, S as typedScripts, _ as unreleasedChange, v as unreleasedChangeRule, Wt as workspaceGlobs, f as workspaceProtocol } from "./run-D0ua_8Tj.js";
|
|
@@ -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 = [
|
|
@@ -8454,6 +8455,321 @@ const runnerBudget = {
|
|
|
8454
8455
|
return breaks;
|
|
8455
8456
|
}
|
|
8456
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();
|
|
8457
8773
|
// src/rules/source-main.ts
|
|
8458
8774
|
/**
|
|
8459
8775
|
* The rule `source-main`: a workspace package is a source package, and a public package moves its
|
|
@@ -9721,7 +10037,8 @@ const RULES = [
|
|
|
9721
10037
|
gateTrigger,
|
|
9722
10038
|
homePackage,
|
|
9723
10039
|
licenseFile,
|
|
9724
|
-
pagesSite
|
|
10040
|
+
pagesSite,
|
|
10041
|
+
sharedDocs
|
|
9725
10042
|
];
|
|
9726
10043
|
// src/run.ts
|
|
9727
10044
|
/**
|
|
@@ -10117,6 +10434,6 @@ function runMap(args, io) {
|
|
|
10117
10434
|
else io.stdout(mapText(found));
|
|
10118
10435
|
return 0;
|
|
10119
10436
|
}
|
|
10120
|
-
export {
|
|
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 };
|
|
10121
10438
|
|
|
10122
|
-
//# sourceMappingURL=run-
|
|
10439
|
+
//# sourceMappingURL=run-D0ua_8Tj.js.map
|