lawspec 0.1.0 → 0.2.1

package/README.md

@@ -2,34 +2,41 @@
 
 **State the law once. Check it everywhere.**
 
-LawSpec 0.1 compiles reusable laws into native property tests, executable examples,
+LawSpec 0.2 compiles reusable laws into native property tests, executable examples,
 and implementation adapters. The compiler is Haskell, distributed as prebuilt
 WebAssembly with a Node CLI and an asynchronous, typed JavaScript API.
 
 ## Install and try it
 
-The checkout includes the npm package in `npm/`. Build an installable archive:
+Install [LawSpec from npm](https://www.npmjs.com/package/lawspec):
 
 ```sh
-npm pack ./npm
-npm install --save-dev ./lawspec-0.1.0.tgz
+npm install --save-dev lawspec@0.2.1
+npx lawspec --version
 ```
 
-No Haskell toolchain is needed to install or run the npm package. Node 22+ and the
-selected target's build tools are required. The reference platforms are macOS
-and Linux. This checkout has not been published to the npm registry.
+Node 22+ and the selected target's build tools are required. No Haskell toolchain
+is needed to install or run LawSpec. The reference platforms are macOS and Linux.
+Use `npx lawspec` to run the locally installed CLI.
 
-From an empty application directory, use the installed `lawspec` command:
+To try it in a **new, empty directory**, initialize the starter before installing
+local dependencies so LawSpec can create its `package.json` and test script:
 
 ```sh
-lawspec init --target javascript
-npm install
-lawspec check
-lawspec explain 'example.atoi_codec::itoa and then atoi yields a'
-lawspec doctor
-lawspec generate
+mkdir lawspec-example
+cd lawspec-example
+npm exec --package=lawspec@0.2.1 -- lawspec init --target javascript
+npm install --save-dev lawspec@0.2.1
+npx lawspec check
+npx lawspec explain 'example.atoi_codec::itoa and then atoi yields a'
+npx lawspec doctor
+npx lawspec generate
 ```
 
+In an existing project, install LawSpec first, then run
+`npx lawspec init --target javascript`. Existing build files are preserved;
+apply the printed dependency and test-runner setup instructions before generation.
+
 Implement `src/example/atoi_codec.mjs`, then run `npm test`:
 
 ```javascript
@@ -54,7 +61,7 @@ properties with the selected framework's shrinking and failure reporting.
 | `kotlin` | JDK/JVM 25, Gradle 9.1–9.3, Kotlin 2.3.21 | Kotest 5.9.1 | `gradle test` |
 
 Java 25 and Python 3.13 are the minimum baselines. New JVM releases are admitted
-through compatibility profiles after testing; v0.1's current JVM profile certifies
+through compatibility profiles after testing; v0.2's current JVM profile certifies
 25. Python templates declare `requires-python = ">=3.13"` and runtime checks
 currently recognize 3.13 and 3.14. Kotlin templates pin Gradle's supported build
 configuration to Kotlin 2.3.21 and target JVM 25.
@@ -138,7 +145,8 @@ law `round trip` is
 end
 ```
 
-The implicit prelude defines `left inverse` and `round trip identity is preserved`.
+The implicit prelude defines `left inverse`, `round trip identity is preserved`,
+and `equivalent`.
 A law may reference a local reusable law or a prelude law. The compiler performs
 capture-avoiding expansion and specializes types; it does not recognize codec
 function names specially. `explain` shows the final property:
@@ -150,7 +158,7 @@ for all (x :: Int32) . atoi (itoa (x)) = x
 Reusable laws can declare typed unary function parameters and `requires Eq a`.
 Definitions support law application, function application/composition, universal
 quantification, integer literals and equality. Function signatures use `Int32`
-and `Text`; generic variables are supported in reusable laws. v0.1 generates
+and `Text`; generic variables are supported in reusable laws. v0.2 generates
 quantified `Int32` inputs, including multiple inputs. `Text` can be an intermediate
 or compared result. Functions are synchronous and unary.
 
@@ -165,6 +173,49 @@ Additional primitives, external law packages, cross-unit imports beyond the
 prelude, async functions, direct existing-symbol binding and browser hosting are
 outside this release.
 
+## Comparing alternative implementations
+
+`equivalent` compares two functions with the same input and output types. Its
+`Eq b` requirement applies to the **result**, so an `Int32 -> Text` comparison
+uses text equality, while `Int32 -> Int32` uses integer equality.
+
+```lawspec
+unit example.formatting
+
+render :: Int32 -> Text
+referenceRender :: Int32 -> Text
+
+law `decimal renderers agree` is
+  definition is
+    `equivalent` render referenceRender
+  end
+  example `negative integer` is
+    x = -42
+  end
+end
+```
+
+This expands to `for all (x :: Int32) . render (x) = referenceRender (x)`.
+The example inherits the input name `x` from the prelude. Both functions are
+user-owned adapter functions; either may delegate to your existing code.
+
+[The complete example](https://github.com/brain-fuel/lawspec/blob/v0.2.1/examples/specs/equivalent.lawspec) compares decimal
+renderers and two implementations that clamp negative integers to zero. For
+JavaScript, their adapters can be:
+
+```javascript
+export const render = x => String(x);
+export const referenceRender = x => x.toString(10);
+export const clamp = x => Math.max(0, x);
+export const referenceClamp = x => x < 0 ? 0 : x;
+```
+
+The same specification generates native tests for all seven targets. The
+integration suite checks both examples with matching implementations, then
+breaks each alternative separately to verify detection. Agreement does not
+establish that either implementation meets an independent specification; two
+implementations can share the same bug. Quantified inputs remain `Int32` in v0.2.
+
 ## Ownership
 
 Implementation adapters are created once and belong to you. Implement them or
@@ -203,6 +254,10 @@ by the JS shim.
 
 ## Build and verify
 
+For contributors working from a repository checkout, build a local archive with
+`npm pack ./npm` and install it with `npm install --save-dev ./lawspec-0.2.1.tgz`.
+The package payload lives in `npm/`.
+
 ```sh
 stack test
 # With wasm32-wasi-cabal and wasm32-wasi-ghc installed:

package/bin/lawspec.mjs

@@ -153,13 +153,13 @@ async function init() {
 async function main() {
   if (!verb || ["help", "--help", "-h"].includes(verb)) {
     output(
-      "LawSpec 0.1.0\nUsage: lawspec init --target <language> [--project <directory>]\n       lawspec check | doctor | explain <unit>::<law> | generate\nOptions: --config <path>, --target <language>, --json\nGeneration: --dry-run, --check\nTargets: " +
+      "LawSpec 0.2.1\nUsage: lawspec init --target <language> [--project <directory>]\n       lawspec check | doctor | explain <unit>::<law> | generate\nOptions: --config <path>, --target <language>, --json\nGeneration: --dry-run, --check\nTargets: " +
         targets.join(", "),
     );
     return;
   }
   if (verb === "--version") {
-    output("0.1.0");
+    output("0.2.1");
     return;
   }
   if (positional.length > (verb === "explain" ? 1 : 0))

package/build.json

@@ -17,21 +17,21 @@
     "wasm/lawspec-wasm.cabal"
   ],
   "digests": {
-    "package.yaml": "cb68fcf21def8f7a880bbab7088208a86fcf313a83fe2c02e18957872cf65c67",
+    "package.yaml": "2cc5254bf0c1de94adbb98ee193dd45f5d8e5efced9ce255508112ccbca96793",
     "src/LawSpec/Api.hs": "00b1e4bc81231ebd387f10652463904084ebf9c3c4486fd2c2217a6d4dbfc157",
-    "src/LawSpec/Compile.hs": "5ea31f4a66df87ddba2ff0b498d12eea5cbbefb0e10e3bf1c1d2bf4a88f5792e",
-    "src/LawSpec/Emit.hs": "27ba0cafbea8d5a82aac439f4e72f98e003cfdc177f99a902f8d11f033684b8e",
+    "src/LawSpec/Compile.hs": "c1727ba7d6ece9725567f9561d341d8660b3293ff845c2de1d936ebdd2cd5fc6",
+    "src/LawSpec/Emit.hs": "4e223dfc975c5b66021e7a012a063edd159fe38ca12df7d009aa3de472a2e646",
     "src/LawSpec/Gen.hs": "b283001bc18971ddb2159f2ec7e51ac58aa7e191b52577006140694b09a06987",
     "src/LawSpec/Model.hs": "8f501e134cd1480261ae8bb9e3df8255efd38a02eb883468c6bc2c342e200970",
     "src/LawSpec/Parser.hs": "f546502c6eedb0a4ccd30d11e3b017aedf5a7145080ea58cfd34753fd9b509c6",
-    "src/LawSpec/Prelude.hs": "d4b0ae08eab0f30b4b8c819ce360f7cccb1f77d5ea38ded3b88dbb07936b10b6",
+    "src/LawSpec/Prelude.hs": "f04078dbc03eb793f9f3343db562cf56f84b5fbe6fd4aea6481bad38a7c6f328",
     "stack.yaml": "20ccf4d599e355e60b7aa4f814a7cd4299fe2048616cc2e6dbdc22a7bd8cec73",
     "stack.yaml.lock": "ae222b9c81af920c56e50fa4596fa57786e7fa5a7b461390362b2b2ff63818c7",
     "wasm/app/Exports.hs": "4ecbdac8faa2449e6fc61b93c82e6278fa14374154f29b4dacf0eef433f06a47",
     "wasm/cabal.project": "021e560afdc5eb4cb7169e7119ecb8f92c9ee170245af909c94b612941bff5cc",
     "wasm/cabal.project.freeze": "733dbed3d2ecccb26e874fd58f136296dad772184deb1658c196b5d54a0814dc",
-    "wasm/lawspec-wasm.cabal": "d11ccf7991e406f0fd26f124c54d6552613b892328f8e22a964e38d03c7d6de4",
-    "npm/core.wasm": "14d88c08f92b10ac2939d6b92bc428b0ee255d56e88890fd46abb1e959a26b2b",
+    "wasm/lawspec-wasm.cabal": "139de82d2d6063eb82fc86438a82e59d9b9315318009cad199f488bca14cb56d",
+    "npm/core.wasm": "943abf2084a7395ef6c5441ef4fd93aa0d57e581a0e71723bf6187afa2c3b48c",
     "npm/core_jsffi.js": "88d136efe92f7cff5758c8fec8d9b6bbc9707fe37741cebeeb415fe34ce3d72b",
     "npm/api.mjs": "d6df654600172131ac66a55b86876fc29cde2a76a0a63bbefff3183488a4837b",
     "npm/index.d.ts": "8003304d88dbb01a07bd3dbdc4d680a193db1ec323c5712b9860e166ca9cc94b"

package/examples/specs/atoi_codec.lawspec

@@ -0,0 +1,31 @@
+unit example.atoi_codec
+
+itoa :: Int32 -> Text
+atoi :: Text -> Int32
+
+law `itoa and then atoi yields a` is
+  definition is
+    `round trip identity is preserved` itoa atoi
+  end
+
+  description is
+    "converting an Int32 to Text with {itoa} and then back with {atoi} yields the original Int32"
+  end
+
+  rationale is
+    "representing an Int32 as Text must not change its value"
+  end
+
+  example `negative integer` is
+    x = -42
+  end
+
+  example `zero` is
+    x = 0
+  end
+
+  references are
+    "left inverse"
+    "round-trip property"
+  end
+end

package/examples/specs/equivalent.lawspec

@@ -0,0 +1,39 @@
+unit example.alternatives
+
+render :: Int32 -> Text
+referenceRender :: Int32 -> Text
+clamp :: Int32 -> Int32
+referenceClamp :: Int32 -> Int32
+
+law `decimal renderers agree` is
+  definition is
+    `equivalent` render referenceRender
+  end
+  description is
+    "{render} agrees with {referenceRender} on decimal formatting"
+  end
+  rationale is
+    "changing the formatting implementation must preserve its result"
+  end
+  example `negative integer` is
+    x = -42
+  end
+  example `zero` is
+    x = 0
+  end
+end
+
+law `nonnegative clamps agree` is
+  definition is
+    `equivalent` clamp referenceClamp
+  end
+  description is
+    "{clamp} agrees with {referenceClamp} when clamping negative inputs to zero"
+  end
+  example `negative boundary` is
+    x = -2147483648
+  end
+  example `positive boundary` is
+    x = 2147483647
+  end
+end

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lawspec",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "State the law once. Check it everywhere.",
   "license": "MIT",
   "type": "module",
@@ -8,6 +8,6 @@
   "bin": { "lawspec": "bin/lawspec.mjs" },
   "exports": { ".": { "types": "./index.d.ts", "import": "./api.mjs" } },
   "types": "index.d.ts",
-  "files": ["*.mjs", "*.json", "index.d.ts", "bin", "core.wasm", "core_jsffi.js", "README.md", "LICENSE", "starter.lawspec"],
+  "files": ["*.mjs", "*.json", "index.d.ts", "bin", "core.wasm", "core_jsffi.js", "README.md", "LICENSE", "starter.lawspec", "examples"],
   "scripts": { "test": "node --test test/*.test.mjs" }
 }