@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.
Files changed (42) hide show
  1. package/README.md +35 -21
  2. package/dist/bin/api-diff.mjs +25 -14
  3. package/dist/bin/body-check.mjs +3 -3
  4. package/dist/bin/capture.d.mts +1 -0
  5. package/dist/bin/capture.mjs +559 -0
  6. package/dist/bin/check-size.mjs +3 -3
  7. package/dist/bin/checks.mjs +24 -6
  8. package/dist/bin/comment-proof.mjs +3 -3
  9. package/dist/bin/garden.mjs +229 -28
  10. package/dist/bin/lease.d.mts +1 -0
  11. package/dist/bin/lease.mjs +1053 -0
  12. package/dist/bin/ratchet.mjs +146 -100
  13. package/dist/bin/suppressions.mjs +5 -5
  14. package/dist/bin/sync.mjs +150 -176
  15. package/dist/bin/verify.mjs +238 -125
  16. package/dist/capture/index.d.mts +50 -0
  17. package/dist/capture/index.mjs +2 -0
  18. package/dist/{ci-workflow-ChW4He0r.mjs → ci-workflow-DVkpwauQ.mjs} +12 -0
  19. package/dist/{files-Bc036sJW.mjs → files-DJ0TeaTU.mjs} +10 -4
  20. package/dist/formal/index.d.mts +40 -0
  21. package/dist/formal/index.mjs +205 -0
  22. package/dist/oxc/anti-slop/index.mjs +717 -16
  23. package/dist/oxc/fmt.mjs +1 -1
  24. package/dist/oxc/guardrails/index.d.mts +1 -1
  25. package/dist/oxc/guardrails/index.mjs +93 -5
  26. package/dist/oxc/lint.d.mts +9 -0
  27. package/dist/oxc/lint.mjs +14 -3
  28. package/dist/{oxlint-Bltmk8-6.mjs → oxlint-DIV-lLSS.mjs} +7 -3
  29. package/dist/{package-DTxLPNDu.mjs → package-BRTjkzt5.mjs} +26 -1
  30. package/dist/{proof-stamp-w-3j47A-.mjs → proof-stamp-DDDC0J6l.mjs} +3 -3
  31. package/dist/{ratchet-DwRj9h4L.mjs → ratchet-BAcLRYuM.mjs} +194 -21
  32. package/dist/scenes-DZVXkcxS.mjs +104 -0
  33. package/dist/shared-igPpEDpS.mjs +622 -0
  34. package/dist/{size-DNtWruCO.mjs → size-DBatLT-F.mjs} +2 -2
  35. package/dist/{suppression-base-DAfCXwjL.mjs → suppression-base-9L8dlMQK.mjs} +36 -11
  36. package/dist/{suppression-budget-Bd2GqMYb.mjs → suppression-budget-C0SkPO5R.mjs} +56 -19
  37. package/dist/{suppressions-BD_f8f7L.mjs → suppressions-DM60NkvL.mjs} +1 -1
  38. package/dist/templates-CypDm-j9.mjs +121 -0
  39. package/dist/{typescript-BmS5BmrS.mjs → typescript-CM0LrVP7.mjs} +2 -2
  40. package/dist/verify/index.d.mts +6 -1
  41. package/package.json +29 -4
  42. 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 };