lawspec 0.15.0 → 0.15.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +532 -0
- package/README.md +60 -741
- package/api.mjs +1 -1
- package/bin/lawspec.mjs +4 -2
- package/build.json +25 -27
- package/core.wasm +0 -0
- package/doctor.mjs +1 -0
- package/examples-command.mjs +1 -0
- package/files.mjs +1 -0
- package/index.d.ts +1 -1
- package/launcher.mjs +26 -16
- package/native-examples.mjs +1 -0
- package/package.json +33 -6
- package/read-only-hpack.mjs +1 -0
- package/scalars.mjs +1 -0
- package/templates.mjs +112 -219
- package/API-MIGRATION.md +0 -339
- package/GO.md +0 -144
- package/HASKELL.md +0 -172
- package/JAVA.md +0 -113
- package/KOTLIN.md +0 -219
- package/LANGUAGE.md +0 -692
- package/NATIVE-BINDINGS.md +0 -1051
- package/PRIMITIVES.md +0 -150
- package/PYTHON.md +0 -152
- package/REFINEMENTS.md +0 -449
- package/RELEASE-0.10.md +0 -60
- package/RELEASE-0.11.md +0 -62
- package/RELEASE-0.12.md +0 -47
- package/RELEASE-0.13.md +0 -97
- package/RELEASE-0.14.md +0 -52
- package/RELEASE-0.15.md +0 -44
- package/RELEASE-0.9.md +0 -61
- package/RUST.md +0 -211
- package/WEB.md +0 -144
package/RELEASE-0.13.md
DELETED
|
@@ -1,97 +0,0 @@
|
|
|
1
|
-
# LawSpec 0.13
|
|
2
|
-
|
|
3
|
-
## 0.13.2
|
|
4
|
-
|
|
5
|
-
A maintenance release. The language, generated code and API are unchanged.
|
|
6
|
-
|
|
7
|
-
- The repository has no hosted CI. `stack run lawspec-dev -- ci` runs the
|
|
8
|
-
complete check locally: compiler, npm, parity, package and editor checks, then
|
|
9
|
-
for each target the dependency bootstrap, every acceptance suite in both
|
|
10
|
-
machine profiles, and the installed native-binding example. It logs each step to
|
|
11
|
-
`.artifacts/ci/` and exits non-zero on any failure. `--target`, `--core`,
|
|
12
|
-
`--fail-fast`, `--rust-toolchains` and `--rust-targets` select what to run.
|
|
13
|
-
`make ci` is equivalent.
|
|
14
|
-
- The JavaScript acceptance runners and fixture modules replaced by
|
|
15
|
-
`lawspec-acceptance` are removed.
|
|
16
|
-
- The package smoke test's per-command timeout is ten minutes: exporting every
|
|
17
|
-
bundled example had exceeded the former two-minute limit on slower machines.
|
|
18
|
-
- The integration bootstrap restores missing scaffold files in existing projects.
|
|
19
|
-
|
|
20
|
-
## 0.13.1
|
|
21
|
-
|
|
22
|
-
A maintenance release. The language, generated code and API are unchanged from
|
|
23
|
-
0.13.0.
|
|
24
|
-
|
|
25
|
-
- Repository checks move from JavaScript to Haskell. `lawspec-dev boundaries` and
|
|
26
|
-
`lawspec-dev integrity` replace `tools/check-boundaries.mjs` and
|
|
27
|
-
`tools/build-integrity.mjs`. The integrity check now also rejects staged npm
|
|
28
|
-
copies of documentation and examples that differ from their sources.
|
|
29
|
-
- `lawspec-acceptance` runs the bundled-example acceptance suites
|
|
30
|
-
(`integration`, `algebra`, `scalar`, `refinement`, `indexed`, `domain`) in
|
|
31
|
-
process. Adapters and mutants are real files under `acceptance/`, and a
|
|
32
|
-
mutant that only breaks the build now fails the suite. This exposed a
|
|
33
|
-
TypeScript scalar mutant that previously counted as rejected because it
|
|
34
|
-
failed type-checking; it now exercises the laws. The JavaScript runners
|
|
35
|
-
continue to run alongside it in CI.
|
|
36
|
-
- Build-file scaffolds are defined once in Haskell (`LawSpec.Scaffold`) and
|
|
37
|
-
checked against the npm templates byte for byte.
|
|
38
|
-
- Compiler API contract tests formerly in `npm/test` run in hspec against the
|
|
39
|
-
same JSON boundary that `core.wasm` exports. A new npm test checks that
|
|
40
|
-
generation never rewrites build files and that regeneration is a no-op on
|
|
41
|
-
every target.
|
|
42
|
-
|
|
43
|
-
## 0.13.0
|
|
44
|
-
|
|
45
|
-
### Wrappers and constrained primitives
|
|
46
|
-
|
|
47
|
-
```lawspec
|
|
48
|
-
wrapper UnitQuantity is Int32 where value >= 1 && value <= 1000 end
|
|
49
|
-
wrapper NonEmptyList (a :: Type) is List a where prelude.length value > 0 end
|
|
50
|
-
```
|
|
51
|
-
|
|
52
|
-
A wrapper declares a distinct nominal type with one field, `value`, and an
|
|
53
|
-
optional constraint. Its constructor checks the constraint, so an invalid value
|
|
54
|
-
cannot be constructed in an example (the compiler rejects `UnitQuantity 0`),
|
|
55
|
-
produced by a generator, or decoded from native code. `valueOf<Name>` unwraps a
|
|
56
|
-
value. Wrappers may take type parameters. They elaborate to a single-constructor
|
|
57
|
-
product with a refined field, so all eight targets represent them natively with
|
|
58
|
-
no new runtime machinery.
|
|
59
|
-
|
|
60
|
-
### Workflows and state distinctions
|
|
61
|
-
|
|
62
|
-
```lawspec
|
|
63
|
-
workflow placeOrder :: UnvalidatedOrder -> Either OrderError PricedOrder is
|
|
64
|
-
validateOrder :: UnvalidatedOrder -> Either OrderError ValidatedOrder
|
|
65
|
-
priceOrder :: ValidatedOrder -> Either OrderError PricedOrder
|
|
66
|
-
end
|
|
67
|
-
```
|
|
68
|
-
|
|
69
|
-
A workflow declares its steps as adapters and checks the pipeline: each step
|
|
70
|
-
must accept the previous step's state, and fallible steps must share an error
|
|
71
|
-
type. The workflow's result must match `Either E T` when any step can fail, or
|
|
72
|
-
`T` otherwise. The compiler adds the law `placeOrder composes its steps`: the
|
|
73
|
-
native workflow must equal the railway composition of the native steps.
|
|
74
|
-
Diagnostics name the step and the mismatched types, with the workflow's source
|
|
75
|
-
location.
|
|
76
|
-
|
|
77
|
-
### Evidence
|
|
78
|
-
|
|
79
|
-
Constructor field constraints, including wrapper constraints, appear in the
|
|
80
|
-
evidence as `construction` obligations with status `runtime-checked`, next to
|
|
81
|
-
the contract obligations introduced in 0.12. The TypeScript API declares these
|
|
82
|
-
records as `ObligationEvidence`; the 0.12 typing was not published.
|
|
83
|
-
|
|
84
|
-
### Examples and acceptance
|
|
85
|
-
|
|
86
|
-
`examples/specs/domain_modeling.lawspec` combines wrappers, a parameterized
|
|
87
|
-
`NonEmptyList`, order states and the workflow. `tools/domain-integration.mjs`
|
|
88
|
-
runs it on all eight targets in both machine profiles. Correct adapters pass;
|
|
89
|
-
mutants that break a wrapper invariant, the railway composition, or a non-empty
|
|
90
|
-
list operation fail. The example runners now share
|
|
91
|
-
`tools/example-acceptance.mjs`.
|
|
92
|
-
|
|
93
|
-
### Compatibility
|
|
94
|
-
|
|
95
|
-
`wrapper` and `workflow` begin new declarations. Specifications that do not use
|
|
96
|
-
them compile as in 0.12. API schemas 3 and 4 are unchanged, apart from the
|
|
97
|
-
additive `construction` stage in `evidence`.
|
package/RELEASE-0.14.md
DELETED
|
@@ -1,52 +0,0 @@
|
|
|
1
|
-
# LawSpec 0.14
|
|
2
|
-
|
|
3
|
-
## 0.14.0
|
|
4
|
-
|
|
5
|
-
### Imports
|
|
6
|
-
|
|
7
|
-
```lawspec
|
|
8
|
-
unit shop.orders
|
|
9
|
-
import shop.domain as domain (Money, Cents, `commutative`)
|
|
10
|
-
```
|
|
11
|
-
|
|
12
|
-
A unit imports other units by name. Every declaration of an imported unit is
|
|
13
|
-
available through the alias (`domain.Usd`, `domain.centsOf`), and listed names
|
|
14
|
-
also unqualified. Types, wrappers, indexed families, refinements, checked
|
|
15
|
-
definitions and generic laws can be imported. Adapters and concrete laws stay
|
|
16
|
-
with their unit. Import cycles, unknown units and missing or ambiguous names are
|
|
17
|
-
reported at the import, with the reason: an adapter, a constructor listed
|
|
18
|
-
without its type, or a law without parameters.
|
|
19
|
-
|
|
20
|
-
Names are scoped to their unit, so units compiled together no longer need
|
|
21
|
-
distinct constructor names. Targets with one data namespace (Python,
|
|
22
|
-
JavaScript, TypeScript, Go and Haskell) name colliding types after their unit,
|
|
23
|
-
`ShopDomainCurrency` and `ShopOrdersCurrency`, and their constructors
|
|
24
|
-
`ShopDomainCurrencyUsd`. Java, Kotlin and Rust qualify only the type. Earlier
|
|
25
|
-
versions qualified only the colliding names, for example
|
|
26
|
-
`ShopDomainTypeCurrencyUsd` next to `CurrencyEur`.
|
|
27
|
-
|
|
28
|
-
Imports are resolved before type checking, like indexed families and domain
|
|
29
|
-
models, so Core and the eight backends are unchanged.
|
|
30
|
-
|
|
31
|
-
### Packages
|
|
32
|
-
|
|
33
|
-
A `lawspec-package.json` names a package, its version, its source directories
|
|
34
|
-
and the version ranges of its dependencies. Package units are named after the
|
|
35
|
-
package, a unit imports only from its own package and direct dependencies, and
|
|
36
|
-
every range must accept the supplied version. A project lists `dependencies` and
|
|
37
|
-
the `packages` directories in `lawspec.json`. A package's adapters and laws are a
|
|
38
|
-
published contract: dependent projects implement and test them as their own.
|
|
39
|
-
`lawspec package` checks a package and summarizes it.
|
|
40
|
-
|
|
41
|
-
The compiler API accepts `dependencies`, `packages` and `package`, and reports
|
|
42
|
-
the resolved packages (see [API migration](API-MIGRATION.md#imports-and-packages-014)).
|
|
43
|
-
|
|
44
|
-
### Other changes
|
|
45
|
-
|
|
46
|
-
- Rust: a law without quantified inputs no longer emits an untyped empty case
|
|
47
|
-
vector, which did not compile.
|
|
48
|
-
- The VS Code grammar highlights `import` and `as`.
|
|
49
|
-
- A new acceptance suite, `packages`, runs the
|
|
50
|
-
[package example](examples/packages) on all eight targets in both machine
|
|
51
|
-
profiles and rejects five adapter mutants plus the bare stubs. `lawspec-dev ci`
|
|
52
|
-
includes it.
|
package/RELEASE-0.15.md
DELETED
|
@@ -1,44 +0,0 @@
|
|
|
1
|
-
# LawSpec 0.15
|
|
2
|
-
|
|
3
|
-
## 0.15.0
|
|
4
|
-
|
|
5
|
-
### Evidence and discharge
|
|
6
|
-
|
|
7
|
-
Every obligation of a program reports how it is discharged, strongest first:
|
|
8
|
-
|
|
9
|
-
- `proved`: statically. Definition postconditions and indices, as since 0.12,
|
|
10
|
-
and now laws that call only checked definitions.
|
|
11
|
-
- `exhaustively-checked`: every input of a finite domain, by the compiler for
|
|
12
|
-
laws over checked definitions and otherwise by the generated tests. A law with
|
|
13
|
-
no inputs is a single case.
|
|
14
|
-
- `property-tested`: generated cases, boundary cases and examples.
|
|
15
|
-
- `runtime-checked`: adapter contracts, definition preconditions, constructor
|
|
16
|
-
constraints and native type bindings, at every native boundary.
|
|
17
|
-
- `assumed`: adapters, native functions, custom generators and codec hooks,
|
|
18
|
-
taken on trust. Each adapter reports how many laws call it, or that none does.
|
|
19
|
-
|
|
20
|
-
`lawspec check` summarizes the obligations by status, and the new
|
|
21
|
-
`lawspec evidence` lists each with its claim and reason (`--json` for the API
|
|
22
|
-
records, and a unit or `unit::declaration` filter).
|
|
23
|
-
|
|
24
|
-
### Laws proved and refuted by the compiler
|
|
25
|
-
|
|
26
|
-
A law over checked definitions is attempted as a proof by the same exact linear
|
|
27
|
-
arithmetic that proves definition results, from its input refinements, with
|
|
28
|
-
definitions that have no preconditions unfolded into the claim. When it is not
|
|
29
|
-
proved and its domain is finite, the compiler evaluates every input; a
|
|
30
|
-
counterexample is a compile error with code `refuted`, such as
|
|
31
|
-
`law always positive is false for x = -128`. Specifications that compiled
|
|
32
|
-
before may therefore be rejected if a law over definitions is false.
|
|
33
|
-
|
|
34
|
-
The prover also handles constant factors on integer expressions (`x * 2`),
|
|
35
|
-
which it previously treated as non-linear, so more definition results are
|
|
36
|
-
proved.
|
|
37
|
-
|
|
38
|
-
### API
|
|
39
|
-
|
|
40
|
-
`evidence` items have the five statuses above and new stages: `law`,
|
|
41
|
-
`adapter`, and, with native bindings, `binding`, `codec`, `generator` and
|
|
42
|
-
`native-function`. `claim` is `null` for obligations without one. The
|
|
43
|
-
TypeScript API declares `ObligationEvidence` and `DischargeStatus`. See
|
|
44
|
-
[API migration](API-MIGRATION.md#evidence-and-discharge-015).
|
package/RELEASE-0.9.md
DELETED
|
@@ -1,61 +0,0 @@
|
|
|
1
|
-
# LawSpec 0.9.0
|
|
2
|
-
|
|
3
|
-
This release adds structural data and checked total definitions across Java,
|
|
4
|
-
Python, JavaScript, TypeScript, Go, Haskell, Kotlin, and Rust.
|
|
5
|
-
|
|
6
|
-
## Language
|
|
7
|
-
|
|
8
|
-
- `List a` supports nested contextual literals, structural equality, exact
|
|
9
|
-
length, deterministic boundaries, and native framework generation/shrinking.
|
|
10
|
-
- Algebraic `Maybe a` and `Either a b` provide `Nothing`/`Just` and `Left`/`Right`.
|
|
11
|
-
They remain distinct from interoperability `Nullable` and `Optional` values.
|
|
12
|
-
- Named parameterized products and sums have constructors and ordered fields.
|
|
13
|
-
Generated native types and typed adapters preserve their structure.
|
|
14
|
-
- Total definitions support exhaustive matching and checked structural recursion.
|
|
15
|
-
The compiler rejects partial matches and recursion it cannot establish as
|
|
16
|
-
terminating. Generic definitions specialize to their concrete uses.
|
|
17
|
-
- Refined definition signatures become executable native contracts. Scoped
|
|
18
|
-
payload predicates preserve type-parameter roles through recursive and mutual
|
|
19
|
-
data declarations, including predicates that depend on preceding inputs.
|
|
20
|
-
|
|
21
|
-
Existing scalar semantics remain intact: exact arithmetic does not wrap,
|
|
22
|
-
conversions to bounded adapter parameters are checked, floating equality follows
|
|
23
|
-
IEEE rules, and Symbol equality uses identity.
|
|
24
|
-
|
|
25
|
-
## Generated output
|
|
26
|
-
|
|
27
|
-
Readable code is the default for runtimes, declarations, definitions, adapters,
|
|
28
|
-
tests, and scaffolds. Explicit `--minify` selects compact output for `init`,
|
|
29
|
-
`generate`, and `examples`; the compiler API accepts `minify: true`.
|
|
30
|
-
|
|
31
|
-
Output follows Google language-specific guidance where applicable, PEP 8 for
|
|
32
|
-
Python, standard Go and Rust formatting, and an 80-column Haskell layout.
|
|
33
|
-
Formatting is deterministic in both native and WASM compilation and requires
|
|
34
|
-
no formatter download. Compact output preserves required layout, literal
|
|
35
|
-
contents, and semantics. Changing formatting mode does not overwrite edited
|
|
36
|
-
adapters or create false adapter-signature updates.
|
|
37
|
-
|
|
38
|
-
## API and compatibility
|
|
39
|
-
|
|
40
|
-
API schema 3 adds named data declarations, structural values, checked definitions,
|
|
41
|
-
construction/matching expressions, and scoped payload predicates. Existing scalar
|
|
42
|
-
wire encodings are unchanged. Exhaustive expression visitors must handle the
|
|
43
|
-
new variants; see [API migration](API-MIGRATION.md).
|
|
44
|
-
|
|
45
|
-
Java 25+, Python 3.13+, Node 22+, and Rust 1.85+ baselines remain unchanged.
|
|
46
|
-
Machine-width profiles, custom source/test directories, generation manifests,
|
|
47
|
-
and user ownership of adapters/build files remain supported. Framework-specific
|
|
48
|
-
strategies stay separate from reusable runtime source.
|
|
49
|
-
|
|
50
|
-
GADTs, indexed families, and general dependent types remain future work. See
|
|
51
|
-
[the language reference](LANGUAGE.md) and the target guides for native type
|
|
52
|
-
representations and framework-specific refinement/shrinking limits.
|
|
53
|
-
|
|
54
|
-
## Examples and release acceptance
|
|
55
|
-
|
|
56
|
-
Bundled examples cover reverse involution, sorting idempotence/sortedness/length/
|
|
57
|
-
permutation, nested presence, products/sums, exhaustive matches, total functions,
|
|
58
|
-
and recursive payload refinements. Release acceptance includes compiler and
|
|
59
|
-
native/WASM checks, native execution on all eight targets, deliberately incorrect
|
|
60
|
-
adapters, independent formatting/syntax checks, regeneration protection, and
|
|
61
|
-
installation of the packed npm artifact. Publication is a separate step.
|
package/RUST.md
DELETED
|
@@ -1,211 +0,0 @@
|
|
|
1
|
-
# Rust backend
|
|
2
|
-
|
|
3
|
-
Rust is the first backend built on LawSpec's typed core and testing plan. The
|
|
4
|
-
compiler remains implemented in Haskell. Rust generation does not parse source
|
|
5
|
-
expressions, infer their types, or expand refinement declarations.
|
|
6
|
-
|
|
7
|
-
## Project setup
|
|
8
|
-
|
|
9
|
-
Use Rust 1.85 or later, edition 2024, and Cargo. The generated project pins
|
|
10
|
-
Proptest 1.11.0, num-bigint 0.4.8, num-rational 0.4.2, num-complex 0.4.6, and
|
|
11
|
-
num-traits 0.2.19.
|
|
12
|
-
|
|
13
|
-
```sh
|
|
14
|
-
lawspec init --target rust
|
|
15
|
-
lawspec doctor
|
|
16
|
-
lawspec generate
|
|
17
|
-
cargo test
|
|
18
|
-
cargo test --release
|
|
19
|
-
```
|
|
20
|
-
|
|
21
|
-
Adapters are user-owned files under `src/`. LawSpec maintains
|
|
22
|
-
`lawspec_runtime.rs`, module declarations in `lawspec_modules.rs`, and tests
|
|
23
|
-
under `tests/`. The scaffolded `src/lib.rs` includes the generated declarations;
|
|
24
|
-
an existing library can include those declarations explicitly. Generation
|
|
25
|
-
preserves edited adapters and reports required signature updates.
|
|
26
|
-
|
|
27
|
-
The numeric runtime has no Proptest dependency. Framework support lives in a
|
|
28
|
-
separate generated file, `tests/support/lawspec_strategies.rs`.
|
|
29
|
-
|
|
30
|
-
## Total definitions (0.9)
|
|
31
|
-
|
|
32
|
-
Unit-level definitions supply executable implementations alongside laws:
|
|
33
|
-
|
|
34
|
-
```lawspec
|
|
35
|
-
unit example.total
|
|
36
|
-
|
|
37
|
-
definition size (xs :: List Int8) :: BigInt is
|
|
38
|
-
match xs with
|
|
39
|
-
| Nil -> 0
|
|
40
|
-
| Cons head tail -> 1 + size tail
|
|
41
|
-
end
|
|
42
|
-
end
|
|
43
|
-
```
|
|
44
|
-
|
|
45
|
-
The compiler checks types, exhaustive matching, structural termination, and
|
|
46
|
-
potentially failing operations before emission. Definitions may call other
|
|
47
|
-
checked definitions, including forward references; they cannot call adapters.
|
|
48
|
-
Generic definitions specialize to concrete uses. Refinement predicates may call
|
|
49
|
-
checked definitions. Refined definition signatures become checked native contracts.
|
|
50
|
-
|
|
51
|
-
Rust emits their implementations into the generated source file
|
|
52
|
-
`lawspec_definitions.rs`. They are not user-owned adapter stubs. Typed native
|
|
53
|
-
entry points are grouped by unit, for example:
|
|
54
|
-
|
|
55
|
-
```rust
|
|
56
|
-
let mut context = lawspec_runtime::Context::default();
|
|
57
|
-
let count = lawspec_definitions::example_total::size(&mut context, vec![1, 2, 3])?;
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
These entry points return `lawspec_runtime::Result<T>` and check native values
|
|
61
|
-
at the boundary. Share the context when Symbol fixture identities must match.
|
|
62
|
-
Native machine-sized bindings check the architecture, including fields in
|
|
63
|
-
unselected data variants. The implementation has no Proptest dependency and can
|
|
64
|
-
be used by the application library. Generated properties invoke the same checked
|
|
65
|
-
implementation; remaining external declarations still receive adapter stubs.
|
|
66
|
-
|
|
67
|
-
`tools/rust-definitions-integration.mjs` verifies both machine profiles, custom
|
|
68
|
-
source/test roots, native calls, readable and compact source, exact `rustfmt`
|
|
69
|
-
layout, incorrect adapters, and regeneration ownership.
|
|
70
|
-
|
|
71
|
-
## Formatting (0.9)
|
|
72
|
-
|
|
73
|
-
Rust source uses four-space indentation and structured line wrapping. Request
|
|
74
|
-
compact layout explicitly with `lawspec generate --minify`, or `minify: true`
|
|
75
|
-
in the compiler API. The mode is not saved in project configuration. Formatting
|
|
76
|
-
switches preserve user-owned adapters and their canonical interface references.
|
|
77
|
-
|
|
78
|
-
`tools/rust-formatting-integration.mjs` compares all Rust artifacts generated
|
|
79
|
-
from the bundled examples and the total-definition fixture against rustfmt,
|
|
80
|
-
under both machine profiles. Formatting is implemented in the compiler; generated
|
|
81
|
-
projects do not need rustfmt to run. The bundled WASM uses the same layout.
|
|
82
|
-
|
|
83
|
-
## Owned adapter values
|
|
84
|
-
|
|
85
|
-
Arguments and results are owned Rust values. LawSpec does not add borrowing,
|
|
86
|
-
lifetimes, or pointer operations to its language. Tests clone values where an
|
|
87
|
-
expression needs to use an input more than once.
|
|
88
|
-
|
|
89
|
-
| LawSpec domain | Rust adapter representation |
|
|
90
|
-
| --- | --- |
|
|
91
|
-
| `Bool` | `bool` |
|
|
92
|
-
| Fixed signed/unsigned integers | `i8`…`i64`, `u8`…`u64` |
|
|
93
|
-
| `IntSize`, `UIntSize`, `UIntPtr` | `isize`, `usize`, `usize` |
|
|
94
|
-
| `BigInt`, `BigUInt` | `BigInt`, `BigUint` |
|
|
95
|
-
| `Integer` input | `BigInt` |
|
|
96
|
-
| `Integer` result | `Integer`, with lossless `From` implementations |
|
|
97
|
-
| `Decimal`, `Rational` | Generated `Decimal`, `BigRational` |
|
|
98
|
-
| `Float32`, `Float64` | `f32`, `f64` |
|
|
99
|
-
| `Complex64`, `Complex128` | `Complex32`, `Complex64` from num-complex |
|
|
100
|
-
| `Char`, `Text` | `char`, `String` |
|
|
101
|
-
| `CodePoint`, `CodePointText` | Generated checked wrappers |
|
|
102
|
-
| `CodeUnit16`, `Utf16Text`, `Bytes` | `u16`, generated UTF-16 wrapper, `Vec<u8>` |
|
|
103
|
-
| `Symbol` | Generated identity type; cloning preserves identity |
|
|
104
|
-
| `Unit`, `Null`, `Undefined` | `()`, distinct generated absence types |
|
|
105
|
-
| `Nullable a`, `Optional a` | Distinct generated enums, including nested presence |
|
|
106
|
-
| `List a` | `Vec<A>` |
|
|
107
|
-
| `Maybe a` | `Option<A>` |
|
|
108
|
-
| `Either a b` | Generated `Either<A, B>` |
|
|
109
|
-
| User-defined products and sums | Named generic enums in `lawspec_data` |
|
|
110
|
-
|
|
111
|
-
Names such as `Integer` and `Decimal` above are exported by the generated
|
|
112
|
-
`lawspec_runtime` module. Machine-sized native bindings check the requested
|
|
113
|
-
`machineBits` against the executing architecture.
|
|
114
|
-
|
|
115
|
-
For a declaration such as `successor :: Int8 -> Integer`, an implementation can
|
|
116
|
-
return a wider native integer through the logical result wrapper:
|
|
117
|
-
|
|
118
|
-
```rust
|
|
119
|
-
use crate::lawspec_runtime as ls;
|
|
120
|
-
|
|
121
|
-
pub fn successor(value: i8) -> ls::Integer {
|
|
122
|
-
(i16::from(value) + 1).into()
|
|
123
|
-
}
|
|
124
|
-
```
|
|
125
|
-
|
|
126
|
-
Exact arithmetic in laws uses arbitrary precision. Passing its result to an
|
|
127
|
-
`i8` adapter parameter performs a checked conversion. A fractional or
|
|
128
|
-
out-of-range value fails with the adapter's context.
|
|
129
|
-
|
|
130
|
-
`Decimal` stores an arbitrary integer coefficient and exponent. Decimal
|
|
131
|
-
arithmetic is exact; explicit rounding uses the requested scale and ties to
|
|
132
|
-
even. Exact-to-float conversion rounds directly to the requested IEEE precision,
|
|
133
|
-
including subnormal and halfway cases.
|
|
134
|
-
|
|
135
|
-
## Native data declarations
|
|
136
|
-
|
|
137
|
-
User-defined data emits reusable `lawspec_data.rs` and `lawspec_schema.rs` in the
|
|
138
|
-
source directory. Adapters receive native enum values with named, typed fields.
|
|
139
|
-
A product uses an enum with one record variant. Parameterized fields retain
|
|
140
|
-
Rust generic types; recursive fields use `Box` where an inline cycle requires
|
|
141
|
-
indirection, while `Vec` already supplies it. Mutually recursive declarations
|
|
142
|
-
are resolved together. When two units use the same type name, generated names
|
|
143
|
-
are qualified by their unit identities.
|
|
144
|
-
|
|
145
|
-
The runtime's `FromValue` and `IntoValue` traits provide conversion bridges.
|
|
146
|
-
Generated calls validate the complete logical value before conversion and the
|
|
147
|
-
native result before checking postconditions. This preserves raw UTF-16 units,
|
|
148
|
-
bytes, nested presence, and primitive range checks inside custom fields.
|
|
149
|
-
Machine-width checks also apply to machine integers inside custom data.
|
|
150
|
-
|
|
151
|
-
Generated enums derive `Clone` and `Debug`. LawSpec equality remains a runtime
|
|
152
|
-
operation: it compares fields structurally, retains IEEE NaN and signed-zero
|
|
153
|
-
rules, and compares Symbols by identity. It does not replace these rules with a
|
|
154
|
-
derived Rust `Eq` implementation.
|
|
155
|
-
|
|
156
|
-
Unused or exclusively recursive type parameters use a `PhantomData` marker.
|
|
157
|
-
Types with no constructors remain uninhabited; they do not acquire a synthetic
|
|
158
|
-
variant. Generated schemas and conversion support have no Proptest dependency.
|
|
159
|
-
The test support composes native Proptest strategies for recursive values and
|
|
160
|
-
shrinking, with deterministic boundary cases and finite-domain enumeration.
|
|
161
|
-
The structural budget counts each scalar, container, and constructor as one
|
|
162
|
-
node. Generation reserves every product field's minimum before distributing
|
|
163
|
-
remaining nodes. List length and element budgets vary together, so a deep
|
|
164
|
-
singleton remains reachable and lists have no hidden four-element limit.
|
|
165
|
-
Native shrinking preserves the schema and the structural budget.
|
|
166
|
-
|
|
167
|
-
## Refinements and generation
|
|
168
|
-
|
|
169
|
-
Small finite domains are enumerated. Larger domains use native Proptest
|
|
170
|
-
strategies. Integer bounds over earlier inputs become dependent strategies;
|
|
171
|
-
when a prefix has no possible continuation, generation retries the prefix.
|
|
172
|
-
Shrinking recomputes those dependent bounds and retains only valid tuples.
|
|
173
|
-
Refinement evaluation errors fail the test rather than being counted as rejected
|
|
174
|
-
samples. Generation limits prevent an empty or unreachable domain from passing
|
|
175
|
-
vacuously.
|
|
176
|
-
|
|
177
|
-
Contracts check preconditions, evaluate the adapter once, validate its native
|
|
178
|
-
result, and then check postconditions on that result.
|
|
179
|
-
|
|
180
|
-
## Custom layouts
|
|
181
|
-
|
|
182
|
-
`sourceDir` and `testDir` move generated sources and imports together. Set Cargo's
|
|
183
|
-
`[lib] path` to the library entry point under the selected source directory. For
|
|
184
|
-
test directories other than `tests`, register generated test files using Cargo
|
|
185
|
-
`[[test]]` entries. Doctor checks the selected Cargo package, edition, resolved
|
|
186
|
-
dependencies, library directory, and custom test registration.
|
|
187
|
-
|
|
188
|
-
Internal typed Core definitions with attached contracts are proved before Rust
|
|
189
|
-
emission. Generated source checks preconditions after argument validation and
|
|
190
|
-
postconditions after result validation, without property-framework dependencies.
|
|
191
|
-
Checks sequence through Result, preserving ordered predicates and contextual
|
|
192
|
-
failures. Native wrappers share logical enforcement. Readable contract bodies
|
|
193
|
-
match rustfmt exactly.
|
|
194
|
-
The shared native fixture passes both machine profiles and formatting modes,
|
|
195
|
-
including exact division, narrowing, nested calls, direct logical entry checks,
|
|
196
|
-
and rejection of corrupted results. Refined source definition signatures now
|
|
197
|
-
produce these contracts through template proof and specialization.
|
|
198
|
-
|
|
199
|
-
## Constructor field contracts
|
|
200
|
-
|
|
201
|
-
Rust checks constructor predicates at logical definition and native adapter
|
|
202
|
-
boundaries. Generated proptest strategies validate complete candidates, retain
|
|
203
|
-
native shrinking, and share each case's Symbol context with witness literals and
|
|
204
|
-
assertions. Only false predicates trigger retries; evaluation errors fail the
|
|
205
|
-
property. `maxAttempts` bounds local and global rejection, and exhaustion does
|
|
206
|
-
not prove an empty domain.
|
|
207
|
-
|
|
208
|
-
Validated witnesses seed nested payloads. Builtin lists and presence/sum
|
|
209
|
-
containers retain native structural shrinking; sampled named witnesses can
|
|
210
|
-
still produce larger counterexamples than native branches. Recursive named
|
|
211
|
-
refined payloads remain outside the currently supported contract fragment.
|
package/WEB.md
DELETED
|
@@ -1,144 +0,0 @@
|
|
|
1
|
-
# JavaScript and TypeScript backends
|
|
2
|
-
|
|
3
|
-
LawSpec emits ES modules. JavaScript uses `.mjs`; TypeScript uses `.ts` with `.js`
|
|
4
|
-
import paths for NodeNext compilation. Generated data and numeric support belong
|
|
5
|
-
in source directories and do not depend on fast-check. Generated properties use
|
|
6
|
-
fast-check's native generators and shrinkers.
|
|
7
|
-
|
|
8
|
-
## Native structural values
|
|
9
|
-
|
|
10
|
-
`List a` uses `Array<A>`. `Maybe a` and `Either a b` use named classes and, in
|
|
11
|
-
TypeScript, generic unions from `lawspec_data`. User products and sums likewise
|
|
12
|
-
have named native variant classes. TypeScript retains payload types and nominal
|
|
13
|
-
variant identity, including recursive fields and phantom parameters.
|
|
14
|
-
|
|
15
|
-
`Nullable a` and `Optional a` use tagged `data.Presence<A>` values, preserving
|
|
16
|
-
nested states separately from algebraic `Maybe`. Runtime checks enforce the
|
|
17
|
-
presence kind and payload domain. Scalar and structural presence values both use
|
|
18
|
-
the schema bridge when crossing native adapter boundaries.
|
|
19
|
-
|
|
20
|
-
Checked conversions copy containers, reject sparse arrays and invalid fields,
|
|
21
|
-
validate numeric ranges and machine profiles, and preserve raw text and bytes.
|
|
22
|
-
LawSpec equality follows the schema: NaN differs from itself, signed zeros compare
|
|
23
|
-
equal, and Symbols compare by identity. Ordinary JavaScript object equality is
|
|
24
|
-
not a replacement for structural LawSpec equality.
|
|
25
|
-
|
|
26
|
-
## Total definitions
|
|
27
|
-
|
|
28
|
-
Checked definitions produce reusable source functions:
|
|
29
|
-
|
|
30
|
-
```lawspec
|
|
31
|
-
unit example.total
|
|
32
|
-
|
|
33
|
-
definition increment (x :: Int8) :: BigInt is x + 1 end
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
```javascript
|
|
37
|
-
import {increment} from './lawspec_definitions/example/total.mjs';
|
|
38
|
-
|
|
39
|
-
const symbols = new Map();
|
|
40
|
-
const result = increment(symbols, 127); // 128n
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
The TypeScript entry point has `symbols: Map<string, symbol>`, `value0: number`,
|
|
44
|
-
and a `bigint` result. Native signatures preserve lists, products, sums, and
|
|
45
|
-
nested presence payloads. Runtime validation also rejects invalid number ranges,
|
|
46
|
-
fractional primitive inputs, and malformed values from JavaScript callers.
|
|
47
|
-
Failures identify the resolved definition.
|
|
48
|
-
|
|
49
|
-
The first argument shares Symbol fixture identity across calls within an example.
|
|
50
|
-
Equal descriptions in separate contexts do not create equal Symbols. Exact
|
|
51
|
-
integers use bigint; exact Decimal and Rational operations use the scalar runtime
|
|
52
|
-
without passing through Number arithmetic.
|
|
53
|
-
|
|
54
|
-
Public modules live under `lawspec_definitions/`, grouped by unit. Checked logical
|
|
55
|
-
bodies live in `lawspec_definition_bodies`. Both are generated-owned source.
|
|
56
|
-
Properties call the implementations directly; a definition never becomes an
|
|
57
|
-
adapter stub. Ordinary adapters remain user-owned. Support-module collisions and
|
|
58
|
-
bindings that shadow generated global access are rejected before output.
|
|
59
|
-
|
|
60
|
-
Definitions and properties share typed Core expression rendering. Match inputs
|
|
61
|
-
are evaluated once, only the selected branch runs, and Boolean guards
|
|
62
|
-
short-circuit. Totality validation checks structural descent and potentially
|
|
63
|
-
failing operations. Generic definitions specialize to concrete uses. Refined signatures become
|
|
64
|
-
checked contracts, and refinement predicates may call checked definitions.
|
|
65
|
-
|
|
66
|
-
## Formatting and verification
|
|
67
|
-
|
|
68
|
-
Definition output uses two-space blocks, four-space continuations, single-quoted
|
|
69
|
-
strings, and an 80-column layout. String tokens preserve escaped and raw payloads
|
|
70
|
-
in readable and compact modes. Compact mode removes optional document breaks.
|
|
71
|
-
The public `--minify` path covers runtime, declaration, definition, adapter, and
|
|
72
|
-
test artifacts. `tools/web-formatting-integration.mjs` checks the full bundled
|
|
73
|
-
corpus for formatting rules and readable/compact syntax-tree equivalence. It
|
|
74
|
-
records Prettier differences separately: Prettier's continuation layout is not
|
|
75
|
-
the Google four-space continuation rule used here.
|
|
76
|
-
|
|
77
|
-
`tools/web-definitions-integration.mjs` checks both targets and machine profiles,
|
|
78
|
-
strict TypeScript entry points and rejected assignments, source-only execution,
|
|
79
|
-
recursive properties, incorrect adapters, compact output, custom directories,
|
|
80
|
-
and regeneration protection. The implementation modules pass strict TypeScript
|
|
81
|
-
without `any` or `@ts-nocheck`. Existing schema and numeric runtime TypeScript
|
|
82
|
-
files still use `@ts-nocheck`; their public data declarations and definition
|
|
83
|
-
entry points are checked separately.
|
|
84
|
-
|
|
85
|
-
## Runtime source formatting
|
|
86
|
-
|
|
87
|
-
The checked-in JavaScript scalar runtime, schema runtime, and fast-check helpers
|
|
88
|
-
use two-space indentation, single quotes, and an 80-column target, formatted with
|
|
89
|
-
Prettier 3.6.2. `node tools/format-web-runtimes.mjs` checks these sources;
|
|
90
|
-
`--write` formats them. Set `LAWSPEC_PRETTIER` to the formatter's `index.mjs` when
|
|
91
|
-
it is not in `.artifacts/formatter-deps/prettier/`. This development tool never
|
|
92
|
-
runs in generated projects or during compiler requests.
|
|
93
|
-
|
|
94
|
-
Run `python3 tools/embed-runtimes.py` after runtime edits, then use `--check` to
|
|
95
|
-
verify that native/WASM source embedding is current. Both JavaScript and
|
|
96
|
-
TypeScript receive the reviewed runtime source, with the existing typed-schema
|
|
97
|
-
constructor annotation and module-extension adjustments for TypeScript.
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
Internal checked Core definition contracts now run at native and logical entry
|
|
101
|
-
points. Emission proves the obligations first; argument validation precedes
|
|
102
|
-
ordered preconditions, and result validation precedes postconditions. Contract
|
|
103
|
-
binders map explicitly to body inputs and the checked result. Refined source
|
|
104
|
-
signatures now produce these contracts through template proof and specialization.
|
|
105
|
-
|
|
106
|
-
`tools/portable-definition-contract-integration.mjs` exercises Python, JavaScript
|
|
107
|
-
and strict TypeScript with both machine profiles and layouts, without property
|
|
108
|
-
frameworks. It also verifies that deliberately corrupted results are rejected.
|
|
109
|
-
The fixture in `test/DefinitionContractFixture.hs` is shared with the JVM checks.
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
## Generated source style checks
|
|
113
|
-
|
|
114
|
-
JavaScript and TypeScript emitters use two-space blocks and four-space
|
|
115
|
-
continuations. The latter follows the [Google JavaScript line-wrapping guide](https://google.github.io/styleguide/jsguide.html#s4.5-line-wrapping).
|
|
116
|
-
Binary operators remain on the preceding line when an expression wraps.
|
|
117
|
-
Generated adapter error messages and tagged scalar values use the shared
|
|
118
|
-
single-quoted JavaScript literal renderer.
|
|
119
|
-
|
|
120
|
-
`tools/web-formatting-integration.mjs` independently parses both output modes
|
|
121
|
-
with TypeScript, compares their syntax trees and literal contents, and checks
|
|
122
|
-
quote choice, binary-operator breaks, continuation and statement-block indentation,
|
|
123
|
-
the 80-column limit, tabs, and trailing
|
|
124
|
-
whitespace. Module imports/re-exports and indivisible source excerpts on their
|
|
125
|
-
own comment line are explicit column exceptions. Ordinary prose and code remain
|
|
126
|
-
subject to the limit. Long scalar string values use escaped concatenated chunks;
|
|
127
|
-
property names remain single tokens. It runs
|
|
128
|
-
both machine profiles for the bundled examples and total-definition fixture.
|
|
129
|
-
Set `LAWSPEC_CORE` to the native compiler; optional `LAWSPEC_TYPESCRIPT` and
|
|
130
|
-
`LAWSPEC_PRETTIER` paths select the cached development tools. Prettier must be
|
|
131
|
-
version 3.6.2. Positional arguments select specification files.
|
|
132
|
-
|
|
133
|
-
Prettier differences are saved for inspection, not treated as an exact Google
|
|
134
|
-
style oracle: its continuation indentation differs from Google's. These checks
|
|
135
|
-
are partial style evidence. Additional indentation cases (such as switch bodies
|
|
136
|
-
and type declarations) and Kotlin formatter acceptance remain tracked in the 0.9 plan; passing this script alone does not
|
|
137
|
-
establish complete style conformance.
|
|
138
|
-
|
|
139
|
-
The development-only runtime formatter (`tools/format-web-runtimes.mjs`) applies
|
|
140
|
-
Prettier layout and then syntax-tree-directed continuation indentation. It verifies
|
|
141
|
-
that JavaScript tokens remain unchanged, retains relative callback block indentation,
|
|
142
|
-
and rejects adjustments inside multiline template literals. It is idempotent and
|
|
143
|
-
checks the resulting 80-column limit. Reviewed runtime source is embedded at build
|
|
144
|
-
time; generated projects never download or invoke these development tools.
|