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

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

@@ -4,14 +4,17 @@
 // 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";
 import { identifiers, operandText, replaceIdentifiers, type OperandExpression } from "#src/knowledge/expression.ts";
 import { ANALYZERS } from "#src/knowledge/import.ts";
 import { isGeneratedFile, type CommentPlacement, type Origin, type RegionType } from "#src/knowledge/schema.ts";
-import { hasZeroPageForm, MNEMONICS, MODE_LENGTH, OPCODES, takesAddress, type Mode } from "./opcodes.ts";
+import type { Area } from "#src/platform.ts";
+import { hasZeroPageForm, MNEMONICS, MODE_LENGTH, OPCODES, takesAddress, USE_KINDS, useKind, type Mode, type UseKind } from "./opcodes.ts";
 
 export interface Range {
   start: number;
@@ -35,10 +38,53 @@ export interface SourceInput {
   referenceTargets: readonly number[];
   /** Joined coverage files (D40): an instruction that no run executed is marked (D49). */
   coverage?: Uint8Array;
-  /** Platform names (D52): the name of an address that knowledge does not name, and the last address of its entry. */
-  platform?: ReadonlyArray<{ address: number; end: number; name: string }>;
+  /** Platform names (D52): the name of an address that knowledge does not name, the last address of its entry, and what it is. */
+  platform?: ReadonlyArray<{ address: number; end: number; name: string; meaning?: string }>;
+  /** The platform area of an address, and the register that an I/O mirror repeats: constants.asm groups and describes its names with them. */
+  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. */
@@ -92,6 +138,10 @@ export interface Layout {
   names: Map<number, string>;
   /** Addresses outside the image that the source names, as constants. */
   constants: number[];
+  /** How the source uses each constant: instructions by kind, and pointer table entries. */
+  uses: Map<number, Map<UseKind, number>>;
+  platform: NonNullable<SourceInput["platform"]>;
+  describe?: SourceInput["describe"];
   inImage: (address: number) => boolean;
   byteAt: (address: number) => number;
   comments: SourceInput["comments"];
@@ -103,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")}`;
@@ -153,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);
@@ -195,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);
@@ -203,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;
     }
@@ -221,13 +284,20 @@ export function layout(input: SourceInput): Layout {
   const symbols = new Map(input.symbols.filter((symbol) => !(isAnalyzer(symbol.origin) && platform.has(symbol.address))).map((symbol) => [symbol.address, symbol.name]));
   /** Addresses outside the image without a name of their own, inside a named platform entry of more bytes: the start of that entry (F-20). */
   const insideEntry = new Map<number, number>();
-  const use = (address: number) => {
+  const uses = new Map<number, Map<UseKind, number>>();
+  const count = (constant: number, kind: UseKind) => {
+    outside.add(constant);
+    const kinds = uses.get(constant) ?? new Map<UseKind, number>();
+    kinds.set(kind, (kinds.get(kind) ?? 0) + 1);
+    uses.set(constant, kinds);
+  };
+  const use = (address: number, kind: UseKind) => {
     if (inImage(address)) wanted.add(address);
-    else if (symbols.has(address) || platform.has(address)) outside.add(address);
+    else if (symbols.has(address) || platform.has(address)) count(address, kind);
     else {
       const entry = input.platform?.find((row) => address > row.address && address <= row.end && !inImage(row.address) && (symbols.has(row.address) || platform.has(row.address)));
       if (entry === undefined) return;
-      outside.add(entry.address);
+      count(entry.address, kind);
       insideEntry.set(address, entry.address);
     }
   };
@@ -236,7 +306,43 @@ 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] : []))));
-  const expressions: Array<{ address: number; text: string }> = [];
+  // 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)) {
     const expression = operandText(operand);
@@ -251,23 +357,41 @@ export function layout(input: SourceInput): Layout {
       operandsAsNumbers.push({ address: operand.address, expression, reason: `No symbol and no platform name is ${missing.join(", ")}.` });
       continue;
     }
-    expressions.push({ address: operand.address, text: expression });
+    // An immediate operand builds the address of a name; any other operand uses the address as the instruction does.
+    expressions.push({ address: operand.address, text: expression, kind: mode === "imm" ? "address" : useKind(item!.opcode) });
   }
-  for (const { text: expression } of expressions) for (const name of identifiers(expression)) use(byName.get(name)!);
+  for (const { text: expression, kind } of expressions) for (const name of identifiers(expression)) use(byName.get(name)!, kind);
   // An instruction with an expression names what the expression names, not its plain target (D65).
   const written = new Set(expressions.map((expression) => expression.address));
   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)!);
+        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);
+      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()]);
@@ -293,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[] = [];
@@ -310,6 +470,9 @@ export function layout(input: SourceInput): Layout {
     pieces,
     names,
     constants: [...outside].sort((a, b) => a - b),
+    uses,
+    platform: input.platform ?? [],
+    ...(input.describe === undefined ? {} : { describe: input.describe }),
     inImage,
     byteAt: input.byteAt,
     comments: input.comments,
@@ -319,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),
   };
 }
 
@@ -539,6 +707,83 @@ function dataLines(item: DataItem, layout: Layout, breaks: Set<number>): Array<{
   return lines;
 }
 
+// --- Constants --------------------------------------------------------------
+
+/** A longer name moves only its own comment, not the columns of the file. */
+const MAX_NAME_COLUMN = 24;
+
+/** What an address outside the image is: the comment of the knowledge, else the platform meaning, else the register that a mirror repeats. */
+function describeConstant(layout: Layout, address: number): string | undefined {
+  const comments = layout.comments.filter((comment) => comment.address === address);
+  // Line comments come before the side comment, as they do in the code.
+  const own = [...comments.filter((comment) => comment.placement === "line"), ...comments.filter((comment) => comment.placement === "side")];
+  if (own.length > 0) return own.map((comment) => comment.text.replace(/\s*\r?\n\s*/g, " ").trim()).join(" ");
+  const entry = layout.platform.find((row) => address >= row.address && address <= row.end);
+  if (entry?.meaning !== undefined) {
+    const platformName = address === entry.address ? entry.name : `${entry.name}+${address - entry.address}`;
+    return platformName === layout.names.get(address) ? entry.meaning : `${platformName}: ${entry.meaning}`;
+  }
+  const mirrorOf = layout.describe?.(address).mirrorOf;
+  if (mirrorOf === undefined) return undefined;
+  const register = layout.platform.find((row) => row.address === mirrorOf);
+  return `Mirror of ${hex4(mirrorOf)}${register === undefined ? "" : ` (${register.name})`}.`;
+}
+
+/** How the source uses a constant, for example "Used: read 4, written 1." */
+function usageText(kinds: ReadonlyMap<UseKind, number> | undefined): string | undefined {
+  const parts = USE_KINDS.filter((kind) => kinds?.has(kind)).map((kind) => `${kind} ${kinds!.get(kind)!}`);
+  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;
+  const rows = layout.constants.map((address) => {
+    const comment = [describeConstant(layout, address), usageText(layout.uses.get(address))].filter((text) => text !== undefined).join(" ");
+    return { address, name: layout.names.get(address)!, value: constantValue(address), comment };
+  });
+  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 = [...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;
+  for (const row of rows) {
+    const next = describe?.(row.address).area;
+    if (next !== undefined && next.start !== area?.start) {
+      area = next;
+      out.push("", `; ${area.name[0]!.toUpperCase()}${area.name.slice(1)} ${hex4(area.start)}-${hex4(area.end)}`);
+      if (area.meaning !== undefined) out.push(`; ${area.meaning}`);
+    }
+    const line = `${row.name.padEnd(nameColumn)} = ${row.value.padEnd(valueColumn)}`;
+    out.push(row.comment === "" ? line.trimEnd() : `${line} ; ${row.comment}`);
+  }
+  return `${out.join("\n")}\n`;
+}
+
 // --- Rendering --------------------------------------------------------------
 
 export interface Rendered {
@@ -554,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}`);
@@ -563,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) {
@@ -572,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[] };
@@ -583,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)!);
         }
@@ -642,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;
@@ -655,13 +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` });
   }
 
-  const constants = ["; Names outside the image.", ...layout.constants.map((address) => `${layout.names.get(address)} = ${constantValue(address)}`)];
-  result.files.push({ name: "constants.asm", text: `${constants.join("\n")}\n` });
-  const main = [...header.map((line) => `; ${line}`), "", "!cpu 6510", '!source "constants.asm"'];
+  result.files.push({ name: "constants.asm", text: constantsText(layout) });
+  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

@@ -11,13 +11,13 @@ Find the static structure of a C64 program. Record the structure in the project
 
 ## Inputs
 
-- The program: a PRG file, relative to the project directory. Or 64 KiB of memory from `$0000`, for example a memory dump.
+- The program: a PRG file, relative to the project folder. Or 64 KiB of memory from `$0000`, for example a memory dump.
 - Entry points: addresses where code starts, for example the SYS address from the c64-basic skill. Routine symbols in the knowledge are entry points too. Ghidra needs at least one. DXA finds the SYS of a BASIC start by itself.
 - Optional: routines to decompile (Ghidra), or a file for the listing (DXA).
 
 ## Tools / execution path
 
-The script reads the current knowledge and runs DXA or Ghidra on this machine. The host runtime is not necessary. The script records the result in `.c64-re-tools/knowledge.db`.
+The script reads the current knowledge and runs DXA or Ghidra on this machine. The host runtime is not necessary. The script records the result in the project knowledge, `.c64-re-tools/knowledge/`.
 
 ```
 node <skill>/scripts/analyze.ts extracted/game.prg --analyzer dxa --listing analysis/game.lst
@@ -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.
 
@@ -53,6 +54,13 @@ More seeds come from evidence:
 
 The analyzers take at most 1024 entry points. Knowledge routines and `--entry` come first, then code regions and tables, then coverage. `coverageSeeds` gives how many entry points the coverage gave and how many the analysis used.
 
+### Project folder
+
+- Paths are relative to the project folder. The project folder is the nearest folder at or above the working directory that holds `.c64-re-tools/`.
+- If the working directory is not in a project and has projects below it, the script refuses and lists them. Then give `--project <folder>` to each script.
+- Keep the results, batches and step files that you save for yourself in `.c64-re-tools/local/` of the project. Git ignores that folder.
+- A shell redirect (`>`) is relative to the working directory, not to the project folder. From the folder above the project, write `<folder>/.c64-re-tools/local/result.json`.
+
 ## Workflow
 
 1. Read the knowledge for the program with the c64-knowledge skill.
@@ -67,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.