@milkenjoyer/toolchain 0.11.0 → 0.12.0

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 (38) hide show
  1. package/README.md +98 -14
  2. package/dist/conformance.d.mts +18 -0
  3. package/dist/conformance.mjs +31 -0
  4. package/dist/effect-plugin.mjs +1 -1
  5. package/dist/exceptions-Dybl9xpc.mjs +11 -0
  6. package/dist/exceptions.mjs +1 -1
  7. package/dist/foldkit-plugin.mjs +1 -1
  8. package/dist/formal.d.mts +131 -3
  9. package/dist/formal.mjs +716 -65
  10. package/dist/guard.mjs +2 -2
  11. package/dist/{lint-JSnPsGO1.mjs → lint-IhmtnBbx.mjs} +3 -3
  12. package/dist/lint.mjs +1 -1
  13. package/dist/plugin.mjs +1 -1
  14. package/dist/proof.mjs +1 -1
  15. package/dist/trace-file-KuPRWgwt.mjs +17 -0
  16. package/dist/verdict.d.mts +1 -1
  17. package/dist/verdict.mjs +1 -1
  18. package/dist/{verification-p2rSx5lc.d.mts → verification-FgQFU1YN.d.mts} +1 -1
  19. package/dist/verification.d.mts +1 -1
  20. package/dist/verification.mjs +1 -1
  21. package/package.json +6 -2
  22. package/src/formal/cfg.ts +58 -1
  23. package/src/formal/checks.ts +39 -52
  24. package/src/formal/coverage.ts +79 -0
  25. package/src/formal/gate.ts +74 -0
  26. package/src/formal/git.ts +38 -0
  27. package/src/formal/proofs.ts +217 -0
  28. package/src/formal/semantics.ts +110 -0
  29. package/src/formal/specs.ts +80 -34
  30. package/src/formal/tla.ts +24 -2
  31. package/src/formal/trace-file.ts +35 -0
  32. package/src/formal/traces.ts +293 -0
  33. package/src/formal/violations.ts +76 -0
  34. package/src/formal.ts +9 -2
  35. package/dist/exceptions-Bq-9MxoR.mjs +0 -3
  36. package/dist/{effect-plugin-kYxB-5LJ.mjs → effect-plugin-BXUx9PPu.mjs} +1 -1
  37. package/dist/{plugin-BoBRGtGf.mjs → plugin-CwxhPtui.mjs} +1 -1
  38. package/dist/{verification-6s2chr4X.mjs → verification-oAc1Q6I9.mjs} +1 -1
@@ -0,0 +1,293 @@
1
+ import { createHash } from "node:crypto";
2
+ import { basename, dirname, relative } from "node:path";
3
+
4
+ import * as Clock from "effect/Clock";
5
+ import * as Console from "effect/Console";
6
+ import * as Effect from "effect/Effect";
7
+ import { FileSystem } from "effect/FileSystem";
8
+ import * as Option from "effect/Option";
9
+ import { ChildProcess } from "effect/process";
10
+ import * as Schema from "effect/Schema";
11
+ import * as Stream from "effect/Stream";
12
+
13
+ import { derive } from "./cfg.ts";
14
+ import type { Check } from "./checks.ts";
15
+ import { Gate } from "./gate.ts";
16
+ import { FormalError, Tla } from "./tla.ts";
17
+ import { FORMAL_TRACES, receiptPath, sorted } from "./trace-file.ts";
18
+ import { sandbox } from "./violations.ts";
19
+ const quote = (s: string) => JSON.stringify(s);
20
+ const RawState = Schema.Record(Schema.String, Schema.Json);
21
+ const Raw = Schema.Array(RawState);
22
+ const decodeAction = Schema.decodeUnknownSync(
23
+ Schema.Struct({
24
+ name: Schema.String,
25
+ context: Schema.optionalKey(
26
+ Schema.NullOr(Schema.Record(Schema.String, Schema.Json))
27
+ ),
28
+ location: Schema.optionalKey(Schema.Json),
29
+ })
30
+ );
31
+ export const normalize = (
32
+ text: string,
33
+ plan: {
34
+ count: number;
35
+ depth: number;
36
+ init: string;
37
+ actions: ReadonlyMap<string, number>;
38
+ variables: ReadonlyArray<string>;
39
+ constants: Record<string, Schema.Json>;
40
+ }
41
+ ): string => {
42
+ const lines =
43
+ text === ""
44
+ ? []
45
+ : (text.endsWith("\n") ? text.slice(0, -1) : text).split("\n");
46
+ if (lines.length !== plan.count)
47
+ throw new Error(
48
+ `only ${lines.length} of ${plan.count} behaviors reached depth ${plan.depth}`
49
+ );
50
+ return (
51
+ lines
52
+ .map((line, index) => {
53
+ const states = Schema.decodeSync(Schema.fromJsonString(Raw))(line);
54
+ if (states.length !== plan.depth)
55
+ throw new Error(
56
+ `trace ${index} has ${states.length} states; expected ${plan.depth}`
57
+ );
58
+ const steps = states.map((s, i) => {
59
+ if (s.formal_tick !== i)
60
+ throw new Error(`trace ${index} state ${i} has wrong formal_tick`);
61
+ const action = decodeAction(s._action);
62
+ const name = action.name.replace(/^Formal_/u, "");
63
+ if (
64
+ action.name !== `Formal_${name}` ||
65
+ (i === 0 ? name !== plan.init : !plan.actions.has(name))
66
+ )
67
+ throw new Error(
68
+ `trace ${index} state ${i} has unknown action ${action.name}`
69
+ );
70
+ const args = action.context ?? {};
71
+ if (
72
+ Object.keys(args).length !== (i === 0 ? 0 : plan.actions.get(name))
73
+ )
74
+ throw new Error(`trace ${index} state ${i} has wrong action arity`);
75
+ const keys = Object.keys(s).toSorted();
76
+ const expected = [
77
+ ...plan.variables,
78
+ "_action",
79
+ "formal_tick",
80
+ ].toSorted();
81
+ if (JSON.stringify(keys) !== JSON.stringify(expected))
82
+ throw new Error(`trace ${index} state ${i} has wrong variables`);
83
+ return {
84
+ action: name,
85
+ args,
86
+ state: Object.fromEntries(
87
+ Object.entries(s).filter(
88
+ ([k]) => k !== "_action" && k !== "formal_tick"
89
+ )
90
+ ),
91
+ };
92
+ });
93
+ return JSON.stringify(
94
+ sorted({ index, constants: plan.constants, steps })
95
+ );
96
+ })
97
+ .join("\n") + "\n"
98
+ );
99
+ };
100
+ export const traces: Check = (repo) =>
101
+ Effect.gen(function* () {
102
+ const fs = yield* FileSystem;
103
+ const tla = yield* Tla;
104
+ const gate = yield* Gate;
105
+ const problems: { file: string; message: string }[] = [];
106
+ for (const m of repo.models) {
107
+ if (m.entry.mode !== "gate" || !m.entry.traces) continue;
108
+ const t = m.entry.traces;
109
+ const result = yield* gate.run(m);
110
+ if (result._tag === "Failed") continue;
111
+ const finding = yield* Effect.scoped(
112
+ Effect.gen(function* () {
113
+ const section = (k: string) =>
114
+ m.config.cfg.sections.find((s) => s.keyword === k)?.text;
115
+ const spec = section("SPECIFICATION");
116
+ const pair =
117
+ spec !== undefined
118
+ ? m.semantics.specifications.get(spec)
119
+ : { init: section("INIT"), next: section("NEXT") };
120
+ if (pair?.init === undefined || pair.next === undefined)
121
+ return "cannot derive zero-argument INIT/NEXT from config";
122
+ const { init, next } = pair;
123
+ const names = [
124
+ ...new Set(result.coverage.actions.map((a) => a.name)),
125
+ ];
126
+ const actions = new Map<string, number>();
127
+ for (const name of names) {
128
+ const op = m.semantics.operators.get(name);
129
+ if (name === next || !op || op.params.some((p) => p.arity !== 0))
130
+ return `cannot wrap action ${name}: unnamed, INSTANCE'd, or higher-order action`;
131
+ actions.set(name, op.params.length);
132
+ }
133
+ for (const name of Object.keys(t.steer ?? {}))
134
+ if (!actions.has(name)) return `steer key ${name} is not an action`;
135
+ if (
136
+ [...m.semantics.operators.keys(), ...m.semantics.variables].some(
137
+ (n) =>
138
+ n === "FormalTraces" ||
139
+ n === "formal_tick" ||
140
+ n.startsWith("Formal_")
141
+ )
142
+ )
143
+ return "generated trace name collides with spec";
144
+ const dir = yield* sandbox(repo, m);
145
+ const raw = `${dir}/raw.ndjson`;
146
+ const module = basename(m.path, ".tla");
147
+ const slash = "\\";
148
+ const defs = names.map((name) => {
149
+ const params =
150
+ m.semantics.operators.get(name)?.params.map((p) => p.name) ?? [];
151
+ const args = params.length ? `(${params.join(", ")})` : "";
152
+ const keep = t.steer?.[name];
153
+ return `Formal_${name}${args} == Formal_M!${name}${args} /${slash} formal_tick' = formal_tick + 1${keep === undefined ? "" : ` /${slash} Formal_TLC!RandomElement(1 .. ${keep}) = 1`}`;
154
+ });
155
+ const wrapper = [
156
+ "---- MODULE FormalTraces ----",
157
+ `EXTENDS ${module}`,
158
+ "VARIABLE formal_tick",
159
+ `Formal_M == INSTANCE ${module}`,
160
+ "Formal_TLC == INSTANCE TLC",
161
+ "Formal_Ext == INSTANCE TLCExt",
162
+ "Formal_IO == INSTANCE IOUtils",
163
+ `Formal_${init} == Formal_M!${init} /${slash} formal_tick = 0`,
164
+ ...defs,
165
+ 'Formal_Count == Formal_TLC!TLCGet("stats").traces',
166
+ `Formal_Fresh == 1 ${slash}notin DOMAIN Formal_TLC!TLCGet("all") ${slash}/ Formal_TLC!TLCGet(1) # Formal_Count`,
167
+ `Formal_Export == (Formal_TLC!TLCGet("level") = ${t.depth} /${slash} Formal_Fresh) =>`,
168
+ ` /${slash} Formal_TLC!TLCSet(1, Formal_Count)`,
169
+ ` /${slash} Formal_IO!Serialize(<<Formal_Ext!Trace>>, ${quote(raw)}, [format |-> "NDJSON", charset |-> "UTF-8", openOptions |-> <<"WRITE", "CREATE", "APPEND">>])`,
170
+ "====",
171
+ "",
172
+ ].join("\n");
173
+ yield* fs.writeFileString(`${dir}/FormalTraces.tla`, wrapper);
174
+ const cfg = derive(m.config.cfg, {
175
+ simulation: {
176
+ init,
177
+ next,
178
+ overrides: [
179
+ `${init} <- Formal_${init}`,
180
+ ...names.map((n) => `${n} <- Formal_${n}`),
181
+ ],
182
+ },
183
+ });
184
+ yield* fs.writeFileString(`${dir}/FormalTraces.cfg`, cfg);
185
+ const run = yield* tla.tlc({
186
+ spec: `${dir}/FormalTraces.tla`,
187
+ config: `${dir}/FormalTraces.cfg`,
188
+ timeoutSeconds: m.entry.timeoutSeconds,
189
+ mode: {
190
+ _tag: "Simulate",
191
+ num: t.count,
192
+ depth: t.depth,
193
+ seed: t.seed,
194
+ },
195
+ });
196
+ if (run._tag === "TimedOut")
197
+ return `simulation timed out after ${m.entry.timeoutSeconds} s`;
198
+ if (
199
+ run.code !== 0 ||
200
+ run.messages.some((x) => x.severity >= 1 && x.severity <= 3)
201
+ )
202
+ return `simulation exited ${run.code}: ${run.messages
203
+ .filter((x) => x.severity >= 1 && x.severity <= 3)
204
+ .map((x) => x.text)
205
+ .join("; ")}`;
206
+ const text = (yield* fs.exists(raw))
207
+ ? yield* fs.readFileString(raw)
208
+ : "";
209
+ const normalized = yield* Effect.try({
210
+ try: () =>
211
+ normalize(text, {
212
+ count: t.count,
213
+ depth: t.depth,
214
+ init,
215
+ actions,
216
+ variables: m.semantics.variables,
217
+ constants: Object.fromEntries(
218
+ m.config.cfg.constants.flatMap((c) =>
219
+ c._tag === "Value"
220
+ ? [
221
+ [
222
+ c.name,
223
+ /^-?\d+$/u.test(c.value)
224
+ ? Number(c.value)
225
+ : c.value,
226
+ ],
227
+ ]
228
+ : []
229
+ )
230
+ ),
231
+ }),
232
+ catch: (e) =>
233
+ new FormalError({
234
+ message: e instanceof Error ? e.message : String(e),
235
+ }),
236
+ });
237
+ const file = `${dir}/traces.ndjson`;
238
+ yield* fs.writeFileString(file, normalized);
239
+ let owner = dirname(t.conformance);
240
+ while (
241
+ owner !== "." &&
242
+ !repo.tracked.includes(`${owner}/package.json`)
243
+ )
244
+ owner = dirname(owner);
245
+ const started = yield* Clock.currentTimeMillis;
246
+ const conformance = yield* Effect.scoped(
247
+ Effect.gen(function* () {
248
+ const p = yield* ChildProcess.make(
249
+ "vp",
250
+ ["test", "run", relative(owner, t.conformance)],
251
+ {
252
+ cwd: `${repo.root}/${owner}`,
253
+ env: { [FORMAL_TRACES]: file },
254
+ extendEnv: true,
255
+ stdin: "ignore",
256
+ killSignal: "SIGKILL",
257
+ }
258
+ );
259
+ return yield* Effect.all(
260
+ [
261
+ p.stdout.pipe(Stream.decodeText, Stream.mkString),
262
+ p.stderr.pipe(Stream.decodeText, Stream.mkString),
263
+ p.exitCode,
264
+ ],
265
+ { concurrency: "unbounded" }
266
+ );
267
+ }).pipe(Effect.timeoutOption(`${m.entry.timeoutSeconds} seconds`))
268
+ );
269
+ if (Option.isNone(conformance))
270
+ return `conformance test ${t.conformance} timed out`;
271
+ if (Number(conformance.value[2]) !== 0) {
272
+ yield* Console.log(
273
+ (conformance.value[0] + conformance.value[1]).slice(-4000)
274
+ );
275
+ return `conformance test ${t.conformance} failed (vp test exited ${conformance.value[2]})`;
276
+ }
277
+ const receipt = receiptPath(file);
278
+ const replayed = (yield* fs.exists(receipt))
279
+ ? (yield* fs.readFileString(receipt)).trim()
280
+ : "0";
281
+ if (replayed !== String(t.count))
282
+ return `conformance test replayed ${replayed} of ${t.count} traces; register them with replayTraces`;
283
+ yield* Console.log(
284
+ `traces: ${m.path}: ${t.count} traces of ${t.depth} states (sha256 ${createHash("sha256").update(normalized).digest("hex")}), conformance passed in ${((yield* Clock.currentTimeMillis) - started) / 1000} s`
285
+ );
286
+ return undefined;
287
+ })
288
+ ).pipe(Effect.catch((e) => Effect.succeed(e.message)));
289
+ if (finding !== undefined)
290
+ problems.push({ file: m.path, message: finding });
291
+ }
292
+ return problems;
293
+ });
@@ -0,0 +1,76 @@
1
+ import { dirname, basename } from "node:path";
2
+
3
+ import * as Effect from "effect/Effect";
4
+ import { FileSystem } from "effect/FileSystem";
5
+
6
+ import { derive, parseCfg } from "./cfg.ts";
7
+ import type { Model, Repo } from "./specs.ts";
8
+ import { Tla } from "./tla.ts";
9
+ export const sandbox = Effect.fn("formal.sandbox")(function* (
10
+ repo: Repo,
11
+ model: Model
12
+ ) {
13
+ const fs = yield* FileSystem;
14
+ const dir = yield* fs.makeTempDirectoryScoped({ prefix: "formal-model-" });
15
+ for (const file of repo.tracked.filter(
16
+ (f) => dirname(f) === dirname(model.path) && f.endsWith(".tla")
17
+ ))
18
+ yield* fs.copyFile(`${repo.root}/${file}`, `${dir}/${basename(file)}`);
19
+ return dir;
20
+ });
21
+ export const held = Symbol("held");
22
+ export const violate = Effect.fn("formal.violate")(function* (
23
+ repo: Repo,
24
+ m: Model,
25
+ target: string,
26
+ edit?: Model["entry"]["breaks"][number]
27
+ ) {
28
+ return yield* Effect.scoped(
29
+ Effect.gen(function* () {
30
+ const fs = yield* FileSystem;
31
+ const tla = yield* Tla;
32
+ const dir = yield* sandbox(repo, m);
33
+ let cfg = m.config.cfg;
34
+ if (edit) {
35
+ const file = edit.file ?? m.path;
36
+ const text = yield* fs.readFileString(`${repo.root}/${file}`);
37
+ const changed = text.replace(edit.find, edit.replace);
38
+ if (file === m.config.path) {
39
+ const parsed = parseCfg(changed);
40
+ if ("_tag" in parsed) return parsed.message;
41
+ cfg = parsed;
42
+ } else yield* fs.writeFileString(`${dir}/${basename(file)}`, changed);
43
+ }
44
+ const level =
45
+ m.semantics.operators.get(target)?.level ??
46
+ (cfg.properties.includes(target) ? 3 : 1);
47
+ const config = `${dir}/Check.cfg`;
48
+ yield* fs.writeFileString(
49
+ config,
50
+ derive(cfg, { target: { name: target, level } })
51
+ );
52
+ const run = yield* tla.tlc({
53
+ spec: `${dir}/${basename(m.path)}`,
54
+ config,
55
+ timeoutSeconds: m.entry.timeoutSeconds,
56
+ mode: { _tag: "Check", coverage: false },
57
+ });
58
+ if (run._tag === "TimedOut")
59
+ return `TLC timed out after ${m.entry.timeoutSeconds} s`;
60
+ if (run.code === 0) return held;
61
+ const violated = [2107, 2108, 2110, 2112, 2116];
62
+ if (
63
+ [12, 13].includes(run.code) &&
64
+ run.messages.some((x) => violated.includes(x.code)) &&
65
+ !run.messages.some(
66
+ (x) =>
67
+ x.severity >= 1 &&
68
+ x.severity <= 3 &&
69
+ ![...violated, 2121, 2264].includes(x.code)
70
+ )
71
+ )
72
+ return undefined;
73
+ return `TLC exited ${run.code}; ${run.messages.find((x) => x.severity >= 1 && x.severity <= 3)?.text ?? "expected a violation of " + target}`;
74
+ })
75
+ );
76
+ });
package/src/formal.ts CHANGED
@@ -4,10 +4,12 @@ import * as Cause from "effect/Cause";
4
4
  import * as Console from "effect/Console";
5
5
  import * as Effect from "effect/Effect";
6
6
  import * as Exit from "effect/Exit";
7
+ import * as Layer from "effect/Layer";
7
8
  import { ChildProcess } from "effect/process";
8
9
  import * as Stream from "effect/Stream";
9
10
 
10
11
  import { checks, type Finding } from "./formal/checks.ts";
12
+ import { Gate } from "./formal/gate.ts";
11
13
  import { load } from "./formal/specs.ts";
12
14
  import { FormalError, Tla } from "./formal/tla.ts";
13
15
 
@@ -23,7 +25,10 @@ export const formal = Effect.fn("formal")(function* (root: string) {
23
25
  findings.push(...problems.map((problem) => ({ ...problem, check: name })));
24
26
  }
25
27
  findings.sort(
26
- (a, b) => a.file.localeCompare(b.file) || a.check.localeCompare(b.check)
28
+ (a, b) =>
29
+ a.file.localeCompare(b.file) ||
30
+ Object.keys(checks).indexOf(a.check) -
31
+ Object.keys(checks).indexOf(b.check)
27
32
  );
28
33
  if (findings.length) {
29
34
  for (const f of findings)
@@ -59,7 +64,9 @@ if (import.meta.main) {
59
64
  return yield* new FormalError({
60
65
  message: "run formal inside a git repository",
61
66
  });
62
- return yield* formal(root.trim()).pipe(Effect.provide(Tla.layer));
67
+ return yield* formal(root.trim()).pipe(
68
+ Effect.provide(Gate.layer.pipe(Layer.provideMerge(Tla.layer)))
69
+ );
63
70
  })
64
71
  ).pipe(Effect.provide(NodeServices.layer))
65
72
  );
@@ -1,3 +0,0 @@
1
- // src/exceptions.ts
2
- const exceptions = [];
3
- export { exceptions as t };
@@ -6,8 +6,8 @@ import * as Option from "effect/Option";
6
6
  import * as R from "effect/Record";
7
7
  import * as Schema from "effect/Schema";
8
8
  import * as Str from "effect/String";
9
- import { AST, Diagnostic, Plugin, Rule, RuleContext, Scope, SourceCode, Visitor } from "effect-oxlint";
10
9
  import * as Effect from "effect/Effect";
10
+ import { AST, Diagnostic, Plugin, Rule, RuleContext, Scope, SourceCode, Visitor } from "effect-oxlint";
11
11
  import * as Ref from "effect/Ref";
12
12
  import { pipe as pipe$1 } from "effect";
13
13
  import * as Result from "effect/Result";
@@ -4,8 +4,8 @@ import { dual } from "effect/Function";
4
4
  import * as HashSet from "effect/HashSet";
5
5
  import * as Option from "effect/Option";
6
6
  import * as Str from "effect/String";
7
- import { Comment, Diagnostic, Plugin, Rule, RuleContext } from "effect-oxlint";
8
7
  import * as Effect from "effect/Effect";
8
+ import { Comment, Diagnostic, Plugin, Rule, RuleContext } from "effect-oxlint";
9
9
  import * as HashMap from "effect/HashMap";
10
10
  // src/rules/no-comments.ts
11
11
  const noCommentsRule = Rule.define({
@@ -1,12 +1,12 @@
1
1
  import * as Data from "effect/Data";
2
2
  import * as Schema from "effect/Schema";
3
+ import * as Config from "effect/Config";
3
4
  import * as Effect from "effect/Effect";
4
5
  import { NodeServices } from "@effect/platform-node";
5
6
  import * as Cause from "effect/Cause";
6
7
  import * as Console from "effect/Console";
7
8
  import * as Exit from "effect/Exit";
8
9
  import { FileSystem } from "effect/FileSystem";
9
- import * as Config from "effect/Config";
10
10
  import { Octokit } from "@octokit/rest";
11
11
  import * as Redacted from "effect/Redacted";
12
12
  // src/verification.ts