lawspec 0.9.0 → 0.11.0

package/examples/specs/indexed_families.lawspec

@@ -0,0 +1,59 @@
+unit example.indexed
+
+-- A list indexed by its length. Each constructor states how it changes the
+-- index; nOfVec is the checked measure that recomputes it from a value.
+type Vec (n :: Natural) (a :: Type) is
+  | VNil where n = 0
+  | VCons head :: a tail :: Vec m a where n = m + 1
+end
+
+-- A binary tree indexed by its number of values.
+type Tree (n :: Natural) (a :: Type) is
+  | Tip where n = 0
+  | Bin left :: Tree l a value :: a right :: Tree r a where n = l + r + 1
+end
+
+-- Result indices are checked contracts over the native implementations.
+replicate :: (n :: Natural where n < 64) -> (x :: Int8) -> (r :: Vec n Int8)
+append :: (xs :: Vec n Int8) -> (ys :: Vec m Int8) -> (r :: Vec (n + m) Int8)
+zip :: (xs :: Vec n Int8) -> (ys :: Vec n Bool) -> (r :: Vec n Bool)
+flatten :: (tree :: Tree n Int8) -> (r :: Vec n Int8)
+
+law `replicate has the requested length` is
+  definition is
+    `for all` (n :: Natural where n < 16) (x :: Int8) . nOfVec (replicate n x) = n
+  end
+  example `three copies` is
+    n = 3
+    x = 7
+    expect nOfVec (replicate n x) = 3
+  end
+end
+
+law `append adds lengths` is
+  definition is
+    `for all` (xs :: Vec n Int8) (ys :: Vec m Int8) .
+      nOfVec (append xs ys) = n + m
+  end
+end
+
+-- A fixed index is generated directly rather than filtered.
+law `vectors of three elements` is
+  definition is
+    `for all` (xs :: Vec 3 Int8) . nOfVec (append xs xs) = 6
+  end
+end
+
+-- A shared index constrains the second input by the first.
+law `zip preserves a shared length` is
+  definition is
+    `for all` (xs :: Vec n Int8) (ys :: Vec n Bool) . nOfVec (zip xs ys) = n
+  end
+end
+
+-- Generation splits the remaining index across both subtrees.
+law `flattening five values` is
+  definition is
+    `for all` (tree :: Tree 5 Int8) . nOfVec (flatten tree) = 5
+  end
+end

package/examples/specs/payments.lawspec

@@ -0,0 +1,76 @@
+unit example.payments
+
+-- The executable acceptance model for native domain bindings in 0.10.
+-- Applications may call Money "Price", amount "major", and currency "unit";
+-- those representation choices must not alter these laws.
+type Currency is USD | EUR | GBP end
+
+type Money is
+  Money amount :: Decimal currency :: Currency
+end
+
+type Payment is
+  Paid value :: Money
+  Declined reason :: Text
+end
+
+-- These are adapter functions supplied by the application.
+addFee :: Money -> Money
+roundTrip :: Payment -> Payment
+archive :: List (Maybe Payment) -> List (Maybe Payment)
+
+-- The model is exact, independent of host decimal rounding settings.
+definition feeModel (money :: Money) :: Money is
+  match money with
+    | Money amount currency -> Money (amount + 0.2) currency
+  end
+end
+
+law `fees preserve currency and exact decimal value` is
+  definition is
+    `for all` (money :: Money) . addFee money = feeModel money
+  end
+  example `decimal tenths` is
+    money = Money 0.1 USD
+    expect addFee money = Money 0.3 USD
+  end
+  example `small amount is not rounded away` is
+    money = Money 0.000000000000000000000000000001 EUR
+    expect addFee money = Money 0.200000000000000000000000000001 EUR
+  end
+  example `beyond binary floating precision` is
+    money = Money 9007199254740993.1 GBP
+    expect addFee money = Money 9007199254740993.3 GBP
+  end
+end
+
+law `payment variants and payloads survive native conversion` is
+  definition is
+    `for all` (payment :: Payment) . roundTrip payment = payment
+  end
+  example `successful payment` is
+    payment = Paid (Money 12.34 EUR)
+    expect roundTrip payment = Paid (Money 12.34 EUR)
+  end
+  example `declined payment` is
+    payment = Declined "card declined"
+    expect roundTrip payment = Declined "card declined"
+  end
+end
+
+law `archives preserve order duplicates and absence` is
+  definition is
+    `for all` (payments :: List (Maybe Payment)) . archive payments = payments
+  end
+  example `empty archive` is
+    payments = []
+    expect archive payments = []
+  end
+  example `missing is different from a declined payment` is
+    payments = [Nothing, Just (Declined ""), Just (Paid (Money 0.1 USD)),
+                Just (Paid (Money 0.1 USD))]
+    expect archive payments = [Nothing, Just (Declined ""),
+                              Just (Paid (Money 0.1 USD)),
+                              Just (Paid (Money 0.1 USD))]
+  end
+end

package/examples-command.mjs

@@ -3,11 +3,16 @@ import path from "node:path";
 import { createCompiler } from "./api.mjs";
 import { targets } from "./templates.mjs";
 import { safePath, planWrites, applyWrites } from "./files.mjs";
+import { exportNativePayments } from "./native-examples.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}`);
+  if (options.example !== undefined) {
+    if (options.example !== "payments") throw new Error(`Unknown example: ${options.example}`);
+    return exportNativePayments(options, selected);
+  }
   const directory = new URL("./examples/specs/", import.meta.url);
   const sources = await Promise.all(
     (await readdir(directory))

package/files.mjs

@@ -63,8 +63,8 @@ export async function atomicWrite(file, content, exclusive = false) {
     }
   }
 }
-export async function planWrites(root, artifacts) {
-  const manifestPath = await safePath(root, ".lawspec/generated.json");
+export async function planWrites(root, artifacts, {manifest = ".lawspec/generated.json"} = {}) {
+  const manifestPath = await safePath(root, manifest);
   const previousText = await readOptional(manifestPath);
   const previous =
     previousText === null
@@ -144,18 +144,18 @@ export async function planWrites(root, artifacts) {
       throw new Error(`Refusing to remove edited generated file: ${relative}`);
     changes.push({ action: "remove", file, relative, expected: old });
   }
-  const manifest =
+  const manifestContent =
     JSON.stringify(
       { version: 1, files: next, adapters: adapterHashes },
       null,
       2,
     ) + "\n";
-  if (manifest !== previousText)
+  if (manifestContent !== previousText)
     changes.push({
       action: previousText === null ? "create" : "update",
       file: manifestPath,
-      relative: ".lawspec/generated.json",
-      content: manifest,
+      relative: manifest,
+      content: manifestContent,
       expected: previousText,
     });
   return { root, changes, preserved, adapterUpdates };

package/index.d.ts

@@ -162,11 +162,62 @@ export interface Refinement {
   definition: string;
 }
 
+export type NativeReference = string[];
+
+export interface NativeFieldBinding {
+  field: string;
+  native: string;
+}
+
+export interface NativeConstructorBinding {
+  constructor: string;
+  native: NativeReference;
+  fields?: NativeFieldBinding[];
+  style: 'record' | 'variant' | 'unit';
+}
+
+export interface NativeCodecBinding {
+  toNative: NativeReference;
+  fromNative: NativeReference;
+}
+
+export interface NativeTypeBinding {
+  type: string;
+  native: NativeReference;
+  constructors?: NativeConstructorBinding[];
+  codec?: NativeCodecBinding;
+}
+
+export interface NativeGeneratorBinding {
+  type: string;
+  factory: NativeReference;
+  stub?: boolean;
+}
+
+export interface NativeFunctionBinding {
+  declaration: string;
+  native: NativeReference;
+}
+
+export interface NativeGoImport {
+  alias: string;
+  path: string;
+}
+
+export interface NativeBindings {
+  types?: NativeTypeBinding[];
+  generators?: NativeGeneratorBinding[];
+  functions?: NativeFunctionBinding[];
+  rustCrate?: string;
+  goImports?: NativeGoImport[];
+}
+
 export interface CheckRequest {
   sources: Source[];
-  schemaVersion?: 3;
+  schemaVersion?: 3 | 4;
   machineBits?: 32 | 64;
   generation?: Partial<Generation>;
+  nativeBindings?: NativeBindings;
 }
 
 export interface GenerationRequest extends CheckRequest {
@@ -177,7 +228,7 @@ export interface GenerationRequest extends CheckRequest {
 }
 
 export interface Result {
-  schemaVersion: 3;
+  schemaVersion: 3 | 4;
   machineBits?: 32 | 64;
   generation?: Generation;
   units?: Unit[];

package/native-examples.mjs

@@ -0,0 +1,81 @@
+import {readFile, readdir, mkdir} from 'node:fs/promises';
+import path from 'node:path';
+import {templates, commands, setup} from './templates.mjs';
+import {safePath, planWrites, applyWrites} from './files.mjs';
+
+async function projectFiles(directory, prefix = '') {
+  const files = {};
+  for (const entry of await readdir(directory, {withFileTypes: true})) {
+    const name = prefix + entry.name;
+    const location = new URL(entry.name + (entry.isDirectory() ? '/' : ''), directory);
+    if (entry.isDirectory()) Object.assign(files, await projectFiles(location, name + '/'));
+    else if (entry.isFile()) files[name] = await readFile(location, 'utf8');
+    else throw new Error(`Unsupported bundled example entry: ${name}`);
+  }
+  return files;
+}
+
+export async function exportNativePayments(options, selected) {
+  const root = await safePath(process.cwd(), options.output || 'native_payments');
+  await mkdir(root, {recursive: true});
+  const law = await readFile(new URL('./examples/specs/payments.lawspec', import.meta.url), 'utf8');
+  const plans = [];
+  const results = [];
+  for (const target of selected) {
+    const directory = await safePath(root, target);
+    await mkdir(directory, {recursive: true});
+    const files = {
+      ...templates(target, {minify: options.minify === true}),
+      ...await projectFiles(new URL(`./examples/native-payments/${target}/`, import.meta.url)),
+      'laws/payments.lawspec': law,
+    };
+    const config = JSON.parse(files['lawspec.json']);
+    config.machineBits = options.machineBits ?? 64;
+    files['lawspec.json'] = JSON.stringify(config, null, options.minify ? undefined : 2) + '\n';
+    files['README.md'] = `# Native payments: ${target}
+
+This project checks application-owned payment types against the shared LawSpec
+model. Money maps to Price, currency variants have application names, and the
+archive preserves distinct present and absent payments.
+
+## Run
+
+Install LawSpec and the native dependencies described below, then run:
+
+\`\`\`sh
+lawspec check
+lawspec generate
+${commands[target]}
+\`\`\`
+
+${setup[target]}
+
+JavaScript and TypeScript projects require \`npm install\` before testing.
+The specification includes exact decimal arithmetic and explicit USD/GBP examples.
+The native price generator deliberately samples only EUR values between 1.00 and
+2.00; examples and deterministic boundaries still check the other cases. Its
+framework's mapping operation preserves the native shrinker.
+
+The application types use native exact decimals where available and LawSpec's
+framework-independent numeric runtime otherwise. Run generation before compiling
+the application so that runtime support is present.
+
+## Change the application
+
+Edit the domain implementation or generator, then run the native tests again.
+For example, change the fee from 0.2 to 0.3: the exact-decimal law must fail.
+Edit \`lawspec.json\` to change native bindings and rerun \`lawspec generate\`.
+
+All exported project files are user-owned. Re-exporting preserves your edits;
+it reports changed bundled versions for review. Compiler-generated files use a
+separate ownership manifest and remain protected against accidental overwrites.
+`;
+    const artifacts = Object.entries(files).map(([path, content]) => ({path, content, ownership: 'user'}));
+    const plan = await planWrites(directory, artifacts, {manifest: '.lawspec/example.json'});
+    plans.push(plan);
+    results.push({target, directory, example: 'payments', files: artifacts.map(({path, ownership}) => ({path, ownership})),
+      changes: plan.changes.length, preservedAdapters: plan.preserved, adapterUpdates: plan.adapterUpdates});
+  }
+  await applyWrites(plans);
+  return results;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lawspec",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "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", "PRIMITIVES.md", "REFINEMENTS.md", "RUST.md", "JAVA.md", "PYTHON.md", "GO.md", "HASKELL.md", "KOTLIN.md", "WEB.md", "LANGUAGE.md", "API-MIGRATION.md", "RELEASE-0.9.md", "LICENSE", "starter.lawspec", "examples"],
+  "files": ["*.mjs", "*.json", "index.d.ts", "bin", "core.wasm", "core_jsffi.js", "README.md", "NATIVE-BINDINGS.md", "PRIMITIVES.md", "REFINEMENTS.md", "RUST.md", "JAVA.md", "PYTHON.md", "GO.md", "HASKELL.md", "KOTLIN.md", "WEB.md", "LANGUAGE.md", "API-MIGRATION.md", "RELEASE-0.9.md", "RELEASE-0.10.md", "RELEASE-0.11.md", "LICENSE", "starter.lawspec", "examples"],
   "scripts": { "test": "node --test test/*.test.mjs" }
 }