lawspec 0.31.1 → 0.31.3

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 (79) hide show
  1. package/CHANGELOG.md +89 -2
  2. package/README.md +85 -9
  3. package/api.mjs +14 -9
  4. package/authoring.mjs +899 -0
  5. package/beam-coverage.mjs +190 -65
  6. package/beam-doctor.mjs +343 -124
  7. package/bin/lawspec.mjs +1949 -661
  8. package/build.json +134 -128
  9. package/component-packages.mjs +662 -176
  10. package/component.d.ts +82 -20
  11. package/component.mjs +317 -94
  12. package/core.wasm +2 -2
  13. package/core_jsffi.js +5 -5
  14. package/doctor.mjs +558 -299
  15. package/examples-command.mjs +44 -23
  16. package/failure-database.mjs +60 -17
  17. package/files.mjs +122 -62
  18. package/index.d.ts +585 -312
  19. package/input-files.mjs +90 -25
  20. package/launcher.mjs +72 -31
  21. package/learn/coverage.json +184 -112
  22. package/learn/curriculum.json +4 -1
  23. package/learn/vendor/fantomas/{LawSpec.Learn.Formatter.5arcua4vy0.wasm → LawSpec.Learn.Formatter.poiijdbsl9.wasm} +0 -0
  24. package/learn/vendor/fantomas/dotnet.js +3 -3
  25. package/learn/vendor/manifest.json +4 -8
  26. package/lsp.mjs +444 -133
  27. package/mcp.mjs +250 -0
  28. package/native-evidence.mjs +668 -182
  29. package/native-examples.mjs +56 -19
  30. package/native-host.mjs +136 -42
  31. package/native-parsers/clojure.LICENSE +121 -0
  32. package/native-parsers/clojure.wasm +0 -0
  33. package/native-parsers/csharp.LICENSE +21 -0
  34. package/native-parsers/csharp.wasm +0 -0
  35. package/native-parsers/elixir.LICENSE +176 -0
  36. package/native-parsers/elixir.wasm +0 -0
  37. package/native-parsers/erlang.LICENSE +201 -0
  38. package/native-parsers/erlang.wasm +0 -0
  39. package/native-parsers/fsharp.LICENSE +21 -0
  40. package/native-parsers/fsharp.wasm +0 -0
  41. package/native-parsers/gleam.LICENSE +202 -0
  42. package/native-parsers/gleam.wasm +0 -0
  43. package/native-parsers/go.LICENSE +21 -0
  44. package/native-parsers/go.wasm +0 -0
  45. package/native-parsers/groovy.LICENSE +21 -0
  46. package/native-parsers/groovy.wasm +0 -0
  47. package/native-parsers/haskell.LICENSE +21 -0
  48. package/native-parsers/haskell.wasm +0 -0
  49. package/native-parsers/java.LICENSE +21 -0
  50. package/native-parsers/java.wasm +0 -0
  51. package/native-parsers/javascript.LICENSE +21 -0
  52. package/native-parsers/javascript.wasm +0 -0
  53. package/native-parsers/kotlin.LICENSE +9 -0
  54. package/native-parsers/kotlin.wasm +0 -0
  55. package/native-parsers/lock.json +114 -0
  56. package/native-parsers/prolog.LICENSE +21 -0
  57. package/native-parsers/prolog.wasm +0 -0
  58. package/native-parsers/python.LICENSE +21 -0
  59. package/native-parsers/python.wasm +0 -0
  60. package/native-parsers/rust.LICENSE +21 -0
  61. package/native-parsers/rust.wasm +0 -0
  62. package/native-parsers/scala.LICENSE +21 -0
  63. package/native-parsers/scala.wasm +0 -0
  64. package/native-parsers/swift.LICENSE +21 -0
  65. package/native-parsers/swift.wasm +0 -0
  66. package/native-parsers/typescript.LICENSE +21 -0
  67. package/native-parsers/typescript.wasm +0 -0
  68. package/node-events-reporter.mjs +41 -17
  69. package/package.json +4 -3
  70. package/project.mjs +338 -0
  71. package/proof.d.ts +93 -19
  72. package/proof.mjs +1538 -447
  73. package/read-only-hpack.mjs +6 -5
  74. package/scala-build-state.mjs +131 -41
  75. package/scala-coverage.mjs +57 -34
  76. package/scalars.mjs +23 -8
  77. package/templates.mjs +566 -617
  78. package/test-command.mjs +1671 -521
  79. package/learn/vendor/fantomas/LawSpec.Learn.Formatter.u1ne3a6xd2.wasm +0 -0
package/bin/lawspec.mjs CHANGED
@@ -1,25 +1,69 @@
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, rm, stat, writeFile } from "node:fs/promises";
4
- import { createHash } from "node:crypto";
5
- import path from "node:path";
6
- import { createCompiler } from "../api.mjs";
7
- import {readManifest, writeManifest, findManifest, dependencyRanges, resolveComponent} from "../component.mjs";
8
- import {resolveDependencies, packComponent} from "../component-packages.mjs";
9
- import { targets, artifactTargets, templates, commands, setup } from "../templates.mjs";
10
- import { generateExamples } from "../examples-command.mjs";
11
- import { proveWithZ3 } from "../proof.mjs";
12
- import { serveLanguage } from "../lsp.mjs";
13
- import { showScalar } from "../scalars.mjs";
14
- import { doctor } from "../doctor.mjs";
15
- import { recordNativeAttempts, nativeSeed, attestedKeys, readNativeObservations, attachNativeEvidence, nativeEvidenceText } from "../native-evidence.mjs";
16
- import { beamCoverageRequirement, collectBeamCoverage } from "../beam-coverage.mjs";
17
- import { collectScalaCoverage } from "../scala-coverage.mjs";
18
- import {captureScalaBuildFailure,isScalaCompilationFailure} from "../scala-build-state.mjs";
19
- import { failureDatabase, projectKey } from "../failure-database.mjs";
20
- import { spawn, spawnSync } from "node:child_process";
21
- import { benchmarkInvocations, presentationInvocations, presentationDigest, configurationInvocations, preparationInvocations, environmentDigest, executedTests, invocations, lawKeys, previousResult, projectDigest, recordedDigest, selectByTags, mergeJunit,
22
- harnessStatistics, coverageTools, junitFromTests, testsToRun } from "../test-command.mjs";
3
+ import {readFile, mkdir, readdir, rm, stat, writeFile} from 'node:fs/promises';
4
+ import {createHash} from 'node:crypto';
5
+ import path from 'node:path';
6
+ import {collectNativeSources, settleAdvice} from '../authoring.mjs';
7
+ import {createCompiler} from '../api.mjs';
8
+ import {
9
+ readManifest,
10
+ writeManifest,
11
+ findManifest,
12
+ dependencyRanges,
13
+ resolveComponent,
14
+ } from '../component.mjs';
15
+ import {resolveDependencies, packComponent} from '../component-packages.mjs';
16
+ import {
17
+ targets,
18
+ artifactTargets,
19
+ templates,
20
+ commands,
21
+ setup,
22
+ } from '../templates.mjs';
23
+ import {generateExamples} from '../examples-command.mjs';
24
+ import {proveWithZ3} from '../proof.mjs';
25
+ import {serveLanguage} from '../lsp.mjs';
26
+ import {showScalar} from '../scalars.mjs';
27
+ import {doctor} from '../doctor.mjs';
28
+ import {
29
+ recordNativeAttempts,
30
+ nativeSeed,
31
+ attestedKeys,
32
+ readNativeObservations,
33
+ attachNativeEvidence,
34
+ nativeEvidenceText,
35
+ } from '../native-evidence.mjs';
36
+ import {
37
+ beamCoverageRequirement,
38
+ collectBeamCoverage,
39
+ } from '../beam-coverage.mjs';
40
+ import {collectScalaCoverage} from '../scala-coverage.mjs';
41
+ import {
42
+ captureScalaBuildFailure,
43
+ isScalaCompilationFailure,
44
+ } from '../scala-build-state.mjs';
45
+ import {failureDatabase, projectKey} from '../failure-database.mjs';
46
+ import {spawn, spawnSync} from 'node:child_process';
47
+ import {
48
+ benchmarkInvocations,
49
+ presentationInvocations,
50
+ presentationDigest,
51
+ configurationInvocations,
52
+ preparationInvocations,
53
+ environmentDigest,
54
+ executedTests,
55
+ invocations,
56
+ lawKeys,
57
+ previousResult,
58
+ projectDigest,
59
+ recordedDigest,
60
+ selectByTags,
61
+ mergeJunit,
62
+ harnessStatistics,
63
+ coverageTools,
64
+ junitFromTests,
65
+ testsToRun,
66
+ } from '../test-command.mjs';
23
67
  import {
24
68
  readOptional,
25
69
  planWrites,
@@ -27,390 +71,648 @@ import {
27
71
  atomicWrite,
28
72
  safePath,
29
73
  collectSources,
30
- } from "../files.mjs";
31
- const VERSION = "0.31.1";
74
+ } from '../files.mjs';
75
+ const VERSION = '0.31.3';
32
76
  const args = process.argv.slice(2);
33
77
  const verb = args.shift();
34
78
  const options = {};
35
79
  const positional = [];
36
- for (let i = 0; i < args.length; i++) {
80
+ for (let i = 0; i < args.length; i++)
81
+ {
37
82
  const arg = args[i];
38
- if (["--port", "--target", "--project", "--config", "--output", "--machine-bits", "--example", "--seed", "--report", "--attestation", "--view", "--solver", "--proof-timeout", "--proof-memory", "--proof-rlimit", "--proof-seed"].includes(arg)) {
39
- if (!args[i + 1] || args[i + 1].startsWith("--"))
83
+ if (
84
+ [
85
+ '--port',
86
+ '--languages',
87
+ '--target',
88
+ '--project',
89
+ '--config',
90
+ '--output',
91
+ '--machine-bits',
92
+ '--example',
93
+ '--seed',
94
+ '--report',
95
+ '--attestation',
96
+ '--view',
97
+ '--solver',
98
+ '--proof-timeout',
99
+ '--proof-memory',
100
+ '--proof-rlimit',
101
+ '--proof-seed',
102
+ ].includes(arg)
103
+ )
104
+ {
105
+ if (!args[i + 1] || args[i + 1].startsWith('--'))
40
106
  throw new Error(`Missing value for ${arg}`);
41
107
  options[arg.slice(2)] = args[++i];
42
- } else if (["--tag", "--exclude-tag"].includes(arg)) {
108
+ }
109
+ else if (['--tag', '--exclude-tag'].includes(arg))
110
+ {
43
111
  // Repeatable, and each may list several: --tag a,b --tag c.
44
- if (!args[i + 1] || args[i + 1].startsWith("--"))
112
+ if (!args[i + 1] || args[i + 1].startsWith('--'))
45
113
  throw new Error(`Missing value for ${arg}`);
46
- options[arg.slice(2)] = [...(options[arg.slice(2)] ?? []), ...args[++i].split(",").filter(Boolean)];
47
- } else if (["--dry-run", "--check", "--json", "--minify", "--no-cache", "--fresh", "--coverage", "--update-recorded", "--benchmarks", "--stdio", "--warn-matches", "--compile", "--locked", "--offline"].includes(arg))
114
+ options[arg.slice(2)] = [
115
+ ...(options[arg.slice(2)] ?? []),
116
+ ...args[++i].split(',').filter(Boolean),
117
+ ];
118
+ }
119
+ else if (
120
+ [
121
+ '--dry-run',
122
+ '--check',
123
+ '--json',
124
+ '--minify',
125
+ '--no-cache',
126
+ '--fresh',
127
+ '--coverage',
128
+ '--update-recorded',
129
+ '--benchmarks',
130
+ '--stdio',
131
+ '--warn-matches',
132
+ '--no-advice',
133
+ '--strict',
134
+ '--compile',
135
+ '--locked',
136
+ '--offline',
137
+ ].includes(arg)
138
+ )
48
139
  options[arg.slice(2)] = true;
49
- else if (arg.startsWith("--")) throw new Error(`Unknown option: ${arg}`);
140
+ else if (arg.startsWith('--')) throw new Error(`Unknown option: ${arg}`);
50
141
  else positional.push(arg);
51
142
  }
52
- let configFile = path.resolve(options.config || "lawspec.edn");
143
+ let configFile = path.resolve(options.config || 'lawspec.edn');
53
144
  let configRoot = path.dirname(configFile);
54
- const output = (value) =>
145
+ const output = value =>
55
146
  console.log(
56
- typeof value === "string" ? value : JSON.stringify(value, null, 2),
147
+ typeof value === 'string' ? value : JSON.stringify(value, null, 2),
57
148
  );
58
- const shellQuote = (value) =>
59
- "'" + String(value).replaceAll("'", "'\\''") + "'";
60
- function testCommand(target, root) {
149
+ const shellQuote = value => "'" + String(value).replaceAll("'", "'\\''") + "'";
150
+ function testCommand(target, root)
151
+ {
61
152
  if (artifactTargets.includes(target.language)) return null;
62
- const testDir = target.testDir || "test";
153
+ const testDir = target.testDir || 'test';
63
154
  let command = commands[target.language];
64
- if (target.language === "python")
65
- command = `${shellQuote(target.python || "python3")} -m pytest`;
66
- if (target.language === "prolog")
67
- command = `${shellQuote(target.python || "python3")} lawspec_test.py`;
68
- if (target.language === "java")
69
- command = `${shellQuote(target.maven || "mvn")} test`;
70
- if (target.language === "kotlin")
71
- command = `${shellQuote(target.gradle || "gradle")} test`;
72
- if (target.language === "scala")
73
- command = `${shellQuote(target.scala || "scala")} test .`;
74
- if (target.language === "javascript")
155
+ if (target.language === 'python')
156
+ command = `${shellQuote(target.python || 'python3')} -m pytest`;
157
+ if (target.language === 'prolog')
158
+ command = `${shellQuote(target.python || 'python3')} lawspec_test.py`;
159
+ if (target.language === 'java')
160
+ command = `${shellQuote(target.maven || 'mvn')} test`;
161
+ if (target.language === 'kotlin')
162
+ command = `${shellQuote(target.gradle || 'gradle')} test`;
163
+ if (target.language === 'scala')
164
+ command = `${shellQuote(target.scala || 'scala')} test .`;
165
+ if (target.language === 'javascript')
75
166
  command = `node --test ${shellQuote(testDir)}/*.test.mjs`;
76
- if (target.language === "typescript")
77
- command = `npm exec -- tsc -p tsconfig.json && node --test ${shellQuote("dist/" + testDir)}/*.test.js`;
167
+ if (target.language === 'typescript')
168
+ command = `npm exec -- tsc -p tsconfig.json && node --test ${shellQuote('dist/' + testDir)}/*.test.js`;
78
169
  return `(cd ${shellQuote(root)} && ${command})`;
79
170
  }
80
171
  // A refuted law fails the command, but evidence still lists it: the
81
172
  // diagnostics then only say which laws are refuted.
82
- function refutedOnly(result) {
83
- return result.diagnostics?.length && result.diagnostics.every((d) => d.code === "refuted") && result.evidence
84
- ? { ...result, refuted: result.diagnostics, diagnostics: [] } : result;
173
+ function refutedOnly(result)
174
+ {
175
+ return result.diagnostics?.length &&
176
+ result.diagnostics.every(d => d.code === 'refuted') &&
177
+ result.evidence
178
+ ? {...result, refuted: result.diagnostics, diagnostics: []}
179
+ : result;
85
180
  }
86
181
 
87
- function diagnostics(result) {
182
+ const emittedWarnings = new Set();
183
+ function diagnostics(result)
184
+ {
185
+ if (!options.json)
186
+ {
187
+ for (const warning of result.warnings ?? [])
188
+ {
189
+ const message = `${warning.at ? `${warning.at.file}:${warning.at.line}:${warning.at.column}: ` : ''}warning ${warning.code}: ${warning.message}`;
190
+ if (!emittedWarnings.has(message))
191
+ {
192
+ console.error(message);
193
+ emittedWarnings.add(message);
194
+ }
195
+ }
196
+ }
88
197
  if (result.diagnostics?.length)
89
198
  throw Object.assign(
90
199
  new Error(
91
200
  result.diagnostics
92
201
  .map(
93
- (d) =>
94
- `${d.at ? `${d.at.file}:${d.at.line}:${d.at.column}: ` : ""}${d.code}: ${d.message}`,
202
+ d =>
203
+ `${d.at ? `${d.at.file}:${d.at.line}:${d.at.column}: ` : ''}${d.code}: ${d.message}`,
95
204
  )
96
- .join("\n"),
205
+ .join('\n'),
97
206
  ),
98
- { diagnostics: result.diagnostics },
207
+ {diagnostics: result.diagnostics},
99
208
  );
100
209
  return result;
101
210
  }
102
- async function sources(config) {
211
+ async function sources(config)
212
+ {
103
213
  return lawspecFiles(configRoot, config.sources);
104
214
  }
105
- async function lawspecFiles(root,entries){return collectSources(root,entries,configRoot);}
106
- async function packageInput(owner, root, optional = false) {
107
- try {
108
- const resolved = await resolveDependencies(path.join(root, "lawspec.edn"), owner,
109
- {locked: !!options.locked, offline: optional || !!options.offline});
110
- return {packages: resolved.packages, dependencies: dependencyRanges(owner), ...(owner.package ? {package: owner.package} : {})};
111
- } catch (error) {
112
- if (optional && (error.code === "ENOENT" || /Offline:/.test(error.message))) return {};
215
+ async function lawspecFiles(root, entries)
216
+ {
217
+ return collectSources(root, entries, configRoot);
218
+ }
219
+ async function packageInput(owner, root, optional = false)
220
+ {
221
+ try
222
+ {
223
+ const resolved = await resolveDependencies(
224
+ path.join(root, 'lawspec.edn'),
225
+ owner,
226
+ {
227
+ locked: !!options.locked,
228
+ readOnly: ['inspect', 'advise'].includes(verb),
229
+ writeLock: !['inspect', 'advise'].includes(verb),
230
+ offline:
231
+ optional || ['inspect', 'advise'].includes(verb) || !!options.offline,
232
+ },
233
+ );
234
+ return {
235
+ packages: resolved.packages,
236
+ dependencies: dependencyRanges(owner),
237
+ ...(owner.package ? {package: owner.package} : {}),
238
+ };
239
+ }
240
+ catch (error)
241
+ {
242
+ if (optional && (error.code === 'ENOENT' || /Offline:/.test(error.message)))
243
+ return {};
113
244
  throw error;
114
245
  }
115
246
  }
116
- async function formatCommand() {
247
+ async function formatCommand()
248
+ {
117
249
  const config = positional.length ? null : await readManifest(configFile);
118
250
  const root = positional.length ? process.cwd() : configRoot;
119
- const files = await collectSources(root, positional.length ? positional : config.sources);
251
+ const files = await collectSources(
252
+ root,
253
+ positional.length ? positional : config.sources,
254
+ );
120
255
  const compiler = await createCompiler();
121
- const result = diagnostics(await compiler.format({
122
- sources: files, compile: !!options.compile, machineBits: options.machineBits ?? 64,
123
- ...(config ? await packageInput(config, configRoot, !options.compile) : {}),
124
- languageProfile: "1.0-rc.2", verification: { layers: [] },
125
- }));
126
- const changed = result.formattedSources.filter((file, index) => file.content !== files[index].content);
127
- if (!options.check) for (const file of changed) await atomicWrite(path.resolve(root, file.path), file.content);
128
- output(options.json ? { changed: changed.map(file => file.path), check: !!options.check }
129
- : changed.length ? `${changed.length} source file(s) ${options.check ? "need formatting" : "formatted"}.` : "All sources are formatted.");
256
+ const result = diagnostics(
257
+ await compiler.format({
258
+ sources: files,
259
+ compile: !!options.compile,
260
+ machineBits: options.machineBits ?? 64,
261
+ ...(config
262
+ ? await packageInput(config, configRoot, !options.compile)
263
+ : {}),
264
+ languageProfile: '1.0-rc.2',
265
+ verification: {layers: []},
266
+ }),
267
+ );
268
+ const changed = result.formattedSources.filter(
269
+ (file, index) => file.content !== files[index].content,
270
+ );
271
+ if (!options.check)
272
+ for (const file of changed)
273
+ await atomicWrite(path.resolve(root, file.path), file.content);
274
+ output(
275
+ options.json
276
+ ? {changed: changed.map(file => file.path), check: !!options.check}
277
+ : changed.length
278
+ ? `${changed.length} source file(s) ${options.check ? 'need formatting' : 'formatted'}.`
279
+ : 'All sources are formatted.',
280
+ );
130
281
  if (options.check && changed.length) process.exitCode = 1;
131
282
  }
132
283
 
133
- async function packageCommand() {
134
- const file = options.config ? configFile : path.resolve(options.project || ".", "lawspec.edn");
284
+ async function packageCommand()
285
+ {
286
+ const file = options.config
287
+ ? configFile
288
+ : path.resolve(options.project || '.', 'lawspec.edn');
135
289
  const directory = path.dirname(file);
136
290
  const manifest = await readManifest(file);
137
- if (!manifest.package) throw new Error(`${file}: expected a package identity`);
138
- const own = {...manifest.package, dependencies: dependencyRanges(manifest), sources: await lawspecFiles(directory, manifest.sources)};
291
+ if (!manifest.package)
292
+ throw new Error(`${file}: expected a package identity`);
293
+ const own = {
294
+ ...manifest.package,
295
+ dependencies: dependencyRanges(manifest),
296
+ sources: await lawspecFiles(directory, manifest.sources),
297
+ };
139
298
  const compiler = await createCompiler();
140
299
  const result = diagnostics(
141
300
  await compiler.check({
142
- languageProfile: '1.0-rc.2', verification: {layers: []},
301
+ languageProfile: '1.0-rc.2',
302
+ verification: {layers: []},
143
303
  sources: own.sources,
144
- package: { name: own.name, version: own.version },
304
+ package: {name: own.name, version: own.version},
145
305
  ...(await packageInput(manifest, directory)),
146
306
  machineBits: options.machineBits ?? 64,
147
307
  }),
148
308
  );
149
309
  // A package owns the units in its namespace; its dependencies' units are not its own.
150
310
  const units = result.units
151
- .map((u) => u.id)
152
- .filter((u) => u === own.name || u.startsWith(own.name + "."));
153
- const laws = result.laws.filter((l) => units.includes(l.owner));
311
+ .map(u => u.id)
312
+ .filter(u => u === own.name || u.startsWith(own.name + '.'));
313
+ const laws = result.laws.filter(l => units.includes(l.owner));
154
314
  const summary = {
155
315
  name: own.name,
156
316
  version: own.version,
157
317
  dependencies: own.dependencies,
158
318
  units,
159
- laws: laws.map((l) => `${l.owner}::${l.name}`),
319
+ laws: laws.map(l => `${l.owner}::${l.name}`),
160
320
  dataTypes: result.dataTypes
161
- .filter((d) => units.some((u) => d.id.startsWith(u + "::")))
162
- .map((d) => d.id),
321
+ .filter(d => units.some(u => d.id.startsWith(u + '::')))
322
+ .map(d => d.id),
163
323
  };
164
- if (options.output) summary.archive = await packComponent(file, options.output);
324
+ if (options.output)
325
+ summary.archive = await packComponent(file, options.output);
165
326
  output(
166
327
  options.json
167
328
  ? summary
168
329
  : `${summary.name} ${summary.version}: ${units.length} unit(s), ${summary.laws.length} law(s), ${summary.dataTypes.length} data type(s).
169
330
  ` +
170
- `Units: ${units.join(", ")}
331
+ `Units: ${units.join(', ')}
171
332
  ` +
172
- `Dependencies: ${Object.entries(summary.dependencies).map(([n, r]) => `${n} ${r}`).join(", ") || "none"}`,
333
+ `Dependencies: ${
334
+ Object.entries(summary.dependencies)
335
+ .map(([n, r]) => `${n} ${r}`)
336
+ .join(', ') || 'none'
337
+ }`,
173
338
  );
174
339
  }
175
- async function init() {
340
+ async function init()
341
+ {
176
342
  const language = options.target;
177
343
  if (!targets.includes(language))
178
- throw new Error(`Choose --target ${targets.join("|")}`);
179
- const root = path.resolve(configRoot, options.project || ".");
180
- if (path.extname(configFile) !== '.edn') throw new Error('Use lawspec.edn; JSON configuration is no longer supported');
181
- for (const old of ['lawspec.json', 'lawspec-package.json']) {
182
- if (await readOptional(path.join(configRoot, old)) !== null)
344
+ throw new Error(`Choose --target ${targets.join('|')}`);
345
+ if (path.extname(configFile) !== '.edn')
346
+ throw new Error(
347
+ 'Use lawspec.edn; JSON configuration is no longer supported',
348
+ );
349
+ for (const old of ['lawspec.json', 'lawspec-package.json'])
350
+ {
351
+ if ((await readOptional(path.join(configRoot, old))) !== null)
183
352
  throw new Error(`${old} is no longer supported; use lawspec.edn`);
184
353
  }
185
354
  const current = await readOptional(configFile);
186
355
  const config =
187
356
  current === null
188
- ? { manifestVersion: 1, component: {name: path.basename(configRoot), version: "0.1.0"}, languageProfile: "1.0-rc.2", verification: { layers: [] }, sources: ["laws"], targets: [] }
357
+ ? {
358
+ manifestVersion: 1,
359
+ component: {name: path.basename(configRoot), version: '0.1.0'},
360
+ languageProfile: '1.0-rc.2',
361
+ verification: {layers: []},
362
+ sources: ['laws'],
363
+ targets: [],
364
+ }
189
365
  : await readManifest(configFile);
190
- if (
191
- config.targets.some(
192
- (t) =>
193
- t.language === language && path.resolve(configRoot, t.root) === root,
194
- )
195
- )
196
- throw new Error("Target is already configured");
197
- await mkdir(root, { recursive: true });
366
+ const declared = config.targets.filter(
367
+ target => target.language === language,
368
+ );
369
+ if (options.project === undefined && declared.length > 1)
370
+ {
371
+ throw new Error(
372
+ `Several ${language} targets are configured; choose the root with --project`,
373
+ );
374
+ }
375
+ const root = path.resolve(
376
+ configRoot,
377
+ options.project ?? declared[0]?.root ?? '.',
378
+ );
379
+ const configured = config.targets.some(
380
+ t => t.language === language && path.resolve(configRoot, t.root) === root,
381
+ );
382
+ await mkdir(root, {recursive: true});
198
383
  const buildFiles = [
199
- "Cargo.toml",
200
- "pom.xml",
201
- "pyproject.toml",
202
- "package.json",
203
- "go.mod",
204
- "stack.yaml",
205
- "package.yaml",
206
- "build.gradle",
207
- "build.gradle.kts",
208
- "settings.gradle.kts",
209
- "rebar.config",
210
- "mix.exs",
211
- "gleam.toml",
384
+ 'Cargo.toml',
385
+ 'pom.xml',
386
+ 'pyproject.toml',
387
+ 'package.json',
388
+ 'go.mod',
389
+ 'stack.yaml',
390
+ 'package.yaml',
391
+ 'build.gradle',
392
+ 'build.gradle.kts',
393
+ 'settings.gradle.kts',
394
+ 'rebar.config',
395
+ 'mix.exs',
396
+ 'gleam.toml',
212
397
  ];
213
398
  const hasBuild = (await readdir(root)).some(
214
- (f) => buildFiles.includes(f) || f.endsWith(".cabal"),
399
+ f => buildFiles.includes(f) || f.endsWith('.cabal'),
215
400
  );
216
- const additions = hasBuild ? {} : templates(language, {minify: options.minify === true});
217
- for (const name of Object.keys(additions)) {
401
+ const additions = hasBuild
402
+ ? {}
403
+ : templates(language, {minify: options.minify === true});
404
+ for (const name of Object.keys(additions))
405
+ {
218
406
  const file = await safePath(root, name);
219
407
  if ((await readOptional(file)) !== null)
220
408
  throw new Error(`Will not overwrite ${file}`);
221
409
  }
222
- const starter = await safePath(configRoot, "laws/atoi_codec.lawspec");
410
+ const starter = await safePath(configRoot, 'laws/atoi_codec.lawspec');
223
411
  await safePath(configRoot, path.basename(configFile));
224
412
  if (current === null && (await readOptional(starter)) !== null)
225
413
  throw new Error(
226
- "Starter specification already exists; create lawspec.edn manually to use it",
414
+ 'Starter specification already exists; create lawspec.edn manually to use it',
227
415
  );
228
- if (!hasBuild && language !== "go")
229
- await mkdir(path.join(root, "src"), { recursive: true });
416
+ if (!hasBuild && language !== 'go')
417
+ await mkdir(path.join(root, 'src'), {recursive: true});
230
418
  for (const [name, content] of Object.entries(additions))
231
419
  await atomicWrite(path.join(root, name), content, true);
232
420
  if (current === null)
233
421
  await atomicWrite(
234
422
  starter,
235
- artifactTargets.includes(language) && language !== "make"
236
- ? "unit configuration\ntype Settings is a record{port :: UInt16 enabled :: Bool} end type\nfunction settings (unused :: Unit) -> Settings is Settings record{port = 8080, enabled = true} end function\nend unit\n"
237
- : await readFile(new URL("../starter-rc1.lawspec", import.meta.url), "utf8"),
423
+ artifactTargets.includes(language) && language !== 'make'
424
+ ? 'unit configuration\ntype Settings is a record{port :: UInt16 enabled :: Bool} end type\nfunction settings (unused :: Unit) -> Settings is Settings record{port = 8080, enabled = true} end function\nend unit\n'
425
+ : (
426
+ await readFile(
427
+ new URL('../starter-rc1.lawspec', import.meta.url),
428
+ 'utf8',
429
+ )
430
+ ).replace(/^-- Generated[^\r\n]*Do not edit\.\r?\n/, ''),
238
431
  true,
239
432
  );
240
- if (options.machineBits !== undefined) config.machineBits = options.machineBits;
241
- config.targets.push({
242
- language,
243
- root: path.relative(configRoot, root) || ".",
244
- });
245
- await atomicWrite(
246
- configFile,
247
- writeManifest(config, {compact: options.minify === true}),
248
- current === null,
249
- );
433
+ if (options.machineBits !== undefined)
434
+ config.machineBits = options.machineBits;
435
+ if (!configured)
436
+ config.targets.push({
437
+ language,
438
+ root: path.relative(configRoot, root) || '.',
439
+ });
440
+ if (current === null || !configured || options.machineBits !== undefined)
441
+ {
442
+ await atomicWrite(
443
+ configFile,
444
+ writeManifest(config, {compact: options.minify === true}),
445
+ current === null,
446
+ );
447
+ }
250
448
  output(
251
- `Configured ${language}. ${hasBuild ? "Existing build files preserved." : "Created missing project build files."}\n${setup[language]}\nNext: lawspec doctor, then lawspec generate.`,
449
+ `Configured ${language}. ${hasBuild ? 'Existing build files preserved.' : 'Created missing project build files.'}\n${setup[language]}\nNext: lawspec doctor, then lawspec generate.`,
252
450
  );
253
451
  }
254
- function showAssertion(assertion) {
255
- if (assertion.kind === "equal") return `${assertion.left.text} = ${assertion.right.text}`;
256
- if (assertion.kind === "implies") return `${assertion.guard.text} implies ${showAssertion(assertion.body)}`;
257
- return assertion.items.map(showAssertion).join(" and ");
452
+ function showAssertion(assertion)
453
+ {
454
+ if (assertion.kind === 'equal')
455
+ return `${assertion.left.text} = ${assertion.right.text}`;
456
+ if (assertion.kind === 'implies')
457
+ return `${assertion.guard.text} implies ${showAssertion(assertion.body)}`;
458
+ return assertion.items.map(showAssertion).join(' and ');
258
459
  }
259
460
  // An ability key, as the spec names it: example.shop::ability::Store(Int32)
260
461
  // is Store Int32, lawspec::ability::Fail(example.shop::type::E) is Fail E.
261
- function abilityName(key) {
262
- const short = (text) => text.replace(/[A-Za-z0-9_.]+::(ability|type)::/g, "");
462
+ function abilityName(key)
463
+ {
464
+ const short = text => text.replace(/[A-Za-z0-9_.]+::(ability|type)::/g, '');
263
465
  const match = /^(.*?)(\((.*)\))?$/.exec(short(key));
264
- return match[3] ? `${match[1]} ${match[3].replace(/[()]/g, " ").replace(/;/g, " ").trim()}` : match[1];
466
+ return match[3]
467
+ ? `${match[1]} ${match[3].replace(/[()]/g, ' ').replace(/;/g, ' ').trim()}`
468
+ : match[1];
265
469
  }
266
470
  // The handlers a law runs under, and the ability row of each function its
267
471
  // expansion calls.
268
- function explainAbilities(law, expansion, units) {
269
- const unit = (units || []).find((u) => u.id === law.owner);
472
+ function explainAbilities(law, expansion, units)
473
+ {
474
+ const unit = (units || []).find(u => u.id === law.owner);
270
475
  const called = (unit ? unit.declarations : []).filter(
271
- (d) => d.uses && new RegExp(`\\b${d.name}\\b`).test(expansion),
476
+ d => d.uses && new RegExp(`\\b${d.name}\\b`).test(expansion),
477
+ );
478
+ const handlers = (law.handlers || [])
479
+ .map(h => `\n ${abilityName(h.ability)}: ${h.handler}`)
480
+ .join('');
481
+ const rows = called
482
+ .map(d => `\n ${d.name} uses ${d.uses.map(abilityName).join(', ')}`)
483
+ .join('');
484
+ return (
485
+ (handlers ? `\nhandlers${handlers}` : '') + (rows ? `\nrows${rows}` : '')
272
486
  );
273
- const handlers = (law.handlers || []).map((h) => `\n ${abilityName(h.ability)}: ${h.handler}`).join("");
274
- const rows = called.map((d) => `\n ${d.name} uses ${d.uses.map(abilityName).join(", ")}`).join("");
275
- return (handlers ? `\nhandlers${handlers}` : "") + (rows ? `\nrows${rows}` : "");
276
487
  }
277
- function explainExamples(law) {
278
- return law.examples.map(ex =>
279
- `\nexample ${JSON.stringify(ex.name)}\n` +
280
- ex.bindings.map(b => ` ${b.name} = ${showScalar(b.value)}`).join("\n") + "\n" +
281
- ex.expectations.map(e => ` expect ${showAssertion(e)}`).join("\n")
282
- ).join("\n");
488
+ function explainExamples(law)
489
+ {
490
+ return law.examples
491
+ .map(
492
+ ex =>
493
+ `\nexample ${JSON.stringify(ex.name)}\n` +
494
+ ex.bindings
495
+ .map(b => ` ${b.name} = ${showScalar(b.value)}`)
496
+ .join('\n') +
497
+ '\n' +
498
+ ex.expectations.map(e => ` expect ${showAssertion(e)}`).join('\n'),
499
+ )
500
+ .join('\n');
283
501
  }
284
502
  // What lawspec test last recorded for each law, across targets, and the
285
503
  // environment attestations its runs were given, by run id. A law passed in
286
504
  // an attested run names that run; across targets, its latest passing run.
287
- async function lastRuns() {
288
- const folder = path.join(configRoot, ".lawspec", "results");
505
+ async function lastRuns()
506
+ {
507
+ const folder = path.join(configRoot, '.lawspec', 'results');
289
508
  const runs = new Map();
290
509
  const attestations = new Map();
291
510
  // The outcome each law last had in each attested run, by run id; across
292
511
  // targets a failure outweighs a pass.
293
512
  const outcomes = new Map();
294
- const rank = (o) => ["passed", "known-discrepancy", "skipped", "incomplete", "failed"].indexOf(o);
295
- for (const name of (await readOptionalDirectory(folder)) ?? []) {
296
- if (!name.endsWith(".json")) continue;
297
- const recorded = JSON.parse((await readOptional(path.join(folder, name))) ?? "{}");
298
- for (const [id, attestation] of Object.entries(recorded.attestations ?? {})) attestations.set(id, attestation);
299
- const outcome = (id, law, value) => {
513
+ const rank = o =>
514
+ ['passed', 'known-discrepancy', 'skipped', 'incomplete', 'failed'].indexOf(
515
+ o,
516
+ );
517
+ for (const name of (await readOptionalDirectory(folder)) ?? [])
518
+ {
519
+ if (!name.endsWith('.json')) continue;
520
+ const recorded = JSON.parse(
521
+ (await readOptional(path.join(folder, name))) ?? '{}',
522
+ );
523
+ for (const [id, attestation] of Object.entries(recorded.attestations ?? {}))
524
+ attestations.set(id, attestation);
525
+ const outcome = (id, law, value) =>
526
+ {
300
527
  const known = outcomes.get(id) ?? {};
301
- if (known[law] === undefined || rank(value) > rank(known[law])) known[law] = value;
528
+ if (known[law] === undefined || rank(value) > rank(known[law]))
529
+ known[law] = value;
302
530
  outcomes.set(id, known);
303
531
  };
304
532
  for (const [law, attempt] of Object.entries(recorded.attempts ?? {}))
305
- if (attempt.environment) outcome(attempt.environment, law, attempt.outcome);
533
+ if (attempt.environment)
534
+ outcome(attempt.environment, law, attempt.outcome);
306
535
  for (const [law, run] of Object.entries(recorded.laws ?? {}))
307
- if (run.environment && recorded.attempts?.[law]?.environment !== run.environment) outcome(run.environment, law, "passed");
308
- for (const [law, run] of Object.entries(recorded.laws ?? {})) {
536
+ if (
537
+ run.environment &&
538
+ recorded.attempts?.[law]?.environment !== run.environment
539
+ )
540
+ outcome(run.environment, law, 'passed');
541
+ for (const [law, run] of Object.entries(recorded.laws ?? {}))
542
+ {
309
543
  const known = runs.get(law) ?? {};
310
- const latest = (known.passed ?? "") > (run.passed ?? "") ? known : run;
311
- runs.set(law, { flaky: known.flaky || run.flaky, adequacy: run.adequacy ?? known.adequacy,
312
- passed: latest.passed, seed: latest.seed, environment: latest.environment });
544
+ const latest = (known.passed ?? '') > (run.passed ?? '') ? known : run;
545
+ runs.set(law, {
546
+ flaky: known.flaky || run.flaky,
547
+ adequacy: run.adequacy ?? known.adequacy,
548
+ passed: latest.passed,
549
+ seed: latest.seed,
550
+ environment: latest.environment,
551
+ });
313
552
  }
314
553
  }
315
- return { runs, attestations, outcomes };
554
+ return {runs, attestations, outcomes};
316
555
  }
317
556
  // An environment attestation: a versioned JSON document any tool may write,
318
557
  // recording for one run where each dependency was wired and whether it was
319
558
  // the real dependency or a stand-in. --attestation names one, or lawspec.edn
320
559
  // does; the compiler checks it. It is reporting only and changes no evidence.
321
- async function readAttestation(config) {
322
- const file = options.attestation !== undefined ? path.resolve(options.attestation)
323
- : config.attestation !== undefined ? path.resolve(configRoot, config.attestation) : null;
560
+ async function readAttestation(config)
561
+ {
562
+ const file =
563
+ options.attestation !== undefined
564
+ ? path.resolve(options.attestation)
565
+ : config.attestation !== undefined
566
+ ? path.resolve(configRoot, config.attestation)
567
+ : null;
324
568
  if (file === null) return null;
325
569
  const text = await readOptional(file);
326
570
  if (text === null) throw new Error(`No environment attestation at ${file}`);
327
- try {
571
+ try
572
+ {
328
573
  return JSON.parse(text);
329
- } catch (error) {
330
- throw new Error(`${file}: the environment attestation is not JSON: ${error.message}`);
574
+ }
575
+ catch (error)
576
+ {
577
+ throw new Error(
578
+ `${file}: the environment attestation is not JSON: ${error.message}`,
579
+ );
331
580
  }
332
581
  }
333
582
  // One attested dependency, as lawspec evidence shows it.
334
- function dependencyText(d) {
335
- const level = (c) => /^[0-9]+$/.test(c) ? `conformance level ${c}` : `conformance ${c}`;
583
+ function dependencyText(d)
584
+ {
585
+ const level = c =>
586
+ /^[0-9]+$/.test(c) ? `conformance level ${c}` : `conformance ${c}`;
336
587
  const ran = d.ranAgainst ?? {};
337
588
  const history = ran.historyDigest ?? d.standIn?.historyDigest;
338
- return `${d.dependency}: ` + (d.standIn
339
- ? `stand-in ${d.standIn.identity} ${d.standIn.version} (${level(d.standIn.conformance)}` +
340
- (history ? `, history ${history}${ran.historyFrom === "completed" ? " when completed" : ""}` : "") + ")"
341
- : "real") + ` at ${d.endpoint}` + (d.reached ? "" : " (not reached when recorded)") +
342
- (d.implementation ? `; ${d.implementation.kind} ${d.implementation.product} ${d.implementation.version}` : "") +
343
- (d.contract ? `; contract ${d.contract.package} ${d.contract.version}` : "") +
344
- (d.node ? `; node ${d.node}` + (d.edge ? ` via ${d.edge}` : "") : "") +
345
- (d.completed && !d.completed.reached ? " (not reached when completed)" : "");
589
+ return (
590
+ `${d.dependency}: ` +
591
+ (d.standIn
592
+ ? `stand-in ${d.standIn.identity} ${d.standIn.version} (${level(d.standIn.conformance)}` +
593
+ (history
594
+ ? `, history ${history}${ran.historyFrom === 'completed' ? ' when completed' : ''}`
595
+ : '') +
596
+ ')'
597
+ : 'real') +
598
+ ` at ${d.endpoint}` +
599
+ (d.reached ? '' : ' (not reached when recorded)') +
600
+ (d.implementation
601
+ ? `; ${d.implementation.kind} ${d.implementation.product} ${d.implementation.version}`
602
+ : '') +
603
+ (d.contract
604
+ ? `; contract ${d.contract.package} ${d.contract.version}`
605
+ : '') +
606
+ (d.node ? `; node ${d.node}` + (d.edge ? ` via ${d.edge}` : '') : '') +
607
+ (d.completed && !d.completed.reached ? ' (not reached when completed)' : '')
608
+ );
346
609
  }
347
610
  // What an attested run's document records, as lawspec evidence shows it.
348
- function executionText(run) {
611
+ function executionText(run)
612
+ {
349
613
  const e = run?.execution;
350
- if (!e) return "";
351
- return e.status === "completed" ? `, completed with exit code ${e.exitCode}` :
352
- e.status === "running" ? ", in progress" : ", wiring only";
614
+ if (!e) return '';
615
+ return e.status === 'completed'
616
+ ? `, completed with exit code ${e.exitCode}`
617
+ : e.status === 'running'
618
+ ? ', in progress'
619
+ : ', wiring only';
353
620
  }
354
621
  // Why a law relying on an attested dependency has no completed run linked.
355
- function unlinkedText(run) {
622
+ function unlinkedText(run)
623
+ {
356
624
  const status = run?.execution?.status;
357
- return status === "wired" ? "wiring only; nothing ran" :
358
- status === "running" ? "run in progress; no completed run linked" : "no completed run linked";
625
+ return status === 'wired'
626
+ ? 'wiring only; nothing ran'
627
+ : status === 'running'
628
+ ? 'run in progress; no completed run linked'
629
+ : 'no completed run linked';
359
630
  }
360
631
  // One law's harness, as lawspec evidence shows it.
361
- function harnessText(item) {
632
+ function harnessText(item)
633
+ {
362
634
  const h = item.harness ?? {};
363
635
  const parts = [];
364
636
  if (h.unit) parts.push(`harness ${h.unit}`);
365
- if (h.tags?.length) parts.push(`tags ${h.tags.join(", ")}`);
366
- if (h.strategies?.length) parts.push(h.strategies.map((s) => `${s.input} drawn by ${s.strategy}`).join(", "));
367
- for (const c of h.cover ?? []) parts.push(`cover ${c.percent}% "${c.label}" when ${c.when.text}`);
368
- for (const c of h.classify ?? []) parts.push(`classify ${c.when.text} as "${c.label}"`);
637
+ if (h.tags?.length) parts.push(`tags ${h.tags.join(', ')}`);
638
+ if (h.strategies?.length)
639
+ parts.push(
640
+ h.strategies.map(s => `${s.input} drawn by ${s.strategy}`).join(', '),
641
+ );
642
+ for (const c of h.cover ?? [])
643
+ parts.push(`cover ${c.percent}% "${c.label}" when ${c.when.text}`);
644
+ for (const c of h.classify ?? [])
645
+ parts.push(`classify ${c.when.text} as "${c.label}"`);
369
646
  for (const l of h.labels ?? []) parts.push(`label ${l.text}`);
370
647
  if (h.target) parts.push(`target maximize ${h.target.text}`);
371
648
  if (h.timeoutMilliseconds) parts.push(`timeout ${h.timeoutMilliseconds} ms`);
372
649
  if (h.repeat > 1) parts.push(`repeat ${h.repeat}`);
373
650
  if (h.retries) parts.push(`retry flaky ${h.retries}`);
374
651
  if (h.skip) parts.push(`skip "${h.skip}"`);
375
- if (h.knownDiscrepancy) parts.push(`known discrepancy "${h.knownDiscrepancy}"`);
376
- if (h.orderRandom) parts.push("order random");
377
- if (h.parallel) parts.push("parallel");
378
- const lines = [` ${item.declaration.replace("::law::", "::")}: ${parts.join("; ") || "no harness settings"}`];
379
- for (const run of item.adequacy ?? []) {
380
- lines.push(` last run: ${run.cases} generated case(s)` +
381
- (run.cover ?? []).map((c) => `; cover "${c.label}" ${c.observed}% (needs ${c.required}%)${c.met ? "" : " NOT MET"}`).join(""));
382
- const counts = { ...(run.classes ?? {}), ...Object.fromEntries(Object.entries(run.labels ?? {}).map(([k, v]) => [`label ${k}`, v])) };
652
+ if (h.knownDiscrepancy)
653
+ parts.push(`known discrepancy "${h.knownDiscrepancy}"`);
654
+ if (h.orderRandom) parts.push('order random');
655
+ if (h.parallel) parts.push('parallel');
656
+ const lines = [
657
+ ` ${item.declaration.replace('::law::', '::')}: ${parts.join('; ') || 'no harness settings'}`,
658
+ ];
659
+ for (const run of item.adequacy ?? [])
660
+ {
661
+ lines.push(
662
+ ` last run: ${run.cases} generated case(s)` +
663
+ (run.cover ?? [])
664
+ .map(
665
+ c =>
666
+ `; cover "${c.label}" ${c.observed}% (needs ${c.required}%)${c.met ? '' : ' NOT MET'}`,
667
+ )
668
+ .join(''),
669
+ );
670
+ const counts = {
671
+ ...(run.classes ?? {}),
672
+ ...Object.fromEntries(
673
+ Object.entries(run.labels ?? {}).map(([k, v]) => [`label ${k}`, v]),
674
+ ),
675
+ };
383
676
  if (Object.keys(counts).length)
384
- lines.push(` ${Object.entries(counts).map(([k, v]) => `${k}: ${run.cases ? (100 * v / run.cases).toFixed(1) : 0}%`).join(", ")}`);
677
+ lines.push(
678
+ ` ${Object.entries(counts)
679
+ .map(
680
+ ([k, v]) =>
681
+ `${k}: ${run.cases ? ((100 * v) / run.cases).toFixed(1) : 0}%`,
682
+ )
683
+ .join(', ')}`,
684
+ );
385
685
  }
386
- return lines.join("\n");
686
+ return lines.join('\n');
387
687
  }
388
688
  // The compiler keeps work between runs in .lawspec/cache, in one folder per
389
689
  // compiler build, so a different build never reads another's entries. The
390
690
  // WebAssembly compiler sees only the working directory. A command that fails
391
691
  // removes the .lawspec folder if it created it, leaving the project as it was.
392
692
  let createdState = null;
393
- async function cacheDirectory(config) {
394
- if (options["no-cache"] || config.cache === false) return undefined;
395
- const folder = path.join(configRoot, ".lawspec", "cache");
693
+ async function cacheDirectory(config)
694
+ {
695
+ if (options['no-cache'] || config.cache === false) return undefined;
696
+ const folder = path.join(configRoot, '.lawspec', 'cache');
396
697
  const relative = path.relative(process.cwd(), folder);
397
- if (relative.startsWith("..") || path.isAbsolute(relative)) return undefined;
698
+ if (relative.startsWith('..') || path.isAbsolute(relative)) return undefined;
398
699
  const build = (await buildDigest()).slice(0, 16);
399
- const state = path.join(configRoot, ".lawspec");
700
+ const state = path.join(configRoot, '.lawspec');
400
701
  if ((await readOptionalDirectory(state)) === null) createdState = state;
401
- await mkdir(path.join(folder, build), { recursive: true });
402
- await writeFile(path.join(folder, ".gitignore"), "*\n");
702
+ await mkdir(path.join(folder, build), {recursive: true});
703
+ await writeFile(path.join(folder, '.gitignore'), '*\n');
403
704
  for (const entry of await readdir(folder))
404
- if (entry !== build && entry !== ".gitignore")
405
- await rm(path.join(folder, entry), { recursive: true, force: true });
406
- return path.join(relative, build).split(path.sep).join("/");
705
+ if (entry !== build && entry !== '.gitignore')
706
+ await rm(path.join(folder, entry), {recursive: true, force: true});
707
+ return path.join(relative, build).split(path.sep).join('/');
407
708
  }
408
709
  // The compiler build, by the digest of its WebAssembly module.
409
710
  let buildDigestValue = null;
410
- async function buildDigest() {
411
- buildDigestValue ??= createHash("sha256")
412
- .update(await readFile(new URL("../core.wasm", import.meta.url)))
413
- .digest("hex");
711
+ async function buildDigest()
712
+ {
713
+ buildDigestValue ??= createHash('sha256')
714
+ .update(await readFile(new URL('../core.wasm', import.meta.url)))
715
+ .digest('hex');
414
716
  return buildDigestValue;
415
717
  }
416
718
  // lawspec test: run the tests of the laws whose results may have changed,
@@ -418,383 +720,904 @@ async function buildDigest() {
418
720
  // harness plane chooses which: --tag and --exclude-tag select laws by their
419
721
  // harness tags, and a skipped law runs nothing. A law whose last run failed
420
722
  // runs first, and its failing inputs are replayed first (.lawspec/failures).
421
- async function runTests(compiler, input, selected, roots, config) {
723
+ async function runTests(compiler, input, selected, roots, config)
724
+ {
422
725
  // Recorded values live beside lawspec.edn, under recorded/<unit>/<name>.
423
- const recordedFolder = path.join(configRoot, "recorded");
424
- const seed = options.seed ?? String(1 + Math.floor(Math.random() * 2147483646));
425
- const offline = process.env.LAWSPEC_OFFLINE === "1";
726
+ const recordedFolder = path.join(configRoot, 'recorded');
727
+ const seed =
728
+ options.seed ?? String(1 + Math.floor(Math.random() * 2147483646));
729
+ const offline = process.env.LAWSPEC_OFFLINE === '1';
426
730
  const build = await buildDigest();
427
731
  const summaries = [];
428
732
  const junit = [];
429
- const report = options.report === undefined ? null : parseReport(options.report);
733
+ const report =
734
+ options.report === undefined ? null : parseReport(options.report);
430
735
  const attestation = await readAttestation(config);
431
- for (const [i, target] of selected.entries()) {
736
+ for (const [i, target] of selected.entries())
737
+ {
432
738
  const root = roots[i];
433
- const planned = diagnostics(await compiler.planGeneration({
434
- ...input, target: target.language, sourceDir: target.sourceDir, testDir: target.testDir,
435
- nativeBindings: target.nativeBindings, minify: options.minify === true,
436
- ...(attestation ? { attestation } : {}),
437
- }));
739
+ const planned = diagnostics(
740
+ await compiler.planGeneration({
741
+ ...input,
742
+ target: target.language,
743
+ sourceDir: target.sourceDir,
744
+ testDir: target.testDir,
745
+ nativeBindings: target.nativeBindings,
746
+ minify: options.minify === true,
747
+ ...(attestation ? {attestation} : {}),
748
+ }),
749
+ );
438
750
  // The laws the attestation touches, each with how its dependencies
439
751
  // were wired (the run's id and times aside).
440
752
  const attested = attestedKeys(planned);
441
- if(!planned.tests.length&&!options.benchmarks){
442
- summaries.push({target:target.language,root:target.root,seed:nativeSeed(seed),ran:[],unchanged:0,
443
- ok:true,testsExecuted:0,selection:'no-selected-native-checks'});
753
+ if (!planned.tests.length && !options.benchmarks)
754
+ {
755
+ summaries.push({
756
+ target: target.language,
757
+ root: target.root,
758
+ seed: nativeSeed(seed),
759
+ ran: [],
760
+ unchanged: 0,
761
+ ok: true,
762
+ testsExecuted: 0,
763
+ selection: 'no-selected-native-checks',
764
+ });
444
765
  continue;
445
766
  }
446
767
  const pending = await planWrites(root, planned.files);
447
768
  if (pending.changes.length)
448
- throw new Error(`${target.language}: generated files are out of date; run lawspec generate${options.minify ? " --minify" : ""}`);
449
- for(const preparation of configurationInvocations(target)){
450
- const result=await spawned(preparation.command,preparation.args,root,process.env);
451
- if(!result.ok)throw new Error(`${target.language}: native build metadata preparation failed`);
769
+ throw new Error(
770
+ `${target.language}: generated files are out of date; run lawspec generate${options.minify ? ' --minify' : ''}`,
771
+ );
772
+ for (const preparation of configurationInvocations(target))
773
+ {
774
+ const result = await spawned(
775
+ preparation.command,
776
+ preparation.args,
777
+ root,
778
+ process.env,
779
+ );
780
+ if (!result.ok)
781
+ throw new Error(
782
+ `${target.language}: native build metadata preparation failed`,
783
+ );
452
784
  }
453
785
  const report_ = await doctor(target, root, planned.files);
454
- if (!report_.ok) throw new Error(`${target.language}: ${report_.message}\n${report_.instructions}`);
455
- const generated = new Set(planned.files.filter((f) => f.ownership === "generated").map((f) => f.path));
786
+ if (!report_.ok)
787
+ throw new Error(
788
+ `${target.language}: ${report_.message}\n${report_.instructions}`,
789
+ );
790
+ const generated = new Set(
791
+ planned.files.filter(f => f.ownership === 'generated').map(f => f.path),
792
+ );
456
793
  const keys = lawKeys({
457
- build, target, machineBits: input.machineBits, minify: options.minify === true,
794
+ build,
795
+ target,
796
+ machineBits: input.machineBits,
797
+ minify: options.minify === true,
458
798
  tests: planned.tests,
459
799
  // Recorded values are spec data: a changed recording runs its laws again.
460
- environment: await environmentDigest(root, report_,target.language),
800
+ environment: await environmentDigest(root, report_, target.language),
461
801
  recorded: await recordedDigest(recordedFolder),
462
- project: await projectDigest(root, generated,target.language,{inputRoot:configRoot,inputs:config.inputs??[]}),
802
+ project: await projectDigest(root, generated, target.language, {
803
+ inputRoot: configRoot,
804
+ inputs: config.inputs ?? [],
805
+ }),
463
806
  attested,
464
807
  });
465
808
  const identity = projectKey(root);
466
- const resultsFile = path.join(configRoot, ".lawspec", "results", `${target.language}-${identity}.json`);
467
- const previous = JSON.parse((await readOptional(resultsFile)) ?? '{"version":1,"laws":{}}');
468
- const presentation=presentationDigest(planned.files,await environmentDigest(root,report_,target.language));
469
- if(previous.presentation!==presentation){
470
- const checks=presentationInvocations(target,planned.files,{offline});
471
- if(!checks.length)throw new Error(`${target.language}: no native source validator is available`);
472
- for(const check of checks){
473
- const result=await spawned(check.command,check.args,root,{...process.env,...check.environment});
474
- if(!result.ok)throw new Error(`${target.language}: current generated source failed native validation`);
809
+ const resultsFile = path.join(
810
+ configRoot,
811
+ '.lawspec',
812
+ 'results',
813
+ `${target.language}-${identity}.json`,
814
+ );
815
+ const previous = JSON.parse(
816
+ (await readOptional(resultsFile)) ?? '{"version":1,"laws":{}}',
817
+ );
818
+ const presentation = presentationDigest(
819
+ planned.files,
820
+ await environmentDigest(root, report_, target.language),
821
+ );
822
+ if (previous.presentation !== presentation)
823
+ {
824
+ const checks = presentationInvocations(target, planned.files, {offline});
825
+ if (!checks.length)
826
+ throw new Error(
827
+ `${target.language}: no native source validator is available`,
828
+ );
829
+ for (const check of checks)
830
+ {
831
+ const result = await spawned(check.command, check.args, root, {
832
+ ...process.env,
833
+ ...check.environment,
834
+ });
835
+ if (!result.ok)
836
+ throw new Error(
837
+ `${target.language}: current generated source failed native validation`,
838
+ );
475
839
  }
476
840
  }
477
841
  const attempts = {...(previous.attempts ?? {})};
478
- const {directory: failures, file: databaseFile, database} = await failureDatabase(configRoot, target.language, root);
842
+ const {
843
+ directory: failures,
844
+ file: databaseFile,
845
+ database,
846
+ } = await failureDatabase(configRoot, target.language, root);
479
847
  // Recording again runs every law, so each records what it sees now.
480
- const chosen = selectByTags(planned.tests, options.tag ?? [], options["exclude-tag"] ?? []);
481
- const stale = testsToRun(chosen, keys, previous.laws, database,
482
- {fresh: options.fresh, coverage: options.coverage, updateRecorded: options["update-recorded"]});
848
+ const chosen = selectByTags(
849
+ planned.tests,
850
+ options.tag ?? [],
851
+ options['exclude-tag'] ?? [],
852
+ );
853
+ const stale = testsToRun(chosen, keys, previous.laws, database, {
854
+ fresh: options.fresh,
855
+ coverage: options.coverage,
856
+ updateRecorded: options['update-recorded'],
857
+ });
483
858
  // The failure database: each law whose last run failed, with the seed
484
859
  // that exposed it. Those laws run first, with that seed, so the failing
485
860
  // inputs are generated again; the runtimes keep their own counterexample
486
861
  // databases beside it (Hypothesis, proptest).
487
- const replayed = options.seed === undefined ? stale.filter((entry) => database[entry.law]) : [];
862
+ const replayed =
863
+ options.seed === undefined
864
+ ? stale.filter(entry => database[entry.law])
865
+ : [];
488
866
  const batches = [
489
- ...[...new Set(replayed.map((entry) => nativeSeed(database[entry.law].seed)))].map((s) =>
490
- ({ seed: String(s), entries: replayed.filter((entry) => nativeSeed(database[entry.law].seed) === s) })),
491
- { seed, entries: stale.filter((entry) => !replayed.includes(entry)) },
492
- ].filter((batch) => batch.entries.length);
493
- const profile = {target:target.language,root,machineBits:input.machineBits,
494
- minify:options.minify===true,build};
867
+ ...[
868
+ ...new Set(replayed.map(entry => nativeSeed(database[entry.law].seed))),
869
+ ].map(s => ({
870
+ seed: String(s),
871
+ entries: replayed.filter(
872
+ entry => nativeSeed(database[entry.law].seed) === s,
873
+ ),
874
+ })),
875
+ {seed, entries: stale.filter(entry => !replayed.includes(entry))},
876
+ ].filter(batch => batch.entries.length);
877
+ const profile = {
878
+ target: target.language,
879
+ root,
880
+ machineBits: input.machineBits,
881
+ minify: options.minify === true,
882
+ build,
883
+ };
495
884
  // Persist pending attempts before starting a native process. Interrupted or
496
885
  // failed setup cannot leave an older passing cache entry looking completed.
497
- for(const entry of stale){
498
- Object.assign(attempts,recordNativeAttempts({laws:[entry],command:null},[],
499
- {keys,seed,ok:false,profile,allEntries:planned.tests}));
886
+ for (const entry of stale)
887
+ {
888
+ Object.assign(
889
+ attempts,
890
+ recordNativeAttempts({laws: [entry], command: null}, [], {
891
+ keys,
892
+ seed,
893
+ ok: false,
894
+ profile,
895
+ allEntries: planned.tests,
896
+ }),
897
+ );
500
898
  }
501
- const pendingLaws=Object.fromEntries(Object.entries(previous.laws??{})
502
- .filter(([id])=>!stale.some(entry=>entry.law===id)));
503
- await mkdir(path.dirname(resultsFile),{recursive:true});
504
- await writeFile(path.join(path.dirname(resultsFile),".gitignore"),"*\n");
505
- await atomicWrite(resultsFile,JSON.stringify({...previous,version:1,laws:pendingLaws,attempts},null,2)+"\n");
899
+ const pendingLaws = Object.fromEntries(
900
+ Object.entries(previous.laws ?? {}).filter(
901
+ ([id]) => !stale.some(entry => entry.law === id),
902
+ ),
903
+ );
904
+ await mkdir(path.dirname(resultsFile), {recursive: true});
905
+ await writeFile(path.join(path.dirname(resultsFile), '.gitignore'), '*\n');
906
+ await atomicWrite(
907
+ resultsFile,
908
+ JSON.stringify(
909
+ {...previous, version: 1, laws: pendingLaws, attempts},
910
+ null,
911
+ 2,
912
+ ) + '\n',
913
+ );
506
914
  const passed = [];
507
915
  const unrun = [];
508
916
  let failed = false;
509
- const scratch = path.join(configRoot, ".lawspec", "reports", target.language, identity);
510
- const stats = path.join(scratch, "statistics");
511
- const beam = ["erlang", "elixir", "gleam"].includes(target.language);
512
- const coverage = options.coverage ? path.join(configRoot, ".lawspec", "coverage", target.language, identity) : null;
917
+ const scratch = path.join(
918
+ configRoot,
919
+ '.lawspec',
920
+ 'reports',
921
+ target.language,
922
+ identity,
923
+ );
924
+ const stats = path.join(scratch, 'statistics');
925
+ const beam = ['erlang', 'elixir', 'gleam'].includes(target.language);
926
+ const coverage = options.coverage
927
+ ? path.join(configRoot, '.lawspec', 'coverage', target.language, identity)
928
+ : null;
513
929
  const coverageRuns = [];
514
- let coverageWritten = false, coverageError;
515
- await rm(scratch, { recursive: true, force: true });
516
- await mkdir(stats, { recursive: true });
517
- await mkdir(failures, { recursive: true });
518
- await writeFile(path.join(configRoot, ".lawspec", "reports", ".gitignore"), "*\n");
519
- const missingCoverage = coverage ? await coverageMissing(target, root, report_) : null;
930
+ let coverageWritten = false,
931
+ coverageError;
932
+ await rm(scratch, {recursive: true, force: true});
933
+ await mkdir(stats, {recursive: true});
934
+ await mkdir(failures, {recursive: true});
935
+ await writeFile(
936
+ path.join(configRoot, '.lawspec', 'reports', '.gitignore'),
937
+ '*\n',
938
+ );
939
+ const missingCoverage = coverage
940
+ ? await coverageMissing(target, root, report_)
941
+ : null;
520
942
  const useCoverage = coverage && !missingCoverage;
521
943
  if (missingCoverage)
522
- console.error(`${target.language}: --coverage needs ${missingCoverage.tool}, which is not available; ${missingCoverage.install}. Running without coverage.`);
523
- if (useCoverage) {
524
- if (beam || target.language === "scala") await rm(coverage, {recursive: true, force: true});
525
- await mkdir(beam ? path.join(coverage, "runs") : coverage, { recursive: true });
944
+ console.error(
945
+ `${target.language}: --coverage needs ${missingCoverage.tool}, which is not available; ${missingCoverage.install}. Running without coverage.`,
946
+ );
947
+ if (useCoverage)
948
+ {
949
+ if (beam || target.language === 'scala')
950
+ await rm(coverage, {recursive: true, force: true});
951
+ await mkdir(beam ? path.join(coverage, 'runs') : coverage, {
952
+ recursive: true,
953
+ });
526
954
  }
527
955
  // Python may use xdist processes; the host harness otherwise supplies
528
956
  // its existing thread scheduler, which Prolog also uses through Janus.
529
957
  let xdist = false;
530
- if (target.language === "python" && stale.some((entry) => entry.parallel)) {
531
- xdist = spawnSync(target.python || "python3", ["-c", "import xdist"], { cwd: root, stdio: "ignore" }).status === 0;
958
+ if (target.language === 'python' && stale.some(entry => entry.parallel))
959
+ {
960
+ xdist =
961
+ spawnSync(target.python || 'python3', ['-c', 'import xdist'], {
962
+ cwd: root,
963
+ stdio: 'ignore',
964
+ }).status === 0;
532
965
  }
533
966
  // A skipped law runs nothing. BEAM known-discrepancy checks finish as native
534
967
  // passing tests, so their completion must appear in the native report.
535
- const expected = (entry) => !entry.skip && (!entry.knownDiscrepancy || ["erlang", "elixir", "gleam"].includes(target.language));
968
+ const expected = entry =>
969
+ !entry.skip &&
970
+ (!entry.knownDiscrepancy ||
971
+ ['erlang', 'elixir', 'gleam'].includes(target.language));
536
972
  const benchmarking = options.benchmarks ? (planned.benchmarks ?? []) : [];
537
- if (batches.length || benchmarking.length) {
538
- for (const preparation of preparationInvocations(target, planned.files)) {
539
- const {ok} = await spawned(preparation.command, preparation.args, root, process.env);
540
- if (!ok) throw new Error(`${target.language}: native test preparation failed`);
973
+ if (batches.length || benchmarking.length)
974
+ {
975
+ for (const preparation of preparationInvocations(target, planned.files))
976
+ {
977
+ const {ok} = await spawned(
978
+ preparation.command,
979
+ preparation.args,
980
+ root,
981
+ process.env,
982
+ );
983
+ if (!ok)
984
+ throw new Error(`${target.language}: native test preparation failed`);
541
985
  }
542
986
  }
543
987
  const seedOf = new Map();
544
- batches: for (const batch of batches) {
545
- for (const run of invocations(target, batch.entries, { offline, scratch, coverage: useCoverage ? coverage : null,
546
- xdist, root, coverageConfig: report_.coverage })) {
988
+ batches: for (const batch of batches)
989
+ {
990
+ for (const run of invocations(target, batch.entries, {
991
+ offline,
992
+ scratch,
993
+ coverage: useCoverage ? coverage : null,
994
+ xdist,
995
+ root,
996
+ coverageConfig: report_.coverage,
997
+ }))
998
+ {
547
999
  const since = Date.now();
548
- const { ok, output } = await spawned(run.command, run.args, root,
549
- { ...process.env, ...run.env, LAWSPEC_SEED: batch.seed, HSPEC_SEED: batch.seed,
550
- LAWSPEC_STATS: stats, LAWSPEC_FAILURES: failures, LAWSPEC_RECORDED: recordedFolder,
551
- ...(options["update-recorded"] ? { LAWSPEC_UPDATE_RECORDED: "1" } : {}) }, run.report?.kind === "go-json");
552
- if(!ok&&target.language==='scala'&&isScalaCompilationFailure(output)) {
553
- const directory=await captureScalaBuildFailure({root,command:run.command,args:run.args,output});
554
- if(directory)console.error(`Scala compiler state: ${directory}`);
1000
+ const {ok, output} = await spawned(
1001
+ run.command,
1002
+ run.args,
1003
+ root,
1004
+ {
1005
+ ...process.env,
1006
+ ...run.env,
1007
+ LAWSPEC_SEED: batch.seed,
1008
+ HSPEC_SEED: batch.seed,
1009
+ LAWSPEC_STATS: stats,
1010
+ LAWSPEC_FAILURES: failures,
1011
+ LAWSPEC_RECORDED: recordedFolder,
1012
+ ...(options['update-recorded']
1013
+ ? {LAWSPEC_UPDATE_RECORDED: '1'}
1014
+ : {}),
1015
+ },
1016
+ run.report?.kind === 'go-json',
1017
+ );
1018
+ if (
1019
+ !ok &&
1020
+ target.language === 'scala' &&
1021
+ isScalaCompilationFailure(output)
1022
+ )
1023
+ {
1024
+ const directory = await captureScalaBuildFailure({
1025
+ root,
1026
+ command: run.command,
1027
+ args: run.args,
1028
+ output,
1029
+ });
1030
+ if (directory) console.error(`Scala compiler state: ${directory}`);
555
1031
  }
556
1032
  if (run.coverage) coverageRuns.push(run.coverage);
557
1033
  const executed = await executedTests(run.report, output, root, since);
558
- const observed=recordNativeAttempts(run,executed,{keys,seed:batch.seed,ok,profile,output,allEntries:planned.tests});
559
- if(!ok&&!run.laws.length)Object.assign(attempts,recordNativeAttempts({laws:batch.entries,command:run.command},[],
560
- {keys,seed:batch.seed,ok:false,profile,output,allEntries:planned.tests}));
561
- Object.assign(attempts,observed);
1034
+ const observed = recordNativeAttempts(run, executed, {
1035
+ keys,
1036
+ seed: batch.seed,
1037
+ ok,
1038
+ profile,
1039
+ output,
1040
+ allEntries: planned.tests,
1041
+ });
1042
+ if (!ok && !run.laws.length)
1043
+ Object.assign(
1044
+ attempts,
1045
+ recordNativeAttempts(
1046
+ {laws: batch.entries, command: run.command},
1047
+ [],
1048
+ {
1049
+ keys,
1050
+ seed: batch.seed,
1051
+ ok: false,
1052
+ profile,
1053
+ output,
1054
+ allEntries: planned.tests,
1055
+ },
1056
+ ),
1057
+ );
1058
+ Object.assign(attempts, observed);
562
1059
  for (const law of run.laws) seedOf.set(law.law, batch.seed);
563
1060
  // A completed combined model method remains scoped to its own checks,
564
1061
  // even if another selected method in this invocation failed.
565
- passed.push(...run.laws.filter(entry=>['passed','known-discrepancy'].includes(observed[entry.law]?.outcome)||!expected(entry)));
566
- if (report) junit.push({ target: `${target.language} (${target.root})`, xml: await junitOf(run, executed, root, since) });
567
- if (!ok || executed.some((test) => test.status === "failed")) { failed = true; break batches; }
1062
+ passed.push(
1063
+ ...run.laws.filter(
1064
+ entry =>
1065
+ ['passed', 'known-discrepancy'].includes(
1066
+ observed[entry.law]?.outcome,
1067
+ ) || !expected(entry),
1068
+ ),
1069
+ );
1070
+ if (report)
1071
+ junit.push({
1072
+ target: `${target.language} (${target.root})`,
1073
+ xml: await junitOf(run, executed, root, since),
1074
+ });
1075
+ if (!ok || executed.some(test => test.status === 'failed'))
1076
+ {
1077
+ failed = true;
1078
+ break batches;
1079
+ }
568
1080
  // A runner whose filter matched nothing reports success, so a law
569
1081
  // counts as passed only if the runner's report shows its tests ran.
570
- unrun.push(...run.laws.filter(entry=>!passed.includes(entry)&&expected(entry)));
1082
+ unrun.push(
1083
+ ...run.laws.filter(
1084
+ entry => !passed.includes(entry) && expected(entry),
1085
+ ),
1086
+ );
571
1087
  }
572
1088
  }
573
1089
  if (unrun.length) failed = true;
574
- if (useCoverage && target.language === "scala" && !failed) {
575
- try {
576
- coverageWritten = await collectScalaCoverage({root, directory: coverage, command: target.scala || "scala", offline});
577
- } catch (error) {
1090
+ if (useCoverage && target.language === 'scala' && !failed)
1091
+ {
1092
+ try
1093
+ {
1094
+ coverageWritten = await collectScalaCoverage({
1095
+ root,
1096
+ directory: coverage,
1097
+ command: target.scala || 'scala',
1098
+ offline,
1099
+ });
1100
+ }
1101
+ catch (error)
1102
+ {
578
1103
  failed = true;
579
1104
  coverageError = error.message;
580
1105
  }
581
1106
  }
582
- if (useCoverage && beam) {
583
- try {
584
- coverageWritten = !!(await collectBeamCoverage({root, directory: coverage, runs: coverageRuns}));
585
- } catch (error) {
1107
+ if (useCoverage && beam)
1108
+ {
1109
+ try
1110
+ {
1111
+ coverageWritten = !!(await collectBeamCoverage({
1112
+ root,
1113
+ directory: coverage,
1114
+ runs: coverageRuns,
1115
+ }));
1116
+ }
1117
+ catch (error)
1118
+ {
586
1119
  failed = true;
587
1120
  coverageError = error.message;
588
1121
  }
589
1122
  }
590
1123
  // --benchmarks: the harness's benchmarks run after the laws, every time;
591
1124
  // they are measured, never asserted, and never cached.
592
- if (!failed) for (const run of benchmarkInvocations(target, benchmarking, { offline })) {
593
- const { ok } = await spawned(run.command, run.args, root,
594
- { ...process.env, ...run.env, LAWSPEC_SEED: seed, HSPEC_SEED: seed, LAWSPEC_STATS: stats, LAWSPEC_RECORDED: recordedFolder }, false);
595
- if (!ok) { failed = true; break; }
596
- }
1125
+ if (!failed)
1126
+ for (const run of benchmarkInvocations(target, benchmarking, {offline}))
1127
+ {
1128
+ const {ok} = await spawned(
1129
+ run.command,
1130
+ run.args,
1131
+ root,
1132
+ {
1133
+ ...process.env,
1134
+ ...run.env,
1135
+ LAWSPEC_SEED: seed,
1136
+ HSPEC_SEED: seed,
1137
+ LAWSPEC_STATS: stats,
1138
+ LAWSPEC_RECORDED: recordedFolder,
1139
+ },
1140
+ false,
1141
+ );
1142
+ if (!ok)
1143
+ {
1144
+ failed = true;
1145
+ break;
1146
+ }
1147
+ }
597
1148
  const statistics = await harnessStatistics(stats);
598
1149
  // A renamed law keeps its result: it is found by its key.
599
- const kept = (entry) => previous.laws[entry.law] ?? previousResult(previous.laws, entry.law, keys.get(entry.law));
600
- const laws = Object.fromEntries(planned.tests.filter(kept).map((entry) => [entry.law, kept(entry)]));
601
- for (const entry of passed) {
1150
+ const kept = entry =>
1151
+ previous.laws[entry.law] ??
1152
+ previousResult(previous.laws, entry.law, keys.get(entry.law));
1153
+ const laws = Object.fromEntries(
1154
+ planned.tests.filter(kept).map(entry => [entry.law, kept(entry)]),
1155
+ );
1156
+ for (const entry of passed)
1157
+ {
602
1158
  const label = entry.label;
603
- const observed = statistics.filter((s) => s.law === label);
604
- laws[entry.law] = { key: keys.get(entry.law), seed: nativeSeed(seedOf.get(entry.law) ?? seed), passed: new Date().toISOString(),
1159
+ const observed = statistics.filter(s => s.law === label);
1160
+ laws[entry.law] = {
1161
+ key: keys.get(entry.law),
1162
+ seed: nativeSeed(seedOf.get(entry.law) ?? seed),
1163
+ passed: new Date().toISOString(),
605
1164
  // A law the attestation touches names the run it passed in.
606
- ...(attestation && attested.has(entry.law) ? { environment: attestation.run.id } : {}),
607
- ...(observed.some((s) => s.outcome === "flaky") ? { flaky: true } : {}),
608
- ...(observed.some((s) => s.cover || s.labels || s.classes) ? { adequacy: observed.filter((s) => s.cover || s.labels || s.classes)
609
- .map(({ test, cases, cover, classes, labels }) => ({ test, cases, cover, classes, labels })) } : {}) };
1165
+ ...(attestation && attested.has(entry.law)
1166
+ ? {environment: attestation.run.id}
1167
+ : {}),
1168
+ ...(observed.some(s => s.outcome === 'flaky') ? {flaky: true} : {}),
1169
+ ...(observed.some(s => s.cover || s.labels || s.classes)
1170
+ ? {
1171
+ adequacy: observed
1172
+ .filter(s => s.cover || s.labels || s.classes)
1173
+ .map(({test, cases, cover, classes, labels}) => ({
1174
+ test,
1175
+ cases,
1176
+ cover,
1177
+ classes,
1178
+ labels,
1179
+ })),
1180
+ }
1181
+ : {}),
1182
+ };
610
1183
  }
611
1184
  // A law that failed is recorded with its seed; one that passed leaves.
612
- for (const entry of stale) {
1185
+ for (const entry of stale)
1186
+ {
613
1187
  if (passed.includes(entry)) delete database[entry.law];
614
- else {
1188
+ else
1189
+ {
615
1190
  delete laws[entry.law];
616
- if(!seedOf.has(entry.law))continue;
617
- database[entry.law] = { seed: nativeSeed(seedOf.get(entry.law)), failed: new Date().toISOString() };
1191
+ if (!seedOf.has(entry.law)) continue;
1192
+ database[entry.law] = {
1193
+ seed: nativeSeed(seedOf.get(entry.law)),
1194
+ failed: new Date().toISOString(),
1195
+ };
618
1196
  }
619
1197
  }
620
- await writeFile(path.join(configRoot, ".lawspec", "failures", ".gitignore"), "*\n");
621
- await writeFile(databaseFile, JSON.stringify(database, null, 2) + "\n");
622
- await mkdir(path.dirname(resultsFile), { recursive: true });
623
- await writeFile(path.join(path.dirname(resultsFile), ".gitignore"), "*\n");
1198
+ await writeFile(
1199
+ path.join(configRoot, '.lawspec', 'failures', '.gitignore'),
1200
+ '*\n',
1201
+ );
1202
+ await writeFile(databaseFile, JSON.stringify(database, null, 2) + '\n');
1203
+ await mkdir(path.dirname(resultsFile), {recursive: true});
1204
+ await writeFile(path.join(path.dirname(resultsFile), '.gitignore'), '*\n');
624
1205
  // Each attempt at a law the attestation touches names the run it was
625
1206
  // made in, whatever its outcome.
626
- if (attestation) for (const entry of stale) {
627
- if (!seedOf.has(entry.law) || !attempts[entry.law]) continue;
628
- attempts[entry.law] = {...attempts[entry.law], executionRun: attestation.run.id,
629
- ...(attested.has(entry.law) ? {environment: attestation.run.id} : {})};
630
- }
1207
+ if (attestation)
1208
+ for (const entry of stale)
1209
+ {
1210
+ if (!seedOf.has(entry.law) || !attempts[entry.law]) continue;
1211
+ attempts[entry.law] = {
1212
+ ...attempts[entry.law],
1213
+ executionRun: attestation.run.id,
1214
+ ...(attested.has(entry.law) ? {environment: attestation.run.id} : {}),
1215
+ };
1216
+ }
631
1217
  // Each attestation a recorded law ran under is kept with the results.
632
- const attestations = Object.fromEntries(Object.entries({ ...(previous.attestations ?? {}),
633
- ...(attestation ? { [attestation.run.id]: attestation } : {}) })
634
- .filter(([id]) => [...Object.values(laws), ...Object.values(attempts)].some((run) => run.environment === id || run.executionRun === id)));
635
- await atomicWrite(resultsFile, JSON.stringify({ version: 1, laws, attempts,presentation,
636
- ...(Object.keys(attestations).length ? { attestations } : {}) }, null, 2) + "\n");
637
- const flaky = statistics.filter((s) => s.outcome === "flaky").map((s) => s.law);
638
- const unmet = statistics.flatMap((s) => (s.cover ?? []).filter((c) => !c.met).map((c) => `${s.law}: cover ${c.required}% "${c.label}" (${c.observed}%)`));
639
- const benchmarks = statistics.filter((s) => s.benchmark);
1218
+ const attestations = Object.fromEntries(
1219
+ Object.entries({
1220
+ ...(previous.attestations ?? {}),
1221
+ ...(attestation ? {[attestation.run.id]: attestation} : {}),
1222
+ }).filter(([id]) =>
1223
+ [...Object.values(laws), ...Object.values(attempts)].some(
1224
+ run => run.environment === id || run.executionRun === id,
1225
+ ),
1226
+ ),
1227
+ );
1228
+ await atomicWrite(
1229
+ resultsFile,
1230
+ JSON.stringify(
1231
+ {
1232
+ version: 1,
1233
+ laws,
1234
+ attempts,
1235
+ presentation,
1236
+ ...(Object.keys(attestations).length ? {attestations} : {}),
1237
+ },
1238
+ null,
1239
+ 2,
1240
+ ) + '\n',
1241
+ );
1242
+ const flaky = statistics.filter(s => s.outcome === 'flaky').map(s => s.law);
1243
+ const unmet = statistics.flatMap(s =>
1244
+ (s.cover ?? [])
1245
+ .filter(c => !c.met)
1246
+ .map(
1247
+ c => `${s.law}: cover ${c.required}% "${c.label}" (${c.observed}%)`,
1248
+ ),
1249
+ );
1250
+ const benchmarks = statistics.filter(s => s.benchmark);
640
1251
  // How each parallel unit's tests actually ran at the same time.
641
- const parallelism = statistics.filter((s) => s.parallel).map(({ parallel, mode, workers }) => ({ unit: parallel, mode, workers }));
642
- summaries.push({ target: target.language, root: target.root, seed: nativeSeed(seed), ran: stale.map((e) => e.law),
643
- ...(attestation ? { environment: attestation.environment } : {}),
644
- unchanged: chosen.length - stale.length, ok: !failed,
645
- ...(chosen.length !== planned.tests.length ? { deselected: planned.tests.length - chosen.length } : {}),
646
- ...(unrun.length ? { unrun: unrun.map((e) => e.law) } : {}),
647
- ...(flaky.length ? { flaky: [...new Set(flaky)] } : {}),
648
- ...(unmet.length ? { unmetCover: unmet } : {}),
649
- ...(benchmarks.length ? { benchmarks } : {}),
650
- ...(parallelism.length ? { parallelism } : {}),
1252
+ const parallelism = statistics
1253
+ .filter(s => s.parallel)
1254
+ .map(({parallel, mode, workers}) => ({unit: parallel, mode, workers}));
1255
+ summaries.push({
1256
+ target: target.language,
1257
+ root: target.root,
1258
+ seed: nativeSeed(seed),
1259
+ ran: stale.map(e => e.law),
1260
+ ...(attestation ? {environment: attestation.environment} : {}),
1261
+ unchanged: chosen.length - stale.length,
1262
+ ok: !failed,
1263
+ ...(chosen.length !== planned.tests.length
1264
+ ? {deselected: planned.tests.length - chosen.length}
1265
+ : {}),
1266
+ ...(unrun.length ? {unrun: unrun.map(e => e.law)} : {}),
1267
+ ...(flaky.length ? {flaky: [...new Set(flaky)]} : {}),
1268
+ ...(unmet.length ? {unmetCover: unmet} : {}),
1269
+ ...(benchmarks.length ? {benchmarks} : {}),
1270
+ ...(parallelism.length ? {parallelism} : {}),
651
1271
  ...(coverageError ? {coverageError} : {}),
652
- ...(useCoverage && ((!beam && target.language !== "scala") || coverageWritten) ? { coverage: path.relative(process.cwd(), coverage) || "." } : {}) });
1272
+ ...(useCoverage &&
1273
+ ((!beam && target.language !== 'scala') || coverageWritten)
1274
+ ? {coverage: path.relative(process.cwd(), coverage) || '.'}
1275
+ : {}),
1276
+ });
653
1277
  }
654
- if (report) {
655
- await mkdir(path.dirname(path.resolve(report.path)), { recursive: true });
1278
+ if (report)
1279
+ {
1280
+ await mkdir(path.dirname(path.resolve(report.path)), {recursive: true});
656
1281
  await writeFile(path.resolve(report.path), mergeJunit(junit));
657
1282
  }
658
- output(options.json ? summaries : summaries.map((s) =>
659
- `${s.target}${summaries.filter(other => other.target === s.target).length > 1 ? ` (${s.root})` : ""}: ${s.ran.length ? `ran ${s.ran.length} law(s) with seed ${s.seed}${s.environment ? ` in environment ${s.environment}` : ""}` : "nothing to run"}` +
660
- (s.selection==='no-selected-native-checks'?'; no native checks selected; intrinsic definition checks passed.':
661
- `, ${s.unchanged} unchanged since their last passing run.${s.ok ? "" : " FAILED"}`) +
662
- (s.deselected ? `\n${s.deselected} law(s) not selected by --tag or --exclude-tag.` : "") +
663
- (s.unrun ? `\nNo tests ran for ${s.unrun.join(", ")}; the runner matched none of their tests.` : "") +
664
- (s.flaky ? `\nFlaky (failed, then passed on a retry): ${s.flaky.join(", ")}` : "") +
665
- (s.unmetCover ? `\nCover not met: ${s.unmetCover.join("; ")}` : "") +
666
- (s.parallelism ? "\n" + s.parallelism.map((p) => `parallel ${p.unit}: ${p.mode}, ${p.workers} worker(s)`).join("\n") : "") +
667
- (s.benchmarks ? "\n" + s.benchmarks.map((b) => `benchmark ${b.benchmark}: mean ${(b.mean_ns / 1000).toFixed(2)} us over ${b.iterations} iteration(s)`).join("\n") : "") +
668
- (s.coverageError ? `\nCoverage failed: ${s.coverageError}` : "") +
669
- (s.coverage ? `\nCoverage written to ${s.coverage}.` : "")).join("\n"));
670
- if (summaries.some((s) => !s.ok)) process.exitCode = 1;
1283
+ output(
1284
+ options.json
1285
+ ? summaries
1286
+ : summaries
1287
+ .map(
1288
+ s =>
1289
+ `${s.target}${summaries.filter(other => other.target === s.target).length > 1 ? ` (${s.root})` : ''}: ${s.ran.length ? `ran ${s.ran.length} law(s) with seed ${s.seed}${s.environment ? ` in environment ${s.environment}` : ''}` : 'nothing to run'}` +
1290
+ (s.selection === 'no-selected-native-checks'
1291
+ ? '; no native checks selected; intrinsic definition checks passed.'
1292
+ : `, ${s.unchanged} unchanged since their last passing run.${s.ok ? '' : ' FAILED'}`) +
1293
+ (s.deselected
1294
+ ? `\n${s.deselected} law(s) not selected by --tag or --exclude-tag.`
1295
+ : '') +
1296
+ (s.unrun
1297
+ ? `\nNo tests ran for ${s.unrun.join(', ')}; the runner matched none of their tests.`
1298
+ : '') +
1299
+ (s.flaky
1300
+ ? `\nFlaky (failed, then passed on a retry): ${s.flaky.join(', ')}`
1301
+ : '') +
1302
+ (s.unmetCover
1303
+ ? `\nCover not met: ${s.unmetCover.join('; ')}`
1304
+ : '') +
1305
+ (s.parallelism
1306
+ ? '\n' +
1307
+ s.parallelism
1308
+ .map(
1309
+ p =>
1310
+ `parallel ${p.unit}: ${p.mode}, ${p.workers} worker(s)`,
1311
+ )
1312
+ .join('\n')
1313
+ : '') +
1314
+ (s.benchmarks
1315
+ ? '\n' +
1316
+ s.benchmarks
1317
+ .map(
1318
+ b =>
1319
+ `benchmark ${b.benchmark}: mean ${(b.mean_ns / 1000).toFixed(2)} us over ${b.iterations} iteration(s)`,
1320
+ )
1321
+ .join('\n')
1322
+ : '') +
1323
+ (s.coverageError ? `\nCoverage failed: ${s.coverageError}` : '') +
1324
+ (s.coverage ? `\nCoverage written to ${s.coverage}.` : ''),
1325
+ )
1326
+ .join('\n'),
1327
+ );
1328
+ if (summaries.some(s => !s.ok)) process.exitCode = 1;
671
1329
  }
672
1330
  // --report junit=path: one JUnit report merged across targets.
673
- function parseReport(value) {
1331
+ function parseReport(value)
1332
+ {
674
1333
  const match = value.match(/^junit=(.+)$/);
675
- if (!match) throw new Error("--report takes junit=<path>");
676
- return { kind: "junit", path: match[1] };
1334
+ if (!match) throw new Error('--report takes junit=<path>');
1335
+ return {kind: 'junit', path: match[1]};
677
1336
  }
678
1337
  // A run's JUnit XML: the runner's own where it writes one, otherwise made
679
1338
  // from what it printed.
680
- async function junitOf(run, executed, root, since) {
681
- if (run.report?.kind === "junit") {
682
- const files = run.report.files ?? (await readdir(path.join(root, run.report.directory)).catch(() => []))
683
- .filter((n) => n.endsWith(".xml")).map((n) => path.join(root, run.report.directory, n));
1339
+ async function junitOf(run, executed, root, since)
1340
+ {
1341
+ if (run.report?.kind === 'junit')
1342
+ {
1343
+ const files =
1344
+ run.report.files ??
1345
+ (await readdir(path.join(root, run.report.directory)).catch(() => []))
1346
+ .filter(n => n.endsWith('.xml'))
1347
+ .map(n => path.join(root, run.report.directory, n));
684
1348
  const xml = [];
685
- for (const file of files) {
1349
+ for (const file of files)
1350
+ {
686
1351
  const info = await stat(path.resolve(root, file)).catch(() => null);
687
- if (info && info.mtimeMs >= since) xml.push(await readFile(path.resolve(root, file), "utf8"));
1352
+ if (info && info.mtimeMs >= since)
1353
+ xml.push(await readFile(path.resolve(root, file), 'utf8'));
688
1354
  }
689
- return xml.join("\n");
1355
+ return xml.join('\n');
690
1356
  }
691
1357
  // BEAM reports only executed cases. Intentional harness skips remain
692
1358
  // reportable obligations; they are never evidence that a test passed.
693
- const skipped = run.report?.kind === "beam-events" ? run.laws.filter((entry) => entry.skip)
694
- .map((entry) => ({name: entry.label, classname: entry.unit, status: "skipped", reason: entry.skip})) : [];
1359
+ const skipped =
1360
+ run.report?.kind === 'beam-events'
1361
+ ? run.laws
1362
+ .filter(entry => entry.skip)
1363
+ .map(entry => ({
1364
+ name: entry.label,
1365
+ classname: entry.unit,
1366
+ status: 'skipped',
1367
+ reason: entry.skip,
1368
+ }))
1369
+ : [];
695
1370
  return junitFromTests([...executed, ...skipped]);
696
1371
  }
697
1372
  // The tool --coverage needs, if it is missing.
698
- async function coverageMissing(target, root, report) {
1373
+ async function coverageMissing(target, root, report)
1374
+ {
699
1375
  const tool = coverageTools[target.language];
700
- if (!tool) return { tool: "a coverage tool", install: "no coverage tool is known for this target" };
701
- const probe = (command, args) => new Promise((resolve) => {
702
- const child = spawn(command, args, { cwd: root, stdio: "ignore" });
703
- child.on("error", () => resolve(false));
704
- child.on("close", (code) => resolve(code === 0));
705
- });
706
- if (["erlang", "elixir", "gleam"].includes(target.language)) {
1376
+ if (!tool)
1377
+ return {
1378
+ tool: 'a coverage tool',
1379
+ install: 'no coverage tool is known for this target',
1380
+ };
1381
+ const probe = (command, args) =>
1382
+ new Promise(resolve =>
1383
+ {
1384
+ const child = spawn(command, args, {cwd: root, stdio: 'ignore'});
1385
+ child.on('error', () => resolve(false));
1386
+ child.on('close', code => resolve(code === 0));
1387
+ });
1388
+ if (['erlang', 'elixir', 'gleam'].includes(target.language))
1389
+ {
707
1390
  const requirement = beamCoverageRequirement(target, report);
708
1391
  if (requirement) return requirement;
709
- return (await probe("erl", ["-noshell", "-eval",
710
- 'case code:ensure_loaded(cover) of {module,cover} -> halt(0); _ -> halt(1) end.'])) ? null : tool;
1392
+ return (await probe('erl', [
1393
+ '-noshell',
1394
+ '-eval',
1395
+ 'case code:ensure_loaded(cover) of {module,cover} -> halt(0); _ -> halt(1) end.',
1396
+ ]))
1397
+ ? null
1398
+ : tool;
711
1399
  }
712
- if (target.language === "python") return (await probe(target.python || "python3", tool.check)) ? null : tool;
713
- if (["javascript", "typescript"].includes(target.language)) return (await probe("npx", ["--no-install", "c8", "--version"])) ? null : tool;
714
- if (target.language === "rust") return (await probe("cargo", ["llvm-cov", "--version"])) ? null : tool;
715
- if (target.language === "kotlin") {
716
- const build = await readFile(path.join(root, "build.gradle.kts"), "utf8").catch(() => "");
717
- return build.includes("kover") ? null : tool;
1400
+ if (target.language === 'python')
1401
+ return (await probe(target.python || 'python3', tool.check)) ? null : tool;
1402
+ if (['javascript', 'typescript'].includes(target.language))
1403
+ return (await probe('npx', ['--no-install', 'c8', '--version']))
1404
+ ? null
1405
+ : tool;
1406
+ if (target.language === 'rust')
1407
+ return (await probe('cargo', ['llvm-cov', '--version'])) ? null : tool;
1408
+ if (target.language === 'kotlin')
1409
+ {
1410
+ const build = await readFile(
1411
+ path.join(root, 'build.gradle.kts'),
1412
+ 'utf8',
1413
+ ).catch(() => '');
1414
+ return build.includes('kover') ? null : tool;
718
1415
  }
719
- if (target.language === "scala") return null;
1416
+ if (target.language === 'scala') return null;
720
1417
  return null;
721
1418
  }
722
1419
  // Run a native test command, showing its output (on stderr with --json) and
723
1420
  // keeping it. Go's JSON events are shown as the text they carry.
724
- function spawned(command, args, cwd, env, goJson = false) {
725
- return new Promise((resolve, reject) => {
726
- const child = spawn(command, args, { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
1421
+ function spawned(command, args, cwd, env, goJson = false)
1422
+ {
1423
+ return new Promise((resolve, reject) =>
1424
+ {
1425
+ const child = spawn(command, args, {
1426
+ cwd,
1427
+ env,
1428
+ stdio: ['ignore', 'pipe', 'pipe'],
1429
+ });
727
1430
  const shown = options.json ? process.stderr : process.stdout;
728
- let output = "";
729
- let pending = "";
730
- child.stdout.on("data", (chunk) => {
1431
+ let output = '';
1432
+ let pending = '';
1433
+ child.stdout.on('data', chunk =>
1434
+ {
731
1435
  const text = chunk.toString();
732
1436
  output += text;
733
1437
  if (!goJson) return shown.write(text);
734
1438
  pending += text;
735
- const lines = pending.split("\n");
1439
+ const lines = pending.split('\n');
736
1440
  pending = lines.pop();
737
- for (const line of lines) {
738
- try { const event = JSON.parse(line); if (event.Output) shown.write(event.Output); }
739
- catch { shown.write(line + "\n"); }
1441
+ for (const line of lines)
1442
+ {
1443
+ try
1444
+ {
1445
+ const event = JSON.parse(line);
1446
+ if (event.Output) shown.write(event.Output);
1447
+ }
1448
+ catch
1449
+ {
1450
+ shown.write(line + '\n');
1451
+ }
740
1452
  }
741
1453
  });
742
- child.stderr.on("data", (chunk) => { output += chunk.toString(); process.stderr.write(chunk); });
743
- child.on("error", reject);
744
- child.on("close", (code) => resolve({ ok: code === 0, output }));
1454
+ child.stderr.on('data', chunk =>
1455
+ {
1456
+ output += chunk.toString();
1457
+ process.stderr.write(chunk);
1458
+ });
1459
+ child.on('error', reject);
1460
+ child.on('close', code => resolve({ok: code === 0, output}));
745
1461
  });
746
1462
  }
747
- async function readOptionalDirectory(folder) {
748
- try {
1463
+ async function readOptionalDirectory(folder)
1464
+ {
1465
+ try
1466
+ {
749
1467
  return await readdir(folder);
750
- } catch (error) {
751
- if (error.code === "ENOENT") return null;
1468
+ }
1469
+ catch (error)
1470
+ {
1471
+ if (error.code === 'ENOENT') return null;
752
1472
  throw error;
753
1473
  }
754
1474
  }
755
- async function main() {
756
- if (options['machine-bits'] !== undefined) {
1475
+ async function main()
1476
+ {
1477
+ if (options['machine-bits'] !== undefined)
1478
+ {
757
1479
  options.machineBits = Number(options['machine-bits']);
758
- if (![32,64].includes(options.machineBits)) throw new Error('machineBits must be 32 or 64');
1480
+ if (![32, 64].includes(options.machineBits))
1481
+ throw new Error('machineBits must be 32 or 64');
759
1482
  }
760
- if (!verb || ["help", "--help", "-h"].includes(verb)) {
1483
+ if (!verb || ['help', '--help', '-h'].includes(verb))
1484
+ {
761
1485
  output(
762
- "LawSpec " + VERSION + "\nUsage: lawspec learn [--port <port>]\n lawspec init --target <language> [--project <directory>] [--minify]\n lawspec fmt [paths...] [--check] [--compile]\n lawspec lsp --stdio\n lawspec prove [--solver <z3-executable>] [--proof-timeout <ms>] [--json]\n lawspec check [--warn-matches] | doctor | explain [<unit>::<law>] [--view eng|math|dev] | generate\n lawspec evidence [<unit> | <unit>::<declaration>] [--attestation <file>]\n lawspec test [--target <language>] [--fresh] [--seed <n>] [--attestation <file>] [--update-recorded] [--tag <t>] [--exclude-tag <t>] [--report junit=<path>] [--coverage] [--benchmarks]\n lawspec describe --json\n lawspec fetch | update [<package>]\n lawspec package [--project <package directory>] [--output <archive.tgz>]\n lawspec examples [--example payments] [--target <language>] [--output <directory>]\nOptions: --config <path>, --target <language>, --machine-bits <32|64>, --json, --no-cache, --locked, --offline\nGeneration: --dry-run, --check, --minify\nTargets: " +
763
- targets.join(", "),
1486
+ 'LawSpec ' +
1487
+ VERSION +
1488
+ '\nUsage: lawspec prelude [query] [--json]\n lawspec inspect --target <target> [--json]\n lawspec advise [--target <target>] [--json] [--strict]\n lawspec project init|adopt|status|validate [--project <directory>]\n lawspec learn [--port <port>]\n lawspec init --target <language> [--project <directory>] [--minify]\n lawspec fmt [paths...] [--check] [--compile]\n lawspec lsp --stdio | lawspec mcp\n lawspec prove [--solver <z3-executable>] [--proof-timeout <ms>] [--json]\n lawspec check [--warn-matches] [--no-advice] | doctor | explain [<unit>::<law>] [--view eng|math|dev] | generate\n lawspec evidence [<unit> | <unit>::<declaration>] [--attestation <file>]\n lawspec test [--target <language>] [--fresh] [--seed <n>] [--attestation <file>] [--update-recorded] [--tag <t>] [--exclude-tag <t>] [--report junit=<path>] [--coverage] [--benchmarks]\n lawspec describe --json\n lawspec fetch | update [<package>]\n lawspec package [--project <package directory>] [--output <archive.tgz>]\n lawspec examples [--example payments] [--target <language>] [--output <directory>]\nOptions: --config <path>, --target <language>, --machine-bits <32|64>, --json, --no-cache, --locked, --offline\nGeneration: --dry-run, --check, --minify\nTargets: ' +
1489
+ targets.join(', '),
764
1490
  );
765
1491
  return;
766
1492
  }
767
- if (verb === "--version") {
1493
+ if (verb === '--version')
1494
+ {
768
1495
  output(VERSION);
769
1496
  return;
770
1497
  }
1498
+ if (verb === 'prelude')
1499
+ {
1500
+ if (
1501
+ positional.length > 1 ||
1502
+ Object.keys(options).some(key => key !== 'json')
1503
+ )
1504
+ throw new Error('Usage: lawspec prelude [query] [--json]');
1505
+ const result = diagnostics(
1506
+ await (await createCompiler()).prelude({query: positional[0] ?? ''}),
1507
+ );
1508
+ return output(
1509
+ options.json
1510
+ ? result
1511
+ : result.entries
1512
+ .map(
1513
+ entry =>
1514
+ `${entry.kind}: ${entry.name}${entry.definition ? ` — ${entry.definition}` : ''}`,
1515
+ )
1516
+ .join('\n'),
1517
+ );
1518
+ }
1519
+ if (options.strict && verb !== 'advise')
1520
+ throw new Error('--strict applies to advise');
1521
+ if (options['no-advice'] && !['check', 'generate'].includes(verb))
1522
+ throw new Error('--no-advice applies to check and generate');
771
1523
  if (verb === 'learn')
772
1524
  {
773
1525
  if (positional.length || Object.keys(options).some(key => key !== 'port'))
1526
+ throw new Error('Usage: lawspec learn [--port <port>]');
1527
+ const {serveLearn} = await import('../learn.mjs');
1528
+ return serveLearn(options.port);
1529
+ }
1530
+ if (options.port !== undefined) throw new Error('--port applies to learn');
1531
+ if (verb === 'project')
1532
+ {
1533
+ if (
1534
+ positional.length !== 1 ||
1535
+ Object.keys(options).some(
1536
+ key => !['project', 'config', 'json', 'languages'].includes(key),
1537
+ )
1538
+ )
1539
+ throw new Error(
1540
+ 'Usage: lawspec project init|adopt|status|validate [--project <directory>] [--json]; add targets with lawspec init --target',
1541
+ );
1542
+ const {setupProject, inspectProject, projectExitCode} =
1543
+ await import('../project.mjs');
1544
+ const action = positional[0];
1545
+ if (!['init', 'adopt', 'status', 'validate'].includes(action))
1546
+ throw new Error(
1547
+ 'Usage: lawspec project init|adopt|status|validate [--project <directory>]',
1548
+ );
1549
+ if (options.config && options.project)
1550
+ throw new Error('Choose --config or --project');
1551
+ const root = options.config
1552
+ ? configRoot
1553
+ : path.resolve(options.project || '.');
1554
+ if (action === 'init' || action === 'adopt')
774
1555
  {
775
- throw new Error('learn supports --port only');
1556
+ const result = await setupProject(root, {
1557
+ adopt: action === 'adopt',
1558
+ ...(options.languages ? {languages: options.languages.split(',')} : {}),
1559
+ });
1560
+ return output(
1561
+ options.json
1562
+ ? result
1563
+ : `LawSpec ${result.manifest}; Canon ${result.canon} in ${root}. Add an application with lawspec init --target <language>.`,
1564
+ );
776
1565
  }
777
- const {serveLearn} = await import('../learn.mjs');
778
- return serveLearn(options.port ?? '8384');
1566
+ if (options.languages)
1567
+ throw new Error('--languages applies to project init/adopt');
1568
+ const report = await inspectProject(root, {
1569
+ validate: action === 'validate',
1570
+ configFile: options.config ? configFile : path.join(root, 'lawspec.edn'),
1571
+ });
1572
+ output(
1573
+ options.json
1574
+ ? report
1575
+ : Object.entries(report)
1576
+ .filter(([key]) => key !== 'root')
1577
+ .map(([key, value]) => `${key}: ${JSON.stringify(value)}`)
1578
+ .join('\n'),
1579
+ );
1580
+ process.exitCode = projectExitCode(report);
1581
+ return;
779
1582
  }
780
- if (options.port) throw new Error('--port applies to learn');
781
- if (options.compile && verb !== "fmt") throw new Error("--compile applies to fmt");
782
- if (verb !== "fmt" && positional.length > (["explain", "evidence", "update"].includes(verb) ? 1 : 0))
783
- throw new Error(`Unexpected argument: ${positional.join(" ")}`);
784
- if (verb === "examples") {
1583
+ if (options.languages)
1584
+ throw new Error('--languages applies to project init/adopt');
1585
+ if (options.compile && verb !== 'fmt')
1586
+ throw new Error('--compile applies to fmt');
1587
+ if (
1588
+ verb !== 'fmt' &&
1589
+ positional.length >
1590
+ (['project', 'explain', 'evidence', 'update'].includes(verb) ? 1 : 0)
1591
+ )
1592
+ throw new Error(`Unexpected argument: ${positional.join(' ')}`);
1593
+ if (verb === 'examples')
1594
+ {
785
1595
  if (
786
1596
  options.config ||
787
1597
  options.project ||
788
- options["dry-run"] ||
1598
+ options['dry-run'] ||
789
1599
  options.check
790
1600
  )
791
- throw new Error("examples supports --example, --target, --output, --machine-bits, --json and --minify only");
1601
+ throw new Error(
1602
+ 'examples supports --example, --target, --output, --machine-bits, --json and --minify only',
1603
+ );
792
1604
  const result = await generateExamples(options);
793
- if (options.example) {
794
- output(options.json ? result : result.map(r =>
795
- `${r.target}: payment project in ${r.directory}; ${r.preservedAdapters.length} user files preserved.` +
796
- (r.adapterUpdates.length ? `\nReview changed example files: ${r.adapterUpdates.map(a => a.path).join(", ")}` : "")
797
- ).join("\n") + "\nOpen each project's README.md, run lawspec generate, then its native test command.");
1605
+ if (options.example)
1606
+ {
1607
+ output(
1608
+ options.json
1609
+ ? result
1610
+ : result
1611
+ .map(
1612
+ r =>
1613
+ `${r.target}: payment project in ${r.directory}; ${r.preservedAdapters.length} user files preserved.` +
1614
+ (r.adapterUpdates.length
1615
+ ? `\nReview changed example files: ${r.adapterUpdates.map(a => a.path).join(', ')}`
1616
+ : ''),
1617
+ )
1618
+ .join('\n') +
1619
+ "\nOpen each project's README.md, run lawspec generate, then its native test command.",
1620
+ );
798
1621
  return;
799
1622
  }
800
1623
  output(
@@ -802,64 +1625,149 @@ async function main() {
802
1625
  ? result
803
1626
  : result
804
1627
  .map(
805
- (r) =>
806
- `${r.target}: ${r.files.length} artifacts in ${r.directory}; ${r.preservedAdapters.length} user adapters preserved.${r.adapterUpdates.length ? "\nReview required adapter signatures:\n" + r.adapterUpdates.map((a) => a.path + "\n" + a.requiredAdapter).join("\n") : ""}`,
1628
+ r =>
1629
+ `${r.target}: ${r.files.length} artifacts in ${r.directory}; ${r.preservedAdapters.length} user adapters preserved.${r.adapterUpdates.length ? '\nReview required adapter signatures:\n' + r.adapterUpdates.map(a => a.path + '\n' + a.requiredAdapter).join('\n') : ''}`,
807
1630
  )
808
- .join("\n") +
809
- "\nInspection artifacts only; native toolchains and dependencies are not checked. Stubs must be implemented before running tests.",
1631
+ .join('\n') +
1632
+ '\nInspection artifacts only; native toolchains and dependencies are not checked. Stubs must be implemented before running tests.',
810
1633
  );
811
1634
  return;
812
1635
  }
813
- if (["solver","proof-timeout","proof-memory","proof-rlimit","proof-seed"].some(key => options[key] !== undefined) && verb !== "prove")
814
- throw new Error("Z3 options apply to prove");
815
- if (options.view && verb !== "explain") throw new Error("--view applies to explain");
816
- if (options.output && verb !== "package") throw new Error("--output is only supported by examples and package");
817
- if (options.example) throw new Error("--example is only supported by examples");
818
- if (options.minify && !["init", "generate", "examples", "test"].includes(verb))
819
- throw new Error("--minify applies to init, generate, test and examples");
820
- if ((options.fresh || options.seed !== undefined || options.tag || options["exclude-tag"] ||
821
- options.report !== undefined || options.coverage || options["update-recorded"] || options.benchmarks) && verb !== "test")
822
- throw new Error("--fresh, --seed, --update-recorded, --tag, --exclude-tag, --report, --coverage and --benchmarks apply to test");
823
- if (options.attestation !== undefined && !["evidence", "test"].includes(verb))
824
- throw new Error("--attestation applies to evidence and test");
1636
+ if (
1637
+ [
1638
+ 'solver',
1639
+ 'proof-timeout',
1640
+ 'proof-memory',
1641
+ 'proof-rlimit',
1642
+ 'proof-seed',
1643
+ ].some(key => options[key] !== undefined) &&
1644
+ verb !== 'prove'
1645
+ )
1646
+ throw new Error('Z3 options apply to prove');
1647
+ if (options.view && verb !== 'explain')
1648
+ throw new Error('--view applies to explain');
1649
+ if (options.output && verb !== 'package')
1650
+ throw new Error('--output is only supported by examples and package');
1651
+ if (options.example)
1652
+ throw new Error('--example is only supported by examples');
1653
+ if (
1654
+ options.minify &&
1655
+ !['init', 'generate', 'examples', 'test'].includes(verb)
1656
+ )
1657
+ throw new Error('--minify applies to init, generate, test and examples');
1658
+ if (
1659
+ (options.fresh ||
1660
+ options.seed !== undefined ||
1661
+ options.tag ||
1662
+ options['exclude-tag'] ||
1663
+ options.report !== undefined ||
1664
+ options.coverage ||
1665
+ options['update-recorded'] ||
1666
+ options.benchmarks) &&
1667
+ verb !== 'test'
1668
+ )
1669
+ throw new Error(
1670
+ '--fresh, --seed, --update-recorded, --tag, --exclude-tag, --report, --coverage and --benchmarks apply to test',
1671
+ );
1672
+ if (options.attestation !== undefined && !['evidence', 'test'].includes(verb))
1673
+ throw new Error('--attestation applies to evidence and test');
825
1674
  if (options.seed !== undefined && !/^[0-9]+$/.test(options.seed))
826
- throw new Error("--seed must be a whole number");
827
- if (options["warn-matches"] && verb !== "check") throw new Error("--warn-matches applies to check");
828
- if (options.stdio && verb !== "lsp") throw new Error("--stdio applies to lsp");
829
- if (verb === "lsp") {
830
- if (!options.stdio) throw new Error("lsp requires --stdio");
1675
+ throw new Error('--seed must be a whole number');
1676
+ if (options['warn-matches'] && verb !== 'check')
1677
+ throw new Error('--warn-matches applies to check');
1678
+ if (options.stdio && verb !== 'lsp')
1679
+ throw new Error('--stdio applies to lsp');
1680
+ if (verb === 'lsp')
1681
+ {
1682
+ if (!options.stdio) throw new Error('lsp requires --stdio');
831
1683
  return serveLanguage();
832
1684
  }
833
- if (!options.config && verb !== "init" && verb !== "package" && !(verb === "fmt" && positional.length)) {
1685
+ if (
1686
+ !options.config &&
1687
+ verb !== 'init' &&
1688
+ verb !== 'package' &&
1689
+ verb !== 'mcp' &&
1690
+ !(verb === 'fmt' && positional.length)
1691
+ )
1692
+ {
834
1693
  configFile = await findManifest();
835
1694
  configRoot = path.dirname(configFile);
836
1695
  }
837
- if (verb === "describe") return output(await resolveComponent(configFile, options));
838
- if (verb === "fetch" || verb === "update") {
1696
+ if (verb === 'mcp')
1697
+ {
1698
+ if (options.target || options.project || options.output || options.stdio)
1699
+ throw new Error('mcp supports --config only');
1700
+ const {serveLawSpec} = await import('../mcp.mjs');
1701
+ return serveLawSpec(options.config ? configFile : undefined);
1702
+ }
1703
+ if (verb === 'describe')
1704
+ return output(await resolveComponent(configFile, options));
1705
+ if (verb === 'fetch' || verb === 'update')
1706
+ {
839
1707
  const manifest = await readManifest(configFile);
840
- const resolved = await resolveDependencies(configFile, manifest, {...options, update: verb === "update" ? positional[0] ?? true : false});
841
- return output(options.json ? resolved.lock : `Resolved ${resolved.packages.length} contract package(s).`);
1708
+ const resolved = await resolveDependencies(configFile, manifest, {
1709
+ ...options,
1710
+ update: verb === 'update' ? (positional[0] ?? true) : false,
1711
+ });
1712
+ return output(
1713
+ options.json
1714
+ ? resolved.lock
1715
+ : `Resolved ${resolved.packages.length} contract package(s).`,
1716
+ );
842
1717
  }
843
- if (verb === "fmt") return formatCommand();
844
- if (verb === "init") return init();
845
- if (verb === "package") return packageCommand();
846
- if (!["check", "doctor", "evidence", "explain", "generate", "test", "prove"].includes(verb))
1718
+ if (verb === 'fmt') return formatCommand();
1719
+ if (verb === 'init') return init();
1720
+ if (verb === 'package') return packageCommand();
1721
+ if (
1722
+ ![
1723
+ 'check',
1724
+ 'doctor',
1725
+ 'evidence',
1726
+ 'explain',
1727
+ 'generate',
1728
+ 'test',
1729
+ 'prove',
1730
+ 'inspect',
1731
+ 'advise',
1732
+ ].includes(verb)
1733
+ )
847
1734
  throw new Error(`Unknown command: ${verb}`);
848
1735
  const config = await readManifest(configFile);
849
1736
  config.targets ??= [];
850
- if (verb === "test" && artifactTargets.includes(options.target))
851
- throw new Error(`${options.target} is an artifact target and cannot execute application laws`);
1737
+ if (verb === 'inspect' && !options.target)
1738
+ throw new Error('inspect requires --target <target>');
1739
+ if (
1740
+ options.target &&
1741
+ !config.targets.some(t => t.language === options.target)
1742
+ )
1743
+ throw new Error('No matching configured target');
1744
+ if (verb === 'test' && artifactTargets.includes(options.target))
1745
+ throw new Error(
1746
+ `${options.target} is an artifact target and cannot execute application laws`,
1747
+ );
852
1748
  const selected = config.targets.filter(
853
- (t) => (!options.target || t.language === options.target) &&
854
- (verb !== "test" || !artifactTargets.includes(t.language)),
1749
+ t =>
1750
+ (!options.target || t.language === options.target) &&
1751
+ (verb !== 'test' || !artifactTargets.includes(t.language)),
855
1752
  );
856
- if (["doctor", "generate", "test"].includes(verb) && !selected.length &&
857
- !(verb === "test" && !options.benchmarks && config.manifestVersion === 1 && !(config.verification?.layers ?? []).some(layer => ["exhaustive", "property", "examples", "model"].includes(layer))))
858
- throw new Error("No matching configured target");
859
- const roots = selected.map((t) => path.resolve(configRoot, t.root));
1753
+ if (
1754
+ ['doctor', 'generate', 'test', 'inspect'].includes(verb) &&
1755
+ !selected.length &&
1756
+ !(
1757
+ verb === 'test' &&
1758
+ !options.benchmarks &&
1759
+ config.manifestVersion === 1 &&
1760
+ !(config.verification?.layers ?? []).some(layer =>
1761
+ ['exhaustive', 'property', 'examples', 'model'].includes(layer),
1762
+ )
1763
+ )
1764
+ )
1765
+ throw new Error('No matching configured target');
1766
+ const roots = selected.map(t => path.resolve(configRoot, t.root));
860
1767
  if (new Set(roots).size !== roots.length)
861
- throw new Error("Each configured target needs its own project root");
862
- if (verb === "doctor") {
1768
+ throw new Error('Each configured target needs its own project root');
1769
+ if (verb === 'doctor')
1770
+ {
863
1771
  const reports = await Promise.all(
864
1772
  selected.map((t, i) => doctor(t, roots[i])),
865
1773
  );
@@ -868,227 +1776,605 @@ async function main() {
868
1776
  ? reports
869
1777
  : reports
870
1778
  .map(
871
- (r) =>
872
- `${r.target}: ${r.ok ? (r.kind === "artifact" ? "generation ready" : "ready") : `${r.message}\n${r.instructions}`}`,
1779
+ r =>
1780
+ `${r.target}: ${r.ok ? (r.kind === 'artifact' ? 'generation ready' : 'ready') : `${r.message}\n${r.instructions}`}`,
873
1781
  )
874
- .join("\n"),
1782
+ .join('\n'),
875
1783
  );
876
- if (reports.some((r) => !r.ok)) process.exitCode = 1;
1784
+ if (reports.some(r => !r.ok)) process.exitCode = 1;
877
1785
  return;
878
1786
  }
879
- if (config.machineBits !== undefined && ![32, 64].includes(config.machineBits)) throw new Error("machineBits must be 32 or 64");
880
- if (config.cache !== undefined && typeof config.cache !== "boolean") throw new Error("cache must be true or false");
881
- if (config.attestation !== undefined && typeof config.attestation !== "string")
882
- throw new Error("attestation must be the path of an environment attestation");
883
- const cache = await cacheDirectory(config);
1787
+ if (
1788
+ config.machineBits !== undefined &&
1789
+ ![32, 64].includes(config.machineBits)
1790
+ )
1791
+ throw new Error('machineBits must be 32 or 64');
1792
+ if (config.cache !== undefined && typeof config.cache !== 'boolean')
1793
+ throw new Error('cache must be true or false');
1794
+ if (
1795
+ config.attestation !== undefined &&
1796
+ typeof config.attestation !== 'string'
1797
+ )
1798
+ throw new Error(
1799
+ 'attestation must be the path of an environment attestation',
1800
+ );
1801
+ const cache = ['inspect', 'advise'].includes(verb)
1802
+ ? undefined
1803
+ : await cacheDirectory(config);
884
1804
  const input = {
885
- ...(cache === undefined ? {} : { cacheDirectory: cache }),
1805
+ ...(cache === undefined ? {} : {cacheDirectory: cache}),
1806
+ advice: !options['no-advice'],
886
1807
  sources: await sources(config),
887
- languageProfile: config.languageProfile, verification: config.verification ?? { layers: [] },
1808
+ languageProfile: config.languageProfile,
1809
+ verification: config.verification ?? {layers: []},
888
1810
  ...(await packageInput(config, configRoot)),
889
1811
  generation: config.generation,
890
1812
  machineBits: options.machineBits ?? config.machineBits ?? 64,
891
1813
  // What a law-set exemption's until is compared with: the project's
892
1814
  // version and the current UTC time.
893
- ...((config.component?.version ?? config.package?.version) ? {projectVersion: config.component?.version ?? config.package?.version} : {}),
1815
+ ...((config.component?.version ?? config.package?.version)
1816
+ ? {projectVersion: config.component?.version ?? config.package?.version}
1817
+ : {}),
894
1818
  now: new Date().toISOString(),
895
1819
  };
896
1820
  const compiler = await createCompiler();
897
- if (verb === "prove") {
898
- const result = diagnostics(await proveWithZ3(compiler, input, {
899
- ...(options.solver !== undefined ? {binary: options.solver} : {}),
900
- ...Object.fromEntries([["proof-timeout","timeoutMs"],["proof-memory","memoryMb"],
901
- ["proof-rlimit","resourceLimit"],["proof-seed","seed"]]
902
- .filter(([name]) => options[name] !== undefined).map(([name,key]) => [key,Number(options[name])])),
903
- }));
904
- output(options.json ? result : result.solverEvidence.length
905
- ? result.solverEvidence.map(row => `${row.declaration}${row.kind === "analysis" ? ` ${row.stage}` : ""}: ${row.status} (${row.outcome}). ${row.reason}`).join("\n")
906
- : (input.verification?.layers.includes("proof")
907
- ? "No source law obligations are available. No solver was invoked."
908
- : "No proof layer selected. Intrinsic definition checks passed; no solver was invoked."));
1821
+ async function authoringReport()
1822
+ {
1823
+ const reports = [];
1824
+ for (const [i, target] of selected.entries())
1825
+ {
1826
+ let nativeSources;
1827
+ try
1828
+ {
1829
+ nativeSources = await collectNativeSources(roots[i]);
1830
+ }
1831
+ catch (error)
1832
+ {
1833
+ reports.push({
1834
+ findings: [],
1835
+ checks: [
1836
+ {
1837
+ rule: 'native-sources',
1838
+ status: 'incomplete',
1839
+ target: target.language,
1840
+ reason: error.message,
1841
+ },
1842
+ ],
1843
+ ok: false,
1844
+ });
1845
+ continue;
1846
+ }
1847
+ const advised = await compiler.advise({
1848
+ ...input,
1849
+ cacheDirectory: undefined,
1850
+ target: target.language,
1851
+ sourceDir: target.sourceDir,
1852
+ testDir: target.testDir,
1853
+ nativeBindings: target.nativeBindings,
1854
+ nativeSources,
1855
+ exceptions: config.authoringExceptions ?? [],
1856
+ });
1857
+ if (advised.diagnostics?.length)
1858
+ reports.push({
1859
+ findings: [],
1860
+ checks: [
1861
+ {
1862
+ rule: 'native-interface',
1863
+ target: target.language,
1864
+ status: 'incomplete',
1865
+ reason: advised.diagnostics.map(d => d.message).join('; '),
1866
+ },
1867
+ ],
1868
+ ok: false,
1869
+ });
1870
+ else reports.push(advised.advice);
1871
+ }
1872
+ if (!selected.length)
1873
+ reports.push(
1874
+ diagnostics(
1875
+ await compiler.advise({
1876
+ ...input,
1877
+ exceptions: config.authoringExceptions ?? [],
1878
+ }),
1879
+ ).advice,
1880
+ );
1881
+ const unique = rows => [
1882
+ ...new Map(rows.map(row => [JSON.stringify(row), row])).values(),
1883
+ ];
1884
+ return settleAdvice(
1885
+ {
1886
+ findings: unique(reports.flatMap(r => r.findings)),
1887
+ checks: unique(reports.flatMap(r => r.checks)),
1888
+ },
1889
+ config.authoringExceptions ?? [],
1890
+ );
1891
+ }
1892
+ function printAdvice(report)
1893
+ {
1894
+ for (const finding of report.findings.filter(
1895
+ f => f.status === 'unresolved',
1896
+ ))
1897
+ console.error(
1898
+ `warning ${finding.rule}: ${finding.declaration}: ${finding.message}`,
1899
+ );
1900
+ for (const check of report.checks.filter(
1901
+ c => !['complete', 'not-applicable'].includes(c.status),
1902
+ ))
1903
+ console.error(
1904
+ `advice ${check.status}: ${check.declaration ?? check.path ?? check.target ?? 'source'}: ${check.reason}`,
1905
+ );
1906
+ }
1907
+ if (verb === 'inspect')
1908
+ {
1909
+ const target = selected[0];
1910
+ const result = diagnostics(
1911
+ await compiler.inspect({
1912
+ ...input,
1913
+ target: target.language,
1914
+ sourceDir: target.sourceDir,
1915
+ testDir: target.testDir,
1916
+ nativeBindings: target.nativeBindings,
1917
+ }),
1918
+ );
1919
+ return output(options.json ? result : result.interface);
1920
+ }
1921
+ if (verb === 'advise')
1922
+ {
1923
+ diagnostics(await compiler.check({...input, advice: false}));
1924
+ const report = await authoringReport();
1925
+ if (options.json) output(report);
1926
+ else
1927
+ {
1928
+ printAdvice(report);
1929
+ output(
1930
+ report.ok
1931
+ ? 'Selected authoring checks complete; no unresolved findings.'
1932
+ : 'Authoring review required; see findings and analysis limits.',
1933
+ );
1934
+ }
1935
+ if (options.strict && !report.ok) process.exitCode = 1;
1936
+ return;
1937
+ }
1938
+ if (verb === 'prove')
1939
+ {
1940
+ const result = diagnostics(
1941
+ await proveWithZ3(compiler, input, {
1942
+ ...(options.solver !== undefined ? {binary: options.solver} : {}),
1943
+ ...Object.fromEntries(
1944
+ [
1945
+ ['proof-timeout', 'timeoutMs'],
1946
+ ['proof-memory', 'memoryMb'],
1947
+ ['proof-rlimit', 'resourceLimit'],
1948
+ ['proof-seed', 'seed'],
1949
+ ]
1950
+ .filter(([name]) => options[name] !== undefined)
1951
+ .map(([name, key]) => [key, Number(options[name])]),
1952
+ ),
1953
+ }),
1954
+ );
1955
+ output(
1956
+ options.json
1957
+ ? result
1958
+ : result.solverEvidence.length
1959
+ ? result.solverEvidence
1960
+ .map(
1961
+ row =>
1962
+ `${row.declaration}${row.kind === 'analysis' ? ` ${row.stage}` : ''}: ${row.status} (${row.outcome}). ${row.reason}`,
1963
+ )
1964
+ .join('\n')
1965
+ : input.verification?.layers.includes('proof')
1966
+ ? 'No source law obligations are available. No solver was invoked.'
1967
+ : 'No proof layer selected. Intrinsic definition checks passed; no solver was invoked.',
1968
+ );
909
1969
  // A refuted law is a definite failure; anything else not proved is incomplete.
910
- if (result.solverEvidence.some(row => row.status === "refuted")) process.exitCode = 1;
911
- else if (result.solverEvidence.some(row => !["proved", "exempted"].includes(row.status))) process.exitCode = 2;
1970
+ if (result.solverEvidence.some(row => row.status === 'refuted'))
1971
+ process.exitCode = 1;
1972
+ else if (
1973
+ result.solverEvidence.some(
1974
+ row => !['proved', 'exempted'].includes(row.status),
1975
+ )
1976
+ )
1977
+ process.exitCode = 2;
912
1978
  return;
913
1979
  }
914
1980
  // Each obligation reports how it is discharged, strongest first.
915
1981
  const statuses = [
916
- ["proved", "PROVED"],
917
- ["exhaustively-checked", "EXHAUSTIVELY CHECKED"],
918
- ["property-tested", "PROPERTY TESTED"],
919
- ["measured", "MEASURED"],
920
- ["runtime-checked", "RUNTIME CHECKED"],
921
- ["default-handler", "DEFAULT HANDLER"],
922
- ["assumed", "ASSUMED / EXTERNAL"],
1982
+ ['proved', 'PROVED'],
1983
+ ['exhaustively-checked', 'EXHAUSTIVELY CHECKED'],
1984
+ ['property-tested', 'PROPERTY TESTED'],
1985
+ ['measured', 'MEASURED'],
1986
+ ['runtime-checked', 'RUNTIME CHECKED'],
1987
+ ['default-handler', 'DEFAULT HANDLER'],
1988
+ ['assumed', 'ASSUMED / EXTERNAL'],
923
1989
  // A law-set check a laws-for block excuses, with its reason and expiry.
924
- ["exempted", "EXEMPTED"],
1990
+ ['exempted', 'EXEMPTED'],
925
1991
  // A law a confirmed counterexample shows false; the build fails.
926
- ["refuted", "REFUTED"],
1992
+ ['refuted', 'REFUTED'],
927
1993
  // The harness plane: an acknowledged discrepancy, a law whose last
928
1994
  // run was flaky, and a law whose tests it skips.
929
- ["known-discrepancy", "KNOWN DISCREPANCY"],
930
- ["flaky", "FLAKY"],
931
- ["skipped", "SKIPPED"],
1995
+ ['known-discrepancy', 'KNOWN DISCREPANCY'],
1996
+ ['flaky', 'FLAKY'],
1997
+ ['skipped', 'SKIPPED'],
932
1998
  // A law about an open history that the entries so far do not decide.
933
- ["pending", "PENDING"],
934
- ["planned", "PLANNED"],
935
- ["not-verified", "NOT VERIFIED"],
936
- ["incomplete", "INCOMPLETE"],
937
- ["unsupported", "UNSUPPORTED"],
1999
+ ['pending', 'PENDING'],
2000
+ ['planned', 'PLANNED'],
2001
+ ['not-verified', 'NOT VERIFIED'],
2002
+ ['incomplete', 'INCOMPLETE'],
2003
+ ['unsupported', 'UNSUPPORTED'],
938
2004
  ];
939
- const evidenceSummary = (evidence) => {
940
- if (!evidence.length) return "";
941
- const count = (status) => evidence.filter((item) => item.status === status).length;
2005
+ const evidenceSummary = evidence =>
2006
+ {
2007
+ if (!evidence.length) return '';
2008
+ const count = status =>
2009
+ evidence.filter(item => item.status === status).length;
942
2010
  // Exempted, refuted and the harness statuses (after assumed) are counted only when
943
2011
  // some obligation has them.
944
- const harnessFrom = statuses.findIndex(([status]) => status === "exempted");
945
- const shown = statuses.filter(([status], i) => i < harnessFrom || count(status));
946
- return ` Evidence: ${shown.map(([status, label]) => `${count(status)} ${label.toLowerCase()}`).join(", ")}.`;
2012
+ const harnessFrom = statuses.findIndex(([status]) => status === 'exempted');
2013
+ const shown = statuses.filter(
2014
+ ([status], i) => i < harnessFrom || count(status),
2015
+ );
2016
+ return ` Evidence: ${shown.map(([status, label]) => `${count(status)} ${label.toLowerCase()}`).join(', ')}.`;
947
2017
  };
948
- const obligationName = (item) => item.declaration.replace("::law::", "::");
949
- if (verb === "check") {
950
- const result = diagnostics(await compiler.check({...input, ...(options["warn-matches"] ? {warnMatches:true} : {})}));
951
- if (!options.json) for (const warning of result.warnings ?? [])
952
- console.error(`${warning.at ? `${warning.at.file}:${warning.at.line}:${warning.at.column}: ` : ""}warning ${warning.code}: ${warning.message}`);
953
- for (const target of selected) {
2018
+ const obligationName = item => item.declaration.replace('::law::', '::');
2019
+ if (verb === 'check')
2020
+ {
2021
+ const result = diagnostics(
2022
+ await compiler.check({
2023
+ ...input,
2024
+ ...(options['warn-matches'] ? {warnMatches: true} : {}),
2025
+ }),
2026
+ );
2027
+ if (!options['no-advice'])
2028
+ {
2029
+ result.advice = await authoringReport();
2030
+ if (!options.json) printAdvice(result.advice);
2031
+ }
2032
+
2033
+ for (const target of selected)
2034
+ {
954
2035
  if (target.nativeBindings !== undefined)
955
- diagnostics(await compiler.check({...input, nativeBindings: target.nativeBindings}));
2036
+ diagnostics(
2037
+ await compiler.check({
2038
+ ...input,
2039
+ nativeBindings: target.nativeBindings,
2040
+ }),
2041
+ );
956
2042
  }
957
2043
  output(
958
2044
  options.json
959
2045
  ? result
960
2046
  : `Compiled ${result.laws.length} law(s). Intrinsic definition checks passed.` +
961
- (result.verification?.selection === "no-selected-checks"
962
- ? " No law checks selected." : evidenceSummary(result.evidence ?? [])),
2047
+ (result.verification?.selection === 'no-selected-checks'
2048
+ ? ' No law checks selected.'
2049
+ : evidenceSummary(result.evidence ?? [])),
963
2050
  );
964
2051
  return;
965
2052
  }
966
- if (verb === "evidence") {
2053
+ if (verb === 'evidence')
2054
+ {
967
2055
  // An attestation named here, or in lawspec.edn, says where the tests
968
2056
  // ran; otherwise each law shows the attested run it last passed in.
969
2057
  // A named attestation of a run lawspec test recorded links each law to
970
2058
  // that run, with the outcome recorded for it, unless the document says
971
2059
  // the run has not completed.
972
2060
  const named = await readAttestation(config);
973
- const { runs, attestations, outcomes } = await lastRuns();
974
- const recorded = named && typeof named.run?.id === "string" ? outcomes.get(named.run.id) : undefined;
975
- const result = diagnostics(refutedOnly(await compiler.check({ ...input,
976
- ...(named ? { attestation: named, ...(recorded ? { attestedOutcomes: recorded } : {}) } : {}) })));
2061
+ const {runs, attestations, outcomes} = await lastRuns();
2062
+ const recorded =
2063
+ named && typeof named.run?.id === 'string'
2064
+ ? outcomes.get(named.run.id)
2065
+ : undefined;
2066
+ const result = diagnostics(
2067
+ refutedOnly(
2068
+ await compiler.check({
2069
+ ...input,
2070
+ ...(named
2071
+ ? {
2072
+ attestation: named,
2073
+ ...(recorded ? {attestedOutcomes: recorded} : {}),
2074
+ }
2075
+ : {}),
2076
+ }),
2077
+ ),
2078
+ );
977
2079
  if (result.refuted) process.exitCode = 1;
978
- let evidence = attachNativeEvidence(result.evidence,await readNativeObservations({compiler,input,selected,roots,
979
- configRoot,config,build:await buildDigest(),evidence:result.evidence,attestation:named}));
2080
+ let evidence = attachNativeEvidence(
2081
+ result.evidence,
2082
+ await readNativeObservations({
2083
+ compiler,
2084
+ input,
2085
+ selected,
2086
+ roots,
2087
+ configRoot,
2088
+ config,
2089
+ build: await buildDigest(),
2090
+ evidence: result.evidence,
2091
+ attestation: named,
2092
+ }),
2093
+ );
980
2094
  const environments = named ? [result.attestation] : [];
981
- if (!named) for (const [id, attestation] of attestations) {
982
- const laws = new Set([...runs].filter(([, run]) => run.environment === id).map(([law]) => law));
983
- if (!laws.size) continue;
984
- const attested = diagnostics(await compiler.check({ ...input, attestation, attestedOutcomes: outcomes.get(id) ?? {} }));
985
- const fields = new Map(attested.evidence.filter((item) => (item.against || item.plannedAgainst) && laws.has(item.declaration))
986
- .map(item => {
987
- // Receipts predating execution states keep their historical meaning.
988
- // An explicit running/wired state must retain the compiler's planned
989
- // fields; a cached passing law does not complete its environment run.
990
- const legacy = !attestation.execution && !item.against;
991
- return [item.declaration, legacy ? {
992
- environment: item.plannedEnvironment, environmentRun: item.plannedEnvironmentRun,
993
- against: item.plannedAgainst, environmentProviders: item.plannedEnvironmentProviders,
994
- } : Object.fromEntries(["environment", "environmentRun", "against", "environmentProviders", "environmentOutcome",
995
- "plannedEnvironment", "plannedEnvironmentRun", "plannedAgainst", "plannedEnvironmentProviders"]
996
- .filter(key => item[key] !== undefined).map(key => [key, item[key]]))];
997
- }));
998
- evidence = evidence.map((item) => item.stage === "law" && fields.has(item.declaration) ? { ...item, ...fields.get(item.declaration) } : item);
999
- environments.push({ ...attested.attestation, dependencies: attested.attestation.dependencies
1000
- .map((d) => ({ ...d,
1001
- obligations: (attestation.execution ? d.obligations : [...new Set([...d.obligations, ...(d.plannedObligations ?? [])])])
1002
- .filter((law) => laws.has(law)),
1003
- plannedObligations: attestation.execution ? (d.plannedObligations ?? []).filter((law) => laws.has(law)) : [] })) });
1004
- }
2095
+ if (!named)
2096
+ for (const [id, attestation] of attestations)
2097
+ {
2098
+ const laws = new Set(
2099
+ [...runs]
2100
+ .filter(([, run]) => run.environment === id)
2101
+ .map(([law]) => law),
2102
+ );
2103
+ if (!laws.size) continue;
2104
+ const attested = diagnostics(
2105
+ await compiler.check({
2106
+ ...input,
2107
+ attestation,
2108
+ attestedOutcomes: outcomes.get(id) ?? {},
2109
+ }),
2110
+ );
2111
+ const fields = new Map(
2112
+ attested.evidence
2113
+ .filter(
2114
+ item =>
2115
+ (item.against || item.plannedAgainst) &&
2116
+ laws.has(item.declaration),
2117
+ )
2118
+ .map(item =>
2119
+ {
2120
+ // Receipts predating execution states keep their historical meaning.
2121
+ // An explicit running/wired state must retain the compiler's planned
2122
+ // fields; a cached passing law does not complete its environment run.
2123
+ const legacy = !attestation.execution && !item.against;
2124
+ return [
2125
+ item.declaration,
2126
+ legacy
2127
+ ? {
2128
+ environment: item.plannedEnvironment,
2129
+ environmentRun: item.plannedEnvironmentRun,
2130
+ against: item.plannedAgainst,
2131
+ environmentProviders: item.plannedEnvironmentProviders,
2132
+ }
2133
+ : Object.fromEntries(
2134
+ [
2135
+ 'environment',
2136
+ 'environmentRun',
2137
+ 'against',
2138
+ 'environmentProviders',
2139
+ 'environmentOutcome',
2140
+ 'plannedEnvironment',
2141
+ 'plannedEnvironmentRun',
2142
+ 'plannedAgainst',
2143
+ 'plannedEnvironmentProviders',
2144
+ ]
2145
+ .filter(key => item[key] !== undefined)
2146
+ .map(key => [key, item[key]]),
2147
+ ),
2148
+ ];
2149
+ }),
2150
+ );
2151
+ evidence = evidence.map(item =>
2152
+ item.stage === 'law' && fields.has(item.declaration)
2153
+ ? {...item, ...fields.get(item.declaration)}
2154
+ : item,
2155
+ );
2156
+ environments.push({
2157
+ ...attested.attestation,
2158
+ dependencies: attested.attestation.dependencies.map(d => ({
2159
+ ...d,
2160
+ obligations: (attestation.execution
2161
+ ? d.obligations
2162
+ : [
2163
+ ...new Set([
2164
+ ...d.obligations,
2165
+ ...(d.plannedObligations ?? []),
2166
+ ]),
2167
+ ]
2168
+ ).filter(law => laws.has(law)),
2169
+ plannedObligations: attestation.execution
2170
+ ? (d.plannedObligations ?? []).filter(law => laws.has(law))
2171
+ : [],
2172
+ })),
2173
+ });
2174
+ }
1005
2175
  // Native bindings are configured per target; their obligations are added.
1006
- for (const target of selected) {
2176
+ for (const target of selected)
2177
+ {
1007
2178
  if (target.nativeBindings === undefined) continue;
1008
- const bound = diagnostics(await compiler.check({...input, nativeBindings: target.nativeBindings}));
1009
- evidence = evidence.concat(bound.evidence
1010
- .filter((item) => ["binding", "codec", "generator", "native-function"].includes(item.stage))
1011
- .map((item) => ({...item, target: target.language})));
2179
+ const bound = diagnostics(
2180
+ await compiler.check({...input, nativeBindings: target.nativeBindings}),
2181
+ );
2182
+ evidence = evidence.concat(
2183
+ bound.evidence
2184
+ .filter(item =>
2185
+ ['binding', 'codec', 'generator', 'native-function'].includes(
2186
+ item.stage,
2187
+ ),
2188
+ )
2189
+ .map(item => ({...item, target: target.language})),
2190
+ );
1012
2191
  }
1013
- evidence = evidence.filter((item) => !positional[0] ||
1014
- obligationName(item) === positional[0] || item.owner === positional[0]);
1015
- if (positional[0] && !evidence.length) throw new Error("No matching obligation");
2192
+ evidence = evidence.filter(
2193
+ item =>
2194
+ !positional[0] ||
2195
+ obligationName(item) === positional[0] ||
2196
+ item.owner === positional[0],
2197
+ );
2198
+ if (positional[0] && !evidence.length)
2199
+ throw new Error('No matching obligation');
1016
2200
  // The last run's outcome (lawspec test): a law that failed, then passed
1017
2201
  // on a retry, is flaky; what its generated cases covered is its adequacy.
1018
- evidence = evidence.map((item) => {
1019
- if(item.nativeEvidence)return item;
1020
- const run = item.stage === "law" ? runs.get(item.declaration) : undefined;
2202
+ evidence = evidence.map(item =>
2203
+ {
2204
+ if (item.nativeEvidence) return item;
2205
+ const run = item.stage === 'law' ? runs.get(item.declaration) : undefined;
1021
2206
  if (!run) return item;
1022
- return { ...item, lastNativeRun: {passed: run.passed, seed: run.seed}, ...(run.adequacy ? { adequacy: run.adequacy } : {}),
1023
- ...(run.flaky && ["property-tested", "exhaustively-checked"].includes(item.status)
1024
- ? { status: "flaky", reason: `${item.reason}; its last run failed, then passed on a retry` } : {}) };
2207
+ return {
2208
+ ...item,
2209
+ lastNativeRun: {passed: run.passed, seed: run.seed},
2210
+ ...(run.adequacy ? {adequacy: run.adequacy} : {}),
2211
+ ...(run.flaky &&
2212
+ ['property-tested', 'exhaustively-checked'].includes(item.status)
2213
+ ? {
2214
+ status: 'flaky',
2215
+ reason: `${item.reason}; its last run failed, then passed on a retry`,
2216
+ }
2217
+ : {}),
2218
+ };
1025
2219
  });
1026
- const harnessed = evidence.filter((item) => item.harness || item.adequacy);
2220
+ const harnessed = evidence.filter(item => item.harness || item.adequacy);
1027
2221
  output(
1028
2222
  options.json
1029
2223
  ? evidence
1030
- : [...statuses
1031
- .map(([status, label]) => {
1032
- const items = evidence.filter((item) => item.status === status);
1033
- if (!items.length) return null;
1034
- return `${label} (${items.length})\n` + items.map((item) =>
1035
- ` ${item.stage} ${obligationName(item)}${item.target ? ` [${item.target}]` : ""}` +
1036
- (item.claim ? `: ${item.claim.text}` : "") + `\n ${item.reason}` +
1037
- (item.nativeEvidence ? `\n ${nativeEvidenceText(item).replaceAll("\n","\n ")}` : "") +
1038
- (item.lastNativeRun ? `\n last native run passed at ${item.lastNativeRun.passed} (seed ${item.lastNativeRun.seed})` : "") +
1039
- (item.against ? (item.environmentOutcome
1040
- ? `\n ${item.environmentOutcome} in completed run ${item.environmentRun.id} in environment ${item.environment}${executionText(item.environmentRun)} against `
1041
- : `\n last recorded passing run in environment ${item.environment} (run ${item.environmentRun.id}) against `) +
1042
- item.against.map(dependencyText).join("; ") : "") +
1043
- (item.plannedAgainst ? `\n planned in environment ${item.plannedEnvironment} (run ${item.plannedEnvironmentRun.id}` +
1044
- `${executionText(item.plannedEnvironmentRun)}; ${unlinkedText(item.plannedEnvironmentRun)}) against ` +
1045
- item.plannedAgainst.map(dependencyText).join("; ") : "")).join("\n");
1046
- })
1047
- .filter((section) => section !== null),
1048
- // How each law is discharged: the harness plane, apart from what
1049
- // the laws say.
1050
- ...(harnessed.length ? [`HARNESS (${harnessed.length})\n` + harnessed.map(harnessText).join("\n")] : []),
1051
- // Where the tests ran: reporting only, so no status above changes.
1052
- ...environments.map((e) => `ENVIRONMENT ${e.environment} (run ${e.run.id}, recorded ${e.run.recordedAt}${executionText(e.run)})\n` +
1053
- (e.architecture ? ` architecture ${e.architecture.document} ${e.architecture.digest}` +
1054
- (e.architecture.topologyDigest ? `, topology ${e.architecture.topologyDigest}` : "") + "\n" : "") +
1055
- (e.application ? ` application ${e.application.node}: ` +
1056
- (e.application.component ? `component ${e.application.component.name} ${e.application.component.version} (${e.application.component.fingerprint}); ` : `contract ${e.application.contract.package} ${e.application.contract.version}; `) +
1057
- `${e.application.implementation.kind} ${e.application.implementation.product} ${e.application.implementation.version}` +
1058
- (e.application.implementation.commit ? ` (commit ${e.application.implementation.commit})` : "") + "\n" : "") +
1059
- e.dependencies.map((d) => {
1060
- const outcome = (o) => evidence.find((item) => item.declaration === o && item.environmentOutcome)?.environmentOutcome;
1061
- const failed = d.obligations.filter((o) => ["failed", "incomplete"].includes(outcome(o))).length;
1062
- return ` ${dependencyText(d)}; ` + (d.obligations.length
1063
- ? `${d.obligations.length} tested obligation(s)` + (failed ? `, ${failed} failed` : "") :
1064
- d.plannedObligations?.length ? `${d.plannedObligations.length} planned obligation(s); ${unlinkedText(e.run)}` : "no tested obligation relies on it");
1065
- }).join("\n"))]
1066
- .join("\n\n"),
2224
+ : [
2225
+ ...statuses
2226
+ .map(([status, label]) =>
2227
+ {
2228
+ const items = evidence.filter(item => item.status === status);
2229
+ if (!items.length) return null;
2230
+ return (
2231
+ `${label} (${items.length})\n` +
2232
+ items
2233
+ .map(
2234
+ item =>
2235
+ ` ${item.stage} ${obligationName(item)}${item.target ? ` [${item.target}]` : ''}` +
2236
+ (item.claim ? `: ${item.claim.text}` : '') +
2237
+ `\n ${item.reason}` +
2238
+ (item.nativeEvidence
2239
+ ? `\n ${nativeEvidenceText(item).replaceAll('\n', '\n ')}`
2240
+ : '') +
2241
+ (item.lastNativeRun
2242
+ ? `\n last native run passed at ${item.lastNativeRun.passed} (seed ${item.lastNativeRun.seed})`
2243
+ : '') +
2244
+ (item.against
2245
+ ? (item.environmentOutcome
2246
+ ? `\n ${item.environmentOutcome} in completed run ${item.environmentRun.id} in environment ${item.environment}${executionText(item.environmentRun)} against `
2247
+ : `\n last recorded passing run in environment ${item.environment} (run ${item.environmentRun.id}) against `) +
2248
+ item.against.map(dependencyText).join('; ')
2249
+ : '') +
2250
+ (item.plannedAgainst
2251
+ ? `\n planned in environment ${item.plannedEnvironment} (run ${item.plannedEnvironmentRun.id}` +
2252
+ `${executionText(item.plannedEnvironmentRun)}; ${unlinkedText(item.plannedEnvironmentRun)}) against ` +
2253
+ item.plannedAgainst.map(dependencyText).join('; ')
2254
+ : ''),
2255
+ )
2256
+ .join('\n')
2257
+ );
2258
+ })
2259
+ .filter(section => section !== null),
2260
+ // How each law is discharged: the harness plane, apart from what
2261
+ // the laws say.
2262
+ ...(harnessed.length
2263
+ ? [
2264
+ `HARNESS (${harnessed.length})\n` +
2265
+ harnessed.map(harnessText).join('\n'),
2266
+ ]
2267
+ : []),
2268
+ // Where the tests ran: reporting only, so no status above changes.
2269
+ ...environments.map(
2270
+ e =>
2271
+ `ENVIRONMENT ${e.environment} (run ${e.run.id}, recorded ${e.run.recordedAt}${executionText(e.run)})\n` +
2272
+ (e.architecture
2273
+ ? ` architecture ${e.architecture.document} ${e.architecture.digest}` +
2274
+ (e.architecture.topologyDigest
2275
+ ? `, topology ${e.architecture.topologyDigest}`
2276
+ : '') +
2277
+ '\n'
2278
+ : '') +
2279
+ (e.application
2280
+ ? ` application ${e.application.node}: ` +
2281
+ (e.application.component
2282
+ ? `component ${e.application.component.name} ${e.application.component.version} (${e.application.component.fingerprint}); `
2283
+ : `contract ${e.application.contract.package} ${e.application.contract.version}; `) +
2284
+ `${e.application.implementation.kind} ${e.application.implementation.product} ${e.application.implementation.version}` +
2285
+ (e.application.implementation.commit
2286
+ ? ` (commit ${e.application.implementation.commit})`
2287
+ : '') +
2288
+ '\n'
2289
+ : '') +
2290
+ e.dependencies
2291
+ .map(d =>
2292
+ {
2293
+ const outcome = o =>
2294
+ evidence.find(
2295
+ item =>
2296
+ item.declaration === o && item.environmentOutcome,
2297
+ )?.environmentOutcome;
2298
+ const failed = d.obligations.filter(o =>
2299
+ ['failed', 'incomplete'].includes(outcome(o)),
2300
+ ).length;
2301
+ return (
2302
+ ` ${dependencyText(d)}; ` +
2303
+ (d.obligations.length
2304
+ ? `${d.obligations.length} tested obligation(s)` +
2305
+ (failed ? `, ${failed} failed` : '')
2306
+ : d.plannedObligations?.length
2307
+ ? `${d.plannedObligations.length} planned obligation(s); ${unlinkedText(e.run)}`
2308
+ : 'no tested obligation relies on it')
2309
+ );
2310
+ })
2311
+ .join('\n'),
2312
+ ),
2313
+ ].join('\n\n'),
1067
2314
  );
1068
2315
  return;
1069
2316
  }
1070
- if (verb === "explain") {
2317
+ if (verb === 'explain')
2318
+ {
1071
2319
  // The compiler words the law (eng by default); the CLI only reads the
1072
2320
  // recorded native observations and passes their evidence rows in.
1073
- const request = { ...input, view: options.view ?? "eng", ...(positional[0] ? { law: positional[0] } : {}) };
2321
+ const request = {
2322
+ ...input,
2323
+ view: options.view ?? 'eng',
2324
+ ...(positional[0] ? {law: positional[0]} : {}),
2325
+ };
1074
2326
  let explained = diagnostics(await compiler.explain(request));
1075
2327
  const expanded = diagnostics(await compiler.expand(input));
1076
- const observations = await readNativeObservations({ compiler, input, selected, roots, configRoot, config,
1077
- build: await buildDigest(), evidence: expanded.evidence, attestation: await readAttestation(config) });
2328
+ const observations = await readNativeObservations({
2329
+ compiler,
2330
+ input,
2331
+ selected,
2332
+ roots,
2333
+ configRoot,
2334
+ config,
2335
+ build: await buildDigest(),
2336
+ evidence: expanded.evidence,
2337
+ attestation: await readAttestation(config),
2338
+ });
1078
2339
  if (observations.length)
1079
- explained = diagnostics(await compiler.explain({ ...request, evidence: attachNativeEvidence(expanded.evidence, observations) }));
2340
+ explained = diagnostics(
2341
+ await compiler.explain({
2342
+ ...request,
2343
+ evidence: attachNativeEvidence(expanded.evidence, observations),
2344
+ }),
2345
+ );
1080
2346
  output(options.json ? explained.explanations : explained.text);
1081
2347
  return;
1082
2348
  }
1083
- if (verb === "test" && !options.benchmarks && config.manifestVersion === 1 && !(config.verification?.layers ?? []).some(layer => ["exhaustive", "property", "examples", "model"].includes(layer))) {
2349
+ if (
2350
+ verb === 'test' &&
2351
+ !options.benchmarks &&
2352
+ config.manifestVersion === 1 &&
2353
+ !(config.verification?.layers ?? []).some(layer =>
2354
+ ['exhaustive', 'property', 'examples', 'model'].includes(layer),
2355
+ )
2356
+ )
2357
+ {
1084
2358
  const checked = diagnostics(await compiler.check(input));
1085
- output(options.json ? { verification: checked.verification, evidence: checked.evidence, testsExecuted: 0 }
1086
- : (config.verification?.layers?.length ? "No native law checks selected. See lawspec evidence for the selected static analyses." : "No law verification layers selected. Intrinsic definition checks passed; no law checks ran."));
2359
+ output(
2360
+ options.json
2361
+ ? {
2362
+ verification: checked.verification,
2363
+ evidence: checked.evidence,
2364
+ testsExecuted: 0,
2365
+ }
2366
+ : config.verification?.layers?.length
2367
+ ? 'No native law checks selected. See lawspec evidence for the selected static analyses.'
2368
+ : 'No law verification layers selected. Intrinsic definition checks passed; no law checks ran.',
2369
+ );
1087
2370
  return;
1088
2371
  }
1089
- if (verb === "test") return runTests(compiler, input, selected, roots, config);
1090
- if (options["dry-run"] && options.check)
1091
- throw new Error("--dry-run and --check are mutually exclusive");
2372
+ if (verb === 'test')
2373
+ return runTests(compiler, input, selected, roots, config);
2374
+ if (options['dry-run'] && options.check)
2375
+ throw new Error('--dry-run and --check are mutually exclusive');
2376
+ const advisory = options['no-advice'] ? undefined : await authoringReport();
2377
+ if (advisory && !options.json) printAdvice(advisory);
1092
2378
  const artifacts = [];
1093
2379
  for (const target of selected)
1094
2380
  artifacts.push(
@@ -1106,20 +2392,21 @@ async function main() {
1106
2392
  const reports = await Promise.all(
1107
2393
  selected.map((t, i) => doctor(t, roots[i], artifacts[i])),
1108
2394
  );
1109
- const failed = reports.filter((r) => !r.ok);
2395
+ const failed = reports.filter(r => !r.ok);
1110
2396
  if (failed.length)
1111
2397
  throw new Error(
1112
2398
  failed
1113
- .map((r) => `${r.target}: ${r.message}\n${r.instructions}`)
1114
- .join("\n"),
2399
+ .map(r => `${r.target}: ${r.message}\n${r.instructions}`)
2400
+ .join('\n'),
1115
2401
  );
1116
2402
  const plans = await Promise.all(
1117
2403
  artifacts.map((files, i) => planWrites(roots[i], files)),
1118
2404
  );
1119
- if (!options["dry-run"] && !options.check) await applyWrites(plans);
2405
+ if (!options['dry-run'] && !options.check) await applyWrites(plans);
1120
2406
  const summary = plans.map((plan, i) => ({
1121
2407
  target: selected[i].language,
1122
- changes: plan.changes.map((c) => ({ action: c.action, path: c.relative })),
2408
+ ...(advisory ? {advice: advisory} : {}),
2409
+ changes: plan.changes.map(c => ({action: c.action, path: c.relative})),
1123
2410
  preservedAdapters: plan.preserved,
1124
2411
  adapterUpdates: plan.adapterUpdates,
1125
2412
  test: testCommand(selected[i], roots[i]),
@@ -1129,20 +2416,21 @@ async function main() {
1129
2416
  ? summary
1130
2417
  : summary
1131
2418
  .map(
1132
- (r) =>
1133
- `${r.target}: ${r.changes.length} ${options["dry-run"] || options.check ? "planned" : "applied"} change(s), ${r.preservedAdapters.length} user adapter(s) preserved.${r.adapterUpdates.length ? "\nReview required adapter signatures:\n" + r.adapterUpdates.map((a) => a.path + "\n" + a.requiredAdapter).join("\n") : ""}\n${r.test === null ? "Artifact generation complete." : "Test: " + r.test}`,
2419
+ r =>
2420
+ `${r.target}: ${r.changes.length} ${options['dry-run'] || options.check ? 'planned' : 'applied'} change(s), ${r.preservedAdapters.length} user adapter(s) preserved.${r.adapterUpdates.length ? '\nReview required adapter signatures:\n' + r.adapterUpdates.map(a => a.path + '\n' + a.requiredAdapter).join('\n') : ''}\n${r.test === null ? 'Artifact generation complete.' : 'Test: ' + r.test}`,
1134
2421
  )
1135
- .join("\n"),
2422
+ .join('\n'),
1136
2423
  );
1137
- if (options.check && plans.some((p) => p.changes.length))
1138
- process.exitCode = 1;
2424
+ if (options.check && plans.some(p => p.changes.length)) process.exitCode = 1;
1139
2425
  }
1140
- main().catch(async (error) => {
1141
- if (createdState !== null) await rm(createdState, { recursive: true, force: true });
2426
+ main().catch(async error =>
2427
+ {
2428
+ if (createdState !== null)
2429
+ await rm(createdState, {recursive: true, force: true});
1142
2430
  if (options.json)
1143
2431
  output({
1144
2432
  diagnostics: error.diagnostics || [
1145
- { code: "cli", message: error.message, at: null },
2433
+ {code: 'cli', message: error.message, at: null},
1146
2434
  ],
1147
2435
  });
1148
2436
  else console.error(`lawspec: ${error.message}`);