lawspec 0.24.0 → 0.25.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (87) hide show
  1. package/CHANGELOG.md +67 -1
  2. package/README.md +29 -22
  3. package/UNICODE-LICENSE.txt +39 -0
  4. package/api.mjs +14 -23
  5. package/bin/lawspec.mjs +186 -65
  6. package/build.json +255 -159
  7. package/builtin-data-names.mjs +73 -0
  8. package/core.wasm +2 -2
  9. package/examples/native-payments/clojure/lawspec.json +13 -2
  10. package/examples/native-payments/csharp/lawspec.json +13 -2
  11. package/examples/native-payments/elixir/lawspec.json +14 -3
  12. package/examples/native-payments/erlang/lawspec.json +14 -3
  13. package/examples/native-payments/fsharp/lawspec.json +14 -3
  14. package/examples/native-payments/gleam/lawspec.json +14 -3
  15. package/examples/native-payments/go/lawspec.json +14 -3
  16. package/examples/native-payments/groovy/lawspec.json +14 -3
  17. package/examples/native-payments/haskell/lawspec.json +14 -3
  18. package/examples/native-payments/java/lawspec.json +14 -3
  19. package/examples/native-payments/javascript/lawspec.json +14 -3
  20. package/examples/native-payments/kotlin/lawspec.json +14 -3
  21. package/examples/native-payments/python/lawspec.json +14 -3
  22. package/examples/native-payments/rust/lawspec.json +14 -3
  23. package/examples/native-payments/scala/lawspec.json +14 -3
  24. package/examples/native-payments/swift/lawspec.json +14 -3
  25. package/examples/native-payments/typescript/lawspec.json +14 -3
  26. package/examples/packages/orders/lawspec.json +25 -5
  27. package/examples/packages/orders/orders.lawspec +36 -34
  28. package/examples/packages/shop-domain/src/domain.lawspec +23 -21
  29. package/examples/packages/shop-tax-1/src/rates.lawspec +4 -4
  30. package/examples/packages/shop-tax-2/src/rates.lawspec +5 -4
  31. package/examples/rc1/authorization-snapshots.lawspec +112 -0
  32. package/examples/rc1/banner-filenames.lawspec +63 -0
  33. package/examples/rc1/bit-codec.lawspec +56 -0
  34. package/examples/rc1/bounded-witness-search.lawspec +144 -0
  35. package/examples/rc1/conflicting-requirements.lawspec +30 -0
  36. package/examples/rc1/constructive-witnesses.lawspec +113 -0
  37. package/examples/rc1/documentary-review.lawspec +42 -0
  38. package/examples/rc1/empty-domains.lawspec +46 -0
  39. package/examples/rc1/finite-integer-domains.lawspec +75 -0
  40. package/examples/rc1/law-metadata.lawspec +29 -0
  41. package/examples/rc1/native-payments.lawspec +107 -0
  42. package/examples/rc1/nesting/rrr.lawspec +33 -0
  43. package/examples/rc1/nesting/rru.lawspec +56 -0
  44. package/examples/rc1/nesting/rur.lawspec +57 -0
  45. package/examples/rc1/nesting/ruu.lawspec +77 -0
  46. package/examples/rc1/nesting/urr.lawspec +52 -0
  47. package/examples/rc1/nesting/uru.lawspec +72 -0
  48. package/examples/rc1/nesting/uur.lawspec +73 -0
  49. package/examples/rc1/nesting/uuu.lawspec +95 -0
  50. package/examples/rc1/order-workflow.lawspec +126 -0
  51. package/examples/rc1/parcel-measurements.lawspec +92 -0
  52. package/examples/rc1/picture-records.lawspec +51 -0
  53. package/examples/rc1/picture-tuples.lawspec +47 -0
  54. package/examples/rc1/record-payloads.lawspec +56 -0
  55. package/examples/rc1/recursive-records.lawspec +64 -0
  56. package/examples/rc1/refund-conformance.lawspec +44 -0
  57. package/examples/rc1/refund-policy.lawspec +88 -0
  58. package/examples/rc1/requirement-composition.lawspec +89 -0
  59. package/examples/rc1/structural-records.lawspec +53 -0
  60. package/examples/rc1-authoring.lawspec +56 -0
  61. package/examples-command.mjs +11 -5
  62. package/explain.mjs +112 -0
  63. package/expression-presentation.mjs +333 -0
  64. package/files.mjs +16 -0
  65. package/index.d.ts +929 -11
  66. package/lsp.mjs +231 -0
  67. package/migrate.mjs +135 -0
  68. package/migration-bindings.mjs +86 -0
  69. package/migration-cases.mjs +45 -0
  70. package/migration-collections.mjs +54 -0
  71. package/migration-correspondence.mjs +275 -0
  72. package/migration-generation.mjs +99 -0
  73. package/migration-laws.mjs +102 -0
  74. package/migration-records.mjs +166 -0
  75. package/migration-source.mjs +247 -0
  76. package/migration-write.mjs +156 -0
  77. package/native-evidence.mjs +187 -0
  78. package/native-examples.mjs +8 -1
  79. package/node-events-reporter.mjs +23 -0
  80. package/package.json +8 -1
  81. package/positional-fields.mjs +13 -0
  82. package/proof.d.ts +35 -0
  83. package/proof.mjs +174 -0
  84. package/starter-rc1.lawspec +25 -0
  85. package/templates.mjs +2 -2
  86. package/test-command.mjs +107 -35
  87. package/typed-presentation.mjs +165 -0
package/CHANGELOG.md CHANGED
@@ -6,6 +6,71 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [0.25.0] - 2026-10-18
10
+
11
+ ### Added
12
+
13
+ - Optional case warnings through `lawspec check --warn-matches`, SDK requests
14
+ with `warnMatches: true`, and the VS Code `lawspec.warnMatches` setting.
15
+ Findings retain source spans and remain separate from compiler errors and
16
+ law evidence. An empty warning list does not prove that every branch is reachable.
17
+
18
+ - Checked documentation rejection examples with `reject=<diagnostic-code>`.
19
+ Each fixture requires exactly its expected compiler diagnostic, preserves
20
+ failure context and reports unexpected acceptance after editing.
21
+ - Canonical authoring with `function` and `procedure`, phrase names, explicit
22
+ record and alternative payloads, first-matching cases, readable equality
23
+ wording and nested logical quantifiers.
24
+ - Checked mappings over resolved scalar, record, constructor and collection
25
+ constants. Typed Eq detects duplicate and non-reflexive keys; complete finite
26
+ coverage or an explicit fallback is required. Complete mappings derive
27
+ preimages and, when justified by unique outputs, a Maybe-valued inverse.
28
+ - Formatting, validated project migration from 0.24, four explanation views,
29
+ and compiler-backed editor support. Ordinary interfaces use API schema 5,
30
+ configuration version 2 and the technical language profile `1.0-rc.1`.
31
+ - A canonical Chapter 6 specification, with independent native Python oracles
32
+ for all A-instruction addresses and C-instruction combinations.
33
+ - Scoped native execution evidence shared by the four explanation views,
34
+ including current/stale inputs, actual completions, seeds and failure output.
35
+ Interrupted or undiscovered checks cannot reuse an older successful result;
36
+ sampled model runs remain distinct from proofs.
37
+ - Refund policy and native conformance examples, contradictory requirements
38
+ with concrete refutations, and a stateful order-processing example.
39
+
40
+ ### Changed
41
+
42
+ - Formatting omits optional record-type field commas using the parser's source
43
+ inventory, retaining commas in values, patterns, tuples, comments and text.
44
+ - Formatting preserves line-scoped scenario arguments, including command
45
+ bindings, parallel branches and recovery, while wrapping surrounding code.
46
+ Multiline literal contents retain their whitespace, and block endings after
47
+ a closing quote update the indentation of subsequent declarations.
48
+ - Documentation highlighting now uses the editor's shared TextMate grammar and
49
+ tokenizer. Phrase names end at their delimiter, and canonical function/type
50
+ syntax receives the editor's scopes. Highlighting asset failures preserve
51
+ readable source and compiler interaction.
52
+ - Formatting retains the indentation of abilities, stateful handler operations
53
+ and handled expressions, including conditional initializers.
54
+ - Source formatting covers workflows, models, actors, supervisors, protocols,
55
+ scenarios, resources, wrappers, refinements and harness groups. Paired scenario
56
+ and benchmark names remain indivisible; words inside them do not affect block
57
+ indentation. A top-level `handle` declaration does not open an expression block.
58
+
59
+ - Law verification layers are selected independently and default to none.
60
+ Definition validation and deliberately deferred runtime contracts remain
61
+ mandatory. New-project instructions explicitly select starter law checks.
62
+ - Model checks can be selected independently on all 17 native targets while
63
+ actor and supervisor APIs remain available to ordinary law tests. Native
64
+ manifests register model checks, and runners require their actual completions.
65
+ - Canonical `Set` uses Eq and first-occurrence order; legacy ordered-set uses
66
+ migrate to `SortedSet`. Canonical numeric names distinguish `Whole` and `Nat`.
67
+ - Validated payload transport preserves indexed, GADT and existential metadata.
68
+ Unsupported source, population, dependency and native-binding correspondence
69
+ continues to block migration writes.
70
+ - Java and Groovy structural property checks retain seeded generation and native
71
+ shrinking without exhausting a small domain's JetCheck generation trees.
72
+ Go equality generation handles payload-free alternatives alongside payloads.
73
+
9
74
  ## [0.24.0] - 2026-10-13
10
75
 
11
76
  ### Added
@@ -1634,7 +1699,8 @@ A maintenance release. The language, generated code and API are unchanged from
1634
1699
  machine-sized bindings reject an architecture mismatch. Rust adapters take
1635
1700
  owned values.
1636
1701
 
1637
- [Unreleased]: https://github.com/brain-fuel/lawspec/compare/v0.24.0...HEAD
1702
+ [Unreleased]: https://github.com/brain-fuel/lawspec/compare/v0.25.0...HEAD
1703
+ [0.25.0]: https://github.com/brain-fuel/lawspec/compare/v0.24.0...v0.25.0
1638
1704
  [0.24.0]: https://github.com/brain-fuel/lawspec/compare/v0.23.0...v0.24.0
1639
1705
  [0.23.0]: https://github.com/brain-fuel/lawspec/compare/v0.22.0...v0.23.0
1640
1706
  [0.22.0]: https://github.com/brain-fuel/lawspec/compare/v0.21.0...v0.22.0
package/README.md CHANGED
@@ -5,21 +5,28 @@
5
5
  LawSpec is a specification language for the laws your code must obey. It
6
6
  compiles reusable laws and concrete examples into native property-based tests
7
7
  and implementation adapters for Java, Python, JavaScript, TypeScript, Go,
8
- Haskell, Kotlin and Rust. The compiler is written in Haskell and distributed on
9
- npm as prebuilt WebAssembly, with a Node CLI and a typed JavaScript API.
8
+ Haskell, Kotlin, Rust, C#, F#, Swift, Erlang, Elixir, Gleam, Clojure, Groovy and
9
+ Scala. The compiler is written in Haskell and distributed on npm as prebuilt
10
+ WebAssembly, with a Node CLI and a typed JavaScript API.
11
+
12
+ The canonical authoring examples below target 0.25.0, the minor in preparation
13
+ on `main`.
14
+ Install the development checkout as shown below. For released 0.24.0, use the
15
+ [0.24.0 documentation](https://github.com/brain-fuel/lawspec/tree/v0.24.0).
10
16
 
11
17
  ## Features
12
18
 
13
19
  - **Reusable laws.** A prelude of [round-trip, equivalence and algebraic laws](docs/reference/prelude-algebra.md), and your own generic laws.
14
20
  - **Examples with expected results** that [pin each law down](docs/reference/language/laws-and-examples.md).
15
- - **Native tests** with each target's framework, generators and shrinkers: JetCheck, Hypothesis, fast-check, Rapid, Hedgehog, Kotest and Proptest.
21
+ - **Native tests** with each [target's framework, generators and shrinkers](docs/how-to/targets/index.md).
16
22
  - **A full scalar catalog** with [exact arithmetic](docs/reference/primitives.md) that never wraps.
17
23
  - **Structural data**: [lists, `Maybe`, `Either`, products and sums](docs/reference/language/types-and-data.md).
18
24
  - **Refinements and contracts** with [dependent generation](docs/reference/refinements.md) that constructs valid inputs.
19
- - **Checked total definitions** that are [proved and generated](docs/reference/language/definitions.md) on every target.
25
+ - **Automatic definition checks** for [exhaustiveness, termination, definedness and contracts](docs/reference/language/definitions.md), with deliberately deferred postconditions enforced at runtime.
20
26
  - **Indexed families** such as [length-indexed vectors](docs/reference/language/indexed-families.md), with proved indices.
21
27
  - **Domain modeling** with [wrappers and workflows](docs/reference/language/domain-modeling.md).
22
28
  - **Imports and versioned packages** of [shared laws and types](docs/reference/language/imports-and-packages.md).
29
+ - **Optional Z3 law proofs** through an [explicit solver host](docs/explanation/smt-proof.md), with task identities, limits and outcomes recorded.
23
30
  - **Evidence** for every obligation: [proved, exhaustively checked, property tested, runtime checked or assumed](docs/reference/language/evidence-and-discharge.md).
24
31
  - **Native bindings** to [your existing domain types and generators](docs/how-to/bind-native-types.md).
25
32
  - **Safe regeneration**: [your adapters and build files stay yours](docs/explanation/ownership-and-regeneration.md).
@@ -29,33 +36,33 @@ npm as prebuilt WebAssembly, with a Node CLI and a typed JavaScript API.
29
36
  Node 22+ and the selected target's build tools are required. No Haskell
30
37
  toolchain is needed. The reference platforms are macOS and Linux.
31
38
 
32
- ```sh
33
- npm install --save-dev lawspec@0.24.0
34
- npx lawspec --version
35
- ```
36
-
37
- To try it in a **new, empty directory**, initialize before installing, so that
38
- LawSpec can create `package.json` and its test script:
39
+ The checkout includes the development WASM package. To try it in a **new, empty
40
+ directory**, initialize before installing, so that LawSpec can create
41
+ `package.json` and its test script:
39
42
 
40
43
  ```sh
44
+ git clone https://github.com/brain-fuel/lawspec.git lawspec
41
45
  mkdir lawspec-example
42
46
  cd lawspec-example
43
- npm exec --package=lawspec@0.24.0 -- lawspec init --target javascript
44
- npm install --save-dev lawspec@0.24.0
47
+ node ../lawspec/npm/bin/lawspec.mjs init --target javascript
48
+ npm install --save-dev ../lawspec/npm
49
+ npx lawspec --version
45
50
  npx lawspec check
46
- npx lawspec explain 'example.atoi_codec::itoa and then atoi yields a'
51
+ npx lawspec explain 'example.codec::codec'
47
52
  npx lawspec doctor
48
- npx lawspec generate
49
53
  ```
50
54
 
51
- Implement `src/example/atoi_codec.mjs`, then run `npm test`:
55
+ New projects start with `verification.layers: []`: intrinsic definition checks
56
+ run, and no law verification is selected. Set `verification.layers` to
57
+ `["property", "examples"]` in `lawspec.json`, then run `npx lawspec generate`.
58
+ Implement `src/example/codec.mjs`, then run `npm test`:
52
59
 
53
60
  ```javascript
54
61
  export function itoa(value) { return String(value); }
55
62
  export function atoi(value) { return Number(value); }
56
63
  ```
57
64
 
58
- In an existing project, install LawSpec first, then run
65
+ In an existing project, install the checkout's `npm` directory first, then run
59
66
  `npx lawspec init --target javascript`. Existing build files are preserved;
60
67
  apply the printed setup instructions before generating. See
61
68
  [Install LawSpec and create a project](docs/how-to/install-and-init.md).
@@ -68,14 +75,14 @@ unit example.atoi_codec
68
75
  itoa :: Int32 -> Text
69
76
  atoi :: Text -> Int32
70
77
 
71
- law `round trip` is
72
- definition is
73
- `left inverse` atoi itoa
78
+ law "|round trip| is
79
+ definition :
80
+ apply law "|left inverse| atoi itoa
74
81
  end
75
- description is
82
+ description :
76
83
  "applying {itoa} and then {atoi} recovers the original integer"
77
84
  end
78
- example `negative integers use a minus sign and round-trip unchanged` is
85
+ example "|negative integers use a minus sign and round-trip unchanged| :
79
86
  x = -42
80
87
  expect itoa x = "-42"
81
88
  expect atoi (itoa x) = -42
@@ -0,0 +1,39 @@
1
+ UNICODE LICENSE V3
2
+
3
+ COPYRIGHT AND PERMISSION NOTICE
4
+
5
+ Copyright © 1991-2026 Unicode, Inc.
6
+
7
+ NOTICE TO USER: Carefully read the following legal agreement. BY
8
+ DOWNLOADING, INSTALLING, COPYING OR OTHERWISE USING DATA FILES, AND/OR
9
+ SOFTWARE, YOU UNEQUIVOCALLY ACCEPT, AND AGREE TO BE BOUND BY, ALL OF THE
10
+ TERMS AND CONDITIONS OF THIS AGREEMENT. IF YOU DO NOT AGREE, DO NOT
11
+ DOWNLOAD, INSTALL, COPY, DISTRIBUTE OR USE THE DATA FILES OR SOFTWARE.
12
+
13
+ Permission is hereby granted, free of charge, to any person obtaining a
14
+ copy of data files and any associated documentation (the "Data Files") or
15
+ software and any associated documentation (the "Software") to deal in the
16
+ Data Files or Software without restriction, including without limitation
17
+ the rights to use, copy, modify, merge, publish, distribute, and/or sell
18
+ copies of the Data Files or Software, and to permit persons to whom the
19
+ Data Files or Software are furnished to do so, provided that either (a)
20
+ this copyright and permission notice appear with all copies of the Data
21
+ Files or Software, or (b) this copyright and permission notice appear in
22
+ associated Documentation.
23
+
24
+ THE DATA FILES AND SOFTWARE ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
25
+ KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
26
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF
27
+ THIRD PARTY RIGHTS.
28
+
29
+ IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE
30
+ BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES,
31
+ OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
32
+ WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
33
+ ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE DATA
34
+ FILES OR SOFTWARE.
35
+
36
+ Except as contained in this notice, the name of a copyright holder shall
37
+ not be used in advertising or otherwise to promote the sale, use or other
38
+ dealings in these Data Files or Software without prior written
39
+ authorization of the copyright holder.
package/api.mjs CHANGED
@@ -4,29 +4,20 @@ import {loadCore} from './launcher.mjs';
4
4
  export async function createCompiler() {
5
5
  const call = await loadCore();
6
6
  return {
7
- check: (input) =>
8
- call(
9
- {
10
- schemaVersion: input.nativeBindings === undefined ? 3 : 4,
11
- ...input,
12
- method: 'check',
13
- }
14
- ),
15
- expand: (input) =>
16
- call(
17
- {
18
- schemaVersion: input.nativeBindings === undefined ? 3 : 4,
19
- ...input,
20
- method: 'expand',
21
- }
22
- ),
7
+ format: (input) => call({schemaVersion: 5, ...input, method: 'format'}),
8
+ check: (input) => call({schemaVersion: 5, ...input, method: 'check'}),
9
+ expand: (input) => call({schemaVersion: 5, ...input, method: 'expand'}),
10
+ proofTasks: (input) =>
11
+ call({schemaVersion: 5, ...input, method: 'proofTasks'}),
23
12
  planGeneration: (input) =>
24
- call(
25
- {
26
- schemaVersion: input.nativeBindings === undefined ? 3 : 4,
27
- ...input,
28
- method: 'planGeneration',
29
- }
30
- ),
13
+ call({schemaVersion: 5, ...input, method: 'planGeneration'}),
14
+ migrationBaseline: (input) =>
15
+ call({schemaVersion: 5, ...input, method: 'migrationBaseline'}),
16
+ migrationComparison: (input) =>
17
+ call({schemaVersion: 5, ...input, method: 'migrationComparison'}),
18
+ migrationBindings: (input) =>
19
+ call({schemaVersion: 5, ...input, method: 'migrationBindings'}),
20
+ migrationGeneration: (input) =>
21
+ call({schemaVersion: 5, ...input, method: 'migrationGeneration'}),
31
22
  };
32
23
  }