@henols/c64-re-tools 2.0.0-rc.12 → 2.0.0-rc.13

package/skills/c64-source/scripts/source.ts

@@ -4,7 +4,9 @@
 // written by its region type. The source assembles to the same bytes: the
 // generator forces operand sizes, and writes an opcode form that ACME
 // encodes differently as bytes (see the probe in generate.ts). An operand
-// expression of the knowledge is written in place of its number (D65).
+// expression of the knowledge is written in place of its number (D65). A
+// patch is written as !if SWITCH { code } else { original } (D72), and a
+// macro use as one +name args line (D73).
 
 import { COVERAGE, formatC64Address } from "#src/c64.ts";
 import { WireFailure } from "#src/host-client/tools.ts";
@@ -42,6 +44,47 @@ export interface SourceInput {
   describe?: (address: number) => { area: Area; mirrorOf?: number };
   /** Operand expressions of the knowledge (D65), by instruction address. */
   operands?: ReadonlyArray<OperandExpression & { address: number }>;
+  /** Patches of the knowledge (D72): code that replaces a range when the build defines the switch. */
+  patches?: ReadonlyArray<{ start: number; end: number; switch: string; code: string; comment?: string }>;
+  /** Macros of the knowledge (D73), written to macros.asm. */
+  macros?: ReadonlyArray<{ name: string; params: readonly string[]; body: string; comment?: string }>;
+  /** Macro uses of the knowledge (D73): the instructions of a range, written as one use of a macro. */
+  macroUses?: ReadonlyArray<{ start: number; end: number; macro: string; args: readonly string[] }>;
+}
+
+/** A macro use that the source writes (D73), with its args in the names of this source. */
+export interface MacroUseBlock {
+  start: number;
+  end: number;
+  macro: string;
+  args: string[];
+}
+
+/** A macro use that the source writes as its instructions, and why. */
+export interface MacroAsInstructions {
+  start: number;
+  end: number;
+  macro: string;
+  reason: string;
+}
+
+/** A patch that the source writes (D72), with the addresses inside it that have a name. */
+export interface PatchBlock {
+  start: number;
+  end: number;
+  switch: string;
+  code: string;
+  comment?: string;
+  /** Named addresses after the start of the range: the source defines them before the patch, so both builds have them. */
+  inner: number[];
+}
+
+/** A patch of the knowledge that the source does not write, and why. */
+export interface PatchNotWritten {
+  start: number;
+  end: number;
+  switch: string;
+  reason: string;
 }
 
 /** An operand expression that the source writes as a number, with its text and why. */
@@ -110,6 +153,14 @@ export interface Layout {
   operands: Map<number, string>;
   /** Operand expressions that cannot be written. */
   operandsAsNumbers: OperandAsNumber[];
+  /** The patches that the source writes, by start (D72). */
+  patches: Map<number, PatchBlock>;
+  patchesNotWritten: PatchNotWritten[];
+  /** The macros, by name (D73). */
+  macros: NonNullable<SourceInput["macros"]>;
+  /** The macro uses that the source can write, by start. */
+  macroUses: Map<number, MacroUseBlock>;
+  macrosAsInstructions: MacroAsInstructions[];
 }
 
 const hex2 = (value: number) => `$${value.toString(16).padStart(2, "0")}`;
@@ -160,6 +211,11 @@ export function layout(input: SourceInput): Layout {
   const modules = [...input.modules].sort((a, b) => a.start - b.start);
   const unusedModules = modules.filter((module) => !inImage(module.start)).map(({ start, file }) => ({ start, file }));
 
+  // A patch starts and ends at an item boundary, so a data run stops there (D72).
+  const patches = [...(input.patches ?? [])].sort((a, b) => a.start - b.start);
+  const macroUses = [...(input.macroUses ?? [])].sort((a, b) => a.start - b.start);
+  const cuts = new Set([...patches, ...macroUses].flatMap((range) => [range.start, range.end + 1]));
+
   const pieces: Piece[] = [];
   for (const segment of input.segments) {
     const starts = modules.filter((module) => module.start > segment.start && module.start <= segment.end).map((module) => module.start);
@@ -202,7 +258,7 @@ export function layout(input: SourceInput): Layout {
       const type: DataItem["type"] = codeRegion ? "undecoded" : (region?.type ?? "unclassified");
       let end = address;
       const same = (at: number) => {
-        if (at > piece.end) return false;
+        if (at > piece.end || cuts.has(at)) return false;
         const next = regionAt(at);
         if (region !== undefined && !codeRegion) return next === region;
         if (codeRegion) return next === region && !input.instructions.has(at);
@@ -210,7 +266,7 @@ export function layout(input: SourceInput): Layout {
       };
       while (same(end + 1)) end++;
       const last = piece.items.at(-1);
-      if (last?.kind === "data" && last.type === type && last.region === region && last.end + 1 === address) last.end = end;
+      if (last?.kind === "data" && last.type === type && last.region === region && last.end + 1 === address && !cuts.has(address)) last.end = end;
       else piece.items.push({ kind: "data", start: address, end, type, ...(region === undefined ? {} : { region }) });
       address = end + 1;
     }
@@ -250,6 +306,42 @@ export function layout(input: SourceInput): Layout {
   for (const row of input.platform ?? []) if (!byName.has(row.name)) byName.set(row.name, row.address);
   for (const symbol of input.symbols) byName.set(symbol.name, symbol.address);
   const instructionAt = new Map(pieces.flatMap((piece) => piece.items.flatMap((item) => (item.kind === "instruction" ? [[item.address, item] as const] : []))));
+  // A macro use is a run of whole instructions of one file, of a macro with one param for each arg, whose args name known names (D73).
+  const macrosByName = new Map((input.macros ?? []).map((macro) => [macro.name, macro]));
+  const macrosAsInstructions: MacroAsInstructions[] = [];
+  const candidates: Array<{ use: (typeof macroUses)[number]; items: InstructionItem[] }> = [];
+  for (const use of macroUses) {
+    const fallBack = (reason: string) => macrosAsInstructions.push({ start: use.start, end: use.end, macro: use.macro, reason });
+    const macro = macrosByName.get(use.macro);
+    if (macro === undefined) {
+      fallBack(`There is no macro ${use.macro}.`);
+      continue;
+    }
+    if (macro.params.length !== use.args.length) {
+      fallBack(`The macro has ${macro.params.length} params, and the use gives ${use.args.length} args.`);
+      continue;
+    }
+    if (patches.some((patch) => patch.start <= use.end && use.start <= patch.end)) {
+      fallBack("The use lies in a patch.");
+      continue;
+    }
+    const piece = pieces.find((row) => use.start >= row.start && use.start <= row.end);
+    const run = piece?.items.filter((item) => (item.kind === "instruction" ? item.address : item.start) >= use.start && (item.kind === "instruction" ? item.address : item.start) <= use.end) ?? [];
+    const last = run.at(-1);
+    const whole = last?.kind === "instruction" && run.every((item) => item.kind === "instruction") && (run[0] as InstructionItem).address === use.start && last.address + last.length - 1 === use.end;
+    if (!whole) {
+      fallBack("The range is not a run of whole instructions of one file.");
+      continue;
+    }
+    const missing = [...new Set(use.args.flatMap((arg) => identifiers(arg)))].filter((name) => !byName.has(name));
+    if (missing.length > 0) {
+      fallBack(`No symbol and no platform name is ${missing.join(", ")}.`);
+      continue;
+    }
+    candidates.push({ use, items: run as InstructionItem[] });
+  }
+  /** The instructions of a written use name nothing: the macro writes them. */
+  const inUse = new Set(candidates.flatMap((candidate) => candidate.items.map((item) => item.address)));
   const expressions: Array<{ address: number; text: string; kind: UseKind }> = [];
   const operandsAsNumbers: OperandAsNumber[] = [];
   for (const operand of [...(input.operands ?? [])].sort((a, b) => a.address - b.address)) {
@@ -274,15 +366,32 @@ export function layout(input: SourceInput): Layout {
   for (const piece of pieces) {
     for (const item of piece.items) {
       if (item.kind === "instruction") {
-        if (takesAddress(OPCODES[item.opcode]!.mode) && !written.has(item.address)) use(operandValue(item.address, item.opcode, input.byteAt)!, useKind(item.opcode));
+        if (takesAddress(OPCODES[item.opcode]!.mode) && !written.has(item.address) && !inUse.has(item.address)) use(operandValue(item.address, item.opcode, input.byteAt)!, useKind(item.opcode));
         continue;
       }
       for (const pointer of pointersOf(item, input.byteAt)) use(pointer, "table");
     }
   }
+  for (const candidate of candidates) for (const arg of candidate.use.args) for (const name of identifiers(arg)) use(byName.get(name)!, "macro argument");
   for (const symbol of input.symbols) want(symbol.address);
   for (const target of input.referenceTargets) want(target);
   if (input.entry !== undefined) want(input.entry);
+  // A use with a label inside it is written as its instructions, which then name their targets: that can put a label inside another use.
+  const accepted = new Set(candidates);
+  for (let changed = true; changed; ) {
+    changed = false;
+    for (const candidate of [...accepted]) {
+      const inside = [...wanted].filter((address) => address > candidate.use.start && address <= candidate.use.end).sort((a, b) => a - b)[0];
+      if (inside === undefined) continue;
+      accepted.delete(candidate);
+      changed = true;
+      macrosAsInstructions.push({ start: candidate.use.start, end: candidate.use.end, macro: candidate.use.macro, reason: `The source has a label at ${hex4(inside)}, inside the use.` });
+      for (const item of candidate.items) {
+        inUse.delete(item.address);
+        if (takesAddress(OPCODES[item.opcode]!.mode) && !written.has(item.address)) use(operandValue(item.address, item.opcode, input.byteAt)!, useKind(item.opcode));
+      }
+    }
+  }
 
   const names = new Map<number, string>();
   const taken = new Set([...knowledgeNames, ...platform.values()]);
@@ -308,8 +417,44 @@ export function layout(input: SourceInput): Layout {
     names.set(address, name);
     generatedLabels++;
   }
+  // A patch is written when its range is whole items of one file and its switch is no name of the source (D72).
+  const blocks = new Map<number, PatchBlock>();
+  const patchesNotWritten: PatchNotWritten[] = [];
+  const sourceNames = new Set([...names.values(), ...taken]);
+  for (const patch of patches) {
+    const refuse = (reason: string) => patchesNotWritten.push({ start: patch.start, end: patch.end, switch: patch.switch, reason });
+    const piece = pieces.find((row) => patch.start >= row.start && patch.start <= row.end);
+    if (piece === undefined) {
+      refuse("The range is not in the image.");
+      continue;
+    }
+    if (patch.end > piece.end) {
+      refuse(`The range runs past the end of the file ${piece.file} at ${hex4(piece.end)}: a patch is in one file.`);
+      continue;
+    }
+    const starts = new Set(piece.items.map((item) => (item.kind === "instruction" ? item.address : item.start)));
+    const ends = new Set(piece.items.map((item) => (item.kind === "instruction" ? item.address + item.length - 1 : item.end)));
+    if (!starts.has(patch.start) || !ends.has(patch.end)) {
+      const cut = piece.items.find((item) => item.kind === "instruction" && ((patch.start > item.address && patch.start < item.address + item.length) || (patch.end >= item.address && patch.end < item.address + item.length - 1)));
+      refuse(cut === undefined ? "The range does not start and end at an item of the source." : `The range cuts the instruction at ${hex4((cut as InstructionItem).address)}.`);
+      continue;
+    }
+    if (sourceNames.has(patch.switch)) {
+      refuse(`The switch name ${patch.switch} is also a name of the source.`);
+      continue;
+    }
+    const inner = [...names.keys()].filter((address) => address > patch.start && address <= patch.end).sort((a, b) => a - b);
+    blocks.set(patch.start, { start: patch.start, end: patch.end, switch: patch.switch, code: patch.code, ...(patch.comment === undefined ? {} : { comment: patch.comment }), inner });
+  }
   // The high byte of a vector is NMINV+1. A zero-page entry keeps zero-page instructions: its constant has two digits.
   for (const [address, start] of insideEntry) names.set(address, `${names.get(start)!}+${address - start}`);
+  /** An expression with the names of this source: a name with an offset in brackets, so an operator after it keeps its meaning. */
+  const sourceText = (text: string) => replaceIdentifiers(text, (name) => {
+    const label = names.get(byName.get(name)!)!;
+    return label.includes("+") ? `(${label})` : label;
+  });
+  const usesWritten = new Map<number, MacroUseBlock>();
+  for (const { use: row } of [...accepted].sort((a, b) => a.use.start - b.use.start)) usesWritten.set(row.start, { start: row.start, end: row.end, macro: row.macro, args: row.args.map(sourceText) });
   const operands = new Map<number, string>();
   for (const { address, text } of expressions) {
     const unnamed: string[] = [];
@@ -337,6 +482,11 @@ export function layout(input: SourceInput): Layout {
     unusedModules,
     operands,
     operandsAsNumbers: operandsAsNumbers.sort((a, b) => a.address - b.address),
+    patches: blocks,
+    patchesNotWritten,
+    macros: [...(input.macros ?? [])].sort((a, b) => (a.name < b.name ? -1 : 1)),
+    macroUses: usesWritten,
+    macrosAsInstructions: macrosAsInstructions.sort((a, b) => a.start - b.start),
   };
 }
 
@@ -585,6 +735,25 @@ function usageText(kinds: ReadonlyMap<UseKind, number> | undefined): string | un
   return parts.length === 0 ? undefined : `Used: ${parts.join(", ")}.`;
 }
 
+/** The switches of the patches (D72), each 0 unless the build defines it, with the ranges of its patches. */
+export function switchesOf(layout: Pick<Layout, "patches">): Map<string, PatchBlock[]> {
+  const switches = new Map<string, PatchBlock[]>();
+  for (const patch of [...layout.patches.values()].sort((a, b) => a.start - b.start)) switches.set(patch.switch, [...(switches.get(patch.switch) ?? []), patch]);
+  return new Map([...switches].sort(([a], [b]) => (a < b ? -1 : 1)));
+}
+
+function switchLines(layout: Layout): string[] {
+  const switches = switchesOf(layout);
+  if (switches.size === 0) return [];
+  const width = Math.max(...[...switches.keys()].map((name) => name.length));
+  const lines = ["; Switches: each is 0 unless the build defines it. Assemble with -DNAME=1", "; (c64-assembler --define NAME=1) to put in the patches of NAME."];
+  for (const [name, patches] of switches) {
+    const ranges = patches.map((patch) => `${hex4(patch.start)}-${hex4(patch.end)}`).join(", ");
+    lines.push(`!ifndef ${name} { ${name} = 0 }${" ".repeat(width - name.length)} ; ${patches.length} patch${patches.length === 1 ? "" : "es"}: ${ranges}`);
+  }
+  return [...lines, ""];
+}
+
 /** constants.asm: the names outside the image by platform area, each with what it is and how the source uses it. */
 function constantsText(layout: Layout): string {
   const { describe } = layout;
@@ -594,10 +763,11 @@ function constantsText(layout: Layout): string {
   });
   const nameColumn = Math.min(MAX_NAME_COLUMN, Math.max(0, ...rows.map((row) => row.name.length)));
   const valueColumn = Math.max(0, ...rows.map((row) => row.value.length));
-  const out = [
+  const out = [...switchLines(layout)];
+  out.push(
     describe === undefined ? "; Names of addresses outside the image." : "; Names of addresses outside the image, by memory area.",
     '; "Used" counts the instructions and table entries of this source that use the name.',
-  ];
+  );
   // Without platform areas the names form one group.
   if (describe === undefined && rows.length > 0) out.push("");
   let area: Area | undefined;
@@ -629,6 +799,45 @@ export interface Rendered {
   expressions: Array<{ address: number; length: number; file: string; line: number }>;
   /** Operand expressions written as numbers, in address order (D65). */
   operandsAsNumbers: OperandAsNumber[];
+  /** The patches written, in address order (D72). */
+  patches: number;
+  /** Each macro use written: its file and line (1 is the first line of the text) (D73). */
+  uses: Array<{ start: number; end: number; macro: string; file: string; line: number }>;
+  /** The macro uses written as instructions, in address order, with the reason. */
+  macrosAsInstructions: MacroAsInstructions[];
+  /** The lines of each macro in macros.asm, from its !macro line to its closing brace. */
+  macroLines: Map<string, { first: number; last: number }>;
+}
+
+/** macros.asm (D73): each macro with its comment, as ACME reads it; a param is .name in the body. */
+function macrosText(layout: Layout): { text: string; lines: Map<string, { first: number; last: number }> } {
+  const out = ["; Macros of the knowledge. The source writes a use as +name args."];
+  const lines = new Map<string, { first: number; last: number }>();
+  for (const macro of layout.macros) {
+    out.push("");
+    if (macro.comment !== undefined) out.push(...macro.comment.split(/\r?\n/).map((line) => `; ${line}`.trimEnd()));
+    const first = out.length + 1;
+    out.push(`!macro ${macro.name}${macro.params.map((param, index) => `${index === 0 ? " " : ", "}.${param}`).join("")} {`, ...macro.body.split(/\r?\n/), "}");
+    lines.set(macro.name, { first, last: out.length });
+  }
+  return { text: `${out.join("\n")}\n`, lines };
+}
+
+/** The lines that open a patch (D72): its zone, the switch, the code, and the guard that stops a patch longer than its range. */
+function patchOpening(patch: PatchBlock): string[] {
+  const bytes = patch.end - patch.start + 1;
+  const range = `${hex4(patch.start)}-${hex4(patch.end)}`;
+  const comment = patch.comment === undefined ? [] : patch.comment.split(/\r?\n/).map((line) => `${INDENT}; ${line}`.trimEnd());
+  return [
+    `!zone patch_${patch.switch}_${patch.start.toString(16).padStart(4, "0")} {`,
+    ".patch_start",
+    `!if ${patch.switch} {`,
+    `${INDENT}; ${patch.switch} on: ${bytes} byte${bytes === 1 ? "" : "s"} at ${range}, NOP after the code`,
+    ...comment,
+    ...(patch.code === "" ? [] : patch.code.split(/\r?\n/)),
+    `${INDENT}!if * - .patch_start > ${bytes} { !error "The patch ${patch.switch} at ${hex4(patch.start)} has ", * - .patch_start, " bytes; the range has ${bytes}." } else { !fill ${bytes} - (* - .patch_start), $ea }`,
+    "} else {",
+  ];
 }
 
 const withSide = (text: string, side: string | undefined) => (side === undefined ? text : `${text.padEnd(SIDE_COLUMN - 1)} ; ${side}`);
@@ -638,7 +847,7 @@ const withSide = (text: string, side: string | undefined) => (side === undefined
  * holds the opcode form keys that the probe refused; `numbers` the operand
  * expressions that ACME did not assemble to the image, with the reason.
  */
-export function render(layout: Layout, asBytes: ReadonlySet<string>, header: string[], numbers: ReadonlyMap<number, string> = new Map()): Rendered {
+export function render(layout: Layout, asBytes: ReadonlySet<string>, header: string[], numbers: ReadonlyMap<number, string> = new Map(), asInstructions: ReadonlyMap<number, string> = new Map()): Rendered {
   const lineComments = new Map<number, string[]>();
   const sideComments = new Map<number, string>();
   for (const comment of layout.comments) {
@@ -647,7 +856,24 @@ export function render(layout: Layout, asBytes: ReadonlySet<string>, header: str
     else sideComments.set(comment.address, comment.text.replace(/\s*\r?\n\s*/g, " "));
   }
   const breaks = new Set<number>([...layout.names.keys(), ...lineComments.keys(), ...sideComments.keys()]);
-  const result: Rendered = { files: [], instructions: 0, dataBytes: 0, undecodedBytes: 0, asBytes: [], expressions: [], operandsAsNumbers: [...layout.operandsAsNumbers] };
+  const result: Rendered = {
+    files: [],
+    instructions: 0,
+    dataBytes: 0,
+    undecodedBytes: 0,
+    asBytes: [],
+    expressions: [],
+    operandsAsNumbers: [...layout.operandsAsNumbers],
+    patches: 0,
+    uses: [],
+    macrosAsInstructions: [...layout.macrosAsInstructions],
+    macroLines: new Map(),
+  };
+  for (const [start, reason] of asInstructions) {
+    const use = layout.macroUses.get(start);
+    if (use !== undefined) result.macrosAsInstructions.push({ start, end: use.end, macro: use.macro, reason });
+  }
+  result.macrosAsInstructions.sort((a, b) => a.start - b.start);
   const unwritten = new Map(layout.operandsAsNumbers.map((row) => [row.address, row.expression]));
   const { coverage } = layout;
   const notExecuted = { instructions: 0, ranges: [] as Range[] };
@@ -658,34 +884,79 @@ export function render(layout: Layout, asBytes: ReadonlySet<string>, header: str
     let running = false;
     /** The line of the mark of the open range of instructions that did not execute. */
     let markLine = 0;
+    /** The open patch: its labels are defined before it, so the original code writes none (D72). */
+    let patch: PatchBlock | undefined;
+    /** The last address of the macro use just written: its instructions are in the use line (D73). */
+    let useEnd = -1;
+    /** Marks the start of a range of instructions that no run executed, or makes the open range longer. */
+    const mark = (address: number, last: number, count: number) => {
+      const executed = coverage === undefined || (coverage[address]! & COVERAGE.ramExecute) !== 0;
+      if (!executed) {
+        if (running) notExecuted.ranges.at(-1)!.end = last;
+        else {
+          notExecuted.ranges.push({ start: address, end: last });
+          markLine = out.length;
+          out.push("");
+        }
+        // The mark gives the range, so a reader finds it in the full list (D49).
+        const range = notExecuted.ranges.at(-1)!;
+        out[markLine] = `; not executed ${hex4(range.start)}-${hex4(range.end)}`;
+        notExecuted.instructions += count;
+      }
+      running = !executed;
+    };
     const head = (address: number) => {
+      if (patch?.start === address) return;
       for (const text of lineComments.get(address) ?? []) out.push(`; ${text}`.trimEnd());
       const label = layout.names.get(address);
-      if (label !== undefined) out.push(label);
+      if (label !== undefined && patch === undefined) out.push(label);
     };
     for (const item of piece.items) {
+      const itemStart = item.kind === "instruction" ? item.address : item.start;
+      const opened = layout.patches.get(itemStart);
+      if (opened !== undefined) {
+        head(itemStart);
+        for (const address of opened.inner) out.push(`${layout.names.get(address)!} = * + ${address - opened.start}`);
+        out.push(...patchOpening(opened));
+        patch = opened;
+        result.patches++;
+      }
+      const close = () => {
+        const itemEnd = item.kind === "instruction" ? item.address + item.length - 1 : item.end;
+        if (patch === undefined || itemEnd !== patch.end) return;
+        out.push("}", "}");
+        patch = undefined;
+      };
+      if (item.kind === "instruction" && item.address <= useEnd) {
+        result.instructions++;
+        continue;
+      }
+      const macroUse = item.kind === "instruction" && !asInstructions.has(item.address) ? layout.macroUses.get(item.address) : undefined;
+      if (macroUse !== undefined) {
+        head(macroUse.start);
+        const count = piece.items.filter((other) => other.kind === "instruction" && other.address >= macroUse.start && other.address <= macroUse.end).length;
+        mark(macroUse.start, macroUse.end, count);
+        // The comments inside the use go to its side comment, as for the bytes of an instruction.
+        const sides: string[] = [];
+        for (let address = macroUse.start; address <= macroUse.end; address++) {
+          if (address !== macroUse.start) for (const text of lineComments.get(address) ?? []) sides.push(text);
+          if (sideComments.has(address)) sides.push(sideComments.get(address)!);
+        }
+        out.push(withSide(`${INDENT}+${macroUse.macro}${macroUse.args.length === 0 ? "" : ` ${macroUse.args.join(", ")}`}`, sides.length === 0 ? undefined : sides.join(" ")));
+        result.uses.push({ start: macroUse.start, end: macroUse.end, macro: macroUse.macro, file: piece.file, line: out.length });
+        result.instructions++;
+        useEnd = macroUse.end;
+        continue;
+      }
       if (item.kind === "instruction") {
         head(item.address);
-        const executed = coverage === undefined || (coverage[item.address]! & COVERAGE.ramExecute) !== 0;
-        if (!executed) {
-          if (running) notExecuted.ranges.at(-1)!.end = item.address + item.length - 1;
-          else {
-            notExecuted.ranges.push({ start: item.address, end: item.address + item.length - 1 });
-            markLine = out.length;
-            out.push("");
-          }
-          // The mark gives the range, so a reader finds it in the full list (D49).
-          const range = notExecuted.ranges.at(-1)!;
-          out[markLine] = `; not executed ${hex4(range.start)}-${hex4(range.end)}`;
-          notExecuted.instructions++;
-        }
-        running = !executed;
+        mark(item.address, item.address + item.length - 1, 1);
         const sides: string[] = [];
         if (sideComments.has(item.address)) sides.push(sideComments.get(item.address)!);
         for (let offset = 1; offset < item.length; offset++) {
           const inside = item.address + offset;
           const label = layout.names.get(inside);
-          if (label !== undefined) out.push(`${label} = * + ${offset}`);
+          if (label !== undefined && patch === undefined) out.push(`${label} = * + ${offset}`);
           for (const text of lineComments.get(inside) ?? []) sides.push(text);
           if (sideComments.has(inside)) sides.push(sideComments.get(inside)!);
         }
@@ -717,6 +988,7 @@ export function render(layout: Layout, asBytes: ReadonlySet<string>, header: str
           out.push(withSide(`${INDENT}${instructionText(item.opcode, form.suffix, expression)}`, sides.length === 0 ? undefined : sides.join(" ")));
         }
         result.instructions++;
+        close();
         continue;
       }
       running = false;
@@ -730,12 +1002,18 @@ export function render(layout: Layout, asBytes: ReadonlySet<string>, header: str
       const bytes = item.end - item.start + 1;
       if (item.type === "undecoded") result.undecodedBytes += bytes;
       else result.dataBytes += bytes;
+      close();
     }
     result.files.push({ name: piece.file, text: `${out.join("\n")}\n` });
   }
 
   result.files.push({ name: "constants.asm", text: constantsText(layout) });
-  const main = [...header.map((line) => `; ${line}`), "", "!cpu 6510", '!source "constants.asm"'];
+  if (layout.macros.length > 0) {
+    const macros = macrosText(layout);
+    result.files.push({ name: "macros.asm", text: macros.text });
+    result.macroLines = macros.lines;
+  }
+  const main = [...header.map((line) => `; ${line}`), "", "!cpu 6510", '!source "constants.asm"', ...(layout.macros.length > 0 ? ['!source "macros.asm"'] : [])];
   for (const piece of layout.pieces) {
     if (piece.segmentStart) main.push("", `* = ${hex4(piece.start)}`);
     main.push(`!source "${piece.file}"`);

package/skills/c64-static-analysis/SKILL.md

@@ -35,6 +35,7 @@ node <skill>/scripts/analyze.ts extracted/game.prg --entry '$080d' --decompile '
 | `--instructions analysis/instructions.json` | Ghidra only: write every instruction to this project file as JSON. Each has `address`, `bytes`, `mnemonic`, `mode` and `operand` in 6502 syntax. A branch, jump or call also has its `target`. With `--coverage`, `executed` tells if it ran. |
 | `--space drive8` | The knowledge space of the image: `drive8` for code from the 1541 drive, or `bank0` to `bank255` for a cartridge bank. The default is `c64`. The seeds come from that space, and the findings go into it. |
 | `--coverage coverage/attract.bin` | A coverage file of 64 KiB from `c64_memmap` (action `read` with `out`). Use it again for more runs. The executed code becomes entry points. |
+| `--macro-batch .c64-re-tools/local/macros.json` | Write the macro candidates to this project file as a batch for `apply` of the c64-knowledge skill. |
 
 The script prints one JSON object. Addresses are `$` and four hex digits.
 
@@ -74,6 +75,7 @@ The analyzers take at most 1024 entry points. Knowledge routines and `--entry` c
    - `conflicts` lists the places where the analyzer and the current knowledge disagree.
    - `idioms` tells what the script found by pattern: RTS dispatch tables (`rtsTables`), JMP tables (`jumpTables`) and BIT skips (`bitSkips`). The script writes them as knowledge with the origin `heuristic`, and seeds their targets into the same analysis. `candidates` gives DOP padding (`dop`) and opcodes that the program wrote and executed (`selfModified`). For `selfModified`, the write and the execution must be in one coverage file. A coverage file does not record the order. Thus a candidate can also be code that ran first, and that the program then wrote over. To prevent this, save one coverage file for each part of the program, for example the intro and the game. Clear the memory map between the parts. Each list has a `count`. The script does not write the candidates. Look at them and decide.
    - `candidates.pointers` gives code that makes an address from immediates. A `vector` or a `zero-page pointer` candidate stores a low byte (`low`) and a high byte (`high`) to a vector or to a zero-page pair that `(zp),y` uses. Its `target` is in the image or has a platform name. A `sprite pointer` candidate stores an immediate (`at`) to a sprite pointer of the screen at $0400 in VIC bank 0. Its `target` (the value × 64) is in a `sprite` region. For each candidate that you confirm, write operand expressions with `operand` of the c64-knowledge skill, for example `operand '<low>' --lo <target name>` and `operand '<high>' --hi <target name>`. Then a rebuild can move the target.
+   - `candidates.macros` gives runs of instructions that a macro writes as one line, for example `+inc16 ptr`. The script knows these 6502 idioms: `inc16`, `dec16`, `add16_8`, `add16`, `sub16`, `set16`, `mov16` and `wait_line`. It reads the code regions after the analysis. An arg has the name of a `user` or `llm` symbol or a platform name. Each candidate has `macro`, `start`, `end`, `args` and `text`. `known` counts the uses that the knowledge has. `leftOut` counts the candidates with a label inside, or with a patch or a use over them. The c64-source skill writes such a candidate as instructions. With `--macro-batch`, `batch` gives the file, the count of writes and the `apply` command. The batch holds the macros that the knowledge does not have, and the uses. When the knowledge has a macro with the same name and another body, `otherMacros` tells that the batch does not have its uses. The script does not write the candidates. Apply the batch, then generate the source again.
    - With `--coverage`, a code finding replaces the DXA or Ghidra data where a run executed an instruction start. `coverageConflicts` lists the analyzer data regions where the coverage still shows executed code. Classify them as code with the c64-knowledge skill, or as `dual-use` when the bytes are also data.
 6. Give each important routine a name with the c64-knowledge skill. Then run the analysis again. The analyzers use the new names.
 

package/skills/c64-static-analysis/scripts/analyze.ts

@@ -18,15 +18,16 @@ import { localToolContext } from "#src/native/local.ts";
 import { GHIDRA_LIMITS } from "#src/native/types.ts";
 import { KnowledgeError, openForRead, withWrite } from "#src/knowledge/database.ts";
 import { importFindings, runProvenance, type Analyzer, type ImportConflict, type ImportContext, type ImportResult, type NormalizedFindings } from "#src/knowledge/import.ts";
-import { currentRevision, listRegions } from "#src/knowledge/read.ts";
+import { currentRevision, listMacros, listMacroUses, listPatches, listReferences, listRegions, listSymbols } from "#src/knowledge/read.ts";
 import { DEFAULT_SPACE, SPACE } from "#src/knowledge/schema.ts";
 import { platformNames } from "#src/platform.ts";
 import { resolveProjectPath } from "#src/project.ts";
 import { runScript, UsageError } from "#src/script.ts";
-import { codeEntries, coverageConflicts, coverageEntries, imageReader, readCoverageMaps } from "./coverage.ts";
+import { codeEntries, coverageConflicts, coverageEntries, imageReader, readCoverageMaps, type ImageByte } from "./coverage.ts";
 import { dxaFindings, ghidraFindings, seedsFromKnowledge } from "./findings.ts";
 import { findIdioms } from "./idioms.ts";
 import { instructionList } from "./instructions.ts";
+import { CATALOGUE, findMacroUses, type MacroCandidate } from "./macros.ts";
 import { findPointers, type PointerCandidate } from "./pointers.ts";
 
 const USAGE = `analyze.ts <image> [options]
@@ -46,6 +47,8 @@ const USAGE = `analyze.ts <image> [options]
                           all labels and functions
   --space <space>         the knowledge space of the image: c64 (the default), drive8
                           for 1541 drive code, or bank0 to bank255 for a cartridge bank
+  --macro-batch <file>    write the macro candidates as an apply batch of c64-knowledge
+                          (the macros and their uses) to this project file
 
 Routine symbols in knowledge are entry points too. Ghidra needs at least one
 entry point; dxa finds the SYS of a BASIC start by itself. The result is one
@@ -67,6 +70,73 @@ function showPointer(candidate: PointerCandidate) {
   return { kind: candidate.kind, to: hex(candidate.to), target: hex(candidate.target), low: hex(candidate.low), high: hex(candidate.high) };
 }
 
+/** A macro candidate with $ addresses and its source line (D73). */
+function showMacro(candidate: MacroCandidate) {
+  return { macro: candidate.macro, start: formatC64Address(candidate.start), end: formatC64Address(candidate.end), args: candidate.args, text: `+${candidate.macro} ${candidate.args.join(", ")}` };
+}
+
+/**
+ * The macro candidates (D73) in the current code regions of every origin,
+ * with the names of the knowledge in their args. A candidate is left out when
+ * a name or a reference target is inside it, or a patch or a use overlaps it:
+ * c64-source would write its instructions. The same use in the knowledge is
+ * known. With `batchPath`, the candidates go to an apply batch with the
+ * macros they need; a macro of the catalogue that the knowledge has with
+ * another body leaves its candidates out of the batch.
+ */
+function macroCandidates(space: string, image: string, byteAt: ImageByte, batchPath: string | undefined) {
+  const db = openForRead();
+  try {
+    const platform = space === DEFAULT_SPACE ? new Map(platformNames().map((entry) => [entry.address, entry.name])) : new Map<number, string>();
+    const semantic = new Map(listSymbols(db, undefined, undefined, ["user", "llm"], space).map((symbol) => [symbol.address, symbol.name]));
+    const code = listRegions(db, undefined, "code", undefined, space);
+    const found = findMacroUses(byteAt, code, (address) => semantic.get(address) ?? platform.get(address));
+    const named = new Set([...listSymbols(db, undefined, undefined, undefined, space).map((symbol) => symbol.address), ...listReferences(db, undefined, undefined, undefined, space).map((reference) => reference.to)]);
+    const patches = listPatches(db, undefined, undefined, undefined, space);
+    const uses = listMacroUses(db, undefined, undefined, undefined, space);
+    const overlaps = (a: { start: number; end: number }, b: { start: number; end: number }) => a.start <= b.end && b.start <= a.end;
+    const candidates: MacroCandidate[] = [];
+    let known = 0;
+    let leftOut = 0;
+    for (const candidate of found) {
+      const same = uses.find((use) => use.start === candidate.start && use.end === candidate.end && use.macro === candidate.macro && use.args.join(",") === candidate.args.join(","));
+      if (same !== undefined) known++;
+      else if ([...named].some((address) => address > candidate.start && address <= candidate.end) || patches.some((patch) => overlaps(patch, candidate)) || uses.some((use) => overlaps(use, candidate))) leftOut++;
+      else candidates.push(candidate);
+    }
+    if (batchPath === undefined) return { candidates, known, leftOut };
+    // A macro of the catalogue goes into the batch unless the knowledge has it; with another body, its uses stay out.
+    const macros = new Map(listMacros(db, undefined, space).map((macro) => [macro.name, macro]));
+    const batch: Array<Record<string, unknown>> = [];
+    const batched: MacroCandidate[] = [];
+    const other = new Set<string>();
+    for (const idiom of CATALOGUE.filter((item) => candidates.some((candidate) => candidate.macro === item.name))) {
+      const existing = macros.get(idiom.name);
+      if (existing === undefined) batch.push({ op: "macro", name: idiom.name, params: idiom.params, body: idiom.body, comment: idiom.comment, ...(space === DEFAULT_SPACE ? {} : { space }) });
+      else if (existing.params.join(",") !== idiom.params.join(",") || existing.body !== idiom.body) other.add(idiom.name);
+    }
+    for (const candidate of candidates) {
+      if (other.has(candidate.macro)) continue;
+      batched.push(candidate);
+      batch.push({ op: "use", start: formatC64Address(candidate.start), end: formatC64Address(candidate.end), macro: candidate.macro, args: candidate.args, ...(space === DEFAULT_SPACE ? {} : { space }) });
+    }
+    if (batch.length > 0) writeProjectFile(batchPath, Buffer.from(`${JSON.stringify(batch, null, 1)}\n`), { what: "--macro-batch" });
+    return {
+      candidates,
+      known,
+      leftOut,
+      batch: {
+        out: batchPath,
+        writes: batch.length,
+        ...(other.size === 0 ? {} : { otherMacros: [...other].map((name) => `The knowledge has another macro ${name}: its candidates are not in the batch.`) }),
+        ...(batch.length === 0 ? {} : { apply: `knowledge.ts apply ${batchPath} --image ${image} --reason "macro uses of 6502 idioms"` }),
+      },
+    };
+  } finally {
+    db?.close();
+  }
+}
+
 /** A decompiler that did not start gets the remedy: Ghidra ships no native decompiler for macOS. */
 function withRemedy(reason: string): string {
   return reason.startsWith("the Ghidra decompiler did not start")
@@ -139,6 +209,7 @@ async function run(argv: string[]): Promise<unknown> {
       coverage: { type: "string", multiple: true },
       instructions: { type: "string" },
       space: { type: "string" },
+      "macro-batch": { type: "string" },
       help: { type: "boolean" },
     },
   });
@@ -165,6 +236,14 @@ async function run(argv: string[]): Promise<unknown> {
     }
   }
 
+  if (values["macro-batch"] !== undefined) {
+    try {
+      resolveProjectPath(values["macro-batch"]);
+    } catch {
+      throw new UsageError(`--macro-batch must be a path relative to the project folder that stays inside it, not ${values["macro-batch"]}`);
+    }
+  }
+
   const space = values.space ?? DEFAULT_SPACE;
   if (!SPACE.test(space)) throw new UsageError("--space must be c64, drive8, or bank0 to bank255");
   // A coverage map is of the C64 CPU: VICE keeps none for the drive (D53).
@@ -206,6 +285,8 @@ async function run(argv: string[]): Promise<unknown> {
   /** Imports the idioms as their own revision, after the analyzer's, and gives their part of the result. */
   const idiomsResult = () => {
     const imported = withWrite((db) => importFindings(db, { ...idioms.findings, space }, { description: `Idioms in ${image}` }));
+    // The macro candidates read the code regions after both imports (D73).
+    const macros = macroCandidates(space, image, byteAt, values["macro-batch"]);
     return {
       idioms: {
         ...idioms.counts,
@@ -217,6 +298,12 @@ async function run(argv: string[]): Promise<unknown> {
           dop: listed(idioms.candidates.dop, max, formatC64Address, "a larger --max-listed"),
           selfModified: listed(idioms.candidates.selfModified, max, formatC64Address, "a larger --max-listed"),
           pointers: listed(pointers, max, showPointer, "a larger --max-listed"),
+          macros: {
+            ...listed(macros.candidates, max, showMacro, "a larger --max-listed, or --macro-batch <file>"),
+            ...(macros.known === 0 ? {} : { known: macros.known }),
+            ...(macros.leftOut === 0 ? {} : { leftOut: macros.leftOut }),
+            ...(macros.batch === undefined ? {} : { batch: macros.batch }),
+          },
         },
       },
     };