lemmascript 0.0.1 → 0.2.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,96 @@
-# LemmaScript
+# LemmaScript (Tech Preview)
 
-A verification toolchain for TypeScript.
+A verification toolchain for TypeScript. Write ordinary TypeScript with `//@ ` specification annotations. The toolchain generates verifiable code from your TypeScript — either in Dafny or Lean 4 (with Velvet/Loom).
+
+See [SPEC.md](SPEC.md) and [DESIGN.md](DESIGN.md).
+
+This is a **Tech Preview**: the core idea is there, but support, semantics, and ergonomics are still evolving.
+
+## Examples and Case Studies
+
+Each example and case study is verified in Lean 4 and/or Dafny from the same annotated TypeScript source.
+
+See the internal [examples](examples).
+
+See the external case studies:
+- **[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).
+- **[hono-lemmascript](https://github.com/midspiral/hono-lemmascript/blob/lemmascript/README_LemmaScript.md)** — brownfield verification of [hono](https://github.com/honojs/hono)'s security middleware. Two CVEs verified: IP restriction bypass ([CVE-2026-39409](https://github.com/honojs/hono/security/advisories/GHSA-3mpf-rcc7-5347)) and cookie name bypass ([CVE-2026-39410](https://github.com/honojs/hono/security/advisories/GHSA-r5rp-j6wh-rvv4)) — 51 Dafny lemmas. Cookie verification done in-place. Dafny only.
+- **[charmchat](https://github.com/CHARM-BDF/charmchat/tree/lemma)** — in-progress verification of some sub-components, in Dafny.
+
+## 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
+
+### 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.
+
+### Lean backend
+
+```sh
+npx lsc gen src/myModule.ts
+lake build
+```
+
+## 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
+
+### 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) |
+
+### 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 |
 
-Coming soon from [Midspiral](https://github.com/midspiral).

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.2.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,98 @@
+/**
+ * Dafny backend commands: gen, check, regen.
+ */
+import { existsSync, readFileSync, writeFileSync, copyFileSync, unlinkSync } 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, timeLimit) {
+    console.log("Running dafny verify...");
+    try {
+        const content = readFileSync(dfyPath, "utf-8");
+        const stdLibFlag = content.includes("import Std.") ? " --standard-libraries" : "";
+        const timeLimitFlag = timeLimit ? ` --verification-time-limit ${timeLimit}` : "";
+        execSync(`dafny verify${stdLibFlag}${timeLimitFlag} "${dfyPath}"`, { cwd: dir, stdio: "inherit" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function dafnyRegen(genPath, dfyPath, basePath, text, dir) {
+    // 1. Read old gen before overwriting (needed for base seeding)
+    const oldGen = existsSync(genPath) ? readFileSync(genPath, "utf-8") : "";
+    // 2. Always write new gen so user can inspect latest output
+    writeGen(genPath, text);
+    // 3. No .dfy yet — create dfy, verify, done
+    if (!existsSync(dfyPath)) {
+        writeFileSync(dfyPath, text);
+        console.log(`Created: ${path.basename(dfyPath)}`);
+        if (!dafnyVerify(dfyPath, dir)) {
+            console.error(`FAILED: ${path.basename(dfyPath)} verification failed on first run.`);
+            process.exit(1);
+        }
+        return;
+    }
+    // 4. Determine anchor: base file if it exists (dirty state), otherwise old gen
+    const anchor = existsSync(basePath) ? readFileSync(basePath, "utf-8") : oldGen;
+    // 5. If gen changed, three-way merge
+    if (text !== anchor) {
+        const savedDfy = readFileSync(dfyPath, "utf-8");
+        if (!existsSync(basePath))
+            writeFileSync(basePath, anchor);
+        const mergedPath = dfyPath + ".merged";
+        console.log("Gen changed. Three-way merging...");
+        try {
+            execSync(`git merge-file "${dfyPath}" "${basePath}" "${genPath}"`, { stdio: "pipe" });
+            console.log(`Merged: ${path.basename(dfyPath)}`);
+        }
+        catch (e) {
+            if (e.status > 0) {
+                copyFileSync(dfyPath, mergedPath);
+                writeFileSync(dfyPath, savedDfy);
+                console.error(`CONFLICT: ${path.basename(dfyPath)} — merge had conflicts, dfy restored. See ${path.basename(mergedPath)}`);
+                process.exit(1);
+            }
+            throw e;
+        }
+    }
+    // 6. Check gen invariant (unconditional)
+    if (!dafnyCheckDiff(genPath, dfyPath)) {
+        console.error(`FAILED: ${path.basename(dfyPath)} has modifications to generated lines.`);
+        process.exit(1);
+    }
+    // 7. Verify
+    if (!dafnyVerify(dfyPath, dir)) {
+        console.error(`FAILED: ${path.basename(dfyPath)} verification failed.`);
+        process.exit(1);
+    }
+    // 8. Success — delete base (gen is now the anchor)
+    if (existsSync(basePath))
+        unlinkSync(basePath);
+}