@henols/c64-re-tools 2.1.0 → 2.1.2

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

@@ -17,11 +17,12 @@ import { operandText } from "#src/knowledge/expression.ts";
 import { historyAt, historyNamed, historyOfMacro, revision, revisionNote, revisions, type HistoryEntry } from "#src/knowledge/history.ts";
 import { joinBatches, type Batch, type JoinChoice, type JoinClash } from "#src/knowledge/join.ts";
 import { knowledgeNames } from "#src/knowledge/names.ts";
-import { addCoverage, coverageRuns, programCoverage, programImage, requireProgram, setImage, type ImageRequest } from "#src/knowledge/program.ts";
+import { addCoverage, programCoverage, programImage, requireProgram, setImage, type ImageRequest } from "#src/knowledge/program.ts";
 import {
   analyzerNamesAt,
   at,
   commentsAt,
+  coverageRuns,
   currentRevision,
   listAnalyzerNames,
   listComments,
@@ -83,7 +84,7 @@ import {
 } from "#src/knowledge/write.ts";
 import { platformNames } from "#src/platform.ts";
 import { isInside, LOCAL_DIRECTORY, PROJECT_DIRECTORY, projectRelative, projectRoot, resolveProjectPath } from "#src/project.ts";
-import { OPTIONS, runScript, UsageError, type Call, type CommandSpec, type OptionSpec, type SubjectSpec } from "#src/script.ts";
+import { listed, OPTIONS, runScript, UsageError, type Call, type CommandSpec, type OptionSpec, type SubjectSpec } from "#src/script.ts";
 import { listing, listingText, type ListingSource } from "./lib/listing.ts";
 
 function oneOf<T extends string>(values: readonly T[], value: string | undefined, what: string): T {
@@ -150,9 +151,18 @@ function suppression(row: SuppressionRow) {
   return { ...spaceOf(row), suppresses: row.entity, ...place, origin: row.origin, revision: row.revision };
 }
 
+/** A row of the program in a revision: memory bytes, the entry, or a coverage range. */
+function programRow(entry: Extract<HistoryEntry, { entity: "memory" | "entry" | "coverage" }>) {
+  if (entry.entity === "memory") return { ...spaceOf(entry.row), start: formatC64Address(entry.row.address), end: formatC64Address(entry.row.address + entry.row.bytes - 1), bytes: entry.row.bytes, origin: entry.row.origin, revision: entry.row.revision };
+  if (entry.entity === "entry") return { ...spaceOf(entry.row), address: formatC64Address(entry.row.address), state: entry.row.state, stages: entry.row.stages, origin: entry.row.origin, revision: entry.row.revision };
+  return { ...spaceOf(entry.row), kind: entry.row.kind, start: formatC64Address(entry.row.start), end: formatC64Address(entry.row.end), origin: entry.row.origin, revision: entry.row.revision };
+}
+
 function historyEntry(entry: HistoryEntry) {
   const shown =
-    entry.entity === "symbol" || entry.entity === "analyzer-name"
+    entry.entity === "memory" || entry.entity === "entry" || entry.entity === "coverage"
+      ? programRow(entry)
+      : entry.entity === "symbol" || entry.entity === "analyzer-name"
       ? symbol(entry.row)
       : entry.entity === "region"
         ? region(entry.row)
@@ -226,13 +236,17 @@ function listingSource(db: DatabaseSync | undefined, space: string): ListingSour
   };
 }
 
-/** --origin for reads: one origin, semantic (user and llm), analyzer (dxa and ghidra), or a comma list. */
+/** Every value of --origin, for the message of a wrong one. */
+const ORIGIN_VALUES = `one of ${ORIGINS.join(", ")}, semantic or analyzer, or a comma list of them. semantic is ${SEMANTIC_ORIGINS.join(" and ")}. analyzer is ${ANALYZERS.slice(0, -1).join(", ")} and ${ANALYZERS.at(-1)}`;
+
+/** --origin for reads: one origin, semantic (user and llm), analyzer (dxa, ghidra and heuristic), or a comma list. */
 function originFilter(value: string): Origin[] {
   const origins = new Set<Origin>();
   for (const part of value.split(",")) {
     if (part === "semantic") for (const origin of SEMANTIC_ORIGINS) origins.add(origin);
     else if (part === "analyzer") for (const origin of ANALYZERS) origins.add(origin);
-    else origins.add(oneOf(ORIGINS, part, "--origin"));
+    else if ((ORIGINS as readonly string[]).includes(part)) origins.add(part as Origin);
+    else throw new UsageError(`--origin cannot be ${JSON.stringify(part)}. Give ${ORIGIN_VALUES}`);
   }
   return [...origins];
 }
@@ -371,6 +385,20 @@ const WRITE: Record<string, OptionSpec> = {
   "expect-revision": OPTIONS["expect-revision"],
 };
 
+/** A list command: --max-listed limits each list of its result. */
+const LIST = { "max-listed": OPTIONS["max-listed"] };
+/** Where to get the rest of a list that a --range limits. */
+const RANGE_REST = "a larger --max-listed, a smaller --range, or knowledge.ts export --out <file> for all current knowledge";
+const MORE = "a larger --max-listed";
+
+/** A list in a result: its count and its first --max-listed items, with rest when it is cut. */
+function list<T, U>(call: Call, items: readonly T[], show: (item: T) => U, rest: string) {
+  return listed(items, call.count("max-listed")!, show, rest);
+}
+
+/** All rows: the lists count every row, and --max-listed limits only what the result shows. */
+const ALL = Number.MAX_SAFE_INTEGER;
+
 /** The rows from --range, or every address. */
 const rangeOf = (call: Call) => call.range("range") ?? { start: 0x0000, end: 0xffff };
 const originsOf = (call: Call) => {
@@ -401,7 +429,8 @@ function writeCommand(spec: Omit<CommandSpec, "run">, prepare: (call: Call) => W
   return {
     ...spec,
     notes: [spec.notes, "A write is one revision. It makes .c64-re-tools/knowledge/ when it is not there."].filter((note) => note !== undefined).join("\n"),
-    options: { ...spec.options, ...WRITE },
+    // A command can give a WRITE option its own help or default, for example --space of revert.
+    options: Object.fromEntries(Object.entries({ ...spec.options, ...WRITE }).map(([name, option]) => [name, spec.options?.[name] ?? option])),
     run: (call) => withWrite(prepare(call)),
   };
 }
@@ -459,50 +488,50 @@ const READ_COMMANDS: CommandSpec[] = [
       name: "search",
       summary: "Symbol names, analyzer names and comment texts that hold the text.",
       subjects: [{ name: "<text>", help: "the text to find" }],
-      options: { origin: OPTIONS.origin, limit: { kind: "count", value: "<n>", min: 1, max: 10_000, default: 50, help: "at most n rows of each kind (default 50)" } },
+      options: { origin: OPTIONS.origin, ...LIST },
     },
     (db, call) => {
-      const found = search(db, call.subject(0), call.count("limit")!, originsOf(call), call.space);
-      return { symbols: found.symbols.map(symbol), analyzerNames: found.analyzerNames.map(symbol), comments: found.comments.map(comment) };
+      const found = search(db, call.subject(0), ALL, originsOf(call), call.space);
+      const rest = "a larger --max-listed, or a longer <text>";
+      return { symbols: list(call, found.symbols, symbol, rest), analyzerNames: list(call, found.analyzerNames, symbol, rest), comments: list(call, found.comments, comment, rest) };
     },
   ),
   readCommand(
-    { name: "symbols", summary: "The symbols, or with --analyzer the second names that DXA, Ghidra and the idioms gave.", options: { ...FILTER, kind: SYMBOL_KIND, analyzer: { kind: "flag", help: "the analyzer names in place of the symbols" } } },
+    { name: "symbols", summary: "The symbols, or with --analyzer the second names that DXA, Ghidra and the idioms gave.", options: { ...FILTER, kind: SYMBOL_KIND, analyzer: { kind: "flag", help: "the analyzer names in place of the symbols" }, ...LIST } },
     (db, call) => {
       const kind = call.string("kind") as (typeof SYMBOL_KINDS)[number] | undefined;
-      if (call.flag("analyzer")) return { analyzerNames: listAnalyzerNames(db, rangeOf(call), kind, originsOf(call), call.space).map(symbol) };
-      return { symbols: listSymbols(db, rangeOf(call), kind, originsOf(call), call.space).map(symbol) };
+      if (call.flag("analyzer")) return { analyzerNames: list(call, listAnalyzerNames(db, rangeOf(call), kind, originsOf(call), call.space), symbol, RANGE_REST) };
+      return { symbols: list(call, listSymbols(db, rangeOf(call), kind, originsOf(call), call.space), symbol, RANGE_REST) };
     },
   ),
-  readCommand({ name: "regions", summary: "The regions: code, data, tables and the other types.", options: { ...FILTER, type: { kind: "choice", value: "<type>", choices: REGION_TYPES, help: `one of ${REGION_TYPES.join(", ")}` } } }, (db, call) => ({
-    regions: listRegions(db, rangeOf(call), call.string("type") as (typeof REGION_TYPES)[number] | undefined, originsOf(call), call.space).map(region),
+  readCommand({ name: "regions", summary: "The regions: code, data, tables and the other types.", options: { ...FILTER, type: { kind: "choice", value: "<type>", choices: REGION_TYPES, help: `one of ${REGION_TYPES.join(", ")}` }, ...LIST } }, (db, call) => ({
+    regions: list(call, listRegions(db, rangeOf(call), call.string("type") as (typeof REGION_TYPES)[number] | undefined, originsOf(call), call.space), region, RANGE_REST),
   })),
-  readCommand({ name: "comments", summary: "The comments.", options: FILTER }, (db, call) => ({ comments: listComments(db, rangeOf(call), originsOf(call), call.space).map(comment) })),
-  readCommand({ name: "references", summary: "The references: calls, jumps, reads, writes and pointers.", options: { ...FILTER, kind: REFERENCE_KIND } }, (db, call) => ({
-    references: listReferences(db, rangeOf(call), call.string("kind") as (typeof REFERENCE_KINDS)[number] | undefined, originsOf(call), call.space).map(reference),
+  readCommand({ name: "comments", summary: "The comments.", options: { ...FILTER, ...LIST } }, (db, call) => ({ comments: list(call, listComments(db, rangeOf(call), originsOf(call), call.space), comment, RANGE_REST) })),
+  readCommand({ name: "references", summary: "The references: calls, jumps, reads, writes and pointers.", options: { ...FILTER, kind: REFERENCE_KIND, ...LIST } }, (db, call) => ({
+    references: list(call, listReferences(db, rangeOf(call), call.string("kind") as (typeof REFERENCE_KINDS)[number] | undefined, originsOf(call), call.space), reference, RANGE_REST),
   })),
-  readCommand({ name: "suppressions", summary: "The places that removals keep free of analyzer facts, with the reason of each.", options: { range: OPTIONS.range } }, (db, call) => {
+  readCommand({ name: "suppressions", summary: "The places that removals keep free of analyzer facts, with the reason of each.", options: { range: OPTIONS.range, ...LIST } }, (db, call) => {
     const rows = listSuppressions(db, rangeOf(call), call.space);
-    const reasons = reasonsOf(db, rows);
-    return { suppressions: rows.map((row) => ({ ...suppression(row), ...(reasons.has(row.revision) ? { reason: reasons.get(row.revision) } : {}) })) };
+    const reasons = reasonsOf(db, rows.slice(0, call.count("max-listed")!));
+    return { suppressions: list(call, rows, (row) => ({ ...suppression(row), ...(reasons.has(row.revision) ? { reason: reasons.get(row.revision) } : {}) }), RANGE_REST) };
   }),
-  readCommand({ name: "modules", summary: "Where the files of the generated source start.", options: FILTER }, (db, call) => ({ modules: listModules(db, rangeOf(call), originsOf(call), call.space).map(module) })),
-  readCommand({ name: "operands", summary: "The operand expressions of instructions.", options: FILTER }, (db, call) => ({ operands: listOperands(db, rangeOf(call), originsOf(call), call.space).map(operand) })),
-  readCommand({ name: "patches", summary: "The code that a switch puts in.", options: { ...FILTER, switch: { kind: "text", value: "<switch>", help: "only the patches of this switch" } } }, (db, call) => ({
-    patches: listPatches(db, rangeOf(call), call.string("switch"), originsOf(call), call.space).map(patch),
+  readCommand({ name: "modules", summary: "Where the files of the generated source start.", options: { ...FILTER, ...LIST } }, (db, call) => ({ modules: list(call, listModules(db, rangeOf(call), originsOf(call), call.space), module, RANGE_REST) })),
+  readCommand({ name: "operands", summary: "The operand expressions of instructions.", options: { ...FILTER, ...LIST } }, (db, call) => ({ operands: list(call, listOperands(db, rangeOf(call), originsOf(call), call.space), operand, RANGE_REST) })),
+  readCommand({ name: "patches", summary: "The code that a switch puts in.", options: { ...FILTER, switch: { kind: "text", value: "<switch>", help: "only the patches of this switch" }, ...LIST } }, (db, call) => ({
+    patches: list(call, listPatches(db, rangeOf(call), call.string("switch"), originsOf(call), call.space), patch, RANGE_REST),
   })),
-  readCommand({ name: "switches", summary: "Each switch with the ranges of its patches." }, (db, call) => {
+  readCommand({ name: "switches", summary: "Each switch with the ranges of its patches.", options: LIST }, (db, call) => {
     const switches = new Map<string, PatchRow[]>();
     for (const row of listPatches(db, undefined, undefined, undefined, call.space)) switches.set(row.switch, [...(switches.get(row.switch) ?? []), row]);
-    return {
-      switches: [...switches].sort(([a], [b]) => (a < b ? -1 : 1)).map(([name, rows]) => ({ name, define: `--define ${name}=1`, patches: rows.map((row) => ({ start: formatC64Address(row.start), end: formatC64Address(row.end) })) })),
-    };
+    const show = ([name, rows]: [string, PatchRow[]]) => ({ name, define: `--define ${name}=1`, patches: rows.map((row) => ({ start: formatC64Address(row.start), end: formatC64Address(row.end) })) });
+    return { switches: list(call, [...switches].sort(([a], [b]) => (a < b ? -1 : 1)), show, MORE) };
   }),
-  readCommand({ name: "macros", summary: "The macros of the generated source.", options: { origin: OPTIONS.origin } }, (db, call) => ({ macros: listMacros(db, originsOf(call), call.space).map(macro) })),
-  readCommand({ name: "uses", summary: "The instructions written as a macro.", options: { ...FILTER, macro: { kind: "text", value: "<name>", help: "only the uses of this macro" } } }, (db, call) => ({
-    uses: listMacroUses(db, rangeOf(call), call.string("macro"), originsOf(call), call.space).map(macroUse),
+  readCommand({ name: "macros", summary: "The macros of the generated source.", options: { origin: OPTIONS.origin, ...LIST } }, (db, call) => ({ macros: list(call, listMacros(db, originsOf(call), call.space), macro, MORE) })),
+  readCommand({ name: "uses", summary: "The instructions written as a macro.", options: { ...FILTER, macro: { kind: "text", value: "<name>", help: "only the uses of this macro" }, ...LIST } }, (db, call) => ({
+    uses: list(call, listMacroUses(db, rangeOf(call), call.string("macro"), originsOf(call), call.space), macroUse, RANGE_REST),
   })),
-  readCommand({ name: "spaces", summary: "The address spaces that hold knowledge." }, (db) => ({ spaces: listSpaces(db) })),
+  readCommand({ name: "spaces", summary: "The address spaces that hold knowledge.", options: LIST }, (db, call) => ({ spaces: list(call, listSpaces(db), (space) => space, MORE) })),
   readCommand({ name: "program", summary: "The program in the knowledge: its segments and entry, and the coverage maps that coverage imported, with the ranges." }, (db, call) => {
     const image = programImage(db, call.space);
     const ranges = db === undefined ? [] : (db.prepare("SELECT kind, count(*) AS count FROM current_coverage WHERE space = ? GROUP BY kind ORDER BY kind").all(call.space) as Array<{ kind: string; count: number }>);
@@ -526,7 +555,7 @@ const READ_COMMANDS: CommandSpec[] = [
       name: "history",
       summary: "The rows at an address, of a name or of a macro, through all revisions, each with the reason and the evidence of its revision.",
       subjects: [{ ...ADDRESS, optional: true }],
-      options: { name: { kind: "text", value: "<name>", help: "the history of a name in place of an address" }, macro: { kind: "text", value: "<name>", help: "the history of a macro in place of an address" } },
+      options: { name: { kind: "text", value: "<name>", help: "the history of a name in place of an address" }, macro: { kind: "text", value: "<name>", help: "the history of a macro in place of an address" }, ...LIST },
       notes: "Give exactly one of <address>, --name and --macro.",
     },
     (db, call) => {
@@ -534,25 +563,22 @@ const READ_COMMANDS: CommandSpec[] = [
       const macroName = call.string("macro");
       if ([call.subjects.length > 0, name !== undefined, macroName !== undefined].filter(Boolean).length !== 1) throw new UsageError("history needs exactly one of <address>, --name and --macro");
       const entries = macroName !== undefined ? historyOfMacro(db, macroName, call.space) : name !== undefined ? historyNamed(db, name, call.space) : historyAt(db, call.parseAddress(call.subject(0), "<address>"), call.space);
-      return { history: entries.map((entry) => ({ ...historyEntry(entry), ...revisionNote(db, entry.from) })) };
+      return { history: list(call, entries, (entry) => ({ ...historyEntry(entry), ...revisionNote(db, entry.from) }), MORE) };
     },
   ),
   readCommand(
-    { name: "revisions", summary: "The revisions, newest first.", options: { limit: { kind: "count", value: "<n>", min: 1, max: 100_000, help: "at most n revisions" }, before: { kind: "text", value: "<revision>", help: "only the revisions before this one" } } },
+    { name: "revisions", summary: "The revisions, newest first.", options: { before: { kind: "text", value: "<revision>", help: "only the revisions before this one" }, ...LIST } },
     (db, call) => {
-      const options: { limit?: number; before?: string } = {};
-      const limit = call.count("limit");
-      if (limit !== undefined) options.limit = limit;
       const before = call.string("before");
-      if (before !== undefined) options.before = before;
-      return { revisions: revisions(db, options) };
+      const rows = revisions(db, before === undefined ? { limit: ALL } : { limit: ALL, before });
+      return { revisions: list(call, rows, (row) => row, "a larger --max-listed, or --before <revision> with the oldest revision in listed") };
     },
   ),
-  readCommand({ name: "revision", summary: "The rows that one revision added and closed.", subjects: [REVISION] }, (db, call) => {
+  readCommand({ name: "revision", summary: "The rows that one revision added and closed: knowledge rows, and memory, entry and coverage rows of the program.", subjects: [REVISION], options: LIST }, (db, call) => {
     const changes = revision(db, call.subject(0));
-    return { revision: changes.revision, added: changes.added.map(historyEntry), closed: changes.closed.map(historyEntry) };
+    return { revision: changes.revision, added: list(call, changes.added, historyEntry, MORE), closed: list(call, changes.closed, historyEntry, MORE) };
   }),
-  readCommand({ name: "export", summary: "All current knowledge to a project file as JSON.", options: { ...FILTER, out: { ...OPTIONS.out, value: "<file>", help: "the JSON file, relative to the project folder", required: true } } }, (db, call) => {
+  readCommand({ name: "export", summary: "All current knowledge to a project file as JSON.", options: { ...FILTER, out: { ...OPTIONS.out, output: "file", value: "<file>", help: "the JSON file, relative to the project folder", required: true } } }, (db, call) => {
     const range = rangeOf(call);
     const origins = originsOf(call);
     const space = call.space;
@@ -579,14 +605,14 @@ const READ_COMMANDS: CommandSpec[] = [
       name: "listing",
       summary: "The program as ACME lines with names, operand expressions, comments, the access of each line in the coverage (x executed, r read, w written) and the references in and out.",
       subjects: [RANGE],
-      options: { out: { ...OPTIONS.out, value: "<file>", help: "write the listing as text to this file in place of the lines in the result" } },
+      options: { out: { ...OPTIONS.out, output: "file", value: "<file>", help: "write the listing as text to this file in place of the lines in the result" }, ...LIST },
     },
     (db, call) => {
       const { start, end } = call.parseRange(call.subject(0), "<range>");
       const lines = listing(listingSource(db, call.space), start, end);
       const out = call.string("out");
       if (out !== undefined) return { lines: lines.length, ...writeReported(out, listingText(lines), { what: "--out" }) };
-      return { lines: lines.map((row) => ({ ...row, address: formatC64Address(row.address) })) };
+      return { lines: list(call, lines, (row) => ({ ...row, address: formatC64Address(row.address) }), "a larger --max-listed, a smaller <range>, or --out <file> for all lines") };
     },
   ),
 ];
@@ -821,11 +847,23 @@ const WRITE_COMMANDS: CommandSpec[] = [
       };
     },
   ),
-  writeCommand({ name: "revert", summary: "Undoes one revision with a new revision.", subjects: [REVISION] }, (call) => {
-    const context = contextOf(call);
-    const request = { revision: call.subject(0) };
-    return (db) => ({ revision: revert(db, context, request).revision });
-  }),
+  writeCommand(
+    {
+      name: "revert",
+      summary: "Makes the knowledge the same as at one revision: all spaces, or with --space only that space. The revert is a new revision: the history stays complete.",
+      subjects: [REVISION],
+      options: { space: { kind: "space", value: "<space>", help: "revert only this space: c64, drive8, or bank0 to bank255. The other spaces do not change. Without --space, every space reverts" } },
+    },
+    (call) => {
+      const context = contextOf(call);
+      const space = call.string("space");
+      const request = { revision: call.subject(0), ...(space === undefined ? {} : { space }) };
+      return (db) => {
+        const result = revert(db, context, request);
+        return { revision: result.revision, restores: result.current.restoredRevision, ...(space === undefined ? { spaces: "all" } : { space }) };
+      };
+    },
+  ),
   writeCommand({ name: "merge", summary: "Decides the conflicts that a git merge of two computers' work left: of the rows of one conflict, the newest stays. One revision for all." }, (call) => {
     const context = contextOf(call);
     const platform = new Map(platformNames().map((entry) => [entry.name, entry.address]));
@@ -869,7 +907,7 @@ const JOIN: CommandSpec = {
   name: "join",
   summary: "Joins the batches of agents that worked in parallel into one batch for apply. It writes no knowledge.",
   subjects: [{ name: "<batch>", help: 'a batch: a list of writes, or {"owner": {"start": "$1000", "end": "$1fff"}, "ops": [...]}', list: true }],
-  options: { ...SPACE, out: { ...OPTIONS.out, value: "<file>", help: "the joined batch, relative to the project folder", required: true } },
+  options: { ...SPACE, out: { ...OPTIONS.out, output: "file", value: "<file>", help: "the joined batch, relative to the project folder", required: true } },
   notes: "At an address in the owner range of a batch, its name, comment, operand and module win, and its regions come last. One name or one module file at two addresses writes nothing.",
   run: (call) => {
     if (call.subjects.length < 2) throw new UsageError("join needs two or more batch files");
@@ -924,7 +962,7 @@ function batchOperation(call: Call, item: unknown, at: string): BatchOperation {
 function batchFields(fields: Record<string, unknown>, at: string, address: (text: string, what: string) => number): BatchOperation {
   const op = oneOf(Object.keys(BATCH_FIELDS) as Array<BatchOperation["op"]>, String(fields.op), `${at}: op`);
   const unknown = Object.keys(fields).filter((key) => key !== "op" && key !== "space" && !BATCH_FIELDS[op].includes(key));
-  if (unknown.length > 0) throw new Refusal("invalid-input", `${at}: ${op} takes ${BATCH_FIELDS[op].join(", ")}, not ${unknown.join(", ")}`);
+  if (unknown.length > 0) throw new Refusal("invalid-input", `${at}: ${op} takes ${[...BATCH_FIELDS[op], "space"].join(", ")}, not ${unknown.join(", ")}`);
   const text = (key: string) => {
     if (typeof fields[key] !== "string") throw new Refusal("invalid-input", `${at}: ${key} must be a string`);
     return fields[key] as string;
@@ -990,7 +1028,7 @@ function batchFields(fields: Record<string, unknown>, at: string, address: (text
 
 await runScript({
   name: "knowledge",
-  summary: "Reads and writes the knowledge of the project: names, regions, comments, references, the program and its coverage, and the source knowledge. A read needs no knowledge folder. Every command takes --space: c64 (the default), drive8 for 1541 drive code, or bank0 to bank255 for cartridge banks.",
+  summary: "Reads and writes the knowledge of the project: names, regions, comments, references, the program and its coverage, and the source knowledge. A read needs no knowledge folder. Every command takes --space: c64 (the default), drive8 for 1541 drive code, or bank0 to bank255 for cartridge banks. revert without --space reverts all spaces.",
   names: knowledgeNames,
   commands: [...READ_COMMANDS, ...WRITE_COMMANDS, JOIN],
 });

package/skills/c64-knowledge/scripts/lib/listing.ts

@@ -4,7 +4,7 @@
 // reads files: knowledge.ts gives the lookups.
 
 import { COVERAGE, formatC64Address, formatC64Byte } from "#src/c64.ts";
-import { MODE_LENGTH, OPCODES, type Mode } from "#src/opcodes.ts";
+import { instructionWith, MODE_LENGTH, OPCODES, type Mode } from "#src/opcodes.ts";
 
 export interface ListingSource {
   /** The image byte at an address, or undefined outside the image. */
@@ -52,36 +52,13 @@ function accessOf(coverage: Uint8Array | undefined, start: number, length: numbe
   return text === "" ? "-" : text;
 }
 
-/** The operand of an instruction in ACME syntax, with the name of its target where one exists. */
+/** The operand value of an instruction as an expression: the name of its target where one exists, else the number. Empty for no operand. */
 function operandOf(mode: Mode, address: number, low: number, high: number, nameOf: ListingSource["nameOf"]): string {
-  const word = low | (high << 8);
   const named = (target: number, digits: 2 | 4) => nameOf(target) ?? (digits === 2 ? formatC64Byte(target) : formatC64Address(target));
-  switch (mode) {
-    case "imp":
-      return "";
-    case "imm":
-      return `#${formatC64Byte(low)}`;
-    case "zp":
-      return named(low, 2);
-    case "zpx":
-      return `${named(low, 2)},x`;
-    case "zpy":
-      return `${named(low, 2)},y`;
-    case "abs":
-      return named(word, 4);
-    case "abx":
-      return `${named(word, 4)},x`;
-    case "aby":
-      return `${named(word, 4)},y`;
-    case "ind":
-      return `(${named(word, 4)})`;
-    case "izx":
-      return `(${named(low, 2)},x)`;
-    case "izy":
-      return `(${named(low, 2)}),y`;
-    case "rel":
-      return named((address + 2 + (low < 0x80 ? low : low - 0x100)) & 0xffff, 4);
-  }
+  if (mode === "imp") return "";
+  if (mode === "imm") return formatC64Byte(low);
+  if (mode === "rel") return named((address + 2 + (low < 0x80 ? low : low - 0x100)) & 0xffff, 4);
+  return MODE_LENGTH[mode] === 3 ? named(low | (high << 8), 4) : named(low, 2);
 }
 
 /** The lines of start..end: instructions in code regions, decoded from the region start, and bytes elsewhere. */
@@ -123,8 +100,9 @@ export function listing(source: ListingSource, start: number, end: number): List
       const length = MODE_LENGTH[opcode.mode];
       const bytes = Array.from({ length: length - 1 }, (_, offset) => source.byteAt(address + 1 + offset));
       if (address + length - 1 <= region.end && bytes.every((value) => value !== undefined)) {
+        // The operand expression of the knowledge in the syntax of the addressing mode, as c64-source writes it.
         const operand = source.operand(address) ?? operandOf(opcode.mode, address, bytes[0] ?? 0, bytes[1] ?? 0, source.nameOf);
-        if (address >= start) lines.push(line(address, length, operand === "" ? opcode.mnemonic : `${opcode.mnemonic} ${operand}`));
+        if (address >= start) lines.push(line(address, length, instructionWith(byte, operand)));
         address += length;
         continue;
       }

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

@@ -31,7 +31,7 @@ node <skill>/scripts/memory-map.ts export --out src/hw.asm
 |---|---|
 | `at <address> ...` | For each address: `kind` (`platform` or `application`), the area, the name and the meaning. |
 | `decode <register> <value>` | The meaning of the value. Use `--bank` with the value of `$DD00` to get the addresses for `$D018`. The decoders are for `$01`, `$D010`, `$D011`, `$D015` to `$D01F`, `$D016`, `$D018`, `$DC0D`, `$DD00` and `$DD0D`. |
-| `list <vic\|sid\|cia1\|cia2\|kernal\|system>` | All entries of that group. |
+| `list <vic\|sid\|cia1\|cia2\|kernal\|system>` | The entries of that group as a list: `count` and `listed`. `--max-listed` limits `listed`. The default is 50. |
 | `export --out <file>` | Writes all platform names to a project file as an ACME include: one line for each name, with its meaning as a comment. A zero-page name is `NAME = $xx`. Other names are `NAME = $xxxx`. |
 
 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.
@@ -43,6 +43,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

@@ -6,7 +6,7 @@ import { formatC64Address, formatC64Byte } from "#src/c64.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";
-import { OPTIONS, runScript, UsageError } from "#src/script.ts";
+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 });
 
@@ -61,16 +61,17 @@ await runScript({
       name: "list",
       summary: "The registers of a chip, the KERNAL jump table, or the system areas.",
       subjects: [{ name: "<list>", help: `one of ${Object.keys(LISTS).join(", ")}` }],
+      options: { "max-listed": OPTIONS["max-listed"] },
       run: (call) => {
         const list = LISTS[call.subject(0)];
         if (list === undefined) throw new UsageError(`<list> must be one of ${Object.keys(LISTS).join(", ")}, not ${call.subject(0)}`);
-        return { entries: list().map(show) };
+        return { entries: listed(list(), call.count("max-listed")!, show, "a larger --max-listed, or memory-map.ts export --out <file> for every platform name") };
       },
     },
     {
       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

@@ -38,7 +38,7 @@ node <skill>/scripts/provenance.ts leftovers --out .c64-re-tools/local/leftovers
 
 | Option | Meaning |
 |---|---|
-| `--shift 2:-256` | Move release 2 (the first release is 1) by -256 bytes. Use it again for more releases. |
+| `--shift 2:-256` | Move release 2 (the first release is 1) by -256 bytes. Use it again for more releases. Give one shift for each release. |
 | `--range '$0900-$09ff'` | Compare only the addresses in this range. |
 | `--frames 600` | Run each release for this many frames, and give each listed difference its runtime evidence. |
 | `--steps .c64-re-tools/local/start-game.json` | With `--frames`: a JSON list of action steps to run before the frames, for example a key to start the game. The steps are the steps of a c64-unpacker steps file. |
@@ -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,7 @@ 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. Run c64-static-analysis first, so that the knowledge has the code regions and the references.
+- `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.
 - `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 +113,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 no call or jump reaches from the entry, and that no run executed. |
+| `deadCode` | Code regions of the knowledge that the entry does not reach, as in `codeRegions.unreachable` of `separate`, and that no run executed. |
 
 Text from another computer can show the tools of the developer:
 
@@ -162,7 +163,8 @@ To save a routine:
    - `--name` is the name of the routine and of its file. When you do not give it, the script uses the user or LLM name at the start.
    - `--title` is the title of the routine. When you do not give it, the script uses the module title.
    - A routine has at least 16 bytes. Its last instruction must end in the range.
-3. Read `leftOut`. It lists the rows that the file does not keep, and why. For example, the file does not keep an operand expression that uses a name outside the routine.
+3. The result shows the routine file as `{out, bytes, sha256}`. `out` is relative to the project folder.
+4. Read `leftOut`. It lists the rows that the file does not keep, and why. For example, the file does not keep an operand expression that uses a name outside the routine.
 
 To find the routines in a program:
 

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

@@ -4,10 +4,12 @@
 // its start, so match finds it in another program at another address and
 // 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, resolve } from "node:path";
+import { join, relative, resolve, sep } from "node:path";
 
 import { Refusal } from "#src/errors.ts";
+import { writeRefusal, type Written } from "#src/host-client/transfer.ts";
 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";
@@ -317,16 +319,26 @@ export function readLibrary(folder: string): Routine[] {
     .map((name) => parseRoutine(readFileSync(join(folder, name), "utf8"), name));
 }
 
-/** Writes a routine file into the library: a temporary file, then a rename. Refuses a name that exists unless `replace`. */
-export function saveRoutine(folder: string, routine: Routine, replace: boolean): string {
+/**
+ * Writes a routine file into the library: a temporary file, then a rename.
+ * Refuses a name that exists unless `replace`. Reports the file as a written
+ * file: its path relative to the project folder `root`, its size and its SHA-256.
+ */
+export function saveRoutine(folder: string, routine: Routine, replace: boolean, root = process.cwd()): Written {
   const file = join(folder, `${routine.name}.json`);
+  const out = relative(root, file).split(sep).join("/");
   if (!replace && statSync(file, { throwIfNoEntry: false }) !== undefined) {
     throw new Refusal("conflict", `The library already has the routine ${routine.name}. Give another --name, or give --replace to save over it.`);
   }
+  const bytes = Buffer.from(routineText(routine), "utf8");
   const temporary = `${file}.${process.pid}.tmp`;
-  writeFileSync(temporary, routineText(routine));
-  renameSync(temporary, file);
-  return file;
+  try {
+    writeFileSync(temporary, bytes);
+    renameSync(temporary, file);
+  } catch (error) {
+    throw writeRefusal(error, out, "--library") ?? error;
+  }
+  return { out, bytes: bytes.length, sha256: createHash("sha256").update(bytes).digest("hex") };
 }
 
 /** An image to search: its segments and its bytes inside them. */

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

@@ -1,10 +1,11 @@
 // 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 reach it from the
-// entry; and what the program reads or executes outside the image. Evidence
-// only: nothing here decides what is original.
+// 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
+// or executes outside the image. Evidence only: nothing here decides what is
+// original.
 
-import { type AddressRange, COVERAGE, executedRamCode } from "#src/c64.ts";
+import { type AddressRange, COVERAGE, executedRamCode, instructionLength } from "#src/c64.ts";
 
 export type Access = "executed" | "read" | "written" | "read-written" | "untouched";
 
@@ -49,6 +50,27 @@ export interface Separation {
 
 const SYSTEM_PAGES_END = 0x03ff;
 
+/** 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]);
+
+/**
+ * The address after a code region where the CPU runs on, or undefined when
+ * its last instruction does not run on (RTS, RTI, JMP, BRK, JAM). The
+ * instructions follow one another from the start of the region.
+ */
+export function fallThrough(region: AddressRange, memory: Uint8Array): number | undefined {
+  let at = region.start;
+  let last = at;
+  while (at <= region.end) {
+    last = at;
+    at += instructionLength(memory[at]!);
+  }
+  return NO_FALL_THROUGH.has(memory[last]!) || at > 0xffff ? undefined : at;
+}
+
+/** The most instructions outside the code regions that the run on from a region goes through, for example an instruction in a dual-use region. */
+const MAX_RUN_ON = 16;
+
 /** Joins addresses in order into ranges; `gap` is the most bytes between two addresses in one range. */
 function merge(addresses: number[], gap = 0, joins: (from: number, to: number) => boolean = () => true): AddressRange[] {
   const ranges: AddressRange[] = [];
@@ -92,12 +114,29 @@ export function separate(input: SeparationInput): Separation {
     }
   }
 
-  // Reachability: from the region that holds the entry, through call and jump references, to a fixed point.
+  // Reachability: from the region that holds the entry, 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 reached = new Set<number>();
   if (input.entry !== undefined && holding(input.entry) >= 0) reached.add(holding(input.entry));
-  const flows = input.references.filter((reference) => reference.kind === "call" || reference.kind === "jump");
+  // 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 => {
+    let at = from;
+    for (let count = 0; count <= MAX_RUN_ON && at <= 0xffff && inImage(at); count++) {
+      if (holding(at) >= 0) return at;
+      if (NO_FALL_THROUGH.has(input.memory[at]!)) return undefined;
+      at += instructionLength(input.memory[at]!);
+    }
+    return undefined;
+  };
+  const runsOn = regions.flatMap((region) => {
+    const next = fallThrough(region, input.memory);
+    const to = next === undefined ? undefined : runOn(next);
+    return to === undefined ? [] : [{ from: region.end, to }];
+  });
+  const flows = [...input.references.filter((reference) => reference.kind === "call" || reference.kind === "jump"), ...runsOn];
   for (let grown = true; grown; ) {
     grown = false;
     for (const flow of flows) {