lawspec 0.9.0 → 0.10.0

package/examples/native-payments/rust/lawspec.json

@@ -0,0 +1,167 @@
+{
+  "version": 1,
+  "sources": [
+    "laws"
+  ],
+  "machineBits": 64,
+  "targets": [
+    {
+      "language": "rust",
+      "root": ".",
+      "nativeBindings": {
+        "rustCrate": "lawspec_example",
+        "types": [
+          {
+            "type": "example.payments::type::Currency",
+            "native": [
+              "crate",
+              "domain",
+              "CurrencyCode"
+            ],
+            "constructors": [
+              {
+                "constructor": "USD",
+                "native": [
+                  "crate",
+                  "domain",
+                  "CurrencyCode",
+                  "Dollars"
+                ],
+                "style": "unit",
+                "fields": []
+              },
+              {
+                "constructor": "EUR",
+                "native": [
+                  "crate",
+                  "domain",
+                  "CurrencyCode",
+                  "Euros"
+                ],
+                "style": "unit",
+                "fields": []
+              },
+              {
+                "constructor": "GBP",
+                "native": [
+                  "crate",
+                  "domain",
+                  "CurrencyCode",
+                  "Pounds"
+                ],
+                "style": "unit",
+                "fields": []
+              }
+            ]
+          },
+          {
+            "type": "example.payments::type::Money",
+            "native": [
+              "crate",
+              "domain",
+              "Price"
+            ],
+            "constructors": [
+              {
+                "constructor": "Money",
+                "native": [
+                  "crate",
+                  "domain",
+                  "Price"
+                ],
+                "style": "record",
+                "fields": [
+                  {
+                    "field": "amount",
+                    "native": "major"
+                  },
+                  {
+                    "field": "currency",
+                    "native": "unit"
+                  }
+                ]
+              }
+            ]
+          },
+          {
+            "type": "example.payments::type::Payment",
+            "native": [
+              "crate",
+              "domain",
+              "PaymentStatus"
+            ],
+            "constructors": [
+              {
+                "constructor": "Paid",
+                "native": [
+                  "crate",
+                  "domain",
+                  "PaymentStatus",
+                  "Settled"
+                ],
+                "style": "variant",
+                "fields": [
+                  {
+                    "field": "value",
+                    "native": "price"
+                  }
+                ]
+              },
+              {
+                "constructor": "Declined",
+                "native": [
+                  "crate",
+                  "domain",
+                  "PaymentStatus",
+                  "Rejected"
+                ],
+                "style": "variant",
+                "fields": [
+                  {
+                    "field": "reason",
+                    "native": "explanation"
+                  }
+                ]
+              }
+            ]
+          }
+        ],
+        "functions": [
+          {
+            "declaration": "example.payments::addFee",
+            "native": [
+              "crate",
+              "domain",
+              "apply_fee"
+            ]
+          },
+          {
+            "declaration": "example.payments::roundTrip",
+            "native": [
+              "crate",
+              "domain",
+              "restore"
+            ]
+          },
+          {
+            "declaration": "example.payments::archive",
+            "native": [
+              "crate",
+              "domain",
+              "store"
+            ]
+          }
+        ],
+        "generators": [
+          {
+            "type": "example.payments::type::Money",
+            "factory": [
+              "lawspec_generators",
+              "prices"
+            ]
+          }
+        ]
+      }
+    }
+  ]
+}

package/examples/native-payments/rust/src/domain.rs

@@ -0,0 +1,37 @@
+// Application-owned types: no dependency on generated lawspec_data types.
+use crate::lawspec_runtime::Decimal;
+
+#[derive(Clone, Debug)]
+pub enum CurrencyCode {
+    Dollars,
+    Euros,
+    Pounds,
+}
+
+#[derive(Clone, Debug)]
+pub struct Price {
+    pub major: Decimal,
+    pub unit: CurrencyCode,
+}
+
+#[derive(Clone, Debug)]
+pub enum PaymentStatus {
+    Settled { price: Price },
+    Rejected { explanation: String },
+}
+
+pub fn apply_fee(mut price: Price) -> Price {
+    price.major = price
+        .major
+        .add(&Decimal::new(2.into(), (-1).into()))
+        .unwrap();
+    price
+}
+
+pub fn restore(payment: PaymentStatus) -> PaymentStatus {
+    payment
+}
+
+pub fn store(payments: Vec<Option<PaymentStatus>>) -> Vec<Option<PaymentStatus>> {
+    payments
+}

package/examples/native-payments/rust/src/lib.rs

@@ -0,0 +1,2 @@
+include!("lawspec_modules.rs");
+pub mod domain;

package/examples/native-payments/rust/tests/support/lawspec_generators.rs

@@ -0,0 +1,11 @@
+use lawspec_example::domain::{CurrencyCode, Price};
+use lawspec_example::lawspec_runtime::Decimal;
+use proptest::prelude::*;
+
+// The native range strategy retains its shrinker through this mapping.
+pub fn prices() -> impl Strategy<Value = Price> {
+    (100i32..=200).prop_map(|cents| Price {
+        major: Decimal::new(cents.into(), (-2).into()),
+        unit: CurrencyCode::Euros,
+    })
+}

package/examples/native-payments/typescript/lawspec.json

@@ -0,0 +1,149 @@
+{
+  "version": 1,
+  "sources": [
+    "laws"
+  ],
+  "machineBits": 64,
+  "targets": [
+    {
+      "language": "typescript",
+      "root": ".",
+      "nativeBindings": {
+        "types": [
+          {
+            "type": "example.payments::type::Currency",
+            "native": [
+              "payments_domain",
+              "CurrencyCode"
+            ],
+            "constructors": [
+              {
+                "constructor": "USD",
+                "native": [
+                  "payments_domain",
+                  "Dollars"
+                ],
+                "style": "unit",
+                "fields": []
+              },
+              {
+                "constructor": "EUR",
+                "native": [
+                  "payments_domain",
+                  "Euros"
+                ],
+                "style": "unit",
+                "fields": []
+              },
+              {
+                "constructor": "GBP",
+                "native": [
+                  "payments_domain",
+                  "Pounds"
+                ],
+                "style": "unit",
+                "fields": []
+              }
+            ]
+          },
+          {
+            "type": "example.payments::type::Money",
+            "native": [
+              "payments_domain",
+              "Price"
+            ],
+            "constructors": [
+              {
+                "constructor": "Money",
+                "native": [
+                  "payments_domain",
+                  "Price"
+                ],
+                "style": "record",
+                "fields": [
+                  {
+                    "field": "amount",
+                    "native": "major"
+                  },
+                  {
+                    "field": "currency",
+                    "native": "unit"
+                  }
+                ]
+              }
+            ]
+          },
+          {
+            "type": "example.payments::type::Payment",
+            "native": [
+              "payments_domain",
+              "PaymentStatus"
+            ],
+            "constructors": [
+              {
+                "constructor": "Paid",
+                "native": [
+                  "payments_domain",
+                  "Settled"
+                ],
+                "style": "variant",
+                "fields": [
+                  {
+                    "field": "value",
+                    "native": "price"
+                  }
+                ]
+              },
+              {
+                "constructor": "Declined",
+                "native": [
+                  "payments_domain",
+                  "Rejected"
+                ],
+                "style": "variant",
+                "fields": [
+                  {
+                    "field": "reason",
+                    "native": "explanation"
+                  }
+                ]
+              }
+            ]
+          }
+        ],
+        "functions": [
+          {
+            "declaration": "example.payments::addFee",
+            "native": [
+              "payments_domain",
+              "apply_fee"
+            ]
+          },
+          {
+            "declaration": "example.payments::roundTrip",
+            "native": [
+              "payments_domain",
+              "restore"
+            ]
+          },
+          {
+            "declaration": "example.payments::archive",
+            "native": [
+              "payments_domain",
+              "store"
+            ]
+          }
+        ],
+        "generators": [
+          {
+            "type": "example.payments::type::Money",
+            "factory": [
+              "lawspec_generators",
+              "prices"
+            ]
+          }
+        ]
+      }
+    }
+  ]
+}

package/examples/native-payments/typescript/src/payments_domain.ts

@@ -0,0 +1,42 @@
+// Application-owned domain types; no generated domain declarations.
+import * as ls from './lawspec_runtime.js';
+
+export class CurrencyCode {}
+export class Dollars extends CurrencyCode {}
+export class Euros extends CurrencyCode {}
+export class Pounds extends CurrencyCode {}
+
+export class Price {
+  major: ls.Decimal;
+  unit: CurrencyCode;
+  constructor({unit, major}: {unit: CurrencyCode; major: ls.Decimal}) {
+    this.unit = unit;
+    this.major = major;
+  }
+}
+export class PaymentStatus {}
+export class Settled extends PaymentStatus {
+  price: Price;
+  constructor({price}: {price: Price}) {
+    super();
+    this.price = price;
+  }
+}
+export class Rejected extends PaymentStatus {
+  explanation: string;
+  constructor({explanation}: {explanation: string}) {
+    super();
+    this.explanation = explanation;
+  }
+}
+export function apply_fee(price: Price): Price {
+  const major = ls.binary('+', price.major, new ls.Decimal(2n, -1n),
+    'Decimal', 'Decimal') as ls.Decimal;
+  return new Price({major, unit: price.unit});
+}
+export function restore<T>(payment: T): T {
+  return payment;
+}
+export function store<T>(payments: T[]): T[] {
+  return payments;
+}

package/examples/native-payments/typescript/test/lawspec_generators.ts

@@ -0,0 +1,8 @@
+import * as fc from 'fast-check';
+import * as ls from '../src/lawspec_runtime.js';
+import {Price, Euros} from '../src/payments_domain.js';
+
+export function prices(): fc.Arbitrary<Price> {
+  return fc.integer({min:100, max:200}).map(cents =>
+    new Price({major:new ls.Decimal(BigInt(cents), -2n), unit:new Euros()}));
+}

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[];