@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.
- package/dist/bin/api-diff.mjs +2 -2
- package/dist/bin/checks.mjs +15 -13
- package/dist/bin/comment-proof.mjs +1 -1
- package/dist/bin/garden.mjs +67 -8
- package/dist/bin/lease.mjs +202 -57
- package/dist/bin/ratchet.mjs +1 -1
- package/dist/bin/sync.mjs +11 -9
- package/dist/bin/verify.mjs +868 -381
- package/dist/{ci-workflow-CXcAZj6g.mjs → ci-workflow-C4mQ8QSp.mjs} +84 -4
- package/dist/env-DT0UJNeL.mjs +79 -0
- package/dist/formal/index.d.mts +12 -0
- package/dist/formal/index.mjs +171 -56
- package/dist/map-s_jKqBQv.mjs +397 -0
- package/dist/oxc/fmt.d.mts +4 -0
- package/dist/oxc/lint.mjs +1 -1
- package/dist/{package-BRTjkzt5.mjs → package-CqqBgE8Y.mjs} +27 -2
- package/dist/{ratchet-BAcLRYuM.mjs → ratchet-Q-JXuZIX.mjs} +1 -1
- package/dist/{templates-CypDm-j9.mjs → templates-BKZv-BRw.mjs} +1 -1
- package/dist/{typescript-CM0LrVP7.mjs → typescript-DAgQIAAR.mjs} +1 -1
- package/dist/verify/index.d.mts +37 -2
- package/package.json +7 -5
|
@@ -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 };
|
package/dist/formal/index.d.mts
CHANGED
|
@@ -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
|
package/dist/formal/index.mjs
CHANGED
|
@@ -1,13 +1,23 @@
|
|
|
1
|
-
import {
|
|
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 {
|
|
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(
|
|
22
|
-
return createHash("sha256").update(
|
|
31
|
+
function sha256(data) {
|
|
32
|
+
return createHash("sha256").update(data).digest("hex");
|
|
23
33
|
}
|
|
24
|
-
|
|
34
|
+
function cacheDir() {
|
|
25
35
|
const cacheRoot = process.env.XDG_CACHE_HOME ?? path.join(os.homedir(), ".cache");
|
|
26
|
-
|
|
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
|
|
93
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
156
|
-
const
|
|
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
|
-
|
|
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
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
if (
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
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
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
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 };
|