lawspec 0.1.0

package/files.mjs

@@ -0,0 +1,172 @@
+import {
+  readFile,
+  mkdir,
+  writeFile,
+  rename,
+  unlink,
+  lstat,
+  realpath,
+  link,
+} from "node:fs/promises";
+import path from "node:path";
+import crypto from "node:crypto";
+export const digest = (text) =>
+  crypto.createHash("sha256").update(text).digest("hex");
+export async function readOptional(file) {
+  try {
+    return await readFile(file, "utf8");
+  } catch (e) {
+    if (e.code === "ENOENT") return null;
+    throw e;
+  }
+}
+export async function safePath(root, relative) {
+  if (
+    typeof relative !== "string" ||
+    !relative ||
+    path.isAbsolute(relative) ||
+    relative.split(/[\\/]/).some((p) => p === ".." || p === ".")
+  )
+    throw new Error(`Unsafe output path: ${relative}`);
+  const resolved = path.resolve(root, relative);
+  if (!resolved.startsWith(path.resolve(root) + path.sep))
+    throw new Error(`Output escapes project: ${relative}`);
+  const realRoot = await realpath(root);
+  let cursor = root;
+  for (const part of relative.split("/")) {
+    cursor = path.join(cursor, part);
+    try {
+      const stat = await lstat(cursor);
+      if (stat.isSymbolicLink())
+        throw new Error(`Refusing symbolic-link output: ${relative}`);
+      const real = await realpath(cursor);
+      if (real !== realRoot && !real.startsWith(realRoot + path.sep))
+        throw new Error(`Output escapes project: ${relative}`);
+    } catch (e) {
+      if (e.code !== "ENOENT") throw e;
+    }
+  }
+  return resolved;
+}
+export async function atomicWrite(file, content, exclusive = false) {
+  await mkdir(path.dirname(file), { recursive: true });
+  const tmp = `${file}.lawspec-${crypto.randomUUID()}.tmp`;
+  try {
+    await writeFile(tmp, content, { flag: "wx" });
+    if (exclusive) await link(tmp, file);
+    else await rename(tmp, file);
+  } finally {
+    try {
+      await unlink(tmp);
+    } catch (e) {
+      if (e.code !== "ENOENT") throw e;
+    }
+  }
+}
+export async function planWrites(root, artifacts) {
+  const manifestPath = await safePath(root, ".lawspec/generated.json");
+  const previousText = await readOptional(manifestPath);
+  const previous =
+    previousText === null
+      ? { version: 1, files: {} }
+      : JSON.parse(previousText);
+  if (
+    previous.version !== 1 ||
+    !previous.files ||
+    typeof previous.files !== "object"
+  )
+    throw new Error("Invalid ownership manifest");
+  const seen = new Set();
+  const changes = [];
+  const preserved = [];
+  const adapterUpdates = [];
+  const adapterHashes = {};
+  const next = {};
+  for (const artifact of artifacts) {
+    if (seen.has(artifact.path))
+      throw new Error(`Duplicate output: ${artifact.path}`);
+    seen.add(artifact.path);
+    const file = await safePath(root, artifact.path);
+    const old = await readOptional(file);
+    if (artifact.ownership === "user") {
+      adapterHashes[artifact.path] = digest(artifact.content);
+      if (
+        old !== null &&
+        previous.adapters?.[artifact.path] !== adapterHashes[artifact.path]
+      )
+        adapterUpdates.push({
+          path: artifact.path,
+          requiredAdapter: artifact.content,
+        });
+      if (old === null)
+        changes.push({
+          action: "create",
+          file,
+          relative: artifact.path,
+          content: artifact.content,
+          expected: null,
+        });
+      else preserved.push(artifact.path);
+      continue;
+    }
+    if (artifact.ownership !== "generated")
+      throw new Error("Unknown artifact ownership");
+    const recorded = previous.files[artifact.path];
+    if (old !== null && (!recorded || digest(old) !== recorded))
+      throw new Error(
+        `Refusing to overwrite unowned or edited generated file: ${artifact.path}`,
+      );
+    next[artifact.path] = digest(artifact.content);
+    if (old !== artifact.content)
+      changes.push({
+        action: old === null ? "create" : "update",
+        file,
+        relative: artifact.path,
+        content: artifact.content,
+        expected: old,
+      });
+  }
+  for (const [relative, hash] of Object.entries(previous.files)) {
+    if (seen.has(relative)) continue;
+    const file = await safePath(root, relative);
+    const old = await readOptional(file);
+    if (old === null) continue;
+    if (digest(old) !== hash)
+      throw new Error(`Refusing to remove edited generated file: ${relative}`);
+    changes.push({ action: "remove", file, relative, expected: old });
+  }
+  const manifest =
+    JSON.stringify(
+      { version: 1, files: next, adapters: adapterHashes },
+      null,
+      2,
+    ) + "\n";
+  if (manifest !== previousText)
+    changes.push({
+      action: previousText === null ? "create" : "update",
+      file: manifestPath,
+      relative: ".lawspec/generated.json",
+      content: manifest,
+      expected: previousText,
+    });
+  return { root, changes, preserved, adapterUpdates };
+}
+export async function applyWrites(plans) {
+  // Recheck every file before the first mutation, including concurrent edits since planning.
+  for (const plan of plans)
+    for (const change of plan.changes) {
+      await safePath(plan.root, change.relative);
+      if ((await readOptional(change.file)) !== change.expected)
+        throw new Error(`File changed during generation: ${change.relative}`);
+    }
+  for (const plan of plans)
+    for (const change of plan.changes) {
+      if (change.action === "remove") await unlink(change.file);
+      else
+        await atomicWrite(
+          change.file,
+          change.content,
+          change.action === "create",
+        );
+    }
+}

package/index.d.ts

@@ -0,0 +1,17 @@
+// Generated from LawSpec.Gen. Do not edit.
+export type Target = 'java' | 'python' | 'javascript' | 'typescript' | 'go' | 'haskell' | 'kotlin';
+export interface Source { path: string; content: string }
+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 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 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[] }
+export interface GenerationRequest extends CheckRequest { target: Target; sourceDir?: string; testDir?: string }
+export interface Result { diagnostics: Diagnostic[]; laws?: Expanded[]; expansions?: string[]; files?: Artifact[] }
+export interface Compiler { check(input: CheckRequest): Promise<Result>; expand(input: CheckRequest): Promise<Result>; planGeneration(input: GenerationRequest): Promise<Result> }
+export function createCompiler(): Promise<Compiler>;

package/launcher.mjs

@@ -0,0 +1,32 @@
+import { readFile } from "node:fs/promises";
+let compiled;
+export async function loadCore() {
+  const { WASI } = await import("node:wasi");
+  if (Number(process.versions.node.split(".")[0]) < 22)
+    throw new Error("LawSpec requires Node 22+");
+  compiled ??= readFile(new URL("./core.wasm", import.meta.url)).then(
+    WebAssembly.compile,
+  );
+  const wasi = new WASI({
+    version: "preview1",
+    args: ["lawspec"],
+    env: { PWD: "/" },
+    preopens: { "/": process.cwd() },
+  });
+  const exports = {};
+  const jsffi = (await import("./core_jsffi.js")).default;
+  const instance = await WebAssembly.instantiate(await compiled, {
+    wasi_snapshot_preview1: wasi.wasiImport,
+    ghc_wasm_jsffi: jsffi(exports),
+  });
+  Object.assign(exports, instance.exports);
+  wasi.initialize(instance);
+  let pending = Promise.resolve();
+  return (input) => {
+    const result = pending.then(async () =>
+      JSON.parse(await instance.exports.lawspec_call(JSON.stringify(input))),
+    );
+    pending = result.catch(() => {});
+    return result;
+  };
+}

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "lawspec",
+  "version": "0.1.0",
+  "description": "State the law once. Check it everywhere.",
+  "license": "MIT",
+  "type": "module",
+  "engines": { "node": ">=22" },
+  "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"],
+  "scripts": { "test": "node --test test/*.test.mjs" }
+}

package/read-only-hpack.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { readdirSync } from "node:fs";
+if (process.argv.some((a) => a === "--numeric-version" || a === "--version"))
+  console.log("0.38.1");
+else if (!readdirSync(process.cwd()).some((f) => f.endsWith(".cabal"))) {
+  console.error(
+    "LawSpec doctor requires an existing .cabal file. Run stack build --test --no-run-tests first.",
+  );
+  process.exitCode = 1;
+}

package/starter.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/templates.mjs

@@ -0,0 +1,112 @@
+export const targets = [
+  "java",
+  "python",
+  "javascript",
+  "typescript",
+  "go",
+  "haskell",
+  "kotlin",
+];
+export const commands = {
+  java: "mvn test",
+  python: "python -m pytest",
+  javascript: "node --test test/*.test.mjs",
+  typescript:
+    "npm exec -- tsc -p tsconfig.json && node --test dist/test/*.test.js",
+  go: "go test ./...",
+  haskell: "stack test",
+  kotlin: "gradle test",
+};
+export const setup = {
+  java: "Use JDK 25+, Maven, JetCheck 0.3.0, JUnit Jupiter 5.14.x, compiler plugin 3.14.1+, Surefire 3.5.x, and maven.compiler.release=25. Run mvn test-compile.",
+  python:
+    'Use Python 3.13+. Install pytest 8.4.x and Hypothesis 6.x into the selected environment: python -m pip install -e ".[test]". Configure pytest pythonpath=["src"] and testpaths=["tests"]. Set the target python field to the interpreter path if needed.',
+  javascript:
+    "Use Node 22+, package.json type=module, and npm install --save-dev fast-check@4.10.2.",
+  typescript:
+    'Use Node 22+, package.json type=module, and npm install --save-dev fast-check@4.10.2 typescript@5.9.3 @types/node@22.20.4. Configure tsconfig.json with module=NodeNext, target=ES2022, rootDir=., outDir=dist, include=["src/**/*.ts","test/**/*.ts"].',
+  go: "Use Go 1.22+ and go get pgregory.net/rapid@v1.2.0, then go mod download.",
+  haskell:
+    "Use Stack with lts-24.58 and test dependencies hspec, hedgehog, hspec-hedgehog, hspec-discover, and a test/Spec.hs using hspec-discover. Run stack build --test --no-run-tests.",
+  kotlin:
+    "Use JDK 25, Gradle 9.3.0, Kotlin plugin 2.3.21, JVM target 25, Kotest 5.9.1 (runner, assertions, property), and useJUnitPlatform(). Run gradle testClasses.",
+};
+const json = (value) => JSON.stringify(value, null, 2) + "\n";
+export function templates(target) {
+  if (!targets.includes(target)) throw new Error(`Unknown target: ${target}`);
+  const commonPackage = {
+    name: "lawspec-example",
+    version: "0.1.0",
+    private: true,
+    type: "module",
+  };
+  switch (target) {
+    case "javascript":
+      return {
+        "package.json": json({
+          ...commonPackage,
+          scripts: { test: commands.javascript },
+          devDependencies: { "fast-check": "4.10.2" },
+        }),
+      };
+    case "typescript":
+      return {
+        "package.json": json({
+          ...commonPackage,
+          scripts: { test: commands.typescript },
+          devDependencies: {
+            "fast-check": "4.10.2",
+            typescript: "5.9.3",
+            "@types/node": "22.20.4",
+          },
+        }),
+        "tsconfig.json": json({
+          compilerOptions: {
+            target: "ES2022",
+            module: "NodeNext",
+            rootDir: ".",
+            outDir: "dist",
+            strict: true,
+            esModuleInterop: true,
+            skipLibCheck: true,
+          },
+          include: ["src/**/*.ts", "test/**/*.ts"],
+        }),
+      };
+    case "python":
+      return {
+        "pyproject.toml": `[build-system]\nrequires = ["setuptools==80.9.0"]\nbuild-backend = "setuptools.build_meta"\n\n[project]\nname = "lawspec-example"\nversion = "0.1.0"\nrequires-python = ">=3.13"\n\n[project.optional-dependencies]\ntest = ["pytest==8.4.2", "hypothesis==6.135.26"]\n\n[tool.setuptools.packages.find]\nwhere = ["src"]\n\n[tool.pytest.ini_options]\npythonpath = ["src"]\ntestpaths = ["tests"]\n`,
+      };
+    case "java":
+      return {
+        "pom.xml": `<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion><groupId>example</groupId><artifactId>lawspec-example</artifactId><version>0.1.0</version>
+  <properties><maven.compiler.release>25</maven.compiler.release><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding></properties>
+  <dependencies>
+    <dependency><groupId>org.jetbrains</groupId><artifactId>jetCheck</artifactId><version>0.3.0</version><scope>test</scope></dependency>
+    <dependency><groupId>org.junit.jupiter</groupId><artifactId>junit-jupiter</artifactId><version>5.14.0</version><scope>test</scope></dependency>
+  </dependencies>
+  <build><plugins>
+    <plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><version>3.14.1</version></plugin>
+    <plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-surefire-plugin</artifactId><version>3.5.4</version></plugin>
+  </plugins></build>
+</project>\n`,
+      };
+    case "go":
+      return {
+        "go.mod":
+          "module example.com/lawspec-example\n\ngo 1.22\n\nrequire pgregory.net/rapid v1.2.0\n",
+      };
+    case "haskell":
+      return {
+        "stack.yaml": "snapshot: lts-24.58\npackages: [.]\n",
+        "package.yaml": `name: lawspec-example\nversion: 0.1.0\ndependencies: [base, text]\nlibrary:\n  source-dirs: src\ntests:\n  laws:\n    main: Spec.hs\n    source-dirs: test\n    dependencies: [lawspec-example, hspec, hedgehog, hspec-hedgehog]\n    build-tools: [hspec-discover]\n`,
+        "test/Spec.hs": "{-# OPTIONS_GHC -F -pgmF hspec-discover #-}\n",
+      };
+    case "kotlin":
+      return {
+        "settings.gradle.kts": 'rootProject.name = "lawspec-example"\n',
+        "build.gradle.kts": `plugins { kotlin("jvm") version "2.3.21" }\nrepositories { mavenCentral() }\nkotlin { jvmToolchain(25) }\ndependencies {\n  testImplementation("io.kotest:kotest-runner-junit5:5.9.1")\n  testImplementation("io.kotest:kotest-assertions-core:5.9.1")\n  testImplementation("io.kotest:kotest-property:5.9.1")\n}\ntasks.test { useJUnitPlatform() }\n`,
+      };
+  }
+}