romdevtools 0.21.0 → 0.22.0

package/src/toolchains/assemble-snippet.js

@@ -25,11 +25,30 @@ import { runCa65, runLd65 } from "./cc65/cc65.js";
 import { runAsar } from "./asar/asar.js";
 import { runVasm68k } from "./vasm68k/vasm68k.js";
 import { runSdasz80, runSdld, ihxToBin } from "./sdcc/sdcc.js";
-import { runRgbasm, runRgblink, runRgbfix } from "./rgbds/rgbds.js";
+import { runRgbasm, runRgblink } from "./rgbds/rgbds.js";
+import { parseBuildLog } from "./parse-errors.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
+// Build a transparent snippet-assembly error: lead with the FIRST structured
+// diagnostic (file:line: message) parsed out of the raw log — the same
+// issues[]-style surfacing build() does — instead of dumping the unparsed
+// assembler stdout and making the agent grep it. Full log still appended for
+// fallback. `where` is e.g. "ca65" / "ld65 link" / "asar".
+function asmError(where, log) {
+  const issues = parseBuildLog(log ?? "");
+  const first = issues.find((i) => i.severity === "error") ?? issues[0];
+  const headline = first
+    ? `${first.file ? first.file + ":" : ""}${first.line ? first.line + ": " : ""}${first.message}`
+    : "no structured diagnostic found";
+  return new Error(
+    `assembleSnippet[${where}] failed: ${headline}` +
+    (issues.length > 1 ? ` (+${issues.length - 1} more issue(s))` : "") +
+    `\nFix the source line above. Full assembler log:\n${log ?? ""}`,
+  );
+}
+
 /**
  * CPU dialect → assembler dispatch. Keys are also the public API.
  */
@@ -102,7 +121,7 @@ async function assembleCa65({ origin, code }, cpu = "6502") {
 
   const asm = await runCa65({ source });
   if (!asm.object) {
-    throw new Error(`assembleSnippet[ca65]: assembly failed.\nlog:\n${asm.log ?? ""}`);
+    throw asmError("ca65", asm.log);
   }
 
   // Minimal linker config: one MEMORY block at `origin`, one SEGMENT
@@ -116,7 +135,7 @@ SEGMENTS { CODE: load = OUT, type = ro; }
     linkerConfig: cfg,
   });
   if (!linked.binary) {
-    throw new Error(`assembleSnippet[ld65]: link failed.\nlog:\n${linked.log ?? ""}`);
+    throw asmError("ld65 link", linked.log);
   }
   return { bytes: linked.binary, log: (asm.log ?? "") + (linked.log ?? "") };
 }
@@ -137,7 +156,7 @@ async function assembleAsar({ origin, code }) {
   const source = `org ${hex24}\n${code}\n`;
   const r = await runAsar({ source, baseRom, symbols: false });
   if (!r.binary) {
-    throw new Error(`assembleSnippet[asar]: assembly failed.\nlog:\n${r.log ?? ""}`);
+    throw asmError("asar", r.log);
   }
   const bin = r.binary;
   // Find first non-sentinel byte (asar may have written anywhere depending
@@ -148,7 +167,7 @@ async function assembleAsar({ origin, code }) {
     if (bin[i] !== SENTINEL) { start = i; break; }
   }
   if (start < 0) {
-    throw new Error(`assembleSnippet[asar]: no bytes written (origin 0x${origin.toString(16)})\nlog:\n${r.log ?? ""}`);
+    throw new Error(`assembleSnippet[asar]: no bytes written (origin 0x${origin.toString(16)}) — the source assembled but emitted nothing at this origin. Check the org address and that the code actually emits bytes.\nFull log:\n${r.log ?? ""}`);
   }
   let end = start + 1;
   let sentinelRun = 0;
@@ -181,7 +200,7 @@ async function assembleVasm68k({ origin, code }) {
   const source = `\torg $${origin.toString(16).toUpperCase()}\n${indented}\n`;
   const r = await runVasm68k({ source, options: ["-Fbin"] });
   if (!r.binary || (r.exitCode != null && r.exitCode !== 0)) {
-    throw new Error(`assembleSnippet[vasm68k]: assembly failed.\nlog:\n${r.log ?? ""}`);
+    throw asmError("vasm68k", r.log);
   }
   return { bytes: r.binary, log: r.log ?? "" };
 }
@@ -199,7 +218,7 @@ async function assembleSdcc({ origin, code }) {
   const source = `\t.module snippet\n\t.area _CODE\n${indented}\n`;
   const asm = await runSdasz80({ source });
   if (!asm.rel) {
-    throw new Error(`assembleSnippet[sdasz80]: assembly failed.\nlog:\n${asm.log ?? ""}`);
+    throw asmError("sdasz80", asm.log);
   }
   // Minimal empty crt0 rel: just declares _HEADER0 (zero bytes) and is
   // enough for sdld to satisfy its hardcoded crt0.rel dependency.
@@ -212,7 +231,7 @@ async function assembleSdcc({ origin, code }) {
     libraries: [],
   });
   if (!linked.ihx) {
-    throw new Error(`assembleSnippet[sdld]: link failed.\nlog:\n${linked.log ?? ""}`);
+    throw asmError("sdld link", linked.log);
   }
   const padded = ihxToBin(linked.ihx, 0x10000, 0xFF);
   // Find first and last non-FF byte from origin onwards. The snippet bytes
@@ -232,19 +251,18 @@ async function assembleSdcc({ origin, code }) {
 async function assembleRgbds({ origin, code }) {
   // rgbasm needs SECTION declarations to place code at an address.
   const sectionAt = `$${origin.toString(16).toUpperCase()}`;
-  const source = `SECTION "snippet", ROMX[${sectionAt}], BANK[0]\n${code}\n`;
-  // Actually GB has no BANK[0] for fixed ROM — use ROM0 if origin < 0x4000.
+  // GB has no BANK[0] for fixed ROM — use ROM0 if origin < 0x4000, else ROMX BANK[1].
   const useRom0 = origin < 0x4000;
   const realSource = useRom0
     ? `SECTION "snippet", ROM0[${sectionAt}]\n${code}\n`
     : `SECTION "snippet", ROMX[${sectionAt}], BANK[1]\n${code}\n`;
   const asm = await runRgbasm({ source: realSource });
   if (!asm.object) {
-    throw new Error(`assembleSnippet[rgbasm]: assembly failed.\nlog:\n${asm.log ?? ""}`);
+    throw asmError("rgbasm", asm.log);
   }
   const linked = await runRgblink({ objects: { "snippet.o": asm.object }, padValue: 0x00 });
   if (!linked.binary) {
-    throw new Error(`assembleSnippet[rgblink]: link failed.\nlog:\n${linked.log ?? ""}`);
+    throw asmError("rgblink link", linked.log);
   }
   // Slice from origin, find last non-zero byte.
   const start = useRom0 ? origin : (origin - 0x4000 + 0x4000); // bank 1 lives at file 0x4000

package/src/toolchains/cc65/presets/nes/chr-ram-runtime.cfg

@@ -19,7 +19,13 @@
 #   3. Write CHR data from C at runtime: PPUADDR = 0x00; PPUDATA = byte; etc.
 
 SYMBOLS {
-    __STACKSIZE__: type = weak, value = $0300;
+    # Stack is $0200 (512 B) so the top RAM page ($0700-$07FF) can be
+    # reserved below for a music driver's scratch RAM (FamiTone2 et al.),
+    # which needs a dedicated, page-aligned block that the C BSS/DATA
+    # region must NOT overlap. Tiny NROM scaffolds use far less than 512 B
+    # of stack, so this is safe; scaffolds with no music driver simply
+    # leave the reserved page unused.
+    __STACKSIZE__: type = weak, value = $0200;
 }
 MEMORY {
     ZP:     file = "", start = $0002, size = $001A, type = rw, define = yes;
@@ -37,6 +43,13 @@ MEMORY {
 
     SRAM:   file = "", start = $0500, size = __STACKSIZE__, define = yes;
 
+    # Reserved page for a sound-driver's RAM scratch ($0700-$07FF). The
+    # bundled FamiTone2 engine (music_demo scaffold) pins FT_BASE_ADR here
+    # so its ~90 bytes of channel/envelope state can't collide with the C
+    # BSS/DATA at $0300-$04FF — that collision silently clobbers the NMI's
+    # cached PPUCTRL and stalls rendering. Unused by non-music scaffolds.
+    SNDRAM: file = "", start = $0700, size = $0100, define = yes;
+
     # BSS / DATA live in real RAM ($0300-$04FF, 512 bytes). NROM (mapper 0)
     # with no battery has $6000-$7FFF UNMAPPED — reads return open bus.
     # Putting BSS there means `int counter = 0;` reads garbage (intermittent

package/src/toolchains/common/reassemble.js

@@ -20,7 +20,6 @@ const hex2 = (b) => "$" + (b & 0xFF).toString(16).padStart(2, "0").toUpperCase()
 // Label form across disassemblers: `L` + 4..8 hex digits (m68k targets can be
 // 24-bit, e.g. an $E0FF00xx RAM mirror → LE0FF0080).
 const LABEL_RE = /^(L[0-9A-Fa-f]{4,8}):\s*$/;
-const LABEL_REF_RE = /\bL[0-9A-Fa-f]{4,8}\b/g;
 
 /** Parse one disasm line into {label?, code?, bytes?[]}. */
 function parseLine(line) {

package/src/toolchains/common/sdk-cache.js

@@ -17,7 +17,7 @@
 // This module is platform-agnostic: each toolchain passes in how to hash its
 // source, where its seed lives, and how to compile from source.
 
-import { readFile, writeFile, mkdir, stat } from "node:fs/promises";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import path from "node:path";
 import os from "node:os";

package/src/toolchains/genesis-c/genesis-c.js

@@ -127,7 +127,7 @@ async function compileSgdkRuntime(baseHeaders, cc1Options) {
   for (const [k, v] of Object.entries(localHeaders)) {
     if (/\.i80$/i.test(k)) z80Includes[path.basename(k)] = v;
   }
-  async function loadI80From(dir, rel = "") {
+  async function loadI80From(dir, _rel = "") {
     let ents;
     try { ents = await readdir(dir, { withFileTypes: true }); } catch { return; }
     for (const e of ents) {
@@ -268,8 +268,10 @@ async function buildWithSgdk({ sources, headers, binaryIncludes, cc1Options, reb
   // implicit decls, …) parsed into structured issues[]. The SGDK runtime is
   // compiled WITHOUT these (sgdkCc1Options) — we can't fix SDK warnings and they'd
   // bury the agent's own. -Wno-unused-parameter avoids the common `(void)hard`
-  // scaffold-param noise.
-  const userCc1Options = [...sgdkCc1Options, "-Wall", "-Wextra", "-Wno-unused-parameter"];
+  // scaffold-param noise. -Wno-main: SGDK MANDATES `int main(bool hardReset)`
+  // (sys.c declares it and calls main(TRUE)/main(FALSE)); GCC's -Wmain objects to
+  // the non-standard signature, but it's REQUIRED here, not a bug — so silence it.
+  const userCc1Options = [...sgdkCc1Options, "-Wall", "-Wextra", "-Wno-unused-parameter", "-Wno-main"];
 
   // ── Stage A: gather SGDK headers (visible to tcc via tcc-style flat mount) ──
   // cc1's -iquote /work picks up sibling files mounted alongside main.c.

package/src/toolchains/index.js

@@ -117,6 +117,27 @@ const PLATFORM_DEFAULT_LANGUAGE = {
   msx:        "c",
 };
 
+/**
+ * Order build issues by DANGER so the agent reads the lethal ones first:
+ *   critical (crash-class, e.g. the uint8 infinite-loop)  →  error  →  warning  →  info.
+ * Stable within a rank (preserves source order / file:line). Pure; no dedup.
+ * @param {Array<{severity?:string, critical?:boolean}>} issues
+ * @returns {Array} the same issues, ranked
+ */
+export function rankIssues(issues) {
+  const rank = (i) =>
+    i?.critical ? 0
+    : i?.severity === "error" ? 1
+    : i?.severity === "warning" ? 2
+    : 3;
+  // map→sort→unmap keeps it stable (Array.prototype.sort is stable in V8, but
+  // tie-break on original index to be explicit and portable).
+  return issues
+    .map((issue, idx) => ({ issue, idx }))
+    .sort((a, b) => rank(a.issue) - rank(b.issue) || a.idx - b.idx)
+    .map((x) => x.issue);
+}
+
 /**
  * Public API for the platforms tool to discover the language matrix.
  * Returns `{defaultLanguage, languages: [{language, toolchain, available, note?}]}`.
@@ -835,10 +856,13 @@ export async function buildForPlatform(args) {
         r.log += "\n--- MSX ROM header present (\"AB\") ---";
       }
     }
-    // Combine lint warnings with parsed build log. Lint comes first so
-    // agents see them at the top of the issues array.
+    // Combine lint warnings with parsed build log, then RANK so an agent
+    // triaging issues[] sees the dangerous ones first: crash-class (critical)
+    // → errors → plain warnings. Without this, a "WILL HANG" infinite-loop
+    // warning sits among unused-variable noise and gets skipped (the exact
+    // "agent missed the warning, hit the crash 100 functions later" failure).
     const buildIssues = parseBuildLog(r.log);
-    const issues = [...lintIssues, ...buildIssues];
+    const issues = rankIssues([...lintIssues, ...buildIssues]);
     return {
       ok: r.exitCode === 0 && binary !== null,
       binary,

package/src/toolchains/parse-errors.js

@@ -32,6 +32,9 @@ export function parseBuildLog(log) {
     const baseStage = stage.split(/\s|\(/)[0].toLowerCase();
     if (/^cc65$|^ca65$|^ld65$/.test(baseStage)) {
       issues.push(...parseCc65Like(text, baseStage));
+      // ld65's linker-level errors (segment-missing / memory-overflow) carry no
+      // file:line and slip past parseCc65Like — pick them up too.
+      if (baseStage === "ld65") issues.push(...parseLd65Linker(text, baseStage));
     } else if (/^dasm$/.test(baseStage)) {
       issues.push(...parseDasm(text));
     } else if (/^asar$/.test(baseStage)) {
@@ -68,6 +71,7 @@ export function parseBuildLog(log) {
       // failure). Include vasm + sdcc + wla, which the old fallback omitted.
       const tag = baseStage || "unknown";
       issues.push(...parseCc65Like(text, tag));
+      issues.push(...parseLd65Linker(text, tag));
       issues.push(...parseSdcc(text, tag));
       issues.push(...parseDasm(text));
       issues.push(...parseAsar(text, tag));
@@ -109,6 +113,50 @@ function splitByStage(log) {
   return stages;
 }
 
+// ld65 LINKER diagnostics have NO file:line — parseCc65Like (which requires a
+// `file:line:` lead) misses them entirely, so a failed link returned issues[]
+// EMPTY even though the real error sat in the log. The common ones on a
+// mis-wired NES rebuild (wrong/absent linker config for the project's segments):
+//   ld65: Warning: Segment 'HEADER' does not exist
+//   ld65: Error: Memory area overflow in 'ROM0', segment 'CODE' (6 bytes)
+//   Error: Cannot generate most of the files due to memory area overflow
+// They appear either bare or with an `ld65:`/`ld65.exe:` tool prefix. We add a
+// short hint on the segment/overflow case (the linker config doesn't match the
+// project's segments — the exact CHR-ROM-vs-CHR-RAM mismatch agents hit).
+function parseLd65Linker(text, stage) {
+  const out = [];
+  const re = /^(?:ld65(?:\.exe)?:\s*)?(?<sev>Error|Warning):\s*(?<msg>.+)$/gm;
+  let m;
+  while ((m = re.exec(text))) {
+    const msg = m.groups.msg.trim().replace(/\x1b\[[0-9;]*m/g, "");
+    // Skip the file:line form — parseCc65Like already owns those (and a leading
+    // path would have been consumed as the message here, doubling the issue).
+    if (/^[^\s:]+:\d+:/.test(msg)) continue;
+    // Actionable hint in a SEPARATE field (matching GNU ld / sdld), not glued
+    // onto the message — two common ld65 link failures:
+    let hint;
+    if (/does not exist|overflow|Cannot generate/i.test(msg)) {
+      hint =
+        "The linker config's segments don't match the project. For an NROM " +
+        "rebuild use build({inesHeader:{...}}) or linkerConfig:'chr-rom'; otherwise " +
+        "check that your .cfg's SEGMENTS match the .segment names in your source.";
+    } else if (/unresolved external|undefined symbol/i.test(msg)) {
+      const sym = msg.match(/['"`]?(?<s>[A-Za-z_]\w*)['"`]?\s*$/)?.groups?.s;
+      hint =
+        `${sym ? `\`${sym}'` : "That symbol"} is referenced but never defined or linked. ` +
+        "Add the source/object that defines it (or the right cc65 lib for this platform) " +
+        "to your build, or check for a typo.";
+    }
+    out.push({
+      severity: m.groups.sev.toLowerCase() === "error" ? "error" : "warning",
+      message: msg,
+      stage: stage || "ld65",
+      ...(hint ? { hint } : {}),
+    });
+  }
+  return out;
+}
+
 // cc65, ca65, ld65 all use the gcc-style `file:line:col?: severity: message`.
 // Example:
 //   /work/main.s:12: Error: Cannot open include file 'longbranch.mac'
@@ -173,10 +221,25 @@ function parseSdcc(text, stage) {
     // An "Undefined Global" is effectively an error even though ASlink labels it
     // a warning — the ROM won't run. Promote it so the agent treats it as fatal.
     const isUndef = /undefined\s+global/i.test(msg);
+    // Give the same actionable hint GNU ld's undefined-reference path gets, so
+    // the SDCC platforms (GB/GBC/SMS/GG/MSX) reach parity on the single most
+    // common link failure (forgot to include the source/runtime that defines it).
+    // SDCC mangles C symbols with a leading '_' — show the C name too.
+    let hint;
+    if (isUndef) {
+      const sym = msg.match(/global\s+['"]?(?<s>\w+)['"]?/i)?.groups?.s;
+      const cName = sym && sym.startsWith("_") ? sym.slice(1) : sym;
+      hint =
+        `${sym ? `\`${sym}'` : "That symbol"} is called but never defined or linked` +
+        `${cName && cName !== sym ? ` (the C name is \`${cName}'; SDCC prefixes an underscore)` : ""}. ` +
+        "Add the source file (or runtime/library) that defines it to your build's sources/includes, " +
+        "or check for a typo in the name.";
+    }
     out.push({
       severity: lm.groups.sev === "Error" || isUndef ? "error" : "warning",
       message: "linker: " + msg,
       stage: "sdld",
+      ...(hint ? { hint } : {}),
     });
   }
   return out;
@@ -268,12 +331,26 @@ function parseWla(text, stage = "wla") {
   const reLink = /^(?<obj>\S+\.obj):\s*(?<file>[^\s:]+):(?<line>\d+):\s*(?<phase>[A-Z_]+):\s*(?<msg>.+)$/gm;
   let m;
   while ((m = reLink.exec(text))) {
+    const rawMsg = m.groups.msg.trim();
+    // An "unknown label" reference is SNES's undefined-symbol failure — give it
+    // the same actionable hint ld65/sdld/GNU ld carry, so SNES reaches parity.
+    let hint;
+    const lbl = /unknown label\s+["'`]?(?<l>[A-Za-z_]\w*)/i.exec(rawMsg)?.groups?.l;
+    if (lbl || /reference to an unknown/i.test(rawMsg)) {
+      hint =
+        `${lbl ? `\`${lbl}'` : "That label"} is referenced but never defined or linked. ` +
+        "Add the source/object that defines it (or the right PVSnesLib runtime) to your build, " +
+        "or check for a typo.";
+    }
     out.push({
       severity: "error",
       file: m.groups.file,
       line: parseInt(m.groups.line, 10),
-      message: `${m.groups.phase}: ${m.groups.msg.trim()}`,
+      // Keep the wla internal phase name (FIX_REFERENCES, etc.) out of the
+      // agent-facing message — it's noise; the message + hint say what to do.
+      message: rawMsg,
       stage: stage === "wla" ? "wlalink" : stage,
+      ...(hint ? { hint } : {}),
     });
   }
   // wla-65816 assembler: "<file>:<line>: ERROR|WARNING: <message>"

package/src/toolchains/sdcc/preflight-lint.js

@@ -136,10 +136,14 @@ export function lintSdccSource(source, file = "main.c", opts = {}) {
       if (bound !== null && bound > 255) {
         issues.push({
           severity: "warning",
+          // CRASH-CLASS: not cosmetic — this loop never exits and hangs the
+          // game. `critical` lifts it above ordinary warnings so an agent
+          // triaging issues[] can't miss it among unused-variable noise.
+          critical: true,
           file,
           line: i + 1,
           stage: "lint",
-          message: `uint8 loop counter '${counter}' with bound ${bound} (> 255) — infinite loop`,
+          message: `WILL HANG: uint8 loop counter '${counter}' with bound ${bound} (> 255) — infinite loop`,
           details: `A u8/uint8_t/char counter can never reach ${bound}, so this loop never exits and all code after it is dead. ${portLabel} gives no warning. Declare '${counter}' as uint16_t. See GB TROUBLESHOOTING § uint8 loop-bound trap.`,
           ref: "uint8-loop-bound",
         });

package/src/toolchains/sdcc/sdcc.js

@@ -56,7 +56,7 @@ export const SDCC_PORTS = {
   msx:        { marg: "z80",      libDir: "z80" },
 };
 
-import { runIsolated, textFile, binaryFile, getOutputBytes, getOutputText } from "../_worker/run.js";
+import { runIsolated, textFile, getOutputText } from "../_worker/run.js";
 
 /**
  * Tag the abort/crash log with the SDCC-flavored hint pointing at the

package/src/toolchains/sjasm/sjasm.js

@@ -5,7 +5,7 @@
 // #include that generated .h. Built by scripts/build-sjasm.sh.
 
 import { fileURLToPath } from "node:url";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import path from "node:path";
 
 const __filename = fileURLToPath(import.meta.url);

package/src/toolchains/snes-c/snes-c.js

@@ -288,7 +288,7 @@ async function buildWithPvSnesLib({ sources, headers, tccOptions, wlaOptions, bi
  * Minimum-viable path (R16 original behavior). No PVSnesLib runtime;
  * bundled original crt0.asm + hdr.asm support a bare `int main()`.
  */
-async function buildMinimal({ sources, headers, tccOptions, wlaOptions, binaryIncludes = {} }) {
+async function buildMinimal({ sources, headers, tccOptions, wlaOptions, _binaryIncludes = {} }) {
   let log = "";
   const hdrAsm  = await readFile(path.join(MINIMAL_LIB_DIR, "hdr.asm"),  "utf-8");
   const crt0Asm = await readFile(path.join(MINIMAL_LIB_DIR, "crt0.asm"), "utf-8");
@@ -380,7 +380,7 @@ async function buildMinimal({ sources, headers, tccOptions, wlaOptions, binaryIn
 let _headerCache = null;
 async function loadPvSnesLibHeaders() {
   if (_headerCache) return _headerCache;
-  const { readdir, stat } = await import("node:fs/promises");
+  const { readdir } = await import("node:fs/promises");
   const out = {};
   /**
    * @param {string} dir

package/src/toolchains/vasm68k/vasm68k.js

@@ -49,10 +49,8 @@ function vasm68kPreflight(source) {
   const issues = [];
 
   // Check 1: source includes an org $00000000 or starts at $00 implicitly.
-  // vasm68k defaults to $00000000 if no org is given, so missing org is fine.
-  // But if an `org $00000200` (or similar) appears WITHOUT a preceding
-  // vector table, the cart is unbootable.
-  const hasOrg0 = /\borg\s+\$0+\b/i.test(source) || /\borg\s+0\b/i.test(source);
+  // vasm68k defaults to $00000000 if no org is given, so a missing org is fine;
+  // what actually breaks boot is a missing reset vector, which we check below.
   const hasReset = /\bdc\.l\s+(\$00FF[E-F][0-9A-F]{3}|_reset|reset)\b/i.test(source);
   if (!hasReset) {
     issues.push(

package/src/toolchains/wladx/wladx.js

@@ -15,7 +15,7 @@ import { fileURLToPath } from "node:url";
 import { existsSync } from "node:fs";
 import path from "node:path";
 
-import { runIsolated, textFile, binaryFile, getOutputBytes, getOutputText } from "../_worker/run.js";
+import { runIsolated, textFile, binaryFile, getOutputBytes } from "../_worker/run.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);