@antelopejs/tooling-configs 0.2.16 → 0.2.18

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.
Files changed (51) hide show
  1. package/README.md +101 -52
  2. package/dist/bin/api-diff.mjs +430 -107
  3. package/dist/bin/body-check.d.mts +1 -0
  4. package/dist/bin/body-check.mjs +344 -0
  5. package/dist/bin/capture.d.mts +1 -0
  6. package/dist/bin/capture.mjs +559 -0
  7. package/dist/bin/check-size.mjs +3 -3
  8. package/dist/bin/checks.mjs +3 -3
  9. package/dist/bin/comment-proof.mjs +4 -3
  10. package/dist/bin/garden.mjs +6 -6
  11. package/dist/bin/ratchet.mjs +316 -10
  12. package/dist/bin/suppressions.mjs +118 -80
  13. package/dist/bin/sync.mjs +554 -153
  14. package/dist/bin/verify.mjs +240 -127
  15. package/dist/capture/index.d.mts +50 -0
  16. package/dist/capture/index.mjs +2 -0
  17. package/dist/{ceilings-BSw9p4YB.mjs → ceilings-B7KayYIG.mjs} +11 -3
  18. package/dist/{checks-BlWDFYio.mjs → checks-CxkSu2E6.mjs} +1 -1
  19. package/dist/{ci-workflow-DIsoEgMd.mjs → ci-workflow-ChW4He0r.mjs} +84 -3
  20. package/dist/{files-2FikHZ9F.mjs → files-DJ0TeaTU.mjs} +11 -5
  21. package/dist/formal/index.d.mts +40 -0
  22. package/dist/formal/index.mjs +205 -0
  23. package/dist/{json-BqvuCkqr.mjs → json-CG2L7YFl.mjs} +12 -8
  24. package/dist/oxc/anti-slop/index.mjs +869 -21
  25. package/dist/oxc/fmt.mjs +1 -1
  26. package/dist/oxc/guardrails/index.d.mts +1 -1
  27. package/dist/oxc/guardrails/index.mjs +736 -4
  28. package/dist/oxc/lint.d.mts +20 -3
  29. package/dist/oxc/lint.mjs +34 -10
  30. package/dist/oxlint-DIV-lLSS.mjs +98 -0
  31. package/dist/{package-Dtjt_lSa.mjs → package-BRTjkzt5.mjs} +29 -3
  32. package/dist/proof-stamp-DDDC0J6l.mjs +279 -0
  33. package/dist/ratchet-BAcLRYuM.mjs +448 -0
  34. package/dist/{renames-BGO4dWJ8.mjs → renames-L2owF5GD.mjs} +2 -2
  35. package/dist/scenes-DZVXkcxS.mjs +104 -0
  36. package/dist/shared-igPpEDpS.mjs +622 -0
  37. package/dist/{size-BVgNbLO6.mjs → size-DBatLT-F.mjs} +4 -4
  38. package/dist/suppression-base-9L8dlMQK.mjs +120 -0
  39. package/dist/suppression-budget-C0SkPO5R.mjs +535 -0
  40. package/dist/{suppressions-BJAngUxo.mjs → suppressions-DM60NkvL.mjs} +180 -18
  41. package/dist/templates-CypDm-j9.mjs +121 -0
  42. package/dist/typescript-CM0LrVP7.mjs +222 -0
  43. package/dist/verify/index.d.mts +6 -1
  44. package/dist/verify/index.mjs +1 -1
  45. package/package.json +31 -5
  46. package/dist/kinds-Bzyyi9yk.mjs +0 -25
  47. package/dist/ratchet-DRdIYwmv.mjs +0 -80
  48. package/dist/shared-CsXIMK3I.mjs +0 -34
  49. package/dist/staged-ratchet-CjoRfZaM.mjs +0 -236
  50. package/dist/suppression-budget-Yyf5_J5l.mjs +0 -283
  51. package/dist/typescript-C54ONh9m.mjs +0 -433
@@ -1,6 +1,6 @@
1
1
  import { existsSync, readFileSync, readdirSync } from "node:fs";
2
2
  import { join } from "node:path";
3
- import { isMap, isPair, isScalar, isSeq, parseDocument, visit } from "yaml";
3
+ import { Scalar, isMap, isPair, isScalar, isSeq, parseDocument, visit } from "yaml";
4
4
  //#region src/guardrails/workflow.ts
5
5
  const CI_NODE_PATTERN = /^AntelopeJS\/\.github\/\.github\/workflows\/ci-node\.yml@\S+$/;
6
6
  const CI_RENOVATE_SYNC_PATTERN = /^AntelopeJS\/\.github\/\.github\/workflows\/ci-renovate-sync\.yml@\S+$/;
@@ -53,6 +53,51 @@ function ciRenovateSyncCallers(text) {
53
53
  return callers(text, CI_RENOVATE_SYNC_PATTERN);
54
54
  }
55
55
  //#endregion
56
+ //#region src/guardrails/workflow-needs.ts
57
+ const NEEDS_REFERENCE = /(?<![\w.'"-])needs(?:\.([A-Za-z_][\w-]*)|\[\s*(['"])([^'"]+)\2\s*\])/g;
58
+ function neededIds(job) {
59
+ const needs = job.get("needs", true);
60
+ return (isSeq(needs) ? needs.items : [needs]).flatMap((entry) => isScalar(entry) ? [String(entry.value)] : []);
61
+ }
62
+ function isText$1(value) {
63
+ return String(value) === value;
64
+ }
65
+ function expressionsOf(job) {
66
+ const expressions = [];
67
+ visit(job, { Scalar(key, node, path) {
68
+ if (key === "key") return;
69
+ const text = node.value;
70
+ if (!isText$1(text)) return;
71
+ const parent = path.at(-1);
72
+ if (isPair(parent) && isScalar(parent.key) && parent.key.value === "if") expressions.push(text);
73
+ else expressions.push(...text.match(/\$\{\{[\s\S]*?\}\}/g) ?? []);
74
+ } });
75
+ return expressions;
76
+ }
77
+ function referencedIds(job) {
78
+ return expressionsOf(job).flatMap((expression) => [...expression.matchAll(NEEDS_REFERENCE)].map(([, dotted, , quoted]) => dotted ?? quoted));
79
+ }
80
+ /**
81
+ * Lists every `needs:` entry naming no job and every `needs.<id>` or `needs['<id>']` read in a job's `if:` or `${{ }}`
82
+ * expressions whose id is not in that job's `needs:`. GitHub evaluates such a read to null, so a gate condition like
83
+ * `needs.checks.result == 'skipped'` silently stops failing once the job it named was renamed.
84
+ */
85
+ function staleNeeds(document, path) {
86
+ const jobs = document.get("jobs", true);
87
+ if (!isMap(jobs)) return [];
88
+ const ids = new Set(jobs.items.flatMap(({ key }) => isScalar(key) ? [String(key.value)] : []));
89
+ const problems = [];
90
+ for (const { key, value: job } of jobs.items) {
91
+ if (!isScalar(key) || !isMap(job)) continue;
92
+ const name = String(key.value);
93
+ const needed = neededIds(job);
94
+ for (const id of needed) if (!ids.has(id)) problems.push(`${path}: job ${name} needs ${id}, but no job ${id} exists. Replace it with the job id it was renamed to (the ci-node.yml caller is ci), then rerun antelopejs-sync --check.`);
95
+ const listed = `[${needed.join(", ")}]`;
96
+ for (const id of new Set(referencedIds(job))) if (!needed.includes(id)) problems.push(`${path}: job ${name} reads needs.${id}, but ${id} is not in its needs: ${listed}, so the read is always null. Read needs.<id> of a job in that list (the ci-node.yml caller is needs.ci), or add ${id} to needs, then rerun antelopejs-sync --check.`);
97
+ }
98
+ return problems;
99
+ }
100
+ //#endregion
56
101
  //#region src/guardrails/ci-workflow.ts
57
102
  const CI_PATH = ".github/workflows/ci.yml";
58
103
  const MUTATION_PATH = ".github/workflows/mutation.yml";
@@ -206,6 +251,38 @@ function skipRenovateSync(document, job) {
206
251
  else job.set("with", document.createNode({ "renovate-sync": false }));
207
252
  return true;
208
253
  }
254
+ function lines(text) {
255
+ return text.split("\n").map((line) => line.trim()).filter(Boolean);
256
+ }
257
+ function normalizePath(path) {
258
+ return path.replace(/^(?:\.\/)+/, "").replace(/\/+$/, "");
259
+ }
260
+ function mergedDocsFiles(current, plan) {
261
+ const computed = new Set(plan.docsFiles);
262
+ const kept = current.map(normalizePath).filter((path) => path && !computed.has(path) && plan.exists(path));
263
+ return [.../* @__PURE__ */ new Set([...plan.docsFiles, ...kept])];
264
+ }
265
+ function setDocsFiles(document, job, plan) {
266
+ const inputs = job.get("with", true);
267
+ const current = isMap(inputs) ? inputs.get("docs-files", true) : void 0;
268
+ const existing = isScalar(current) ? lines(String(current.value)) : [];
269
+ const files = mergedDocsFiles(existing, plan);
270
+ if (isScalar(current) && existing.join("\n") === files.join("\n")) return false;
271
+ const value = new Scalar(`${files.join("\n")}\n`);
272
+ value.type = Scalar.BLOCK_LITERAL;
273
+ if (isMap(inputs)) inputs.set("docs-files", value);
274
+ else job.set("with", document.createNode({ "docs-files": value }));
275
+ return true;
276
+ }
277
+ function setCallersDocsFiles(document, jobs, callers, plan) {
278
+ let changed = false;
279
+ if (!plan?.docsFiles.length) return false;
280
+ for (const { id } of callers) {
281
+ const job = jobs.get(id, true);
282
+ if (isMap(job)) changed = setDocsFiles(document, job, plan) || changed;
283
+ }
284
+ return changed;
285
+ }
209
286
  function canonicalSyncJob() {
210
287
  const job = parseDocument(CI_CALLER).getIn(["jobs", RENOVATE_SYNC_JOB_ID], true);
211
288
  if (!isMap(job)) throw new Error("CI_CALLER has no renovate-sync job");
@@ -236,8 +313,10 @@ function assertNoClash(jobs, callerId, hasSyncCaller) {
236
313
  * dispatchable and read-only, with the Renovate sync it would otherwise run turned off. The write permissions the sync
237
314
  * needs to push and dispatch the caller live on a separate job calling ci-renovate-sync.yml, which is added when missing.
238
315
  * No `uses:` ref is ever rewritten. A workflow with no caller job is repository-specific CI and is left as it is.
316
+ * When `docsFiles` computes paths, every caller's `docs-files` input lists them first, then keeps its hand-listed paths
317
+ * that still exist, so sync never drops coverage.
239
318
  */
240
- function ciWorkflow(current, callers, syncCallers) {
319
+ function ciWorkflow(current, callers, syncCallers, docsFiles) {
241
320
  if (current === void 0) return CI_CALLER;
242
321
  if (!callers.length) return current;
243
322
  const document = parseDocument(current);
@@ -248,7 +327,7 @@ function ciWorkflow(current, callers, syncCallers) {
248
327
  assertNoClash(jobs, caller.id, syncCallers.length > 0);
249
328
  const pair = jobs.items.find(({ key }) => isScalar(key) && key.value === caller.id);
250
329
  if (!pair || !isMap(pair.value)) return current;
251
- let changed = false;
330
+ let changed = setCallersDocsFiles(document, jobs, callers, docsFiles);
252
331
  if (caller.named) {
253
332
  pair.value.delete("name");
254
333
  changed = true;
@@ -266,6 +345,8 @@ function ciWorkflow(current, callers, syncCallers) {
266
345
  addDispatch(document);
267
346
  changed = true;
268
347
  }
348
+ const stale = staleNeeds(document, CI_PATH);
349
+ if (stale.length) throw new Error(stale.join("\n"));
269
350
  if (!changed) return current;
270
351
  blockOverflowingFlow(document);
271
352
  return document.toString({
@@ -1,5 +1,5 @@
1
- import "./ceilings-BSw9p4YB.mjs";
2
- import { n as IGNORE_PATTERNS, t as AGENT_IGNORE_PATTERNS } from "./shared-CsXIMK3I.mjs";
1
+ import "./ceilings-B7KayYIG.mjs";
2
+ import { n as IGNORE_PATTERNS, r as SYNCED_AGENT_PATTERNS, t as AGENT_IGNORE_PATTERNS } from "./shared-igPpEDpS.mjs";
3
3
  import { closeSync, existsSync, lstatSync, openSync, readSync } from "node:fs";
4
4
  import { dirname, join, matchesGlob, relative, resolve } from "node:path";
5
5
  import { execFileSync, spawnSync } from "node:child_process";
@@ -9,7 +9,7 @@ const SIZE_EXCLUSIONS = [
9
9
  kind: "generated",
10
10
  patterns: [
11
11
  ...IGNORE_PATTERNS,
12
- ...AGENT_IGNORE_PATTERNS,
12
+ ...SYNCED_AGENT_PATTERNS,
13
13
  "**/*.generated.*",
14
14
  "**/generated/**",
15
15
  "**/__snapshots__/**"
@@ -40,6 +40,8 @@ const SIZE_EXCLUSIONS = [
40
40
  patterns: ["**/*.{png,jpg,jpeg,gif,webp,avif,ico,svg,bmp,tiff,pdf,mp3,wav,ogg,flac,mp4,webm,mov,avi,woff,woff2,ttf,otf,eot,zip,gz,tgz,bz2,xz,7z,tar,rar,wasm,bin,exe,dll,so,dylib,db,sqlite,sqlite3,icns}"]
41
41
  }
42
42
  ];
43
+ /** A lint configuration file, which a measurement at an earlier revision keeps at its current content. */
44
+ const LINT_CONFIG = /(?:^|\/)(?:oxlint\.config\.[cm]?[jt]s|\.oxlintrc\.jsonc?)$/u;
43
45
  function trackedManifests(root) {
44
46
  return execFileSync("git", ["ls-files", "-z"], {
45
47
  cwd: root,
@@ -160,7 +162,11 @@ function isBinary(root, file, staged) {
160
162
  closeSync(descriptor);
161
163
  }
162
164
  }
163
- /** Whether a repository path is generated output the size guard skips: `dist`, `.nuxt`, agent tooling, `*.generated.*`, snapshots, and package-root `build` or `output`. */
165
+ /** Whether a repository path is in an agent tooling directory, whose repository-authored files the budget records apart from the rest. */
166
+ function isAgentFile(file) {
167
+ return AGENT_IGNORE_PATTERNS.some((pattern) => file.startsWith(pattern.slice(0, -2)));
168
+ }
169
+ /** Whether a repository path is generated output the budget and the size guard skip: `dist`, `.nuxt`, the agent files `antelopejs-sync` writes, `*.generated.*`, snapshots, and package-root `build` or `output`. */
164
170
  function generatedOutput(root) {
165
171
  const packageOutputs = packageOutputPatterns(root);
166
172
  const generated = SIZE_EXCLUSIONS.filter(({ kind }) => kind === "generated");
@@ -179,4 +185,4 @@ function authoredSizes(root, files = gitFiles(root), staged = false) {
179
185
  return sizes;
180
186
  }
181
187
  //#endregion
182
- export { repositoryPath as a, trackedManifests as c, gitFiles as i, changedFiles as n, repositoryRoot as o, generatedOutput as r, resolveRevision as s, authoredSizes as t };
188
+ export { gitFiles as a, repositoryRoot as c, generatedOutput as i, resolveRevision as l, authoredSizes as n, isAgentFile as o, changedFiles as r, repositoryPath as s, LINT_CONFIG as t, trackedManifests as u };
@@ -0,0 +1,40 @@
1
+ //#region src/formal/index.d.ts
2
+ /** Exit codes of a check: 0 when every rule matches its record, 1 when a rule changed, 2 when TLC could not run. */
3
+ declare const EXIT: {
4
+ readonly ok: 0;
5
+ readonly changed: 1;
6
+ readonly tool: 2;
7
+ };
8
+ /** Each recorded finding: the invariant a spec breaks today, with the number of states in TLC's shortest counterexample. */
9
+ type Findings = Readonly<Record<string, number>>;
10
+ /** What {@link checkSpec} model-checks. */
11
+ interface CheckSpecOptions {
12
+ /** The folder holding `<spec>.tla`, the modules it extends and `<config>.cfg`. */
13
+ dir: string;
14
+ /** The module name of the spec, without `.tla`. */
15
+ spec: string;
16
+ /** The configuration file name, without `.cfg`; defaults to `spec`. */
17
+ config?: string;
18
+ /** The invariants of the configuration expected to break. */
19
+ findings: Findings;
20
+ }
21
+ /**
22
+ * Model-checks `<dir>/<spec>.tla` with TLC under the constants, bounds and
23
+ * invariants of `<dir>/<config>.cfg`. Every invariant must hold except the
24
+ * `findings`, each of which must still break with a shortest counterexample
25
+ * of exactly its recorded number of states. Prints one line per rule
26
+ * (`holds`, `finding`, `BROKEN`, `CHANGED` or `HOLDS`) and exits the process
27
+ * with {@link EXIT}`.changed` when a rule differs from its record, or
28
+ * {@link EXIT}`.tool` when TLC could not run; returns when everything
29
+ * matches.
30
+ *
31
+ * TLC is the pinned tla2tools.jar 1.7.4, downloaded once into
32
+ * `$XDG_CACHE_HOME/antelopejs-formal` (default `~/.cache/antelopejs-formal`)
33
+ * and checked against its SHA-256. Java comes from `$JAVA`, else `java` on
34
+ * PATH, else the `eclipse-temurin:21-jre` Docker image, run with `--rm` in a
35
+ * container named after `$TLC_DOCKER_PREFIX` (default
36
+ * `antelopejs-formal-tlc`).
37
+ */
38
+ declare function checkSpec(options: CheckSpecOptions): Promise<void>;
39
+ //#endregion
40
+ export { CheckSpecOptions, EXIT, Findings, checkSpec };
@@ -0,0 +1,205 @@
1
+ import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
2
+ import path from "node:path";
3
+ import { spawnSync } from "node:child_process";
4
+ import { createHash } from "node:crypto";
5
+ import os from "node:os";
6
+ //#region src/formal/index.ts
7
+ const TLC_VERSION = "1.7.4";
8
+ const TLC_URL = `https://github.com/tlaplus/tlaplus/releases/download/v${TLC_VERSION}/tla2tools.jar`;
9
+ const TLC_SHA256 = "936a262061c914694dfd669a543be24573c45d5aa0ff20a8b96b23d01e050e88";
10
+ const DOCKER_IMAGE = "eclipse-temurin:21-jre";
11
+ /** Exit codes of a check: 0 when every rule matches its record, 1 when a rule changed, 2 when TLC could not run. */
12
+ const EXIT = {
13
+ ok: 0,
14
+ changed: 1,
15
+ tool: 2
16
+ };
17
+ function fail(message) {
18
+ console.error(`check: ${message}`);
19
+ process.exit(EXIT.tool);
20
+ }
21
+ function sha256(file) {
22
+ return createHash("sha256").update(readFileSync(file)).digest("hex");
23
+ }
24
+ async function ensureJar() {
25
+ const cacheRoot = process.env.XDG_CACHE_HOME ?? path.join(os.homedir(), ".cache");
26
+ const dir = path.join(cacheRoot, "antelopejs-formal");
27
+ const jar = path.join(dir, `tla2tools-${TLC_VERSION}.jar`);
28
+ if (existsSync(jar) && sha256(jar) === TLC_SHA256) return jar;
29
+ mkdirSync(dir, { recursive: true });
30
+ console.log(`Downloading ${TLC_URL}`);
31
+ const response = await fetch(TLC_URL);
32
+ if (!response.ok) fail(`download failed: HTTP ${response.status}`);
33
+ const partial = `${jar}.${process.pid}.part`;
34
+ writeFileSync(partial, Buffer.from(await response.arrayBuffer()));
35
+ const actual = sha256(partial);
36
+ if (actual !== TLC_SHA256) {
37
+ rmSync(partial, { force: true });
38
+ fail(`tla2tools.jar has SHA-256 ${actual}, expected ${TLC_SHA256}`);
39
+ }
40
+ renameSync(partial, jar);
41
+ return jar;
42
+ }
43
+ function onPath(program) {
44
+ return spawnSync(program, ["-version"], { stdio: "ignore" }).status === 0;
45
+ }
46
+ let dockerRuns = 0;
47
+ function javaInvocation(jar, work) {
48
+ const java = process.env.JAVA;
49
+ if (java) return {
50
+ program: java,
51
+ prefix: []
52
+ };
53
+ if (onPath("java")) return {
54
+ program: "java",
55
+ prefix: []
56
+ };
57
+ dockerRuns += 1;
58
+ const name = process.env.TLC_DOCKER_PREFIX ?? "antelopejs-formal-tlc";
59
+ const jars = path.dirname(jar);
60
+ return {
61
+ program: "docker",
62
+ prefix: [
63
+ "run",
64
+ "--rm",
65
+ "--name",
66
+ `${name}-${process.pid}-${dockerRuns}`,
67
+ "--user",
68
+ `${process.getuid?.()}:${process.getgid?.()}`,
69
+ "-v",
70
+ `${jars}:${jars}:ro`,
71
+ "-v",
72
+ `${work}:${work}`,
73
+ "-w",
74
+ work,
75
+ DOCKER_IMAGE,
76
+ "java"
77
+ ]
78
+ };
79
+ }
80
+ function readConfig(dir, config, findings) {
81
+ const text = readFileSync(path.join(dir, `${config}.cfg`), "utf8");
82
+ const constants = Array.from(text.matchAll(/^\s+(\w+)\s*=\s*(.+?)\s*$/gm), ([, name, value]) => ` ${name} = ${value}`);
83
+ const invariants = Array.from(text.matchAll(/^INVARIANT\s+(\w+)/gm), ([, name]) => name);
84
+ const bounds = Array.from(text.matchAll(/^(?:CONSTRAINT|ACTION_CONSTRAINT|SYMMETRY|VIEW)\s+\w+\s*$/gm), ([line]) => line.trim());
85
+ for (const name of Object.keys(findings)) if (!invariants.includes(name)) fail(`finding ${name} is not an INVARIANT in ${config}.cfg`);
86
+ return {
87
+ constants,
88
+ invariants,
89
+ bounds
90
+ };
91
+ }
92
+ function runTlc(run, invariants) {
93
+ const { jar, work, spec, name, config, workers } = run;
94
+ const cfg = path.join(work, `${name}.cfg`);
95
+ writeFileSync(cfg, [
96
+ "SPECIFICATION Spec",
97
+ "CONSTANTS",
98
+ ...config.constants,
99
+ ...config.bounds,
100
+ ...invariants.map((rule) => `INVARIANT ${rule}`),
101
+ ""
102
+ ].join("\n"));
103
+ const java = javaInvocation(jar, work);
104
+ const result = spawnSync(java.program, [
105
+ ...java.prefix,
106
+ "-XX:+UseParallelGC",
107
+ "-cp",
108
+ jar,
109
+ "tlc2.TLC",
110
+ "-config",
111
+ cfg,
112
+ "-workers",
113
+ workers,
114
+ "-deadlock",
115
+ "-metadir",
116
+ path.join(work, `states-${name}`),
117
+ `${spec}.tla`
118
+ ], {
119
+ cwd: work,
120
+ encoding: "utf8",
121
+ maxBuffer: 268435456
122
+ });
123
+ if (result.error) fail(`cannot run ${java.program}: ${result.error.message}`);
124
+ const output = `${result.stdout}${result.stderr}`;
125
+ writeFileSync(path.join(work, `${name}.out`), output);
126
+ const violated = /Invariant (\w+) is violated/.exec(output)?.[1];
127
+ const distinct = /([\d,]+) distinct states found, 0 states left/.exec(output)?.[1];
128
+ if (!violated && !output.includes("No error has been found")) fail(`TLC did not finish ${name}; output in ${path.join(work, `${name}.out`)}\n${output.slice(-2e3)}`);
129
+ return {
130
+ violated,
131
+ distinct,
132
+ steps: Array.from(output.matchAll(/^State \d+: <(\w+)/gm), ([, action]) => action)
133
+ };
134
+ }
135
+ /**
136
+ * Model-checks `<dir>/<spec>.tla` with TLC under the constants, bounds and
137
+ * invariants of `<dir>/<config>.cfg`. Every invariant must hold except the
138
+ * `findings`, each of which must still break with a shortest counterexample
139
+ * of exactly its recorded number of states. Prints one line per rule
140
+ * (`holds`, `finding`, `BROKEN`, `CHANGED` or `HOLDS`) and exits the process
141
+ * with {@link EXIT}`.changed` when a rule differs from its record, or
142
+ * {@link EXIT}`.tool` when TLC could not run; returns when everything
143
+ * matches.
144
+ *
145
+ * TLC is the pinned tla2tools.jar 1.7.4, downloaded once into
146
+ * `$XDG_CACHE_HOME/antelopejs-formal` (default `~/.cache/antelopejs-formal`)
147
+ * and checked against its SHA-256. Java comes from `$JAVA`, else `java` on
148
+ * PATH, else the `eclipse-temurin:21-jre` Docker image, run with `--rm` in a
149
+ * container named after `$TLC_DOCKER_PREFIX` (default
150
+ * `antelopejs-formal-tlc`).
151
+ */
152
+ async function checkSpec(options) {
153
+ const { dir, spec, config = spec, findings } = options;
154
+ const parsed = readConfig(dir, config, findings);
155
+ const jar = await ensureJar();
156
+ const work = mkdtempSync(path.join(os.tmpdir(), `formal-${spec}-`));
157
+ for (const file of readdirSync(dir).filter((name) => name.endsWith(".tla"))) copyFileSync(path.join(dir, file), path.join(work, file));
158
+ const run = {
159
+ jar,
160
+ work,
161
+ spec,
162
+ config: parsed
163
+ };
164
+ const holding = parsed.invariants.filter((rule) => !Object.hasOwn(findings, rule));
165
+ console.log(`TLC ${TLC_VERSION} on ${spec}.tla (${config}.cfg) with ${parsed.constants.map((line) => line.trim()).join(", ")}`);
166
+ let changed = false;
167
+ if (holding.length > 0) {
168
+ const held = runTlc({
169
+ ...run,
170
+ name: "holds",
171
+ workers: "auto"
172
+ }, holding);
173
+ if (held.violated) {
174
+ changed = true;
175
+ console.log(`BROKEN ${held.violated}: ${held.steps.join(" -> ")}`);
176
+ } else console.log(`holds ${holding.join(", ")} (${held.distinct} states)`);
177
+ }
178
+ for (const [rule, expected] of Object.entries(findings)) {
179
+ const found = runTlc({
180
+ ...run,
181
+ name: rule,
182
+ workers: "1"
183
+ }, [rule]);
184
+ if (!found.violated) {
185
+ changed = true;
186
+ console.log(`HOLDS ${rule}: the finding is gone (${found.distinct} states)`);
187
+ continue;
188
+ }
189
+ const length = found.steps.length;
190
+ const tag = length === expected ? "finding" : "CHANGED";
191
+ changed ||= length !== expected;
192
+ console.log(`${tag} ${rule}: ${length} states (recorded ${expected}): ${found.steps.join(" -> ")}`);
193
+ }
194
+ if (changed) {
195
+ console.log(`TLC output kept in ${work}`);
196
+ process.exit(EXIT.changed);
197
+ }
198
+ rmSync(work, {
199
+ recursive: true,
200
+ force: true
201
+ });
202
+ console.log("Every rule matches the record in SKILL.md.");
203
+ }
204
+ //#endregion
205
+ export { EXIT, checkSpec };
@@ -21,37 +21,41 @@ function list(value, path) {
21
21
  if (!Array.isArray(value)) throw new DecodeError(`${path}: expected a list`);
22
22
  return value;
23
23
  }
24
+ /** The field's value when the payload has it as an own key; never one inherited from `Object.prototype`. */
25
+ function field(source, key) {
26
+ return Object.hasOwn(source, key) ? source[key] : void 0;
27
+ }
24
28
  function str(source, key) {
25
- const value = source[key];
29
+ const value = field(source, key);
26
30
  if (value === void 0 || !isString(value)) throw new DecodeError(`${key}: expected a string`);
27
31
  return value;
28
32
  }
29
33
  function optStr(source, key) {
30
- const value = source[key];
34
+ const value = field(source, key);
31
35
  return value !== void 0 && isString(value) ? value : void 0;
32
36
  }
33
37
  function num(source, key) {
34
- const value = source[key];
38
+ const value = field(source, key);
35
39
  if (value === void 0 || !isNumber(value)) throw new DecodeError(`${key}: expected a number`);
36
40
  return value;
37
41
  }
38
42
  function optNum(source, key) {
39
- const value = source[key];
43
+ const value = field(source, key);
40
44
  return value !== void 0 && isNumber(value) ? value : void 0;
41
45
  }
42
46
  function flag(source, key) {
43
- return source[key] === true;
47
+ return field(source, key) === true;
44
48
  }
45
49
  function child(source, key) {
46
- const value = source[key];
50
+ const value = field(source, key);
47
51
  return value === void 0 ? {} : object(value, key);
48
52
  }
49
53
  function children(source, key) {
50
- const value = source[key];
54
+ const value = field(source, key);
51
55
  return value === void 0 ? [] : list(value, key).map((entry) => object(entry, key));
52
56
  }
53
57
  function strings(source, key) {
54
- const value = source[key];
58
+ const value = field(source, key);
55
59
  return value === void 0 ? [] : list(value, key).filter((entry) => isString(entry));
56
60
  }
57
61
  function time(source, key) {