lawspec 0.2.1 → 0.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 **State the law once. Check it everywhere.**
 
-LawSpec 0.2 compiles reusable laws into native property tests, executable examples,
+LawSpec 0.4 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.
 
@@ -11,7 +11,7 @@ WebAssembly with a Node CLI and an asynchronous, typed JavaScript API.
 Install [LawSpec from npm](https://www.npmjs.com/package/lawspec):
 
 ```sh
-npm install --save-dev lawspec@0.2.1
+npm install --save-dev lawspec@0.4.0
 npx lawspec --version
 ```
 
@@ -25,8 +25,8 @@ local dependencies so LawSpec can create its `package.json` and test script:
 ```sh
 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
+npm exec --package=lawspec@0.4.0 -- lawspec init --target javascript
+npm install --save-dev lawspec@0.4.0
 npx lawspec check
 npx lawspec explain 'example.atoi_codec::itoa and then atoi yields a'
 npx lawspec doctor
@@ -52,7 +52,7 @@ properties with the selected framework's shrinking and failure reporting.
 
 | Target | Build setup | Test libraries | Test command |
 | --- | --- | --- | --- |
-| `java` | Maven, JDK 25, release 25 | JetCheck 0.3.0, JUnit Jupiter 5.14.x | `mvn test` |
+| `java` | Maven, JDK 25, release 25 | JetCheck 0.4.0, JUnit Jupiter 5.14.x | `mvn test` |
 | `python` | Python 3.13 or 3.14, pyproject | pytest 8.4.x, Hypothesis 6.135.26+ (6.x) | `python -m pytest` |
 | `javascript` | Node 22+, npm, ESM | fast-check 4.x, node:test | `npm test` |
 | `typescript` | Node 22+, npm, TypeScript 5.9.x, ESM | fast-check 4.x, node:test | `npm test` |
@@ -61,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.4'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.
@@ -113,7 +113,7 @@ uses `test/Spec.hs` with `hspec-discover`.
 Commands:
 
 - `check`: parse, resolve, type-check and expand laws without target dependencies.
-- `explain [unit::law]`: display expansion steps and inherited example inputs.
+- `explain [unit::law]`: display expansions, example inputs, and expected results.
 - `doctor`: inspect selected native environments and print corrective instructions.
 - `generate`: check environments, validate every output, then write artifacts.
 - `generate --dry-run`: show proposed file operations without applying them.
@@ -139,14 +139,16 @@ law `round trip` is
   description is
     "applying {itoa} and then {atoi} recovers the original integer"
   end
-  example `negative` is
+  example `negative integers use a minus sign and round-trip unchanged` is
     x = -42
+    expect itoa x = "-42"
+    expect atoi (itoa x) = -42
   end
 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:
@@ -157,15 +159,18 @@ 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.4 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
 are errors. Descriptions and rationales use `{function}` references; `{{` and `}}`
-produce literal braces. Metadata blocks follow the order shown in `scratch.md`:
+produce literal braces. Law blocks use this order:
 definition, optional description, optional rationale, examples, optional references.
 `--` starts a line comment. Names that cannot be emitted portably are diagnosed.
 
@@ -173,6 +178,40 @@ Additional primitives, external law packages, cross-unit imports beyond the
 prelude, async functions, direct existing-symbol binding and browser hosting are
 outside this release.
 
+## Expected results and migration to 0.4
+
+Every `example` must bind all quantified inputs and then include one or more
+`expect <expression> = <literal>` assertions. The expected literal must have the
+same `Int32` or `Text` type as the expression. Expressions can reference the
+example's inputs and the unit's functions, including composed function calls.
+Input names shadow function names within expectations, following lexical scope.
+
+An example passes only when **all its expected results and its enclosing law**
+pass. Expected results are authored specifications, never inferred by executing
+your adapter. They apply to that example's inputs; randomized and boundary tests
+continue to check the general law. Generated assertions show compared values and
+identify the example, input bindings and expression. A failing assertion stops
+that individual test; other tests remain independent.
+
+This is an intentional syntax break from 0.3: input-only examples are rejected,
+and `expect` is now a reserved keyword. Laws can still omit examples altogether.
+For an existing input-only example, retain its bindings and add the intended
+result before `end`:
+
+```lawspec
+example `zero renders as 0 and round-trips unchanged` is
+  x = 0
+  expect itoa x = "0"
+  expect atoi (itoa x) = 0
+end
+```
+
+Update every example before running `check` or `generate`. Use
+`npx lawspec explain` to inspect the law expansion, example inputs and expected
+results; this command displays the specification without executing adapters.
+Existing implementation adapters remain user-owned and are never overwritten.
+The historical `scratch.md` is a design draft, not the current syntax reference.
+
 ## Comparing alternative implementations
 
 `equivalent` compares two functions with the same input and output types. Its
@@ -189,8 +228,10 @@ law `decimal renderers agree` is
   definition is
     `equivalent` render referenceRender
   end
-  example `negative integer` is
+  example `both renderers produce a negative decimal string` is
     x = -42
+    expect render x = "-42"
+    expect referenceRender x = "-42"
   end
 end
 ```
@@ -199,7 +240,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](https://github.com/brain-fuel/lawspec/blob/v0.2.1/examples/specs/equivalent.lawspec) compares decimal
+[The complete example](https://github.com/brain-fuel/lawspec/blob/v0.4.0/examples/specs/equivalent.lawspec) compares decimal
 renderers and two implementations that clamp negative integers to zero. For
 JavaScript, their adapters can be:
 
@@ -212,9 +253,91 @@ 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.
+breaks each alternative separately to verify detection. The general equivalence law alone does not establish independent correctness;
+two implementations can share the same bug. Explicit expectations additionally
+check the specified outputs at the supplied example inputs. 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 `spaces become hyphens; punctuation is preserved` is
+    x = "Hello, World!"
+    expect normalize x = "Hello,-World!"
+    expect referenceNormalize x = "Hello,-World!"
+  end
+end
+```
+
+The [slug example](https://github.com/brain-fuel/lawspec/blob/v0.4.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
+  example `all trailing slashes are removed in one pass` is
+    x = "https://example.com/path///"
+    expect canonicalize x = "https://example.com/path"
+  end
+end
+```
+
+The [canonical URL example](https://github.com/brain-fuel/lawspec/blob/v0.4.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.4.0/examples/specs/mixed_inputs.lawspec)
+shows `Text` and `Int32` in the same quantified property and executable example.
+The JavaScript API represents input bindings and expected values as `number | string`.
+Each example includes `expectations: { actual: Expr; expected: 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
 
@@ -255,7 +378,7 @@ 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`.
+`npm pack ./npm` and install it with `npm install --save-dev ./lawspec-0.4.0.tgz`.
 The package payload lives in `npm/`.
 
 ```sh

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];
@@ -150,20 +151,70 @@ async function init() {
     `Configured ${language}. ${hasBuild ? "Existing build files preserved." : "Created missing project build files."}\n${setup[language]}\nNext: lawspec doctor, then lawspec generate.`,
   );
 }
+function showExpression(expr) {
+  const value = expr.contents;
+  if (expr.tag === "Var") return value;
+  if (expr.tag === "Number" || expr.tag === "StringLit")
+    return JSON.stringify(value);
+  if (expr.tag === "Apply")
+    return `${showExpression(value[0])} (${showExpression(value[1])})`;
+  return `(${showExpression(value[0])} . ${showExpression(value[1])})`;
+}
+function explainExamples(law) {
+  return law.original.examples
+    .map(
+      (ex) =>
+        `\nexample ${JSON.stringify(ex.exampleName)}\n` +
+        ex.bindings
+          .map(([n, v]) => `  ${n} = ${JSON.stringify(v)}`)
+          .join("\n") +
+        "\n" +
+        ex.expectations
+          .map(
+            (e) =>
+              `  expect ${showExpression(e.actual)} = ${JSON.stringify(e.expected)}`,
+          )
+          .join("\n"),
+    )
+    .join("\n");
+}
 async function main() {
   if (!verb || ["help", "--help", "-h"].includes(verb)) {
     output(
-      "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: " +
+      "LawSpec 0.4.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.1");
+    output("0.4.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}`);
@@ -226,7 +277,7 @@ async function main() {
         : indices
             .map(
               ({ e, i }) =>
-                `${e.owner}::${e.name}\n${e.trace.join("\n=> ")}\n=> ${result.expansions[i]}`,
+                `${e.owner}::${e.name}\n${e.trace.join("\n=> ")}\n=> ${result.expansions[i]}${explainExamples(e)}`,
             )
             .join("\n\n"),
     );

package/build.json

@@ -17,23 +17,23 @@
     "wasm/lawspec-wasm.cabal"
   ],
   "digests": {
-    "package.yaml": "2cc5254bf0c1de94adbb98ee193dd45f5d8e5efced9ce255508112ccbca96793",
+    "package.yaml": "2c1176c912901bd218743a88df1b67fb1ee8d58ed73fcbe7e2f23827f10a3a0f",
     "src/LawSpec/Api.hs": "00b1e4bc81231ebd387f10652463904084ebf9c3c4486fd2c2217a6d4dbfc157",
-    "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": "f04078dbc03eb793f9f3343db562cf56f84b5fbe6fd4aea6481bad38a7c6f328",
+    "src/LawSpec/Compile.hs": "336eca415ed6c8594612ad5acfc7ff6f29ef387cf3cb374b60b2407f811c31c7",
+    "src/LawSpec/Emit.hs": "2e23ca38aa5c4c65305283705633209843dd6ba116c43ba8a42ee8731040f7c3",
+    "src/LawSpec/Gen.hs": "305d7710dbc69b25d95fa6c0ac9a59622481f6b89682c1e5c9048def3962315a",
+    "src/LawSpec/Model.hs": "d1eda2b420edbc327b1adbf437c6f39a9e576ef0ab9b82f468c28202a433eb96",
+    "src/LawSpec/Parser.hs": "7fef1876c52d2204f852704150288910bb0c12bcde1d3159219ad25526a879b6",
+    "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": "139de82d2d6063eb82fc86438a82e59d9b9315318009cad199f488bca14cb56d",
-    "npm/core.wasm": "943abf2084a7395ef6c5441ef4fd93aa0d57e581a0e71723bf6187afa2c3b48c",
+    "wasm/lawspec-wasm.cabal": "098f1d0fc52575907312c95095846d1d4f6e7ace7cfbe0419a305b9fe8a75a92",
+    "npm/core.wasm": "0a4ce15cefcd866cd7dd584c32d683c7f8a46823104afcceba1298570883a88a",
     "npm/core_jsffi.js": "88d136efe92f7cff5758c8fec8d9b6bbc9707fe37741cebeeb415fe34ce3d72b",
     "npm/api.mjs": "d6df654600172131ac66a55b86876fc29cde2a76a0a63bbefff3183488a4837b",
-    "npm/index.d.ts": "8003304d88dbb01a07bd3dbdc4d680a193db1ec323c5712b9860e166ca9cc94b"
+    "npm/index.d.ts": "85ad409ae09d243d3b3f21243d0784390d7b0209e2a09fc7c3b733e8dd2e8765"
   }
 }

package/examples/specs/atoi_codec.lawspec

@@ -16,12 +16,16 @@ law `itoa and then atoi yields a` is
     "representing an Int32 as Text must not change its value"
   end
 
-  example `negative integer` is
+  example `negative integers use a minus sign and round-trip unchanged` is
     x = -42
+    expect itoa x = "-42"
+    expect atoi (itoa x) = -42
   end
 
-  example `zero` is
+  example `zero renders as 0 and round-trips unchanged` is
     x = 0
+    expect itoa x = "0"
+    expect atoi (itoa x) = 0
   end
 
   references are

package/examples/specs/canonical_url.lawspec

@@ -0,0 +1,24 @@
+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 `all trailing slashes are removed in one pass` is
+    x = "https://example.com/path///"
+    expect canonicalize x = "https://example.com/path"
+  end
+  example `a URL without trailing slashes stays unchanged` is
+    x = "https://example.com/path"
+    expect canonicalize x = "https://example.com/path"
+  end
+  example `empty input remains empty` is
+    x = ""
+    expect canonicalize x = ""
+  end
+end

package/examples/specs/equivalent.lawspec

@@ -15,11 +15,15 @@ law `decimal renderers agree` is
   rationale is
     "changing the formatting implementation must preserve its result"
   end
-  example `negative integer` is
+  example `both renderers produce "-42"` is
     x = -42
+    expect render x = "-42"
+    expect referenceRender x = "-42"
   end
-  example `zero` is
+  example `both renderers produce "0"` is
     x = 0
+    expect render x = "0"
+    expect referenceRender x = "0"
   end
 end
 
@@ -30,10 +34,14 @@ law `nonnegative clamps agree` is
   description is
     "{clamp} agrees with {referenceClamp} when clamping negative inputs to zero"
   end
-  example `negative boundary` is
+  example `both clamps return 0 for -2147483648` is
     x = -2147483648
+    expect clamp x = 0
+    expect referenceClamp x = 0
   end
-  example `positive boundary` is
+  example `both clamps return 2147483647 for 2147483647` is
     x = 2147483647
+    expect clamp x = 2147483647
+    expect referenceClamp x = 2147483647
   end
 end

package/examples/specs/mixed_inputs.lawspec

@@ -0,0 +1,41 @@
+unit example.mixed.inputs
+
+normalize :: Text -> Text
+identity :: Int32 -> Int32
+
+law `text normalization reaches a fixed point with an unused integer input` is
+  definition is
+    `for all` (text :: Text) (number :: Int32) .
+      normalize text = normalize (normalize text)
+  end
+  example `text normalization and integer identity have explicit results` is
+    text = "Hello, World!"
+    number = -42
+    expect normalize text = "Hello,-World!"
+    expect identity number = -42
+  end
+end
+
+law `integer identity with an unused text input` is
+  definition is
+    `for all` (text :: Text) (number :: Int32) .
+      identity number = number
+  end
+  example `text normalization and integer identity have explicit results` is
+    text = "λ 😀"
+    number = 2147483647
+    expect normalize text = "λ-😀"
+    expect identity number = 2147483647
+  end
+end
+
+law `normalizing an empty literal` is
+  definition is
+    `for all` (text :: Text) .
+      normalize "" = ""
+  end
+  example `empty literal stays empty; quantified text is unused` is
+    text = "unused context"
+    expect normalize "" = ""
+  end
+end

package/examples/specs/slug.lawspec

@@ -0,0 +1,33 @@
+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 `spaces become hyphens; punctuation is preserved` is
+    x = "Hello, World!"
+    expect normalize x = "Hello,-World!"
+    expect referenceNormalize x = "Hello,-World!"
+  end
+  example `empty text remains empty` is
+    x = ""
+    expect normalize x = ""
+    expect referenceNormalize x = ""
+  end
+  example `Unicode is preserved while spaces become hyphens` is
+    x = "café 日本語 😀"
+    expect normalize x = "café-日本語-😀"
+    expect referenceNormalize x = "café-日本語-😀"
+  end
+  example `quotes, backslashes and controls survive space replacement` is
+    x = "quote: \" slash: \\ newline: \n tab: \t dollar: $"
+    expect normalize x = "quote:-\"-slash:-\\-newline:-\n-tab:-\t-dollar:-$"
+    expect referenceNormalize 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,10 @@ 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 Expectation { actual: Expr; expected: number | string }
+export interface Example { exampleName: string; bindings: [string, number | string][]; expectations: Expectation[] }
 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.1",
+  "version": "0.4.0",
   "description": "State the law once. Check it everywhere.",
   "license": "MIT",
   "type": "module",

package/starter.lawspec

@@ -16,12 +16,16 @@ law `itoa and then atoi yields a` is
     "representing an Int32 as Text must not change its value"
   end
 
-  example `negative integer` is
+  example `negative integers use a minus sign and round-trip unchanged` is
     x = -42
+    expect itoa x = "-42"
+    expect atoi (itoa x) = -42
   end
 
-  example `zero` is
+  example `zero renders as 0 and round-trips unchanged` is
     x = 0
+    expect itoa x = "0"
+    expect atoi (itoa x) = 0
   end
 
   references are