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

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

@@ -2,8 +2,10 @@
 // knowledge and Ghidra's instructions, which it runs itself, and checks with
 // ACME that the source assembles to the image byte by byte. With --loader it
 // also writes a loader that recreates the entry state, simulates it, and
-// checks it in the emulator. Exit status: 0 when every check passes, 1 when
-// one fails, 2 for a bad call.
+// checks it in the emulator. Each switch of the patches (D72) is built on
+// alone and checked. A macro use (D73) that does not give the bytes of the
+// image is written as its instructions. Exit status: 0 when every check
+// passes, 1 when one fails, 2 for a bad call.
 
 import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import { join, posix } from "node:path";
@@ -16,24 +18,26 @@ import { ImageError, readImage as readSharedImage, type Image } from "#src/host-
 import { MAX_MEMORY_READ, WireFailure } from "#src/host-client/tools.ts";
 import { readProjectFile, writeProjectFile } from "#src/host-client/transfer.ts";
 import { ViceSessionClient } from "#src/host-client/vice-session.ts";
+import { conflicts } from "#src/knowledge/conflicts.ts";
 import { KnowledgeError, openForRead } from "#src/knowledge/database.ts";
-import { currentRevision, listComments, listModules, listOperands, listReferences, listRegions, listSymbols } from "#src/knowledge/read.ts";
+import { identifiers } from "#src/knowledge/expression.ts";
+import { currentRevision, listComments, listMacros, listMacroUses, listModules, listOperands, listPatches, listReferences, listRegions, listSymbols } from "#src/knowledge/read.ts";
 import { CODE_REGION_TYPES, DEFAULT_SPACE, SPACE, type Space } from "#src/knowledge/schema.ts";
 import { assemble } from "#src/native/acme.ts";
 import { analyze } from "#src/native/ghidra/analyze.ts";
 import { localToolContext } from "#src/native/local.ts";
 import { GHIDRA_LIMITS, type AssembledSymbol, type Diagnostic } from "#src/native/types.ts";
-import { platformNames } from "#src/platform.ts";
+import { describeAddress, platformNames } from "#src/platform.ts";
 import { resolveProjectPath } from "#src/project.ts";
 import { runScript, UsageError } from "#src/script.ts";
 import { LOADER_JUMP, planLoader, rasterLine, readEntryState, simulate, VIC_DISPLAY_REGISTERS, type EntryState, type LoaderPlan } from "./loader.ts";
 import { OPCODES } from "./opcodes.ts";
-import { entriesInData, entryOutsideImage, instructionText, layout, literalOperand, probeForms, render, type Layout, type Range, type Rendered } from "./source.ts";
+import { entriesInData, entryOutsideImage, instructionText, layout, literalOperand, probeForms, render, switchesOf, type Layout, type PatchBlock, type Range, type Rendered } from "./source.ts";
 
 const USAGE = `generate.ts <image> --out <dir> [options]
 
   <image>            an image.json of the c64-unpacker skill, or a PRG, relative to
-                     the project directory
+                     the project folder
   --out <dir>        the directory for the source files, relative to the project
   --entry <address>  an entry point for Ghidra, for example '$080d' (repeatable)
   --coverage <file>  a coverage map of 64 KiB from c64_memmap (repeatable): code
@@ -49,8 +53,8 @@ const USAGE = `generate.ts <image> --out <dir> [options]
 The result is one JSON object. Addresses are $ and four hex digits.`;
 
 const MAX_LISTED = 20;
-/** Rounds of assembly that move operand expressions to numbers (D65). */
-const OPERAND_ROUNDS = 3;
+/** Rounds of assembly that move operand expressions to numbers (D65) and macro uses to instructions (D73). */
+const ROUNDS = 6;
 const PROBE_BASE = 0x1000;
 const PROBE_SLOT = 4;
 /** The copies of a full 64 KiB take about 140 frames. */
@@ -69,6 +73,9 @@ function readImage(path: string): Image {
 function readKnowledge(space: Space) {
   const db = openForRead();
   try {
+    // With conflicts from a git merge, the source would depend on which of two rows comes first (D69).
+    const found = conflicts(db).length;
+    if (found > 0) throw new KnowledgeError("conflict", `The knowledge has ${found} conflict${found === 1 ? "" : "s"} from a git merge. Nothing was generated. Run c64-knowledge's knowledge.ts merge, then generate again.`);
     return {
       revision: currentRevision(db),
       symbols: listSymbols(db, undefined, undefined, undefined, space),
@@ -77,6 +84,9 @@ function readKnowledge(space: Space) {
       modules: listModules(db, undefined, undefined, space),
       references: listReferences(db, undefined, undefined, undefined, space),
       operands: listOperands(db, undefined, undefined, space),
+      patches: listPatches(db, undefined, undefined, undefined, space),
+      macros: listMacros(db, undefined, space),
+      macroUses: listMacroUses(db, undefined, undefined, undefined, space),
     };
   } finally {
     db?.close();
@@ -116,10 +126,14 @@ async function decode(image: Image, knowledge: ReturnType<typeof readKnowledge>,
 }
 
 /** Assembles files given as text with ACME; the program or the diagnostics. */
-async function assembleFiles(files: Array<{ name: string; text: string }>, entry: string): Promise<{ program?: Buffer; start?: number; symbols?: AssembledSymbol[]; diagnostics: Diagnostic[] }> {
+async function assembleFiles(
+  files: Array<{ name: string; text: string }>,
+  entry: string,
+  defines: Record<string, number> = {},
+): Promise<{ program?: Buffer; start?: number; symbols?: AssembledSymbol[]; diagnostics: Diagnostic[] }> {
   const contents = files.map((file) => Buffer.from(file.text, "utf8"));
   const { result, attachments } = await assemble(
-    { files: files.map((file, index) => ({ path: file.name, size: contents[index]!.length })), entrySource: entry, includeDirs: [], defines: {} },
+    { files: files.map((file, index) => ({ path: file.name, size: contents[index]!.length })), entrySource: entry, includeDirs: [], defines },
     contents,
     localToolContext(),
   );
@@ -169,12 +183,88 @@ async function probe(laid: Layout): Promise<Set<string>> {
   throw new WireFailure("operation-failed", "ACME refused the opcode probe three times.");
 }
 
+/** The macro uses that an ACME error names: its line, or a line of the macro body in macros.asm, which every use of that macro shares. */
+function usesInErrors(diagnostics: Diagnostic[], lineOf: ReadonlyMap<string, number>, uses: ReadonlyArray<{ start: number; macro: string }>, macroLines: Rendered["macroLines"], markLines: number): Map<number, string> {
+  const blamed = new Map<number, string>();
+  for (const diagnostic of diagnostics) {
+    if (diagnostic.severity !== "error" || diagnostic.file === undefined || diagnostic.line === undefined) continue;
+    const start = lineOf.get(`${diagnostic.file}:${diagnostic.line}`);
+    if (start !== undefined) blamed.set(start, `ACME refuses it: ${diagnostic.message}`);
+    if (diagnostic.file !== "macros.asm") continue;
+    for (const [macro, lines] of macroLines) {
+      if (diagnostic.line < lines.first + markLines || diagnostic.line > lines.last + markLines) continue;
+      for (const use of uses) if (use.macro === macro) blamed.set(use.start, `ACME refuses the macro ${macro}: ${diagnostic.message}`);
+    }
+  }
+  return blamed;
+}
+
+/** The first address where two byte runs differ, as a reason. */
+function firstDifference(start: number, built: (address: number) => number, original: (address: number) => number, end: number): string | undefined {
+  for (let address = start; address <= end; address++) {
+    if (built(address) !== original(address)) return `ACME assembles it to other bytes than the image: at ${formatC64Address(address)} it gives $${built(address).toString(16).padStart(2, "0")}, and the image has $${original(address).toString(16).padStart(2, "0")}.`;
+  }
+  return undefined;
+}
+
+/**
+ * Assembles each macro use alone at its own address, with the constants and
+ * the macros, and gives the uses that ACME refuses or assembles to other bytes
+ * than the image, with the reason (D73). A use of another length moves no
+ * other use, so each one is checked on its own, as the opcode probe does.
+ */
+async function probeUses(laid: Layout, rendered: Rendered, image: Image): Promise<Map<number, string>> {
+  const blamed = new Map<number, string>();
+  const support = rendered.files.filter((file) => file.name === "constants.asm" || file.name === "macros.asm");
+  for (let round = 0; round < 3; round++) {
+    const uses = [...laid.macroUses.values()].filter((use) => !blamed.has(use.start));
+    if (uses.length === 0) return blamed;
+    // The labels of the image that the args name, with their values: the probe has no other source.
+    const labels = new Map<string, number>();
+    for (const [address, name] of laid.names) if (laid.inImage(address)) labels.set(name, address);
+    const used = [...new Set(uses.flatMap((use) => use.args.flatMap((arg) => identifiers(arg))))].filter((name) => labels.has(name)).sort();
+    const lines = ["!cpu 6510", '!source "constants.asm"', '!source "macros.asm"', ...used.map((name) => `${name} = ${labels.get(name)! < 0x100 ? `$${labels.get(name)!.toString(16).padStart(2, "0")}` : formatC64Address(labels.get(name)!)}`), `* = ${formatC64Address(PROBE_BASE)}`];
+    const lineOf = new Map<string, number>();
+    uses.forEach((use, index) => {
+      lines.push(`!pseudopc ${formatC64Address(use.start)} {`, `        +${use.macro}${use.args.length === 0 ? "" : ` ${use.args.join(", ")}`}`);
+      lineOf.set(`probe.asm:${lines.length}`, use.start);
+      lines.push(`probe_end_${index}`, "}");
+    });
+    const built = await assembleFiles([...support, { name: "probe.asm", text: `${lines.join("\n")}\n` }], "probe.asm");
+    if (built.program === undefined) {
+      const refused = usesInErrors(built.diagnostics, lineOf, uses, rendered.macroLines, 0);
+      if (refused.size === 0) throw new WireFailure("operation-failed", `ACME refused the macro probe: ${built.diagnostics.map((diagnostic) => diagnostic.message).join("; ")}`);
+      for (const [start, reason] of refused) blamed.set(start, reason);
+      continue;
+    }
+    const ends = new Map((built.symbols ?? []).map((symbol) => [symbol.name, symbol.kind === "address" ? symbol.address : symbol.value]));
+    let offset = 2 + PROBE_BASE - built.start!;
+    uses.forEach((use, index) => {
+      const length = ends.get(`probe_end_${index}`)! - use.start;
+      const wanted = use.end - use.start + 1;
+      const program = built.program!;
+      const at = offset;
+      offset += length;
+      if (length !== wanted) {
+        blamed.set(use.start, `ACME assembles it to ${length} bytes, and the range has ${wanted}.`);
+        return;
+      }
+      const reason = firstDifference(use.start, (address) => program[at + address - use.start]!, image.byteAt, use.end);
+      if (reason !== undefined) blamed.set(use.start, reason);
+    });
+    return blamed;
+  }
+  throw new WireFailure("operation-failed", "ACME refused the macro probe three times.");
+}
+
 /**
- * The operand expressions that made the assembly fail or that ACME assembled
- * to other bytes than the image, with the reason (D65). `markLines` is the
- * number of lines added before the rendered text of each file.
+ * The operand expressions (D65) and macro uses (D73) that made the assembly
+ * fail or that ACME assembled to other bytes than the image, with the
+ * reason. `markLines` is the number of lines added before the rendered text of
+ * each file. A use of another length moves every byte after it: then only the
+ * first use that differs is blamed, and no operand.
  */
-function blame(rendered: Rendered, built: Awaited<ReturnType<typeof assembleFiles>>, image: Image, markLines: number): Map<number, string> {
+function blame(rendered: Rendered, built: Awaited<ReturnType<typeof assembleFiles>>, image: Image, markLines: number): { numbers: Map<number, string>; uses: Map<number, string> } {
   const blamed = new Map<number, string>();
   if (built.program === undefined) {
     const lines = new Map(rendered.expressions.map((item) => [`${item.file}:${item.line + markLines}`, item.address]));
@@ -183,9 +273,20 @@ function blame(rendered: Rendered, built: Awaited<ReturnType<typeof assembleFile
       const address = lines.get(`${diagnostic.file}:${diagnostic.line}`);
       if (address !== undefined) blamed.set(address, `ACME refuses it: ${diagnostic.message}`);
     }
-    return blamed;
+    const useLines = new Map(rendered.uses.map((use) => [`${use.file}:${use.line + markLines}`, use.start]));
+    return { numbers: blamed, uses: usesInErrors(built.diagnostics, useLines, rendered.uses, rendered.macroLines, markLines) };
   }
   const end = built.start! + built.program.length - 3;
+  const at = (address: number) => (address >= built.start! && address <= end ? built.program![2 + address - built.start!]! : -1);
+  const uses = new Map<number, string>();
+  const imageEnd = Math.max(...image.segments.map((segment) => segment.end));
+  for (const use of rendered.uses) {
+    const reason = firstDifference(use.start, at, image.byteAt, use.end);
+    if (reason === undefined) continue;
+    uses.set(use.start, reason);
+    if (end !== imageEnd) break;
+  }
+  if (uses.size > 0) return { numbers: blamed, uses };
   const word = (at: (address: number) => number, item: Rendered["expressions"][number]) => (item.length === 3 ? at(item.address + 1) | (at(item.address + 2) << 8) : at(item.address + 1));
   const show = (value: number, length: number) => `$${value.toString(16).padStart(length === 3 ? 4 : 2, "0")}`;
   for (const item of rendered.expressions) {
@@ -194,7 +295,7 @@ function blame(rendered: Rendered, built: Awaited<ReturnType<typeof assembleFile
     const original = word(image.byteAt, item);
     if (assembled !== original) blamed.set(item.address, `ACME assembles it to ${show(assembled, item.length)}, and the image has ${show(original, item.length)}.`);
   }
-  return blamed;
+  return { numbers: blamed, uses };
 }
 
 interface SegmentCheck {
@@ -224,6 +325,57 @@ function check(program: Buffer, start: number, image: Image): { identical: boole
   return { identical: segments.every((segment) => segment.result === "identical"), segments };
 }
 
+/** What a build with one switch on gives (D72). */
+interface SwitchCheck {
+  name: string;
+  define: string;
+  patches: Array<{ start: string; end: string; bytes: number; insideNames?: string[] }>;
+  result: "fits" | "overflow" | "changes outside" | "does not assemble";
+  changedBytes?: number;
+  outside?: { count: number; first: { address: string; built: number; default: number } };
+  overflow?: Array<{ start: string; message: string }>;
+  diagnostics?: Diagnostic[];
+}
+
+/**
+ * Builds the source with one switch on and compares it with the default
+ * build: only the ranges of its patches may change, and the program keeps its
+ * start and length. A patch longer than its range stops ACME with !error.
+ */
+async function checkSwitch(name: string, patches: PatchBlock[], files: Array<{ name: string; text: string }>, base: { program: Buffer; start: number }, names: Layout["names"]): Promise<SwitchCheck> {
+  const shown: SwitchCheck = {
+    name,
+    define: `--define ${name}=1`,
+    patches: patches.map((patch) => {
+      const inside = patch.inner.map((address) => names.get(address)!);
+      return { start: formatC64Address(patch.start), end: formatC64Address(patch.end), bytes: patch.end - patch.start + 1, ...(inside.length === 0 ? {} : { insideNames: inside }) };
+    }),
+    result: "fits",
+  };
+  const built = await assembleFiles(files, "main.asm", { [name]: 1 });
+  if (built.program === undefined) {
+    const overflow = built.diagnostics.flatMap((diagnostic) => {
+      const found = /The patch \S+ at (\$[0-9a-f]{4}) has .*/.exec(diagnostic.message);
+      return found === null ? [] : [{ start: found[1]!, message: found[0] }];
+    });
+    if (overflow.length > 0) return { ...shown, result: "overflow", overflow };
+    return { ...shown, result: "does not assemble", diagnostics: built.diagnostics.slice(0, MAX_LISTED) };
+  }
+  const inside = (address: number) => patches.some((patch) => address >= patch.start && address <= patch.end);
+  let changed = 0;
+  let outside: SwitchCheck["outside"];
+  const end = Math.max(base.start + base.program.length, built.start! + built.program.length) - 2;
+  for (let address = Math.min(base.start, built.start!); address < end; address++) {
+    const at = (program: Buffer, start: number) => (address >= start && address < start + program.length - 2 ? program[2 + address - start]! : -1);
+    const now = at(built.program, built.start!);
+    const before = at(base.program, base.start);
+    if (now === before) continue;
+    if (inside(address)) changed++;
+    else outside = { count: (outside?.count ?? 0) + 1, first: outside?.first ?? { address: formatC64Address(address), built: now, default: before } };
+  }
+  return outside === undefined ? { ...shown, changedBytes: changed } : { ...shown, result: "changes outside", changedBytes: changed, outside };
+}
+
 /** Reads RAM in parts. */
 async function readRam(client: ViceSessionClient, start: number, size: number): Promise<Buffer> {
   const parts: Buffer[] = [];
@@ -332,7 +484,7 @@ async function run(argv: string[]): Promise<{ output: Record<string, unknown>; f
   try {
     resolveProjectPath(values.out);
   } catch {
-    throw new UsageError(`--out must be a path relative to the project directory that stays inside it, not ${values.out}`);
+    throw new UsageError(`--out must be a path relative to the project folder that stays inside it, not ${values.out}`);
   }
   const entries = (values.entry ?? []).map((value) => {
     try {
@@ -364,9 +516,12 @@ async function run(argv: string[]): Promise<{ output: Record<string, unknown>; f
     modules: knowledge.modules,
     referenceTargets: knowledge.references.map((reference) => reference.to),
     operands: knowledge.operands,
+    patches: knowledge.patches,
+    macros: knowledge.macros,
+    macroUses: knowledge.macroUses,
     ...(coverage === undefined ? {} : { coverage }),
     // The platform names are C64 names: drive code and banks get none.
-    ...(space === DEFAULT_SPACE ? { platform: platformNames() } : {}),
+    ...(space === DEFAULT_SPACE ? { platform: platformNames(), describe: describeAddress } : {}),
   });
   const asBytes = await probe(laid);
   const header = [`Generated by c64-source from ${image.path}${space === DEFAULT_SPACE ? "" : ` in space ${space}`} and knowledge revision ${knowledge.revision}.`, "Change names, comments, regions and modules in knowledge, then generate again."];
@@ -379,7 +534,7 @@ async function run(argv: string[]): Promise<{ output: Record<string, unknown>; f
     const segments = image.segments.map((segment) => ({ ...segment, files: laid.pieces.filter((piece) => piece.start >= segment.start && piece.start <= segment.end).map((piece) => piece.file) }));
     try {
       const entryName = laid.names.get(image.entry!);
-      loader = planLoader({ segments, byteAt: image.byteAt, state, entry: image.entry!, ...(entryName === undefined ? {} : { entryName }), header: [`Loader generated by c64-source from ${image.path}.`, "It copies the segments into place, sets the entry state and jumps to the entry."] });
+      loader = planLoader({ segments, byteAt: image.byteAt, state, entry: image.entry!, ...(entryName === undefined ? {} : { entryName }), macros: laid.macros.length > 0, header: [`Loader generated by c64-source from ${image.path}.`, "It copies the segments into place, sets the entry state and jumps to the entry."] });
     } catch (error) {
       if (!(error instanceof WireFailure)) throw error;
       loaderRefused = error.message;
@@ -388,16 +543,21 @@ async function run(argv: string[]): Promise<{ output: Record<string, unknown>; f
   // Every generated file starts with the mark, so a later run knows its own files and removes the ones it does not write again (F-25).
   const marked = (list: Array<{ name: string; text: string }>) => list.map((file) => ({ ...file, text: `${GENERATED_MARK}. Do not edit: change the knowledge and generate again.\n${file.text}` }));
   const loaderFiles = loader === undefined ? [] : [{ name: "loader.asm", text: loader.text }];
-  // An operand expression that ACME refuses, or assembles to other bytes, is written as its number, and the source is assembled again (D65).
+  // An operand expression that ACME refuses, or assembles to other bytes, is written as its number, and a macro use as its
+  // instructions; then the source is assembled again (D65, D73).
   const numbers = new Map<number, string>();
-  let rendered = render(laid, asBytes, header, numbers);
+  const asInstructions = new Map<number, string>();
+  let rendered = render(laid, asBytes, header, numbers, asInstructions);
+  if (laid.macroUses.size > 0) for (const [start, reason] of await probeUses(laid, rendered, image)) asInstructions.set(start, reason);
+  if (asInstructions.size > 0) rendered = render(laid, asBytes, header, numbers, asInstructions);
   let files = marked([...rendered.files, ...loaderFiles]);
   let built = await assembleFiles(files, "main.asm");
-  for (let round = 0; round < OPERAND_ROUNDS && rendered.expressions.length > 0; round++) {
+  for (let round = 0; round < ROUNDS && (rendered.expressions.length > 0 || rendered.uses.length > 0); round++) {
     const blamed = blame(rendered, built, image, 1);
-    if (blamed.size === 0) break;
-    for (const [address, reason] of blamed) numbers.set(address, reason);
-    rendered = render(laid, asBytes, header, numbers);
+    if (blamed.numbers.size === 0 && blamed.uses.size === 0) break;
+    for (const [address, reason] of blamed.numbers) numbers.set(address, reason);
+    for (const [start, reason] of blamed.uses) asInstructions.set(start, reason);
+    rendered = render(laid, asBytes, header, numbers, asInstructions);
     files = marked([...rendered.files, ...loaderFiles]);
     built = await assembleFiles(files, "main.asm");
   }
@@ -446,6 +606,25 @@ async function run(argv: string[]): Promise<{ output: Record<string, unknown>; f
             listed: rendered.operandsAsNumbers.slice(0, MAX_LISTED).map((item) => ({ address: formatC64Address(item.address), expression: item.expression, reason: item.reason })),
           },
         }),
+    ...(rendered.uses.length === 0 && rendered.macrosAsInstructions.length === 0 ? {} : { macroUses: rendered.uses.length }),
+    // A macro use that the source writes as its instructions does not fail the run: the source stays identical (D73).
+    ...(rendered.macrosAsInstructions.length === 0
+      ? {}
+      : {
+          macrosAsInstructions: {
+            count: rendered.macrosAsInstructions.length,
+            listed: rendered.macrosAsInstructions.slice(0, MAX_LISTED).map((item) => ({ start: formatC64Address(item.start), end: formatC64Address(item.end), macro: item.macro, reason: item.reason })),
+          },
+        }),
+    // A patch that the source cannot write fails the run: the switch would miss a part (D72).
+    ...(laid.patchesNotWritten.length === 0
+      ? {}
+      : {
+          patchesNotWritten: {
+            count: laid.patchesNotWritten.length,
+            listed: laid.patchesNotWritten.slice(0, MAX_LISTED).map((item) => ({ start: formatC64Address(item.start), end: formatC64Address(item.end), switch: item.switch, reason: item.reason })),
+          },
+        }),
   };
   // The loader includes the source, so it is built only from a source that is identical to the image.
   const notBuilt = (reason: string) => (state === undefined ? {} : { loader: { verified: false, reason: loaderRefused ?? reason } });
@@ -455,8 +634,13 @@ async function run(argv: string[]): Promise<{ output: Record<string, unknown>; f
   const checked = check(built.program, built.start!, image);
   output.check = checked;
   if (!checked.identical) return { output: { ...output, ...notBuilt("The source does not assemble to the image, and the loader includes it.") }, failed: true };
+  // Each switch on alone, against the default build (D72); combinations are not built.
+  const switches: SwitchCheck[] = [];
+  for (const [name, patches] of switchesOf(laid)) switches.push(await checkSwitch(name, patches, files, { program: built.program, start: built.start! }, laid.names));
+  if (switches.length > 0) output.switches = switches;
+  const sourceFailed = laid.patchesNotWritten.length > 0 || switches.some((item) => item.result !== "fits");
   if (loaderRefused !== undefined) return { output: { ...output, loader: { verified: false, reason: loaderRefused } }, failed: true };
-  if (loader === undefined || state === undefined) return { output, failed: missingEntry !== undefined };
+  if (loader === undefined || state === undefined) return { output, failed: missingEntry !== undefined || sourceFailed };
 
   const loaderBuilt = await assembleFiles(files, "loader.asm");
   if (loaderBuilt.program === undefined) return { output: { ...output, loader: { verified: false, reason: "loader.asm does not assemble.", diagnostics: loaderBuilt.diagnostics.slice(0, MAX_LISTED) } }, failed: true };
@@ -490,12 +674,12 @@ async function run(argv: string[]): Promise<{ output: Record<string, unknown>; f
     // What the loader cannot set as it was at the entry (D63).
     ...(loader.cia === undefined || loader.cia.limits.length === 0 ? {} : { limits: loader.cia.limits }),
   };
-  return { output, failed: !ran.verified };
+  return { output, failed: !ran.verified || sourceFailed };
 }
 
 await runScript(
-  async () => {
-    const { output, failed } = await run(process.argv.slice(2));
+  async (argv) => {
+    const { output, failed } = await run(argv);
     if (failed) process.exitCode = 1;
     return output;
   },

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

@@ -357,6 +357,8 @@ export interface LoaderInput {
   /** The label of the entry in the source: the loader jumps to it, so the jump follows the code when it moves (D66). */
   entryName?: string;
   header: string[];
+  /** The source has macros.asm (D73): the loader includes it after the constants. */
+  macros?: boolean;
 }
 
 /** The label of a block (D66): its first byte and the byte after it in the loader file, and its first address where it runs. */
@@ -419,7 +421,7 @@ export function planLoader(input: LoaderInput): LoaderPlan {
   const copyBlocks = order.map((index) => blockOf[index]!);
 
   const stackByte = 0x0100 + state.sp;
-  const lines: string[] = [...input.header.map((line) => `; ${line}`), "", "!cpu 6510", '!source "constants.asm"', "", `* = ${hex4(LOAD)}`];
+  const lines: string[] = [...input.header.map((line) => `; ${line}`), "", "!cpu 6510", '!source "constants.asm"', ...(input.macros ? ['!source "macros.asm"'] : []), "", `* = ${hex4(LOAD)}`];
   lines.push(`        !byte $0b,$08,$0a,$00,$9e,${[...String(STUB)].map((digit) => hex2(digit.charCodeAt(0))).join(",")},$00,$00,$00 ; 10 SYS ${STUB}`);
   lines.push(
     "!zone loader_stub {",

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

@@ -59,3 +59,22 @@ export function takesAddress(mode: Mode): boolean {
 export function isZeroPageMode(mode: Mode): boolean {
   return mode === "zp" || mode === "zpx" || mode === "zpy" || mode === "izx" || mode === "izy";
 }
+
+/** How an instruction uses the address of its operand, in the order a summary lists them. */
+export const USE_KINDS = ["read", "written", "modified", "called", "jumped to", "jumped through", "branched to", "pointer", "address", "table", "macro argument"] as const;
+export type UseKind = (typeof USE_KINDS)[number];
+
+const WRITES = new Set(["sta", "stx", "sty", "sax", "sha", "shx", "shy", "tas"]);
+const MODIFIES = new Set(["inc", "dec", "asl", "lsr", "rol", "ror", "slo", "rla", "sre", "rra", "dcp", "isc"]);
+
+/** The use of the operand address of an instruction that takes an address. Through (zp),y and (zp,x) the address is a pointer. */
+export function useKind(opcode: number): UseKind {
+  const { mnemonic, mode } = OPCODES[opcode]!;
+  if (mode === "izx" || mode === "izy") return "pointer";
+  if (mode === "rel") return "branched to";
+  if (mnemonic === "jsr") return "called";
+  if (mnemonic === "jmp") return mode === "ind" ? "jumped through" : "jumped to";
+  if (WRITES.has(mnemonic)) return "written";
+  if (MODIFIES.has(mnemonic)) return "modified";
+  return "read";
+}