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

package/src/knowledge/database.ts

@@ -1,14 +1,23 @@
-// The one place that opens .c64-re-tools/knowledge.db.
+// The one place that opens the knowledge. The knowledge is text in
+// .c64-re-tools/knowledge/ (D69); .c64-re-tools/local/knowledge.db is an index
+// that is made again from the text when the text changed.
 
-import { existsSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { DatabaseSync } from "node:sqlite";
 import { join } from "node:path";
 
-import { projectRoot } from "../project.ts";
-import { checkVersion, ensureSchema, schemaVersion } from "./schema.ts";
+import { ensureLocal, LOCAL_DIRECTORY, PROJECT_DIRECTORY, projectRoot } from "../project.ts";
+import { ensureSchema } from "./schema.ts";
+import { compareText, loadText, readText, REVISIONS_FILE, revisionsText, sha256, sqlName, TABLES, tableText, writeAtomic } from "./text.ts";
 
-export const KNOWLEDGE_DIRECTORY = ".c64-re-tools";
-export const KNOWLEDGE_FILE = "knowledge.db";
+export const KNOWLEDGE_DIRECTORY = PROJECT_DIRECTORY;
+/** The folder of the committed knowledge text. */
+export const TEXT_DIRECTORY = "knowledge";
+/** The index file in .c64-re-tools/local/. */
+export const INDEX_FILE = "knowledge.db";
+/** Git keeps the lines of both sides when two computers changed the same knowledge file. */
+// eol=lf: with core.autocrlf (the Windows default) git would check the files out with CRLF, so two computers would hold other bytes.
+export const GIT_ATTRIBUTES = "# The knowledge of c64-re-tools: git keeps the lines of both sides of a merge, with LF line ends on every system.\n*.jsonl merge=union text eol=lf\n.gitattributes text eol=lf\n";
 
 export const KNOWLEDGE_ERROR_CODES = [
   "invalid-input",
@@ -31,12 +40,27 @@ export class KnowledgeError extends Error {
   }
 }
 
-export function knowledgePath(root: string = projectRoot()): string {
-  return join(root, KNOWLEDGE_DIRECTORY, KNOWLEDGE_FILE);
+/** The folder of the knowledge text: .c64-re-tools/knowledge/. */
+export function textPath(root: string = projectRoot()): string {
+  return join(root, KNOWLEDGE_DIRECTORY, TEXT_DIRECTORY);
+}
+
+/** The index: .c64-re-tools/local/knowledge.db. */
+export function indexPath(root: string = projectRoot()): string {
+  return join(root, KNOWLEDGE_DIRECTORY, LOCAL_DIRECTORY, INDEX_FILE);
+}
+
+/** Refuses a project that has only the knowledge.db of an older c64-re-tools. */
+function refuseOldLayout(root: string): void {
+  if (!existsSync(textPath(root)) && existsSync(join(root, KNOWLEDGE_DIRECTORY, INDEX_FILE))) {
+    throw new KnowledgeError(
+      "unsupported-schema",
+      `${KNOWLEDGE_DIRECTORY}/${INDEX_FILE} is the knowledge of an older c64-re-tools. This c64-re-tools keeps the knowledge as text in ${KNOWLEDGE_DIRECTORY}/${TEXT_DIRECTORY}/. Convert it one time with distribution/convert-knowledge.ts of the c64-re-tools source repository.`,
+    );
+  }
 }
 
 function configure(db: DatabaseSync): void {
-  // A committed write must be complete in knowledge.db itself: rollback journal, never WAL.
   db.exec("PRAGMA journal_mode = DELETE; PRAGMA foreign_keys = ON; PRAGMA busy_timeout = 5000;");
 }
 
@@ -47,28 +71,23 @@ function open(path: string, readOnly: boolean): DatabaseSync {
     configure(db);
     db.prepare("SELECT count(*) FROM sqlite_master").get();
   } catch (error) {
-    throw new KnowledgeError("invalid-database", `${KNOWLEDGE_DIRECTORY}/${KNOWLEDGE_FILE} is not a readable SQLite database: ${(error as Error).message}`);
+    throw new KnowledgeError("invalid-database", `${KNOWLEDGE_DIRECTORY}/${LOCAL_DIRECTORY}/${INDEX_FILE} is not a readable SQLite database: ${(error as Error).message} Delete it: it is made again from the knowledge text.`);
   }
   return db;
 }
 
-/**
- * Opens the project's knowledge database read-only, as it is: a read never
- * migrates and never writes. Returns undefined when the database does not
- * exist or has no schema yet: that reads as empty knowledge, and a read
- * creates nothing. Refuses a schema version other than this build's.
- */
-export function openForRead(root: string = projectRoot()): DatabaseSync | undefined {
-  const path = knowledgePath(root);
-  if (!existsSync(path)) return undefined;
-  const db = open(path, true);
+/** Opens the index for a write and gives it the schema of this build. A file that is no database is made again. */
+function openIndex(root: string): DatabaseSync {
+  ensureLocal(root);
+  let db: DatabaseSync;
   try {
-    const version = schemaVersion(db);
-    if (version === 0) {
-      db.close();
-      return undefined;
-    }
-    checkVersion(version);
+    db = open(indexPath(root), false);
+  } catch {
+    writeFileSync(indexPath(root), "");
+    db = open(indexPath(root), false);
+  }
+  try {
+    ensureSchema(db);
   } catch (error) {
     db.close();
     throw error;
@@ -76,16 +95,75 @@ export function openForRead(root: string = projectRoot()): DatabaseSync | undefi
   return db;
 }
 
+function storedHashes(db: DatabaseSync): Record<string, string> {
+  const row = db.prepare("SELECT value FROM meta WHERE key = 'text_hashes'").get() as { value: string } | undefined;
+  return row === undefined ? {} : (JSON.parse(row.value) as Record<string, string>);
+}
+
+function storeHashes(db: DatabaseSync, hashes: Record<string, string>): void {
+  const sorted = Object.fromEntries(Object.entries(hashes).sort(([a], [b]) => compareText(a, b)));
+  db.prepare("INSERT INTO meta (key, value) VALUES ('text_hashes', ?) ON CONFLICT (key) DO UPDATE SET value = excluded.value").run(JSON.stringify(sorted));
+}
+
+/** The SHA-256 of each knowledge file, by file name, in name order. */
+function textHashes(files: ReadonlyMap<string, { sha256: string }>): Record<string, string> {
+  return Object.fromEntries([...files].map(([name, file]): [string, string] => [name, file.sha256]).sort(([a], [b]) => compareText(a, b)));
+}
+
+const sameHashes = (a: Record<string, string>, b: Record<string, string>) => JSON.stringify(Object.entries(a).sort()) === JSON.stringify(Object.entries(b).sort());
+
 /**
- * Opens the project's knowledge database for a write, creating
- * .c64-re-tools/knowledge.db and its schema when needed. Refuses a schema
- * version other than this build's.
+ * Makes the index equal to the text when a knowledge file has another
+ * SHA-256 than the index holds, or a file came or went. Runs inside a write
+ * transaction, so two processes never make the index at the same time.
+ */
+function freshen(db: DatabaseSync, root: string): void {
+  const files = readText(textPath(root));
+  const hashes = textHashes(files);
+  if (sameHashes(hashes, storedHashes(db))) return;
+  db.exec("DELETE FROM evidence");
+  for (const spec of TABLES) db.exec(`DELETE FROM ${sqlName(spec.table)}`);
+  db.exec("DELETE FROM revisions");
+  loadText(db, files);
+  storeHashes(db, hashes);
+}
+
+/** The project of each index opened for a write: its writes go to the text too. */
+const projects = new WeakMap<DatabaseSync, string>();
+
+/**
+ * Opens the project's knowledge read-only, made fresh from the text first. A
+ * read never changes the knowledge. Returns undefined when the project has no
+ * knowledge text: that reads as empty knowledge, and a read creates nothing.
+ */
+export function openForRead(root: string = projectRoot()): DatabaseSync | undefined {
+  refuseOldLayout(root);
+  if (!existsSync(textPath(root))) return undefined;
+  const index = openIndex(root);
+  try {
+    // The lock is taken only when the text changed: a read does not wait for a long write that keeps the index fresh.
+    if (!sameHashes(textHashes(readText(textPath(root))), storedHashes(index))) transaction(index, () => freshen(index, root));
+  } finally {
+    index.close();
+  }
+  return open(indexPath(root), true);
+}
+
+/**
+ * Opens the project's knowledge for a write: it creates
+ * .c64-re-tools/knowledge/ with its .gitattributes when needed, and the index.
+ * Every committed transaction on the database writes the changed knowledge
+ * files.
  */
 export function openForWrite(root: string = projectRoot()): DatabaseSync {
-  mkdirSync(join(root, KNOWLEDGE_DIRECTORY), { recursive: true });
-  const db = open(knowledgePath(root), false);
+  refuseOldLayout(root);
+  mkdirSync(textPath(root), { recursive: true });
+  const attributes = join(textPath(root), ".gitattributes");
+  if (!existsSync(attributes)) writeFileSync(attributes, GIT_ATTRIBUTES);
+  const db = openIndex(root);
+  projects.set(db, root);
   try {
-    ensureSchema(db);
+    transaction(db, () => undefined);
   } catch (error) {
     db.close();
     throw error;
@@ -94,13 +172,14 @@ export function openForWrite(root: string = projectRoot()): DatabaseSync {
 }
 
 /**
- * Runs one write on the project's knowledge database and closes it. When the
- * project has no knowledge.db yet, `work` first runs on an empty database in
- * memory: a write that is refused there creates no .c64-re-tools/. `work`
- * must change nothing outside the database it gets.
+ * Runs one write on the project's knowledge and closes it. When the project
+ * has no knowledge yet, `work` first runs on an empty database in memory: a
+ * write that is refused there creates no .c64-re-tools/. `work` must change
+ * nothing outside the database it gets.
  */
 export function withWrite<T>(work: (db: DatabaseSync) => T, root: string = projectRoot()): T {
-  if (!existsSync(knowledgePath(root))) {
+  refuseOldLayout(root);
+  if (!existsSync(textPath(root))) {
     const trial = new DatabaseSync(":memory:");
     try {
       configure(trial);
@@ -118,11 +197,44 @@ export function withWrite<T>(work: (db: DatabaseSync) => T, root: string = proje
   }
 }
 
-/** Runs `work` in one immediate transaction: all of it commits, or none of it does. */
+/** The newest revision id, or "0" when there is none. */
+function newest(db: DatabaseSync): string {
+  return (db.prepare("SELECT max(id) AS id FROM revisions").get() as { id: string | null }).id ?? "0";
+}
+
+/**
+ * Writes the knowledge files that the revisions after `before` changed, then
+ * keeps their SHA-256 in the index. The text is written before the index
+ * commits: when the commit fails, the next open makes the index from the text.
+ */
+function writeText(db: DatabaseSync, root: string, before: string): void {
+  const directory = textPath(root);
+  const hashes = storedHashes(db);
+  const write = (file: string, text: string) => {
+    writeAtomic(join(directory, file), text);
+    hashes[file] = sha256(text);
+  };
+  write(REVISIONS_FILE, revisionsText(db));
+  for (const spec of TABLES) {
+    const changed = db.prepare(`SELECT 1 FROM ${sqlName(spec.table)} WHERE valid_from_revision > ? OR valid_to_revision > ? LIMIT 1`).get(before, before);
+    if (changed !== undefined) write(spec.file, tableText(db, spec));
+  }
+  storeHashes(db, hashes);
+}
+
+/**
+ * Runs `work` in one immediate transaction: all of it commits, or none of it
+ * does. On the knowledge of a project, the index is made fresh from the text
+ * first, and a work that adds a revision writes the changed knowledge files.
+ */
 export function transaction<T>(db: DatabaseSync, work: () => T): T {
+  const root = projects.get(db);
   db.exec("BEGIN IMMEDIATE");
   try {
+    if (root !== undefined) freshen(db, root);
+    const before = root === undefined ? "0" : newest(db);
     const result = work();
+    if (root !== undefined && newest(db) !== before) writeText(db, root, before);
     db.exec("COMMIT");
     return result;
   } catch (error) {

package/src/knowledge/expression.ts

@@ -0,0 +1,209 @@
+// Operand expressions (D65): the part of ACME's expression syntax that names
+// an operand by symbols and numbers. Knowledge checks an expression against
+// the image with it, and c64-source writes it with the names of its layout.
+//
+// Priorities are ACME's, from high to low: unary - and !, then * / %, + -,
+// << >> >>>, unary < and >, &, XOR, |. A unary < or > takes everything of a
+// higher priority after it, so <a+1 is the low byte of a+1.
+
+/** An expression that does not parse, or that names a symbol with no value. */
+export class ExpressionError extends Error {
+  override name = "ExpressionError";
+}
+
+/** The selectors of an operand expression: a byte of a symbol, its value, or free expression text. */
+export const OPERAND_SELECTS = ["lo", "hi", "value", "expr"] as const;
+export type OperandSelect = (typeof OPERAND_SELECTS)[number];
+
+/** An operand expression as knowledge stores it: a symbol with an offset, or text for expr. */
+export interface OperandExpression {
+  select: OperandSelect;
+  symbol?: string;
+  offset?: number;
+  expression?: string;
+}
+
+type Node =
+  | { kind: "number"; value: number }
+  | { kind: "name"; name: string }
+  | { kind: "unary"; operator: string; operand: Node }
+  | { kind: "binary"; operator: string; left: Node; right: Node };
+
+/** Binary operators by priority (higher binds tighter); unary < and > sit at LOW_HIGH. */
+const BINARY: Record<string, number> = { "*": 10, "/": 10, "%": 10, "+": 9, "-": 9, "<<": 8, ">>": 8, ">>>": 8, "&": 4, XOR: 3, "|": 2 };
+const LOW_HIGH = 7;
+const NAME = /^[A-Za-z_.][A-Za-z0-9_]*/;
+const MAX_TEXT = 200;
+
+interface Token {
+  text: string;
+  at: number;
+}
+
+/** The expression as tokens with their offsets; context decides % (binary literal or remainder). */
+function tokenize(text: string): Token[] {
+  const tokens: Token[] = [];
+  let at = 0;
+  let operandNext = true;
+  while (at < text.length) {
+    const rest = text.slice(at);
+    const space = /^\s+/.exec(rest);
+    if (space) {
+      at += space[0].length;
+      continue;
+    }
+    const number: RegExpExecArray | null = operandNext ? /^(\$[0-9A-Fa-f]+|%[01]+|[0-9]+)/.exec(rest) : null;
+    const match: RegExpExecArray | null = number ?? /^(>>>|<<|>>|XOR\b)/.exec(rest) ?? NAME.exec(rest) ?? /^[-+*/%&|!<>()]/.exec(rest);
+    if (!match) throw new ExpressionError(`"${text}" has an unknown character at position ${at + 1}: "${rest[0]}".`);
+    const token: string = match[0];
+    tokens.push({ text: token, at });
+    at += token.length;
+    // After an operand or a ), an operator comes next; after anything else, an operand.
+    operandNext = !(number !== null || (NAME.test(token) && token !== "XOR") || token === ")");
+  }
+  return tokens;
+}
+
+function parse(text: string): Node {
+  if (text.trim().length === 0) throw new ExpressionError("An expression is empty.");
+  if (text.length > MAX_TEXT) throw new ExpressionError(`An expression has at most ${MAX_TEXT} characters.`);
+  const tokens = tokenize(text);
+  let index = 0;
+  const peek = () => tokens[index]?.text;
+  const fail = (what: string): never => {
+    throw new ExpressionError(`"${text}" ${what}.`);
+  };
+
+  const operand = (): Node => {
+    const token = tokens[index++]?.text ?? fail("ends where an operand is missing");
+    if (token === "(") {
+      const inner = binary(0);
+      if (tokens[index++]?.text !== ")") fail("has a ( with no )");
+      return inner;
+    }
+    if (token === "-" || token === "!") return { kind: "unary", operator: token, operand: operand() };
+    if (token === "<" || token === ">") return { kind: "unary", operator: token, operand: binary(LOW_HIGH + 1) };
+    if (token.startsWith("$")) return { kind: "number", value: Number.parseInt(token.slice(1), 16) };
+    if (token.startsWith("%")) return { kind: "number", value: Number.parseInt(token.slice(1), 2) };
+    if (/^[0-9]/.test(token)) return { kind: "number", value: Number.parseInt(token, 10) };
+    if (NAME.test(token) && token !== "XOR") return { kind: "name", name: token };
+    return fail(`has "${token}" where an operand must be`);
+  };
+
+  const binary = (minimum: number): Node => {
+    let left = operand();
+    for (;;) {
+      const operator = peek();
+      const priority = operator === undefined ? undefined : BINARY[operator];
+      if (priority === undefined || priority < minimum) return left;
+      index++;
+      left = { kind: "binary", operator: operator!, left, right: binary(priority + 1) };
+    }
+  };
+
+  const tree = binary(0);
+  if (index < tokens.length) fail(`has "${tokens[index]!.text}" after the end of the expression`);
+  return tree;
+}
+
+function names(node: Node, into: string[]): string[] {
+  if (node.kind === "name" && !into.includes(node.name)) into.push(node.name);
+  if (node.kind === "unary") names(node.operand, into);
+  if (node.kind === "binary") {
+    names(node.left, into);
+    names(node.right, into);
+  }
+  return into;
+}
+
+function value(node: Node, resolve: (name: string) => number | undefined): number {
+  switch (node.kind) {
+    case "number":
+      return node.value;
+    case "name": {
+      const found = resolve(node.name);
+      if (found === undefined) throw new ExpressionError(`"${node.name}" is no symbol of the knowledge and no platform name.`);
+      return found;
+    }
+    case "unary": {
+      const inner = value(node.operand, resolve);
+      if (node.operator === "-") return -inner;
+      if (node.operator === "!") return ~inner;
+      return node.operator === "<" ? inner & 0xff : (inner >> 8) & 0xff;
+    }
+    case "binary": {
+      const left = value(node.left, resolve);
+      const right = value(node.right, resolve);
+      switch (node.operator) {
+        case "*":
+          return left * right;
+        case "/":
+        case "%":
+          if (right === 0) throw new ExpressionError("An expression divides by zero.");
+          return node.operator === "/" ? Math.trunc(left / right) : left % right;
+        case "+":
+          return left + right;
+        case "-":
+          return left - right;
+        case "<<":
+          return left << right;
+        case ">>":
+          return left >> right;
+        case ">>>":
+          return left >>> right;
+        case "&":
+          return left & right;
+        case "XOR":
+          return left ^ right;
+        default:
+          return left | right;
+      }
+    }
+  }
+}
+
+/** Throws ExpressionError when the text is no expression of this syntax. */
+export function checkExpression(text: string): void {
+  parse(text);
+}
+
+/** The value of the expression; `resolve` gives the value of a name, or undefined. */
+export function evaluate(text: string, resolve: (name: string) => number | undefined): number {
+  return value(parse(text), resolve);
+}
+
+/** The names the expression uses, each once, in their order. */
+export function identifiers(text: string): string[] {
+  return names(parse(text), []);
+}
+
+/**
+ * The text with each name replaced by `replace(name)` (a name it returns
+ * unchanged stays). Spaces and other tokens stay as written.
+ */
+export function replaceIdentifiers(text: string, replace: (name: string) => string): string {
+  parse(text);
+  let out = "";
+  let from = 0;
+  for (const token of tokenize(text)) {
+    if (!NAME.test(token.text) || token.text === "XOR") continue;
+    out += text.slice(from, token.at) + replace(token.text);
+    from = token.at + token.text.length;
+  }
+  return out + text.slice(from);
+}
+
+function offsetText(offset: number): string {
+  const size = Math.abs(offset);
+  return `${offset < 0 ? "-" : "+"}${size < 10 ? String(size) : `$${size.toString(16)}`}`;
+}
+
+/** ACME text of an operand expression, for example <irq_handler, >(sprite_bank+$1000) or bar_colours-1. */
+export function operandText(operand: OperandExpression): string {
+  if (operand.select === "expr") return operand.expression!;
+  const offset = operand.offset ?? 0;
+  const sum = offset === 0 ? operand.symbol! : `${operand.symbol!}${offsetText(offset)}`;
+  if (operand.select === "value") return sum;
+  const selector = operand.select === "lo" ? "<" : ">";
+  return offset === 0 ? `${selector}${sum}` : `${selector}(${sum})`;
+}

package/src/knowledge/graph.ts

@@ -0,0 +1,104 @@
+// The routine graph of the knowledge (D78, D80): which routine calls, jumps
+// to or dispatches through a table to which other routine, and the same
+// graph as a mermaid flowchart. The callers give the rows, so the graph needs
+// no database and the documentation and the knowledge script draw one graph.
+
+import { formatC64Address } from "../c64.ts";
+import type { ReferenceKind, SymbolKind } from "./schema.ts";
+
+/** How one routine reaches another: a call, a jump, or an entry of a table of addresses. */
+export type EdgeKind = "call" | "jump" | "table";
+
+export interface GraphReference {
+  from: number;
+  to: number;
+  kind: ReferenceKind | "table";
+}
+
+export interface RoutineHead {
+  address: number;
+  name: string;
+}
+
+export interface GraphEdge {
+  from: number;
+  to: number;
+  /** The strongest kind of the references that make the edge: a call, then a table entry, then a jump. */
+  kind: EdgeKind;
+  /** The references that make the edge. */
+  count: number;
+}
+
+const STRENGTH: Record<EdgeKind, number> = { call: 3, table: 2, jump: 1 };
+
+/**
+ * The routine heads: every routine of the knowledge, and every call or table
+ * target, which another routine enters at its start. A head without a name of
+ * the knowledge gets the name that `nameOf` gives.
+ */
+export function routineHeads(symbols: ReadonlyArray<{ address: number; name: string; kind: SymbolKind }>, references: readonly GraphReference[], nameOf: (address: number) => string): RoutineHead[] {
+  const names = new Map(symbols.map((symbol) => [symbol.address, symbol.name]));
+  const heads = new Set(symbols.filter((symbol) => symbol.kind === "routine").map((symbol) => symbol.address));
+  for (const reference of references) if (reference.kind === "call" || reference.kind === "table") heads.add(reference.to);
+  return [...heads].sort((a, b) => a - b).map((address) => ({ address, name: names.get(address) ?? nameOf(address) }));
+}
+
+/**
+ * The head that holds an address: the nearest head at or below it, when no
+ * boundary (a module start) lies between the two.
+ */
+export function ownerOf(heads: readonly RoutineHead[], boundaries: readonly number[], address: number): RoutineHead | undefined {
+  let low = 0;
+  let high = heads.length - 1;
+  let found: RoutineHead | undefined;
+  while (low <= high) {
+    const middle = (low + high) >> 1;
+    if (heads[middle]!.address <= address) {
+      found = heads[middle];
+      low = middle + 1;
+    } else high = middle - 1;
+  }
+  if (found === undefined) return undefined;
+  return boundaries.some((boundary) => boundary > found.address && boundary <= address) ? undefined : found;
+}
+
+/** The edges between routines: each call, jump or table reference from one head's code to another head; a jump inside a routine is no edge. */
+export function routineEdges(heads: readonly RoutineHead[], boundaries: readonly number[], references: readonly GraphReference[]): GraphEdge[] {
+  const edges = new Map<string, GraphEdge>();
+  for (const reference of references) {
+    if (reference.kind !== "call" && reference.kind !== "jump" && reference.kind !== "table") continue;
+    const from = ownerOf(heads, boundaries, reference.from);
+    const to = ownerOf(heads, boundaries, reference.to);
+    if (from === undefined || to === undefined || from.address === to.address) continue;
+    // A jump into the middle of another routine is an edge to that routine.
+    const key = `${from.address}:${to.address}`;
+    const edge = edges.get(key);
+    if (edge === undefined) edges.set(key, { from: from.address, to: to.address, kind: reference.kind, count: 1 });
+    else {
+      edge.count++;
+      if (STRENGTH[reference.kind] > STRENGTH[edge.kind]) edge.kind = reference.kind;
+    }
+  }
+  return [...edges.values()].sort((a, b) => a.from - b.from || a.to - b.to);
+}
+
+const ARROWS: Record<EdgeKind, string> = { call: "-->", table: "==>", jump: "-.->" };
+
+/**
+ * A mermaid flowchart of the edges: a node per head with its name and
+ * address, a solid arrow for a call, a thick one for a table entry and a
+ * dotted one for a jump. The heads in `own` are drawn as rounded nodes.
+ */
+export function mermaidGraph(heads: readonly RoutineHead[], edges: readonly GraphEdge[], own: ReadonlySet<number> = new Set()): string {
+  const used = new Set(edges.flatMap((edge) => [edge.from, edge.to]));
+  for (const address of own) used.add(address);
+  const id = (address: number) => `n${address.toString(16).padStart(4, "0")}`;
+  const lines = ["flowchart LR"];
+  for (const head of heads) {
+    if (!used.has(head.address)) continue;
+    const label = `${head.name}<br/>${formatC64Address(head.address).toUpperCase()}`;
+    lines.push(own.has(head.address) ? `  ${id(head.address)}("${label}")` : `  ${id(head.address)}["${label}"]`);
+  }
+  for (const edge of edges) lines.push(`  ${id(edge.from)} ${ARROWS[edge.kind]} ${id(edge.to)}`);
+  return lines.join("\n");
+}