@henols/c64-re-tools 2.0.0-rc.2 → 2.0.0-rc.21

package/skills/c64-static-analysis/scripts/{findings.ts → lib/findings.ts}

@@ -5,6 +5,7 @@ import type { DatabaseSync } from "node:sqlite";
 
 import type { NormalizedFindings } from "#src/knowledge/import.ts";
 import { listRegions, listSymbols } from "#src/knowledge/read.ts";
+import { CODE_REGION_TYPES, DEFAULT_SPACE, type Space } from "#src/knowledge/schema.ts";
 import type { DxaResult, GhidraParams, GhidraResult } from "#src/native/types.ts";
 
 export type Seeds = Pick<GhidraParams, "entryPoints" | "dataRanges" | "labels">;
@@ -18,13 +19,14 @@ const semantic = (row: { origin: string }) => row.origin === "user" || row.origi
  * earlier guess would force the same answer again, and a re-analysis could
  * not retire it.
  */
-export function seedsFromKnowledge(db: DatabaseSync | undefined, extraEntryPoints: number[] = []): Seeds {
-  const symbols = listSymbols(db).filter(semantic);
+export function seedsFromKnowledge(db: DatabaseSync | undefined, extraEntryPoints: number[] = [], space: Space = DEFAULT_SPACE): Seeds {
+  const symbols = listSymbols(db, undefined, undefined, undefined, space).filter(semantic);
   const entryPoints = [...new Set([...extraEntryPoints, ...symbols.filter((symbol) => symbol.kind === "routine").map((symbol) => symbol.address)])].sort((a, b) => a - b);
   return {
     entryPoints,
-    dataRanges: listRegions(db)
-      .filter((region) => semantic(region) && region.type !== "code")
+    dataRanges: listRegions(db, undefined, undefined, undefined, space)
+      // A JMP table is code and dual-use bytes are both: neither is a data range (D42).
+      .filter((region) => semantic(region) && !CODE_REGION_TYPES.includes(region.type) && region.type !== "dual-use")
       .map((region) => ({ start: region.start, end: region.end })),
     labels: symbols.map((symbol) => ({ address: symbol.address, name: symbol.name })),
   };
@@ -44,11 +46,15 @@ export function ghidraFindings(result: GhidraResult): NormalizedFindings {
   for (const fn of result.functions) uses.set(fn.name, (uses.get(fn.name) ?? 0) + 1);
   const nameOf = (fn: GhidraResult["functions"][number]) =>
     fn.nameSource !== "seed" && uses.get(fn.name)! > 1 ? `${fn.name}_${fn.entry.toString(16).padStart(4, "0")}` : fn.name;
+  // A function that branches and jumps reach, and no call, is a place in a routine: a label (D74).
+  const called = new Set(result.references.filter((reference) => reference.type === "call").map((reference) => reference.to));
+  const jumped = new Set(result.references.filter((reference) => reference.type === "jump").map((reference) => reference.to));
+  const kindOf = (fn: GhidraResult["functions"][number]) => (jumped.has(fn.entry) && !called.has(fn.entry) ? ("label" as const) : ("routine" as const));
   return {
     analyzer: "ghidra",
     coverage: result.coverage,
     authoritative: { symbols: result.completeness.functions, regions: result.completeness.regions, references: result.completeness.references },
-    symbols: result.functions.map((fn) => ({ address: fn.entry, name: nameOf(fn), kind: "routine" as const })),
+    symbols: result.functions.map((fn) => ({ address: fn.entry, name: nameOf(fn), kind: kindOf(fn) })),
     regions: result.regions.map((region) => ({ start: region.start, end: region.end, type: region.classification === "code" ? ("code" as const) : ("bytes" as const) })),
     references: result.references.map((reference) => ({ from: reference.from, to: reference.to, kind: reference.type })),
   };

package/skills/c64-static-analysis/scripts/lib/idioms.ts

@@ -0,0 +1,158 @@
+// 6502 idioms that hide code from a disassembler (D44): RTS dispatch tables,
+// JMP tables and BIT skips are found by their exact instruction patterns and
+// become heuristic findings and entry points; DOP padding and self-modified
+// opcodes are only reported. The CBM80 header of a cartridge bank at $8000
+// gives its two start vectors as entry points (F-29). A self-modified opcode is one that one run wrote
+// and executed, in either order, since a coverage file holds no order (R3-04):
+// a copier's writes in one run and their execution in another do not count (F-16). A table's length is not known statically: entries
+// count while each target is a plausible instruction in the program.
+
+import { COVERAGE } from "#src/c64.ts";
+import type { NormalizedFindings } from "#src/knowledge/import.ts";
+import type { ImageByte } from "./coverage.ts";
+
+const MAX_TABLE = 64;
+const MIN_JUMPS = 3;
+const LDA_INDEXED = new Set([0xbd, 0xb9]);
+const JAMS = new Set([0x02, 0x12, 0x22, 0x32, 0x42, 0x52, 0x62, 0x72, 0x92, 0xb2, 0xd2, 0xf2]);
+/** Undocumented NOPs with an operand byte (DOP): padding between instructions hides the real ones. */
+const DOPS = new Set([0x04, 0x14, 0x34, 0x44, 0x54, 0x64, 0x74, 0x80, 0x82, 0x89, 0xc2, 0xd4, 0xe2, 0xf4]);
+/** "CBM80" in PETSCII at $8004: the KERNAL then starts the cartridge through the vectors at $8000 (cold) and $8002 (warm). */
+const CBM80 = [0xc3, 0xc2, 0xcd, 0x38, 0x30];
+
+export interface Idioms {
+  findings: NormalizedFindings;
+  /** Entry points for the same analysis run: analyzer facts are never seeds. */
+  entryPoints: number[];
+  /** Table ranges for the same run: they are data. */
+  dataRanges: Array<{ start: number; end: number }>;
+  counts: { cartridgeHeaders: number; rtsTables: number; jumpTables: number; bitSkips: number };
+  /** Seen in the coverage, not written: the LLM decides. All of them: the result lists the first ones. */
+  candidates: { dop: number[]; selfModified: number[] };
+}
+
+/** True when an instruction can start at the address: inside the program, and no JAM. */
+function plausible(byteAt: ImageByte, address: number, range: { start: number; end: number }): boolean {
+  const opcode = byteAt(address);
+  return address >= range.start && address <= range.end && opcode !== undefined && !JAMS.has(opcode);
+}
+
+const word = (byteAt: ImageByte, address: number) => {
+  const low = byteAt(address);
+  const high = byteAt(address + 1);
+  return low === undefined || high === undefined ? undefined : low | (high << 8);
+};
+
+/** `covered` is the coverage of the knowledge (D83): the joined map, and the addresses that one run wrote and executed. */
+export function findIdioms(byteAt: ImageByte, range: { start: number; end: number }, covered?: { map: Uint8Array; selfModified: Uint8Array }): Idioms {
+  const coverage = covered?.map;
+  const regions: NormalizedFindings["regions"] = [];
+  const references: NormalizedFindings["references"] = [];
+  const entryPoints = new Set<number>();
+  const counts = { cartridgeHeaders: 0, rtsTables: 0, jumpTables: 0, bitSkips: 0 };
+  const taken = (start: number, end: number) => regions.some((region) => start <= region.end && end >= region.start);
+  const addRegion = (start: number, end: number, type: NormalizedFindings["regions"][number]["type"]) => {
+    if (start < range.start || end > range.end || taken(start, end)) return false;
+    regions.push({ start, end, type });
+    return true;
+  };
+
+  if (range.start <= 0x8000 && range.end >= 0x8008 && CBM80.every((byte, index) => byteAt(0x8004 + index) === byte)) {
+    const vectors = [word(byteAt, 0x8000)!, word(byteAt, 0x8002)!].filter((target) => plausible(byteAt, target, range));
+    if (addRegion(0x8000, 0x8003, "addresses") && addRegion(0x8004, 0x8008, "petscii")) {
+      counts.cartridgeHeaders++;
+      for (const target of vectors) entryPoints.add(target);
+    }
+  }
+
+  for (let at = range.start; at + 8 <= range.end; at++) {
+    // RTS dispatch: LDA high,X / PHA / LDA low,X / PHA / RTS.
+    if (LDA_INDEXED.has(byteAt(at)!) && byteAt(at + 3) === 0x48 && LDA_INDEXED.has(byteAt(at + 4)!) && byteAt(at + 7) === 0x48 && byteAt(at + 8) === 0x60) {
+      const high = word(byteAt, at + 1)!;
+      const low = word(byteAt, at + 5)!;
+      const interleaved = high === low + 1;
+      const step = interleaved ? 2 : 1;
+      const targets: number[] = [];
+      for (let index = 0; index < MAX_TABLE; index++) {
+        const lowByte = byteAt(low + index * step);
+        const highByte = byteAt(high + index * step);
+        if (lowByte === undefined || highByte === undefined) break;
+        const target = ((highByte << 8) | lowByte) + 1;
+        if (!plausible(byteAt, target, range)) break;
+        targets.push(target);
+      }
+      if (targets.length === 0) continue;
+      const n = targets.length;
+      const written = interleaved
+        ? addRegion(low, low + 2 * n - 1, "rts-addresses")
+        : low + n === high
+          ? addRegion(low, high + n - 1, "rts-addresses-split")
+          : addRegion(low, low + n - 1, "bytes") && addRegion(high, high + n - 1, "bytes");
+      if (!written) continue;
+      counts.rtsTables++;
+      for (const target of targets) {
+        references.push({ from: at + 8, to: target, kind: "jump" });
+        entryPoints.add(target);
+      }
+    }
+  }
+
+  // JMP tables: at least three JMP abs in a row.
+  for (let at = range.start; at + 3 * MIN_JUMPS - 1 <= range.end; at++) {
+    let n = 0;
+    while (at + 3 * n + 2 <= range.end && byteAt(at + 3 * n) === 0x4c) n++;
+    if (n < MIN_JUMPS || !addRegion(at, at + 3 * n - 1, "jumps")) continue;
+    counts.jumpTables++;
+    for (let index = 0; index < n; index++) {
+      entryPoints.add(at + 3 * index);
+      const target = word(byteAt, at + 3 * index + 1)!;
+      if (plausible(byteAt, target, range)) entryPoints.add(target);
+    }
+    at += 3 * n - 1;
+  }
+
+  // BIT skips: BIT abs ($2c) whose operand bytes are an instruction that a JMP, a JSR or the coverage enters.
+  const entered = new Set<number>();
+  for (let at = range.start; at + 2 <= range.end; at++) {
+    if (byteAt(at) === 0x4c || byteAt(at) === 0x20) entered.add(word(byteAt, at + 1)!);
+  }
+  if (coverage !== undefined) for (let address = range.start; address <= range.end; address++) if ((coverage[address]! & COVERAGE.ramExecute) !== 0) entered.add(address);
+  for (let at = range.start; at + 2 <= range.end; at++) {
+    if (byteAt(at) !== 0x2c || !entered.has(at + 1) || !plausible(byteAt, at + 1, range)) continue;
+    if (!addRegion(at + 1, at + 2, "dual-use")) continue;
+    counts.bitSkips++;
+    entryPoints.add(at);
+    entryPoints.add(at + 1);
+    for (let from = range.start; from + 2 <= range.end; from++) {
+      if ((byteAt(from) === 0x4c || byteAt(from) === 0x20) && word(byteAt, from + 1) === at + 1) references.push({ from, to: at + 1, kind: byteAt(from) === 0x20 ? "call" : "jump" });
+    }
+  }
+
+  // Candidates from the coverage: DOP padding that ran, and opcodes that one run wrote and executed.
+  const candidates = { dop: [] as number[], selfModified: [] as number[] };
+  if (coverage !== undefined) {
+    for (let address = range.start; address <= range.end; address++) {
+      if ((coverage[address]! & COVERAGE.ramExecute) === 0) continue;
+      if (DOPS.has(byteAt(address)!)) candidates.dop.push(address);
+      if (covered!.selfModified[address] === 1) candidates.selfModified.push(address);
+    }
+  }
+
+  regions.sort((a, b) => a.start - b.start);
+  const dataRanges = regions.filter((region) => region.type !== "jumps" && region.type !== "dual-use").map(({ start, end }) => ({ start, end }));
+  return {
+    findings: {
+      analyzer: "heuristic",
+      coverage: [range],
+      authoritative: { symbols: true, regions: true, references: true },
+      symbols: [],
+      regions,
+      // Each reference once: the importer keys them by from, to and kind.
+      references: [...new Map(references.map((reference) => [`${reference.from}|${reference.to}|${reference.kind}`, reference])).values()],
+    },
+    entryPoints: [...entryPoints].sort((a, b) => a - b),
+    dataRanges,
+    counts,
+    candidates,
+  };
+}

package/skills/c64-static-analysis/scripts/lib/instructions.ts

@@ -0,0 +1,105 @@
+// The structured instruction list (D44): Ghidra's decoded instructions with
+// the addressing mode, the operand in 6502 syntax, the flow target and,
+// with a coverage file, whether the instruction ran.
+
+import { COVERAGE, formatC64Address } from "#src/c64.ts";
+import type { GhidraInstruction } from "#src/native/types.ts";
+
+export type Mode =
+  | "implied"
+  | "accumulator"
+  | "immediate"
+  | "zeropage"
+  | "zeropage,x"
+  | "zeropage,y"
+  | "absolute"
+  | "absolute,x"
+  | "absolute,y"
+  | "(indirect)"
+  | "(indirect,x)"
+  | "(indirect),y"
+  | "relative";
+
+const BRANCHES = new Set([0x10, 0x30, 0x50, 0x70, 0x90, 0xb0, 0xd0, 0xf0]);
+const JMP_INDIRECT = 0x6c;
+
+/**
+ * The addressing mode from Ghidra's operand text and the instruction length.
+ * Ghidra prints zero page and absolute alike, and JMP (indirect) as an
+ * address, so the length and the opcode decide those.
+ */
+export function modeOf(opcode: number, length: number, operands: string): Mode {
+  const text = operands.toUpperCase();
+  if (text === "") return "implied";
+  if (text === "A") return "accumulator";
+  if (text.startsWith("#")) return "immediate";
+  if (text.startsWith("(") && text.endsWith(",X)")) return "(indirect,x)";
+  if (text.startsWith("(") && text.endsWith("),Y")) return "(indirect),y";
+  if (text.endsWith(",X")) return length === 2 ? "zeropage,x" : "absolute,x";
+  if (text.endsWith(",Y")) return length === 2 ? "zeropage,y" : "absolute,y";
+  if (BRANCHES.has(opcode)) return "relative";
+  if (opcode === JMP_INDIRECT) return "(indirect)";
+  return length === 2 ? "zeropage" : "absolute";
+}
+
+/** The operand in 6502 syntax, from the instruction bytes; empty for implied. */
+export function operandText(mode: Mode, bytes: Uint8Array, target: number | undefined): string {
+  const byte = `$${(bytes[1] ?? 0).toString(16).padStart(2, "0")}`;
+  const word = formatC64Address((bytes[1] ?? 0) | ((bytes[2] ?? 0) << 8));
+  switch (mode) {
+    case "implied":
+      return "";
+    case "accumulator":
+      return "a";
+    case "immediate":
+      return `#${byte}`;
+    case "zeropage":
+      return byte;
+    case "zeropage,x":
+      return `${byte},x`;
+    case "zeropage,y":
+      return `${byte},y`;
+    case "absolute":
+      return word;
+    case "absolute,x":
+      return `${word},x`;
+    case "absolute,y":
+      return `${word},y`;
+    case "(indirect)":
+      return `(${word})`;
+    case "(indirect,x)":
+      return `(${byte},x)`;
+    case "(indirect),y":
+      return `(${byte}),y`;
+    case "relative":
+      return target === undefined ? byte : formatC64Address(target);
+  }
+}
+
+export interface ListedInstruction {
+  address: string;
+  bytes: string;
+  mnemonic: string;
+  mode: Mode;
+  operand: string;
+  target?: string;
+  executed?: boolean;
+}
+
+/** Ghidra's instructions as the list that --instructions writes. */
+export function instructionList(instructions: GhidraInstruction[], coverage?: Uint8Array): ListedInstruction[] {
+  return instructions.map((instruction) => {
+    const bytes = Buffer.from(instruction.bytes, "hex");
+    const mode = modeOf(bytes[0]!, bytes.length, instruction.operands);
+    const [target] = instruction.flows;
+    return {
+      address: formatC64Address(instruction.address),
+      bytes: (instruction.bytes.match(/../g) ?? []).join(" "),
+      mnemonic: instruction.mnemonic,
+      mode,
+      operand: operandText(mode, bytes, target),
+      ...(target === undefined ? {} : { target: formatC64Address(target) }),
+      ...(coverage === undefined ? {} : { executed: (coverage[instruction.address]! & COVERAGE.ramExecute) !== 0 }),
+    };
+  });
+}

package/skills/c64-static-analysis/scripts/lib/macros.ts

@@ -0,0 +1,233 @@
+// Macro candidates (D73): runs of instructions that are a known 6502 idiom,
+// such as a 16-bit increment, and that a macro can write as one line. They
+// are only reported, never written: the LLM applies them as macro uses with
+// c64-knowledge, and c64-source writes a use only when it gives the bytes of
+// the image.
+//
+// The catalogue is fixed, so each candidate has a name and a body that is
+// known to be correct. A search for any repeated sequence was weighed and not
+// chosen: it gives many candidates without a name (D73).
+
+import { instructionLength } from "#src/c64.ts";
+import type { ImageByte } from "./coverage.ts";
+
+/** A macro of the catalogue: its params and its ACME body, which names a param with a dot. */
+export interface MacroIdiom {
+  name: string;
+  params: string[];
+  body: string;
+  comment: string;
+}
+
+export const CATALOGUE: readonly MacroIdiom[] = [
+  { name: "inc16", params: ["dst"], body: ["        inc .dst", "        bne +", "        inc .dst+1", "+"].join("\n"), comment: "Adds 1 to the 16-bit value at dst." },
+  { name: "dec16", params: ["dst"], body: ["        lda .dst", "        bne +", "        dec .dst+1", "+       dec .dst"].join("\n"), comment: "Subtracts 1 from the 16-bit value at dst. It changes A." },
+  {
+    name: "add16_8",
+    params: ["dst", "value"],
+    body: ["        clc", "        lda .dst", "        adc #.value", "        sta .dst", "        bcc +", "        inc .dst+1", "+"].join("\n"),
+    comment: "Adds the 8-bit value to the 16-bit value at dst. It changes A.",
+  },
+  {
+    name: "add16",
+    params: ["dst", "value"],
+    body: ["        clc", "        lda .dst", "        adc #<.value", "        sta .dst", "        lda .dst+1", "        adc #>.value", "        sta .dst+1"].join("\n"),
+    comment: "Adds the 16-bit value to the 16-bit value at dst. It changes A.",
+  },
+  {
+    name: "sub16",
+    params: ["dst", "value"],
+    body: ["        sec", "        lda .dst", "        sbc #<.value", "        sta .dst", "        lda .dst+1", "        sbc #>.value", "        sta .dst+1"].join("\n"),
+    comment: "Subtracts the 16-bit value from the 16-bit value at dst. It changes A.",
+  },
+  {
+    name: "set16",
+    params: ["dst", "value"],
+    body: ["        lda #<.value", "        sta .dst", "        lda #>.value", "        sta .dst+1"].join("\n"),
+    comment: "Puts the 16-bit value at dst. It changes A.",
+  },
+  {
+    name: "mov16",
+    params: ["dst", "src"],
+    body: ["        lda .src", "        sta .dst", "        lda .src+1", "        sta .dst+1"].join("\n"),
+    comment: "Copies the 16-bit value at src to dst. It changes A.",
+  },
+  { name: "wait_line", params: ["line"], body: ["        lda #.line", "-       cmp $d012", "        bne -"].join("\n"), comment: "Waits until the raster line (bits 0-7) is line. It changes A." },
+];
+
+/** A run of instructions that one macro of the catalogue can write, with its args as ACME expressions. */
+export interface MacroCandidate {
+  macro: string;
+  start: number;
+  end: number;
+  args: string[];
+}
+
+/** One instruction: its opcode, its length and its operand value. */
+export interface Instruction {
+  opcode: number;
+  length: number;
+  value: number;
+}
+
+/** An address operand: zero page or absolute, of the same memory in one idiom. */
+interface Operand {
+  value: number;
+  absolute: boolean;
+}
+
+/** Opcodes by mnemonic, zero page first, then absolute. */
+const MEMORY = {
+  lda: [0xa5, 0xad],
+  sta: [0x85, 0x8d],
+  inc: [0xe6, 0xee],
+  dec: [0xc6, 0xce],
+} as const;
+const IMMEDIATE = { lda: 0xa9, adc: 0x69, sbc: 0xe9 } as const;
+const CLC = 0x18;
+const SEC = 0x38;
+const BNE = 0xd0;
+const BCC = 0x90;
+const CMP_ABSOLUTE = 0xcd;
+
+/**
+ * Names the args of a candidate: `address` gives the name of an address in
+ * the knowledge, or undefined. An absolute operand below $0100 keeps four
+ * digits, so ACME writes the absolute form again.
+ */
+export type Namer = (address: number) => string | undefined;
+
+const hex2 = (value: number) => `$${value.toString(16).padStart(2, "0")}`;
+const hex4 = (value: number) => `$${value.toString(16).padStart(4, "0")}`;
+
+function addressArg(operand: Operand, name: Namer): string {
+  const named = name(operand.value);
+  // A name of a zero-page address gives the zero-page form: an absolute operand there keeps its number.
+  if (named !== undefined && (operand.value >= 0x100 || !operand.absolute)) return named;
+  return operand.absolute ? hex4(operand.value) : hex2(operand.value);
+}
+
+/** The memory operand of `instruction` when it is one of the opcodes of the mnemonic. */
+function memory(instruction: Instruction | undefined, mnemonic: keyof typeof MEMORY): Operand | undefined {
+  if (instruction === undefined) return undefined;
+  const index = (MEMORY[mnemonic] as readonly number[]).indexOf(instruction.opcode);
+  return index < 0 ? undefined : { value: instruction.value, absolute: index === 1 };
+}
+
+const same = (a: Operand | undefined, b: Operand | undefined, offset = 0): boolean => a !== undefined && b !== undefined && a.absolute === b.absolute && b.value === a.value + offset;
+const immediate = (instruction: Instruction | undefined, opcode: number) => (instruction?.opcode === opcode ? instruction.value : undefined);
+/** A branch past the next instruction only: its distance is the length of that instruction. */
+const skips = (branch: Instruction | undefined, opcode: number, next: Instruction | undefined) => branch?.opcode === opcode && next !== undefined && branch.value === next.length;
+
+/** Each idiom: how many instructions it takes, and its args when the instructions match. */
+const MATCHERS: Record<string, { count: number; match: (run: Instruction[], name: Namer) => string[] | undefined }> = {
+  inc16: {
+    count: 3,
+    match: ([low, branch, high], name) => {
+      const dst = memory(low, "inc");
+      return same(dst, memory(high, "inc"), 1) && skips(branch, BNE, high) ? [addressArg(dst!, name)] : undefined;
+    },
+  },
+  dec16: {
+    count: 4,
+    match: ([load, branch, high, low], name) => {
+      const dst = memory(load, "lda");
+      return same(dst, memory(low, "dec")) && same(dst, memory(high, "dec"), 1) && skips(branch, BNE, high) ? [addressArg(dst!, name)] : undefined;
+    },
+  },
+  add16_8: {
+    count: 6,
+    match: ([clc, load, add, store, branch, high], name) => {
+      const dst = memory(load, "lda");
+      const value = immediate(add, IMMEDIATE.adc);
+      const ok = clc?.opcode === CLC && value !== undefined && same(dst, memory(store, "sta")) && same(dst, memory(high, "inc"), 1) && skips(branch, BCC, high);
+      return ok ? [addressArg(dst!, name), hex2(value)] : undefined;
+    },
+  },
+  add16: { count: 7, match: (run, name) => wide(run, name, CLC, IMMEDIATE.adc) },
+  sub16: { count: 7, match: (run, name) => wide(run, name, SEC, IMMEDIATE.sbc) },
+  set16: {
+    count: 4,
+    match: ([loadLow, storeLow, loadHigh, storeHigh], name) => {
+      const low = immediate(loadLow, IMMEDIATE.lda);
+      const high = immediate(loadHigh, IMMEDIATE.lda);
+      const dst = memory(storeLow, "sta");
+      if (low === undefined || high === undefined || !same(dst, memory(storeHigh, "sta"), 1)) return undefined;
+      const value = low | (high << 8);
+      return [addressArg(dst!, name), name(value) ?? hex4(value)];
+    },
+  },
+  mov16: {
+    count: 4,
+    match: ([loadLow, storeLow, loadHigh, storeHigh], name) => {
+      const src = memory(loadLow, "lda");
+      const dst = memory(storeLow, "sta");
+      if (!same(src, memory(loadHigh, "lda"), 1) || !same(dst, memory(storeHigh, "sta"), 1)) return undefined;
+      return [addressArg(dst!, name), addressArg(src!, name)];
+    },
+  },
+  wait_line: {
+    count: 3,
+    match: ([load, compare, branch]) => {
+      const line = immediate(load, IMMEDIATE.lda);
+      // BNE back to the CMP: 5 bytes back from the end of the BNE.
+      return line !== undefined && compare?.opcode === CMP_ABSOLUTE && compare.value === 0xd012 && branch?.opcode === BNE && branch.value === 0xfb ? [hex2(line)] : undefined;
+    },
+  },
+};
+
+/** add16 and sub16: the carry, then the low and the high byte, each with an immediate of the 16-bit value. */
+function wide([carry, loadLow, low, storeLow, loadHigh, high, storeHigh]: Instruction[], name: Namer, carryOpcode: number, opcode: number): string[] | undefined {
+  const dst = memory(loadLow, "lda");
+  const lowValue = immediate(low, opcode);
+  const highValue = immediate(high, opcode);
+  const ok =
+    carry?.opcode === carryOpcode && lowValue !== undefined && highValue !== undefined && same(dst, memory(storeLow, "sta")) && same(dst, memory(loadHigh, "lda"), 1) && same(dst, memory(storeHigh, "sta"), 1);
+  return ok ? [addressArg(dst!, name), hex4(lowValue | (highValue << 8))] : undefined;
+}
+
+/** The instruction at `at`, or undefined when a byte of it is outside the range or the image. */
+export function instructionAt(byteAt: ImageByte, at: number, end: number): Instruction | undefined {
+  const opcode = byteAt(at);
+  if (opcode === undefined) return undefined;
+  const length = instructionLength(opcode);
+  if (at + length - 1 > end) return undefined;
+  const bytes = Array.from({ length: length - 1 }, (_, offset) => byteAt(at + 1 + offset));
+  if (bytes.some((byte) => byte === undefined)) return undefined;
+  return { opcode, length, value: length === 1 ? 0 : length === 2 ? bytes[0]! : bytes[0]! | (bytes[1]! << 8) };
+}
+
+/**
+ * Finds the macro candidates in code regions. Each region is read as
+ * instructions from its start; at each instruction the idioms of the
+ * catalogue are tried in order, and a match is a candidate. Candidates do not
+ * overlap: the scan goes on after the end of a match.
+ */
+export function findMacroUses(byteAt: ImageByte, regions: ReadonlyArray<{ start: number; end: number }>, name: Namer): MacroCandidate[] {
+  const candidates: MacroCandidate[] = [];
+  for (const region of [...regions].sort((a, b) => a.start - b.start)) {
+    const run: Array<Instruction & { at: number }> = [];
+    for (let at = region.start; at <= region.end; ) {
+      const instruction = instructionAt(byteAt, at, region.end);
+      if (instruction === undefined) break;
+      run.push({ ...instruction, at });
+      at += instruction.length;
+    }
+    for (let index = 0; index < run.length; ) {
+      const found = CATALOGUE.flatMap((idiom) => {
+        const matcher = MATCHERS[idiom.name]!;
+        const part = run.slice(index, index + matcher.count);
+        const args = part.length === matcher.count ? matcher.match(part, name) : undefined;
+        return args === undefined ? [] : [{ idiom, count: matcher.count, args }];
+      })[0];
+      if (found === undefined) {
+        index++;
+        continue;
+      }
+      const last = run[index + found.count - 1]!;
+      candidates.push({ macro: found.idiom.name, start: run[index]!.at, end: last.at + last.length - 1, args: found.args });
+      index += found.count;
+    }
+  }
+  return candidates;
+}

package/skills/c64-static-analysis/scripts/lib/pitfalls.ts

@@ -0,0 +1,68 @@
+// Platform pitfalls in code regions (M23.7): code that a C64 runs in another
+// way than it reads. A fixed catalogue, reported as candidates only (D51).
+//
+// raster-bit-8: a read of $D011 gives bit 8 of the current raster line in
+// bit 7. Code that writes the value back without clearing bit 7 sets bit 8 of
+// the raster compare: the next raster interrupt then comes at line 256 or
+// later, or never on a PAL machine past line 311 (the Bruce Lee freeze).
+
+import type { ImageByte } from "./coverage.ts";
+import { instructionAt, type Instruction } from "./macros.ts";
+
+export interface Pitfall {
+  kind: "raster-bit-8";
+  /** The instruction that reads $D011. */
+  at: number;
+  /** The instruction that writes the value back to $D011. */
+  store: number;
+}
+
+const D011 = 0xd011;
+/** LDA, LDX and LDY absolute, and the stores of the same register. */
+const LOADS: Record<number, "a" | "x" | "y"> = { 0xad: "a", 0xae: "x", 0xac: "y" };
+const STORES: Record<number, "a" | "x" | "y"> = { 0x8d: "a", 0x8e: "x", 0x8c: "y" };
+/** INC, DEC, ASL, ROL and ROR absolute: they read the register and write it back. LSR shifts a 0 into bit 7. */
+const READ_MODIFY_WRITE = new Set([0xee, 0xce, 0x0e, 0x2e, 0x6e]);
+/** Instructions after which the next one is not the next in the flow: a jump, a return, a call or a branch. */
+const FLOW = new Set([0x4c, 0x6c, 0x20, 0x60, 0x40, 0x00, 0x10, 0x30, 0x50, 0x70, 0x90, 0xb0, 0xd0, 0xf0]);
+/** Instructions that load A, X or Y with a new value, which ends what the load of $D011 gave. */
+const NEW_VALUE: Record<"a" | "x" | "y", Set<number>> = {
+  a: new Set([0xa9, 0xa5, 0xb5, 0xad, 0xbd, 0xb9, 0xa1, 0xb1, 0x8a, 0x98, 0x68]),
+  x: new Set([0xa2, 0xa6, 0xb6, 0xae, 0xbe, 0xaa, 0xba]),
+  y: new Set([0xa0, 0xa4, 0xb4, 0xac, 0xbc, 0xa8]),
+};
+/** The most instructions between the load and the store. */
+const WINDOW = 8;
+
+/** The raster-bit-8 pitfalls in the code regions, in address order. */
+export function findPitfalls(byteAt: ImageByte, regions: ReadonlyArray<{ start: number; end: number }>): Pitfall[] {
+  const found: Pitfall[] = [];
+  for (const region of [...regions].sort((a, b) => a.start - b.start)) {
+    const run: Array<Instruction & { at: number }> = [];
+    for (let at = region.start; at <= region.end; ) {
+      const instruction = instructionAt(byteAt, at, region.end);
+      if (instruction === undefined) break;
+      run.push({ ...instruction, at });
+      at += instruction.length;
+    }
+    run.forEach((instruction, index) => {
+      if (instruction.length !== 3 || instruction.value !== D011) return;
+      if (READ_MODIFY_WRITE.has(instruction.opcode)) {
+        found.push({ kind: "raster-bit-8", at: instruction.at, store: instruction.at });
+        return;
+      }
+      const register = LOADS[instruction.opcode];
+      if (register === undefined) return;
+      for (const next of run.slice(index + 1, index + 1 + WINDOW)) {
+        // AND #imm without bit 7 clears raster bit 8: the code knows about it.
+        if (register === "a" && next.opcode === 0x29 && (next.value & 0x80) === 0) return;
+        if (STORES[next.opcode] === register && next.length === 3 && next.value === D011) {
+          found.push({ kind: "raster-bit-8", at: instruction.at, store: next.at });
+          return;
+        }
+        if (FLOW.has(next.opcode) || NEW_VALUE[register].has(next.opcode)) return;
+      }
+    });
+  }
+  return found;
+}