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

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

@@ -3,7 +3,7 @@
 // the bytes from coverage files, and the references in and out. Nothing here
 // reads files: knowledge.ts gives the lookups.
 
-import { COVERAGE } from "#src/c64.ts";
+import { COVERAGE, formatC64Address, formatC64Byte } from "#src/c64.ts";
 import { MODE_LENGTH, OPCODES, type Mode } from "#src/opcodes.ts";
 
 export interface ListingSource {
@@ -41,8 +41,6 @@ export interface ListingLine {
 }
 
 const CODE = new Set(["code", "jumps"]);
-const hex2 = (value: number) => `$${value.toString(16).padStart(2, "0")}`;
-const hex4 = (value: number) => `$${value.toString(16).padStart(4, "0")}`;
 const DATA_PER_LINE = 8;
 
 /** The access class of bytes from the coverage: x, r and w as they occur, or - for none. */
@@ -57,12 +55,12 @@ function accessOf(coverage: Uint8Array | undefined, start: number, length: numbe
 /** The operand of an instruction in ACME syntax, with the name of its target where one exists. */
 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 ? hex2(target) : hex4(target));
+  const named = (target: number, digits: 2 | 4) => nameOf(target) ?? (digits === 2 ? formatC64Byte(target) : formatC64Address(target));
   switch (mode) {
     case "imp":
       return "";
     case "imm":
-      return `#${hex2(low)}`;
+      return `#${formatC64Byte(low)}`;
     case "zp":
       return named(low, 2);
     case "zpx":
@@ -138,7 +136,7 @@ export function listing(source: ListingSource, start: number, end: number): List
       values.push(source.byteAt(at)!);
       at++;
     }
-    if (address >= start) lines.push(line(address, values.length, `!byte ${values.map(hex2).join(",")}`));
+    if (address >= start) lines.push(line(address, values.length, `!byte ${values.map(formatC64Byte).join(",")}`));
     address = at;
   }
   return lines;
@@ -149,7 +147,7 @@ export function listingText(lines: readonly ListingLine[]): string {
   const out: string[] = [];
   for (const item of lines) {
     for (const comment of item.lineComments ?? []) out.push(`                         ; ${comment}`);
-    const head = `${hex4(item.address)}  ${item.bytes.padEnd(9)} ${(item.access ?? "").padEnd(3)}`;
+    const head = `${formatC64Address(item.address)}  ${item.bytes.padEnd(9)} ${(item.access ?? "").padEnd(3)}`;
     const body = (item.label === undefined ? "" : `${item.label} `).padEnd(20) + item.text;
     const notes = [
       ...(item.comment === undefined ? [] : [item.comment]),

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

@@ -21,10 +21,10 @@ This skill does not read the emulator and does not change project knowledge.
 The script looks up local reference data. It does not use the host runtime.
 
 ```
-node <skill>/scripts/memmap.ts at '$d020' '$0314' '$ffd2'
-node <skill>/scripts/memmap.ts decode '$d018' '$15' --bank '$97'
-node <skill>/scripts/memmap.ts list vic
-node <skill>/scripts/memmap.ts export --out src/hw.asm
+node <skill>/scripts/memory-map.ts at '$d020' '$0314' '$ffd2'
+node <skill>/scripts/memory-map.ts decode '$d018' '$15' --bank '$97'
+node <skill>/scripts/memory-map.ts list vic
+node <skill>/scripts/memory-map.ts export --out src/hw.asm
 ```
 
 | Command | Result |
@@ -34,16 +34,26 @@ node <skill>/scripts/memmap.ts export --out src/hw.asm
 | `list <vic\|sid\|cia1\|cia2\|kernal\|system>` | All entries of that group. |
 | `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 an address or a value as `$` and hex digits, as a decimal number, or as `%` and binary digits. Put a `$` value in single quotes in a shell.
+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.
 
-The script prints one JSON object.
+### 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`.
 
@@ -71,9 +81,7 @@ A conclusion about the application can be project knowledge. For example: "the p
 
 ## Result
 
-The platform meaning of each address, or the decoded meaning of a register value. For `export`: the file, the count of names and the bytes.
-
-The exit status is 0 for a result. The exit status is 2 for a wrong argument.
+The platform meaning of each address, or the decoded meaning of a register value. For `export`: the count of names in `names`, and the file as `{out, bytes, sha256}`.
 
 ## Failure and conflicts
 

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

@@ -0,0 +1,81 @@
+// The c64-memory-map script: the platform meaning of C64 addresses and of
+// values in platform registers. Local lookup only; nothing is stored. export
+// writes the platform names to a project file as an ACME include.
+
+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";
+
+const show = (entry: Entry) => ({ start: formatC64Address(entry.start), ...(entry.end !== entry.start ? { end: formatC64Address(entry.end) } : {}), name: entry.name, meaning: entry.meaning });
+
+const LISTS: Record<string, () => Entry[]> = {
+  vic: () => IO[0]!.registers,
+  sid: () => IO[1]!.registers,
+  cia1: () => IO[2]!.registers,
+  cia2: () => IO[3]!.registers,
+  kernal: () => ROM,
+  system: () => SYSTEM,
+};
+
+await runScript({
+  name: "memory-map",
+  summary: "The platform meaning of C64 addresses and of values in platform registers.",
+  names: knowledgeNames,
+  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 }],
+      run: (call) => ({
+        addresses: call.subjects.map((text) => {
+          const found = lookup(call.parseAddress(text, "<address>"));
+          // The chip registers, color RAM and the cartridge I/O areas show only while $01 maps I/O in.
+          const io = found.address >= 0xd000 && found.address <= 0xdfff;
+          return {
+            ...found,
+            address: formatC64Address(found.address),
+            ...(found.mirrorOf === undefined ? {} : { mirrorOf: formatC64Address(found.mirrorOf) }),
+            ...(found.entryStart === undefined ? {} : { entryStart: formatC64Address(found.entryStart) }),
+            ...(io ? { visible: "when $01 shows I/O at $D000 (the default)" } : {}),
+          };
+        }),
+      }),
+    },
+    {
+      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: "<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 } },
+      run: (call) => {
+        const register = call.parseAddress(call.subject(0), "<register>");
+        const value = call.parseNumber(call.subject(1), "<value>", 0, 0xff);
+        return { register: formatC64Address(register), value: formatC64Byte(value), name: lookup(register).name, ...decode(register, value, call.count("bank")) };
+      },
+    },
+    {
+      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(", ")}` }],
+      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) };
+      },
+    },
+    {
+      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 } },
+      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}`)];
+        return { names: names.length, ...writeReported(call.string("out")!, `${lines.join("\n")}\n`, { what: "--out" }) };
+      },
+    },
+  ],
+});

package/skills/c64-provenance/SKILL.md

@@ -17,7 +17,7 @@ This skill does not change project knowledge.
 
 ## Inputs
 
-- Two or more releases, relative to the project folder. A release is a PRG file or an `image.json` from c64-unpacker capture. Extract releases from disk images with the c64-disk skill. Unpack packed releases with the c64-unpacker skill first.
+- Two or more releases, relative to the project folder. A release is `knowledge` (the program in the knowledge), a PRG file, or an `image.json` from c64-unpacker capture with its `entry_state.json` beside it. Extract releases from disk images with the c64-disk skill. Unpack packed releases with the c64-unpacker skill first.
 - Optional: an address range to compare.
 - Optional: a shift for a release that loads at a different address.
 - Optional: a number of frames to run each release, and a steps file.
@@ -26,12 +26,12 @@ This skill does not change project knowledge.
 
 ## Tools / execution path
 
-The script compares the files locally. Only `--run` uses the host runtime: each release runs in its own emulator.
+The script compares the releases locally. Only `--frames` uses the host runtime: each release runs in its own emulator.
 
 ```
-node <skill>/scripts/provenance.ts releases/a.prg releases/b.prg releases/c.prg
-node <skill>/scripts/provenance.ts releases/a.prg releases/b.prg --shift 2:-256 --from '$0900' --to '$09ff'
-node <skill>/scripts/provenance.ts releases/a.prg .c64-re-tools/local/b/image.json --run 600 --steps .c64-re-tools/local/start-game.json
+node <skill>/scripts/provenance.ts compare releases/a.prg releases/b.prg releases/c.prg
+node <skill>/scripts/provenance.ts compare releases/a.prg releases/b.prg --shift 2:-256 --range '$0900-$09ff'
+node <skill>/scripts/provenance.ts compare knowledge .c64-re-tools/local/b/image.json --frames 600 --steps .c64-re-tools/local/start-game.json
 node <skill>/scripts/provenance.ts separate --out .c64-re-tools/local/separate.json
 node <skill>/scripts/provenance.ts leftovers --out .c64-re-tools/local/leftovers.json
 ```
@@ -39,23 +39,34 @@ 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. |
-| `--from '$0900'` | Compare from this address. |
-| `--to '$09ff'` | Compare up to this address. |
-| `--run 600` | Run each release for this many frames, and give each listed difference its runtime evidence. |
-| `--steps steps/start-game.json` | With `--run`: the action steps of the c64-unpacker steps file to run before the frames, for example a key to start the game. |
+| `--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. |
 
-The script puts each PRG at its load address. An image has bytes only in its segments. The script compares the addresses where all releases have bytes. It prints one JSON object.
+The script puts each PRG at its load address. An image has bytes only in its segments. The script compares the addresses where all releases have bytes.
 
 With `--shift`, the addresses of `segments`, `common` and `differences` are the release addresses plus the `shift` of the release. The `start` and `end` of `runtime` are the addresses in the release itself, without the shift.
 
-With `--run`, a PRG starts with autostart and RUN. An image starts from its bytes: the script writes the segments and the entry state from `entry_state.json` into the emulator, and starts at the entry. Watchpoints on each difference stop the run at its first access.
+With `--frames`, a PRG starts with autostart and RUN. An image starts from its bytes: the script writes the segments and the entry state from `entry_state.json` into the emulator, and starts at the entry. Watchpoints on each difference stop the run at its first access.
+
+### 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`.
 
@@ -66,7 +77,7 @@ With `--run`, a PRG starts with autostart and RUN. An image starts from its byte
 
    `suggestedShifts` has at most 3 shifts for each release. The shift with the most `matchingSequences` is first. Data that did not move and code that moved give different shifts. Try each shift. `current: true` marks the shift of this run.
 3. Read `differences`. Each one has an address range, the bytes of each release, and `groups`: the releases that have the same bytes there.
-4. To know how the program uses the differences, run the script again with `--run` and the frames that get the program to the part you examine. Read `runtime` of each difference:
+4. To know how the program uses the differences, run the script again with `--frames` and the frames that get the program to the part you examine. Read `runtime` of each difference:
    - `first`: the first access in that release: `read`, `write`, `execute` or `none`. An instruction that reads and then writes the same byte, for example INC, counts as `read`. The operand bytes of an executed instruction count as `execute`, for example the value of `LDA #$03`.
    - `changed`: `true` when the bytes at the end of the run are not the bytes of the release.
    - A range that each release writes before it reads is probably runtime state, not a difference of the releases.
@@ -88,7 +99,7 @@ Use `separate` when you have only one release. It reads the program, its stages
 - `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.
 - `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`. `--out` writes all of them. Run more coverage runs for parts that are `untouched`, and add them with `coverage` of the c64-knowledge skill, before you decide.
+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.
 
 ## Leftovers
 
@@ -136,18 +147,18 @@ Read the findings with care:
 
 A library is a folder of routine files. Each file holds one routine: its bytes and its knowledge. Keep one library beside the project folders, for example `library/` at the root of the workspace. A library is not a project folder. Commit it with the projects.
 
-`--library` is relative to the working directory, as `--project`. All other paths are relative to the project folder.
+`--library` is relative to the project folder, as all other paths. For example, `../library` is the folder `library/` beside the project.
 
 ```
-node <skill>/scripts/provenance.ts routine --module '$1000' --library library --project game-a
-node <skill>/scripts/provenance.ts routine --start '$1000' --end '$1026' --name play --library library --project game-a
-node <skill>/scripts/provenance.ts match --library library --out .c64-re-tools/local/match.json --project game-b
+node <skill>/scripts/provenance.ts routine '$1000' --library ../library --project game-a
+node <skill>/scripts/provenance.ts routine '$1000-$1026' --name play --library ../library --project game-a
+node <skill>/scripts/provenance.ts match --library ../library --out .c64-re-tools/local/match.json --project game-b
 ```
 
 To save a routine:
 
 1. Put the program into the knowledge, and name the routine there first. The file keeps the user and LLM names, comments, regions, references and operand expressions in the range. It also keeps the code regions of each origin.
-2. Run `routine` with the start of a module (`--module`), or with `--start` and `--end`. A module ends at the next module or at the end of its segment.
+2. Run `routine` with the start address of a module, or with a range `<start>-<end>`. A module ends at the next module or at the end of its segment.
    - `--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.
@@ -159,7 +170,7 @@ To find the routines in a program:
    - The opcodes and the other bytes must be equal.
    - An address into the routine must point into the routine at its new address. `shift` is the address in the program minus the address in the library.
    - An operand that addresses something outside the routine can be different. `differing` lists each one with its value in the library and in the program. Examine them. For example, the program can use other variables or another SID voice.
-2. Give `--out` to get a batch for `knowledge.ts apply`. The batch has the names, regions, comments, references and operand expressions of each routine at its addresses in the program. `match` does not change the knowledge.
+2. Give `--out` to get a batch for `knowledge.ts apply`. `batch` shows the file as `{out, bytes, sha256}`. The batch has the names, regions, comments, references and operand expressions of each routine at its addresses in the program. `match` does not change the knowledge.
 3. Read `batch.leftOut` before you apply the batch. The script leaves out a write in these conditions:
    - The program has a user or LLM row at that place.
    - The program uses the name at another address.
@@ -179,14 +190,12 @@ Record a confirmed conclusion as a normal comment, region or symbol with the c64
 
 ## Result
 
-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 `--run`, each difference also has `runtime`, and `run` tells if each release started, or why not.
+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.
 
 The runtime evidence and the leftovers are evidence only. The script does not decide which bytes are original.
 
-The exit status is 0 for a result. The exit status is 1 for an error. The exit status is 2 for a wrong argument.
-
 ## Failure and conflicts
 
 - Do not call releases independent when you do not know their relation. Two cracks can come from the same source.
@@ -194,7 +203,7 @@ The exit status is 0 for a result. The exit status is 1 for an error. The exit s
 - `common` is empty: the releases do not cover the same addresses. Use `--shift`, or compare a range that all releases cover.
 - `run.releases` shows `started: false`: a PRG without a BASIC start, or an image without `entry_state.json`. The reason tells which. The other releases still give evidence.
 - `installation-incomplete`, or `machine-unavailable` with a message that the host runtime does not run: stop the task. Give the message to the user and wait for the user. The message gives the remedy. Do not make a replacement for the tool or the host runtime, for example your own emulator script.
-- `moreDifferences: true`: the script shows only the first differences. Use `--from` and `--to` to see the others.
+- `moreDifferences: true`: the script shows only the first differences. Use `--range` to see the others.
 - `not-found`: the project has no file at that path.
 - `not-found` from `match`: the library folder does not exist, or it has no routine files. Save a routine with `routine` first.
 - `conflict` from `routine`: the library has a routine with that name. Give another `--name`, or give `--replace` to save over it.

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

@@ -5,15 +5,12 @@
 // releases differ and which releases agree there. It never decides which
 // bytes are original: that needs evidence beyond one comparison.
 
-export interface Range {
-  start: number;
-  end: number;
-}
+import { type AddressRange, formatC64Address } from "#src/c64.ts";
 
 export interface Release {
   name: string;
   /** Where the release has bytes, after the shift, in address order. */
-  segments: Range[];
+  segments: AddressRange[];
   /** The byte at an address inside a segment. */
   byteAt: (address: number) => number;
 }
@@ -29,7 +26,7 @@ export interface DifferingRange {
 
 export interface Comparison {
   /** The addresses where every release has bytes. */
-  common: Range[];
+  common: AddressRange[];
   identicalBytes: number;
   differingBytes: number;
   differences: DifferingRange[];
@@ -43,8 +40,8 @@ const JOIN_GAP = 4;
 export const covers = (release: Release, address: number) => release.segments.some((segment) => address >= segment.start && address <= segment.end);
 
 /** The ranges where every release has bytes, inside from..to. */
-export function commonRanges(releases: Release[], from = 0x0000, to = 0xffff): Range[] {
-  const ranges: Range[] = [];
+export function commonRanges(releases: Release[], from = 0x0000, to = 0xffff): AddressRange[] {
+  const ranges: AddressRange[] = [];
   for (let address = from; address <= to; address++) {
     if (!releases.every((release) => covers(release, address))) continue;
     const last = ranges.at(-1);
@@ -67,7 +64,7 @@ export function compareReleases(releases: Release[], options: { from?: number; t
   }
   // A joined range stays inside one common range, so every release has all of its bytes.
   const inSameCommon = (a: number, b: number) => common.some((range) => a >= range.start && b <= range.end);
-  const ranges: Range[] = [];
+  const ranges: AddressRange[] = [];
   for (const address of differing) {
     const last = ranges.at(-1);
     if (last !== undefined && address - last.end <= JOIN_GAP && inSameCommon(last.start, address)) last.end = address;
@@ -137,9 +134,8 @@ export type ShiftSuggestion = { release: number; shift: number; matchingSequence
  */
 export function shiftSuggestion(releases: Release[], applied: number[], index: number, found: { shift: number; matches: number }): ShiftSuggestion {
   const outside = (release: Release, by: number) => release.segments.find((segment) => segment.start + by < 0 || segment.end + by > 0xffff);
-  const hex = (value: number) => `$${value.toString(16).padStart(4, "0")}`;
-  const why = (number: number, by: number, segment: Range) =>
-    `release ${number} moved by ${by} puts ${hex(segment.start)}-${hex(segment.end)} ${segment.start + by < 0 ? "below $0000" : "past $ffff"}`;
+  const why = (number: number, by: number, segment: AddressRange) =>
+    `release ${number} moved by ${by} puts ${formatC64Address(segment.start)}-${formatC64Address(segment.end)} ${segment.start + by < 0 ? "below $0000" : "past $ffff"}`;
   const own = outside(releases[index]!, found.shift);
   if (own === undefined) return { release: index + 1, shift: applied[index]! + found.shift, matchingSequences: found.matches };
   const reasons = [why(index + 1, found.shift, own)];

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

@@ -6,13 +6,12 @@
 // its bytes from the separation. Evidence only: nothing here decides what a
 // leftover is or who made it.
 
-import { basicLineText } from "#src/c64.ts";
+import { type AddressRange, basicLineText } from "#src/c64.ts";
 import { MNEMONICS } from "#src/opcodes.ts";
-import type { Range } from "./compare.ts";
 import type { Access, Separation } from "./separate.ts";
 
 export interface LeftoversInput {
-  segments: Range[];
+  segments: AddressRange[];
   /** 64 KiB with the program bytes at their addresses. */
   memory: Uint8Array;
   separation: Separation;
@@ -33,7 +32,7 @@ export interface Placement {
 /** high-bit is text with bit 7 set: ASCII as the Apple II keeps it, or C64 shifted letters with $a0 spaces. Its spaces can also be $20. */
 export type TextEncoding = "petscii" | "screen" | "ascii" | "high-bit";
 
-export interface TextFinding extends Range, Placement {
+export interface TextFinding extends AddressRange, Placement {
   encoding: TextEncoding;
   /** Screen codes with bit 7 set: the characters show reversed. */
   reversed?: boolean;
@@ -45,26 +44,26 @@ export interface TextFinding extends Range, Placement {
   mnemonics?: number;
 }
 
-export interface BasicFinding extends Range, Placement {
+export interface BasicFinding extends AddressRange, Placement {
   /** The address of the first line where the links put it: where the lines were when BASIC linked them. */
   linkedAt: number;
   lines: string[];
 }
 
-export interface FillFinding extends Range, Placement {
+export interface FillFinding extends AddressRange, Placement {
   pattern: number[];
 }
 
 /** Untouched bytes that are no text, BASIC, fill or code region. */
-export type ResidueFinding = Range & Placement;
+export type ResidueFinding = AddressRange & Placement;
 
-export interface CopyFinding extends Range, Placement {
+export interface CopyFinding extends AddressRange, Placement {
   /** The first address of the same bytes earlier in the program. */
   copyOf: number;
 }
 
 /** A code region that no call or jump reaches from the entry, and that no run executed. */
-export interface DeadCodeFinding extends Range, Placement {
+export interface DeadCodeFinding extends AddressRange, Placement {
   type: string;
   /** false when the coverage shows that it did not run; absent without coverage. */
   executed?: false;
@@ -228,7 +227,7 @@ function ownEncoding(encoding: TextEncoding, bytes: number[], characters: Charac
 }
 
 /** The runs of one encoding in a segment that read as text. `reversed` reads the bytes with bit 7 set, without that bit. */
-function textRuns(memory: Uint8Array, segment: Range, encoding: TextEncoding, reversed: boolean, min: number): TextFinding[] {
+function textRuns(memory: Uint8Array, segment: AddressRange, encoding: TextEncoding, reversed: boolean, min: number): TextFinding[] {
   const decode = { petscii: petsciiOrLineEnd, screen: screenCharacter, ascii: asciiCharacter, "high-bit": highAsciiCharacter }[encoding];
   const found: TextFinding[] = [];
   let run: Array<{ address: number; character: Character }> = [];
@@ -276,10 +275,10 @@ function textRuns(memory: Uint8Array, segment: Range, encoding: TextEncoding, re
   return found;
 }
 
-export function findText(memory: Uint8Array, segments: Range[], min = MIN_TEXT): TextFinding[] {
+export function findText(memory: Uint8Array, segments: AddressRange[], min = MIN_TEXT): TextFinding[] {
   const scan = (encoding: TextEncoding, reversed = false) => segments.flatMap((segment) => textRuns(memory, segment, encoding, reversed, min));
   // A run that is mostly a run of an earlier list is the same text, read in another encoding, with stray bytes at its edges.
-  const overlap = (a: Range, b: Range) => Math.max(0, Math.min(a.end, b.end) - Math.max(a.start, b.start) + 1);
+  const overlap = (a: AddressRange, b: AddressRange) => Math.max(0, Math.min(a.end, b.end) - Math.max(a.start, b.start) + 1);
   const kept: TextFinding[] = [];
   for (const list of [[...scan("high-bit"), ...scan("ascii")], scan("petscii"), [...scan("screen"), ...scan("screen", true)]]) {
     kept.push(...list.filter((run) => !kept.some((other) => overlap(run, other) * 2 > run.end - run.start + 1)));
@@ -303,7 +302,7 @@ function tokensFit(tokens: Uint8Array): boolean {
  * a finding. The links give the address where BASIC put the lines, which can
  * be another address than where they are now.
  */
-export function findBasic(memory: Uint8Array, segments: Range[], basicStart?: number): BasicFinding[] {
+export function findBasic(memory: Uint8Array, segments: AddressRange[], basicStart?: number): BasicFinding[] {
   const found: BasicFinding[] = [];
   for (const segment of segments) {
     const word = (at: number) => memory[at]! | (memory[at + 1]! << 8);
@@ -348,7 +347,7 @@ export function findBasic(memory: Uint8Array, segments: Range[], basicStart?: nu
 }
 
 /** Runs of one byte of at least MIN_FILL bytes, and runs of a pattern of two to four bytes of at least twice that. */
-export function findFills(memory: Uint8Array, segments: Range[]): FillFinding[] {
+export function findFills(memory: Uint8Array, segments: AddressRange[]): FillFinding[] {
   const found: FillFinding[] = [];
   for (const segment of segments) {
     for (let at = segment.start; at <= segment.end; ) {
@@ -374,7 +373,7 @@ export function findFills(memory: Uint8Array, segments: Range[]): FillFinding[]
 }
 
 /** Exact copies of at least MIN_COPY bytes of an earlier range, with enough different byte values to be no fill. */
-export function findCopies(memory: Uint8Array, segments: Range[]): CopyFinding[] {
+export function findCopies(memory: Uint8Array, segments: AddressRange[]): CopyFinding[] {
   const found: CopyFinding[] = [];
   const seen = new Map<string, number>();
   const inside = (address: number) => segments.some((segment) => address >= segment.start && address <= segment.end);
@@ -399,8 +398,8 @@ export function findCopies(memory: Uint8Array, segments: Range[]): CopyFinding[]
 }
 
 /** Splits `range` at the parts that `taken` covers, and keeps the pieces of at least `min` bytes. */
-function without(range: Range, taken: Range[], min: number): Range[] {
-  const pieces: Range[] = [];
+function without(range: AddressRange, taken: AddressRange[], min: number): AddressRange[] {
+  const pieces: AddressRange[] = [];
   let start = range.start;
   for (const part of taken.filter((item) => item.start <= range.end && item.end >= range.start).sort((a, b) => a.start - b.start)) {
     if (part.start > start) pieces.push({ start, end: part.start - 1 });
@@ -413,19 +412,19 @@ function without(range: Range, taken: Range[], min: number): Range[] {
 export function findLeftovers(input: LeftoversInput): Leftovers {
   const { memory, segments, separation } = input;
   const ranges = separation.ranges;
-  const placement = (range: Range): Placement => {
+  const placement = (range: AddressRange): Placement => {
     const parts = ranges.filter((part) => part.start <= range.end && part.end >= range.start);
     const stages = [...new Set(parts.flatMap((part) => (part.stage === undefined ? [] : [part.stage])))].sort((a, b) => a - b);
     const access = [...new Set(parts.flatMap((part) => (part.access === undefined ? [] : [part.access])))];
     return { ...(stages.length === 0 ? {} : { stages }), ...(access.length === 0 ? {} : { access }) };
   };
-  const placed = <T extends Range>(items: T[]) => items.map((item) => ({ ...item, ...placement(item) }));
+  const placed = <T extends AddressRange>(items: T[]) => items.map((item) => ({ ...item, ...placement(item) }));
 
   const text = findText(memory, segments, input.minText);
   const basic = findBasic(memory, segments, input.basicStart);
   const fill = findFills(memory, segments);
   // Untouched bytes that no other finding explains.
-  const untouched: Range[] = [];
+  const untouched: AddressRange[] = [];
   for (const part of ranges) {
     if (part.access !== "untouched") continue;
     const last = untouched.at(-1);