lemmascript 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 midspiral
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,5 +1,103 @@
-# LemmaScript
+# LemmaScript (Tech Preview)
 
-A verification toolchain for TypeScript.
+A verification toolchain for TypeScript. Write ordinary TypeScript with `//@ ` specification annotations. The toolchain generates verified code from your TypeScript — either Lean 4 (with Velvet/Loom) or Dafny.
 
-Coming soon from [Midspiral](https://github.com/midspiral).
+See [SPEC.md](SPEC.md) for the full specification, [DESIGN.md](DESIGN.md) for the Lean backend design, and [DESIGN_DAFNY.md](DESIGN_DAFNY.md) for the Dafny backend design.
+
+This is a **Tech Preview**: the core idea is there, but support, semantics, and ergonomics are still evolving.
+
+## Case Studies
+
+Each case study is verified in both Lean 4 and Dafny from the same annotated TypeScript source.
+
+- **[colorwheel-lemmascript](https://github.com/midspiral/colorwheel-lemmascript/)** — verified color palette generator with mood + harmony constraints. 31 Lean proofs + 18 behavioral properties, 115 Dafny lemmas (invariant preservation, commutativity, NoOp completeness).
+- **[clear-split-lemmascript](https://github.com/midspiral/clear-split-lemmascript/)** — greenfield verified expense splitting web app. Conservation theorem, invariant preservation, delta laws — all proven in both Lean (no sorry) and Dafny (56 lemmas).
+- **[node-casbin-lemmascript](https://github.com/midspiral/node-casbin-lemmascript/blob/lemmascript/README_LemmaScript.md)** — brownfield verification of [node-casbin](https://github.com/casbin/node-casbin). 5 functions verified, 217 existing tests pass. End-to-end correctness and order independence for all 4 effect modes in both Lean and Dafny (39 lemmas).
+
+## Setup
+
+**Prerequisites:** Node.js >= 18. For the Lean backend: [elan](https://github.com/leanprover/elan). For the Dafny backend: [Dafny](https://github.com/dafny-lang/dafny) >= 4.x.
+
+**Install from npm:**
+
+```sh
+npm install lemmascript
+```
+
+**Or from source:**
+
+```sh
+git clone https://github.com/midspiral/LemmaScript.git
+cd LemmaScript && npm install && npm run build
+```
+
+**Lean backend** additionally requires the Loom and Velvet forks:
+
+```sh
+git clone https://github.com/namin/loom.git -b lemma ../loom
+git clone https://github.com/namin/velvet.git -b lemma ../velvet
+```
+
+## Usage
+
+### Lean backend (default)
+
+```sh
+npx lsc gen src/myModule.ts
+lake build
+```
+
+### Dafny backend
+
+```sh
+npx lsc gen --backend=dafny src/myModule.ts
+npx lsc check --backend=dafny src/myModule.ts
+npx lsc regen --backend=dafny src/myModule.ts
+```
+
+The Dafny backend generates two files per TS source: `foo.dfy.gen` (always regeneratable) and `foo.dfy` (source of truth, with LLM/user proof additions). The diff between them must be additions-only.
+
+## What's Supported
+
+### Annotations
+
+```typescript
+//@ requires arr.length > 0
+//@ ensures \result >= -1 && \result < arr.length
+//@ invariant 0 <= i && i <= arr.length
+//@ decreases arr.length - i
+//@ type i nat
+```
+
+## File Structure
+
+### Lean backend
+
+| File | Generated? | Purpose |
+|------|-----------|---------|
+| `foo.ts` | — | TypeScript source with `//@ ` annotations |
+| `foo.types.lean` | Yes | Lean types, `namespace Pure` defs |
+| `foo.spec.lean` | No | Ghost definitions, helper lemmas |
+| `foo.def.lean` | Yes | Velvet method definitions |
+| `foo.proof.lean` | No | `prove_correct` with proof tactics |
+
+### Dafny backend
+
+| File | Generated? | Purpose |
+|------|-----------|---------|
+| `foo.ts` | — | TypeScript source with `//@ ` annotations |
+| `foo.dfy.gen` | Yes | Generated Dafny (merge base, always regeneratable) |
+| `foo.dfy` | Yes (initial) | Annotated Dafny (gen + proof additions) |
+
+## Examples
+
+| Example | Pattern |
+|---------|---------|
+| `binarySearch` | Array search, break, Int arithmetic |
+| `linearSearch` | Loop with break, Nat index |
+| `arraySum` | Accumulator, recursive ghost function |
+| `transition` | State machine, enum ADT, inter-method call |
+| `packet` | Discriminated union with data, if-chain → match |
+| `isSorted` | Loop with break, existential in invariant |
+| `maxElement` | If-without-else in loop |
+| `arrayContains` | For-of loop, boolean flag |

package/package.json

@@ -1,27 +1,37 @@
 {
   "name": "lemmascript",
-  "version": "0.0.1",
-  "description": "A verification toolchain for TypeScript",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "prepublishOnly": "npm run build"
+  "version": "0.1.0",
+  "description": "A verification toolchain for TypeScript — generates Lean 4 or Dafny from annotated TS",
+  "type": "module",
+  "bin": {
+    "lsc": "tools/dist/lsc.js"
   },
-  "keywords": [
-    "typescript",
-    "lean",
-    "verification",
-    "formal-verification",
-    "proof",
-    "toolchain"
+  "files": [
+    "tools/dist"
   ],
-  "license": "MIT",
-  "engines": {
-    "node": ">=18"
+  "scripts": {
+    "build": "tsc -p tools/tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc -p tools/tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "ts-morph": "^25.0.0"
   },
   "devDependencies": {
-    "typescript": "^5.8.0"
-  }
+    "@types/node": "^25.5.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.7.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/midspiral/LemmaScript"
+  },
+  "keywords": [
+    "verification",
+    "typescript",
+    "lean4",
+    "dafny",
+    "formal-methods"
+  ]
 }

package/tools/dist/dafny-commands.js

@@ -0,0 +1,104 @@
+/**
+ * Dafny backend commands: gen, check, regen.
+ */
+import { existsSync, readFileSync, writeFileSync, copyFileSync } from "fs";
+import { execSync } from "child_process";
+import path from "path";
+function writeGen(genPath, text) {
+    writeFileSync(genPath, text);
+    console.log(`Generated: ${genPath}`);
+}
+export function dafnyGen(genPath, dfyPath, text) {
+    writeGen(genPath, text);
+    if (!existsSync(dfyPath)) {
+        writeFileSync(dfyPath, text);
+        console.log(`Created: ${dfyPath}`);
+    }
+}
+export function dafnyCheckDiff(genPath, dfyPath) {
+    if (!existsSync(dfyPath))
+        return true;
+    try {
+        const diff = execSync(`git diff --no-index -- "${genPath}" "${dfyPath}" 2>/dev/null || true`, { encoding: "utf-8" });
+        const deletions = diff.split("\n").filter(l => l.startsWith("-") && !l.startsWith("---"));
+        if (deletions.length > 0) {
+            console.error(`WARNING: ${path.basename(dfyPath)} has modifications to generated lines (not additions-only):`);
+            for (const d of deletions.slice(0, 5))
+                console.error("  " + d);
+            return false;
+        }
+    }
+    catch { /* diff not available */ }
+    return true;
+}
+export function dafnyVerify(dfyPath, dir) {
+    console.log("Running dafny verify...");
+    try {
+        const content = readFileSync(dfyPath, "utf-8");
+        const stdLibFlag = content.includes("import Std.") ? " --standard-libraries" : "";
+        execSync(`dafny verify${stdLibFlag} "${dfyPath}"`, { cwd: dir, stdio: "inherit" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function dafnySavePatch(genPath, dfyPath, patchPath) {
+    try {
+        const patch = execSync(`diff -u "${genPath}" "${dfyPath}" || true`, { encoding: "utf-8" });
+        writeFileSync(patchPath, patch);
+        console.log(`Saved: ${patchPath}`);
+    }
+    catch { /* diff not available */ }
+}
+function dafnyApplyPatch(genPath, dfyPath, patchPath) {
+    if (!existsSync(patchPath))
+        return false;
+    const patch = readFileSync(patchPath, "utf-8").trim();
+    if (!patch)
+        return false;
+    copyFileSync(genPath, dfyPath);
+    try {
+        execSync(`patch --no-backup-if-mismatch -p0 "${dfyPath}" < "${patchPath}"`, { stdio: "pipe" });
+        console.log(`Applied: ${patchPath}`);
+        return true;
+    }
+    catch {
+        copyFileSync(genPath, dfyPath);
+        return false;
+    }
+}
+export function dafnyRegen(genPath, dfyPath, patchPath, text, dir) {
+    // 1. No .dfy yet — create both, verify, done
+    if (!existsSync(dfyPath)) {
+        dafnyGen(genPath, dfyPath, text);
+        if (!dafnyVerify(dfyPath, dir)) {
+            console.error(`FAILED: ${path.basename(dfyPath)} verification failed on first run.`);
+            process.exit(1);
+        }
+        return;
+    }
+    // 2. Capture patch from current gen → dfy BEFORE overwriting gen
+    let hasPatch = false;
+    if (existsSync(genPath)) {
+        dafnySavePatch(genPath, dfyPath, patchPath);
+        hasPatch = readFileSync(patchPath, "utf-8").trim().length > 0;
+    }
+    // 3. Write new gen
+    writeGen(genPath, text);
+    // 4. Try verifying existing dfy as-is
+    if (dafnyVerify(dfyPath, dir))
+        return;
+    // 5. Failed — try applying captured patch to new gen
+    if (hasPatch) {
+        console.log("Verification failed. Trying to apply patch...");
+        if (dafnyApplyPatch(genPath, dfyPath, patchPath) && dafnyVerify(dfyPath, dir))
+            return;
+    }
+    // 6. Needs LLM re-adaptation
+    console.error(`FAILED: ${path.basename(dfyPath)} needs manual re-adaptation.`);
+    console.error(`  ${genPath} has the new generated code.`);
+    if (hasPatch)
+        console.error(`  ${patchPath} has the captured patch.`);
+    process.exit(1);
+}