romdevtools 0.29.0 → 0.40.0

package/src/analysis/analyze.js

@@ -0,0 +1,263 @@
+// analyze.js — MCP-facing RE analysis ops built on the Rizin WASM engine:
+// control-flow graphs, deep cross-references, auto-detected functions, and a
+// one-shot structural map. Complements disasm.js (da65/native, rebuildable
+// output) — rizin gives the GRAPH structure da65 can't.
+//
+// Address model: rizin's own bin-loader sets the load address for formats it
+// recognizes (iNES → 0x8000, GBA → 0x08000000, raw → 0). For platforms whose
+// flat file maps 1:1 to the CPU bus (Genesis, plain binaries) the file offset
+// IS the CPU address. We pass an explicit base only where it helps; the
+// reported addresses are rizin virtual addresses, which match the CPU view for
+// the common (unbanked / first-bank) case. Banked carts: a bank's window is
+// resolved by the existing disasm mappers — analysis here is whole-file.
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { runRizin, runRizinJson, RIZIN_ARCH } from "./rizin.js";
+import { decompileFunction, SLEIGH_LANGID } from "./decompile.js";
+
+/** Sniff platform from a ROM extension (mirrors disasm.js). */
+export function sniffPlatform(p) {
+  if (/\.nes$/i.test(p)) return "nes";
+  if (/\.(sfc|smc)$/i.test(p)) return "snes";
+  if (/\.gbc$/i.test(p)) return "gbc";
+  if (/\.gb$/i.test(p)) return "gb";
+  if (/\.sms$/i.test(p)) return "sms";
+  if (/\.gg$/i.test(p)) return "gg";
+  if (/\.a26$/i.test(p)) return "atari2600";
+  if (/\.a78$/i.test(p)) return "atari7800";
+  if (/\.prg$/i.test(p)) return "c64";
+  if (/\.(lnx|lyx)$/i.test(p)) return "lynx";
+  if (/\.gba$/i.test(p)) return "gba";
+  if (/\.pce$/i.test(p)) return "pce";
+  if (/\.(gen|md|bin)$/i.test(p)) return "genesis";
+  return null;
+}
+
+/** rizin asm.bits per arch (analysis defaults; rizin's loader usually sets
+ * these for recognized formats, but raw blobs need a hint). */
+const BITS = { arm: 32, m68k: 32, snes: 16 };
+
+/** Build the common rizin invocation context for a ROM + platform. Returns
+ * { romBytes, arch, bits, note } — arch null means let rizin sniff. */
+async function loadContext(romPath, platformOverride) {
+  const platform = platformOverride ?? sniffPlatform(romPath);
+  if (!platform) {
+    throw new Error(
+      `analyze: could not determine platform from '${path.basename(romPath)}' — pass platform explicitly`
+    );
+  }
+  if (!(platform in RIZIN_ARCH)) {
+    throw new Error(`analyze: unsupported platform '${platform}'`);
+  }
+  const arch = RIZIN_ARCH[platform];
+  if (arch == null) {
+    throw new Error(`analyze: no Rizin arch mapping for platform '${platform}'`);
+  }
+  const romBytes = new Uint8Array(await readFile(romPath));
+  // PCE: rizin's 6502 plugin drives the loader + standard control flow for
+  // function detection, but mis-decodes HuC6280 custom opcodes — CFG/xrefs are
+  // approximate. Accurate HuC6280 decode is the decompiler's job (SLEIGH spec).
+  const approx = platform === "pce";
+  return { platform, romBytes, arch, bits: BITS[arch], approx };
+}
+
+/** Hex-format an address the way agents expect for the platform width. */
+function hx(n) { return "0x" + (n >>> 0).toString(16); }
+
+/**
+ * Auto-detected function list for a ROM.
+ * @returns {{platform, count, functions: Array<{address, name, size, nbbs, cc, callers, callees}>}}
+ */
+export async function analyzeFunctions(romPath, platformOverride) {
+  const { platform, romBytes, arch, bits } = await loadContext(romPath, platformOverride);
+  const fns = await runRizinJson({ romBytes, arch, bits, commands: "aaa; aflj" });
+  const functions = fns.map((f) => ({
+    address: f.offset,
+    addressHex: hx(f.offset),
+    name: f.name,
+    size: f.size,
+    nbbs: f.nbbs,           // basic-block count
+    cc: f.cc,               // cyclomatic complexity
+    callers: f.indegree ?? (f.codexrefs?.length ?? 0),
+    callees: f.outdegree ?? 0,
+  }));
+  return { platform, arch, count: functions.length, functions };
+}
+
+/**
+ * Control-flow graph for the function containing `address`.
+ * @returns {{platform, address, nodes: Array<{id,address,size,instructions,jump,fail,out}>, edges}}
+ */
+export async function analyzeCfg(romPath, address, platformOverride) {
+  if (address == null) throw new Error("analyze cfg: address required");
+  const { platform, romBytes, arch, bits } = await loadContext(romPath, platformOverride);
+  // afbj = basic blocks of the function as JSON: each block has addr/size/jump/
+  // fail/ninstr. `jump` is the taken edge; `fail` (present only on conditional
+  // blocks) is the fall-through. This is the structured CFG source — `agf json`
+  // only gives a text body blob with untyped out_nodes.
+  const blocks = await runRizinJson({
+    romBytes, arch, bits,
+    commands: `aaa; af @ ${hx(address)}; afbj @ ${hx(address)}`,
+  });
+  if (!Array.isArray(blocks) || blocks.length === 0) {
+    return { platform, arch, address, addressHex: hx(address), nodes: [], edges: [], note: "no function/blocks at address" };
+  }
+  const nodes = blocks.map((b) => ({
+    id: b.addr,
+    address: b.addr,
+    addressHex: hx(b.addr),
+    size: b.size,
+    ninstr: b.ninstr,
+  }));
+  const edges = [];
+  for (const b of blocks) {
+    const conditional = b.fail != null;
+    if (b.jump != null) edges.push({ from: b.addr, to: b.jump, type: conditional ? "branch_true" : "jump_or_fall" });
+    if (b.fail != null) edges.push({ from: b.addr, to: b.fail, type: "branch_false" });
+  }
+  return {
+    platform, arch,
+    address, addressHex: hx(address),
+    blockCount: nodes.length,
+    nodes, edges,
+  };
+}
+
+/**
+ * All cross-references TO `address` across the ROM.
+ * @returns {{platform, address, count, refs: Array<{from, to, type}>}}
+ */
+export async function analyzeXrefs(romPath, address, platformOverride) {
+  if (address == null) throw new Error("analyze xrefs: address required");
+  const { platform, romBytes, arch, bits } = await loadContext(romPath, platformOverride);
+  let refs;
+  try {
+    refs = await runRizinJson({ romBytes, arch, bits, commands: `aaa; axtj @ ${hx(address)}` });
+  } catch (e) {
+    // axtj prints nothing (not even `[]`) when there are zero refs → our JSON
+    // guard throws. Treat "no JSON" as "no refs".
+    if (/no JSON/.test(e.message)) refs = [];
+    else throw e;
+  }
+  const out = (refs ?? []).map((r) => ({
+    from: r.from,
+    fromHex: hx(r.from),
+    to: r.to,
+    type: (r.type || "").toLowerCase(), // CALL / CODE / DATA / STRING
+    opcode: r.opcode,
+  }));
+  return { platform, arch, address, addressHex: hx(address), count: out.length, refs: out };
+}
+
+/**
+ * One-shot structural map: functions + strings + entrypoints from a full
+ * analysis pass. The "give me the shape of this ROM" call.
+ */
+export async function analyzeStructure(romPath, platformOverride) {
+  const { platform, romBytes, arch, bits } = await loadContext(romPath, platformOverride);
+  const [fns, strings, entries] = await Promise.all([
+    runRizinJson({ romBytes, arch, bits, commands: "aaa; aflj" }).catch(() => []),
+    runRizinJson({ romBytes, arch, bits, commands: "aaa; izj" }).catch(() => []),
+    runRizinJson({ romBytes, arch, bits, commands: "aaa; iej" }).catch(() => []),
+  ]);
+  return {
+    platform, arch,
+    functionCount: Array.isArray(fns) ? fns.length : 0,
+    stringCount: Array.isArray(strings) ? strings.length : 0,
+    entrypoints: (Array.isArray(entries) ? entries : []).map((e) => ({ address: e.vaddr, addressHex: hx(e.vaddr) })),
+    functions: (Array.isArray(fns) ? fns : []).slice(0, 512).map((f) => ({
+      address: f.offset, addressHex: hx(f.offset), name: f.name, size: f.size, callers: f.indegree ?? 0,
+    })),
+    strings: (Array.isArray(strings) ? strings : []).slice(0, 256).map((s) => ({
+      address: s.vaddr, addressHex: hx(s.vaddr), value: s.string,
+    })),
+  };
+}
+
+/** Look up rizin's IO map (omlj) for the segment containing `vaddr`. Each map
+ * entry carries {from (vaddr base), delta (vaddr-paddr), to}. Returns
+ * { paddr, vbase } where paddr = vaddr-delta is the raw-file offset and vbase
+ * (= delta) is the address byte 0 of the file maps to on the CPU bus. */
+async function vaMapping(romBytes, arch, bits, vaddr) {
+  let maps;
+  try {
+    maps = await runRizinJson({ romBytes, arch, bits, commands: "omlj" });
+  } catch { maps = []; }
+  for (const m of (Array.isArray(maps) ? maps : [])) {
+    const from = m.from ?? m.vaddr ?? 0;
+    const to = m.to ?? (from + (m.size ?? 0));
+    if (vaddr >= from && vaddr < to) return { paddr: vaddr - (m.delta ?? 0), vbase: m.delta ?? 0 };
+  }
+  return { paddr: vaddr, vbase: 0 };
+}
+
+/**
+ * Decompile the function containing `address` to C pseudocode (Ghidra).
+ * @returns {{platform, langid, address, code, warnings, qualityNote}}
+ */
+export async function analyzeDecompile(romPath, address, platformOverride) {
+  if (address == null) throw new Error("analyze decompile: address required");
+  const platform = platformOverride ?? sniffPlatform(romPath);
+  if (!platform) throw new Error(`analyze decompile: unknown platform for '${path.basename(romPath)}'`);
+  if (!SLEIGH_LANGID[platform]) throw new Error(`analyze decompile: unsupported platform '${platform}'`);
+  const romBytes = new Uint8Array(await readFile(romPath));
+
+  // Use rizin's loader mapping to turn the VA (what the user sees from
+  // target='functions') into the file offset the raw decompiler image needs.
+  // PCE uses the 6502 plugin only for the map/loader (HuC6280 decode is the
+  // decompiler's job via SLEIGH) — its flat image bases at 0 either way.
+  const arch = RIZIN_ARCH[platform] ?? "6502";
+  const bits = { arm: 32, m68k: 32, snes: 16 }[arch];
+  const { paddr, vbase } = await vaMapping(romBytes, arch, bits, address);
+  if (paddr < 0 || paddr >= romBytes.length) {
+    throw new Error(
+      `decompile: address ${hx(address)} maps to file offset ${paddr}, outside the ` +
+      `${romBytes.length}-byte image for ${platform}.`
+    );
+  }
+  // The raw decompiler loads byte 0 at VMA 0. Code that references absolute CPU
+  // addresses (typical 6502: JSR/JMP to $Fxxx) only resolves if the image sits
+  // at the right CPU base. Rizin's map gives `vbase` when it knows the base;
+  // some headerless carts (2600/7800) it loads at 0, so we supply the base from
+  // a per-platform table. Left-pad the image by the base so file offset == CPU
+  // address, then decompile at the function's CPU address. Capped at 64KB (the
+  // 6502 family's whole address space) so a large base never over-allocates.
+  // Atari 2600/7800 are headerless 6502 dumps rizin loads at 0; supply the real
+  // CPU base so absolute references ($8000/$C000/$F000) resolve. 7800's base is
+  // size-dependent (16KB→$C000, 32KB→$8000); 7800 carts may carry a 128-byte
+  // header before the body.
+  let forcedBase = 0, bodyStart = 0;
+  if (platform === "atari2600") {
+    forcedBase = 0xf000;
+  } else if (platform === "atari7800") {
+    const hasHdr = romBytes.length > 128 &&
+      romBytes[1] === 0x41 && romBytes[2] === 0x54; // "AT"
+    bodyStart = hasHdr ? 128 : 0;
+    const body = romBytes.length - bodyStart;
+    forcedBase = body <= 0x4000 ? 0xc000 : body <= 0x8000 ? 0x8000 : 0x4000;
+  }
+  const base = vbase > 0 ? vbase : forcedBase;
+  let image = romBytes, decompAddr = paddr;
+  if (base > 0 && base <= 0x10000) {
+    const body = romBytes.subarray(bodyStart);
+    const padded = new Uint8Array(base + body.length);
+    padded.set(body, base);
+    image = padded;
+    decompAddr = base + (paddr - bodyStart); // CPU address of the function
+  }
+  const r = await decompileFunction({ platform, romBytes: image, fileOffset: decompAddr });
+  const QUALITY = {
+    gba: "excellent (ARM)", genesis: "excellent (M68K)",
+    gb: "good (SM83)", gbc: "good (SM83)", sms: "good (Z80)", gg: "good (Z80)", msx: "good (Z80)",
+    snes: "medium (65816 variable register width)", pce: "medium (HuC6280)",
+    nes: "rough (6502 architecture limit)", atari2600: "rough (6502)", atari7800: "rough (6502)",
+    c64: "rough (6502)", lynx: "rough (65C02)",
+  };
+  return {
+    platform, langid: r.langid,
+    address, addressHex: hx(address),
+    code: r.code,
+    warnings: r.warnings,
+    qualityNote: QUALITY[platform] ?? "unknown",
+  };
+}

package/src/analysis/decompile.js

@@ -0,0 +1,108 @@
+// decompile.js — drive the Ghidra decompiler WASM (romdev-analysis-decompiler)
+// to turn a function into C pseudocode. Runs the decompiler's REPL one-shot
+// through the isolated worker pool: mount the SLEIGH home + the ROM image,
+// feed `load file <langid> <rom>; map function <addr>; decompile; print C`.
+//
+// The ROM is loaded as a RAW binary at VMA 0 — so the address passed must be a
+// FILE OFFSET into the image we hand it, not a banked CPU address. Callers that
+// have a CPU address use the disasm mappers to slice the right bank first; for
+// the common flat/first-bank case the file offset equals the CPU address minus
+// the platform's load base (handled in analyze.js).
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import fs from "node:fs";
+import { runIsolated } from "../toolchains/_worker/run.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/** Resolve the decompiler package (or the gitignored src staging fallback). */
+function decompilerPaths() {
+  let base;
+  try {
+    base = path.dirname(fileURLToPath(import.meta.resolve("romdev-analysis-decompiler")));
+  } catch { base = null; }
+  const candidates = [
+    base && { js: path.join(base, "wasm", "decompile.js"), sleigh: path.join(base, "sleigh") },
+    { js: path.join(__dirname, "decompiler", "wasm", "decompile.js"), sleigh: path.join(__dirname, "decompiler", "sleigh") },
+  ].filter(Boolean);
+  for (const c of candidates) if (fs.existsSync(c.js)) return c;
+  throw new Error(
+    "decompiler not found: install romdev-analysis-decompiler or run scripts/build-decompiler.sh"
+  );
+}
+
+/** romdev platform → Ghidra SLEIGH language id. null = not decompilable yet. */
+export const SLEIGH_LANGID = {
+  nes: "6502:LE:16:default",
+  atari2600: "6502:LE:16:default",
+  atari7800: "6502:LE:16:default",
+  c64: "6502:LE:16:default",
+  lynx: "65C02:LE:16:default",
+  sms: "z80:LE:16:default",
+  gg: "z80:LE:16:default",
+  msx: "z80:LE:16:default",
+  gb: "SM83:LE:16:default",
+  gbc: "SM83:LE:16:default",
+  gba: "ARM:LE:32:v4t",
+  genesis: "68000:BE:32:default",
+  snes: "65816:LE:24:snes",
+  pce: "HuC6280:LE:16:default",
+};
+
+/**
+ * Decompile the function at `fileOffset` in `romBytes` for `platform`.
+ * @returns {{platform, langid, address, code, warnings:string[], raw:string}}
+ */
+export async function decompileFunction({ platform, romBytes, fileOffset, name = "fn_target" }) {
+  const langid = SLEIGH_LANGID[platform];
+  if (!langid) throw new Error(`decompile: no SLEIGH language for platform '${platform}'`);
+  const { js, sleigh } = decompilerPaths();
+  const addr = "0x" + (fileOffset >>> 0).toString(16);
+
+  // REPL script. RawBinary loads at vma 0; `print C` emits the pseudocode.
+  const script = [
+    `load file ${langid} /work/rom.bin`,
+    `map function ${addr} ${name}`,
+    `decompile ${name}`,
+    `print C`,
+    `quit`,
+    "",
+  ].join("\n");
+
+  const res = await runIsolated({
+    gluePath: js,
+    argv: [],
+    env: { SLEIGHHOME: "/sleigh" },
+    stdinText: script,
+    hostDirMounts: [{ hostDir: sleigh, vfsDir: "/sleigh" }],
+    inputFiles: [{
+      vfsPath: "/work/rom.bin",
+      encoding: "base64",
+      data: Buffer.from(romBytes).toString("base64"),
+    }],
+  });
+
+  const raw = res.log ?? "";
+  // The decompiler echoes each prompt; the C body follows `print C`.
+  const code = extractC(raw);
+  const warnings = [...raw.matchAll(/\/\* WARNING: (.+?) \*\//g)].map((m) => m[1]);
+  if (!code) {
+    throw new Error(`decompile produced no C output (exit=${res.exitCode}): ${raw.slice(-400)}`);
+  }
+  return { platform, langid, address: fileOffset, addressHex: addr, code, warnings, raw };
+}
+
+/** Pull the C function text out of the REPL transcript (between `print C` and
+ * the next `[decomp]>` prompt). */
+function extractC(transcript) {
+  const lines = transcript.split("\n");
+  const start = lines.findIndex((l) => /\[decomp\]>\s*print C\b/.test(l));
+  if (start === -1) return null;
+  const body = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^\[decomp\]>/.test(lines[i])) break;
+    body.push(lines[i]);
+  }
+  const text = body.join("\n").trim();
+  return text.length ? text : null;
+}

package/src/analysis/decompiler/sleigh/6502.cspec

@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<compiler_spec>
+  <global>
+    <range space="RAM"/>
+  </global>
+  <stackpointer register="SP" space="RAM" growth="negative"/>
+  <returnaddress>
+    <varnode space="stack" offset="1" size="2"/>
+  </returnaddress>
+  <default_proto>
+    <prototype name="__stdcall" extrapop="2" stackshift="2" strategy="register">
+      <input>
+        <pentry minsize="1" maxsize="1">
+          <register name="A"/>
+        </pentry>
+        <pentry minsize="1" maxsize="1">
+          <register name="X"/>
+        </pentry>
+        <pentry minsize="1" maxsize="1">
+          <register name="Y"/>
+        </pentry>
+      </input>
+      <output>
+        <pentry minsize="1" maxsize="1">
+          <register name="A"/>
+        </pentry>
+      </output>
+      <unaffected>
+        <register name="SP"/>
+      </unaffected>
+    </prototype>
+  </default_proto>
+</compiler_spec>

package/src/analysis/decompiler/sleigh/6502.ldefs

@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<language_definitions>
+  
+  <language processor="6502"
+            endian="little"
+            size="16"
+            variant="default"
+            version="1.0"
+            slafile="6502.sla"
+            processorspec="6502.pspec"
+            manualindexfile="../manuals/6502.idx"
+            id="6502:LE:16:default">
+    <description>6502 Microcontroller Family</description>
+    <compiler name="default" spec="6502.cspec" id="default"/>
+    <external_name tool="IDA-PRO" name="m6502"/>
+  </language>
+
+  <language processor="65C02"
+            endian="little"
+            size="16"
+            variant="default"
+            version="1.0"
+            slafile="65c02.sla"
+            processorspec="6502.pspec"
+            manualindexfile="../manuals/65c02.idx"
+            id="65C02:LE:16:default">
+    <description>65C02 Microcontroller Family</description>
+    <compiler name="default" spec="6502.cspec" id="default"/>
+	<external_name tool="IDA-PRO" name="m65c02"/>
+  </language>
+  
+</language_definitions>

package/src/analysis/decompiler/sleigh/6502.pspec

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<processor_spec>
+  <programcounter register="PC"/>
+  
+  <default_symbols>
+    <symbol name="NMI" address="FFFA" entry="true" type="code_ptr"/>
+    <symbol name="RES" address="FFFC" entry="true" type="code_ptr"/>
+    <symbol name="IRQ" address="FFFE" entry="true" type="code_ptr"/>
+  </default_symbols>
+  
+  <default_memory_blocks>
+    <memory_block name="ZERO_PAGE" start_address="0x0000" length="0x0100" initialized="false"/>
+    <memory_block name="STACK" start_address="0x0100" length="0x0100" initialized="false"/>
+  </default_memory_blocks>
+</processor_spec>