@antelopejs/tooling-configs 0.2.17 → 0.2.19
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 +35 -21
- package/dist/bin/api-diff.mjs +25 -14
- package/dist/bin/body-check.mjs +3 -3
- 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 +24 -6
- package/dist/bin/comment-proof.mjs +3 -3
- package/dist/bin/garden.mjs +229 -28
- package/dist/bin/lease.d.mts +1 -0
- package/dist/bin/lease.mjs +1053 -0
- package/dist/bin/ratchet.mjs +146 -100
- package/dist/bin/suppressions.mjs +5 -5
- package/dist/bin/sync.mjs +150 -176
- package/dist/bin/verify.mjs +238 -125
- package/dist/capture/index.d.mts +50 -0
- package/dist/capture/index.mjs +2 -0
- package/dist/{ci-workflow-ChW4He0r.mjs → ci-workflow-DVkpwauQ.mjs} +12 -0
- package/dist/{files-Bc036sJW.mjs → files-DJ0TeaTU.mjs} +10 -4
- package/dist/formal/index.d.mts +40 -0
- package/dist/formal/index.mjs +205 -0
- package/dist/oxc/anti-slop/index.mjs +717 -16
- package/dist/oxc/fmt.mjs +1 -1
- package/dist/oxc/guardrails/index.d.mts +1 -1
- package/dist/oxc/guardrails/index.mjs +93 -5
- package/dist/oxc/lint.d.mts +9 -0
- package/dist/oxc/lint.mjs +14 -3
- package/dist/{oxlint-Bltmk8-6.mjs → oxlint-DIV-lLSS.mjs} +7 -3
- package/dist/{package-DTxLPNDu.mjs → package-BRTjkzt5.mjs} +26 -1
- package/dist/{proof-stamp-w-3j47A-.mjs → proof-stamp-DDDC0J6l.mjs} +3 -3
- package/dist/{ratchet-DwRj9h4L.mjs → ratchet-BAcLRYuM.mjs} +194 -21
- package/dist/scenes-DZVXkcxS.mjs +104 -0
- package/dist/shared-igPpEDpS.mjs +622 -0
- package/dist/{size-DNtWruCO.mjs → size-DBatLT-F.mjs} +2 -2
- package/dist/{suppression-base-DAfCXwjL.mjs → suppression-base-9L8dlMQK.mjs} +36 -11
- package/dist/{suppression-budget-Bd2GqMYb.mjs → suppression-budget-C0SkPO5R.mjs} +56 -19
- package/dist/{suppressions-BD_f8f7L.mjs → suppressions-DM60NkvL.mjs} +1 -1
- package/dist/templates-CypDm-j9.mjs +121 -0
- package/dist/{typescript-BmS5BmrS.mjs → typescript-CM0LrVP7.mjs} +2 -2
- package/dist/verify/index.d.mts +6 -1
- package/package.json +29 -4
- package/dist/shared-CoUt4GUm.mjs +0 -73
|
@@ -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 };
|