@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.
- package/README.md +101 -52
- package/dist/bin/api-diff.mjs +430 -107
- package/dist/bin/body-check.d.mts +1 -0
- package/dist/bin/body-check.mjs +344 -0
- package/dist/bin/capture.d.mts +1 -0
- package/dist/bin/capture.mjs +559 -0
- package/dist/bin/check-size.mjs +3 -3
- package/dist/bin/checks.mjs +3 -3
- package/dist/bin/comment-proof.mjs +4 -3
- package/dist/bin/garden.mjs +6 -6
- package/dist/bin/ratchet.mjs +316 -10
- package/dist/bin/suppressions.mjs +118 -80
- package/dist/bin/sync.mjs +554 -153
- package/dist/bin/verify.mjs +240 -127
- package/dist/capture/index.d.mts +50 -0
- package/dist/capture/index.mjs +2 -0
- package/dist/{ceilings-BSw9p4YB.mjs → ceilings-B7KayYIG.mjs} +11 -3
- package/dist/{checks-BlWDFYio.mjs → checks-CxkSu2E6.mjs} +1 -1
- package/dist/{ci-workflow-DIsoEgMd.mjs → ci-workflow-ChW4He0r.mjs} +84 -3
- package/dist/{files-2FikHZ9F.mjs → files-DJ0TeaTU.mjs} +11 -5
- package/dist/formal/index.d.mts +40 -0
- package/dist/formal/index.mjs +205 -0
- package/dist/{json-BqvuCkqr.mjs → json-CG2L7YFl.mjs} +12 -8
- package/dist/oxc/anti-slop/index.mjs +869 -21
- package/dist/oxc/fmt.mjs +1 -1
- package/dist/oxc/guardrails/index.d.mts +1 -1
- package/dist/oxc/guardrails/index.mjs +736 -4
- package/dist/oxc/lint.d.mts +20 -3
- package/dist/oxc/lint.mjs +34 -10
- package/dist/oxlint-DIV-lLSS.mjs +98 -0
- package/dist/{package-Dtjt_lSa.mjs → package-BRTjkzt5.mjs} +29 -3
- package/dist/proof-stamp-DDDC0J6l.mjs +279 -0
- package/dist/ratchet-BAcLRYuM.mjs +448 -0
- package/dist/{renames-BGO4dWJ8.mjs → renames-L2owF5GD.mjs} +2 -2
- package/dist/scenes-DZVXkcxS.mjs +104 -0
- package/dist/shared-igPpEDpS.mjs +622 -0
- package/dist/{size-BVgNbLO6.mjs → size-DBatLT-F.mjs} +4 -4
- package/dist/suppression-base-9L8dlMQK.mjs +120 -0
- package/dist/suppression-budget-C0SkPO5R.mjs +535 -0
- package/dist/{suppressions-BJAngUxo.mjs → suppressions-DM60NkvL.mjs} +180 -18
- package/dist/templates-CypDm-j9.mjs +121 -0
- package/dist/typescript-CM0LrVP7.mjs +222 -0
- package/dist/verify/index.d.mts +6 -1
- package/dist/verify/index.mjs +1 -1
- package/package.json +31 -5
- package/dist/kinds-Bzyyi9yk.mjs +0 -25
- package/dist/ratchet-DRdIYwmv.mjs +0 -80
- package/dist/shared-CsXIMK3I.mjs +0 -34
- package/dist/staged-ratchet-CjoRfZaM.mjs +0 -236
- package/dist/suppression-budget-Yyf5_J5l.mjs +0 -283
- 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 =
|
|
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-
|
|
2
|
-
import { n as IGNORE_PATTERNS, t as AGENT_IGNORE_PATTERNS } from "./shared-
|
|
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
|
-
...
|
|
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
|
|
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 {
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
47
|
+
return field(source, key) === true;
|
|
44
48
|
}
|
|
45
49
|
function child(source, key) {
|
|
46
|
-
const value = source
|
|
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
|
|
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
|
|
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) {
|