@henols/c64-re-tools 2.1.0-rc.1 → 2.1.0

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

@@ -3,27 +3,21 @@
 // knowledge; a target that knowledge does not name gets l_xxxx. Data is
 // 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
+// encodes differently as bytes (see the probe in source.ts). An operand
 // expression of the knowledge is written in place of its number. A
 // patch is written as !if SWITCH { code } else { original }, and a
 // macro use as one +name args line.
 
-import { COVERAGE, formatC64Address, POINTER_TABLE_TYPES, pointerTableEntries, type PointerTableType } from "#src/c64.ts";
+import { type AddressRange, COVERAGE, formatC64Address, formatC64Byte, POINTER_TABLE_TYPES, pointerTableEntries, type PointerTableType } 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 { type CommentPlacement, isAnalyzer, isGeneratedFile, type Origin, type RegionType } from "#src/knowledge/schema.ts";
 import type { Area } from "#src/platform.ts";
 import { hasZeroPageForm, MNEMONICS, MODE_LENGTH, OPCODES, takesAddress, USE_KINDS, useKind, type Mode, type UseKind } from "#src/opcodes.ts";
 
-export interface Range {
-  start: number;
-  end: number;
-}
-
 export interface SourceInput {
   /** In address order, without overlap. */
-  segments: Range[];
+  segments: AddressRange[];
   /** The image byte at an address inside a segment. */
   byteAt: (address: number) => number;
   entry?: number;
@@ -144,7 +138,7 @@ function decodedStores(pieces: readonly Piece[], input: SourceInput): Array<{ ad
       if (input.segments.some((segment) => target >= segment.start && target <= segment.end)) continue;
       try {
         const text = decodedText(input.decode(target, input.byteAt(load.address + 1)));
-        if (text !== "") found.push({ address: store.address, placement: "side", text: `${hex4(target)}: ${text}` });
+        if (text !== "") found.push({ address: store.address, placement: "side", text: `${formatC64Address(target)}: ${text}` });
       } catch {
         // No decoder for this register.
       }
@@ -212,10 +206,8 @@ export interface Layout {
   macrosAsInstructions: MacroAsInstructions[];
 }
 
-const hex2 = (value: number) => `$${value.toString(16).padStart(2, "0")}`;
-const hex4 = (value: number) => formatC64Address(value);
 /** ACME reads leading zeros as a 16-bit value, so a zero-page name gets two digits. */
-const constantValue = (address: number) => (address < 0x100 ? hex2(address) : hex4(address));
+const constantValue = (address: number) => (address < 0x100 ? formatC64Byte(address) : formatC64Address(address));
 const signed = (byte: number) => (byte < 0x80 ? byte : byte - 0x100);
 
 function operandValue(address: number, opcode: number, byteAt: (address: number) => number): number | undefined {
@@ -240,9 +232,9 @@ export function entriesInData<R extends { start: number; end: number; type: Regi
 }
 
 /** Why an image without its entry fails: the image does not hold the program. Undefined when the entry is in a segment, or the image has no entry. */
-export function entryOutsideImage(entry: number | undefined, segments: readonly Range[]): string | undefined {
+export function entryOutsideImage(entry: number | undefined, segments: readonly AddressRange[]): string | undefined {
   if (entry === undefined || segments.some((segment) => entry >= segment.start && entry <= segment.end)) return undefined;
-  return `The entry ${hex4(entry)} is in no segment of the image: the image does not hold the program. Capture it again with c64-unpacker loads or capture.`;
+  return `The entry ${formatC64Address(entry)} is in no segment of the image: the image does not hold the program. Capture it again with c64-unpacker loads or capture.`;
 }
 
 /** Splits the segments into pieces at module starts and lays out instructions and data. */
@@ -255,7 +247,7 @@ export function layout(input: SourceInput): Layout {
   };
 
   for (const module of input.modules) {
-    if (isGeneratedFile(module.file)) throw new WireFailure("invalid-input", `The module at ${hex4(module.start)} has the file ${module.file}, which the generator writes itself. Give the module another file.`);
+    if (isGeneratedFile(module.file)) throw new WireFailure("invalid-input", `The module at ${formatC64Address(module.start)} has the file ${module.file}, which the generator writes itself. Give the module another file.`);
   }
   const modules = [...input.modules].sort((a, b) => a.start - b.start);
   const unusedModules = modules.filter((module) => !inImage(module.start)).map(({ start, file }) => ({ start, file }));
@@ -274,14 +266,14 @@ export function layout(input: SourceInput): Layout {
       const end = bounds[index + 1]! - 1;
       const module = modules.find((row) => row.start === start);
       const file = module?.file ?? `segment_${start.toString(16).padStart(4, "0")}.asm`;
-      const title = module?.title?.replace(/\s*\r?\n\s*/g, " ") ?? `Segment ${hex4(segment.start)}-${hex4(segment.end)}`;
+      const title = module?.title?.replace(/\s*\r?\n\s*/g, " ") ?? `Segment ${formatC64Address(segment.start)}-${formatC64Address(segment.end)}`;
       pieces.push({ start, end, file, title, segmentStart: index === 0, items: [] });
     }
   }
   const files = new Map<string, number>();
   for (const piece of pieces) {
     const other = files.get(piece.file);
-    if (other !== undefined) throw new WireFailure("invalid-input", `The file ${piece.file} is used at ${hex4(other)} and at ${hex4(piece.start)}. Give the module another file.`);
+    if (other !== undefined) throw new WireFailure("invalid-input", `The file ${piece.file} is used at ${formatC64Address(other)} and at ${formatC64Address(piece.start)}. Give the module another file.`);
     files.set(piece.file, piece.start);
   }
 
@@ -329,7 +321,6 @@ export function layout(input: SourceInput): Layout {
   const knowledgeNames = new Set(input.symbols.map((symbol) => symbol.name));
   const platform = new Map((input.platform ?? []).filter(({ name }) => !knowledgeNames.has(name) && !MNEMONICS.has(name.toLowerCase())).map(({ address, name }) => [address, name]));
   // An analyzer name (DXA's ld020) gives way to the platform name (EXTCOL); a user or LLM name wins.
-  const isAnalyzer = (origin: Origin | undefined) => (ANALYZERS as readonly (Origin | undefined)[]).includes(origin);
   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. */
   const insideEntry = new Map<number, number>();
@@ -444,7 +435,7 @@ export function layout(input: SourceInput): Layout {
       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.` });
+      macrosAsInstructions.push({ start: candidate.use.start, end: candidate.use.end, macro: candidate.use.macro, reason: `The source has a label at ${formatC64Address(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));
@@ -459,7 +450,7 @@ export function layout(input: SourceInput): Layout {
   for (const address of [...wanted, ...outside].sort((a, b) => a - b)) {
     const known = symbols.get(address);
     if (known !== undefined) {
-      if (MNEMONICS.has(known.toLowerCase())) throw new WireFailure("invalid-input", `The symbol ${known} at ${hex4(address)} has the name of an instruction, which ACME cannot read as a label. Rename the symbol with c64-knowledge.`);
+      if (MNEMONICS.has(known.toLowerCase())) throw new WireFailure("invalid-input", `The symbol ${known} at ${formatC64Address(address)} has the name of an instruction, which ACME cannot read as a label. Rename the symbol with c64-knowledge.`);
       names.set(address, known);
       if (inImage(address)) namedLabels++;
       continue;
@@ -488,14 +479,14 @@ export function layout(input: SourceInput): Layout {
       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.`);
+      refuse(`The range runs past the end of the file ${piece.file} at ${formatC64Address(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)}.`);
+      refuse(cut === undefined ? "The range does not start and end at an item of the source." : `The range cuts the instruction at ${formatC64Address((cut as InstructionItem).address)}.`);
       continue;
     }
     if (sourceNames.has(patch.switch)) {
@@ -607,7 +598,7 @@ export function instructionText(opcode: number, suffix: string, expression: stri
 /** The plain number of an operand: what the probe assembles, and what a comment shows. */
 export function literalOperand(opcode: number, value: number): string {
   const { mode } = OPCODES[opcode]!;
-  return MODE_LENGTH[mode] === 3 || mode === "rel" ? hex4(value) : hex2(value);
+  return MODE_LENGTH[mode] === 3 || mode === "rel" ? formatC64Address(value) : formatC64Byte(value);
 }
 
 /** One instruction of each form, for the probe: the form, and the instruction bytes. */
@@ -659,9 +650,9 @@ function cellsOf(item: DataItem, layout: Layout, breaks: Set<number>): Cell[] {
   const { byteAt } = layout;
   const cells: Cell[] = [];
   const name = (address: number) => layout.names.get(address);
-  const expression = (target: number) => name(target) ?? hex4(target);
-  const rtsExpression = (target: number) => (name(target) === undefined ? hex4((target - 1) & 0xffff) : `${name(target)}-1`);
-  const byteCell = (address: number, text = hex2(byteAt(address))): Cell => ({ address, length: 1, directive: "!byte", text });
+  const expression = (target: number) => name(target) ?? formatC64Address(target);
+  const rtsExpression = (target: number) => (name(target) === undefined ? formatC64Address((target - 1) & 0xffff) : `${name(target)}-1`);
+  const byteCell = (address: number, text = formatC64Byte(byteAt(address))): Cell => ({ address, length: 1, directive: "!byte", text });
 
   if (item.region !== undefined && POINTER_TYPES.includes(item.type)) {
     const rts = item.type === "rts-addresses" || item.type === "rts-addresses-split";
@@ -696,7 +687,7 @@ function cellsOf(item: DataItem, layout: Layout, breaks: Set<number>): Cell[] {
       const offset = address - (item.region?.start ?? item.start);
       const last = odd && address === item.region!.end;
       if (offset % 2 === 0 && !last && address + 1 <= item.end && !breaks.has(address + 1)) {
-        cells.push({ address, length: 2, directive: "!word", text: hex4(byteAt(address) | (byteAt(address + 1) << 8)) });
+        cells.push({ address, length: 2, directive: "!word", text: formatC64Address(byteAt(address) | (byteAt(address + 1) << 8)) });
         address++;
       } else cells.push(byteCell(address));
     }
@@ -721,12 +712,12 @@ function cellsOf(item: DataItem, layout: Layout, breaks: Set<number>): Cell[] {
       let end = address;
       while (end + 1 <= item.end && byteAt(end + 1) === value && !breaks.has(end + 1)) end++;
       if (end - address + 1 >= MIN_FILL) {
-        cells.push({ address, length: end - address + 1, directive: "!fill", text: `${end - address + 1}, ${hex2(value)}` });
+        cells.push({ address, length: end - address + 1, directive: "!fill", text: `${end - address + 1}, ${formatC64Byte(value)}` });
         address = end;
         continue;
       }
     }
-    cells.push(byteCell(address, binary ? `%${value.toString(2).padStart(8, "0")}` : hex2(value)));
+    cells.push(byteCell(address, binary ? `%${value.toString(2).padStart(8, "0")}` : formatC64Byte(value)));
   }
   return cells;
 }
@@ -779,7 +770,7 @@ function describeConstant(layout: Layout, address: number): string | undefined {
   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})`}.`;
+  return `Mirror of ${formatC64Address(mirrorOf)}${register === undefined ? "" : ` (${register.name})`}.`;
 }
 
 /** How the source uses a constant, for example "Used: read 4, written 1." */
@@ -801,7 +792,7 @@ function switchLines(layout: Layout): string[] {
   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(", ");
+    const ranges = patches.map((patch) => `${formatC64Address(patch.start)}-${formatC64Address(patch.end)}`).join(", ");
     lines.push(`!ifndef ${name} { ${name} = 0 }${" ".repeat(width - name.length)} ; ${patches.length} patch${patches.length === 1 ? "" : "es"}: ${ranges}`);
   }
   return [...lines, ""];
@@ -829,7 +820,7 @@ function constantsText(layout: Layout): { text: string; labels: SourceLabel[] }
     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)}`);
+      out.push("", `; ${area.name[0]!.toUpperCase()}${area.name.slice(1)} ${formatC64Address(area.start)}-${formatC64Address(area.end)}`);
       if (area.meaning !== undefined) out.push(`; ${area.meaning}`);
     }
     const line = `${row.name.padEnd(nameColumn)} = ${row.value.padEnd(valueColumn)}`;
@@ -865,7 +856,7 @@ export interface Rendered {
   /** Instructions written as bytes, because ACME writes their form with other bytes. */
   asBytes: Array<{ address: number; text: string }>;
   /** With coverage: runs of instructions that no run executed. */
-  notExecuted?: { instructions: number; ranges: Range[] };
+  notExecuted?: { instructions: number; ranges: AddressRange[] };
   /** Each instruction written with an operand expression: its file and line (1 is the first line of the text). */
   expressions: Array<{ address: number; length: number; file: string; line: number }>;
   /** Operand expressions written as numbers, in address order. */
@@ -900,7 +891,7 @@ function macrosText(layout: Layout): { text: string; lines: Map<string, { first:
 /** The lines that open a patch: 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 range = `${formatC64Address(patch.start)}-${formatC64Address(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")} {`,
@@ -909,7 +900,7 @@ function patchOpening(patch: PatchBlock): string[] {
     `${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 }`,
+    `${INDENT}!if * - .patch_start > ${bytes} { !error "The patch ${patch.switch} at ${formatC64Address(patch.start)} has ", * - .patch_start, " bytes; the range has ${bytes}." } else { !fill ${bytes} - (* - .patch_start), $ea }`,
     "} else {",
   ];
 }
@@ -957,10 +948,10 @@ export function render(layout: Layout, asBytes: ReadonlySet<string>, header: str
   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[] };
+  const notExecuted = { instructions: 0, ranges: [] as AddressRange[] };
 
   for (const piece of layout.pieces) {
-    const out: string[] = [`; ${piece.title}`, `; ${hex4(piece.start)}-${hex4(piece.end)}`, ""];
+    const out: string[] = [`; ${piece.title}`, `; ${formatC64Address(piece.start)}-${formatC64Address(piece.end)}`, ""];
     /** True while the instructions before have not executed: they form one range. */
     let running = false;
     /** The line of the mark of the open range of instructions that did not execute. */
@@ -981,7 +972,7 @@ export function render(layout: Layout, asBytes: ReadonlySet<string>, header: str
         }
         // The mark gives the range, so a reader finds it in the full list.
         const range = notExecuted.ranges.at(-1)!;
-        out[markLine] = `; not executed ${hex4(range.start)}-${hex4(range.end)}`;
+        out[markLine] = `; not executed ${formatC64Address(range.start)}-${formatC64Address(range.end)}`;
         notExecuted.instructions += count;
       }
       running = !executed;
@@ -1067,7 +1058,7 @@ export function render(layout: Layout, asBytes: ReadonlySet<string>, header: str
         if (written !== undefined && numbers.has(item.address)) asNumber(written, numbers.get(item.address)!);
         if (unwritten.has(item.address)) sides.unshift(`= ${unwritten.get(item.address)!}`);
         if (asBytes.has(form.key)) {
-          const bytes = Array.from({ length: item.length }, (_, offset) => hex2(layout.byteAt(item.address + offset)));
+          const bytes = Array.from({ length: item.length }, (_, offset) => formatC64Byte(layout.byteAt(item.address + offset)));
           out.push(withSide(`${INDENT}!byte ${bytes.join(",")}`, [literal, ...sides].join(" ")));
           result.asBytes.push({ address: item.address, text: literal });
         } else if (written !== undefined) {
@@ -1111,7 +1102,7 @@ export function render(layout: Layout, asBytes: ReadonlySet<string>, header: str
   }
   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)}`);
+    if (piece.segmentStart) main.push("", `* = ${formatC64Address(piece.start)}`);
     main.push(`!source "${piece.file}"`);
   }
   result.files.push({ name: "main.asm", text: `${main.join("\n")}\n` });

package/skills/c64-source/scripts/{generate.ts → source.ts}

@@ -4,55 +4,38 @@
 // also writes a loader that recreates the entry state, simulates it, and
 // checks it in the emulator. Each switch of the patches is built on
 // alone and checked. A macro use 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.
+// image is written as its instructions. result is PASS when every check
+// passes, else FAIL.
 
 import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
-import { parseArgs } from "node:util";
 
-import { COVERAGE, coverageSeedKinds, formatC64Address, parseC64Address, textToPetscii } from "#src/c64.ts";
+import { Refusal } from "#src/errors.ts";
+import { type AddressRange, COVERAGE, coverageSeedKinds, formatC64Address, textToPetscii } from "#src/c64.ts";
 import { autostartLoaded, RUN_LIMIT_FRAMES } from "#src/host-client/autostart.ts";
 import { MAX_MEMORY_READ, WireFailure } from "#src/host-client/tools.ts";
-import { writeProjectFile } from "#src/host-client/transfer.ts";
+import { writeReported, type Written } 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 { openForRead } from "#src/knowledge/database.ts";
 import { identifiers } from "#src/knowledge/expression.ts";
 import { analyzedBytes, programCoverage, requireProgram, type ProgramImage } from "#src/knowledge/program.ts";
 import { ANALYZER_NAME_ORDER, currentRevision, listAnalyzerNames, listComments, listMacros, listMacroUses, listModules, listOperands, listPatches, listReferences, listRegions, listSymbols, type SymbolRow } from "#src/knowledge/read.ts";
-import { CODE_REGION_TYPES, DEFAULT_SPACE, SPACE, type Space } from "#src/knowledge/schema.ts";
+import { CODE_REGION_TYPES, DEFAULT_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 { decode as decodeRegister, describeAddress, platformNamesFor, romUseOf, romUseOfPort, type RomUse } from "#src/platform.ts";
 import { resolveProjectPath } from "#src/project.ts";
-import { runScript, UsageError } from "#src/script.ts";
-import { COPIER_SOURCE, LOADER_JUMP, loaderLimits, planLoader, rasterLine, readEntryState, simulate, stopCause, VIC_DISPLAY_REGISTERS, type EntryState, type LoaderPlan } from "./lib/loader.ts";
+import { listed, OPTIONS, runScript, UsageError, type Call } from "#src/script.ts";
+import { knowledgeNames } from "#src/knowledge/names.ts";
+import { COPIER_SOURCE, LOADER_JUMP, loaderLimits, planLoader, rasterLine, loaderState, simulate, stopCause, VIC_DISPLAY_REGISTERS, type EntryState, type LoaderPlan } from "./lib/loader.ts";
 import { OPCODES } from "#src/opcodes.ts";
-import { entriesInData, entryOutsideImage, instructionText, layout, literalOperand, probeForms, render, switchesOf, type Layout, type PatchBlock, type Range, type Rendered } from "./lib/source.ts";
+import { entriesInData, entryOutsideImage, instructionText, layout, literalOperand, probeForms, render, switchesOf, type Layout, type PatchBlock, type Rendered } from "./lib/source.ts";
 
-const USAGE = `generate.ts --out <dir> [options]
-
-The program, its entry state and the coverage come from the knowledge:
-put them in with knowledge.ts image and coverage of the c64-knowledge skill.
-Code that no imported run executed is marked and listed; <dir>/not_executed.json
-has all of its ranges.
-
-  --out <dir>        the directory for the source files, relative to the project
-  --entry <address>  an entry point for Ghidra, for example '$080d' (repeatable)
-  --space <space>    the knowledge space of the program: c64 (the default), drive8,
-                     or bank0 to bank255; the coverage and --loader are for c64 only
-  --loader           also write loader.asm and loader.prg: the loader copies the
-                     segments into place, sets the entry state of the knowledge,
-                     and jumps to the entry; it is checked in the emulator
-  --analyzer-names   name an address that has no name of the user or the LLM, and
-                     no platform name, with its analyzer name
-
-The result is one JSON object. Addresses are $ and four hex digits.`;
-
-const MAX_LISTED = 20;
+/** At most this many diagnostics or differences of one check. */
+const MAX_DIAGNOSTICS = 20;
 /** Rounds of assembly that move operand expressions to numbers and macro uses to instructions. */
 const ROUNDS = 6;
 const PROBE_BASE = 0x1000;
@@ -66,7 +49,7 @@ function readKnowledge(space: Space, analyzerNames = false) {
   try {
     // With conflicts from a git merge, the source would depend on which of two rows comes first.
     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.`);
+    if (found > 0) throw new Refusal("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.`);
     const symbols = listSymbols(db, undefined, undefined, undefined, space);
     const second = listAnalyzerNames(db, undefined, undefined, undefined, space);
     return {
@@ -392,7 +375,7 @@ async function checkSwitch(name: string, patches: PatchBlock[], files: Array<{ n
       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) };
+    return { ...shown, result: "does not assemble", diagnostics: built.diagnostics.slice(0, MAX_DIAGNOSTICS) };
   }
   const inside = (address: number) => patches.some((patch) => address >= patch.start && address <= patch.end);
   let changed = 0;
@@ -499,7 +482,7 @@ async function runLoader(path: string, program: Buffer, plan: LoaderPlan, image:
       }
       plan.cia.masks.forEach((mask, index) => differ(`CIA ${index + 1} interrupt mask`, chips[index]!.interruptMask, mask));
     }
-    return { verified: differences.length === 0, differences: differences.slice(0, MAX_LISTED) };
+    return { verified: differences.length === 0, differences: differences.slice(0, MAX_DIAGNOSTICS) };
   } finally {
     await client.close();
   }
@@ -548,46 +531,21 @@ function removeOldFiles(out: string, keep: ReadonlySet<string>): void {
   }
 }
 
-async function run(argv: string[]): Promise<{ output: Record<string, unknown>; failed: boolean }> {
-  const { values, positionals } = parseArgs({
-    args: argv,
-    strict: true,
-    allowPositionals: true,
-    options: {
-      out: { type: "string" },
-      entry: { type: "string", multiple: true },
-      space: { type: "string" },
-      loader: { type: "boolean" },
-      "analyzer-names": { type: "boolean" },
-      help: { type: "boolean" },
-    },
-  });
-  if (values.help) throw new UsageError("");
-  if (positionals.length !== 0) throw new UsageError("generate takes no image: it reads the program from the knowledge (knowledge.ts image of the c64-knowledge skill puts it in)");
-  if (values.out === undefined) throw new UsageError("generate needs --out <dir>");
-  try {
-    resolveProjectPath(values.out);
-  } catch {
-    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 {
-      return parseC64Address(value);
-    } catch {
-      throw new UsageError(`--entry must be $ followed by four hex digits, not ${value}`);
-    }
-  });
-  const space = values.space ?? DEFAULT_SPACE;
-  if (!SPACE.test(space)) throw new UsageError("--space must be c64, drive8, or bank0 to bank255");
-  if (space !== DEFAULT_SPACE && values.loader) throw new UsageError("--loader works only in space c64");
-  const knowledge = readKnowledge(space, values["analyzer-names"] === true);
+async function generate(call: Call): Promise<{ output: Record<string, unknown>; failed: boolean }> {
+  const out = call.string("out")!;
+  const entries = call.addresses("entry");
+  const max = call.count("max-listed")!;
+  const space = call.space;
+  const loaderWanted = call.flag("loader");
+  if (space !== DEFAULT_SPACE && loaderWanted) throw new UsageError("--loader works only in space c64");
+  const knowledge = readKnowledge(space, call.flag("analyzer-names"));
   const image = knowledge.program;
   const coverage = knowledge.coverage;
-  if (values.loader && (image.state === undefined || image.entry === undefined)) {
-    throw new UsageError("--loader needs the entry and the entry state of a c64-unpacker capture in the knowledge: put the capture in with knowledge.ts image <image.json>");
+  if (loaderWanted && (image.state === undefined || image.entry === undefined)) {
+    throw new Refusal("not-found", "--loader needs the entry and the entry state of a c64-unpacker capture in the knowledge: put the capture in with knowledge.ts image <image.json>");
   }
   // Read the entry state before the long steps, so a bad state stops the run at once.
-  const state = values.loader ? readEntryState(JSON.stringify(image.state), "the entry state of the knowledge") : undefined;
+  const state = loaderWanted ? loaderState(image.state, "the entry state of the knowledge") : undefined;
   const romUse = romsInUse(image, coverage);
   const instructions = await decode(image, knowledge, entries, coverage);
   const laid = layout({
@@ -646,10 +604,10 @@ async function run(argv: string[]): Promise<{ output: Record<string, unknown>; f
     files = marked([...rendered.files, ...loaderFiles]);
     built = await assembleFiles(files, "main.asm");
   }
-  removeOldFiles(values.out, new Set(files.map((file) => file.name)));
-  for (const file of files) writeProjectFile(`${values.out}/${file.name}`, Buffer.from(file.text, "utf8"), { what: "--out" });
-  writeProjectFile(`${values.out}/${SOURCE_MAP_FILE}`, Buffer.from(sourceMapText(rendered, space, knowledge.revision, files), "utf8"), { what: "--out" });
-  const showRange = (range: Range) => ({ start: formatC64Address(range.start), end: formatC64Address(range.end) });
+  removeOldFiles(out, new Set(files.map((file) => file.name)));
+  const written: Written[] = files.map((file) => writeReported(`${out}/${file.name}`, file.text, { what: "--out" }));
+  written.push(writeReported(`${out}/${SOURCE_MAP_FILE}`, sourceMapText(rendered, space, knowledge.revision, files), { what: "--out" }));
+  const showRange = (range: AddressRange) => ({ start: formatC64Address(range.start), end: formatC64Address(range.end) });
   const inData = entriesInData(entries, knowledge.regions);
   if (rendered.notExecuted !== undefined) {
     // Each range with the file of the source that holds it and the routine before it, as a report groups them.
@@ -662,13 +620,13 @@ async function run(argv: string[]): Promise<{ output: Record<string, unknown>; f
     const files: Record<string, number> = {};
     for (const range of placed) if (range.file !== undefined) files[range.file] = (files[range.file] ?? 0) + 1;
     const all = { revision: knowledge.revision, instructions: rendered.notExecuted.instructions, files, ranges: placed };
-    writeProjectFile(`${values.out}/${NOT_EXECUTED_FILE}`, Buffer.from(`${JSON.stringify(all, null, 2)}\n`, "utf8"), { what: "--out" });
+    written.push(writeReported(`${out}/${NOT_EXECUTED_FILE}`, `${JSON.stringify(all, null, 2)}\n`, { what: "--out" }));
   }
 
   const output: Record<string, unknown> = {
-    out: values.out,
-    files: files.map((file) => file.name),
-    sourceMap: `${values.out}/${SOURCE_MAP_FILE}`,
+    out,
+    files: written,
+    sourceMap: `${out}/${SOURCE_MAP_FILE}`,
     revision: knowledge.revision,
     instructions: rendered.instructions,
     dataBytes: rendered.dataBytes,
@@ -683,51 +641,37 @@ async function run(argv: string[]): Promise<{ output: Record<string, unknown>; f
       : { entriesInData: inData.map(({ entry, region }) => ({ entry: formatC64Address(entry), region: { ...showRange(region), type: region.type }, origin: region.origin })) }),
     ...(rendered.asBytes.length === 0
       ? {}
-      : { asBytes: { count: rendered.asBytes.length, listed: rendered.asBytes.slice(0, MAX_LISTED).map((item) => ({ address: formatC64Address(item.address), instruction: item.text })) } }),
+      : { asBytes: listed(rendered.asBytes, max, (item) => ({ address: formatC64Address(item.address), instruction: item.text })) }),
     ...(rendered.notExecuted === undefined
       ? {}
       : {
-          notExecuted: {
-            instructions: rendered.notExecuted.instructions,
-            ranges: rendered.notExecuted.ranges.length,
-            listed: rendered.notExecuted.ranges.slice(0, MAX_LISTED).map(showRange),
-            all: `${values.out}/${NOT_EXECUTED_FILE}`,
-          },
+          notExecuted: { instructions: rendered.notExecuted.instructions, ...listed(rendered.notExecuted.ranges, max, showRange, `${out}/${NOT_EXECUTED_FILE}`) },
         }),
     ...(laid.unusedModules.length === 0 ? {} : { unusedModules: laid.unusedModules.map((module) => ({ start: formatC64Address(module.start), file: module.file })) }),
     ...(rendered.expressions.length === 0 && rendered.operandsAsNumbers.length === 0 ? {} : { operandExpressions: rendered.expressions.length }),
     ...(rendered.operandsAsNumbers.length === 0
       ? {}
       : {
-          operandsAsNumbers: {
-            count: rendered.operandsAsNumbers.length,
-            listed: rendered.operandsAsNumbers.slice(0, MAX_LISTED).map((item) => ({ address: formatC64Address(item.address), expression: item.expression, reason: item.reason })),
-          },
+          operandsAsNumbers: listed(rendered.operandsAsNumbers, max, (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.
     ...(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 })),
-          },
+          macrosAsInstructions: listed(rendered.macrosAsInstructions, max, (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.
     ...(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 })),
-          },
+          patchesNotWritten: listed(laid.patchesNotWritten, max, (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 } });
   if (built.program === undefined) {
-    return { output: { ...output, check: { identical: false, diagnostics: built.diagnostics.slice(0, MAX_LISTED) }, ...notBuilt("The source does not assemble, and the loader includes it.") }, failed: true };
+    return { output: { ...output, check: { identical: false, diagnostics: built.diagnostics.slice(0, MAX_DIAGNOSTICS) }, ...notBuilt("The source does not assemble, and the loader includes it.") }, failed: true };
   }
   const checked = check(built.program, built.start!, image);
   output.check = checked;
@@ -741,7 +685,7 @@ async function run(argv: string[]): Promise<{ output: Record<string, unknown>; f
   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 };
+  if (loaderBuilt.program === undefined) return { output: { ...output, loader: { verified: false, reason: "loader.asm does not assemble.", diagnostics: loaderBuilt.diagnostics.slice(0, MAX_DIAGNOSTICS) } }, failed: true };
   const program = loaderBuilt.program;
   // The simulation: the loader in memory as it loads, then every copy in its order, byte by byte.
   const memory = new Int16Array(0x10000).fill(-1);
@@ -759,9 +703,8 @@ async function run(argv: string[]): Promise<{ output: Record<string, unknown>; f
   const jump = jumpSymbol.kind === "address" ? jumpSymbol.address : jumpSymbol.value;
   const wrong = simulate(memory, loader.copies, expected);
   if (wrong !== undefined) throw new WireFailure("operation-failed", `The simulated loader writes a wrong byte at ${formatC64Address(wrong)}. This is a defect of the c64-source script.`);
-  const loaderPath = `${values.out}/loader.prg`;
-  writeProjectFile(loaderPath, program, { what: "--out" });
-  (output.files as string[]).push("loader.prg");
+  const loaderPath = `${out}/loader.prg`;
+  written.push(writeReported(loaderPath, program, { what: "--out" }));
   const copierSymbol = loaderBuilt.symbols?.find((symbol) => symbol.name === COPIER_SOURCE);
   if (copierSymbol === undefined) throw new WireFailure("operation-failed", `The assembled loader has no ${COPIER_SOURCE} label. This is a defect of the c64-source script.`);
   const copierSource = copierSymbol.kind === "address" ? copierSymbol.address : copierSymbol.value;
@@ -778,11 +721,27 @@ async function run(argv: string[]): Promise<{ output: Record<string, unknown>; f
   return { output, failed: !ran.verified || sourceFailed };
 }
 
-await runScript(
-  async (argv) => {
-    const { output, failed } = await run(argv);
-    if (failed) process.exitCode = 1;
-    return output;
-  },
-  { usage: USAGE, refusals: [KnowledgeError] },
-);
+await runScript({
+  name: "source",
+  summary: "Generates ACME source from the program and the knowledge, and checks with ACME that it assembles to the program byte by byte.",
+  names: knowledgeNames,
+  commands: [
+    {
+      name: "generate",
+      summary: "Writes the source files, source-map.json and not_executed.json, and checks them. result is PASS when every check passes, else FAIL.",
+      options: {
+        out: { ...OPTIONS.out, value: "<dir>", help: "the folder for the source files, relative to the project folder", required: true },
+        entry: { ...OPTIONS.entry, multiple: true, help: "an entry point for Ghidra" },
+        space: { ...OPTIONS.space, help: "the knowledge space of the program: c64 (the default), drive8, or bank0 to bank255. The coverage and --loader are for c64 only" },
+        loader: { kind: "flag", help: "also write loader.asm and loader.prg: the loader copies the segments into place, sets the entry state of the knowledge, and jumps to the entry. It is checked in the emulator" },
+        "analyzer-names": { kind: "flag", help: "name an address that has no name of the user or the LLM, and no platform name, with its analyzer name" },
+        "max-listed": OPTIONS["max-listed"],
+      },
+      notes: "The program, its entry state and the coverage come from the knowledge: put them in with knowledge.ts image and coverage of the c64-knowledge skill. Code that no imported run executed is marked and listed, and <dir>/not_executed.json has all of its ranges. Without --analyzer-names, an address without a name gets a name of the source, for example l_17e2.",
+      run: async (call) => {
+        const { output, failed } = await generate(call);
+        return { result: failed ? "FAIL" : "PASS", ...output };
+      },
+    },
+  ],
+});