@henols/c64-re-tools 2.0.0-rc.16 → 2.0.0-rc.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henols/c64-re-tools",
-  "version": "2.0.0-rc.16",
+  "version": "2.0.0-rc.18",
   "description": "Agent-friendly Commodore 64 engineering toolkit for reverse engineering, debugging, development and testing.",
   "license": "MIT",
   "author": "Henrik Olsson",

package/skills/c64-assembler/SKILL.md

@@ -43,7 +43,8 @@ The script prints one JSON object. The target CPU is the 6510. The output is a C
 
 - 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.
-- Keep the results, batches and step files that you save for yourself in `.c64-re-tools/local/` of the project. Git ignores that folder.
+- Keep the results, batches and step files that you use only one time in `.c64-re-tools/local/` of the project. Git ignores that folder.
+- Put a run file whose results are the evidence for a finding in `runs/`, with its results. Then git keeps the run file and the results, 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`.
 
 ## Workflow

package/skills/c64-basic/SKILL.md

@@ -29,7 +29,8 @@ The script prints one JSON object. Addresses are `$` and four hex digits.
 
 - 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.
-- Keep the results, batches and step files that you save for yourself in `.c64-re-tools/local/` of the project. Git ignores that folder.
+- Keep the results, batches and step files that you use only one time in `.c64-re-tools/local/` of the project. Git ignores that folder.
+- Put a run file whose results are the evidence for a finding in `runs/`, with its results. Then git keeps the run file and the results, 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`.
 
 ## Workflow

package/skills/c64-disk/SKILL.md

@@ -46,7 +46,8 @@ File names show the characters that the C64 shows in a directory list. A byte th
 
 - 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.
-- Keep the results, batches and step files that you save for yourself in `.c64-re-tools/local/` of the project. Git ignores that folder.
+- Keep the results, batches and step files that you use only one time in `.c64-re-tools/local/` of the project. Git ignores that folder.
+- Put a run file whose results are the evidence for a finding in `runs/`, with its results. Then git keeps the run file and the results, 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`.
 
 ## Workflow

package/skills/c64-docs/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: c64-docs
+description: Use this skill to write the documentation of a C64 program. The documentation explains the flows, state machines, tables, data formats and graphics, with links to the source lines and to the assets. A script generates the reference pages from the knowledge and the source. You write the other pages by the method of this skill. A second script adds the links to each name and address and checks every link. Use it after the source is identical, or to keep the documentation correct after a change to the knowledge.
+---
+
+# c64-docs
+
+## Purpose
+
+Write documentation that tells how a program works, and that points to the code. The documentation is Markdown in the project, for example in `docs/`. It has two parts:
+
+- **The reference.** `generate.ts` generates it from the knowledge, the source map of c64-source and the image. It has a page for each module. The page gives the routines, their callers and callees, the data and a call graph. It also has pages for the names, the variables, the tables, the memory map and the graphics. Do not edit these pages. The next run writes over them.
+- **The pages that you write.** They tell how the program works. They give the flows, the state machines, the data formats and the task of each part. Use the page types in `references/page-types.md` and the rules in `references/style.md`.
+
+`link.ts` connects the two parts. In each page that you write, a name in backticks gets a link to its line in the source. The address after the name gets a link to the entry of the name in the reference. When the source changes, `link.ts` moves the links to the new lines.
+
+This skill does not change the knowledge.
+
+## Inputs
+
+- The source directory of c64-source, with its `source-map.json`, for example `src`. The source must be from the current knowledge revision.
+- The image of the source, for example `unpacked/image.json`. It decodes the tables and shows the graphics.
+- The directory of the documentation, for example `docs`. The reference goes into a directory of its own, for example `docs/reference`.
+
+## Tools / execution path
+
+The scripts run on this machine. They do not use the emulator or the host runtime.
+
+```
+node <skill>/scripts/generate.ts --source src --out docs/reference --image unpacked/image.json
+node <skill>/scripts/link.ts docs --source src
+node <skill>/scripts/link.ts docs --source src --check
+```
+
+| Option | Meaning |
+|---|---|
+| `--source src` | The source directory of c64-source. Both scripts read `src/source-map.json`. |
+| `--out docs/reference` | The directory of the reference. `generate.ts` writes only there. It refuses to start when the directory holds a page that it did not write. |
+| `--image unpacked/image.json` | The image. Without it, the tables are not decoded and the graphics page has no images. |
+| `docs` | The directory of the documentation. `link.ts` reads every `.md` file below it. It changes only the pages that you wrote. It checks the pages of the reference. |
+| `--reference <dir>` | The directory of the reference for `link.ts`. The default is `docs/reference` when it exists. |
+| `--check` | `link.ts` writes nothing. It fails when a link is not up to date or a page has a problem. |
+
+### 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/`.
+- Give `--project <folder>` to each script when the working directory is not in the project.
+
+## Workflow
+
+1. Read the knowledge with the c64-knowledge skill. The documentation can only be as good as the knowledge. Each routine needs a name and a comment. Each table needs a region and a name. Each file of the source needs a module with a title. Record what is missing with c64-knowledge.
+2. Generate the source with c64-source. Make sure that `check.identical` is `true`. The script also writes `source-map.json`.
+3. Run `generate.ts`. Read `index.md` of the reference. A module with no routines, or a routine with no comment, shows what the knowledge does not have yet.
+4. Make the plan of the pages. Start from the modules and the call graphs. Find the main loop, the interrupt chain, the dispatch tables, the state machines and the data formats. Each subsystem gets one page. The entry page lists the pages. Use the page types in `references/page-types.md`.
+5. Write each page. Read the code and the knowledge for each fact. Run the program with c64-testing or c64-emulator when a fact needs a run. Write each name with its address, for example `` `draw_room` `$09BC` ``. Mark each fact with its evidence. Several subagents can write the pages at the same time, one page each. Give each subagent `references/page-types.md` and `references/style.md`.
+6. Record each new fact in the knowledge first: a name, a comment, a region or a module. Then the source and the reference show it too. A fact only in a page is lost at the next change of the knowledge.
+7. Run `link.ts`. Read `problems` and correct each one. Then run `link.ts --check`. Make sure that `problems.count` is 0 and that `notUpToDate.links` is 0.
+8. After each change to the knowledge, do steps 2, 3 and 7 again. The links then go to the new lines.
+
+## The links
+
+`link.ts` changes these forms in the pages that you write. It does not change a code block, a mermaid diagram or an HTML comment.
+
+| You write | `link.ts` writes |
+|---|---|
+| `` `draw_room` `$09BC` `` | `` [`draw_room`](../src/room_draw.asm#L6) [`$09BC`](reference/modules/room_draw.md#draw_room) `` |
+| `` `draw_room` (`$09BC`) `` | the same links, in the brackets |
+| `` `draw_room` `$0AAF` `` | `$0AAF` is a place inside `draw_room`. The address gets a link to its line in the source. |
+| `` `room_script_vars+3` `$4E9A` `` | a name with an offset. The address must be the address of the name plus the offset. |
+| `` `draw_room` `` | the name gets a link to its line. |
+
+- A name is a name of the knowledge or of the source. A word in backticks that is no name stays as it is.
+- In a list such as `` `a`/`b` `$1000`/`$1010` ``, each name gets its link. The addresses stay as they are.
+- `link.ts` writes a link again when its line moves. A link that you made to another target stays as you wrote it.
+- `link.ts` checks every link and image: the file must exist, a `#anchor` must exist in the page, and a `#L` line must exist in the file.
+
+## The reference
+
+- `index.md`: each file of the source with its range, title, the number of routines and the number of names.
+- `modules/<file>.md`: a call graph of the file, its data regions with their readers and writers, and an entry for each name. An entry has the comment, the callers, the table that holds it, and for a routine its calls, jumps, reads and writes.
+- `variables.md`: each name outside the image, with the routines that read it and write it.
+- `tables.md`: each table of addresses, jumps and words, entry by entry, with its target. An RTS table holds each target minus 1. The table gives the target.
+- `memory-map.md`: each region in address order.
+- `symbols.md`: each name in alphabetical order.
+- `graphics.md`: each `sprite`, `bitmap`, `charset` and `screen` region. A sprite, a bitmap or a charset shows in hires and in multicolour, because the knowledge has no graphics mode. A charset shows 16 characters in each row. A screen shows as text.
+
+### Images and assets
+
+- The reference draws each sprite, bitmap and charset region, and it decodes each table. To get the image of a graphic or the entries of a table, classify its region with c64-knowledge. Do not write a script that draws or decodes them.
+- A script of the project decodes only a format of the program, for example a packed map or a music stream. Put the script in `tools/` of the project. Its output files are the assets, for example in `assets/rooms/`.
+- When the code of the program makes the data, run that code in VICE with a run of c64-testing. Observe the memory, or capture the screen. Do not write a 6502 emulator in the script.
+
+In the call graph, a solid arrow is a call, a thick arrow is a table entry, and a dotted arrow is a jump. A table entry goes from each routine that reads the table to each target in code. A table of data addresses gives no arrow.
+
+## Knowledge
+
+Read:
+- symbols, regions, comments, references and modules of the space of the source.
+
+Automatic write:
+- none.
+
+Do not store:
+- the pages, or the facts that are only in the pages. Record each fact with c64-knowledge.
+
+## Result
+
+`generate.ts` gives one JSON object:
+
+- `out`, `index` and `revision`.
+- `pages`, `entries`, `tables`, `images` and `edges`: the counts of the reference.
+- `image`: the image, or a note when `--image` is not given.
+
+`link.ts` gives one JSON object:
+
+- `pages`: the count of the pages that it read.
+- `linked`: the count of the links that it wrote, and the pages that it changed. With `--check`, `notUpToDate` gives the links that are not up to date.
+- `problems`: `count`, `byKind` and the first 50 problems. Each problem has `at` (the page and the line), `kind` and `message`.
+
+The exit status is 0 when there is no problem. The exit status is 1 when there is a problem, or with `--check` when a link is not up to date. The exit status is 2 for a wrong argument.
+
+## Failure and conflicts
+
+- `not-found` for `source-map.json`: generate the source with c64-source. Then run the script again.
+- `invalid-input` that names an old revision: the knowledge changed after the source. Generate the source again, then run `generate.ts`.
+- `invalid-input` that names a page in the reference directory: the page is not a page of `generate.ts`. Move the page out of the directory. Do not give `--out` a directory with pages that you wrote.
+- `unknown-name`: the page uses a name that is not in the knowledge. Record the name with c64-knowledge, or correct the page.
+- `wrong-address`: the address after the name is not the address of the name, and it is not a place inside it. The message gives the routine that holds the address. Correct the name or the address. For a value, write `` `scroll_moves` = `$10` ``.
+- `missing-file`, `missing-anchor` or `missing-line`: a link goes to nothing. Correct the link. An image of an asset must exist in the project.
+- `stale-reference`: the source or the reference is older than the knowledge. Do steps 2 and 3 of the workflow again.
+- `conflict`: the knowledge has conflicts from a git merge. Run `knowledge.ts merge` of c64-knowledge.
+
+## Handoffs
+
+- Names, comments, regions and modules → c64-knowledge
+- The source and its source map → c64-source
+- A fact that needs a run → c64-testing or c64-emulator
+- What an address of the C64 is → c64-memory-map

package/skills/c64-docs/references/page-types.md

@@ -0,0 +1,113 @@
+# Page types
+
+Each page that you write is one of these types. The types come from the documentation of the Bruce Lee field run. Use the parts of a type that the program needs. Do not add a part with no content.
+
+## 1. The entry page
+
+One entry page for the program, for example `docs/README.md` or `docs/rooms.md` for one large subsystem. It has these parts, in this order:
+
+1. **One paragraph.** What the program is, and which release the documentation is for.
+2. **The table of pages.** One row for each page, with the link and one sentence about its content.
+3. **The layers.** A mermaid diagram of the layers of the program. The layers are the data, the code that runs one time, the main loop and the interrupts. Under the diagram, a numbered list tells how the layers work together.
+4. **The flow of a user.** A mermaid diagram of the steps of the player or user from start to end. An example is the order of the levels.
+5. **Findings.** A table of the facts that a reader does not expect, each with its evidence. Put a bug of the original program here.
+6. **The reference.** A link to `reference/index.md`.
+7. **Still open.** What is not known yet, and which run can find it.
+
+```markdown
+# <Program>: <subject>
+
+<What the program is. The release. What this documentation covers.>
+
+| Page | Content |
+|---|---|
+| [parts/main_loop.md](parts/main_loop.md) | **The main loop.** <one sentence> |
+
+## 1. The layers
+
+~~~mermaid
+flowchart TB
+  subgraph DATA["Data"]
+  ...
+~~~
+
+## 2. Findings
+
+| Finding | Evidence |
+|---|---|
+| <fact> | Observed: <what run showed it> |
+
+## 3. Still open
+
+- <question> — <the run that can answer it>
+```
+
+## 2. The subsystem page
+
+One page for each subsystem, for example the main loop, the interrupt chain, the room generation or the sound player. It has these parts:
+
+1. **The scope.** A list of what the page covers, and the sources (the source files, the assets).
+2. **The conventions.** The terms of the page, for example "a pass is one run of `main_loop` `$1BC2`". Also the evidence labels. Use the conventions block of section 5.
+3. **The overview.** A short text diagram or a mermaid flowchart of the calls, from the entry of the subsystem to its end.
+4. **The catalogue.** A table of the data of the subsystem. Each row has the name, the address, the layout (bytes, entries, the meaning of each byte), the readers and the writers.
+5. **The step-by-step walk.** For each main routine: a numbered list of what it does, in the order of the code. Each step gives the names and addresses. Add pseudo-code when a loop or a condition is not clear from the list.
+6. **The state machine.** For code that changes from one state to another: a mermaid `stateDiagram-v2` and a transition table. The transition table has the state, the condition, the next state and the code that makes the change.
+7. **The worked example.** One real case decoded by hand from the image, byte by byte. For example the first bytes of the map of level 1, and the screen cells that they give.
+8. **Still open.**
+
+```markdown
+## 3. The state machine of <thing>
+
+~~~mermaid
+stateDiagram-v2
+  state "Waiting ($00)" as Wait
+  state "Moving ($01)" as Move
+  [*] --> Wait
+  Wait --> Move: timer = 0
+~~~
+
+| State | Condition | Next state | Code |
+|---|---|---|---|
+| Waiting `$00` | `move_timer` = 0 | Moving `$01` | `update_slider` `$3F8C` |
+```
+
+## 3. The entity sections
+
+A program often has many items of one kind: levels, rooms, enemies, tunes. Give each item one section of the same form, in a page for a group of items. Each section has these parts:
+
+1. **The description.** What the item is, in one paragraph. Embed the image of the item when an asset or the reference has one.
+2. **The data.** The table rows of the item: its entries in each table, with the values.
+3. **The setup.** What the init handler of the item does, step by step.
+4. **The behaviour.** What the frame handler of the item does: a state diagram and a transition table.
+5. **The links to other items.** The conditions in other items that change this item, for example a door that opens when another room is empty.
+
+End the group page with a table of the dependencies between the items.
+
+## 4. The data-format page
+
+One page for each format of data, for example a packed map, a music stream or a sprite format. It has these parts:
+
+1. **Where the data is.** The table of pointers, the range of the data, and the routine that reads it.
+2. **The byte layout.** A table of each byte or bit field, with its meaning. For a stream: each command byte, its arguments and what it does.
+3. **The decoder.** Pseudo-code of the routine that reads the format.
+4. **A worked example.** The first bytes of one item, decoded by hand.
+5. **The assets.** A link to the extracted files and images, for example `../assets/rooms/room00.png`. Embed the image.
+
+```markdown
+| Byte | Meaning |
+|---|---|
+| `$80` | End of the stream. |
+| `$81-$FF` | The next `b & $7F` bytes are cells. |
+| `$01-$7F` | The next byte, `b` times. |
+```
+
+## 5. The conventions block
+
+Put this block near the top of each subsystem page. Change the terms for the program.
+
+```markdown
+**Conventions.**
+- Addresses are C64 addresses. Names are the names of the knowledge.
+- A *pass* is one run of `main_loop` `$1BC2`. A *frame* is one raster interrupt.
+- **Observed** marks a fact that a run showed. **Code** marks a fact from the code only. **Conclusion** marks an interpretation.
+```

package/skills/c64-docs/references/style.md

@@ -0,0 +1,43 @@
+# Style of the pages
+
+These rules apply to each page that you write. `link.ts` checks the rules that a script can check.
+
+## Names and addresses
+
+- Write each routine, table and variable with its name and its address: `` `draw_room` `$09BC` ``. `link.ts` gives the name a link to its line, and the address a link to its entry in the reference.
+- Use the name of the knowledge. Do not make a name that is only in the page. When a part has no good name, record a name with c64-knowledge first.
+- For a place inside a routine, write the name of the routine and the address of the place: `` `draw_room` `$0A04` ``. The address gets a link to its line.
+- For a byte inside a table or a variable, write the name with an offset: `` `room_script_vars+3` `$4E9A` ``.
+- For a value, write an equals sign: `` `scroll_moves` = `$10` ``. Without the sign, `link.ts` reads `$10` as an address.
+- Write addresses with `$` and hex digits in upper case: `$09BC`. Write values in hex with `$`, or in decimal without `$`.
+- Write a range with a hyphen: `` `$4E97-$4E9B` ``.
+- Write the name and the address in backticks. A name without backticks gets no link.
+
+## Evidence
+
+- Mark each fact with its evidence, as text:
+  - **Observed**: a run showed it.
+  - **Code**: the code shows it, and no run showed it.
+  - **Conclusion**: an interpretation of the facts.
+- Do not link to the files of a run. The run files are not part of the documentation. Name the run in the text when it helps a reader to do the run again.
+- Do not write a fact that you did not check in the code, the knowledge or a run. Put a question in **Still open**.
+
+## Diagrams and images
+
+- Use mermaid for the diagrams: `flowchart` for calls and data flow, `stateDiagram-v2` for state machines. Write the name and the address in each node: `"draw_room $09BC"`.
+- A diagram gets no links. Give the links in a table or a list under the diagram.
+- Keep a diagram small: at most about 20 nodes. Make two diagrams before one diagram that a reader cannot read.
+- Embed an image only from the project. It can be an image of the reference (`reference/images/`) or a PNG that a skill made. It can also be an asset that a script of the project made from a format of the program, for example `../assets/rooms/room00.png`. `link.ts` checks that each image exists.
+- Give each image one line of text that tells what it shows.
+
+## Text
+
+- Write short sentences: one fact or one step in each sentence.
+- Use a numbered list for steps in an order. Use a bulleted list for items without an order. Use a table for items with the same fields.
+- Use the same word for the same thing on each page. Define each term of the program one time, in the conventions block.
+- Write the pages for a person who knows the 6502 and the C64, but not the program.
+
+## Generated pages
+
+- Do not edit a page in the reference. Change the knowledge, generate the source, and run `generate.ts` again.
+- Do not put a page that you write in the reference directory. `generate.ts` refuses to write when one is there.

package/skills/c64-docs/scripts/generate.ts

@@ -0,0 +1,110 @@
+// c64-docs generate.ts (D80): the reference pages of a program from the
+// knowledge, the source map of c64-source and the image. The pages are
+// generated and never edited; the pages of a person link to them.
+
+import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { join, posix } from "node:path";
+import { parseArgs } from "node:util";
+
+import { ImageError, readImage } from "#src/host-client/image.ts";
+import { WireFailure } from "#src/host-client/tools.ts";
+import { writeProjectFile } from "#src/host-client/transfer.ts";
+import { conflicts } from "#src/knowledge/conflicts.ts";
+import { KnowledgeError, openForRead } from "#src/knowledge/database.ts";
+import { currentRevision, listComments, listModules, listReferences, listRegions, listSymbols } from "#src/knowledge/read.ts";
+import { resolveProjectPath } from "#src/project.ts";
+import { runScript, UsageError } from "#src/script.ts";
+import { buildReference, GENERATED_MARK } from "./lib/reference.ts";
+import { readSourceMap } from "./lib/source-map.ts";
+
+const USAGE = `generate.ts --source <dir> --out <dir> [--image <file>]
+
+  --source <dir>   the source directory of c64-source, with its source-map.json,
+                   relative to the project folder
+  --out <dir>      the directory for the reference pages, relative to the project
+                   folder, for example docs/reference; generate.ts writes only
+                   there and refuses a page in it that it did not write
+  --image <file>   the image of the source: an image.json of the c64-unpacker
+                   skill, or a PRG; it decodes the tables and shows the graphics
+
+The result is one JSON object.`;
+
+/** The files of an earlier run, or a refusal that names a file of a person. */
+function oldFiles(out: string): string[] {
+  const directory = resolveProjectPath(out);
+  if (!existsSync(directory)) return [];
+  const found: string[] = [];
+  const walk = (relative: string) => {
+    for (const entry of readdirSync(join(directory, relative), { withFileTypes: true })) {
+      const path = posix.join(relative, entry.name);
+      if (entry.isDirectory()) {
+        walk(path);
+        continue;
+      }
+      const generated = path.endsWith(".md") ? readFileSync(join(directory, path), "utf8").startsWith(GENERATED_MARK) : path.startsWith("images/") && path.endsWith(".png");
+      if (!generated) throw new WireFailure("invalid-input", `${posix.join(out, path)} is not a page of generate.ts. Nothing was written. Give --out a directory that holds only the reference, and keep the pages of a person outside it.`);
+      found.push(path);
+    }
+  };
+  walk("");
+  return found;
+}
+
+function run(argv: string[]): Record<string, unknown> {
+  const { values, positionals } = parseArgs({ args: argv, strict: true, allowPositionals: true, options: { source: { type: "string" }, out: { type: "string" }, image: { type: "string" }, help: { type: "boolean" } } });
+  if (values.help) throw new UsageError("");
+  if (positionals.length > 0) throw new UsageError(`generate.ts takes no positional arguments, not ${positionals[0]}`);
+  if (values.source === undefined) throw new UsageError("give --source <dir>: the source directory of c64-source");
+  if (values.out === undefined) throw new UsageError("give --out <dir>: the directory for the reference pages");
+  for (const [option, path] of [["--source", values.source], ["--out", values.out]] as const) {
+    try {
+      resolveProjectPath(path);
+    } catch {
+      throw new UsageError(`${option} must be a path relative to the project folder that stays inside it, not ${path}`);
+    }
+  }
+  const map = readSourceMap(values.source);
+  let image: ReturnType<typeof readImage> | undefined;
+  if (values.image !== undefined) {
+    try {
+      image = readImage(values.image);
+    } catch (error) {
+      if (error instanceof ImageError) throw new UsageError(error.message);
+      throw error;
+    }
+  }
+  const db = openForRead();
+  let knowledge;
+  try {
+    const found = conflicts(db).length;
+    if (found > 0) throw new KnowledgeError("conflict", `The knowledge has ${found} conflict${found === 1 ? "" : "s"} from a git merge. Nothing was written. Run c64-knowledge's knowledge.ts merge, then generate the source and the reference again.`);
+    const revision = currentRevision(db);
+    // A source of another revision has other lines: the links would point to the wrong code.
+    if (map.revision !== revision) {
+      throw new WireFailure("invalid-input", `${map.pathOf("source-map.json")} is from knowledge revision ${map.revision}, and the knowledge is at revision ${revision}. Nothing was written. Generate the source again with c64-source, then run generate.ts.`);
+    }
+    knowledge = {
+      revision,
+      symbols: listSymbols(db, undefined, undefined, undefined, map.space),
+      regions: listRegions(db, undefined, undefined, undefined, map.space),
+      comments: listComments(db, undefined, undefined, map.space),
+      references: listReferences(db, undefined, undefined, undefined, map.space),
+      modules: listModules(db, undefined, undefined, map.space),
+    };
+  } finally {
+    db?.close();
+  }
+  const old = oldFiles(values.out);
+  const built = buildReference({
+    out: posix.normalize(values.out),
+    map,
+    ...knowledge,
+    ...(image === undefined ? {} : { image: { path: image.path, byteAt: image.byteAt, inImage: (address: number) => image.segments.some((segment) => address >= segment.start && address <= segment.end) } }),
+  });
+  const directory = resolveProjectPath(values.out);
+  for (const path of old) rmSync(join(directory, path), { force: true });
+  for (const file of built.files) writeProjectFile(file.path, file.bytes, { what: "--out" });
+  return { out: values.out, revision: knowledge.revision, index: posix.join(posix.normalize(values.out), "index.md"), ...built.counts, image: image?.path ?? "none: give --image to decode the tables and show the graphics" };
+}
+
+await runScript(run, { usage: USAGE, refusals: [KnowledgeError] });

package/skills/c64-docs/scripts/lib/links.ts

@@ -0,0 +1,155 @@
+// The links of a page written by a person (D80). A name in backticks links to
+// its line in the source; the address after it links to the entry of the name
+// in the reference, or, for an address inside the routine or the data of the
+// name ("draw_room $0AAF", a place in draw_room), to the line of that address. A link that points into the source or the reference is
+// managed: link.ts writes it again when a line moves. Other links stay as the
+// person wrote them; link.ts only checks that their targets exist.
+
+import { posix } from "node:path";
+
+import { anchorsOf, linksOf, proseLines } from "./markdown.ts";
+
+export interface LinkContext {
+  /** The page, relative to the project folder. */
+  page: string;
+  /** The address of a name of the knowledge or of the source; undefined for a word that is no name. */
+  addressOf: (name: string) => number | undefined;
+  /** The project path and line of the label of a name, as path#Lnn. */
+  codeOf: (name: string) => string | undefined;
+  /** The project path and anchor of the entry of a name, as path#name. */
+  entryOf: (name: string) => string | undefined;
+  /** The last address of the routine or data of a name: an address up to it is a place inside the name. */
+  bodyEnd: (name: string) => number | undefined;
+  /** The project path and line that writes an address, as path#Lnn. */
+  lineOf: (address: number) => string | undefined;
+  /** The name of the routine or data that holds an address, for a message. */
+  placeOf: (address: number) => string | undefined;
+  /** True for a project path that link.ts manages: a file of the source or a page of the reference. */
+  managed: (path: string) => boolean;
+}
+
+export type ProblemKind = "unknown-name" | "wrong-address" | "missing-file" | "missing-anchor" | "missing-line" | "outside-project" | "stale-reference";
+
+export interface Problem {
+  page: string;
+  /** 1 is the first line. */
+  line: number;
+  kind: ProblemKind;
+  message: string;
+}
+
+const NAME = String.raw`([A-Za-z_][A-Za-z0-9_]*)(\+(?:\$[0-9A-Fa-f]{1,4}|[0-9]+))?`;
+const ADDRESS = String.raw`\$([0-9A-Fa-f]{2,4})(?:-\$[0-9A-Fa-f]{2,4})?`;
+const TICK = "`";
+/**
+ * A name in backticks, linked or not, with an optional address in backticks
+ * after it, linked or not. Groups: 1 the [ of a linked name, 2 the name, 3 its
+ * offset, 4 the target of the name, 5 the space or bracket between them, 6 the
+ * address text, 7 its start digits, 8 the target of the address.
+ */
+const MENTION = new RegExp(
+  String.raw`(\[)?${TICK}${NAME}${TICK}(?:\]\(([^)\s]*)\))?(?:(\s*\(\s*|\s+)\[?${TICK}(${ADDRESS})${TICK}(?:\]\(([^)\s]*)\))?)?`,
+  "g",
+);
+
+const relative = (page: string, target: string) => {
+  const [path, fragment] = target.split("#");
+  const shown = posix.relative(posix.dirname(page), path!) || posix.basename(path!);
+  return fragment === undefined ? shown : `${shown}#${fragment}`;
+};
+/** The project path of a link target, without its fragment; undefined for a link out of the project (a URL, or a page anchor only). */
+export function targetPath(page: string, target: string): string | undefined {
+  if (/^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith("#")) return undefined;
+  return posix.normalize(posix.join(posix.dirname(page), decodeURIComponent(target.split("#")[0]!)));
+}
+
+/** Writes the links of the name mentions of a page; returns the new text, the number of links changed and the problems. */
+export function linkPage(text: string, context: LinkContext): { text: string; changed: number; problems: Problem[] } {
+  const problems: Problem[] = [];
+  let changed = 0;
+  const lines = proseLines(text).map((line, index) => {
+    if (!line.prose) return line.text;
+    return line.text.replace(MENTION, (whole: string, open: string | undefined, name: string, offset: string | undefined, nameTarget: string | undefined, space: string | undefined, addressText: string | undefined, digits: string | undefined, addressTarget: string | undefined, at: number, all: string) => {
+      // "[`x`]" without a target is no link of ours: leave it.
+      if (open !== undefined && nameTarget === undefined) return whole;
+      const ownLink = (target: string | undefined) => target !== undefined && !context.managed(targetPath(context.page, target) ?? "");
+      const address = context.addressOf(name);
+      const report = (kind: ProblemKind, message: string) => problems.push({ page: context.page, line: index + 1, kind, message });
+      // In a list "`a`/`b` `$1000`/`$1010`" the address belongs to another name: the name gets its link, the address stays as it is.
+      const namePart = open === undefined ? `${TICK}${name}${offset ?? ""}${TICK}` : `[${TICK}${name}${offset ?? ""}${TICK}](${nameTarget})`;
+      const listed = addressText !== undefined && (all[at - 1] === "/" || all[at + whole.length] === "/");
+      const rest = listed ? whole.slice(namePart.length) : "";
+      const claimed = addressText !== undefined;
+      if (listed) addressText = digits = addressTarget = undefined;
+      if (address === undefined) {
+        // A word in backticks is no claim of a name; with an address after it, or with a link of ours, it is.
+        if (claimed || (nameTarget !== undefined && !ownLink(nameTarget))) {
+          report("unknown-name", `\`${name}\` is no name of the knowledge or the source. Apply the name to the knowledge, or correct the page.`);
+        }
+        return whole;
+      }
+      const delta = offset === undefined ? 0 : offset.startsWith("+$") ? Number.parseInt(offset.slice(2), 16) : Number.parseInt(offset.slice(1), 10);
+      const given = digits === undefined ? undefined : Number.parseInt(digits, 16);
+      const place = given !== undefined && given !== address + delta && given > address && given <= (context.bodyEnd(name) ?? address);
+      if (given !== undefined && given !== address + delta && !place) {
+        const expected = `$${(address + delta).toString(16).toUpperCase().padStart(4, "0")}`;
+        const holder = context.placeOf(given!);
+        report("wrong-address", `\`${name}${offset ?? ""}\` is ${expected} in the knowledge, and the page gives ${addressText}${holder === undefined || holder === name ? "" : `, a place in \`${holder}\``}. Correct the name or the address.${digits!.length <= 2 ? ` For a value, write \`${name}\` = \`${addressText}\`.` : ""}`);
+      }
+      const shownName = `${TICK}${name}${offset ?? ""}${TICK}`;
+      const code = context.codeOf(name);
+      const nameLink = ownLink(nameTarget) ? `[${shownName}](${nameTarget})` : code === undefined ? shownName : `[${shownName}](${relative(context.page, code)})`;
+      let result = nameLink;
+      if (addressText !== undefined) {
+        const entry = place ? context.lineOf(given!) : context.entryOf(name);
+        const shownAddress = `${TICK}${addressText}${TICK}`;
+        result += space! + (ownLink(addressTarget) ? `[${shownAddress}](${addressTarget})` : entry === undefined ? shownAddress : `[${shownAddress}](${relative(context.page, entry)})`);
+      }
+      result += rest;
+      if (result !== whole) changed++;
+      return result;
+    });
+  });
+  return { text: lines.join("\n"), changed, problems };
+}
+
+/** The files that a check reads: their text, or undefined when the file does not exist. */
+export interface Files {
+  exists: (path: string) => boolean;
+  /** The text of a project file, or undefined when it is no file. */
+  text: (path: string) => string | undefined;
+  inside: (path: string) => boolean;
+}
+
+/** Checks that each link and image of a page reaches a file, and its anchor or line. */
+export function checkLinks(page: string, text: string, files: Files): Problem[] {
+  const problems: Problem[] = [];
+  const anchors = new Map<string, Set<string>>();
+  const anchorsAt = (path: string) => {
+    if (!anchors.has(path)) anchors.set(path, anchorsOf(path === page ? text : (files.text(path) ?? "")));
+    return anchors.get(path)!;
+  };
+  for (const link of linksOf(text)) {
+    const report = (kind: ProblemKind, message: string) => problems.push({ page, line: link.line, kind, message });
+    const fragment = link.target.includes("#") ? link.target.slice(link.target.indexOf("#") + 1) : undefined;
+    if (/^[a-z][a-z0-9+.-]*:/i.test(link.target)) continue;
+    const path = link.target.startsWith("#") ? page : targetPath(page, link.target)!;
+    if (!files.inside(path)) {
+      report("outside-project", `${link.target} leaves the project folder.`);
+      continue;
+    }
+    if (!files.exists(path)) {
+      report("missing-file", `${link.target}: there is no ${path}.`);
+      continue;
+    }
+    if (fragment === undefined || fragment === "") continue;
+    const line = /^L(\d+)(?:-L?\d+)?$/.exec(fragment);
+    if (path.endsWith(".md")) {
+      if (!anchorsAt(path).has(fragment)) report("missing-anchor", `${link.target}: ${path} has no anchor ${fragment}.`);
+    } else if (line !== null) {
+      const count = (files.text(path) ?? "").split("\n").length;
+      if (Number(line[1]) > count) report("missing-line", `${link.target}: ${path} has ${count} lines.`);
+    }
+  }
+  return problems;
+}