@henols/c64-re-tools 2.1.1 → 2.1.3

package/skills/c64-memory-map/SKILL.md

@@ -36,6 +36,8 @@ node <skill>/scripts/memory-map.ts export --out src/hw.asm
 
 Write a value for `decode` and `--bank` as `$` and hex digits, as a decimal number, or as `%` and binary digits. Put a `$` value in single quotes in a shell.
 
+`at` and `decode` also take a platform name, for example `SCROLY` or `CHROUT`, in upper or lower case. A platform name comes before a name of the knowledge. `list` and `export` show the platform names.
+
 ### Calling the script
 
 - Call a script as `node <skill>/scripts/<script>.ts <command> [subjects] [options]`. The command comes first.
@@ -43,6 +45,7 @@ Write a value for `decode` and `--bank` as `$` and hex digits, as a decimal numb
 - An address is `$` and 1 to 4 hex digits, for example `'$c000'` or `'$fb'`, or a name. A name is a symbol, else an analyzer name that only one analyzer gives. Quote an address in a shell.
 - A range is `<start>-<end>`, for example `'$c000-$cfff'`. In a JSON file, a range is `start` and `end`.
 - Bytes in a JSON file are hex in a field `data`, for example `"data": "a900"`.
+- The script examines each `--out` path before it starts work. It refuses a path in `.c64-re-tools/knowledge/` and the index of the knowledge, because only c64-knowledge writes them. It refuses a folder where the command writes a file, and a file where the command writes a folder.
 - The result is one JSON object on one line. A file that the script writes shows as `{"out", "bytes", "sha256"}`. A list shows as `{"count", "listed"}`, and `rest` tells where to get the rest of a long list.
 - An error is `{"error": {"code": "...", "message": "..."}}`. The message tells what is wrong and what to do.
 - The exit status is 0 for done or PASS, 1 for FAIL, 2 for an error and 3 for INCONCLUSIVE.

package/skills/c64-memory-map/scripts/memory-map.ts

@@ -3,6 +3,7 @@
 // writes the platform names to a project file as an ACME include.
 
 import { formatC64Address, formatC64Byte } from "#src/c64.ts";
+import { isRefusal, Refusal } from "#src/errors.ts";
 import { writeReported } from "#src/host-client/transfer.ts";
 import { knowledgeNames } from "#src/knowledge/names.ts";
 import { decode, IO, lookup, platformNames, ROM, SYSTEM, type Entry } from "#src/platform.ts";
@@ -10,6 +11,24 @@ import { listed, OPTIONS, runScript, UsageError } from "#src/script.ts";
 
 const show = (entry: Entry) => ({ start: formatC64Address(entry.start), ...(entry.end !== entry.start ? { end: formatC64Address(entry.end) } : {}), name: entry.name, meaning: entry.meaning });
 
+/** The platform names by name in upper case: memory-map knows them also outside a project. */
+const PLATFORM = new Map(platformNames().map((entry) => [entry.name.toUpperCase(), entry.address]));
+
+/**
+ * The address of a name: a platform name (a register, a KERNAL or BASIC entry,
+ * a system variable) in any letter case first, else a name of the knowledge.
+ */
+function names(name: string, space: string): number {
+  const platform = PLATFORM.get(name.toUpperCase());
+  if (platform !== undefined) return platform;
+  try {
+    return knowledgeNames(name, space);
+  } catch (error) {
+    if (!isRefusal(error) || error.code !== "not-found") throw error;
+    throw new Refusal("not-found", `${name} is not a C64 platform name and not a name in the knowledge. Give a $ address, a platform name that memory-map.ts list or export shows (for example SCROLY or CHROUT), or a name that knowledge.ts symbols lists.`);
+  }
+}
+
 const LISTS: Record<string, () => Entry[]> = {
   vic: () => IO[0]!.registers,
   sid: () => IO[1]!.registers,
@@ -22,12 +41,12 @@ const LISTS: Record<string, () => Entry[]> = {
 await runScript({
   name: "memory-map",
   summary: "The platform meaning of C64 addresses and of values in platform registers.",
-  names: knowledgeNames,
+  names,
   commands: [
     {
       name: "at",
       summary: "The platform meaning of each address: its name, area and meaning.",
-      subjects: [{ name: "<address>", help: "an address or a name of the knowledge", list: true }],
+      subjects: [{ name: "<address>", help: "an address, a platform name such as SCROLY, or a name of the knowledge", list: true }],
       run: (call) => ({
         addresses: call.subjects.map((text) => {
           const found = lookup(call.parseAddress(text, "<address>"));
@@ -47,7 +66,7 @@ await runScript({
       name: "decode",
       summary: "The meaning of a value in a platform register.",
       subjects: [
-        { name: "<register>", help: "the register: $0001, $d011, $d016, $d018, $d010, $d015-$d01f, $dc0d, $dd00 or $dd0d" },
+        { name: "<register>", help: "the register, as an address or a platform name: $0001, $d011 (SCROLY), $d016, $d018, $d010, $d015-$d01f, $dc0d, $dd00 or $dd0d" },
         { name: "<value>", help: "the value of the register: $ and hex, decimal, or % and binary, 0 to 255" },
       ],
       options: { bank: { kind: "number", value: "<value>", help: "the value of $dd00, for the VIC-II bank of a $d018 value", max: 0xff } },
@@ -71,7 +90,7 @@ await runScript({
     {
       name: "export",
       summary: "Writes the platform names as an ACME include: NAME = $xxxx.",
-      options: { out: { ...OPTIONS.out, value: "<file>", help: "the include file, relative to the project folder", required: true } },
+      options: { out: { ...OPTIONS.out, output: "file", value: "<file>", help: "the include file, relative to the project folder", required: true } },
       run: (call) => {
         const names = platformNames();
         const lines = ["; C64 platform names from the c64-memory-map skill, for ACME.", ...names.map((item) => `${item.name} = ${item.address < 0x100 ? formatC64Byte(item.address) : formatC64Address(item.address)}`.padEnd(24) + `; ${item.meaning}`)];

package/skills/c64-provenance/SKILL.md

@@ -56,6 +56,7 @@ With `--frames`, a PRG starts with autostart and RUN. An image starts from its b
 - An address is `$` and 1 to 4 hex digits, for example `'$c000'` or `'$fb'`, or a name. A name is a symbol, else an analyzer name that only one analyzer gives. Quote an address in a shell.
 - A range is `<start>-<end>`, for example `'$c000-$cfff'`. In a JSON file, a range is `start` and `end`.
 - Bytes in a JSON file are hex in a field `data`, for example `"data": "a900"`.
+- The script examines each `--out` path before it starts work. It refuses a path in `.c64-re-tools/knowledge/` and the index of the knowledge, because only c64-knowledge writes them. It refuses a folder where the command writes a file, and a file where the command writes a folder.
 - The result is one JSON object on one line. A file that the script writes shows as `{"out", "bytes", "sha256"}`. A list shows as `{"count", "listed"}`, and `rest` tells where to get the rest of a long list.
 - An error is `{"error": {"code": "...", "message": "..."}}`. The message tells what is wrong and what to do.
 - The exit status is 0 for done or PASS, 1 for FAIL, 2 for an error and 3 for INCONCLUSIVE.
@@ -96,7 +97,8 @@ Use `separate` when you have only one release. It reads the program, its stages
 - `ranges`: the program in ranges with the same stage and access. `stage` is the last unpack stage that wrote the range. The last stage is the program. An earlier stage is a depacker, an intro or a loader. Only a capture of c64-unpacker `capture` has stages. For a program from `loads` or a PRG, `noStages` tells this.
 - `access`: from the coverage of the knowledge: `executed`, `read`, `written`, `read-written` or `untouched`. `untouched` bytes did not take part in the runs. A `read` byte right after executed code, or at a return address, can be a dummy read of the 6502 that the program does not use.
 - `codeRegions.total`: the number of code regions in the knowledge.
-- `codeRegions.unreachable`: code regions of the knowledge that no chain of call and jump references reaches from the entry. A region also reaches the code after it when its last instruction is not RTS, RTI, JMP, BRK or JAM: the CPU continues there. Run c64-static-analysis first, so that the knowledge has the code regions and the references.
+- `roots`: the addresses where the reachability starts. They are the entry, and the NMI, RESET and IRQ vectors at `$FFFA`-`$FFFF` when the image holds them. An interrupt handler starts from its vector, because no call or jump goes to it. `from` tells the source of each root.
+- `codeRegions.unreachable`: code regions of the knowledge that no chain of call and jump references reaches from a root. A region also reaches the code after it when its last instruction is not RTS, RTI, JMP, BRK or JAM: the CPU continues there. Run c64-static-analysis first, so that the knowledge has the code regions and the references.
 - `outside`: RAM outside the program that the program `read` or `executed` but did not write, and code it `generated`. A loader or an earlier stage put the bytes that the program did not write. A `generated` range can have gaps of two bytes or less: these are operand bytes.
 
 Each list has `count` and `listed`. `listed` has the first ranges, at most `--max-listed` (default 50). `--out` writes all of them and the result shows the file as `{out, bytes, sha256}`. Run more coverage runs for parts that are `untouched`, and add them with `coverage` of the c64-knowledge skill, before you decide.
@@ -112,7 +114,7 @@ Use `leftovers` to find what the program holds in addition to its working code.
 | `fill` | One byte that repeats, at least 16 times, or a pattern of two to four bytes that repeats, at least 32 bytes in total. `pattern` is the repeated bytes. |
 | `residue` | Bytes that no run touched and that are no text, BASIC, fill or code region. `bytes` shows the first 16 bytes. |
 | `copies` | Bytes that are the same as earlier bytes of the program, at least 32 bytes. `copyOf` is the address of the earlier bytes. |
-| `deadCode` | Code regions of the knowledge that the entry does not reach, as in `codeRegions.unreachable` of `separate`, and that no run executed. |
+| `deadCode` | Code regions of the knowledge that no root reaches, as in `codeRegions.unreachable` of `separate`, and that no run executed. |
 
 Text from another computer can show the tools of the developer:
 
@@ -193,7 +195,7 @@ Record a confirmed conclusion as a normal comment, region or symbol with the c64
 
 The differing ranges with the bytes of each release and the groups that agree, and the share of identical bytes. `common` gives the ranges where all releases have bytes. `releases` gives the segments and the `shift` of each release. With `--frames`, each difference also has `runtime`, and `run` tells if each release started, or why not.
 
-For `leftovers`: the lists of findings, with `entry` and the number of `stages`. `noEntry`, `noStages` and `noCoverage` tell which knowledge is missing.
+For `leftovers`: the lists of findings, with `entry`, `roots` and the number of `stages`. `noStages` and `noCoverage` tell which knowledge is missing. Without a root, `roots` tells why `deadCode` is empty.
 
 The runtime evidence and the leftovers are evidence only. The script does not decide which bytes are original.
 

package/skills/c64-provenance/scripts/lib/library.ts

@@ -5,8 +5,8 @@
 // suggests its names there as an apply batch. Nothing here writes knowledge.
 
 import { createHash } from "node:crypto";
-import { mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
-import { join, relative, resolve, sep } from "node:path";
+import { mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
 
 import { Refusal } from "#src/errors.ts";
 import { writeRefusal, type Written } from "#src/host-client/transfer.ts";
@@ -14,7 +14,7 @@ import { formatC64Address, instructionLength } from "#src/c64.ts";
 import { evaluate, identifiers, operandText } from "#src/knowledge/expression.ts";
 import type { CommentRow, OperandRow, ReferenceRow, RegionRow, SymbolRow } from "#src/knowledge/read.ts";
 import { COMMENT_PLACEMENTS, type CommentPlacement, isSemantic, OPERAND_SELECTS, type OperandSelect, REFERENCE_KINDS, type ReferenceKind, REGION_TYPES, type RegionType, SYMBOL_KINDS, type SymbolKind } from "#src/knowledge/schema.ts";
-import { PROJECT_DIRECTORY } from "#src/project.ts";
+import { checkOutputPath, isInside, PROJECT_DIRECTORY } from "#src/project.ts";
 
 /** A routine shorter than this is not saved and not searched: its bytes occur by chance. */
 export const MIN_ROUTINE = 16;
@@ -291,14 +291,37 @@ export function parseRoutine(text: string, file: string): Routine {
   };
 }
 
+/**
+ * Refuses a library folder to write that is inside the project `root`, also
+ * through a symbolic link, when the output check of every script refuses it
+ * (checkOutputPath): for example a folder in the knowledge. A folder outside
+ * the project gets no check.
+ */
+function checkLibraryOutput(path: string, root: string): void {
+  let existing = path;
+  while (statSync(existing, { throwIfNoEntry: false }) === undefined && dirname(existing) !== existing) existing = dirname(existing);
+  const real = join(realpathSync(existing), relative(existing, path));
+  const realRoot = realpathSync(root);
+  for (const [base, target] of [[root, path], [realRoot, real]] as const) {
+    if (isInside(base, target)) {
+      // A project path shows with "/" on every system, as the messages give it.
+      checkOutputPath(relative(base, target).split(sep).join("/") || ".", "folder", { root: base, what: "--library" });
+      return;
+    }
+  }
+}
+
 /**
  * The library folder that --library names, relative to the working directory
  * like --project (D71). A library is a plain folder, never a project. With
- * `create`, a missing folder is made.
+ * `create`, a missing folder is made; a folder inside the project must pass
+ * the output check of every script, which refuses the knowledge.
  */
 export function libraryFolder(folder: string, options: { create: boolean; cwd?: string }): string {
   if (folder.length === 0) throw new Refusal("invalid-input", "The library folder must not be empty.");
-  const path = resolve(options.cwd ?? process.cwd(), folder);
+  const root = options.cwd ?? process.cwd();
+  const path = resolve(root, folder);
+  if (options.create) checkLibraryOutput(path, root);
   const stat = statSync(path, { throwIfNoEntry: false });
   if (stat === undefined) {
     if (!options.create) throw new Refusal("not-found", `There is no library folder ${folder}. Save a routine to it first with routine.`);

package/skills/c64-provenance/scripts/lib/separate.ts

@@ -1,7 +1,8 @@
 // Evidence from one release: for each range of the image, the unpack
 // stage that wrote it and the access class from coverage; for each code
 // region of knowledge, whether call and jump references or the run on from
-// its last instruction reach it from the entry; and what the program reads
+// its last instruction reach it from a root (the entry, and the NMI, RESET
+// and IRQ vectors at $fffa-$ffff when the image holds them); and what the program reads
 // or executes outside the image. Evidence only: nothing here decides what is
 // original.
 
@@ -30,13 +31,21 @@ export interface EvidenceRange extends AddressRange {
 
 export interface CodeRegionEvidence extends AddressRange {
   type: string;
-  /** Absent when the image has no entry. */
+  /** Absent when the image has no root: no entry and no hardware vector. */
   reachable?: boolean;
   /** Absent without coverage. */
   executed?: boolean;
 }
 
+/** An address where the reachability starts, and why: the entry, or a hardware vector in the image. */
+export interface Root {
+  address: number;
+  from: "entry" | "NMI vector $fffa" | "RESET vector $fffc" | "IRQ vector $fffe";
+}
+
 export interface Separation {
+  /** The roots of the reachability, in the order entry, NMI, RESET, IRQ. */
+  roots: Root[];
   ranges: EvidenceRange[];
   codeRegions: CodeRegionEvidence[];
   /**
@@ -50,6 +59,24 @@ export interface Separation {
 
 const SYSTEM_PAGES_END = 0x03ff;
 
+/** The hardware vectors of the 6510: the CPU reads them from $fffa-$ffff, the RAM when the KERNAL is banked out. */
+const HARDWARE_VECTORS = [
+  { at: 0xfffa, from: "NMI vector $fffa" },
+  { at: 0xfffc, from: "RESET vector $fffc" },
+  { at: 0xfffe, from: "IRQ vector $fffe" },
+] as const;
+
+/**
+ * The roots of the reachability: the entry, and each hardware vector whose
+ * two bytes are in the image. An interrupt handler runs by its vector, and
+ * no call or jump reference reaches it.
+ */
+export function reachabilityRoots(segments: readonly AddressRange[], memory: Uint8Array, entry?: number): Root[] {
+  const inImage = (address: number) => segments.some((segment) => address >= segment.start && address <= segment.end);
+  const vectors = HARDWARE_VECTORS.filter((vector) => inImage(vector.at) && inImage(vector.at + 1)).map((vector): Root => ({ address: memory[vector.at]! | (memory[vector.at + 1]! << 8), from: vector.from }));
+  return [...(entry === undefined ? [] : [{ address: entry, from: "entry" as const }]), ...vectors];
+}
+
 /** BRK, JMP, RTI, RTS, JMP (indirect) and the JAM opcodes: the CPU does not run on to the next instruction after them. */
 const NO_FALL_THROUGH = new Set([0x00, 0x4c, 0x40, 0x60, 0x6c, 0x02, 0x12, 0x22, 0x32, 0x42, 0x52, 0x62, 0x72, 0x92, 0xb2, 0xd2, 0xf2]);
 
@@ -114,12 +141,13 @@ export function separate(input: SeparationInput): Separation {
     }
   }
 
-  // Reachability: from the region that holds the entry, through call and jump references and the run on
+  // Reachability: from the regions that hold a root, through call and jump references and the run on
   // from the last instruction of a region into the next address, to a fixed point.
   const regions = input.codeRegions.filter((region) => input.segments.some((segment) => region.start <= segment.end && segment.start <= region.end));
   const holding = (address: number) => regions.findIndex((region) => address >= region.start && address <= region.end);
+  const roots = reachabilityRoots(input.segments, input.memory, input.entry);
   const reached = new Set<number>();
-  if (input.entry !== undefined && holding(input.entry) >= 0) reached.add(holding(input.entry));
+  for (const root of roots) if (holding(root.address) >= 0) reached.add(holding(root.address));
   // The CPU runs the bytes after the region as instructions: through bytes of no code region (a dual-use
   // instruction, for example) into the next code region, unless one of them does not run on.
   const runOn = (from: number): number | undefined => {
@@ -154,7 +182,7 @@ export function separate(input: SeparationInput): Separation {
       ran = false;
       for (let address = region.start; address <= region.end && !ran; address++) ran = executed[address] === 1;
     }
-    return { start: region.start, end: region.end, type: region.type, ...(input.entry === undefined ? {} : { reachable: reached.has(index) }), ...(ran === undefined ? {} : { executed: ran }) };
+    return { start: region.start, end: region.end, type: region.type, ...(roots.length === 0 ? {} : { reachable: reached.has(index) }), ...(ran === undefined ? {} : { executed: ran }) };
   });
 
   const read: number[] = [];
@@ -174,5 +202,5 @@ export function separate(input: SeparationInput): Separation {
     for (let address = from + 1; address < to; address++) if (inImage(address)) return false;
     return true;
   };
-  return { ranges, codeRegions, outside: { read: merge(read), executed: merge(ranOutside), generated: merge(generated, 2, outsideImage) } };
+  return { roots, ranges, codeRegions, outside: { read: merge(read), executed: merge(ranOutside), generated: merge(generated, 2, outsideImage) } };
 }

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

@@ -41,13 +41,13 @@ import {
 import { CODE_REGION_TYPES, SEMANTIC_ORIGINS } from "#src/knowledge/schema.ts";
 import { platformNames } from "#src/platform.ts";
 import { projectRoot } from "#src/project.ts";
-import { knowledgeNames } from "#src/knowledge/names.ts";
+import { knowledgeAt, knowledgeNames } from "#src/knowledge/names.ts";
 import { listed, OPTIONS, runScript, UsageError, type Call, type CommandSpec } from "#src/script.ts";
 import { compareReleases, shiftSuggestion, suggestShifts, type Release } from "./lib/compare.ts";
 import { findRoutine, libraryFolder, readLibrary, routineFrom, saveRoutine, suggest } from "./lib/library.ts";
 import { watchRelease, type Start } from "./lib/runtime.ts";
 import { findLeftovers } from "./lib/leftovers.ts";
-import { separate } from "./lib/separate.ts";
+import { separate, type Root } from "./lib/separate.ts";
 
 const hexBytes = (bytes: number[]) => Buffer.from(bytes).toString("hex").replace(/(..)(?!$)/g, "$1 ");
 
@@ -107,14 +107,17 @@ async function compare(call: Call): Promise<unknown> {
   const shifts = new Map<number, number>();
   for (const text of call.strings("shift")) {
     const match = /^(\d+):([+-]?\d+)$/.exec(text);
-    if (match === null || Number(match[1]) < 1 || Number(match[1]) > positionals.length) throw new UsageError(`--shift must be <release number>:<bytes>, not ${text}`);
+    if (match === null) throw new UsageError(`--shift must be <release number>:<bytes>, for example 2:-256, not ${text}`);
+    if (Number(match[1]) < 1 || Number(match[1]) > positionals.length) {
+      throw new UsageError(`--shift ${text}: there is no release ${match[1]}. This compare has ${positionals.length} releases: give a release number from 1 to ${positionals.length}`);
+    }
     if (shifts.has(Number(match[1]))) throw new UsageError(`--shift gives release ${match[1]} more than one shift (${shifts.get(Number(match[1]))} and ${match[2]}). Give one --shift for each release`);
     shifts.set(Number(match[1]), Number(match[2]));
   }
   const frames = call.count("frames");
   const stepsFile = call.string("steps");
   if (stepsFile !== undefined && frames === undefined) throw new UsageError("--steps works only with --frames");
-  const steps: ActionStep[] = stepsFile === undefined ? [] : readActionSteps(stepsFile, "--steps");
+  const steps: ActionStep[] = stepsFile === undefined ? [] : readActionSteps(stepsFile, "--steps", knowledgeAt());
   const loaded = positionals.map((path, index) => readRelease(path, shifts.get(index + 1) ?? 0));
   const releases = loaded.map((item) => item.release);
   const range = call.range("range");
@@ -236,6 +239,11 @@ function programEvidence() {
   return { program, stages, coverage, found };
 }
 
+/** The roots of the reachability as a person reads them. */
+const showRoots = (roots: readonly Root[]) => roots.map((root) => ({ address: formatC64Address(root.address), from: root.from }));
+
+const NO_ROOTS = "none: the program in the knowledge has no entry, and the image does not hold the hardware vectors at $fffa-$ffff, so no code region is reachable or unreachable.";
+
 const NO_STAGES = "The program in the knowledge has no stage log. Only a capture of c64-unpacker gives one. A capture of loads holds one part of a program and has none.";
 
 /** separate: evidence from the program in the knowledge, with all ranges in --out and the first ones in the result. */
@@ -248,7 +256,8 @@ function separateCommand(call: Call): unknown {
   const ranges = found.ranges.map((range) => ({ ...show(range), ...(range.stage === undefined ? {} : { stage: range.stage }), ...(range.access === undefined ? {} : { access: range.access }) }));
   const codeRegions = found.codeRegions.map((region) => ({ ...show(region), type: region.type, ...(region.reachable === undefined ? {} : { reachable: region.reachable }), ...(region.executed === undefined ? {} : { executed: region.executed }) }));
   const outside = { read: found.outside.read.map(show), executed: found.outside.executed.map(show), generated: found.outside.generated.map(show) };
-  const written = out === undefined ? undefined : writeReported(out, `${JSON.stringify({ ranges, codeRegions, outside }, null, 1)}\n`, { what: "--out" });
+  const roots = showRoots(found.roots);
+  const written = out === undefined ? undefined : writeReported(out, `${JSON.stringify({ roots, ranges, codeRegions, outside }, null, 1)}\n`, { what: "--out" });
   const rest = out === undefined ? undefined : out;
   const list = <T>(items: T[]) => listed(items, max, undefined, rest);
   const bytes = (filter: (range: (typeof found.ranges)[number]) => boolean) => found.ranges.filter(filter).reduce((sum, range) => sum + range.end - range.start + 1, 0);
@@ -263,10 +272,12 @@ function separateCommand(call: Call): unknown {
         }),
     ...(coverage === undefined ? {} : { bytesByAccess: Object.fromEntries((["executed", "read", "written", "read-written", "untouched"] as const).map((access) => [access, bytes((range) => range.access === access)])) }),
     ranges: list(ranges),
+    // The roots of the reachability: the entry and the hardware vectors in the image.
+    roots: roots.length === 0 ? NO_ROOTS : roots,
     // total counts every code region; unreachable is a list like the others.
     codeRegions: {
       total: codeRegions.length,
-      ...(loaded.entry === undefined ? {} : { unreachable: list(codeRegions.filter((region) => region.reachable === false)) }),
+      ...(roots.length === 0 ? {} : { unreachable: list(codeRegions.filter((region) => region.reachable === false)) }),
     },
     ...(coverage === undefined ? {} : { outside: { read: list(outside.read), executed: list(outside.executed), generated: list(outside.generated) } }),
     ...(written === undefined ? {} : written),
@@ -307,7 +318,8 @@ function leftoversCommand(call: Call): unknown {
   const written = out === undefined ? undefined : writeReported(out, `${JSON.stringify(all, null, 1)}\n`, { what: "--out" });
   const list = <T>(items: T[]) => listed(items, max, undefined, out ?? "a larger --max-listed, or --out <file>");
   return {
-    ...(program.entry === undefined ? { noEntry: "The program in the knowledge has no entry, so deadCode is empty." } : { entry: formatC64Address(program.entry) }),
+    ...(program.entry === undefined ? {} : { entry: formatC64Address(program.entry) }),
+    roots: found.roots.length === 0 ? NO_ROOTS : showRoots(found.roots),
     ...(stages === undefined ? { noStages: NO_STAGES } : { stages: stages.length }),
     ...(coverage === undefined ? { noCoverage: "The knowledge has no coverage, so residue is empty and no finding has access. Add coverage with coverage of the c64-knowledge skill." } : {}),
     text: list(all.text.map((item) => (item.text.length > SHOWN_TEXT ? { ...item, text: `${item.text.slice(0, SHOWN_TEXT)} ...`, length: item.text.length } : item))),
@@ -462,14 +474,14 @@ const COMMANDS: CommandSpec[] = [
   {
     name: "separate",
     summary: "Evidence from the program in the knowledge: the unpack stage that wrote each range, its access in the coverage, whether call and jump references, or the run on from the code before it, reach each code region from the entry, and what the program reads or executes outside its segments.",
-    options: { out: { ...OPTIONS.out, value: "<file>", help: "write all ranges to this file" }, "max-listed": OPTIONS["max-listed"] },
+    options: { out: { ...OPTIONS.out, output: "file", value: "<file>", help: "write all ranges to this file" }, "max-listed": OPTIONS["max-listed"] },
     run: separateCommand,
   },
   {
     name: "leftovers",
     summary: "What the program in the knowledge holds besides its working code: texts in PETSCII, screen codes, ASCII or with bit 7 set (Apple II), assembler source, BASIC lines away from the BASIC start, fills, untouched bytes outside code, copies of earlier bytes, and code regions that nothing reaches and no run executed.",
     options: {
-      out: { ...OPTIONS.out, value: "<file>", help: "write all findings to this file" },
+      out: { ...OPTIONS.out, output: "file", value: "<file>", help: "write all findings to this file" },
       "min-text": { kind: "count", value: "<n>", min: 4, max: 999, default: 8, help: "the shortest text to find (default 8)" },
       "max-listed": OPTIONS["max-listed"],
     },
@@ -492,7 +504,7 @@ const COMMANDS: CommandSpec[] = [
     summary: "Finds each routine of the library in the program of the knowledge: the opcodes and other fixed bytes equal, and the addresses into the routine moved by one shift.",
     options: {
       library: { ...LIBRARY, help: "the library folder, relative to the project folder, for example ../library" },
-      out: { ...OPTIONS.out, value: "<file>", help: "write the names of the routines at the found addresses as a batch for knowledge.ts apply" },
+      out: { ...OPTIONS.out, output: "file", value: "<file>", help: "write the names of the routines at the found addresses as a batch for knowledge.ts apply" },
       "max-listed": OPTIONS["max-listed"],
     },
     run: matchCommand,

package/skills/c64-source/SKILL.md

@@ -47,6 +47,7 @@ When the knowledge has coverage, code that no run executed gets the line `; not
 - An address is `$` and 1 to 4 hex digits, for example `'$c000'` or `'$fb'`, or a name. A name is a symbol, else an analyzer name that only one analyzer gives. Quote an address in a shell.
 - A range is `<start>-<end>`, for example `'$c000-$cfff'`. In a JSON file, a range is `start` and `end`.
 - Bytes in a JSON file are hex in a field `data`, for example `"data": "a900"`.
+- The script examines each `--out` path before it starts work. It refuses a path in `.c64-re-tools/knowledge/` and the index of the knowledge, because only c64-knowledge writes them. It refuses a folder where the command writes a file, and a file where the command writes a folder.
 - The result is one JSON object on one line. A file that the script writes shows as `{"out", "bytes", "sha256"}`. A list shows as `{"count", "listed"}`, and `rest` tells where to get the rest of a long list.
 - An error is `{"error": {"code": "...", "message": "..."}}`. The message tells what is wrong and what to do.
 - The exit status is 0 for done or PASS, 1 for FAIL, 2 for an error and 3 for INCONCLUSIVE.
@@ -79,7 +80,7 @@ When the knowledge has coverage, code that no run executed gets the line `; not
 - `constants.asm` holds the names of addresses outside the program, for example `EXTCOL = $d020`. The file puts the names in groups by memory area, for example zero page, VIC-II registers or CIA 1 registers. Each group is in address order. Drive code and banks have one group only. The side comment of a name tells what the address is. This text is the knowledge comment of the address. Without a comment, the text is the platform meaning. When the knowledge name is not the platform name, the platform name comes first. For an I/O mirror without a meaning, the text gives the register that the mirror repeats. Then `Used:` counts how the source uses the name. The kinds are `read`, `written`, `modified`, `called`, `jumped to`, `jumped through`, `branched to`, `pointer`, `address`, `table` and `macro argument`. `address` is an immediate operand expression. `table` is an entry in a table of addresses.
 - The top of `constants.asm` sets each switch to 0, for example `!ifndef CRACK { CRACK = 0 }`. A build that defines the switch as 1 uses the patches of that switch.
 - A label or a constant gets the name of the address in the knowledge. Without a knowledge name, it gets the platform name of the c64-memory-map skill, for example `EXTCOL` or `CHROUT`. A platform name wins over a name from an analyzer (`dxa`, `ghidra` or `heuristic`), for example `EXTCOL` over `ld020`. A `user` or `llm` name wins over a platform name. An address in the program without a name gets `l_xxxx`.
-- The source uses the names of a ROM only when the program uses that ROM. When the knowledge has coverage, a ROM is in use when a run executed code of it. A read of ROM bytes as data does not count. Without coverage, `$01` of the entry state tells which ROMs are in. When the program uses neither ROM, the zero page and pages 2 and 3 get no system names. `romNamesLeftOut` gives the ROMs that the source did not name, and the evidence.
+- The source uses the names of a ROM only when the program uses that ROM. When the knowledge has coverage, a ROM is in use when a run executed code of it. A read of ROM bytes as data does not count. Without coverage, `$01` of the entry state tells which ROMs are in. When the program uses neither ROM, the zero page and pages 2 and 3 get no system names. `romNamesLeftOut` gives the ROMs that the source did not name, and the evidence. An operand expression or a macro use with such a name gets that reason.
 - `sta $d011  ; $d011: yScroll 3, rows 25, displayEnabled` is a store of an immediate to a register that the c64-memory-map skill decodes. The side comment gives the decoded value. A side comment in the knowledge replaces it.
 - Code regions, and the instructions that Ghidra decodes outside of data regions, become instructions.
 - Data regions become data by their type: `!byte`, `!word`, `!pet`, `!scr`, `!fill`, tables of labels, and sprite bytes in binary.

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

@@ -13,7 +13,7 @@ import { WireFailure } from "#src/host-client/tools.ts";
 import { identifiers, operandText, replaceIdentifiers, type OperandExpression } from "#src/knowledge/expression.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";
+import { hasZeroPageForm, instructionWith, labelProblem, MODE_LENGTH, OPCODES, takesAddress, USE_KINDS, useKind, type UseKind } from "#src/opcodes.ts";
 
 export interface SourceInput {
   /** In address order, without overlap. */
@@ -34,6 +34,8 @@ export interface SourceInput {
   coverage?: Uint8Array;
   /** Platform names: 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 names that `platform` leaves out, because the program does not use their ROM: the reason of an expression that names one tells it. */
+  platformLeftOut?: ReadonlySet<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 };
   /** What a value in a platform register means (c64-memory-map): an immediate stored to such a register gets it as a side comment. Throws for a register without a decoder. */
@@ -319,7 +321,7 @@ export function layout(input: SourceInput): Layout {
   const outside = new Set<number>();
   // A platform name that knowledge gives to another address, or that reads as an instruction, is not used.
   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]));
+  const platform = new Map((input.platform ?? []).filter(({ name }) => !knowledgeNames.has(name) && labelProblem(name) === undefined).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 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. */
@@ -355,6 +357,17 @@ 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] : []))));
+  /** Why names of an expression are not names of the source: not known, or platform names of a ROM that the program does not use. */
+  const unknownNames = (missing: readonly string[], remedy: string) => {
+    const leftOut = missing.filter((name) => input.platformLeftOut?.has(name) === true);
+    const unknown = missing.filter((name) => !leftOut.includes(name));
+    const are = (names: readonly string[]) => `${names.join(", ")} ${names.length === 1 ? "is" : "are"}`;
+    return [
+      ...(unknown.length === 0 ? [] : [`${are(unknown)} not a symbol of the knowledge or a platform name.`]),
+      ...(leftOut.length === 0 ? [] : [`${are(leftOut)} a platform name of a ROM that the program does not use, so the source leaves ${leftOut.length === 1 ? "it" : "them"} out (romNamesLeftOut).`]),
+      remedy,
+    ].join(" ");
+  };
   // 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.
   const macrosByName = new Map((input.macros ?? []).map((macro) => [macro.name, macro]));
   const macrosAsInstructions: MacroAsInstructions[] = [];
@@ -384,7 +397,7 @@ export function layout(input: SourceInput): Layout {
     }
     const missing = [...new Set(use.args.flatMap((arg) => identifiers(arg)))].filter((name) => !byName.has(name));
     if (missing.length > 0) {
-      fallBack(`${missing.join(", ")} ${missing.length === 1 ? "is" : "are"} not a symbol of the knowledge or a platform name. Name the address with knowledge.ts rename, or give other args with knowledge.ts use.`);
+      fallBack(unknownNames(missing, "Name the address with knowledge.ts rename, or give other args with knowledge.ts use."));
       continue;
     }
     candidates.push({ use, items: run as InstructionItem[] });
@@ -403,7 +416,7 @@ export function layout(input: SourceInput): Layout {
     }
     const missing = identifiers(expression).filter((name) => !byName.has(name));
     if (missing.length > 0) {
-      operandsAsNumbers.push({ address: operand.address, expression, reason: `${missing.join(", ")} ${missing.length === 1 ? "is" : "are"} not a symbol of the knowledge or a platform name. Name the address with knowledge.ts rename, or write the operand again with knowledge.ts operand.` });
+      operandsAsNumbers.push({ address: operand.address, expression, reason: unknownNames(missing, "Name the address with knowledge.ts rename, or write the operand again with knowledge.ts operand.") });
       continue;
     }
     // An immediate operand builds the address of a name; any other operand uses the address as the instruction does.
@@ -450,7 +463,8 @@ 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 ${formatC64Address(address)} has the name of an instruction, which ACME cannot read as a label. Rename the symbol with c64-knowledge.`);
+      const problem = labelProblem(known);
+      if (problem !== undefined) throw new WireFailure("invalid-input", `The symbol ${known} at ${formatC64Address(address)}: ${problem} Rename the symbol with c64-knowledge.`);
       names.set(address, known);
       if (inImage(address)) namedLabels++;
       continue;
@@ -574,27 +588,6 @@ export function formOf(layout: Pick<Layout, "inImage" | "byteAt">, item: Instruc
   return { key: `${item.opcode.toString(16).padStart(2, "0")}${suffix}`, opcode: item.opcode, suffix };
 }
 
-/** The instruction text with an operand expression; the expression is a name or a $ number. */
-export function instructionText(opcode: number, suffix: string, expression: string): string {
-  const { mnemonic, mode } = OPCODES[opcode]!;
-  const operand: Record<Mode, string> = {
-    imp: "",
-    imm: `#${expression}`,
-    zp: expression,
-    zpx: `${expression},x`,
-    zpy: `${expression},y`,
-    abs: expression,
-    abx: `${expression},x`,
-    aby: `${expression},y`,
-    ind: `(${expression})`,
-    izx: `(${expression},x)`,
-    izy: `(${expression}),y`,
-    rel: expression,
-  };
-  const text = operand[mode];
-  return text === "" ? `${mnemonic}${suffix}` : `${mnemonic}${suffix} ${text}`;
-}
-
 /** 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]!;
@@ -1040,13 +1033,14 @@ export function render(layout: Layout, asBytes: ReadonlySet<string>, header: str
             out.push(`${label} = * + ${offset}`);
             result.labels.push({ address: inside, name: label, file: piece.file, line: out.length });
           }
-          for (const text of lineComments.get(inside) ?? []) sides.push(text);
-          if (sideComments.has(inside)) sides.push(sideComments.get(inside)!);
+          // A comment at an operand byte (knowledge of an older version) shows with its address, as in the listing of c64-knowledge.
+          for (const text of lineComments.get(inside) ?? []) sides.push(`${formatC64Address(inside)}: ${text}`);
+          if (sideComments.has(inside)) sides.push(`${formatC64Address(inside)}: ${sideComments.get(inside)!}`);
         }
         const form = formOf(layout, item);
         const { mode } = OPCODES[item.opcode]!;
         const value = mode === "imp" ? 0 : operandValue(item.address, item.opcode, layout.byteAt)!;
-        const literal = instructionText(item.opcode, "", literalOperand(item.opcode, value));
+        const literal = instructionWith(item.opcode, literalOperand(item.opcode, value));
         let written = layout.operands.get(item.address);
         // An expression that is not written stays visible as a side comment.
         const asNumber = (expression: string, reason: string) => {
@@ -1062,13 +1056,11 @@ export function render(layout: Layout, asBytes: ReadonlySet<string>, header: str
           out.push(withSide(`${INDENT}!byte ${bytes.join(",")}`, [literal, ...sides].join(" ")));
           result.asBytes.push({ address: item.address, text: literal });
         } else if (written !== undefined) {
-          // ACME reads an operand in brackets as indirect, so a non-immediate expression does not start with one.
-          const expression = mode !== "imm" && written.startsWith("(") ? `0+${written}` : written;
-          out.push(withSide(`${INDENT}${instructionText(item.opcode, form.suffix, expression)}`, sides.length === 0 ? undefined : sides.join(" ")));
+          out.push(withSide(`${INDENT}${instructionWith(item.opcode, written, form.suffix)}`, sides.length === 0 ? undefined : sides.join(" ")));
           result.expressions.push({ address: item.address, length: item.length, file: piece.file, line: out.length });
         } else {
           const expression = takesAddress(mode) ? (layout.names.get(value) ?? literalOperand(item.opcode, value)) : literalOperand(item.opcode, value);
-          out.push(withSide(`${INDENT}${instructionText(item.opcode, form.suffix, expression)}`, sides.length === 0 ? undefined : sides.join(" ")));
+          out.push(withSide(`${INDENT}${instructionWith(item.opcode, expression, form.suffix)}`, sides.length === 0 ? undefined : sides.join(" ")));
         }
         mapLine(item.address, item.address + item.length - 1);
         result.instructions++;