@henols/c64-re-tools 2.0.0-rc.2 → 2.0.0-rc.21

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

@@ -0,0 +1,406 @@
+// The reference pages of the documentation (D80): generated from the
+// knowledge, the source map and the image, never edited. A name links to its
+// line in the source; an address links to the entry of its name; a call site
+// links to its line.
+
+import { posix } from "node:path";
+
+import { formatC64Address, POINTER_TABLE_TYPES, pointerTableEntries, type PointerTableType } from "#src/c64.ts";
+import { bitmapFrame, charsetFrame, encodePng, PATTERN_PALETTES, scaleFrame, screenText, spriteSheet, type GraphicsMode } from "#src/graphics.ts";
+import { mermaidGraph, ownerOf, routineEdges, routineHeads, type GraphReference, type RoutineHead } from "#src/knowledge/graph.ts";
+import type { CommentRow, ModuleRow, ReferenceRow, RegionRow, SymbolRow } from "#src/knowledge/read.ts";
+import type { RegionType } from "#src/knowledge/schema.ts";
+import type { SourceMap } from "./source-map.ts";
+
+/** The first line of every generated page. A page without it is a page of a person, and generate.ts never writes over it. */
+export const GENERATED_MARK = "<!-- Generated by c64-docs";
+
+export interface ReferenceInput {
+  /** The reference directory, relative to the project folder. */
+  out: string;
+  map: SourceMap;
+  revision: string;
+  symbols: SymbolRow[];
+  regions: RegionRow[];
+  comments: CommentRow[];
+  references: ReferenceRow[];
+  modules: ModuleRow[];
+  image?: { byteAt: (address: number) => number; inImage: (address: number) => boolean };
+}
+
+export interface ReferenceFile {
+  /** Relative to the project folder. */
+  path: string;
+  bytes: Buffer;
+}
+
+/** Files that the source map lists but that hold no code of the program. */
+const NOT_PIECES = new Set(["main.asm", "constants.asm", "macros.asm", "loader.asm"]);
+const TABLE_TYPES: readonly RegionType[] = [...POINTER_TABLE_TYPES, "jumps", "words"];
+const GRAPHICS_TYPES: readonly RegionType[] = ["sprite", "bitmap", "charset", "screen"];
+/** A list longer than this ends with the number of the rest. */
+const MAX_LISTED = 40;
+/** A call graph with more edges is not readable: then it shows the calls only, and at most this many. */
+const MAX_EDGES = 60;
+/** A name outside the image covers the addresses that references use up to the next name, at most this many. */
+const MAX_SPAN = 256;
+/** The kinds of a reference that reads a table: Ghidra gives an indexed read (lda table,x) as "reference". */
+const TABLE_READS: readonly string[] = ["read", "reference", "pointer"];
+
+const hex = (address: number) => formatC64Address(address).toUpperCase();
+const range = (start: number, end: number) => (start === end ? hex(start) : `${hex(start)}-${hex(end)}`);
+const stem = (file: string) => file.replace(/\.asm$/, "");
+
+interface Entry {
+  name: string;
+  address: number;
+  kind: string;
+  /** The page that holds the entry, relative to the project folder. */
+  page: string;
+  /** The last address that the name covers: references to it belong to the name. */
+  spanEnd: number;
+}
+
+/** Builds every page and image of the reference. */
+export function buildReference(input: ReferenceInput): { files: ReferenceFile[]; counts: Record<string, number> } {
+  const { map, out } = input;
+  const pieces = map.files.filter((file) => !NOT_PIECES.has(file));
+  const pageOfFile = (file: string) => (file === "constants.asm" ? posix.join(out, "variables.md") : posix.join(out, "modules", `${stem(file)}.md`));
+
+  // --- Names and their entries ------------------------------------------------
+  const knowledgeNames = new Map(input.symbols.map((symbol) => [symbol.name, symbol]));
+  const entries = new Map<string, Entry>();
+  const sortedNames = [...new Set([...input.symbols.map((symbol) => symbol.address), ...map.labels.filter((label) => label.file === "constants.asm").map((label) => label.address)])].sort((a, b) => a - b);
+  const nextName = (address: number) => sortedNames.find((other) => other > address);
+  const regionAt = (address: number) => input.regions.find((region) => region.start <= address && region.end >= address);
+  const spanOf = (address: number, kind: string) => {
+    if (kind === "routine" || kind === "label") return address;
+    const next = nextName(address) ?? 0x10000;
+    const region = regionAt(address);
+    if (region !== undefined) return Math.min(next - 1, region.end);
+    if (input.image?.inImage(address) === true) return address;
+    const last = Math.min(next - 1, address + MAX_SPAN - 1);
+    let end = address;
+    for (const reference of input.references) if (reference.to > end && reference.to <= last) end = reference.to;
+    return end;
+  };
+  for (const label of map.labels) {
+    const symbol = knowledgeNames.get(label.name);
+    // A name that c64-source makes (l_xxxx) is no entry: it has no meaning of its own.
+    if (symbol === undefined && label.file !== "constants.asm") continue;
+    const kind = symbol?.kind ?? "platform";
+    entries.set(label.name, { name: label.name, address: label.address, kind, page: pageOfFile(label.file), spanEnd: spanOf(label.address, kind) });
+  }
+  const entryAt = new Map<number, Entry>();
+  for (const entry of entries.values()) if (!entryAt.has(entry.address)) entryAt.set(entry.address, entry);
+  const spans = [...entries.values()].filter((entry) => entry.spanEnd > entry.address).sort((a, b) => a.address - b.address);
+  const sourceNameAt = new Map<number, string>();
+  for (const label of map.labels) if (!sourceNameAt.has(label.address)) sourceNameAt.set(label.address, label.name);
+
+  // --- Links ------------------------------------------------------------------
+  const rel = (page: string, target: string) => posix.relative(posix.dirname(page), target) || posix.basename(target);
+  const codeOfName = (page: string, name: string) => {
+    const label = map.labelOf(name);
+    return label === undefined ? `\`${name}\`` : `[\`${name}\`](${rel(page, map.pathOf(label.file))}#L${label.line})`;
+  };
+  const entryOfName = (page: string, name: string, text: string) => {
+    const entry = entries.get(name);
+    return entry === undefined ? `\`${text}\`` : `[\`${text}\`](${rel(page, entry.page)}#${name})`;
+  };
+  /** A name and its address: the name to its line, the address to its entry (the convention of every page). */
+  const pair = (page: string, name: string, address: number) => `${codeOfName(page, name)} ${entryOfName(page, name, hex(address))}`;
+  const codeOfAddress = (page: string, address: number) => {
+    const line = map.lineOf(address);
+    return line === undefined ? `\`${hex(address)}\`` : `[\`${hex(address)}\`](${rel(page, map.pathOf(line.file))}#L${line.line})`;
+  };
+  /** What a reader calls an address: its name, a name plus an offset, or the address. */
+  const nameFor = (address: number): { name: string; base: number } | undefined => {
+    const own = entryAt.get(address)?.name;
+    if (own !== undefined) return { name: own, base: address };
+    const span = spans.find((entry) => entry.address < address && entry.spanEnd >= address);
+    if (span !== undefined) return { name: span.name, base: span.address };
+    const made = sourceNameAt.get(address);
+    return made === undefined ? undefined : { name: made, base: address };
+  };
+  const target = (page: string, address: number) => {
+    const named = nameFor(address);
+    if (named === undefined) return codeOfAddress(page, address);
+    const shown = named.base === address ? named.name : `${named.name}+${address - named.base}`;
+    return entries.has(named.name) ? entryOfName(page, named.name, shown) : codeOfName(page, named.name).replace(`\`${named.name}\``, `\`${shown}\``);
+  };
+  const capped = (items: string[]) => (items.length <= MAX_LISTED ? items.join(", ") : `${items.slice(0, MAX_LISTED).join(", ")} and ${items.length - MAX_LISTED} more`);
+
+  // --- The routine graph ----------------------------------------------------
+  const tableReferences: GraphReference[] = [];
+  const tables = input.regions.filter((region) => TABLE_TYPES.includes(region.type));
+  const tableEntries = new Map<RegionRow, Array<{ at: number; value: number; target?: number }>>();
+  if (input.image !== undefined) {
+    const { byteAt } = input.image;
+    for (const table of tables) {
+      const rows: Array<{ at: number; value: number; target?: number }> = [];
+      if ((POINTER_TABLE_TYPES as readonly string[]).includes(table.type)) {
+        for (const pair of pointerTableEntries({ ...table, type: table.type as PointerTableType }, byteAt)) rows.push({ at: pair.low, value: byteAt(pair.low) | (byteAt(pair.high) << 8), target: pair.target });
+      } else if (table.type === "jumps") {
+        for (let at = table.start; at + 2 <= table.end; at += 3) {
+          const value = byteAt(at + 1) | (byteAt(at + 2) << 8);
+          rows.push(byteAt(at) === 0x4c ? { at, value, target: value } : { at, value });
+        }
+      } else {
+        for (let at = table.start; at + 1 <= table.end; at += 2) rows.push({ at, value: byteAt(at) | (byteAt(at + 1) << 8) });
+      }
+      tableEntries.set(table, rows);
+      for (const row of rows) if (row.target !== undefined && table.type !== "words") tableReferences.push({ from: table.start, to: row.target, kind: "table" });
+    }
+  }
+  // A table entry is an edge of the graph from each instruction that reads the table to each target in code; a table of data pointers makes no edge.
+  const symbolKinds = new Map(input.symbols.map((symbol) => [symbol.address, symbol.kind]));
+  const inCode = (address: number) =>
+    symbolKinds.get(address) === "routine" || symbolKinds.get(address) === "label" || input.regions.some((region) => (region.type === "code" || region.type === "jumps") && region.start <= address && region.end >= address);
+  const dispatches: GraphReference[] = [];
+  for (const [table, rows] of tableEntries) {
+    const readers = input.references.filter((reference) => TABLE_READS.includes(reference.kind) && reference.to >= table.start && reference.to <= table.end).map((reference) => reference.from);
+    for (const row of rows) if (row.target !== undefined && table.type !== "words" && inCode(row.target)) for (const from of new Set(readers)) dispatches.push({ from, to: row.target, kind: "table" });
+  }
+  const graphReferences: GraphReference[] = [...input.references, ...dispatches];
+  const heads = routineHeads(input.symbols, graphReferences, (address) => sourceNameAt.get(address) ?? hex(address));
+  const boundaries = input.modules.map((module) => module.start);
+  const ownerAt = (address: number) => ownerOf(heads, boundaries, address);
+  const site = (page: string, from: number) => {
+    const owner = ownerAt(from);
+    const named = owner === undefined ? undefined : entries.has(owner.name) ? entryOfName(page, owner.name, owner.name) : codeOfName(page, owner.name);
+    return named === undefined ? codeOfAddress(page, from) : `${named} ${codeOfAddress(page, from)}`;
+  };
+  const edges = routineEdges(heads, boundaries, graphReferences);
+
+  // --- File ranges ----------------------------------------------------------
+  const fileRanges = new Map<string, { start: number; end: number }>();
+  for (let address = 0; address <= 0xffff; address++) {
+    const line = map.lineOf(address);
+    if (line === undefined) continue;
+    const known = fileRanges.get(line.file);
+    if (known === undefined) fileRanges.set(line.file, { start: address, end: address });
+    else known.end = address;
+  }
+  const titleOf = (file: string) => input.modules.find((module) => module.file === file)?.title;
+
+  const header = `${GENERATED_MARK} from knowledge revision ${input.revision} and ${map.pathOf("source-map.json")}. Do not edit: change the knowledge, generate the source again, then run generate.ts. -->`;
+  const files: ReferenceFile[] = [];
+  const write = (path: string, lines: string[]) => files.push({ path, bytes: Buffer.from(`${[header, ...lines].join("\n").replace(/\n{3,}/g, "\n\n")}\n`, "utf8") });
+
+  // --- One entry --------------------------------------------------------------
+  const commentLines = (address: number) =>
+    input.comments
+      .filter((comment) => comment.address === address)
+      .sort((a, b) => (a.placement === b.placement ? 0 : a.placement === "line" ? -1 : 1))
+      .map((comment) => comment.text.replace(/\s*\r?\n\s*/g, " ").trim());
+  const incoming = (entry: Entry) => input.references.filter((reference) => reference.to >= entry.address && reference.to <= entry.spanEnd);
+  const outgoing = (head: RoutineHead) => input.references.filter((reference) => ownerAt(reference.from)?.address === head.address);
+  const entryText = (page: string, entry: Entry): string[] => {
+    const lines = ["", `<a id="${entry.name}"></a>`, `### ${codeOfName(page, entry.name)} \`${entry.spanEnd > entry.address ? range(entry.address, entry.spanEnd) : hex(entry.address)}\``, "", `*${entry.kind}*`];
+    const comments = commentLines(entry.address);
+    if (comments.length > 0) lines.push("", ...comments);
+    const facts: string[] = [];
+    const into = incoming(entry);
+    const selfHead = heads.find((candidate) => candidate.address === entry.address);
+    const fromOthers = into.filter((reference) => selfHead === undefined || ownerAt(reference.from)?.address !== selfHead.address);
+    const strong = new Set(fromOthers.filter((reference) => reference.kind !== "reference" && reference.kind !== "pointer").map((reference) => reference.from));
+    const by = (kinds: readonly string[]) =>
+      fromOthers
+        .filter((reference) => kinds.includes(reference.kind) && !((reference.kind === "reference" || reference.kind === "pointer") && strong.has(reference.from)))
+        .map((reference) => site(page, reference.from) + (reference.to === entry.address ? "" : ` (+${reference.to - entry.address})`));
+    const add = (label: string, items: string[]) => {
+      if (items.length > 0) facts.push(`- **${label}:** ${capped([...new Set(items)])}`);
+    };
+    add("Called from", by(["call"]));
+    add("Jumped to from", by(["jump"]));
+    add("Read by", by(["read"]));
+    add("Written by", by(["write"]));
+    add("Referred to by", by(["reference", "pointer"]));
+    const inTables = tableReferences.filter((reference) => reference.to === entry.address).map((reference) => {
+      const table = tables.find((region) => region.start === reference.from)!;
+      return tableLink(page, table);
+    });
+    add("Entry of", inTables);
+    const head = selfHead;
+    if (head !== undefined) {
+      const all = outgoing(head);
+      const named = new Set(all.filter((reference) => reference.kind !== "reference" && reference.kind !== "pointer").map((reference) => `${reference.from}:${reference.to}`));
+      const from = all.filter((reference) => !((reference.kind === "reference" || reference.kind === "pointer") && named.has(`${reference.from}:${reference.to}`)));
+      const to = (kinds: readonly string[]) => from.filter((reference) => kinds.includes(reference.kind) && ownerAt(reference.to)?.address !== head.address).map((reference) => target(page, reference.to));
+      add("Calls", to(["call"]));
+      add("Jumps to", to(["jump"]));
+      add("Reads", to(["read"]));
+      add("Writes", to(["write"]));
+      add("Refers to", to(["reference", "pointer"]));
+    }
+    if (facts.length > 0) lines.push("", ...facts);
+    return lines;
+  };
+  const tableAnchor = (table: RegionRow) => entryAt.get(table.start)?.name ?? `table_${table.start.toString(16).padStart(4, "0")}`;
+  function tableLink(page: string, table: RegionRow): string {
+    return `[\`${entryAt.get(table.start)?.name ?? range(table.start, table.end)}\`](${rel(page, posix.join(out, "tables.md"))}#${tableAnchor(table)})`;
+  }
+
+  // --- Module pages -----------------------------------------------------------
+  const counts = { pages: 0, entries: 0, tables: 0, images: 0, edges: edges.length };
+  const pieceEntries = new Map<string, Entry[]>();
+  for (const entry of entries.values()) {
+    const label = map.labelOf(entry.name)!;
+    if (!pieces.includes(label.file)) continue;
+    pieceEntries.set(label.file, [...(pieceEntries.get(label.file) ?? []), entry]);
+  }
+  for (const file of pieces) {
+    const page = pageOfFile(file);
+    const span = fileRanges.get(file);
+    const own = (pieceEntries.get(file) ?? []).sort((a, b) => a.address - b.address);
+    const title = titleOf(file);
+    const lines = [`# ${file}${title === undefined ? "" : `: ${title}`}`, "", `Range \`${span === undefined ? "-" : range(span.start, span.end)}\`. Source: [${file}](${rel(page, map.pathOf(file))}). Index: [the reference](${rel(page, posix.join(out, "index.md"))}).`];
+    if (span !== undefined) {
+      const inside = (address: number) => address >= span.start && address <= span.end;
+      const ownHeads = new Set(heads.filter((head) => inside(head.address)).map((head) => head.address));
+      let shown = edges.filter((edge) => ownHeads.has(edge.from) || ownHeads.has(edge.to));
+      const all = shown.length;
+      if (shown.length > MAX_EDGES) shown = shown.filter((edge) => edge.kind === "call").slice(0, MAX_EDGES);
+      if (shown.length > 0) {
+        lines.push("", "## Call graph", "", "A solid arrow is a call, a thick arrow a table entry, a dotted arrow a jump. Rounded nodes are in this file.");
+        if (shown.length < all) lines.push("", `The graph shows ${shown.length} of the ${all} edges: the calls only.`);
+        lines.push("", "```mermaid", mermaidGraph(heads, shown, ownHeads), "```");
+      }
+      const regions = input.regions.filter((region) => region.start <= span.end && region.end >= span.start && region.type !== "code");
+      if (regions.length > 0) {
+        lines.push("", "## Data", "", "| Range | Type | Name | Read by | Written by |", "|---|---|---|---|---|");
+        for (const region of regions) {
+          const into = input.references.filter((reference) => reference.to >= region.start && reference.to <= region.end);
+          const owners = (kind: string) => capped([...new Set(into.filter((reference) => reference.kind === kind).map((reference) => ownerAt(reference.from)?.name ?? hex(reference.from)))].map((name) => (entries.has(name) ? entryOfName(page, name, name) : `\`${name}\``)));
+          const name = entryAt.get(region.start);
+          lines.push(`| ${codeOfAddress(page, region.start)}${region.end === region.start ? "" : `-\`${hex(region.end)}\``} | ${region.type}${region.element === undefined ? "" : ` of ${region.element}`} | ${name === undefined ? "" : codeOfName(page, name.name)} | ${owners("read")} | ${owners("write")} |`);
+        }
+      }
+    }
+    if (own.length > 0) lines.push("", "## Names");
+    for (const entry of own) lines.push(...entryText(page, entry));
+    counts.entries += own.length;
+    write(page, lines);
+  }
+
+  // --- Variables: the names outside the image -------------------------------
+  {
+    const page = posix.join(out, "variables.md");
+    const outside = [...entries.values()].filter((entry) => map.labelOf(entry.name)?.file === "constants.asm").sort((a, b) => a.address - b.address);
+    const inside = [...entries.values()].filter((entry) => entry.kind === "variable" && map.labelOf(entry.name)?.file !== "constants.asm").sort((a, b) => a.address - b.address);
+    const lines = ["# Variables", "", `The names outside the image, with the routines that read and write them. Index: [the reference](${rel(page, posix.join(out, "index.md"))}).`];
+    if (inside.length > 0) lines.push("", "Variables inside the image are on the page of their file:", "", ...inside.map((entry) => `- ${pair(page, entry.name, entry.address)}`));
+    for (const entry of outside) lines.push(...entryText(page, entry));
+    counts.entries += outside.length;
+    write(page, lines);
+  }
+
+  // --- Tables -----------------------------------------------------------------
+  {
+    const page = posix.join(out, "tables.md");
+    const lines = ["# Tables", "", `Each table of addresses, jumps and words, entry by entry. An RTS table holds each target minus 1; the target column gives the target. Index: [the reference](${rel(page, posix.join(out, "index.md"))}).`];
+    if (input.image === undefined) lines.push("", "Put the program into the knowledge with knowledge.ts image, then generate the reference again to decode the tables.");
+    for (const table of tables) {
+      const name = entryAt.get(table.start);
+      lines.push("", `<a id="${tableAnchor(table)}"></a>`, `## ${name === undefined ? `\`${range(table.start, table.end)}\`` : `${codeOfName(page, name.name)} \`${range(table.start, table.end)}\``}`, "", `*${table.type}*`);
+      const comments = commentLines(table.start);
+      if (comments.length > 0) lines.push("", ...comments);
+      const readers = [...new Set(input.references.filter((reference) => reference.to >= table.start && reference.to <= table.end && TABLE_READS.includes(reference.kind)).map((reference) => site(page, reference.from)))];
+      if (readers.length > 0) lines.push("", `- **Read by:** ${capped(readers)}`);
+      const rows = tableEntries.get(table);
+      if (rows === undefined) continue;
+      lines.push("", "| Index | At | Value | Target |", "|---|---|---|---|");
+      rows.forEach((row, index) => {
+        const named = row.target === undefined ? nameFor(row.value) : nameFor(row.target);
+        const shown = row.target === undefined ? (named?.base === row.value ? pair(page, named.name, row.value) : "") : named !== undefined && named.base === row.target ? pair(page, named.name, row.target) : target(page, row.target);
+        lines.push(`| ${index} | ${codeOfAddress(page, row.at)} | \`${hex(row.value)}\` | ${shown} |`);
+      });
+      counts.tables++;
+    }
+    write(page, lines);
+  }
+
+  // --- Graphics -----------------------------------------------------------------
+  {
+    const page = posix.join(out, "graphics.md");
+    const graphics = input.regions.filter((region) => GRAPHICS_TYPES.includes(region.type));
+    const lines = [
+      "# Graphics",
+      "",
+      `Each sprite, bitmap, charset and screen region of the knowledge. The knowledge gives no display mode and no colours, so a sprite, bitmap or charset shows in hires and in multicolour, in pattern colours: black is pixel value 0, white is 1 in hires; in multicolour light grey is 1, grey is 2 and yellow is 3. Index: [the reference](${rel(page, posix.join(out, "index.md"))}).`,
+    ];
+    if (input.image === undefined && graphics.length > 0) lines.push("", "Put the program into the knowledge with knowledge.ts image, then generate the reference again to show the graphics.");
+    for (const region of graphics) {
+      const anchor = entryAt.get(region.start)?.name ?? `${region.type}_${region.start.toString(16).padStart(4, "0")}`;
+      const name = entryAt.get(region.start);
+      lines.push("", `<a id="${anchor}"></a>`, `## ${name === undefined ? codeOfAddress(page, region.start) : pair(page, name.name, region.start)} \`${range(region.start, region.end)}\``, "", `*${region.type}*`);
+      const comments = commentLines(region.start);
+      if (comments.length > 0) lines.push("", ...comments);
+      if (input.image === undefined) continue;
+      const bytes = Uint8Array.from({ length: region.end - region.start + 1 }, (_, offset) => input.image!.byteAt(region.start + offset));
+      if (region.type === "screen") {
+        lines.push("", "```text", ...screenText(bytes), "```");
+        continue;
+      }
+      for (const mode of ["hires", "multicolour"] as GraphicsMode[]) {
+        // A sheet of sprites, a charset, or a bitmap of at most 8 rows of cells, is small: each pixel shows as 2 x 2.
+        const raw = region.type === "sprite" ? spriteSheet(bytes, mode, region.element === 63 ? 63 : 64) : region.type === "charset" ? charsetFrame(bytes, mode) : bitmapFrame(bytes, mode);
+        const frame = region.type === "sprite" || region.type === "charset" || raw.height <= 64 ? scaleFrame(raw, 2) : raw;
+        const image = posix.join(out, "images", `${anchor}-${mode}.png`);
+        files.push({ path: image, bytes: encodePng(frame, PATTERN_PALETTES[mode]) });
+        lines.push("", `![${anchor} in ${mode}](${rel(page, image)})`);
+        counts.images++;
+      }
+    }
+    write(page, lines);
+  }
+
+  // --- Memory map ---------------------------------------------------------------
+  {
+    const page = posix.join(out, "memory-map.md");
+    const lines = ["# Memory map", "", `Every region of the knowledge in address order. Index: [the reference](${rel(page, posix.join(out, "index.md"))}).`, "", "| Range | Bytes | Type | Name | File |", "|---|---|---|---|---|"];
+    for (const region of [...input.regions].sort((a, b) => a.start - b.start)) {
+      const name = entryAt.get(region.start);
+      const line = map.lineOf(region.start);
+      const file = line === undefined || !pieces.includes(line.file) ? "" : `[${line.file}](${rel(page, pageOfFile(line.file))})`;
+      lines.push(`| ${codeOfAddress(page, region.start)}${region.end === region.start ? "" : `-\`${hex(region.end)}\``} | ${region.end - region.start + 1} | ${region.type} | ${name === undefined ? "" : pair(page, name.name, region.start)} | ${file} |`);
+    }
+    write(page, lines);
+  }
+
+  // --- Symbols --------------------------------------------------------------------
+  {
+    const page = posix.join(out, "symbols.md");
+    const lines = ["# Names", "", `Every name in alphabetical order. The name links to its line in the source, the address to its entry. Index: [the reference](${rel(page, posix.join(out, "index.md"))}).`, "", "| Name | Address | Kind |", "|---|---|---|"];
+    const names = [...new Set([...entries.keys(), ...input.symbols.map((symbol) => symbol.name)])].sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()) || a.localeCompare(b));
+    for (const name of names) {
+      const entry = entries.get(name);
+      const symbol = knowledgeNames.get(name);
+      const address = entry?.address ?? symbol!.address;
+      lines.push(`| ${codeOfName(page, name)} | ${entryOfName(page, name, hex(address))} | ${entry?.kind ?? symbol!.kind} |`);
+    }
+    write(page, lines);
+  }
+
+  // --- Index ------------------------------------------------------------------------
+  {
+    const page = posix.join(out, "index.md");
+    const lines = [
+      "# Reference",
+      "",
+      `Generated from the knowledge and the source in [${map.directory}](${rel(page, map.directory)}). The other pages: [names](symbols.md), [variables](variables.md), [tables](tables.md), [memory map](memory-map.md) and [graphics](graphics.md).`,
+      "",
+      "| File | Range | Title | Routines | Names |",
+      "|---|---|---|---|---|",
+    ];
+    for (const file of pieces) {
+      const span = fileRanges.get(file);
+      const own = pieceEntries.get(file) ?? [];
+      const routines = span === undefined ? 0 : heads.filter((head) => head.address >= span.start && head.address <= span.end).length;
+      lines.push(`| [${file}](${rel(page, pageOfFile(file))}) | \`${span === undefined ? "-" : range(span.start, span.end)}\` | ${titleOf(file) ?? ""} | ${routines} | ${own.length} |`);
+    }
+    write(page, lines);
+  }
+  counts.pages = files.filter((file) => file.path.endsWith(".md")).length;
+  return { files, counts };
+}

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

@@ -0,0 +1,81 @@
+// The source map that c64-source writes next to the source (D80): the line of
+// each name and of each address. The documentation links to these lines.
+
+import { posix } from "node:path";
+
+import { parseC64Address } from "#src/c64.ts";
+import { WireFailure } from "#src/host-client/tools.ts";
+import { readProjectFile } from "#src/host-client/transfer.ts";
+import type { Space } from "#src/knowledge/schema.ts";
+
+export const SOURCE_MAP_FILE = "source-map.json";
+
+export interface SourceLine {
+  file: string;
+  line: number;
+}
+
+export interface SourceMap {
+  /** The source directory, relative to the project folder. */
+  directory: string;
+  space: Space;
+  revision: string;
+  files: string[];
+  labels: Array<SourceLine & { address: number; name: string }>;
+  /** The label line of a name. */
+  labelOf: (name: string) => (SourceLine & { address: number }) | undefined;
+  /** The line that writes an address: an instruction, a macro use or a data line. */
+  lineOf: (address: number) => SourceLine | undefined;
+  /** The project path of a source file. */
+  pathOf: (file: string) => string;
+}
+
+/** Reads <directory>/source-map.json. A missing map is a refusal with the remedy. */
+export function readSourceMap(directory: string): SourceMap {
+  const path = posix.join(directory, SOURCE_MAP_FILE);
+  let text: string;
+  try {
+    text = readProjectFile(path).bytes.toString("utf8");
+  } catch (error) {
+    if (error instanceof WireFailure && error.code === "not-found") {
+      throw new WireFailure("not-found", `There is no ${path}. Generate the source with c64-source generate.ts --out ${directory}: it writes the source map.`);
+    }
+    throw error;
+  }
+  const fail = (what: string): never => {
+    throw new WireFailure("invalid-input", `${path} is not a source map of c64-source: ${what}. Generate the source again.`);
+  };
+  let raw: Record<string, unknown>;
+  try {
+    raw = JSON.parse(text) as Record<string, unknown>;
+  } catch (error) {
+    return fail((error as Error).message);
+  }
+  if (!Array.isArray(raw.labels) || !Array.isArray(raw.items) || !Array.isArray(raw.files)) fail("it has no labels, items or files");
+  const labels = (raw.labels as Array<Record<string, unknown>>).map((label) => ({ address: parseC64Address(String(label.address)), name: String(label.name), file: String(label.file), line: Number(label.line) }));
+  const items = (raw.items as Array<Record<string, unknown>>)
+    .map((item) => ({ start: parseC64Address(String(item.start)), end: parseC64Address(String(item.end)), file: String(item.file), line: Number(item.line) }))
+    .sort((a, b) => a.start - b.start);
+  const byName = new Map(labels.map((label) => [label.name, label]));
+  return {
+    directory,
+    space: String(raw.space ?? "c64") as Space,
+    revision: String(raw.revision),
+    files: (raw.files as unknown[]).map(String),
+    labels,
+    labelOf: (name) => byName.get(name),
+    lineOf: (address) => {
+      let low = 0;
+      let high = items.length - 1;
+      while (low <= high) {
+        const middle = (low + high) >> 1;
+        const item = items[middle]!;
+        if (address < item.start) high = middle - 1;
+        else if (address > item.end) low = middle + 1;
+        else return { file: item.file, line: item.line };
+      }
+      return undefined;
+    },
+    pathOf: (file) => posix.join(directory, file),
+  };
+}