@antelopejs/tooling-configs 0.3.3 → 0.3.5

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.
@@ -107,6 +107,74 @@ function ciRenovateSyncCallers(text) {
107
107
  return callers(text, CI_RENOVATE_SYNC_PATTERN);
108
108
  }
109
109
  //#endregion
110
+ //#region src/guardrails/ci-aggregator.ts
111
+ /** The caller-level gate job older callers carry next to the shared workflow, which already reports `ci / checks`. */
112
+ const LEGACY_AGGREGATOR_ID = "checks";
113
+ const JOB_KEYS = /* @__PURE__ */ new Set([
114
+ "if",
115
+ "needs",
116
+ "runs-on",
117
+ "timeout-minutes",
118
+ "steps"
119
+ ]);
120
+ const STEP_KEYS = /* @__PURE__ */ new Set([
121
+ "if",
122
+ "run",
123
+ "name"
124
+ ]);
125
+ const PLAIN_EXIT = /^exit(?: \d+)?$/;
126
+ function isText$2(value) {
127
+ return String(value) === value;
128
+ }
129
+ function onlyKeys(map, allowed) {
130
+ return map.items.every(({ key }) => isScalar(key) && allowed.has(String(key.value)));
131
+ }
132
+ function needsOnly(job, id) {
133
+ const needs = job.get("needs", true);
134
+ const entries = isSeq(needs) ? needs.items : [needs];
135
+ return entries.length === 1 && isScalar(entries[0]) && entries[0].value === id;
136
+ }
137
+ /**
138
+ * Whether an `if:` expression is built only from `needs.<id>.result` reads, string literals, `contains()`, `always()`
139
+ * and boolean or comparison operators. Reads of any other context, such as `github.event_name`, fail it.
140
+ */
141
+ function readsOnlyNeedsResults(expression) {
142
+ const rest = expression.replace(/'[^']*'/g, "").replace(/needs\.(?:\*|[\w-]+)\.result/g, "").replace(/\b(?:contains|always)\b/g, "");
143
+ return /^[\s(),|&=!${}]*$/.test(rest);
144
+ }
145
+ function failsOnNeedsResult(step) {
146
+ if (!onlyKeys(step, STEP_KEYS)) return false;
147
+ const run = step.get("run");
148
+ const condition = step.get("if");
149
+ return isText$2(run) && PLAIN_EXIT.test(run.trim()) && isText$2(condition) && /\bneeds\./.test(condition) && readsOnlyNeedsResults(condition);
150
+ }
151
+ function gatesOnNeedsResults(job) {
152
+ const steps = job.get("steps", true);
153
+ const condition = job.get("if");
154
+ return isSeq(steps) && steps.items.length > 0 && steps.items.every((step) => isMap(step) && failsOnNeedsResult(step)) && (condition === void 0 || isText$2(condition) && readsOnlyNeedsResults(condition));
155
+ }
156
+ /** Whether any node of the job declares an anchor, which another job's alias could point into. */
157
+ function holdsAnchor(job) {
158
+ let found = false;
159
+ visit(job, (_key, node) => {
160
+ if ((isScalar(node) || isMap(node) || isSeq(node)) && node.anchor) {
161
+ found = true;
162
+ return visit.BREAK;
163
+ }
164
+ });
165
+ return found;
166
+ }
167
+ /**
168
+ * Whether `jobs` holds a `checks` job that only re-aggregates the caller: it needs exactly `callerId`, has no `uses`,
169
+ * holds no anchor another job could alias, and each of its steps is a plain `exit` guarded by a condition on `needs`
170
+ * results. It is also the only job besides
171
+ * `keep`, so a repository with its own jobs keeps a gate that covers them.
172
+ */
173
+ function hasRedundantAggregator(jobs, callerId, keep) {
174
+ const aggregator = jobs.get(LEGACY_AGGREGATOR_ID, true);
175
+ return isMap(aggregator) && !holdsAnchor(aggregator) && onlyKeys(aggregator, JOB_KEYS) && needsOnly(aggregator, callerId) && gatesOnNeedsResults(aggregator) && jobs.items.every(({ key }) => isScalar(key) && (key.value === "checks" || keep.has(String(key.value))));
176
+ }
177
+ //#endregion
110
178
  //#region src/guardrails/workflow-needs.ts
111
179
  const NEEDS_REFERENCE = /(?<![\w.'"-])needs(?:\.([A-Za-z_][\w-]*)|\[\s*(['"])([^'"]+)\2\s*\])/g;
112
180
  function neededIds(job) {
@@ -134,9 +202,10 @@ function referencedIds(job) {
134
202
  /**
135
203
  * Lists every `needs:` entry naming no job and every `needs.<id>` or `needs['<id>']` read in a job's `if:` or `${{ }}`
136
204
  * expressions whose id is not in that job's `needs:`. GitHub evaluates such a read to null, so a gate condition like
137
- * `needs.checks.result == 'skipped'` silently stops failing once the job it named was renamed.
205
+ * `needs.checks.result == 'skipped'` silently stops failing once the job it named was renamed. `removed` lists job ids
206
+ * the caller just deleted, so a `needs:` on one gets a message that says it was removed, not renamed.
138
207
  */
139
- function staleNeeds(document, path) {
208
+ function staleNeeds(document, path, removed = []) {
140
209
  const jobs = document.get("jobs", true);
141
210
  if (!isMap(jobs)) return [];
142
211
  const ids = new Set(jobs.items.flatMap(({ key }) => isScalar(key) ? [String(key.value)] : []));
@@ -145,7 +214,7 @@ function staleNeeds(document, path) {
145
214
  if (!isScalar(key) || !isMap(job)) continue;
146
215
  const name = String(key.value);
147
216
  const needed = neededIds(job);
148
- 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.`);
217
+ for (const id of needed) if (!ids.has(id)) problems.push(removed.includes(id) ? `${path}: job ${name} needs ${id}, but sync removes the job ${id} because it only re-aggregates ci, which already reports ci / checks. Replace ${id} with ci in the needs: of ${name}, then rerun antelopejs-sync.` : `${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.`);
149
218
  const listed = `[${needed.join(", ")}]`;
150
219
  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.`);
151
220
  }
@@ -348,12 +417,21 @@ function assertNoClash(jobs, callerId, hasSyncCaller) {
348
417
  if (hasSyncCaller || !jobs.has(RENOVATE_SYNC_JOB_ID)) return;
349
418
  throw new Error(callerId === RENOVATE_SYNC_JOB_ID ? `${CI_PATH}: the job ${RENOVATE_SYNC_JOB_ID} calls ci-node.yml, but that id is reserved for the job calling ci-renovate-sync.yml. Rename it, then rerun antelopejs-sync.` : `${CI_PATH}: a job named ${RENOVATE_SYNC_JOB_ID} already exists and does not call ci-renovate-sync.yml. Rename or merge it, then rerun antelopejs-sync.`);
350
419
  }
420
+ function dropRedundantAggregator(jobs, syncCallers) {
421
+ if (!hasRedundantAggregator(jobs, "ci", /* @__PURE__ */ new Set(["ci", ...syncCallers.length ? syncCallers.map(({ id }) => id) : [RENOVATE_SYNC_JOB_ID]]))) return [];
422
+ jobs.delete(LEGACY_AGGREGATOR_ID);
423
+ return [LEGACY_AGGREGATOR_ID];
424
+ }
351
425
  /**
352
426
  * Keeps the shared CI caller on the job id `ci` with no `name`, so the shared workflow reports `ci / checks`,
353
427
  * dispatchable and read-only, with the Renovate sync it would otherwise run turned off. The write permissions the sync
354
428
  * needs to push and dispatch the caller live on a separate job calling ci-renovate-sync.yml, which is added when missing.
355
429
  * A caller without a `test-job` input gets `test-job: true`, which runs the tests in their own job; an explicit value
356
430
  * is left as the repository set it.
431
+ * A `checks` job that only re-aggregates the caller (`needs: [ci]`, steps that `exit` on `needs` results) is removed
432
+ * when the workflow has no other job besides the caller and the Renovate sync, since the shared workflow already
433
+ * reports `ci / checks` and each `needs` hop adds to the critical path. A gate that also covers repository-specific
434
+ * jobs is kept.
357
435
  * No `uses:` ref is ever rewritten. A workflow with no caller job is repository-specific CI and is left as it is.
358
436
  * When `docsFiles` computes paths, every caller's `docs-files` input lists them first, then keeps its hand-listed paths
359
437
  * that still exist, so sync never drops coverage.
@@ -384,11 +462,13 @@ function ciWorkflow(current, callers, syncCallers, docsFiles) {
384
462
  changed = skipRenovateSync(document, pair.value) || changed;
385
463
  changed = addTestJob(document, pair.value) || changed;
386
464
  changed = ensureSyncJob(document, jobs, syncCallers) || changed;
465
+ const removed = dropRedundantAggregator(jobs, syncCallers);
466
+ changed = removed.length > 0 || changed;
387
467
  if (!hasDispatch(document)) {
388
468
  addDispatch(document);
389
469
  changed = true;
390
470
  }
391
- const stale = staleNeeds(document, CI_PATH);
471
+ const stale = staleNeeds(document, CI_PATH, removed);
392
472
  if (stale.length) throw new Error(stale.join("\n"));
393
473
  if (!changed) return current;
394
474
  blockOverflowingFlow(document);
@@ -0,0 +1,79 @@
1
+ import { join } from "node:path";
2
+ //#region src/lease/env.ts
3
+ /** The variable whose presence marks a command as running under `antelopejs-lease run`; `down --stop` finds a lease's processes by it. */
4
+ const LEASE_MARKER = "ANTELOPEJS_LEASE";
5
+ /**
6
+ * The `environ` entry that `run` hands its command and every descendant inherits, which marks a
7
+ * process as the work of lease `id`.
8
+ */
9
+ function leaseMarker(id) {
10
+ return `${LEASE_MARKER}=${id}`;
11
+ }
12
+ /**
13
+ * `env` without the lease marker, for a process that outlives the command that started it and
14
+ * belongs to no lease's `down --stop`, such as a lease's mongod started from inside another lease's
15
+ * `run`.
16
+ */
17
+ function unmarked(env) {
18
+ const { [LEASE_MARKER]: _marker, ...rest } = env;
19
+ return rest;
20
+ }
21
+ function isServerRole(value) {
22
+ return value === "api" || value === "web";
23
+ }
24
+ /** The variables `run` exports for a DMS dev stack, besides the `ANTELOPEJS_LEASE*` ones. */
25
+ const DEV_STACK_VARIABLES = [
26
+ "DMS_BACK_PORT",
27
+ "DMS_FRONT_PORT",
28
+ "DMS_INSPECT_PORT",
29
+ "DMS_SMTP_PORT",
30
+ "DMS_CLIENT_BASE_URL",
31
+ "MONGO_URL",
32
+ "MONGO_DATABASE",
33
+ "DMS_BACK_LOG",
34
+ "DMS_FRONT_LOG",
35
+ "TMPDIR",
36
+ "PORT"
37
+ ];
38
+ /** The variable that carries the lease's directory; a command is under a lease only when this and `LEASE_MARKER` are both non-empty. */
39
+ const LEASE_DIR = "ANTELOPEJS_LEASE_DIR";
40
+ /** The variable that carries the caller's own `TMPDIR` past the lease's override; empty when the caller had none, absent from a lease an older pack opened. */
41
+ const PARENT_TMPDIR = "ANTELOPEJS_LEASE_PARENT_TMPDIR";
42
+ /** The lease's own tmp folder, which `run` exports as `TMPDIR`. */
43
+ function leaseTmpDir(dir) {
44
+ return join(dir, "tmp");
45
+ }
46
+ /**
47
+ * The environment `run` hands its command: `parent` without `PORT`, plus the lease's variables.
48
+ * `PARENT_TMPDIR` keeps the caller's own `TMPDIR`, or the one an outer lease recorded.
49
+ * `PORT` comes back only for `as`, because one shell-wide `PORT` makes the backend and the
50
+ * dashboard bind the same port. `DMS_MONGO_URL` in `parent` replaces the lease's own mongod.
51
+ * `DMS_API_BASE_URL` stays unset. A backend whose config hard-codes its port falls back to a free
52
+ * one and records it in `.antelope/dev.json`, and `ajs dms dev` reads that file only without it.
53
+ */
54
+ function leaseEnv(lease, parent, as) {
55
+ const { record, dir } = lease;
56
+ const { ports } = record;
57
+ const { PORT: _inherited, ...env } = parent;
58
+ const devStack = {
59
+ DMS_BACK_PORT: String(ports.api),
60
+ DMS_FRONT_PORT: String(ports.web),
61
+ DMS_INSPECT_PORT: String(ports.inspect),
62
+ DMS_SMTP_PORT: String(ports.smtp),
63
+ DMS_CLIENT_BASE_URL: `http://localhost:${ports.web}`,
64
+ MONGO_URL: parent.DMS_MONGO_URL || `mongodb://127.0.0.1:${ports.mongo}`,
65
+ MONGO_DATABASE: `dms_${record.id}`,
66
+ DMS_BACK_LOG: join(dir, "logs", "back.log"),
67
+ DMS_FRONT_LOG: join(dir, "logs", "front.log"),
68
+ TMPDIR: leaseTmpDir(dir)
69
+ };
70
+ Object.assign(env, devStack, {
71
+ [LEASE_MARKER]: record.id,
72
+ [LEASE_DIR]: dir,
73
+ [PARENT_TMPDIR]: parent["ANTELOPEJS_LEASE_PARENT_TMPDIR"] ?? parent.TMPDIR ?? ""
74
+ });
75
+ if (as !== void 0) env.PORT = String(ports[as]);
76
+ return env;
77
+ }
78
+ //#endregion
79
+ export { isServerRole as a, leaseTmpDir as c, PARENT_TMPDIR as i, unmarked as l, LEASE_DIR as n, leaseEnv as o, LEASE_MARKER as r, leaseMarker as s, DEV_STACK_VARIABLES as t };
@@ -34,6 +34,18 @@ interface CheckSpecOptions {
34
34
  * PATH, else the `eclipse-temurin:21-jre` Docker image, run with `--rm` in a
35
35
  * container named after `$TLC_DOCKER_PREFIX` (default
36
36
  * `antelopejs-formal-tlc`).
37
+ *
38
+ * The printed lines and the exit code of a check TLC finished are kept in
39
+ * `results/<key>.json` under that folder, and a later check with the same key
40
+ * replays them without starting Java, after one line naming the key. The key
41
+ * is a SHA-256 of this runner's own source, the TLC version, the jar's
42
+ * SHA-256, the JVM options and TLC flags with `$JAVA_TOOL_OPTIONS`,
43
+ * `$JDK_JAVA_OPTIONS` and `$_JAVA_OPTIONS`, the spec and configuration
44
+ * names, the printed header, the bytes of every `.tla` file in `dir`, the
45
+ * configuration and worker count of each TLC run, and `findings`. A replay keeps no TLC output
46
+ * folder. `ANTELOPEJS_FORMAL_CACHE=off` neither reads nor writes the cache.
47
+ * Entries are never pruned; each is a few hundred bytes, one per distinct
48
+ * input.
37
49
  */
38
50
  declare function checkSpec(options: CheckSpecOptions): Promise<void>;
39
51
  //#endregion
@@ -1,13 +1,23 @@
1
- import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
1
+ import { c as object, f as parseJson, p as str, s as num } from "../json-CG2L7YFl.mjs";
2
+ import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
2
3
  import path from "node:path";
3
4
  import { spawnSync } from "node:child_process";
4
- import { createHash } from "node:crypto";
5
+ import { fileURLToPath } from "node:url";
6
+ import { createHash, randomUUID } from "node:crypto";
5
7
  import os from "node:os";
6
8
  //#region src/formal/index.ts
7
9
  const TLC_VERSION = "1.7.4";
8
10
  const TLC_URL = `https://github.com/tlaplus/tlaplus/releases/download/v${TLC_VERSION}/tla2tools.jar`;
9
11
  const TLC_SHA256 = "936a262061c914694dfd669a543be24573c45d5aa0ff20a8b96b23d01e050e88";
10
12
  const DOCKER_IMAGE = "eclipse-temurin:21-jre";
13
+ const JVM_OPTIONS = ["-XX:+UseParallelGC"];
14
+ const TLC_FLAGS = ["-deadlock"];
15
+ const JVM_ENV = [
16
+ "JAVA_TOOL_OPTIONS",
17
+ "JDK_JAVA_OPTIONS",
18
+ "_JAVA_OPTIONS"
19
+ ];
20
+ const CACHE_ENV = "ANTELOPEJS_FORMAL_CACHE";
11
21
  /** Exit codes of a check: 0 when every rule matches its record, 1 when a rule changed, 2 when TLC could not run. */
12
22
  const EXIT = {
13
23
  ok: 0,
@@ -18,21 +28,24 @@ function fail(message) {
18
28
  console.error(`check: ${message}`);
19
29
  process.exit(EXIT.tool);
20
30
  }
21
- function sha256(file) {
22
- return createHash("sha256").update(readFileSync(file)).digest("hex");
31
+ function sha256(data) {
32
+ return createHash("sha256").update(data).digest("hex");
23
33
  }
24
- async function ensureJar() {
34
+ function cacheDir() {
25
35
  const cacheRoot = process.env.XDG_CACHE_HOME ?? path.join(os.homedir(), ".cache");
26
- const dir = path.join(cacheRoot, "antelopejs-formal");
36
+ return path.join(cacheRoot, "antelopejs-formal");
37
+ }
38
+ async function ensureJar() {
39
+ const dir = cacheDir();
27
40
  const jar = path.join(dir, `tla2tools-${TLC_VERSION}.jar`);
28
- if (existsSync(jar) && sha256(jar) === TLC_SHA256) return jar;
41
+ if (existsSync(jar) && sha256(readFileSync(jar)) === TLC_SHA256) return jar;
29
42
  mkdirSync(dir, { recursive: true });
30
43
  console.log(`Downloading ${TLC_URL}`);
31
44
  const response = await fetch(TLC_URL);
32
45
  if (!response.ok) fail(`download failed: HTTP ${response.status}`);
33
46
  const partial = `${jar}.${process.pid}.part`;
34
47
  writeFileSync(partial, Buffer.from(await response.arrayBuffer()));
35
- const actual = sha256(partial);
48
+ const actual = sha256(readFileSync(partial));
36
49
  if (actual !== TLC_SHA256) {
37
50
  rmSync(partial, { force: true });
38
51
  fail(`tla2tools.jar has SHA-256 ${actual}, expected ${TLC_SHA256}`);
@@ -89,21 +102,31 @@ function readConfig(dir, config, findings) {
89
102
  bounds
90
103
  };
91
104
  }
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, [
105
+ function cfgText(config, invariants) {
106
+ return [
96
107
  "SPECIFICATION Spec",
97
108
  "CONSTANTS",
98
109
  ...config.constants,
99
110
  ...config.bounds,
100
111
  ...invariants.map((rule) => `INVARIANT ${rule}`),
101
112
  ""
102
- ].join("\n"));
113
+ ].join("\n");
114
+ }
115
+ function readModules(dir) {
116
+ return readdirSync(dir).filter((name) => name.endsWith(".tla")).sort().map((name) => ({
117
+ name,
118
+ bytes: readFileSync(path.join(dir, name))
119
+ }));
120
+ }
121
+ function runTlc(workspace, run) {
122
+ const { jar, work, spec } = workspace;
123
+ const { name, workers } = run;
124
+ const cfg = path.join(work, `${name}.cfg`);
125
+ writeFileSync(cfg, run.cfg);
103
126
  const java = javaInvocation(jar, work);
104
127
  const result = spawnSync(java.program, [
105
128
  ...java.prefix,
106
- "-XX:+UseParallelGC",
129
+ ...JVM_OPTIONS,
107
130
  "-cp",
108
131
  jar,
109
132
  "tlc2.TLC",
@@ -111,7 +134,7 @@ function runTlc(run, invariants) {
111
134
  cfg,
112
135
  "-workers",
113
136
  workers,
114
- "-deadlock",
137
+ ...TLC_FLAGS,
115
138
  "-metadir",
116
139
  path.join(work, `states-${name}`),
117
140
  `${spec}.tla`
@@ -132,6 +155,89 @@ function runTlc(run, invariants) {
132
155
  steps: Array.from(output.matchAll(/^State \d+: <(\w+)/gm), ([, action]) => action)
133
156
  };
134
157
  }
158
+ function resultKey(plan) {
159
+ return sha256(JSON.stringify({
160
+ runner: sha256(readFileSync(fileURLToPath(import.meta.url))),
161
+ tlc: TLC_VERSION,
162
+ jar: TLC_SHA256,
163
+ jvm: JVM_OPTIONS,
164
+ jvmEnv: JVM_ENV.map((name) => process.env[name] ?? null),
165
+ flags: TLC_FLAGS,
166
+ ...plan,
167
+ modules: plan.modules.map(({ name, bytes }) => [name, sha256(bytes)])
168
+ }));
169
+ }
170
+ function readOutcome(file) {
171
+ try {
172
+ const entry = object(parseJson(readFileSync(file, "utf8")), file);
173
+ const exit = num(entry, "exit");
174
+ if (exit === EXIT.ok || exit === EXIT.changed) return {
175
+ output: str(entry, "output"),
176
+ exit
177
+ };
178
+ return;
179
+ } catch {
180
+ return;
181
+ }
182
+ }
183
+ /** Stores an outcome for later replays; a cache that cannot be written, read-only or full, only costs the next run a TLC run. */
184
+ function writeOutcome(entry, outcome) {
185
+ const temp = `${entry}.${randomUUID()}.tmp`;
186
+ try {
187
+ mkdirSync(path.dirname(entry), { recursive: true });
188
+ writeFileSync(temp, JSON.stringify(outcome));
189
+ renameSync(temp, entry);
190
+ } catch {
191
+ try {
192
+ rmSync(temp, { force: true });
193
+ } catch {
194
+ return;
195
+ }
196
+ }
197
+ }
198
+ async function modelCheck(plan) {
199
+ const { spec, header, modules, holds, findings } = plan;
200
+ const jar = await ensureJar();
201
+ const work = mkdtempSync(path.join(os.tmpdir(), `formal-${spec}-`));
202
+ for (const { name, bytes } of modules) writeFileSync(path.join(work, name), bytes);
203
+ const workspace = {
204
+ jar,
205
+ work,
206
+ spec
207
+ };
208
+ const lines = [];
209
+ const print = (line) => {
210
+ lines.push(line);
211
+ console.log(line);
212
+ };
213
+ print(header);
214
+ let changed = false;
215
+ if (holds) {
216
+ const held = runTlc(workspace, holds.run);
217
+ if (held.violated) {
218
+ changed = true;
219
+ print(`BROKEN ${held.violated}: ${held.steps.join(" -> ")}`);
220
+ } else print(`holds ${holds.rules.join(", ")} (${held.distinct} states)`);
221
+ }
222
+ for (const { rule, expected, run } of findings) {
223
+ const found = runTlc(workspace, run);
224
+ if (!found.violated) {
225
+ changed = true;
226
+ print(`HOLDS ${rule}: the finding is gone (${found.distinct} states)`);
227
+ continue;
228
+ }
229
+ const length = found.steps.length;
230
+ const tag = length === expected ? "finding" : "CHANGED";
231
+ changed ||= length !== expected;
232
+ print(`${tag} ${rule}: ${length} states (recorded ${expected}): ${found.steps.join(" -> ")}`);
233
+ }
234
+ if (!changed) print("Every rule matches the record in SKILL.md.");
235
+ return {
236
+ output: lines.join("\n"),
237
+ exit: changed ? EXIT.changed : EXIT.ok,
238
+ work
239
+ };
240
+ }
135
241
  /**
136
242
  * Model-checks `<dir>/<spec>.tla` with TLC under the constants, bounds and
137
243
  * invariants of `<dir>/<config>.cfg`. Every invariant must hold except the
@@ -148,58 +254,67 @@ function runTlc(run, invariants) {
148
254
  * PATH, else the `eclipse-temurin:21-jre` Docker image, run with `--rm` in a
149
255
  * container named after `$TLC_DOCKER_PREFIX` (default
150
256
  * `antelopejs-formal-tlc`).
257
+ *
258
+ * The printed lines and the exit code of a check TLC finished are kept in
259
+ * `results/<key>.json` under that folder, and a later check with the same key
260
+ * replays them without starting Java, after one line naming the key. The key
261
+ * is a SHA-256 of this runner's own source, the TLC version, the jar's
262
+ * SHA-256, the JVM options and TLC flags with `$JAVA_TOOL_OPTIONS`,
263
+ * `$JDK_JAVA_OPTIONS` and `$_JAVA_OPTIONS`, the spec and configuration
264
+ * names, the printed header, the bytes of every `.tla` file in `dir`, the
265
+ * configuration and worker count of each TLC run, and `findings`. A replay keeps no TLC output
266
+ * folder. `ANTELOPEJS_FORMAL_CACHE=off` neither reads nor writes the cache.
267
+ * Entries are never pruned; each is a few hundred bytes, one per distinct
268
+ * input.
151
269
  */
152
270
  async function checkSpec(options) {
153
271
  const { dir, spec, config = spec, findings } = options;
154
272
  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,
273
+ const holding = parsed.invariants.filter((rule) => !Object.hasOwn(findings, rule));
274
+ const plan = {
161
275
  spec,
162
- config: parsed
276
+ header: `TLC ${TLC_VERSION} on ${spec}.tla (${config}.cfg) with ${parsed.constants.map((line) => line.trim()).join(", ")}`,
277
+ modules: readModules(dir),
278
+ holds: holding.length > 0 ? {
279
+ rules: holding,
280
+ run: {
281
+ name: "holds",
282
+ workers: "auto",
283
+ cfg: cfgText(parsed, holding)
284
+ }
285
+ } : void 0,
286
+ findings: Object.entries(findings).map(([rule, expected]) => ({
287
+ rule,
288
+ expected,
289
+ run: {
290
+ name: rule,
291
+ workers: "1",
292
+ cfg: cfgText(parsed, [rule])
293
+ }
294
+ }))
163
295
  };
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)`);
296
+ const key = resultKey(plan);
297
+ const entry = process.env[CACHE_ENV] === "off" ? void 0 : path.join(cacheDir(), "results", `${key}.json`);
298
+ const replayed = entry === void 0 ? void 0 : readOutcome(entry);
299
+ if (replayed) {
300
+ console.log(`TLC result ${key.slice(0, 12)} replayed from the cache; ${CACHE_ENV}=off reruns TLC`);
301
+ console.log(replayed.output);
302
+ if (replayed.exit !== EXIT.ok) process.exit(replayed.exit);
303
+ return;
177
304
  }
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);
305
+ const outcome = await modelCheck(plan);
306
+ if (entry !== void 0) writeOutcome(entry, {
307
+ output: outcome.output,
308
+ exit: outcome.exit
309
+ });
310
+ if (outcome.exit !== EXIT.ok) {
311
+ console.log(`TLC output kept in ${outcome.work}`);
312
+ process.exit(outcome.exit);
197
313
  }
198
- rmSync(work, {
314
+ rmSync(outcome.work, {
199
315
  recursive: true,
200
316
  force: true
201
317
  });
202
- console.log("Every rule matches the record in SKILL.md.");
203
318
  }
204
319
  //#endregion
205
320
  export { EXIT, checkSpec };