lawspec 0.14.0 → 0.15.1
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 +501 -0
- package/README.md +60 -728
- package/api.mjs +1 -1
- package/bin/lawspec.mjs +46 -6
- package/build.json +18 -18
- 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 +18 -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 -320
- package/GO.md +0 -144
- package/HASKELL.md +0 -172
- package/JAVA.md +0 -113
- package/KOTLIN.md +0 -219
- package/LANGUAGE.md +0 -646
- 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.9.md +0 -61
- package/RUST.md +0 -211
- package/WEB.md +0 -144
package/PRIMITIVES.md
DELETED
|
@@ -1,150 +0,0 @@
|
|
|
1
|
-
# LawSpec scalar reference (0.14.0)
|
|
2
|
-
|
|
3
|
-
A scalar has a declared domain, checked literals, equality, property inputs, and
|
|
4
|
-
boundary fixtures. General collections, objects, pointers, and type-only constructs
|
|
5
|
-
such as `never` are outside this release.
|
|
6
|
-
|
|
7
|
-
| Domain | Types | Representation and equality |
|
|
8
|
-
| --- | --- | --- |
|
|
9
|
-
| Boolean | `Bool` | `true` or `false`; distinct from integers |
|
|
10
|
-
| Signed integers | `Int8`, `Int16`, `Int32`, `Int64` | −2^(bits−1) through 2^(bits−1)−1 |
|
|
11
|
-
| Unsigned integers | `UInt8`, `UInt16`, `UInt32`, `UInt64` | 0 through 2^bits−1 |
|
|
12
|
-
| Machine integers | `IntSize`, `UIntSize`, `UIntPtr` | Explicit 32- or 64-bit profile; no pointer operations |
|
|
13
|
-
| Abstract integers | `Integer` | Exact mathematical values, independent of storage width |
|
|
14
|
-
| Arbitrary integers | `BigInt`, `BigUInt` | Unbounded integer; BigUInt is nonnegative |
|
|
15
|
-
| Exact fractions | `Decimal`, `Rational` | Finite coefficient × 10^exponent; reduced numerator / positive denominator |
|
|
16
|
-
| Floating point | `Float32`, `Float64` | IEEE binary32 / binary64; NaN differs from itself, signed zeros compare equal |
|
|
17
|
-
| Complex | `Complex64`, `Complex128` | Two Float32 / Float64 components; componentwise IEEE equality |
|
|
18
|
-
| Characters | `Char`, `CodePoint`, `CodeUnit16` | Unicode scalar; code point including surrogates; arbitrary 16-bit unit |
|
|
19
|
-
| Sequences | `Text`, `CodePointText`, `Utf16Text`, `Bytes` | Unicode scalars; code points; UTF-16 units; octets |
|
|
20
|
-
| Identity | `Symbol` | Identity, independent of description |
|
|
21
|
-
| Absence | `Unit`, `Null`, `Undefined` | Three distinct singleton domains |
|
|
22
|
-
| Presence | `Nullable a`, `Optional a` | Null or a present scalar; Undefined or a present scalar |
|
|
23
|
-
|
|
24
|
-
`Char` and `Text` exclude U+D800–U+DFFF. Code points range from 0 through
|
|
25
|
-
0x10FFFF. UTF-16 units range from 0 through 65535. Bytes range from 0 through
|
|
26
|
-
255. Raw constructors preserve units without decoding or replacement.
|
|
27
|
-
|
|
28
|
-
## Literals and arithmetic
|
|
29
|
-
|
|
30
|
-
Integer literals inherit a declared parameter or example type, otherwise they
|
|
31
|
-
have type `Integer`. Decimal literals default to exact `Decimal`. An annotation
|
|
32
|
-
supplies context: `(127 :: Int8)`, `(0.1 :: Float32)`. Literals outside the
|
|
33
|
-
contextual domain are rejected during checking.
|
|
34
|
-
|
|
35
|
-
```lawspec
|
|
36
|
-
unit example.increment
|
|
37
|
-
successor :: (x :: Int8) -> (result :: Integer where result == x + 1)
|
|
38
|
-
law `promotes instead of wrapping` is
|
|
39
|
-
definition is `for all` (x :: Int8) . successor x = x + 1 end
|
|
40
|
-
example `maximum input` is x = 127 expect successor x = 128 end
|
|
41
|
-
end
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
Integer `+`, `-`, `*`, and negation produce `Integer`. Decimal dominates integer
|
|
45
|
-
operands; Rational dominates exact operands. Exact `/` always produces Rational.
|
|
46
|
-
`prelude.quot` truncates toward zero, and `prelude.rem a b` satisfies
|
|
47
|
-
`a = quot a b * b + rem a b`. Division by zero fails when evaluated. Implication
|
|
48
|
-
guards short-circuit, including arithmetic and adapter calls.
|
|
49
|
-
|
|
50
|
-
Float32 operations round at binary32 precision; Float64 operations use binary64.
|
|
51
|
-
Mixed inexact operations widen to the greater component precision and to complex
|
|
52
|
-
when needed. Exact and inexact variables require explicit conversion:
|
|
53
|
-
`prelude.Float32 x`, `prelude.Float64 x`, `prelude.Rational x`,
|
|
54
|
-
`prelude.Decimal x`, or `prelude.Int8 x` (and the other numeric type names).
|
|
55
|
-
Fractional and out-of-range conversions to integers fail. A Rational conversion
|
|
56
|
-
to Decimal must terminate. Nonfinite floats cannot convert to exact numbers.
|
|
57
|
-
|
|
58
|
-
`prelude.round value scale` rounds an exact value to a specified number of decimal
|
|
59
|
-
places using ties-to-even. Negative scales round to powers of ten. Decimal
|
|
60
|
-
operations use exact arithmetic, independent of Python's decimal context or other
|
|
61
|
-
ambient rounding settings.
|
|
62
|
-
|
|
63
|
-
Comparison operators are `<`, `<=`, `>`, `>=`, `==`, and `!=`. Numeric comparisons
|
|
64
|
-
follow arithmetic's exact/inexact restriction. Complex numbers are not ordered.
|
|
65
|
-
`=` remains a law assertion. `==` and `!=` produce Bool and also support other
|
|
66
|
-
scalar domains. Multiplication and division bind more tightly than addition and
|
|
67
|
-
subtraction. Application and composition retain their existing syntax.
|
|
68
|
-
|
|
69
|
-
An adjacent sign remains an argument, as in `f -42`. Write `x - 42` for
|
|
70
|
-
subtraction, or parenthesize arithmetic arguments: `f (x - 42)`.
|
|
71
|
-
|
|
72
|
-
## Constructors and helpers
|
|
73
|
-
|
|
74
|
-
| Expression | Meaning |
|
|
75
|
-
| --- | --- |
|
|
76
|
-
| `decimal(123, -2)` | Exact 1.23 |
|
|
77
|
-
| `rational(1, 2)` | Exact 1/2 |
|
|
78
|
-
| `complex64(1, -2)`, `complex128(1, -2)` | Complex components at declared precision |
|
|
79
|
-
| `float32Bits("7fc00000")` | A binary32 NaN |
|
|
80
|
-
| `float64Bits("7ff0000000000000")` | Positive binary64 infinity |
|
|
81
|
-
| `float32Bits("80000000")` | Negative binary32 zero |
|
|
82
|
-
| `char(128512)` | Supplementary Unicode scalar |
|
|
83
|
-
| `codePoint(55296)` | Surrogate code point |
|
|
84
|
-
| `codeUnit16(55296)` | Lone UTF-16 surrogate unit |
|
|
85
|
-
| `codePoints([55296, 128512])` | Raw code-point sequence |
|
|
86
|
-
| `utf16([55296])` | Raw UTF-16 sequence |
|
|
87
|
-
| `bytes([0, 128, 255])` | Raw octets |
|
|
88
|
-
| `symbol("fixture-id", "description")` | Identity shared by the same ID within an example |
|
|
89
|
-
| `unitValue`, `null`, `undefined` | Distinct singleton values |
|
|
90
|
-
| `nullable(7)`, `optional(nullable(7))` | Present states, including nested states |
|
|
91
|
-
| `prelude.isNaN x`, `prelude.isInfinite x`, `prelude.isFinite x` | Float classification |
|
|
92
|
-
| `prelude.isNegativeZero x` | Float sign-bit classification |
|
|
93
|
-
| `prelude.real z`, `prelude.imag z` | Complex component access |
|
|
94
|
-
|
|
95
|
-
For `Optional (Nullable Int8)`, `undefined`, `optional(null)`, and
|
|
96
|
-
`optional(nullable(7))` are different values. Tagged support types preserve this
|
|
97
|
-
nesting, including on targets whose native null/optional types would collapse it.
|
|
98
|
-
|
|
99
|
-
## Target bridges and generated runtime
|
|
100
|
-
|
|
101
|
-
Existing Int32/Text/Bool-only specifications retain their adapter signatures.
|
|
102
|
-
Scalar specifications use native representations where the bridge implements the
|
|
103
|
-
whole domain, and generated support values elsewhere:
|
|
104
|
-
|
|
105
|
-
- Python: native int, bool, str, bytes, float, complex, Decimal and Fraction;
|
|
106
|
-
`Raw`, `Presence`, `Symbol`, and absence support values.
|
|
107
|
-
- JavaScript/TypeScript: number for small integers and floats, bigint for larger
|
|
108
|
-
integers, native strings, Uint8Array bytes and symbols; Decimal, Rational, Complex, Raw and
|
|
109
|
-
Presence support types. Unit is normalized from a void return.
|
|
110
|
-
- Java/Kotlin: native signed primitives and widened unsigned primitives,
|
|
111
|
-
BigInteger, BigDecimal, strings, byte arrays, code points, UTF-16 units and floating primitives; `LawSpecRuntime.Value`
|
|
112
|
-
for remaining domains. Unit-returning adapters normalize native void/Unit.
|
|
113
|
-
- Go: native integer widths, machine integers, floats and complex values,
|
|
114
|
-
`math/big.Int` and `math/big.Rat` (exported aliases), strings, runes, byte arrays and UTF-16 arrays;
|
|
115
|
-
`LawSpecValue` for remaining domains.
|
|
116
|
-
- Haskell: native fixed integers, Integer, Rational, Float, Double, Complex, Char, Text, ByteString and `()`;
|
|
117
|
-
the `Scalar` support type for remaining domains. `Text` maps to `Data.Text.Text`,
|
|
118
|
-
not Haskell’s linked-list `String` (`[Char]`). General list types such as `[Char]`
|
|
119
|
-
are outside this scalar release.
|
|
120
|
-
|
|
121
|
-
Input bridges check primitive bounds before native calls. Result bridges validate
|
|
122
|
-
returned values. In particular, Text bridges reject invalid Unicode rather than
|
|
123
|
-
repairing it. Use raw domains when preserving arbitrary bytes or UTF-16 units.
|
|
124
|
-
|
|
125
|
-
The runtime sources are emitted separately from framework-specific tests. They
|
|
126
|
-
have no property-testing or assertion-library dependencies. Runtime files are
|
|
127
|
-
generated-owned **source** artifacts; adapters are user-owned source artifacts.
|
|
128
|
-
Custom source/test directories and generation manifests preserve that distinction.
|
|
129
|
-
Haskell scalar projects require the standard `bytestring` package in their library
|
|
130
|
-
dependencies (included by new project templates).
|
|
131
|
-
Kotlin uses the shared Java runtime under `src/main/java` by default; custom
|
|
132
|
-
projects must include the configured source directory in their Java source set.
|
|
133
|
-
|
|
134
|
-
## Machine profiles
|
|
135
|
-
|
|
136
|
-
Set `"machineBits": 32` or `64` in `lawspec.json`, the compiler request, or use
|
|
137
|
-
`--machine-bits 32`. The default is 64. Bounds, examples, generators, and bridges
|
|
138
|
-
use this profile. Go and Haskell native machine-sized bridges report an
|
|
139
|
-
architecture mismatch when the native word size differs. Fixed-width types remain
|
|
140
|
-
portable across architectures.
|
|
141
|
-
|
|
142
|
-
The bundled `scalars.lawspec`, `scalar_catalog.lawspec`, and
|
|
143
|
-
`scalar_adapters.lawspec` contain explicit fixtures for every scalar family.
|
|
144
|
-
`tools/scalar-reference.py` produces independent Fraction-based conformance
|
|
145
|
-
vectors; `lawspec-acceptance scalar` executes them across the eight targets and
|
|
146
|
-
verifies that incorrect adapters are detected.
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
Refinements, parameterized domains, abstract native integer results, and executable
|
|
150
|
-
function contracts are described in [REFINEMENTS.md](REFINEMENTS.md).
|
package/PYTHON.md
DELETED
|
@@ -1,152 +0,0 @@
|
|
|
1
|
-
# Python backend
|
|
2
|
-
|
|
3
|
-
Python output follows [PEP 8](https://peps.python.org/pep-0008/): four-space
|
|
4
|
-
indentation, a 79-column code target, 72-column prose comments/docstrings, and
|
|
5
|
-
two blank lines between top-level definitions. Explicit `--minify` permits
|
|
6
|
-
compact layout while preserving Python indentation and semantics.
|
|
7
|
-
`tools/python-formatting-integration.mjs` checks generated runtime, adapter,
|
|
8
|
-
definition, and test files with pycodestyle 2.14.0 at both machine widths. It
|
|
9
|
-
also compares readable and compact syntax trees, including literal contents.
|
|
10
|
-
|
|
11
|
-
Use Python 3.13 or later. Generated tests use Hypothesis; generated data classes,
|
|
12
|
-
scalar operations, and schema validation do not depend on a test framework.
|
|
13
|
-
|
|
14
|
-
## Native structural values
|
|
15
|
-
|
|
16
|
-
| LawSpec type | Adapter representation |
|
|
17
|
-
| --- | --- |
|
|
18
|
-
| `List a` | `list[A]` |
|
|
19
|
-
| `Maybe a` | `lawspec_schema.Maybe[A]`, with `Nothing` and `Just` variants |
|
|
20
|
-
| `Either a b` | `lawspec_schema.Either[A, B]`, with `Left` and `Right` variants |
|
|
21
|
-
| User-defined products and sums | Named generic dataclasses in `lawspec_data` |
|
|
22
|
-
| `Nullable a`, `Optional a` | Tagged `lawspec_runtime.Presence` values |
|
|
23
|
-
|
|
24
|
-
`Nothing()` differs from `Just(Nothing())`. `Left(value)` differs from
|
|
25
|
-
`Right(value)`. These algebraic variants are separate from the interoperability
|
|
26
|
-
states represented by `Nullable`, `Optional`, `Null`, and `Undefined`.
|
|
27
|
-
|
|
28
|
-
For example, this declaration:
|
|
29
|
-
|
|
30
|
-
```lawspec
|
|
31
|
-
type Tree (a :: Type) is
|
|
32
|
-
Leaf value :: a
|
|
33
|
-
Branch children :: List (Tree a)
|
|
34
|
-
end
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
produces a generic `Tree` base and `TreeLeaf` and `TreeBranch` dataclasses. A
|
|
38
|
-
product has one variant: `Pair` with constructor `Pair` produces `PairPair`.
|
|
39
|
-
When names conflict across units or between types and variants, the compiler
|
|
40
|
-
plans distinct names using their Core identities. Use the emitted declarations
|
|
41
|
-
and adapter annotations as the authoritative names.
|
|
42
|
-
|
|
43
|
-
Native pattern matching works on the generated variants:
|
|
44
|
-
|
|
45
|
-
```python
|
|
46
|
-
import lawspec_data as data
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
def count_leaves(tree: data.Tree[int]) -> int:
|
|
50
|
-
match tree:
|
|
51
|
-
case data.TreeLeaf():
|
|
52
|
-
return 1
|
|
53
|
-
case data.TreeBranch(children=children):
|
|
54
|
-
return sum(count_leaves(child) for child in children)
|
|
55
|
-
raise TypeError("unknown Tree variant")
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
Classes are frozen and use slots. Container payloads are copied when crossing
|
|
59
|
-
adapter boundaries, so modifying a native list does not change another use of
|
|
60
|
-
the logical test input. An abstract base cannot be directly constructed; empty
|
|
61
|
-
types acquire no artificial variant.
|
|
62
|
-
|
|
63
|
-
LawSpec equality uses schema-directed comparisons, including IEEE NaN and
|
|
64
|
-
signed-zero rules and Symbol identity. Generated dataclasses do not derive
|
|
65
|
-
Python field equality, whose container shortcuts can change those rules.
|
|
66
|
-
|
|
67
|
-
## Checked boundaries
|
|
68
|
-
|
|
69
|
-
Generated calls validate input values, convert them to native classes, call the
|
|
70
|
-
adapter, and validate its result. A field extracted from a native product can
|
|
71
|
-
be returned directly from an adapter with the corresponding LawSpec result
|
|
72
|
-
type. The same representation is used for nested and standalone containers.
|
|
73
|
-
|
|
74
|
-
Diagnostics identify constructor fields and list indices. Checks distinguish
|
|
75
|
-
Bool from integers, enforce primitive ranges under the selected `machineBits`,
|
|
76
|
-
reject invalid scalar text, and preserve raw code units, code points, and bytes.
|
|
77
|
-
Preconditions and postconditions operate on validated logical values.
|
|
78
|
-
|
|
79
|
-
## Total definitions
|
|
80
|
-
|
|
81
|
-
Checked total definitions emit reusable Python functions separately from adapters:
|
|
82
|
-
|
|
83
|
-
```lawspec
|
|
84
|
-
unit example.total
|
|
85
|
-
|
|
86
|
-
definition increment (x :: Int8) :: BigInt is x + 1 end
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
```python
|
|
90
|
-
from lawspec_definitions.example import total
|
|
91
|
-
|
|
92
|
-
symbols = {}
|
|
93
|
-
assert total.increment(symbols, 127) == 128
|
|
94
|
-
```
|
|
95
|
-
|
|
96
|
-
The first argument is the Symbol fixture context shared within an example.
|
|
97
|
-
Public signatures preserve native container and variant annotations; checked
|
|
98
|
-
conversion enforces element types, ranges, machine profiles, and nested presence
|
|
99
|
-
states at runtime. Errors include the resolved definition name. Source functions
|
|
100
|
-
and implementation bodies have no Hypothesis or pytest dependency.
|
|
101
|
-
|
|
102
|
-
`lawspec_definition_bodies.py` holds checked logical implementations. Public
|
|
103
|
-
modules under `lawspec_definitions/` provide native entry points grouped by unit.
|
|
104
|
-
Both belong in source directories and are generated-owned. Properties invoke
|
|
105
|
-
those checked bodies directly; definitions do not create adapter stubs. Unit
|
|
106
|
-
modules cannot shadow support modules or another unit's package. Native function
|
|
107
|
-
names such as `str` do not shadow built-ins used by generated validation.
|
|
108
|
-
|
|
109
|
-
Definition bodies and Python properties share typed expression rendering. Match
|
|
110
|
-
inputs are evaluated once, branches remain lazy, guards short-circuit, and exact
|
|
111
|
-
Decimal arithmetic is independent of Python's ambient rounding context.
|
|
112
|
-
Definitions must pass structural termination and definedness checks. Generic
|
|
113
|
-
definitions specialize to concrete uses. Refined signatures become checked
|
|
114
|
-
contracts, and refinement predicates may call checked definitions.
|
|
115
|
-
|
|
116
|
-
`tools/python-definitions-integration.mjs` checks standalone source calls,
|
|
117
|
-
properties, incorrect adapters, both machine profiles, custom layouts, compact
|
|
118
|
-
execution, and regeneration protection. The bundled Python corpus passes PEP 8 checks at 79 code columns and 72 prose
|
|
119
|
-
columns. The style audit includes the standalone total-definition fixture.
|
|
120
|
-
|
|
121
|
-
## Generation and layouts
|
|
122
|
-
|
|
123
|
-
Hypothesis composes tuples, alternatives, lists, and dependent strategies.
|
|
124
|
-
Recursive generation reserves each field's minimum node budget before sharing
|
|
125
|
-
the remainder. List length and element budgets vary together. Shrinking remains
|
|
126
|
-
native to Hypothesis and preserves the schema and structural size bound.
|
|
127
|
-
Small finite domains are enumerated; empty domains do not pass vacuously.
|
|
128
|
-
|
|
129
|
-
`lawspec_data.py` and `lawspec_schema.py` belong in the configured source
|
|
130
|
-
directory. `lawspec_data_strategies.py` belongs in the test directory. Configure
|
|
131
|
-
Python's import paths for those directories when using a custom layout.
|
|
132
|
-
Adapters remain user-owned. Unit names cannot shadow generated support modules.
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
Internal checked Core definition contracts now run at native and logical entry
|
|
136
|
-
points. Emission proves the obligations first; argument validation precedes
|
|
137
|
-
ordered preconditions, and result validation precedes postconditions. Contract
|
|
138
|
-
binders map explicitly to body inputs and the checked result. Refined source
|
|
139
|
-
signatures now produce these contracts through template proof and specialization.
|
|
140
|
-
|
|
141
|
-
`tools/portable-definition-contract-integration.mjs` exercises Python, JavaScript
|
|
142
|
-
and strict TypeScript with both machine profiles and layouts, without property
|
|
143
|
-
frameworks. It also verifies that deliberately corrupted results are rejected.
|
|
144
|
-
The fixture in `test/DefinitionContractFixture.hs` is shared with the JVM checks.
|
|
145
|
-
|
|
146
|
-
## Checking Python style
|
|
147
|
-
|
|
148
|
-
Set `LAWSPEC_CORE` to the native compiler, `LAWSPEC_PYTHON` to Python 3.13 or
|
|
149
|
-
later, and `LAWSPEC_PYCODESTYLE` to the `pycodestyle.py` source from version
|
|
150
|
-
2.14.0. Then run `node tools/python-formatting-integration.mjs`. The checker is
|
|
151
|
-
a development dependency; generating and executing runtime code does not
|
|
152
|
-
require it. Optional positional arguments select individual specification files.
|