lemmascript 0.5.6 → 0.5.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lemmascript",
-  "version": "0.5.6",
+  "version": "0.5.7",
   "description": "A verification toolchain for TypeScript — generates Lean 4 or Dafny from annotated TS",
   "type": "module",
   "engines": {
@@ -31,6 +31,7 @@
     "type": "git",
     "url": "https://github.com/midspiral/LemmaScript"
   },
+  "homepage": "https://lemmascript.com",
   "keywords": [
     "lemmascript",
     "verification",

package/tools/dist/extract.js

@@ -599,7 +599,7 @@ function extractExpr(node) {
 }
 // ── Annotation parsing ───────────────────────────────────────
 const PREFIX = "//@ ";
-const KEYWORDS = ["requires", "ensures", "invariant", "decreases", "done_with", "type"];
+const KEYWORDS = ["requires", "ensures", "contract", "invariant", "decreases", "done_with", "type"];
 function parseAnnotations(node) {
     const result = [];
     for (const range of node.getLeadingCommentRanges()) {
@@ -1730,7 +1730,30 @@ function extractFunctionInner(fn, parentAnnotations) {
     }
     return {
         name: fn.getName?.() ?? "<anonymous>",
+        exported: false, // set in extractModule against the source file's export surface
         typeParams: unboundedTypeParams,
+        // Original TS parameter grouping, before the flatten below loses it. `defaults` carries
+        // each bound name's default initializer text (omitted when none) for TS-targeting consumers.
+        tsParams: fn.getParameters().map(p => {
+            const nameNode = p.getNameNode();
+            if (Node.isObjectBindingPattern(nameNode)) {
+                const els = nameNode.getElements();
+                const defaults = {};
+                for (const el of els) {
+                    const init = el.getInitializer();
+                    if (init)
+                        defaults[el.getName()] = init.getText();
+                }
+                const binds = els.map(el => el.getName());
+                return Object.keys(defaults).length ? { kind: "object", binds, defaults } : { kind: "object", binds };
+            }
+            if (p.isRestParameter())
+                return { kind: "rest", binds: [p.getName()] };
+            const init = p.getInitializer();
+            return init
+                ? { kind: "simple", binds: [p.getName()], defaults: { [p.getName()]: init.getText() } }
+                : { kind: "simple", binds: [p.getName()] };
+        }),
         params: fn.getParameters().flatMap(p => {
             // Flatten destructured object params into individual params
             const nameNode = p.getNameNode();
@@ -1790,6 +1813,7 @@ function extractFunctionInner(fn, parentAnnotations) {
         })(),
         requires: annots.filter(a => a.kind === "requires").map(a => a.expr),
         ensures: annots.filter(a => a.kind === "ensures").map(a => a.expr),
+        contract: annots.filter(a => a.kind === "contract").map(a => a.expr),
         decreases: annots.find(a => a.kind === "decreases")?.expr ?? null,
         pure: hasPureAnnotation(fn, body && Node.isBlock(body) ? body.getStatements() : undefined),
         autohavoc: false, // set in extractModule (file-level directive or per-function)
@@ -2076,11 +2100,16 @@ export function extractModule(sourceFile) {
         }
         return false;
     }
+    // The module's export surface, by name — covers inline `export function`,
+    // `export { a, b }`, re-exports, and `export const`. Consumers (e.g. the guard
+    // plugin) use this to wrap only the boundary, not internal helpers.
+    const exportedNames = new Set(sourceFile.getExportedDeclarations().keys());
     const functions = fnsToExtract.map(f => {
         // For expression-body arrows, annotations come from the parent variable statement
         const parentAnnots = f.parentStmt ? parseAnnotations(f.parentStmt) : undefined;
         const raw = extractFunction(f.node, parentAnnots);
         raw.name = f.name; // use the const name, not "<anonymous>"
+        raw.exported = exportedNames.has(f.name);
         raw.autohavoc = hasAutohavoc(f);
         return raw;
     });

package/tools/dist/guard-command.js

@@ -0,0 +1,238 @@
+/**
+ * `lsc guard` — emit a drop-in `<file>.guarded.ts` that enforces each verified
+ * function's `//@ requires` at runtime.
+ *
+ * Backend-neutral (like `extract`/`info`): reads the Raw IR and re-parses each
+ * `//@ requires` string with the specparser, then lowers the resulting RawExpr
+ * back to executable TypeScript. The generated module re-exports every function
+ * at its original signature, each guarded: on a violated clause it throws
+ * `PreconditionError(fn, clause, clauseId, args, detail)`; a `can.*` namespace
+ * exposes the same per-clause checks as booleans for render-time gating.
+ *
+ * Clauses naming a symbol that is not TS-resident (a ghost `.dfy` predicate, an
+ * unbounded quantifier) cannot be lowered — they are SKIPPED with a warning,
+ * never faked. Internal core-to-core calls stay raw (`__core.*`); the proof
+ * covers those.
+ */
+import { writeFileSync } from "fs";
+import * as path from "path";
+import { parseExpr } from "./specparser.js";
+class NotLowerable extends Error {
+}
+const GLOBALS = new Set(["Math", "Number", "undefined"]);
+// ── RawExpr → executable TS (throws NotLowerable on a non-TS-resident symbol) ──
+function lower(e, ctx) {
+    switch (e.kind) {
+        case "num": return String(e.value);
+        case "bool": return String(e.value);
+        case "str": return JSON.stringify(e.value);
+        case "var":
+            if (ctx.bound.has(e.name) || ctx.params.has(e.name) || GLOBALS.has(e.name))
+                return e.name;
+            if (ctx.fns.has(e.name))
+                return `__core.${e.name}`;
+            throw new NotLowerable(`unknown symbol '${e.name}' (not a param, bound var, or module function)`);
+        case "field": return `${lower(e.obj, ctx)}.${e.field}`;
+        case "index": return `${lower(e.obj, ctx)}[${lower(e.idx, ctx)}]`;
+        case "call": return `${lower(e.fn, ctx)}(${e.args.map((a) => lower(a, ctx)).join(", ")})`;
+        case "unop": return `(${e.op}${lower(e.expr, ctx)})`;
+        case "conditional":
+            return `(${lower(e.cond, ctx)} ? ${lower(e.then, ctx)} : ${lower(e.else, ctx)})`;
+        case "arrayLiteral": return `[${e.elems.map((x) => lower(x, ctx)).join(", ")}]`;
+        case "binop": {
+            const l = () => lower(e.left, ctx), r = () => lower(e.right, ctx);
+            if (e.op === "==>")
+                return `(!(${l()}) || (${r()}))`;
+            if (e.op === "<==>")
+                return `((${l()}) === (${r()}))`;
+            if (e.op === "in")
+                throw new NotLowerable("'in' membership not yet lowered");
+            return `(${l()} ${e.op} ${r()})`;
+        }
+        case "forall":
+        case "exists": {
+            const { lo, ubOp, ub } = quantRange(e, ctx);
+            const inner = { ...ctx, bound: new Set([...ctx.bound, e.var]) };
+            const body = lower(e.body, inner);
+            const hit = e.kind === "forall" ? `!(${body})` : `(${body})`;
+            const found = e.kind === "forall" ? "false" : "true";
+            const dflt = e.kind === "forall" ? "true" : "false";
+            return `(() => { for (let ${e.var} = ${lo}; ${e.var} ${ubOp} ${ub}; ${e.var}++) { if (${hit}) return ${found}; } return ${dflt}; })()`;
+        }
+        default: throw new NotLowerable(`unsupported expression kind '${e.kind}'`);
+    }
+}
+// Extract a sound finite iteration range [lo, ub) for the quantified var from a
+// `lo <= v && v < ub ==> P` antecedent. Both bounds must be found (or var is a
+// nat) — guessing would risk an unsound under-scan. Throws otherwise.
+function quantRange(q, ctx) {
+    if (q.body.kind !== "binop" || q.body.op !== "==>")
+        throw new NotLowerable(`quantifier over '${q.var}' has no bounding antecedent`);
+    const inner = { ...ctx, bound: new Set([...ctx.bound, q.var]) };
+    const isVar = (x) => x.kind === "var" && x.name === q.var;
+    const conj = (e) => e.kind === "binop" && e.op === "&&" ? [...conj(e.left), ...conj(e.right)] : [e];
+    let upper = null;
+    let lowerB = null;
+    for (const c of conj(q.body.left)) {
+        if (c.kind !== "binop")
+            continue;
+        if (isVar(c.left) && (c.op === "<" || c.op === "<="))
+            upper = { ub: lower(c.right, inner), strict: c.op === "<" };
+        else if (isVar(c.right) && (c.op === ">" || c.op === ">="))
+            upper = { ub: lower(c.left, inner), strict: c.op === ">" };
+        else if (isVar(c.right) && (c.op === "<" || c.op === "<="))
+            lowerB = { expr: lower(c.left, inner), strict: c.op === "<" };
+        else if (isVar(c.left) && (c.op === ">" || c.op === ">="))
+            lowerB = { expr: lower(c.right, inner), strict: c.op === ">" };
+    }
+    if (!upper)
+        throw new NotLowerable(`no upper bound found for '${q.var}'`);
+    let lo;
+    if (lowerB)
+        lo = lowerB.strict ? `(${lowerB.expr}) + 1` : lowerB.expr;
+    else if (q.varType === "nat")
+        lo = "0";
+    else
+        throw new NotLowerable(`no lower bound found for '${q.var}'`);
+    return { lo, ubOp: upper.strict ? "<" : "<=", ub: upper.ub };
+}
+// ── human-readable label for a sub-expression (spec text, bare names) ──
+function render(e) {
+    switch (e.kind) {
+        case "num": return String(e.value);
+        case "bool": return String(e.value);
+        case "str": return JSON.stringify(e.value);
+        case "var": return e.name;
+        case "field": return `${render(e.obj)}.${e.field}`;
+        case "index": return `${render(e.obj)}[${render(e.idx)}]`;
+        case "call": return `${render(e.fn)}(${e.args.map(render).join(", ")})`;
+        case "unop": return `${e.op}${render(e.expr)}`;
+        case "binop": return `${render(e.left)} ${e.op} ${render(e.right)}`;
+        case "conditional": return `${render(e.cond)} ? ${render(e.then)} : ${render(e.else)}`;
+        default: return "?";
+    }
+}
+// Maximal "notable" sub-expressions (calls / field / index / param vars) whose
+// runtime values explain a failure. Recurses through operators only.
+function collectNotable(e, ctx, out) {
+    switch (e.kind) {
+        case "call":
+        case "field":
+        case "index": {
+            try {
+                out.set(render(e), lower(e, ctx));
+            }
+            catch { /* skip unlowerable leaf */ }
+            return;
+        }
+        case "var":
+            if (ctx.params.has(e.name))
+                out.set(e.name, e.name);
+            return;
+        case "binop":
+            collectNotable(e.left, ctx, out);
+            collectNotable(e.right, ctx, out);
+            return;
+        case "unop":
+            collectNotable(e.expr, ctx, out);
+            return;
+        case "conditional":
+            collectNotable(e.cond, ctx, out);
+            collectNotable(e.then, ctx, out);
+            collectNotable(e.else, ctx, out);
+            return;
+        default: return;
+    }
+}
+// ── per-function check table ──────────────────────────────────────────
+function buildChecks(fn, ctx) {
+    const preamble = [], entries = [], skipped = [];
+    fn.requires.forEach((src, i) => {
+        const id = `${fn.name}#${i}`;
+        try {
+            const ast = parseExpr(src);
+            const clauseLit = JSON.stringify(src);
+            if (ast.kind === "forall") {
+                const { lo, ubOp, ub } = quantRange(ast, ctx);
+                const inner = { ...ctx, bound: new Set([...ctx.bound, ast.var]) };
+                const body = lower(ast.body, inner);
+                const w = `__w${i}`;
+                preamble.push(`  const ${w} = ((): number => { for (let ${ast.var} = ${lo}; ${ast.var} ${ubOp} ${ub}; ${ast.var}++) { if (!(${body})) return ${ast.var}; } return -1; })();`);
+                entries.push(`    __C(${JSON.stringify(id)}, ${clauseLit}, ${w} === -1, () => ({ ${JSON.stringify(ast.var)}: ${w} })),`);
+            }
+            else {
+                const ok = lower(ast, ctx);
+                const notes = new Map();
+                collectNotable(ast, ctx, notes);
+                const detail = `{ ${[...notes].map(([k, v]) => `${JSON.stringify(k)}: ${v}`).join(", ")} }`;
+                entries.push(`    __C(${JSON.stringify(id)}, ${clauseLit}, (${ok}), () => (${detail})),`);
+            }
+        }
+        catch (err) {
+            if (!(err instanceof NotLowerable))
+                throw err;
+            skipped.push(`  // SKIPPED ${id} (${err.message}): ${src}`);
+            console.warn(`  warning: ${fn.name} — unlowerable clause skipped (${err.message}): ${src}`);
+        }
+    });
+    return { preamble, entries, skipped };
+}
+function sig(fn) {
+    const tp = fn.typeParams.length ? `<${fn.typeParams.join(", ")}>` : "";
+    const params = fn.params.map((p) => `${p.name}: ${p.tsType}`).join(", ");
+    return `${tp}(${params}): ${fn.returnType}`;
+}
+const argList = (fn) => fn.params.map((p) => p.name).join(", ");
+function emitFunction(fn, ctx) {
+    const { preamble, entries, skipped } = buildChecks(fn, ctx);
+    const checksBody = [...skipped, ...preamble, `  return [`, ...entries, `  ];`].join("\n");
+    const args = argList(fn);
+    return [
+        `function checks_${fn.name}(${fn.params.map((p) => `${p.name}: ${p.tsType}`).join(", ")}): __Check[] {`,
+        checksBody,
+        `}`,
+        `export function ${fn.name}${sig(fn)} {`,
+        `  return __enforce(${JSON.stringify(fn.name)}, [${args}], checks_${fn.name}(${args}), () => __core.${fn.name}(${args}));`,
+        `}`,
+    ].join("\n");
+}
+export function runGuard(raw, outPath) {
+    const base = path.basename(raw.file, ".ts");
+    const fnNames = new Set(raw.functions.map((f) => f.name));
+    const blocks = raw.functions.map((fn) => {
+        const ctx = { params: new Set(fn.params.map((p) => p.name)), bound: new Set(), fns: fnNames };
+        return emitFunction(fn, ctx);
+    });
+    const canEntries = raw.functions.map((fn) => `  ${fn.name}: (${fn.params.map((p) => `${p.name}: ${p.tsType}`).join(", ")}): boolean => __holds(checks_${fn.name}(${argList(fn)})),`);
+    const header = [
+        `// ${base}.guarded.ts — GENERATED by \`lsc guard\`. Do not edit.`,
+        `// Drop-in for ${base}.ts: each function checks its //@ requires and throws`,
+        `// PreconditionError on violation; \`can.*\` runs the same checks as booleans.`,
+        ``,
+        `import * as __core from "./${base}";`,
+        ``,
+        `export class PreconditionError extends Error {`,
+        `  constructor(`,
+        `    readonly fn: string,`,
+        `    readonly clause: string,`,
+        `    readonly clauseId: string,`,
+        `    readonly args: unknown[],`,
+        `    readonly detail: unknown,`,
+        `  ) {`,
+        `    super(\`precondition failed in \${fn}: \${clause}\`);`,
+        `    this.name = "PreconditionError";`,
+        `  }`,
+        `}`,
+        ``,
+        `type __Check = { id: string; clause: string; ok: boolean; detail: () => unknown };`,
+        `const __C = (id: string, clause: string, ok: boolean, detail: () => unknown): __Check => ({ id, clause, ok, detail });`,
+        `function __enforce<R>(fn: string, args: unknown[], checks: __Check[], call: () => R): R {`,
+        `  for (const c of checks) if (!c.ok) throw new PreconditionError(fn, c.clause, c.id, args, c.detail());`,
+        `  return call();`,
+        `}`,
+        `const __holds = (checks: __Check[]): boolean => checks.every((c) => c.ok);`,
+    ].join("\n");
+    const text = [header, "", ...blocks, "", "export const can = {", ...canEntries, "};", ""].join("\n");
+    writeFileSync(outPath, text);
+    console.log(`Wrote ${outPath} (${raw.functions.length} functions guarded)`);
+}