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

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;
+}

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

@@ -0,0 +1,79 @@
+// What the documentation scripts read in a Markdown page: the lines outside
+// code blocks and HTML comments, the anchors that a link can name, and the
+// links and images with their targets.
+
+/** The lines of a page and, for each one, whether it is prose: outside fenced code (also mermaid) and outside HTML comments. */
+export function proseLines(text: string): Array<{ text: string; prose: boolean }> {
+  const lines = text.split("\n");
+  let fence: string | undefined;
+  let comment = false;
+  return lines.map((line) => {
+    const opening = /^\s*(`{3,}|~{3,})/.exec(line);
+    if (fence !== undefined) {
+      if (opening !== null && opening[1]!.startsWith(fence[0]!) && opening[1]!.length >= fence.length && line.trim() === opening[1]) fence = undefined;
+      return { text: line, prose: false };
+    }
+    if (opening !== null) {
+      fence = opening[1]!;
+      return { text: line, prose: false };
+    }
+    if (comment) {
+      if (line.includes("-->")) comment = false;
+      return { text: line, prose: false };
+    }
+    if (line.trimStart().startsWith("<!--")) {
+      comment = !line.includes("-->");
+      return { text: line, prose: false };
+    }
+    return { text: line, prose: true };
+  });
+}
+
+/** The id that GitHub and VS Code give a heading: lower case, without punctuation, spaces as hyphens. */
+export function headingSlug(heading: string): string {
+  const text = heading
+    .replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .replace(/<[^>]+>/g, "")
+    .replace(/`/g, "")
+    .trim()
+    .toLowerCase();
+  return text.replace(/[^\p{L}\p{N}\s_-]/gu, "").replace(/\s/g, "-");
+}
+
+/** The anchors of a page: each <a id> or <a name>, and each heading slug, with -1, -2 for a slug that comes again. */
+export function anchorsOf(text: string): Set<string> {
+  const anchors = new Set<string>();
+  const seen = new Map<string, number>();
+  for (const line of proseLines(text)) {
+    for (const match of line.text.matchAll(/<a\s+(?:id|name)="([^"]+)"/g)) anchors.add(match[1]!);
+    if (!line.prose) continue;
+    const heading = /^#{1,6}\s+(.*?)\s*#*\s*$/.exec(line.text);
+    if (heading === null) continue;
+    const slug = headingSlug(heading[1]!);
+    const count = seen.get(slug) ?? 0;
+    seen.set(slug, count + 1);
+    anchors.add(count === 0 ? slug : `${slug}-${count}`);
+  }
+  return anchors;
+}
+
+export interface Link {
+  /** 1 is the first line. */
+  line: number;
+  image: boolean;
+  target: string;
+}
+
+/** The links and images of the prose lines; links inside inline code are not links. */
+export function linksOf(text: string): Link[] {
+  const links: Link[] = [];
+  proseLines(text).forEach((line, index) => {
+    if (!line.prose) return;
+    // Inline code that holds no link text: `[x](y)` inside one pair of backticks is code, not a link.
+    const outside = line.text.replace(/`[^`]*`/g, (code) => (code.includes("](") ? " ".repeat(code.length) : code));
+    for (const match of outside.matchAll(/(!?)\[(?:[^\]`]|`[^`]*`)*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g)) {
+      links.push({ line: index + 1, image: match[1] === "!", target: match[2]! });
+    }
+  });
+  return links;
+}

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 };
+}