@asmlift/core 0.1.0

package/src/ir/verify.ts

@@ -0,0 +1,221 @@
+// asmlift IR — the verifier. Runs after every pass; a bad edit fails HERE, at its source,
+// not three stages later as wrong output. Invariants:
+//   1. every block ends in exactly one terminator (and it is the last op)
+//   2. operands well-formed: opcode registered, correct arity/attrs
+//   3. SSA: each value defined once; every use is defined; def dominates use
+import { Block, Fn, Value, predecessors } from './core';
+import { opSig } from './opcodes';
+
+export class VerifyError extends Error {}
+
+// Opcodes admitting EITHER a 2-operand register form OR a 1-operand + `imm` attr form.
+const TWO_OR_IMM = new Set(['sdiv', 'shl', 'shr_u', 'shr_s']);
+
+export function verify(fn: Fn): void {
+  if (fn.blocks.length === 0) {
+    throw new VerifyError(`fn '${fn.name}' has no blocks`);
+  }
+
+  // --- collect definitions; reject double-definition ---
+  const defined = new Set<Value>();
+  const defBlock = new Map<Value, Block>();
+  const defIndex = new Map<Value, number>(); // -1 for block params
+  const define = (v: Value, b: Block, idx: number, what: string) => {
+    if (defined.has(v)) {
+      throw new VerifyError(`value defined twice (${what})`);
+    }
+    defined.add(v);
+    defBlock.set(v, b);
+    defIndex.set(v, idx);
+  };
+  for (const b of fn.blocks) {
+    for (const p of b.params) {
+      define(p, b, -1, 'block param');
+    }
+    b.ops.forEach((op, idx) => op.results.forEach((r) => define(r, b, idx, `result of '${op.opcode}'`)));
+  }
+
+  // --- per-op structural + arity + level checks ---
+  const at = (b: Block, idx: number) => `(fn '${fn.name}', block ^bb${fn.blocks.indexOf(b)}, op ${idx})`;
+  for (const b of fn.blocks) {
+    if (b.ops.length === 0) {
+      throw new VerifyError(`empty block ^bb${fn.blocks.indexOf(b)} in '${fn.name}'`);
+    }
+    b.ops.forEach((op, idx) =>
+      locate(
+        () => {
+          const sig = opSig(op.opcode);
+          if (!sig) {
+            throw new VerifyError(`unknown opcode '${op.opcode}'`);
+          }
+          if (sig.operands !== 'variadic' && op.operands.length !== sig.operands) {
+            throw new VerifyError(`'${op.opcode}' expects ${sig.operands} operands, got ${op.operands.length}`);
+          }
+          if (op.results.length !== sig.results) {
+            throw new VerifyError(`'${op.opcode}' expects ${sig.results} results, got ${op.results.length}`);
+          }
+          // `sdiv` and the shifts are variadic to admit BOTH forms (2-operand register form, or
+          // 1-operand + `imm`), so the generic arity check can't guard them. Enforce the real
+          // invariant here — otherwise a malformed op (0 operands, or 1 with no `imm`) would slip
+          // through and render `/ undefined` / `<< undefined` downstream instead of failing at its
+          // source.
+          if (
+            TWO_OR_IMM.has(op.opcode) &&
+            !(op.operands.length === 2 || (op.operands.length === 1 && 'imm' in op.attrs))
+          ) {
+            throw new VerifyError(
+              `'${op.opcode}' must be 2 operands OR 1 operand with an 'imm' attr, got ${op.operands.length} operands`,
+            );
+          }
+          // `ret` is variadic to admit the void form; anything past one returned value is malformed.
+          if (op.opcode === 'ret' && op.operands.length > 1) {
+            throw new VerifyError(`'ret' takes at most 1 operand, got ${op.operands.length}`);
+          }
+          const isTerm = !!sig.terminator;
+          const isLast = idx === b.ops.length - 1;
+          if (isTerm && !isLast) {
+            throw new VerifyError(`terminator '${op.opcode}' is not the last op in its block`);
+          }
+          if (!isTerm && isLast) {
+            throw new VerifyError(`block does not end in a terminator (ends with '${op.opcode}')`);
+          }
+          if (typeof sig.successors === 'number' && op.successors.length !== sig.successors) {
+            throw new VerifyError(`'${op.opcode}' expects ${sig.successors} successors, got ${op.successors.length}`);
+          }
+          // `switch_br` has variadic successors (N cases + 1 default). Enforce its real invariants here (as
+          // the generic count check can't): ≥2 successors, a `cases` list index-aligned with the first N,
+          // and DISTINCT case values (a duplicate would only surface as a `duplicate case` error at recompile).
+          if (op.opcode === 'switch_br') {
+            if (op.successors.length < 2) {
+              throw new VerifyError(`'switch_br' needs ≥2 successors (cases + default), got ${op.successors.length}`);
+            }
+            const cases = op.attrs.cases;
+            if (!Array.isArray(cases) || cases.length !== op.successors.length - 1) {
+              throw new VerifyError(
+                `'switch_br' 'cases' must have (successors - 1) = ${op.successors.length - 1} entries`,
+              );
+            }
+            if (new Set(cases as number[]).size !== cases.length) {
+              throw new VerifyError(`'switch_br' has duplicate case values`);
+            }
+          }
+          if (!isTerm && op.successors.length) {
+            throw new VerifyError(`non-terminator '${op.opcode}' has successors`);
+          }
+          for (const k of sig.requiredAttrs ?? []) {
+            if (!(k in op.attrs)) {
+              throw new VerifyError(`'${op.opcode}' missing required attr '${k}'`);
+            }
+          }
+          for (const u of op.operands) {
+            if (!defined.has(u)) {
+              throw new VerifyError(`use of undefined value in '${op.opcode}'`);
+            }
+          }
+          for (const s of op.successors) {
+            if (!fn.blocks.includes(s.block)) {
+              throw new VerifyError(`successor of '${op.opcode}' is not a block of this fn`);
+            }
+            if (s.args.length !== s.block.params.length) {
+              throw new VerifyError(
+                `successor of '${op.opcode}' passes ${s.args.length} args to a block with ${s.block.params.length} params`,
+              );
+            }
+            for (const u of s.args) {
+              if (!defined.has(u)) {
+                throw new VerifyError(`use of undefined value in successor args of '${op.opcode}'`);
+              }
+            }
+          }
+        },
+        () => at(b, idx),
+      ),
+    );
+  }
+
+  // --- dominance (iterative dominators over the CFG) ---
+  const entry = fn.blocks[0];
+  const preds = predecessors(fn);
+  const dom = new Map<Block, Set<Block>>();
+  const allBlocks = new Set(fn.blocks);
+  for (const b of fn.blocks) {
+    dom.set(b, b === entry ? new Set([entry]) : new Set(allBlocks));
+  }
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const b of fn.blocks) {
+      if (b === entry) {
+        continue;
+      }
+      let inter: Set<Block> | null = null;
+      for (const p of preds.get(b)!) {
+        const dp = dom.get(p)!;
+        if (inter === null) {
+          inter = new Set(dp);
+          continue;
+        }
+        for (const x of inter) {
+          if (!dp.has(x)) {
+            inter.delete(x);
+          }
+        } // intersect in place (spec-safe delete-in-iter)
+      }
+      const next = new Set<Block>(inter ?? []);
+      next.add(b);
+      if (!setEq(next, dom.get(b)!)) {
+        dom.set(b, next);
+        changed = true;
+      }
+    }
+  }
+  const dominates = (a: Block, b: Block) => dom.get(b)!.has(a);
+
+  for (const b of fn.blocks) {
+    b.ops.forEach((op, idx) =>
+      locate(
+        () => {
+          const checkUse = (u: Value) => {
+            const db = defBlock.get(u)!;
+            if (db === b) {
+              const di = defIndex.get(u)!;
+              if (di >= 0 && di >= idx) {
+                throw new VerifyError(`use before def in '${op.opcode}'`);
+              }
+            } else if (!dominates(db, b)) {
+              throw new VerifyError(`def does not dominate use in '${op.opcode}'`);
+            }
+          };
+          op.operands.forEach(checkUse);
+          op.successors.forEach((s) => s.args.forEach(checkUse));
+        },
+        () => at(b, idx),
+      ),
+    );
+  }
+}
+
+/** Run a check body; a VerifyError it throws is re-thrown with the op's location appended —
+ *  "value defined twice" is unactionable without WHICH block/op. */
+function locate(body: () => void, where: () => string): void {
+  try {
+    body();
+  } catch (e) {
+    if (e instanceof VerifyError) {
+      throw new VerifyError(`${e.message} ${where()}`);
+    }
+    throw e;
+  }
+}
+
+function setEq(a: Set<Block>, b: Set<Block>): boolean {
+  if (a.size !== b.size) {
+    return false;
+  }
+  for (const x of a) {
+    if (!b.has(x)) {
+      return false;
+    }
+  }
+  return true;
+}

package/src/l3/ast.ts

@@ -0,0 +1,301 @@
+// asmlift L3 — the language-NEUTRAL structured AST. A LanguageBackend lowers this to a
+// concrete language (C / Pascal / C++) and prints it. "Return a value" and binary ops
+// are neutral nodes here; each backend owns its own spelling.
+import type { IrType } from '../ir/types';
+
+export type Expr =
+  | { k: 'var'; name: string }
+  | { k: 'const'; value: number }
+  | { k: 'bin'; op: BinOp; l: Expr; r: Expr }
+  | { k: 'un'; op: '-' | '~' | '!'; e: Expr }
+  // A C-style value cast `(T)e`. Tree-level producers: a width-narrowing cast `(u8)e` (the
+  // recovered form of a byte/half extend idiom — zext/sext IR ops), the STRUCT-pointer cast
+  // (structure.ts memAccess/arrayAccess struct paths — see the note on `field` below), and the
+  // integer legalization of a pointer operand under an operator C rejects (structure.ts intify,
+  // `3 & (s32)p`). Scalar deref casts are backend-owned — the C-family printer synthesizes
+  // them from the `index` node's width. Each backend spells the cast in its own syntax
+  // (C: `(u8)e`; Pascal: no spelling yet → fails loud).
+  | { k: 'cast'; to: IrType; e: Expr }
+  | { k: 'call'; fn: string; args: Expr[] }
+  // The ADDRESS of a named global, `&gSym` (agbcc pool `.word gSym`, frontend `gaddr` op). A
+  // DEREF of it collapses to the bare global: memAccess/arrayAccess spell `*(&gSym)` as `gSym`
+  // and `(&gSym)[i]` as `gSym[i]` (a global name decays to a pointer). Only a genuinely
+  // address-TAKEN global (passed by address, `&gSym` as a call arg) prints the `&` form. The
+  // global's type comes from the project headers, so it is never declared as a local.
+  | { k: 'addr'; name: string }
+  // A memory access `base[idx]` (printed `*base` when idx is the constant 0), CARRYING the
+  // access's element width (bytes) and signedness. `idx` counts elements of `width` bytes.
+  // Because the node carries the width, EACH BACKEND owns its own legalization: the C family
+  // checks whether `base`'s rendered C type strides `width` and inserts the reinterpret cast
+  // itself when it does not (`*(u8 *)(a0 + a1)`); Pascal loud-declines a base it cannot spell
+  // faithfully (see also cpp.ts's sub-word guard and `field`'s name-encoded offset).
+  //
+  // Still not fully language-neutral — the idx ≠ 0 form is a known C-idiom:
+  //   • C backend: `*base` (idx 0) and `base[idx]` (idx ≠ 0) — both valid.
+  //   • Pascal backend: `base^` (idx 0) is valid IDO Pascal, but `base[idx]` (idx ≠ 0) is
+  //     REJECTED by `upas` — SGI Pascal has no bare-pointer indexing
+  //     (packages/cli/test/matching/mips-memory.test.ts).
+  // Variable-index `a[i]` is recovered at the IR level (`aload`/`astore` carry elemSize;
+  // raise/arrays.ts) but still LOWERS to this one C-shaped `index` node, so it stays C-only
+  // (a Pascal array-access spelling is future work). Treat `index` with idx ≠ 0 as C-shaped.
+  | { k: 'index'; base: Expr; idx: Expr; width: number; signed: boolean }
+  // A named struct-field access `base->name` (raise/structs.ts recovered `base` as a struct
+  // pointer, so the byte offset resolves to a named field instead of a scaled array index).
+  // Unlike `index`, this carries the field NAME (which encodes the byte offset, `field_<off>`),
+  // not a width-scaled number — the byte-offset-carrying member access cpp.ts's sub-word guard needs.
+  | { k: 'field'; base: Expr; name: string }
+  // A GAP MARKER — the annotate-mode (`onGap: "annotate"`) spelling of a value asmlift could not
+  // faithfully lift (an unmodelled instruction's `opaque` result, an unlowered transient op, a
+  // dropped def). Every backend spells it as a call to the UNDEFINED symbol `ASMLIFT_ERROR("reason",
+  // args…)` (the m2c `M2C_ERROR` discipline): the surrounding function is complete and readable, but
+  // the source does NOT compile until the user consciously defines the macro — loud in the ARTIFACT
+  // instead of loud in the process. `args` carry the source operands for context. Strict mode (the
+  // default) never produces this node; it keeps the `"?"` sentinel → ContractError behavior.
+  | { k: 'marker'; reason: string; args: Expr[] };
+
+export type BinOp =
+  '+' | '-' | '*' | '/' | '%' | '<' | '<=' | '>' | '>=' | '==' | '!=' | '&' | '|' | '^' | '<<' | '>>' | '&&' | '||';
+
+export type Stmt =
+  | { k: 'assign'; name: string; value: Expr }
+  // A memory write to an lvalue expression (`index` → `base[idx] = value` / `*base = value`;
+  // `field` → `base->name = value`). Carrying the lvalue as an Expr keeps stores symmetric with
+  // the load side, so the same leaf-hook / field spelling serves reads and writes alike.
+  | { k: 'store'; lval: Expr; value: Expr }
+  | { k: 'exprstmt'; value: Expr } // a side-effecting expression (e.g. a void call)
+  | { k: 'if'; cond: Expr; then: Stmt[]; else: Stmt[] }
+  | { k: 'while'; cond: Expr; body: Stmt[] }
+  // A bottom-tested loop `do { body } while (cond);` — the body runs at least once, then the test at
+  // the BOTTOM decides re-entry. This is the shape a compiler emits for a loop whose trip count it can
+  // prove ≥1 (guard elided) or a source `do-while`. Distinct from `while` (test-at-top, body may run
+  // 0 times) — the two are NOT interchangeable for matching.
+  | { k: 'dowhile'; cond: Expr; body: Stmt[] }
+  // A counted loop `for (init; cond; inc) { body }` — a PURE RE-SPELLING of a test-at-top `while`
+  // (quality only). Produced ONLY by recognizing a `while` whose induction variable's init literally
+  // precedes it and whose increment is literally the body's last statement, WITHOUT moving any op:
+  // `assign(iv,e0); while(c){ …; assign(iv,e1) }` becomes `for(assign(iv,e0); c; assign(iv,e1)){ … }`.
+  // Semantically identical to that desugaring — with ONE exception the recognizer guards against: a
+  // `continue` in the body RUNS `inc` under `for` but SKIPS it under `while`, so a body containing a
+  // same-level `continue` is NOT converted. `init`/`inc` are Stmts (an `assign`); a backend that
+  // cannot spell native `for` may always fall back to the `while` desugaring (Pascal does), so this
+  // node never forces a loud-fail.
+  | { k: 'for'; init: Stmt; cond: Expr; inc: Stmt; body: Stmt[] }
+  // `break;` / `continue;` — a loop early-exit / next-iteration jump. Emitted ONLY when the target is
+  // the innermost enclosing loop (bare C break/continue cannot express a multi-level exit; a deeper
+  // target declines). SGI/IDO Pascal has neither, so its backend loud-fails them (like `field`/`cast`).
+  | { k: 'break' }
+  | { k: 'continue' }
+  // A multi-way `switch` over an integer scrutinee (recovered from a comparison tree — Regime A — or
+  // a jump-table `switch_br` — Regime B). `cases` are emitted IN ARRAY ORDER; `default` (if present)
+  // is emitted last.
+  //
+  // NON-NEUTRALITY NOTE (like the `index` node above): `fallsThrough` encodes a C/C++ control-flow
+  // concept POSITIONALLY — `cases[i].fallsThrough === true` means control continues into
+  // `cases[i+1].body`, so the array ORDER is semantically load-bearing (a backend that reorders cases
+  // would break fall-through). C/C++ spell it natively; Pascal `case-of` has NO fall-through, so the
+  // Pascal backend MUST loud-fail a `fallsThrough` case (it has no faithful spelling), exactly as it
+  // loud-fails `field`/`cast`. Recovery must therefore only set `fallsThrough` when the fall-through
+  // target is the emission-adjacent case.
+  | { k: 'switch'; scrutinee: Expr; cases: SwitchCase[]; default?: Stmt[] }
+  | { k: 'return'; value?: Expr };
+
+/** One arm of a `switch`. `values` stacks multiple `case K:` labels onto one body (`case 1: case 2:`).
+ *  `fallsThrough` true ⇒ the body flows into the NEXT arm (no `break;`); see the non-neutrality note. */
+export interface SwitchCase {
+  values: number[];
+  body: Stmt[];
+  fallsThrough: boolean;
+}
+
+export interface SFn {
+  name: string;
+  params: { name: string; type: IrType }[];
+  locals: { name: string; type: IrType }[]; // recovered locals, declared at function top
+  retType: IrType;
+  body: Stmt[];
+  /** Struct types this function's fields reference, declared above it by the backend. Empty
+   *  unless raise/structs.ts recovered a struct. Sorted by name for deterministic output. */
+  structs?: StructType[];
+}
+
+/** A struct declaration surfaced to the backend (name + field list). Mirrors the IR struct
+ *  type but lives in the neutral AST so a backend can print `struct N { ... };`. */
+export interface StructType {
+  name: string;
+  fields: { off: number; type: IrType; name: string }[];
+  size?: number;
+}
+
+/** A language backend: emits one L3 AST as concrete-language source, plus the language's
+ *  comment spelling. */
+export interface LanguageBackend {
+  readonly id: 'c' | 'cpp' | 'pascal';
+  emit(fn: SFn): string;
+  // Spell ONE LINE of text as a comment in this language (C block comments, Pascal `(* … *)`).
+  // Used by the annotate-mode stub path to carry the failure reason + the original asm
+  // alongside the emitted marker, so a human/LLM has the raw material to finish by hand.
+  comment(text: string): string;
+}
+
+/** The dot-form base of a `field` node — the array-element `index` node under an
+ *  `arr[i].field` access — or undefined for the arrow form. THE one copy of the dot-vs-arrow
+ *  rule, as a NARROWING accessor (no bare `as` at the consumers): the C-family printer spells
+ *  from it and the deref contract (assertDerefsTyped) type-checks against it; a per-consumer
+ *  copy would let the two silently disagree on the same AST. */
+export function dotBase(f: Extract<Expr, { k: 'field' }>): Extract<Expr, { k: 'index' }> | undefined {
+  return f.base.k === 'index' ? f.base : undefined;
+}
+
+/** Boolean projection of `dotBase` for conditions that need no narrowing. */
+export function fieldSpellsDot(f: Extract<Expr, { k: 'field' }>): boolean {
+  return dotBase(f) !== undefined;
+}
+
+/** Structural equality of two expression trees. THE one copy of Expr deep-equal (like
+ *  fieldSpellsDot/derefStrideOk): key-order-independent by construction (a switch, not a
+ *  stringify), exhaustive under noImplicitReturns like the walkers below. */
+export function exprEquals(a: Expr, b: Expr): boolean {
+  if (a.k !== b.k) {
+    return false;
+  }
+  switch (a.k) {
+    case 'var':
+      return a.name === (b as typeof a).name;
+    case 'addr':
+      return a.name === (b as typeof a).name;
+    case 'const':
+      return a.value === (b as typeof a).value;
+    case 'bin': {
+      const bb = b as typeof a;
+      return a.op === bb.op && exprEquals(a.l, bb.l) && exprEquals(a.r, bb.r);
+    }
+    case 'un': {
+      const bb = b as typeof a;
+      return a.op === bb.op && exprEquals(a.e, bb.e);
+    }
+    case 'cast': {
+      const bb = b as typeof a;
+      return JSON.stringify(a.to) === JSON.stringify(bb.to) && exprEquals(a.e, bb.e);
+    }
+    case 'call': {
+      const bb = b as typeof a;
+      return a.fn === bb.fn && a.args.length === bb.args.length && a.args.every((x, i) => exprEquals(x, bb.args[i]));
+    }
+    case 'index': {
+      const bb = b as typeof a;
+      return a.width === bb.width && a.signed === bb.signed && exprEquals(a.base, bb.base) && exprEquals(a.idx, bb.idx);
+    }
+    case 'field': {
+      const bb = b as typeof a;
+      return a.name === bb.name && exprEquals(a.base, bb.base);
+    }
+    case 'marker': {
+      const bb = b as typeof a;
+      return (
+        a.reason === bb.reason && a.args.length === bb.args.length && a.args.every((x, i) => exprEquals(x, bb.args[i]))
+      );
+    }
+  }
+}
+
+// ── the ONE traversal vocabulary ───────────────────────────────────────────────────────────────
+// Every generic walker derives from these helpers, so a NEW node kind is a compile error in
+// exactly one place per union (the switches are exhaustive under noImplicitReturns) — a
+// hand-rolled walker that misses a node kind is a silent bug. Specialized walkers with per-kind
+// SEMANTICS (loop-boundary scans like hasEnclosingContinue, rebuilding transforms like
+// recognizeForLoops) rightly keep their own switches.
+
+/** The direct sub-expressions of `e`, in syntactic order. */
+export function exprChildren(e: Expr): Expr[] {
+  switch (e.k) {
+    case 'var':
+    case 'const':
+    case 'addr':
+      return [];
+    case 'bin':
+      return [e.l, e.r];
+    case 'un':
+    case 'cast':
+      return [e.e];
+    case 'call':
+      return e.args;
+    case 'index':
+      return [e.base, e.idx];
+    case 'field':
+      return [e.base];
+    case 'marker':
+      return e.args;
+  }
+}
+
+/** Rebuild `e` with each direct sub-expression mapped through `f` (shallow; recurse in `f`). */
+export function mapExprChildren(e: Expr, f: (c: Expr) => Expr): Expr {
+  switch (e.k) {
+    case 'var':
+    case 'const':
+    case 'addr':
+      return e;
+    case 'bin':
+      return { ...e, l: f(e.l), r: f(e.r) };
+    case 'un':
+    case 'cast':
+      return { ...e, e: f(e.e) };
+    case 'call':
+      return { ...e, args: e.args.map(f) };
+    case 'index':
+      return { ...e, base: f(e.base), idx: f(e.idx) };
+    case 'field':
+      return { ...e, base: f(e.base) };
+    case 'marker':
+      return { ...e, args: e.args.map(f) };
+  }
+}
+
+/** The expressions a statement DIRECTLY contains, in syntactic order. */
+export function stmtExprs(s: Stmt): Expr[] {
+  switch (s.k) {
+    case 'assign':
+      return [s.value];
+    case 'store':
+      return [s.lval, s.value];
+    case 'exprstmt':
+      return [s.value];
+    case 'return':
+      return s.value ? [s.value] : [];
+    case 'if':
+    case 'while':
+    case 'dowhile':
+      return [s.cond];
+    case 'for':
+      return [s.cond];
+    case 'switch':
+      return [s.scrutinee];
+    case 'break':
+    case 'continue':
+      return [];
+  }
+}
+
+/** The statements a statement DIRECTLY contains. NOTE for document-order walks: a `for`'s
+ *  init/inc are listed here while its cond is in stmtExprs — a walker visiting exprs-then-stmts
+ *  sees the cond before the init. */
+export function stmtChildren(s: Stmt): Stmt[] {
+  switch (s.k) {
+    case 'assign':
+    case 'store':
+    case 'exprstmt':
+    case 'return':
+    case 'break':
+    case 'continue':
+      return [];
+    case 'if':
+      return [...s.then, ...s.else];
+    case 'while':
+    case 'dowhile':
+      return s.body;
+    case 'for':
+      return [s.init, s.inc, ...s.body];
+    case 'switch':
+      return [...s.cases.flatMap((c) => c.body), ...(s.default ?? [])];
+  }
+}