lawspec 0.17.2 → 0.18.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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,142 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.18.0
4
+
5
+ ### Railway combinators
6
+
7
+ - `>>=`, `<$>`, `<!>`, `<|>`, `??`, `>=>`, `|>` and `<*>`, and the prelude
8
+ names `bind`, `then`, `map`, `mapError`, `orElse`, `fallback`, `fromEither`,
9
+ `andThen`, `pipe`, `both`, `ensure`, `isLeft` and `isRight`, sequence, map
10
+ and recover `Either` values in laws and checked definitions on every target.
11
+ See [expressions](docs/reference/language/expressions-and-arithmetic.md).
12
+ - `Pair` joins the built-in collections unit, and `prelude.select` chooses
13
+ between two values.
14
+
15
+ ### Generated workflows
16
+
17
+ - LawSpec now generates each `workflow` on every target from its stages:
18
+ steps, `then`, `map`, `mapError`, `tap`, `ensure`, `orElse`, `fallback`, and
19
+ `all` groups whose results `combine` joins. With `accumulate`, an `all`
20
+ group reports every failing step's error. See
21
+ [workflows](docs/reference/language/workflows.md).
22
+ - Steps may fail with different error types. A declared error type takes them
23
+ through `mapError`; with `Either _ T`, LawSpec generates an error type named
24
+ after the workflow, with a constructor per failing step
25
+ (`PlaceOrderValidateOrderFailed`).
26
+ - Generated laws check that each workflow composes its stages, succeeds when
27
+ every stage does, stops when a step fails, and recovers with each handler.
28
+ - **Migration:** hand-written workflow adapters are no longer called. Remove
29
+ them, and move any behaviour they had into the steps.
30
+
31
+ ### Policies
32
+
33
+ - A step can run under `retry` (immediate, fixed, linear, exponential,
34
+ fibonacci or custom, with optional jitter and a `when` predicate),
35
+ `timeout`, `rateLimit` (token bucket, leaky bucket, fixed or sliding
36
+ window; wait or reject), `circuitBreaker`, `bulkhead`, `cache`,
37
+ `compensate` and `hedge`. A policy failure becomes a constructor of a
38
+ generated error type, or the value a declared error type names with `else`.
39
+ - Workflows run under a workflow runtime: a real or virtual clock, a SplitMix64
40
+ random source identical on every target, a trace, and the state of
41
+ limiters, breakers, bulkheads and caches. Callers create one to give a
42
+ workflow its own state or a virtual clock; otherwise a shared runtime is used.
43
+ - The rate limits, breaker and bulkhead are written once, as checked
44
+ definitions of a built-in unit, `lawspec.resilience`, so they behave the same
45
+ on every target. A new resilience acceptance suite checks each target's
46
+ runtime against them.
47
+ - Generated tests run workflows on a virtual clock with stateful policies,
48
+ timeouts and hedges off; retries still apply.
49
+
50
+ ### Durations
51
+
52
+ - `Duration` is a whole number of microseconds, exact on every target, with
53
+ literals (`250ms`, `2s`, `5min`), arithmetic, comparisons and native types
54
+ (`timedelta`, `time.Duration`, `java.time.Duration`,
55
+ `kotlin.time.Duration`, `std::time::Duration`). See
56
+ [durations](docs/reference/language/durations.md).
57
+ - The totality audit proves more: products and quotients are atoms, quotients
58
+ are bounded, calls satisfy their definitions' postconditions, and unwrapped
59
+ wrapper values satisfy their constraints.
60
+
61
+ ### Other changes
62
+
63
+ - A definition or adapter named with a target keyword is emitted with a
64
+ leading underscore on that target (`class` is `_class` in Python); such names
65
+ were rejected or broke the build before.
66
+ - On JavaScript and TypeScript, a checked definition that calls an `async`
67
+ adapter, directly or through another definition, is itself `async`.
68
+ - Kotlin workflows can call `suspend` adapters. The Kotlin scaffold depends on
69
+ `kotlinx-coroutines-core`, and `lawspec doctor` reports it missing.
70
+ - Python: a synchronous definition called from inside a running event loop
71
+ (from an `async` adapter) awaits its asynchronous steps on a thread of its
72
+ own instead of failing.
73
+ - Python property tests have no per-example deadline, since adapters may do
74
+ real work.
75
+
76
+ ## 0.17.5
77
+
78
+ ### `lawspec test` confirms that each law's tests ran
79
+
80
+ - A test filter that matches nothing makes Go, Rust, Node, Kotest and hspec
81
+ report success without running anything. `lawspec test` now reads each
82
+ runner's own report (pytest and Node JUnit XML, `go test -json`, the
83
+ Surefire and Gradle reports, and Rust's and hspec's per-test output) and
84
+ records a law as passing only if at least one of its tests ran and was not
85
+ skipped. A selected law with no executed test fails the run, naming the law.
86
+ - Results and runner reports live in `.lawspec/results` and `.lawspec/reports`,
87
+ each with its own `.gitignore`.
88
+
89
+ ## 0.17.4
90
+
91
+ ### `lawspec test`
92
+
93
+ - Runs the generated tests of only the laws whose results may have changed
94
+ since their last passing run, through each target's own runner, and records
95
+ the laws that pass. A law runs again when the law changes, or anything it
96
+ depends on: the types and definitions it reaches, its unit's generated
97
+ tests, the LawSpec version, the target's settings, the project's build and
98
+ lock files, the toolchain, and, for a law that calls adapters, any file in
99
+ the project LawSpec did not generate. `--fresh` runs every law. See
100
+ [`lawspec test`](docs/reference/cli.md#test).
101
+ - Every run uses one random seed for all property tests, printed in the
102
+ summary and recorded with each pass; `--seed` fixes it.
103
+ - `planGeneration` responses list each law's generated test file, its
104
+ position in the unit, its dependency key and whether it calls adapters
105
+ (`tests`).
106
+
107
+ ### Changes to generated tests
108
+
109
+ - Property tests read their seed from `LAWSPEC_SEED` on every target, so a
110
+ failing run can be repeated exactly.
111
+ - Kotlin and Haskell property tests are named `law<n>Property: <law>` like
112
+ their example and boundary tests, so each law's tests can be selected by
113
+ name.
114
+
115
+ ## 0.17.3
116
+
117
+ ### Incremental front end
118
+
119
+ - Each law's expansion and type checking, and its elaboration to Core, are
120
+ keyed by exactly their inputs: the law, the laws it invokes, its unit's
121
+ signatures and the program's data types. Editing a definition's body, or
122
+ another unit's laws, no longer re-checks a law; the dependency keys of
123
+ 0.17.2 still replan the laws that reach the edit.
124
+ - Unit validation and totality checks are keyed by the unit.
125
+ - Evidence discharge shares the test planner's work, and builds the type
126
+ registry once per program rather than once per law.
127
+
128
+ ### On-disk compiler cache
129
+
130
+ - `lawspec check`, `evidence`, `explain` and `generate` keep the compiler's
131
+ work in `.lawspec/cache` and reuse it across runs. Results are identical to
132
+ an uncached run. With every bundled example in one project, a repeated
133
+ `lawspec check` takes 4.7 seconds instead of 8.4, and generating Python
134
+ tests through the API 9.2 instead of 18.2 (natively, a third of the time).
135
+ - One folder per compiler build, with its own `.gitignore`; damaged entries
136
+ are recomputed. `--no-cache` or `"cache": false` turns it off. See
137
+ [the compiler cache](docs/reference/cli.md#the-compiler-cache).
138
+ - API requests may name a `cacheDirectory` to share work the same way.
139
+
3
140
  ## 0.17.2
4
141
 
5
142
  ### Dependency-tracked incremental compilation
package/README.md CHANGED
@@ -30,7 +30,7 @@ Node 22+ and the selected target's build tools are required. No Haskell
30
30
  toolchain is needed. The reference platforms are macOS and Linux.
31
31
 
32
32
  ```sh
33
- npm install --save-dev lawspec@0.17.2
33
+ npm install --save-dev lawspec@0.18.0
34
34
  npx lawspec --version
35
35
  ```
36
36
 
@@ -40,8 +40,8 @@ LawSpec can create `package.json` and its test script:
40
40
  ```sh
41
41
  mkdir lawspec-example
42
42
  cd lawspec-example
43
- npm exec --package=lawspec@0.17.2 -- lawspec init --target javascript
44
- npm install --save-dev lawspec@0.17.2
43
+ npm exec --package=lawspec@0.18.0 -- lawspec init --target javascript
44
+ npm install --save-dev lawspec@0.18.0
45
45
  npx lawspec check
46
46
  npx lawspec explain 'example.atoi_codec::itoa and then atoi yields a'
47
47
  npx lawspec doctor
package/bin/lawspec.mjs CHANGED
@@ -1,12 +1,15 @@
1
1
  #!/usr/bin/env node
2
2
  // Generated from templates/npm/bin/lawspec.mjs by lawspec-dev generate. Do not edit.
3
- import { readFile, mkdir, readdir, stat } from "node:fs/promises";
3
+ import { readFile, mkdir, readdir, rm, stat, writeFile } from "node:fs/promises";
4
+ import { createHash } from "node:crypto";
4
5
  import path from "node:path";
5
6
  import { createCompiler } from "../api.mjs";
6
7
  import { targets, templates, commands, setup } from "../templates.mjs";
7
8
  import { generateExamples } from "../examples-command.mjs";
8
9
  import { showScalar } from "../scalars.mjs";
9
10
  import { doctor } from "../doctor.mjs";
11
+ import { spawn } from "node:child_process";
12
+ import { environmentDigest, executedTests, invocations, lawKeys, projectDigest } from "../test-command.mjs";
10
13
  import {
11
14
  readOptional,
12
15
  planWrites,
@@ -14,18 +17,18 @@ import {
14
17
  atomicWrite,
15
18
  safePath,
16
19
  } from "../files.mjs";
17
- const VERSION = "0.17.2";
20
+ const VERSION = "0.18.0";
18
21
  const args = process.argv.slice(2);
19
22
  const verb = args.shift();
20
23
  const options = {};
21
24
  const positional = [];
22
25
  for (let i = 0; i < args.length; i++) {
23
26
  const arg = args[i];
24
- if (["--target", "--project", "--config", "--output", "--machine-bits", "--example"].includes(arg)) {
27
+ if (["--target", "--project", "--config", "--output", "--machine-bits", "--example", "--seed"].includes(arg)) {
25
28
  if (!args[i + 1] || args[i + 1].startsWith("--"))
26
29
  throw new Error(`Missing value for ${arg}`);
27
30
  options[arg.slice(2)] = args[++i];
28
- } else if (["--dry-run", "--check", "--json", "--minify"].includes(arg))
31
+ } else if (["--dry-run", "--check", "--json", "--minify", "--no-cache", "--fresh"].includes(arg))
29
32
  options[arg.slice(2)] = true;
30
33
  else if (arg.startsWith("--")) throw new Error(`Unknown option: ${arg}`);
31
34
  else positional.push(arg);
@@ -237,6 +240,130 @@ function explainExamples(law) {
237
240
  ex.expectations.map(e => ` expect ${showAssertion(e)}`).join("\n")
238
241
  ).join("\n");
239
242
  }
243
+ // The compiler keeps work between runs in .lawspec/cache, in one folder per
244
+ // compiler build, so a different build never reads another's entries. The
245
+ // WebAssembly compiler sees only the working directory. A command that fails
246
+ // removes the .lawspec folder if it created it, leaving the project as it was.
247
+ let createdState = null;
248
+ async function cacheDirectory(config) {
249
+ if (options["no-cache"] || config.cache === false) return undefined;
250
+ const folder = path.join(configRoot, ".lawspec", "cache");
251
+ const relative = path.relative(process.cwd(), folder);
252
+ if (relative.startsWith("..") || path.isAbsolute(relative)) return undefined;
253
+ const build = (await buildDigest()).slice(0, 16);
254
+ const state = path.join(configRoot, ".lawspec");
255
+ if ((await readOptionalDirectory(state)) === null) createdState = state;
256
+ await mkdir(path.join(folder, build), { recursive: true });
257
+ await writeFile(path.join(folder, ".gitignore"), "*\n");
258
+ for (const entry of await readdir(folder))
259
+ if (entry !== build && entry !== ".gitignore")
260
+ await rm(path.join(folder, entry), { recursive: true, force: true });
261
+ return path.join(relative, build).split(path.sep).join("/");
262
+ }
263
+ // The compiler build, by the digest of its WebAssembly module.
264
+ let buildDigestValue = null;
265
+ async function buildDigest() {
266
+ buildDigestValue ??= createHash("sha256")
267
+ .update(await readFile(new URL("../core.wasm", import.meta.url)))
268
+ .digest("hex");
269
+ return buildDigestValue;
270
+ }
271
+ // lawspec test: run the tests of the laws whose results may have changed,
272
+ // and record each passing law's key and seed (see test-command.mjs).
273
+ async function runTests(compiler, input, selected, roots, config) {
274
+ const seed = options.seed ?? String(1 + Math.floor(Math.random() * 2147483646));
275
+ const offline = process.env.LAWSPEC_OFFLINE === "1";
276
+ const build = await buildDigest();
277
+ const summaries = [];
278
+ for (const [i, target] of selected.entries()) {
279
+ const root = roots[i];
280
+ const planned = diagnostics(await compiler.planGeneration({
281
+ ...input, target: target.language, sourceDir: target.sourceDir, testDir: target.testDir,
282
+ nativeBindings: target.nativeBindings, minify: options.minify === true,
283
+ }));
284
+ const pending = await planWrites(root, planned.files);
285
+ if (pending.changes.length)
286
+ throw new Error(`${target.language}: generated files are out of date; run lawspec generate${options.minify ? " --minify" : ""}`);
287
+ const report = await doctor(target, root, planned.files);
288
+ if (!report.ok) throw new Error(`${target.language}: ${report.message}\n${report.instructions}`);
289
+ const generated = new Set(planned.files.filter((f) => f.ownership === "generated").map((f) => f.path));
290
+ const keys = lawKeys({
291
+ build, target, machineBits: input.machineBits, minify: options.minify === true,
292
+ tests: planned.tests, files: planned.files,
293
+ environment: await environmentDigest(root, report),
294
+ project: await projectDigest(root, generated),
295
+ });
296
+ const resultsFile = path.join(configRoot, ".lawspec", "results",
297
+ `${target.language}-${createHash("sha256").update(root).digest("hex").slice(0, 12)}.json`);
298
+ const previous = JSON.parse((await readOptional(resultsFile)) ?? '{"version":1,"laws":{}}');
299
+ const stale = planned.tests.filter((entry) => options.fresh || previous.laws[entry.law]?.key !== keys.get(entry.law));
300
+ const passed = [];
301
+ const unrun = [];
302
+ let failed = false;
303
+ const scratch = path.join(configRoot, ".lawspec", "reports", target.language);
304
+ await rm(scratch, { recursive: true, force: true });
305
+ await mkdir(scratch, { recursive: true });
306
+ await writeFile(path.join(path.dirname(scratch), ".gitignore"), "*\n");
307
+ for (const run of stale.length ? invocations(target, stale, { offline, scratch }) : []) {
308
+ const since = Date.now() - 1000;
309
+ const { ok, output } = await spawned(run.command, run.args, root,
310
+ { ...process.env, ...run.env, LAWSPEC_SEED: seed, HSPEC_SEED: seed }, run.report?.kind === "go-json");
311
+ if (!ok) { failed = true; break; }
312
+ // A runner whose filter matched nothing reports success, so a law
313
+ // counts as passed only if the runner's report shows its tests ran.
314
+ const executed = new Set((await executedTests(run.report, output, root, since)).flatMap(run.ran ?? (() => [])));
315
+ passed.push(...run.laws.filter((law) => executed.has(law)));
316
+ unrun.push(...run.laws.filter((law) => !executed.has(law)));
317
+ }
318
+ if (unrun.length) failed = true;
319
+ const laws = Object.fromEntries(planned.tests.filter((entry) => previous.laws[entry.law]).map((entry) => [entry.law, previous.laws[entry.law]]));
320
+ for (const entry of passed) laws[entry.law] = { key: keys.get(entry.law), seed: Number(seed), passed: new Date().toISOString() };
321
+ await mkdir(path.dirname(resultsFile), { recursive: true });
322
+ await writeFile(path.join(path.dirname(resultsFile), ".gitignore"), "*\n");
323
+ await writeFile(resultsFile, JSON.stringify({ version: 1, laws }, null, 2) + "\n");
324
+ summaries.push({ target: target.language, seed: Number(seed), ran: stale.map((e) => e.law),
325
+ unchanged: planned.tests.length - stale.length, ok: !failed,
326
+ ...(unrun.length ? { unrun: unrun.map((e) => e.law) } : {}) });
327
+ }
328
+ output(options.json ? summaries : summaries.map((s) =>
329
+ `${s.target}: ${s.ran.length ? `ran ${s.ran.length} law(s) with seed ${s.seed}` : "nothing to run"}` +
330
+ `, ${s.unchanged} unchanged since their last passing run.${s.ok ? "" : " FAILED"}` +
331
+ (s.unrun ? `\nNo tests ran for ${s.unrun.join(", ")}; the runner matched none of their tests.` : "")).join("\n"));
332
+ if (summaries.some((s) => !s.ok)) process.exitCode = 1;
333
+ }
334
+ // Run a native test command, showing its output (on stderr with --json) and
335
+ // keeping it. Go's JSON events are shown as the text they carry.
336
+ function spawned(command, args, cwd, env, goJson = false) {
337
+ return new Promise((resolve, reject) => {
338
+ const child = spawn(command, args, { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
339
+ const shown = options.json ? process.stderr : process.stdout;
340
+ let output = "";
341
+ let pending = "";
342
+ child.stdout.on("data", (chunk) => {
343
+ const text = chunk.toString();
344
+ output += text;
345
+ if (!goJson) return shown.write(text);
346
+ pending += text;
347
+ const lines = pending.split("\n");
348
+ pending = lines.pop();
349
+ for (const line of lines) {
350
+ try { const event = JSON.parse(line); if (event.Output) shown.write(event.Output); }
351
+ catch { shown.write(line + "\n"); }
352
+ }
353
+ });
354
+ child.stderr.on("data", (chunk) => { output += chunk.toString(); process.stderr.write(chunk); });
355
+ child.on("error", reject);
356
+ child.on("close", (code) => resolve({ ok: code === 0, output }));
357
+ });
358
+ }
359
+ async function readOptionalDirectory(folder) {
360
+ try {
361
+ return await readdir(folder);
362
+ } catch (error) {
363
+ if (error.code === "ENOENT") return null;
364
+ throw error;
365
+ }
366
+ }
240
367
  async function main() {
241
368
  if (options['machine-bits'] !== undefined) {
242
369
  options.machineBits = Number(options['machine-bits']);
@@ -244,7 +371,7 @@ async function main() {
244
371
  }
245
372
  if (!verb || ["help", "--help", "-h"].includes(verb)) {
246
373
  output(
247
- "LawSpec " + VERSION + "\nUsage: lawspec init --target <language> [--project <directory>] [--minify]\n lawspec check | doctor | explain <unit>::<law> | generate\n lawspec evidence [<unit> | <unit>::<declaration>]\n lawspec package [--project <package directory>]\n lawspec examples [--example payments] [--target <language>] [--output <directory>]\nOptions: --config <path>, --target <language>, --machine-bits <32|64>, --json\nGeneration: --dry-run, --check, --minify\nTargets: " +
374
+ "LawSpec " + VERSION + "\nUsage: lawspec init --target <language> [--project <directory>] [--minify]\n lawspec check | doctor | explain <unit>::<law> | generate\n lawspec evidence [<unit> | <unit>::<declaration>]\n lawspec test [--target <language>] [--fresh] [--seed <n>]\n lawspec package [--project <package directory>]\n lawspec examples [--example payments] [--target <language>] [--output <directory>]\nOptions: --config <path>, --target <language>, --machine-bits <32|64>, --json, --no-cache\nGeneration: --dry-run, --check, --minify\nTargets: " +
248
375
  targets.join(", "),
249
376
  );
250
377
  return;
@@ -286,11 +413,15 @@ async function main() {
286
413
  }
287
414
  if (options.output) throw new Error("--output is only supported by examples");
288
415
  if (options.example) throw new Error("--example is only supported by examples");
289
- if (options.minify && !["init", "generate", "examples"].includes(verb))
290
- throw new Error("--minify applies to init, generate and examples");
416
+ if (options.minify && !["init", "generate", "examples", "test"].includes(verb))
417
+ throw new Error("--minify applies to init, generate, test and examples");
418
+ if ((options.fresh || options.seed !== undefined) && verb !== "test")
419
+ throw new Error("--fresh and --seed apply to test");
420
+ if (options.seed !== undefined && !/^[0-9]+$/.test(options.seed))
421
+ throw new Error("--seed must be a whole number");
291
422
  if (verb === "init") return init();
292
423
  if (verb === "package") return packageCommand();
293
- if (!["check", "doctor", "evidence", "explain", "generate"].includes(verb))
424
+ if (!["check", "doctor", "evidence", "explain", "generate", "test"].includes(verb))
294
425
  throw new Error(`Unknown command: ${verb}`);
295
426
  const config = JSON.parse(await readFile(configFile, "utf8"));
296
427
  if (
@@ -304,7 +435,7 @@ async function main() {
304
435
  const selected = config.targets.filter(
305
436
  (t) => !options.target || t.language === options.target,
306
437
  );
307
- if (["doctor", "generate"].includes(verb) && !selected.length)
438
+ if (["doctor", "generate", "test"].includes(verb) && !selected.length)
308
439
  throw new Error("No matching configured target");
309
440
  const roots = selected.map((t) => path.resolve(configRoot, t.root));
310
441
  if (new Set(roots).size !== roots.length)
@@ -327,7 +458,10 @@ async function main() {
327
458
  return;
328
459
  }
329
460
  if (config.machineBits !== undefined && ![32, 64].includes(config.machineBits)) throw new Error("machineBits must be 32 or 64");
461
+ if (config.cache !== undefined && typeof config.cache !== "boolean") throw new Error("cache must be true or false");
462
+ const cache = await cacheDirectory(config);
330
463
  const input = {
464
+ ...(cache === undefined ? {} : { cacheDirectory: cache }),
331
465
  sources: await sources(config),
332
466
  ...(await packageInput(config, configRoot)),
333
467
  generation: config.generation,
@@ -411,6 +545,7 @@ async function main() {
411
545
  );
412
546
  return;
413
547
  }
548
+ if (verb === "test") return runTests(compiler, input, selected, roots, config);
414
549
  if (options["dry-run"] && options.check)
415
550
  throw new Error("--dry-run and --check are mutually exclusive");
416
551
  const artifacts = [];
@@ -461,7 +596,8 @@ async function main() {
461
596
  if (options.check && plans.some((p) => p.changes.length))
462
597
  process.exitCode = 1;
463
598
  }
464
- main().catch((error) => {
599
+ main().catch(async (error) => {
600
+ if (createdState !== null) await rm(createdState, { recursive: true, force: true });
465
601
  if (options.json)
466
602
  output({
467
603
  diagnostics: error.diagnostics || [