lawspec 0.2.0 → 0.3.0

package/README.md

@@ -2,34 +2,41 @@
 
 **State the law once. Check it everywhere.**
 
-LawSpec 0.2 compiles reusable laws into native property tests, executable examples,
+LawSpec 0.3 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.2.0.tgz
+npm install --save-dev lawspec@0.3.0
+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. Stable releases are available as the `lawspec` package on npm.
+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.3.0 -- lawspec init --target javascript
+npm install --save-dev lawspec@0.3.0
+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.2's current JVM profile certifies
+through compatibility profiles after testing; v0.3'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.
@@ -139,7 +146,7 @@ end
 ```
 
 The implicit prelude defines `left inverse`, `round trip identity is preserved`,
-and `equivalent`.
+`equivalent`, and `idempotent`.
 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,10 +157,13 @@ 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.2 generates
-quantified `Int32` inputs, including multiple inputs. `Text` can be an intermediate
-or compared result. Functions are synchronous and unary.
+quantification, integer and text literals, and equality. Function signatures use `Int32`
+and `Text`; generic variables are supported in reusable laws. v0.3 generates
+quantified `Int32` and `Text` inputs, including mixed and multiple inputs. Both
+types can also be intermediate or compared results. Functions are synchronous
+and unary. Text literals are double-quoted, with escapes such as `\"`, `\\`,
+`\n`, and `\t`; examples must bind each input to a literal of its declared type.
+Text values contain Unicode scalar values; surrogate code points are rejected.
 
 Examples refer to the expanded input names, including names inherited from the
 prelude. Bind every input exactly once. Ambiguous names and out-of-range values
@@ -192,7 +202,7 @@ 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](examples/specs/equivalent.lawspec) compares decimal
+[The complete example](https://github.com/brain-fuel/lawspec/blob/v0.3.0/examples/specs/equivalent.lawspec) compares decimal
 renderers and two implementations that clamp negative integers to zero. For
 JavaScript, their adapters can be:
 
@@ -207,7 +217,82 @@ 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.
+implementations can share the same bug. Quantified inputs can be `Int32` or `Text`.
+
+## Text properties and idempotence
+
+```lawspec
+unit example.slug
+
+normalize :: Text -> Text
+referenceNormalize :: Text -> Text
+
+law `normalizers agree` is
+  definition is
+    `equivalent` normalize referenceNormalize
+  end
+  example `ordinary text` is
+    x = "Hello, World!"
+  end
+end
+```
+
+The [slug example](https://github.com/brain-fuel/lawspec/blob/v0.3.0/examples/specs/slug.lawspec)
+compares two implementations of ASCII-space replacement. It includes empty,
+Unicode and escaped text. Each target uses its native string generator:
+JetCheck `Generator.stringsOf(Generator.asciiPrintableChars())`, Hypothesis `st.text()`, fast-check `fc.string()`,
+Rapid `rapid.String()`, Hedgehog `Gen.text`, or Kotest `Arb.string()`.
+Generator distributions differ between libraries; the generated tests also
+exercise deterministic empty, whitespace, Unicode, combining-mark and escaped
+control-character cases. Hedgehog's generated text length range is 0–100.
+
+The prelude's `idempotent` law requires `f (f x) = f x`:
+
+```lawspec
+unit example.canonical_url
+
+canonicalize :: Text -> Text
+
+law `canonicalization reaches a fixed point` is
+  definition is
+    `idempotent` canonicalize
+  end
+end
+```
+
+The [canonical URL example](https://github.com/brain-fuel/lawspec/blob/v0.3.0/examples/specs/canonical_url.lawspec)
+uses removal of **all trailing slashes** as a small fixed-point demonstration,
+not a complete URL canonicalization algorithm. For JavaScript:
+
+```javascript
+export const canonicalize = value => value.replace(/\/+$/, "");
+```
+
+Removing just one trailing slash fails the supplied repeated-slash example.
+The [mixed-input example](https://github.com/brain-fuel/lawspec/blob/v0.3.0/examples/specs/mixed_inputs.lawspec)
+shows `Text` and `Int32` in the same quantified property and executable example.
+The JavaScript API represents example values as `number | string`.
+
+## Generate all example artifacts
+
+```sh
+npx lawspec examples
+# Or select a target and a relative output directory:
+npx lawspec examples --target java --output example_artifacts
+```
+
+This command works without a project configuration or native build tools. It
+compiles every bundled example and writes its tests and user-owned stubs to
+`example_artifacts/<language>/`, using each target's normal source/test layout.
+By default it exports all seven languages; `--json` returns the file inventory.
+From a checkout, `make examples` runs the same command.
+
+These are inspection artifacts, not initialized projects: no build files are
+created and dependency compatibility is not checked. To run them, configure the
+corresponding native project and implement the stubs. Regeneration preserves
+user-owned stubs and refuses to overwrite edited generated tests. Each target
+has its own ownership manifest. Output paths must be relative and cannot use
+parent traversal or symlinks. The default directory is ignored by Git.
 
 ## Ownership
 
@@ -247,6 +332,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.3.0.tgz`.
+The package payload lives in `npm/`.
+
 ```sh
 stack test
 # With wasm32-wasi-cabal and wasm32-wasi-ghc installed:

package/bin/lawspec.mjs

@@ -3,6 +3,7 @@ import { readFile, mkdir, readdir, stat } from "node:fs/promises";
 import path from "node:path";
 import { createCompiler } from "../api.mjs";
 import { targets, templates, commands, setup } from "../templates.mjs";
+import { generateExamples } from "../examples-command.mjs";
 import { doctor } from "../doctor.mjs";
 import {
   readOptional,
@@ -17,7 +18,7 @@ const options = {};
 const positional = [];
 for (let i = 0; i < args.length; i++) {
   const arg = args[i];
-  if (["--target", "--project", "--config"].includes(arg)) {
+  if (["--target", "--project", "--config", "--output"].includes(arg)) {
     if (!args[i + 1] || args[i + 1].startsWith("--"))
       throw new Error(`Missing value for ${arg}`);
     options[arg.slice(2)] = args[++i];
@@ -153,17 +154,40 @@ async function init() {
 async function main() {
   if (!verb || ["help", "--help", "-h"].includes(verb)) {
     output(
-      "LawSpec 0.2.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.3.0\nUsage: lawspec init --target <language> [--project <directory>]\n       lawspec check | doctor | explain <unit>::<law> | generate\n       lawspec examples [--target <language>] [--output example_artifacts]\nOptions: --config <path>, --target <language>, --json\nGeneration: --dry-run, --check\nTargets: " +
         targets.join(", "),
     );
     return;
   }
   if (verb === "--version") {
-    output("0.2.0");
+    output("0.3.0");
     return;
   }
   if (positional.length > (verb === "explain" ? 1 : 0))
     throw new Error(`Unexpected argument: ${positional.join(" ")}`);
+  if (verb === "examples") {
+    if (
+      options.config ||
+      options.project ||
+      options["dry-run"] ||
+      options.check
+    )
+      throw new Error("examples supports --target, --output and --json only");
+    const result = await generateExamples(options);
+    output(
+      options.json
+        ? result
+        : result
+            .map(
+              (r) =>
+                `${r.target}: ${r.files.length} artifacts in ${r.directory}; ${r.preservedAdapters.length} user adapters preserved.`,
+            )
+            .join("\n") +
+            "\nInspection artifacts only; native toolchains and dependencies are not checked. Stubs must be implemented before running tests.",
+    );
+    return;
+  }
+  if (options.output) throw new Error("--output is only supported by examples");
   if (verb === "init") return init();
   if (!["check", "doctor", "explain", "generate"].includes(verb))
     throw new Error(`Unknown command: ${verb}`);

package/build.json

@@ -17,23 +17,23 @@
     "wasm/lawspec-wasm.cabal"
   ],
   "digests": {
-    "package.yaml": "f8d2b6bbf4308890903787813994500d4843cd08ee5bc1ae3808a49461d51380",
+    "package.yaml": "a04aefef41a1245f28d4f1d63ea38a5266b1f5302242c9fc3a840252ea7ce3ec",
     "src/LawSpec/Api.hs": "00b1e4bc81231ebd387f10652463904084ebf9c3c4486fd2c2217a6d4dbfc157",
-    "src/LawSpec/Compile.hs": "c1727ba7d6ece9725567f9561d341d8660b3293ff845c2de1d936ebdd2cd5fc6",
-    "src/LawSpec/Emit.hs": "24edca3a078ea10349b3a229b56464c37bfd5303c688a11ed45f9479ce3b7bd1",
-    "src/LawSpec/Gen.hs": "b283001bc18971ddb2159f2ec7e51ac58aa7e191b52577006140694b09a06987",
-    "src/LawSpec/Model.hs": "8f501e134cd1480261ae8bb9e3df8255efd38a02eb883468c6bc2c342e200970",
-    "src/LawSpec/Parser.hs": "f546502c6eedb0a4ccd30d11e3b017aedf5a7145080ea58cfd34753fd9b509c6",
-    "src/LawSpec/Prelude.hs": "f04078dbc03eb793f9f3343db562cf56f84b5fbe6fd4aea6481bad38a7c6f328",
+    "src/LawSpec/Compile.hs": "cb32f1ff2f2ded5e93e25b11658fec6a2ffb1d24e0caaa2ffec94b510f4bfe40",
+    "src/LawSpec/Emit.hs": "c72ff20088dcaf74576710e144e79d35f9441f37fc933603033584fdff309fbe",
+    "src/LawSpec/Gen.hs": "b3d924fddc7e8417665635f049a3f641ea15c2f6f997571287db17a70b1f37b6",
+    "src/LawSpec/Model.hs": "5d550a5b75cd6b00f1b01d276100527a066c35bb69e95adb6b549b6603bab196",
+    "src/LawSpec/Parser.hs": "0a70a57b6535cfa33121e9ada595f518ced4f7b35bf09bc4732a1362c05a253f",
+    "src/LawSpec/Prelude.hs": "0b60dd85bdf0642077dfb497043c63606d507e71e12d3ed8bfe2bf773214c66b",
     "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": "48a9a7587f183565043e313e20e531c72d2eeb4ec706a1052ff0e7b461961002",
-    "npm/core.wasm": "fe4048e604bbdf5ddbecf9ea2e9b27ac60161788fff35524cbcf9825e2e8faeb",
+    "wasm/lawspec-wasm.cabal": "9f61a4c9e5c7715d1de2c42e518f3fe9cf088a3677182bda4c3f4601aa930ba9",
+    "npm/core.wasm": "674f19955c07f0bd987df27463cb0ba35c5e9756a8d22309aa21bff7488e7ed0",
     "npm/core_jsffi.js": "88d136efe92f7cff5758c8fec8d9b6bbc9707fe37741cebeeb415fe34ce3d72b",
     "npm/api.mjs": "d6df654600172131ac66a55b86876fc29cde2a76a0a63bbefff3183488a4837b",
-    "npm/index.d.ts": "8003304d88dbb01a07bd3dbdc4d680a193db1ec323c5712b9860e166ca9cc94b"
+    "npm/index.d.ts": "94c4842654d280796aeedcf7b438ffc63e96d0ff639203f93d04610f1de07c53"
   }
 }

package/examples/specs/canonical_url.lawspec

@@ -0,0 +1,21 @@
+unit example.canonical_url
+
+canonicalize :: Text -> Text
+
+law `canonicalization reaches a fixed point` is
+  definition is
+    `idempotent` canonicalize
+  end
+  description is
+    "{canonicalize} removes trailing slashes until the result is stable"
+  end
+  example `trailing slashes` is
+    x = "https://example.com/path///"
+  end
+  example `already canonical` is
+    x = "https://example.com/path"
+  end
+  example `empty` is
+    x = ""
+  end
+end

package/examples/specs/mixed_inputs.lawspec

@@ -0,0 +1,33 @@
+unit example.mixed.inputs
+
+normalize :: Text -> Text
+identity :: Int32 -> Int32
+
+law `text and integer inputs remain independent` is
+  definition is
+    `for all` (text :: Text) (number :: Int32) .
+      normalize text = normalize (normalize text)
+  end
+  example `mixed inputs` is
+    text = "Hello, World!"
+    number = -42
+  end
+end
+
+law `integer behavior with a text context` is
+  definition is
+    `for all` (text :: Text) (number :: Int32) .
+      identity number = number
+  end
+  example `Unicode context` is
+    text = "λ 😀"
+    number = 2147483647
+  end
+end
+
+law `normalizing an empty literal` is
+  definition is
+    `for all` (text :: Text) .
+      normalize "" = ""
+  end
+end

package/examples/specs/slug.lawspec

@@ -0,0 +1,25 @@
+unit example.slug
+
+normalize :: Text -> Text
+referenceNormalize :: Text -> Text
+
+law `normalizers agree` is
+  definition is
+    `equivalent` normalize referenceNormalize
+  end
+  description is
+    "{normalize} and {referenceNormalize} replace ASCII spaces with hyphens"
+  end
+  example `ordinary text` is
+    x = "Hello, World!"
+  end
+  example `empty` is
+    x = ""
+  end
+  example `Unicode` is
+    x = "café 日本語 😀"
+  end
+  example `escaped text` is
+    x = "quote: \" slash: \\ newline: \n tab: \t dollar: $"
+  end
+end

package/examples-command.mjs

@@ -0,0 +1,51 @@
+import { readFile, readdir, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { createCompiler } from "./api.mjs";
+import { targets } from "./templates.mjs";
+import { safePath, planWrites, applyWrites } from "./files.mjs";
+
+export async function generateExamples(options) {
+  const selected = options.target ? [options.target] : targets;
+  if (selected.some((t) => !targets.includes(t)))
+    throw new Error(`Unknown target: ${options.target}`);
+  const directory = new URL("./examples/specs/", import.meta.url);
+  const sources = await Promise.all(
+    (await readdir(directory))
+      .filter((n) => n.endsWith(".lawspec"))
+      .sort()
+      .map(async (name) => ({
+        path: name,
+        content: await readFile(new URL(name, directory), "utf8"),
+      })),
+  );
+  const compiler = await createCompiler();
+  const artifacts = [];
+  for (const target of selected) {
+    const result = await compiler.planGeneration({ sources, target });
+    if (result.diagnostics.length)
+      throw Object.assign(new Error("Bundled examples failed to compile"), {
+        diagnostics: result.diagnostics,
+      });
+    artifacts.push(result.files);
+  }
+  const root = await safePath(
+    process.cwd(),
+    options.output || "example_artifacts",
+  );
+  await mkdir(root, { recursive: true });
+  const plans = [];
+  for (let i = 0; i < selected.length; i++) {
+    const targetRoot = await safePath(root, selected[i]);
+    await mkdir(targetRoot, { recursive: true });
+    plans.push(await planWrites(targetRoot, artifacts[i]));
+  }
+  await applyWrites(plans);
+  return plans.map((plan, i) => ({
+    target: selected[i],
+    directory: plan.root,
+    files: artifacts[i].map((f) => ({ path: f.path, ownership: f.ownership })),
+    changes: plan.changes.length,
+    preservedAdapters: plan.preserved,
+    adapterUpdates: plan.adapterUpdates,
+  }));
+}

package/index.d.ts

@@ -5,9 +5,9 @@ export interface Location { file: string; line: number; column: number }
 export interface Diagnostic { code: string; message: string; at: Location | null }
 export interface Artifact { path: string; content: string; ownership: 'user' | 'generated' }
 export type Type = {tag: 'Named' | 'Variable'; contents: string} | {tag: 'Arrow'; contents: [Type, Type]};
-export type Expr = {tag: 'Var'; contents: string} | {tag: 'Number'; contents: number} | {tag: 'Apply' | 'Compose'; contents: [Expr, Expr]};
+export type Expr = {tag: 'Var' | 'StringLit'; contents: string} | {tag: 'Number'; contents: number} | {tag: 'Apply' | 'Compose'; contents: [Expr, Expr]};
 export type Definition = {tag: 'Forall'; contents: [[string, Type][], Definition]} | {tag: 'Equal'; contents: [Expr, Expr]} | {tag: 'Invoke'; contents: [string, Expr[]]};
-export interface Example { exampleName: string; bindings: [string, number][] }
+export interface Example { exampleName: string; bindings: [string, number | string][] }
 export interface Law { lawName: string; parameters: [string, Type][]; requirements: Type[]; definition: Definition; description: string; rationale: string; examples: Example[]; references: string[]; location: Location }
 export interface Expanded { owner: string; name: string; inputs: {inputName: string; inputId: string; inputType: Type}[]; left: Expr; right: Expr; trace: string[]; original: Law }
 export interface CheckRequest { sources: Source[] }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lawspec",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "State the law once. Check it everywhere.",
   "license": "MIT",
   "type": "module",