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

package/skills/c64-static-analysis/SKILL.md

@@ -21,22 +21,20 @@ Find the static structure of a C64 program. Record the structure in the project
 The script reads the program, the coverage and the current knowledge, and runs DXA or Ghidra on this machine. The host runtime is not necessary. The script records the result in the project knowledge, `.c64-re-tools/knowledge/`.
 
 ```
-node <skill>/scripts/analyze.ts --analyzer dxa --listing .c64-re-tools/local/game.lst
-node <skill>/scripts/analyze.ts --entry '$080d' --decompile '$080d'
+node <skill>/scripts/static-analysis.ts analyze --analyzer dxa --out-listing .c64-re-tools/local/game.lst
+node <skill>/scripts/static-analysis.ts analyze --entry '$080d' --decompile '$080d'
 ```
 
 | Option | Meaning |
 |---|---|
 | `--analyzer dxa` | Use DXA: a fast first pass. Without this option, the script uses Ghidra. |
 | `--entry '$080d'` | An address where code starts. Use it again for more addresses. |
-| `--listing .c64-re-tools/local/game.lst` | DXA only: write the disassembly listing to this project file. |
+| `--out-listing .c64-re-tools/local/game.lst` | DXA only: write the disassembly listing to this project file. |
 | `--decompile '$0818'` | Ghidra only: decompile the routine at this address. Use it again for more routines, at most 32. |
 | `--max-listed 20` | List at most this number of labels, functions or candidates. The default is 50. Use 0 to list none. |
-| `--instructions .c64-re-tools/local/instructions.json` | Ghidra only: write every instruction to this project file as JSON. Each has `address`, `bytes`, `mnemonic`, `mode` and `operand` in 6502 syntax. A branch, jump or call also has its `target`. When the knowledge has coverage, `executed` tells if it ran. |
+| `--out-instructions .c64-re-tools/local/instructions.json` | Ghidra only: write every instruction to this project file as JSON. Each has `address`, `bytes`, `mnemonic`, `mode` and `operand` in 6502 syntax. A branch, jump or call also has its `target`. When the knowledge has coverage, `executed` tells if it ran. |
 | `--space drive8` | The knowledge space of the program: `drive8` for code from the 1541 drive, or `bank0` to `bank255` for a cartridge bank. The default is `c64`. The seeds come from that space, and the findings go into it. |
-| `--macro-batch .c64-re-tools/local/macros.json` | Write the macro candidates to this project file as a batch for `apply` of the c64-knowledge skill. |
-
-The script prints one JSON object. Addresses are `$` and four hex digits.
+| `--out-macro-batch .c64-re-tools/local/macros.json` | Write the macro candidates to this project file as a batch for `apply` of the c64-knowledge skill. |
 
 Both analyzers use the knowledge from the user and the LLM as seeds:
 
@@ -51,17 +49,29 @@ More seeds come from evidence:
 - The start of each `code` region and each entry of a `jumps` table from the user or the LLM is an entry point.
 - When the knowledge has coverage, each executed instruction of the program that starts a flow is an entry point. A flow starts after a gap, or after RTS, RTI, JMP, BRK or JSR. Then the analyzers find code that only a vector, an RTS table or an interrupt reaches. They also find the code after a JSR to a routine that an analyzer thinks does not return.
 - For Ghidra, a flow start is a routine only when no executed branch or JMP from another flow gets to it. Also, no JSR can be immediately before it. Another flow start is code in a routine, and Ghidra does not make a function of it.
-- When the knowledge has coverage, Ghidra gives `coverageGaps`: the executed instruction starts in the program that are not in its instructions. Normally the count is 0. Each start in the list is missing from `--instructions` and from the source of c64-source. Examine the code at the start. Overlapped instructions and self-modified code can cause a gap. A start in a `dual-use` region is a known overlap, for example a BIT skip, and is not in the list.
+- When the knowledge has coverage, Ghidra gives `coverageGaps`: the executed instruction starts in the program that are not in its instructions. Normally the count is 0. Each start in the list is missing from `--out-instructions` and from the source of c64-source. Examine the code at the start. Overlapped instructions and self-modified code can cause a gap. A start in a `dual-use` region is a known overlap, for example a BIT skip, and is not in the list.
 - When the knowledge has coverage, some RAM under a ROM is data for the analysis. At these addresses, the runs used the ROM and did not read or execute the RAM. Then a call into the KERNAL does not decode the RAM bytes under it as code. A knowledge routine or an `--entry` in such a range keeps its code. Ghidra does not follow BRK, because the vector at `$fffe` is in ROM unless the program removes the KERNAL.
 
 The analyzers take at most 1024 entry points. Knowledge routines and `--entry` come first, then code regions and tables, then coverage. Ghidra also takes at most 8192 flow starts that are code in a routine. `coverageSeeds` gives how many entry points the coverage gave and how many the analysis used. `romOnlyRanges` and `romOnlyUsed` give the same counts for the data ranges under ROM.
 
+### Calling the script
+
+- Call a script as `node <skill>/scripts/<script>.ts <command> [subjects] [options]`. The command comes first.
+- `<script>.ts --help` lists the commands. `<script>.ts <command> --help` gives the subjects and the options of one command. The help is JSON: `{"text": "..."}`.
+- 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 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.
+
 ### Project folder
 
 - Paths are relative to the project folder. The project folder is the nearest folder at or above the working directory that holds `.c64-re-tools/`.
 - If the working directory is not in a project and has projects below it, the script refuses and lists them. Then give `--project <folder>` to each script.
 - Write each file that you make for your work in `.c64-re-tools/local/` of the project. Git ignores that folder. Examples are results, batches, step files, runs, snapshots and memory dumps.
-- Move a file out of `.c64-re-tools/local/` only when it is the evidence for a finding. Move it before you give it to `--evidence` of c64-knowledge. `--evidence` refuses a file in `.c64-re-tools/local/`.
+- Move a file out of `.c64-re-tools/local/` only when it is the evidence for a finding. Move it before you give it to `--evidence test:<file>` or `--evidence file:<file>` of c64-knowledge. These two refuse a file in `.c64-re-tools/local/`.
+- Do not move a coverage map after `coverage` of c64-knowledge imported it. `--evidence coverage:<map>` names the map by its path at the import. The knowledge keeps the coverage and the SHA-256 of the map, so the evidence stays valid.
 - Put a run that is evidence in `runs/<name>/`, with its run file, its results and the snapshot files that it uses. Change the paths in the run file to the new paths. Then git keeps them, and another person can do the run again.
 - A shell redirect (`>`) is relative to the working directory, not to the project folder. From the folder above the project, write `<folder>/.c64-re-tools/local/result.json`.
 
@@ -80,7 +90,7 @@ The analyzers take at most 1024 entry points. Knowledge routines and `--entry` c
    - `idioms` tells what the script found by pattern: RTS dispatch tables (`rtsTables`), JMP tables (`jumpTables`) and BIT skips (`bitSkips`). It also finds the `CBM80` header of a cartridge bank at `$8000` (`cartridgeHeaders`). The two start vectors of the header become entry points. The script writes them as knowledge with the origin `heuristic`, and seeds their targets into the same analysis. `candidates` gives DOP padding (`dop`) and opcodes that the program wrote and executed (`selfModified`). For `selfModified`, the write and the execution must be in one coverage file. A coverage file does not record the order. Thus a candidate can also be code that ran first, and that the program then wrote over. To prevent this, save one coverage file for each part of the program, for example the intro and the game. A loader that copies relocated code is also such a part. Clear the memory map between the parts. Each list has a `count`. The script does not write the candidates. Look at them and decide.
    - `candidates.pointers` gives code that makes an address from immediates. A `vector` or a `zero-page pointer` candidate stores a low byte (`low`) and a high byte (`high`) to a vector or to a zero-page pair that `(zp),y` uses. Its `target` is in the program or has a platform name. A `sprite pointer` candidate stores an immediate (`at`) to a sprite pointer of the screen at $0400 in VIC bank 0. Its `target` (the value × 64) is in a `sprite` region. For each candidate that you confirm, write operand expressions with `operand` of the c64-knowledge skill, for example `operand '<low>' --lo <target name>` and `operand '<high>' --hi <target name>`. Then a rebuild can move the target.
    - `candidates.pitfalls` gives code that a C64 runs in a different way than it reads. `raster-bit-8`: the instruction at `at` reads $D011, and the instruction at `store` writes the value back. A read of $D011 gives bit 8 of the raster line in bit 7. Thus the write can move the raster interrupt to line 256 or later, and on PAL past line 311 the interrupt never comes. Examine each candidate. Where the code must not keep bit 7, add a comment and test the program.
-   - `candidates.macros` gives runs of instructions that a macro writes as one line, for example `+inc16 ptr`. The script knows these 6502 idioms: `inc16`, `dec16`, `add16_8`, `add16`, `sub16`, `set16`, `mov16` and `wait_line`. It reads the code regions after the analysis. An arg has the name of a `user` or `llm` symbol or a platform name. Each candidate has `macro`, `start`, `end`, `args` and `text`. `known` counts the uses that the knowledge has. `leftOut` counts the candidates with a label inside, or with a patch or a use over them. The c64-source skill writes such a candidate as instructions. With `--macro-batch`, `batch` gives the file, the count of writes and the `apply` command. The batch holds the macros that the knowledge does not have, and the uses. When the knowledge has a macro with the same name and another body, `otherMacros` tells that the batch does not have its uses. The script does not write the candidates. Apply the batch, then generate the source again.
+   - `candidates.macros` gives runs of instructions that a macro writes as one line, for example `+inc16 ptr`. The script knows these 6502 idioms: `inc16`, `dec16`, `add16_8`, `add16`, `sub16`, `set16`, `mov16` and `wait_line`. It reads the code regions after the analysis. An arg has the name of a `user` or `llm` symbol or a platform name. Each candidate has `macro`, `start`, `end`, `args` and `text`. `known` counts the uses that the knowledge has. `leftOut` counts the candidates with a label inside, or with a patch or a use over them. The c64-source skill writes such a candidate as instructions. With `--out-macro-batch`, `batch` gives the file, the count of writes (`writes`) and the `apply` command. The batch holds the macros that the knowledge does not have, and the uses. When the knowledge has a macro with the same name and another body, `otherMacros` tells that the batch does not have its uses. The script does not write the candidates. Apply the batch, then generate the source again.
    - When the knowledge has coverage, a code finding replaces the DXA or Ghidra data where a run executed an instruction start. `coverageConflicts` lists the analyzer data regions where the coverage still shows executed code. Classify them as code with the c64-knowledge skill, or as `dual-use` when the bytes are also data. For many conflicts, write all classifications in one `apply` batch of the c64-knowledge skill.
 6. Give each important routine a name with the c64-knowledge skill. Then run the analysis again. The analyzers use the new names.
 
@@ -109,9 +119,9 @@ Do not store:
 
 ## Result
 
-The changes to the knowledge and the conflicts. For DXA, also the regions, the labels and the path of the listing. For Ghidra, also the routines and the decompiled code.
+The changes to the knowledge and the conflicts. For DXA, also the regions, the labels and the file of the listing (`listing`). For Ghidra, also the routines, the decompiled code and the file of the instructions (`instructions`).
 
-The exit status is 0 for a result, also with conflicts. The exit status is 1 for an error. The exit status is 2 for a wrong argument.
+The exit status is 0, also with conflicts.
 
 ## Failure and conflicts
 
@@ -133,4 +143,5 @@ The exit status is 0 for a result, also with conflicts. The exit status is 1 for
 - Runtime behavior → c64-emulator
 - Names and classifications → c64-knowledge
 - The meaning of a C64 hardware address → c64-memory-map
-- Source code for a rebuild → c64-assembler
+- Source code from the knowledge → c64-source
+- Build the source → c64-assembler

package/skills/c64-static-analysis/scripts/lib/coverage.ts

@@ -9,10 +9,9 @@ import { COVERAGE, coverageEntries, coverageSeedKinds, executedStarts } from "#s
 export { coverageEntries, coverageSeedKinds, executedStarts };
 import { FULL_COVERAGE } from "#src/host-client/coverage.ts";
 import { listRegions, type RegionRow } from "#src/knowledge/read.ts";
-import { CODE_REGION_TYPES, DEFAULT_SPACE, type Space } from "#src/knowledge/schema.ts";
+import { CODE_REGION_TYPES, DEFAULT_SPACE, isAnalyzer, isSemantic, type Space } from "#src/knowledge/schema.ts";
 
 const FULL_MAP = FULL_COVERAGE;
-const ANALYZER_ORIGINS = new Set(["dxa", "ghidra", "heuristic"]);
 
 /** The byte at an address of the analyzed image, or undefined outside it. */
 export type ImageByte = (address: number) => number | undefined;
@@ -46,7 +45,7 @@ export function romOnlyRanges(map: Uint8Array, image: ImageByte): Array<{ start:
 /** Entry points from semantic knowledge beyond routines: the start of each code region, and each entry of a JMP table with its target. */
 export function codeEntries(db: DatabaseSync | undefined, image: ImageByte, space: Space = DEFAULT_SPACE): number[] {
   const entries: number[] = [];
-  for (const region of listRegions(db, undefined, undefined, undefined, space).filter((row) => row.origin === "user" || row.origin === "llm")) {
+  for (const region of listRegions(db, undefined, undefined, undefined, space).filter((row) => isSemantic(row.origin))) {
     if (region.type === "code") entries.push(region.start);
     if (region.type !== "jumps") continue;
     for (let at = region.start; at + 2 <= region.end; at += 3) {
@@ -63,7 +62,7 @@ export function codeEntries(db: DatabaseSync | undefined, image: ImageByte, spac
 export function coverageConflicts(db: DatabaseSync | undefined, map: Uint8Array): Array<{ region: RegionRow; executed: number }> {
   const conflicts: Array<{ region: RegionRow; executed: number }> = [];
   for (const region of listRegions(db)) {
-    if (!ANALYZER_ORIGINS.has(region.origin) || CODE_REGION_TYPES.includes(region.type) || region.type === "dual-use") continue;
+    if (!isAnalyzer(region.origin) || CODE_REGION_TYPES.includes(region.type) || region.type === "dual-use") continue;
     let executed = 0;
     for (let address = region.start; address <= region.end; address++) if ((map[address]! & COVERAGE.ramExecute) !== 0) executed++;
     if (executed > 0) conflicts.push({ region, executed });

package/skills/c64-static-analysis/scripts/lib/findings.ts

@@ -5,12 +5,12 @@ import type { DatabaseSync } from "node:sqlite";
 
 import type { NormalizedFindings } from "#src/knowledge/import.ts";
 import { listRegions, listSymbols } from "#src/knowledge/read.ts";
-import { CODE_REGION_TYPES, DEFAULT_SPACE, type Space } from "#src/knowledge/schema.ts";
+import { CODE_REGION_TYPES, DEFAULT_SPACE, isSemantic, type Space } from "#src/knowledge/schema.ts";
 import type { DxaResult, GhidraParams, GhidraResult } from "#src/native/types.ts";
 
 export type Seeds = Pick<GhidraParams, "entryPoints" | "dataRanges" | "labels">;
 
-const semantic = (row: { origin: string }) => row.origin === "user" || row.origin === "llm";
+const semantic = (row: { origin: string }) => isSemantic(row.origin);
 
 /**
  * Seeds from current semantic knowledge: routines from the user or

package/skills/c64-static-analysis/scripts/lib/instructions.ts

@@ -86,7 +86,7 @@ export interface ListedInstruction {
   executed?: boolean;
 }
 
-/** Ghidra's instructions as the list that --instructions writes. */
+/** Ghidra's instructions as the list that --out-instructions writes. */
 export function instructionList(instructions: GhidraInstruction[], coverage?: Uint8Array): ListedInstruction[] {
   return instructions.map((instruction) => {
     const bytes = Buffer.from(instruction.bytes, "hex");

package/skills/c64-static-analysis/scripts/lib/macros.ts

@@ -8,7 +8,7 @@
 // known to be correct. A search for any repeated sequence was weighed and not
 // chosen: it gives many candidates without a name.
 
-import { instructionLength } from "#src/c64.ts";
+import { formatC64Address, formatC64Byte, instructionLength } from "#src/c64.ts";
 import type { ImageByte } from "./coverage.ts";
 
 /** A macro of the catalogue: its params and its ACME body, which names a param with a dot. */
@@ -97,14 +97,12 @@ const CMP_ABSOLUTE = 0xcd;
  */
 export type Namer = (address: number) => string | undefined;
 
-const hex2 = (value: number) => `$${value.toString(16).padStart(2, "0")}`;
-const hex4 = (value: number) => `$${value.toString(16).padStart(4, "0")}`;
 
 function addressArg(operand: Operand, name: Namer): string {
   const named = name(operand.value);
   // A name of a zero-page address gives the zero-page form: an absolute operand there keeps its number.
   if (named !== undefined && (operand.value >= 0x100 || !operand.absolute)) return named;
-  return operand.absolute ? hex4(operand.value) : hex2(operand.value);
+  return operand.absolute ? formatC64Address(operand.value) : formatC64Byte(operand.value);
 }
 
 /** The memory operand of `instruction` when it is one of the opcodes of the mnemonic. */
@@ -141,7 +139,7 @@ const MATCHERS: Record<string, { count: number; match: (run: Instruction[], name
       const dst = memory(load, "lda");
       const value = immediate(add, IMMEDIATE.adc);
       const ok = clc?.opcode === CLC && value !== undefined && same(dst, memory(store, "sta")) && same(dst, memory(high, "inc"), 1) && skips(branch, BCC, high);
-      return ok ? [addressArg(dst!, name), hex2(value)] : undefined;
+      return ok ? [addressArg(dst!, name), formatC64Byte(value)] : undefined;
     },
   },
   add16: { count: 7, match: (run, name) => wide(run, name, CLC, IMMEDIATE.adc) },
@@ -154,7 +152,7 @@ const MATCHERS: Record<string, { count: number; match: (run: Instruction[], name
       const dst = memory(storeLow, "sta");
       if (low === undefined || high === undefined || !same(dst, memory(storeHigh, "sta"), 1)) return undefined;
       const value = low | (high << 8);
-      return [addressArg(dst!, name), name(value) ?? hex4(value)];
+      return [addressArg(dst!, name), name(value) ?? formatC64Address(value)];
     },
   },
   mov16: {
@@ -171,7 +169,7 @@ const MATCHERS: Record<string, { count: number; match: (run: Instruction[], name
     match: ([load, compare, branch]) => {
       const line = immediate(load, IMMEDIATE.lda);
       // BNE back to the CMP: 5 bytes back from the end of the BNE.
-      return line !== undefined && compare?.opcode === CMP_ABSOLUTE && compare.value === 0xd012 && branch?.opcode === BNE && branch.value === 0xfb ? [hex2(line)] : undefined;
+      return line !== undefined && compare?.opcode === CMP_ABSOLUTE && compare.value === 0xd012 && branch?.opcode === BNE && branch.value === 0xfb ? [formatC64Byte(line)] : undefined;
     },
   },
 };
@@ -183,7 +181,7 @@ function wide([carry, loadLow, low, storeLow, loadHigh, high, storeHigh]: Instru
   const highValue = immediate(high, opcode);
   const ok =
     carry?.opcode === carryOpcode && lowValue !== undefined && highValue !== undefined && same(dst, memory(storeLow, "sta")) && same(dst, memory(loadHigh, "lda"), 1) && same(dst, memory(storeHigh, "sta"), 1);
-  return ok ? [addressArg(dst!, name), hex4(lowValue | (highValue << 8))] : undefined;
+  return ok ? [addressArg(dst!, name), formatC64Address(lowValue | (highValue << 8))] : undefined;
 }
 
 /** The instruction at `at`, or undefined when a byte of it is outside the range or the image. */

package/skills/c64-static-analysis/scripts/{analyze.ts → static-analysis.ts}

@@ -3,25 +3,22 @@
 // from current knowledge and the coverage of the knowledge, and imports the
 // structural findings into .c64-re-tools/knowledge/.
 
-import { mkdirSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
-import { parseArgs } from "node:util";
-
-import { COVERAGE, formatC64Address, parseC64Address, prgRange } from "#src/c64.ts";
+import { COVERAGE, formatC64Address, prgRange } from "#src/c64.ts";
+import { Refusal } from "#src/errors.ts";
 import { WireFailure } from "#src/host-client/tools.ts";
-import { writeProjectFile } from "#src/host-client/transfer.ts";
+import { writeReported } from "#src/host-client/transfer.ts";
+import { knowledgeNames } from "#src/knowledge/names.ts";
 import { analyze as analyzeWithDxa } from "#src/native/dxa.ts";
 import { analyze as analyzeWithGhidra } from "#src/native/ghidra/analyze.ts";
 import { localToolContext } from "#src/native/local.ts";
 import { GHIDRA_LIMITS } from "#src/native/types.ts";
-import { KnowledgeError, openForRead, withWrite } from "#src/knowledge/database.ts";
+import { openForRead, withWrite } from "#src/knowledge/database.ts";
 import { analyzedBytes, programCoverage, requireProgram } from "#src/knowledge/program.ts";
-import { importFindings, runProvenance, type Analyzer, type ImportConflict, type ImportContext, type ImportResult, type NormalizedFindings } from "#src/knowledge/import.ts";
+import { importFindings, runProvenance, type ImportConflict, type ImportContext, type ImportResult, type NormalizedFindings } from "#src/knowledge/import.ts";
 import { currentRevision, listMacros, listMacroUses, listPatches, listReferences, listRegions, listSymbols } from "#src/knowledge/read.ts";
-import { DEFAULT_SPACE, SPACE } from "#src/knowledge/schema.ts";
+import { DEFAULT_SPACE, SEMANTIC_ORIGINS, type Analyzer } from "#src/knowledge/schema.ts";
 import { platformNames } from "#src/platform.ts";
-import { resolveProjectPath } from "#src/project.ts";
-import { runScript, UsageError } from "#src/script.ts";
+import { listed, OPTIONS, runScript, UsageError, type Call } from "#src/script.ts";
 import { codeEntries, coverageConflicts, coverageEntries, coverageSeedKinds, executedStarts, imageReader, romOnlyRanges, type ImageByte } from "./lib/coverage.ts";
 import { dxaFindings, ghidraFindings, seedsFromKnowledge } from "./lib/findings.ts";
 import { findIdioms } from "./lib/idioms.ts";
@@ -30,37 +27,6 @@ import { CATALOGUE, findMacroUses, type MacroCandidate } from "./lib/macros.ts";
 import { findPitfalls, type Pitfall } from "./lib/pitfalls.ts";
 import { findPointers, type PointerCandidate } from "./lib/pointers.ts";
 
-const USAGE = `analyze.ts [options]
-
-The program and the coverage come from the knowledge: put them in with
-knowledge.ts image and coverage of the c64-knowledge skill. The executed code of
-the coverage is seeded, and analyzer data over it is reported.
-
-  --analyzer <name>       dxa (fast first pass) or ghidra (deeper, the default)
-  --entry <address>       an entry point, for example '$080d' (repeatable)
-  --decompile <address>   ghidra: a routine to decompile, at most 32 (repeatable)
-  --listing <file>        dxa: write the disassembly listing to this project file
-  --instructions <file>   ghidra: write every instruction (address, bytes, mnemonic,
-                          mode, operand, target, executed) to this project file as JSON
-  --max-listed <n>        list at most n labels, functions or candidates (default 50,
-                          0 for none); the counts are always given, and knowledge has
-                          all labels and functions
-  --space <space>         the knowledge space of the program: c64 (the default), drive8
-                          for 1541 drive code, or bank0 to bank255 for a cartridge bank
-  --macro-batch <file>    write the macro candidates as an apply batch of c64-knowledge
-                          (the macros and their uses) to this project file
-
-Routine symbols in knowledge are entry points too. Ghidra needs at least one
-entry point; dxa finds the SYS of a BASIC start by itself. The result is one
-JSON object. Addresses are $ and four hex digits.`;
-
-const DEFAULT_MAX_LISTED = 50;
-
-/** The first `max` items, the count, and where to read the rest when the list is cut. */
-function listed<T, U>(items: T[], max: number, show: (item: T) => U, all: string) {
-  return { count: items.length, listed: items.slice(0, max).map(show), ...(items.length > max ? { rest: all } : {}) };
-}
-
 /** A pitfall with $ addresses and what goes wrong. */
 function showPitfall(pitfall: Pitfall) {
   return {
@@ -73,11 +39,10 @@ function showPitfall(pitfall: Pitfall) {
 
 /** A pointer candidate with $ addresses, and the operand writes that would name it. */
 function showPointer(candidate: PointerCandidate) {
-  const hex = formatC64Address;
   if (candidate.kind === "sprite pointer") {
-    return { kind: candidate.kind, at: hex(candidate.at), to: hex(candidate.to), value: `$${candidate.value.toString(16).padStart(2, "0")}`, target: hex(candidate.target), assumes: "VIC bank 0 and the screen at $0400" };
+    return { kind: candidate.kind, at: formatC64Address(candidate.at), to: formatC64Address(candidate.to), value: `$${candidate.value.toString(16).padStart(2, "0")}`, target: formatC64Address(candidate.target), assumes: "VIC bank 0 and the screen at $0400" };
   }
-  return { kind: candidate.kind, to: hex(candidate.to), target: hex(candidate.target), low: hex(candidate.low), high: hex(candidate.high) };
+  return { kind: candidate.kind, to: formatC64Address(candidate.to), target: formatC64Address(candidate.target), low: formatC64Address(candidate.low), high: formatC64Address(candidate.high) };
 }
 
 /** A macro candidate with $ addresses and its source line. */
@@ -98,7 +63,7 @@ function macroCandidates(space: string, byteAt: ImageByte, batchPath: string | u
   const db = openForRead();
   try {
     const platform = space === DEFAULT_SPACE ? new Map(platformNames().map((entry) => [entry.address, entry.name])) : new Map<number, string>();
-    const semantic = new Map(listSymbols(db, undefined, undefined, ["user", "llm"], space).map((symbol) => [symbol.address, symbol.name]));
+    const semantic = new Map(listSymbols(db, undefined, undefined, [...SEMANTIC_ORIGINS], space).map((symbol) => [symbol.address, symbol.name]));
     const code = listRegions(db, undefined, "code", undefined, space);
     const found = findMacroUses(byteAt, code, (address) => semantic.get(address) ?? platform.get(address));
     const named = new Set([...listSymbols(db, undefined, undefined, undefined, space).map((symbol) => symbol.address), ...listReferences(db, undefined, undefined, undefined, space).map((reference) => reference.to)]);
@@ -130,13 +95,13 @@ function macroCandidates(space: string, byteAt: ImageByte, batchPath: string | u
       batched.push(candidate);
       batch.push({ op: "use", start: formatC64Address(candidate.start), end: formatC64Address(candidate.end), macro: candidate.macro, args: candidate.args, ...(space === DEFAULT_SPACE ? {} : { space }) });
     }
-    if (batch.length > 0) writeProjectFile(batchPath, Buffer.from(`${JSON.stringify(batch, null, 1)}\n`), { what: "--macro-batch" });
+    const written = batch.length > 0 ? writeReported(batchPath, `${JSON.stringify(batch, null, 1)}\n`, { what: "--out-macro-batch" }) : { out: batchPath };
     return {
       candidates,
       known,
       leftOut,
       batch: {
-        out: batchPath,
+        ...written,
         writes: batch.length,
         ...(other.size === 0 ? {} : { otherMacros: [...other].map((name) => `The knowledge has another macro ${name}: its candidates are not in the batch.`) }),
         ...(batch.length === 0 ? {} : { apply: `knowledge.ts apply ${batchPath} --reason "macro uses of 6502 idioms"` }),
@@ -154,16 +119,6 @@ function withRemedy(reason: string): string {
     : reason;
 }
 
-function addresses(values: string[] | undefined, option: string): number[] {
-  return (values ?? []).map((value) => {
-    try {
-      return parseC64Address(value);
-    } catch {
-      throw new UsageError(`${option} must be $ followed by four hex digits, not ${value}`);
-    }
-  });
-}
-
 /** One conflict: what the knowledge has, and what the analyzer found, under the analyzer's name. */
 function showConflict(conflict: ImportConflict, analyzer: Analyzer): Record<string, unknown> {
   if (conflict.category === "symbol") {
@@ -192,8 +147,8 @@ function record(findings: NormalizedFindings, revision: string, description: str
   try {
     imported = withWrite((db) => importFindings(db, findings, { expectedRevision: revision, description, ...provenance }));
   } catch (error) {
-    if (error instanceof KnowledgeError && error.code === "stale-revision") {
-      throw new KnowledgeError("stale-revision", "The knowledge changed during the analysis. Nothing was imported. Run the analysis again.");
+    if (error instanceof Refusal && error.code === "stale-revision") {
+      throw new Refusal("stale-revision", "The knowledge changed during the analysis. Nothing was imported. Run the analysis again.");
     }
     throw error;
   }
@@ -204,55 +159,19 @@ function record(findings: NormalizedFindings, revision: string, description: str
   };
 }
 
-async function run(argv: string[]): Promise<unknown> {
-  const { values, positionals } = parseArgs({
-    args: argv,
-    strict: true,
-    allowPositionals: true,
-    options: {
-      analyzer: { type: "string" },
-      entry: { type: "string", multiple: true },
-      decompile: { type: "string", multiple: true },
-      listing: { type: "string" },
-      "max-listed": { type: "string" },
-      instructions: { type: "string" },
-      space: { type: "string" },
-      "macro-batch": { type: "string" },
-      help: { type: "boolean" },
-    },
-  });
-  if (values.help) throw new UsageError("");
-  if (positionals.length !== 0) throw new UsageError("analyze takes no image: it reads the program from the knowledge (knowledge.ts image of the c64-knowledge skill puts it in)");
-  const entries = addresses(values.entry, "--entry");
-  const decompile = addresses(values.decompile, "--decompile");
+async function analyze(call: Call): Promise<unknown> {
+  const entries = call.addresses("entry");
+  const decompile = call.addresses("decompile");
   if (decompile.length > 32) throw new UsageError("--decompile takes at most 32 routines");
-  const maxListed = values["max-listed"] ?? String(DEFAULT_MAX_LISTED);
-  if (!/^\d{1,5}$/.test(maxListed)) throw new UsageError(`--max-listed must be a whole number, not ${maxListed}`);
-  const max = Number(maxListed);
-  const analyzer = values.analyzer ?? "ghidra";
-  if (analyzer !== "dxa" && analyzer !== "ghidra") throw new UsageError(`--analyzer must be dxa or ghidra, not ${analyzer}`);
+  const max = call.count("max-listed")!;
+  const analyzer = call.string("analyzer") as "dxa" | "ghidra";
+  const listingPath = call.string("out-listing");
+  const instructionsPath = call.string("out-instructions");
+  const batchPath = call.string("out-macro-batch");
   if (analyzer === "dxa" && decompile.length > 0) throw new UsageError("--decompile works only with --analyzer ghidra");
-  if (analyzer === "ghidra" && values.listing !== undefined) throw new UsageError("--listing works only with --analyzer dxa");
-  if (analyzer === "dxa" && values.instructions !== undefined) throw new UsageError("--instructions works only with --analyzer ghidra");
-  let listingPath: string | undefined;
-  if (values.listing !== undefined) {
-    try {
-      listingPath = resolveProjectPath(values.listing);
-    } catch {
-      throw new UsageError(`--listing must be a path relative to the project folder that stays inside it, not ${values.listing}`);
-    }
-  }
-
-  if (values["macro-batch"] !== undefined) {
-    try {
-      resolveProjectPath(values["macro-batch"]);
-    } catch {
-      throw new UsageError(`--macro-batch must be a path relative to the project folder that stays inside it, not ${values["macro-batch"]}`);
-    }
-  }
-
-  const space = values.space ?? DEFAULT_SPACE;
-  if (!SPACE.test(space)) throw new UsageError("--space must be c64, drive8, or bank0 to bank255");
+  if (analyzer === "ghidra" && listingPath !== undefined) throw new UsageError("--out-listing works only with --analyzer dxa");
+  if (analyzer === "dxa" && instructionsPath !== undefined) throw new UsageError("--out-instructions works only with --analyzer ghidra");
+  const space = call.space;
   const reader = openForRead();
   const program = requireProgram(reader, space);
   // A coverage map is of the C64 CPU: VICE keeps none for the drive.
@@ -296,7 +215,7 @@ async function run(argv: string[]): Promise<unknown> {
   const idiomsResult = () => {
     const imported = withWrite((db) => importFindings(db, { ...idioms.findings, space }, { description: "Idioms in the program" }));
     // The macro candidates read the code regions after both imports.
-    const macros = macroCandidates(space, byteAt, values["macro-batch"]);
+    const macros = macroCandidates(space, byteAt, batchPath);
     // Platform pitfalls are C64 facts: drive code and banks get none.
     const pitfallDb = openForRead();
     const pitfalls = space === DEFAULT_SPACE ? findPitfalls(byteAt, listRegions(pitfallDb, undefined, "code", undefined, space)) : [];
@@ -314,7 +233,7 @@ async function run(argv: string[]): Promise<unknown> {
           pointers: listed(pointers, max, showPointer, "a larger --max-listed"),
           pitfalls: listed(pitfalls, max, showPitfall, "a larger --max-listed"),
           macros: {
-            ...listed(macros.candidates, max, showMacro, "a larger --max-listed, or --macro-batch <file>"),
+            ...listed(macros.candidates, max, showMacro, "a larger --max-listed, or --out-macro-batch <file>"),
             ...(macros.known === 0 ? {} : { known: macros.known }),
             ...(macros.leftOut === 0 ? {} : { leftOut: macros.leftOut }),
             ...(macros.batch === undefined ? {} : { batch: macros.batch }),
@@ -344,13 +263,13 @@ async function run(argv: string[]): Promise<unknown> {
     const listing = attachments[0]!.toString("utf8");
     // The listing is written only after the import: a refused import leaves no new file.
     const imported = record({ ...dxaFindings(result), space, ...executed }, revision, "DXA analysis of the program", runProvenance(bytes, result.toolVersion));
+    let written: ReturnType<typeof writeReported> | undefined;
     if (listingPath !== undefined) {
       try {
-        mkdirSync(dirname(listingPath), { recursive: true });
-        writeFileSync(listingPath, listing);
+        written = writeReported(listingPath, listing, { what: "--out-listing" });
       } catch (error) {
         const recorded = imported.revision === null ? "The knowledge did not change." : `The knowledge has the findings as revision ${imported.revision}.`;
-        throw new WireFailure("operation-failed", `The script did not write the listing to ${values.listing}: ${(error as Error).message}. ${recorded}`);
+        throw new WireFailure("operation-failed", `The script did not write the listing to ${listingPath}: ${(error as Error).message}. ${recorded}`);
       }
     }
     const found = idiomsResult();
@@ -363,7 +282,7 @@ async function run(argv: string[]): Promise<unknown> {
       ...imported,
       regions: result.regions.map((region) => ({ start: formatC64Address(region.start), end: formatC64Address(region.end), classification: region.classification })),
       labels: listed(result.labels, max, (label) => ({ address: formatC64Address(label.address), name: label.name }), "c64-knowledge: knowledge.ts symbols"),
-      ...(listingPath === undefined ? {} : { listing: values.listing }),
+      ...(written === undefined ? {} : { listing: written }),
     };
   }
 
@@ -378,11 +297,10 @@ async function run(argv: string[]): Promise<unknown> {
   const overlaps = listRegions(overlapDb, undefined, "dual-use", undefined, space);
   overlapDb?.close();
   const gaps = coverage === undefined ? [] : executedStarts(coverage, inProgram).filter((address) => address >= loaded.start && address <= loaded.end && !decoded.has(address) && !overlaps.some((region) => address >= region.start && address <= region.end));
-  let instructions: { out: string; count: number } | undefined;
-  if (values.instructions !== undefined) {
+  let instructions: Record<string, unknown> | undefined;
+  if (instructionsPath !== undefined) {
     const list = instructionList(result.instructions, coverage);
-    writeProjectFile(values.instructions, Buffer.from(`${JSON.stringify(list, null, 1)}\n`), { what: "--instructions" });
-    instructions = { out: values.instructions, count: list.length };
+    instructions = { count: list.length, ...writeReported(instructionsPath, `${JSON.stringify(list, null, 1)}\n`, { what: "--out-instructions" }) };
   }
   return {
     analyzer: "ghidra",
@@ -401,4 +319,26 @@ async function run(argv: string[]): Promise<unknown> {
   };
 }
 
-await runScript((argv) => run(argv), { usage: USAGE, refusals: [KnowledgeError] });
+await runScript({
+  name: "static-analysis",
+  summary: "Analyzes the program in the knowledge with DXA or Ghidra, seeded from the knowledge and its coverage, and imports the structural findings into the knowledge.",
+  names: knowledgeNames,
+  commands: [
+    {
+      name: "analyze",
+      summary: "Runs the analyzer over the program in the knowledge and imports what it finds as one revision, then the 6502 idioms as a second one.",
+      options: {
+        analyzer: { kind: "choice", value: "<dxa|ghidra>", choices: ["dxa", "ghidra"], default: "ghidra", help: "dxa (a fast first pass) or ghidra (deeper, the default)" },
+        entry: { ...OPTIONS.entry, multiple: true, help: "an entry point of the program" },
+        decompile: { kind: "address", value: "<address>", multiple: true, help: "ghidra: a routine to decompile, at most 32" },
+        space: OPTIONS.space,
+        "max-listed": { ...OPTIONS["max-listed"], help: "list at most n labels, functions or candidates (default 50, 0 for none). The counts are always given, and the knowledge has all labels and functions" },
+        "out-listing": { kind: "path", value: "<file>", help: "dxa: write the disassembly listing to this project file" },
+        "out-instructions": { kind: "path", value: "<file>", help: "ghidra: write every instruction (address, bytes, mnemonic, mode, operand, target, executed) to this project file as JSON" },
+        "out-macro-batch": { kind: "path", value: "<file>", help: "write the macro candidates as an apply batch of c64-knowledge (the macros and their uses) to this project file" },
+      },
+      notes: "The program and the coverage come from the knowledge: put them in with knowledge.ts image and coverage of the c64-knowledge skill. The executed code of the coverage is seeded. Routine symbols in the knowledge are entry points too. Ghidra needs at least one entry point. DXA finds the SYS of a BASIC start by itself.",
+      run: analyze,
+    },
+  ],
+});