@henols/c64-re-tools 2.0.0-rc.11 → 2.0.0-rc.13

package/src/knowledge/history.ts

@@ -6,32 +6,43 @@ import type { DatabaseSync } from "node:sqlite";
 import { KnowledgeError } from "./database.ts";
 import {
   COMMENT_COLUMNS,
+  MACRO_COLUMNS,
+  MACRO_USE_COLUMNS,
   MODULE_COLUMNS,
   OPERAND_COLUMNS,
+  PATCH_COLUMNS,
   REFERENCE_COLUMNS,
   REGION_COLUMNS,
+  resolveRevision,
   SUPPRESSION_COLUMNS,
   SYMBOL_COLUMNS,
   toComment,
+  toMacro,
+  toMacroUse,
   toModule,
   toOperand,
+  toPatch,
   toReference,
   toRegion,
   toSuppression,
   toSymbol,
   type CommentRow,
+  type MacroRow,
+  type MacroUseRow,
   type ModuleRow,
   type OperandRow,
+  type PatchRow,
   type ReferenceRow,
   type RegionRow,
   type SuppressionRow,
   type SymbolRow,
 } from "./read.ts";
 import { DEFAULT_SPACE, type EvidenceKind, type Origin, type Space } from "./schema.ts";
+import { compareText } from "./text.ts";
 import type { Evidence } from "./write.ts";
 
 export interface Revision {
-  id: number;
+  id: string;
   createdAt: string;
   origin: Origin;
   operation: string;
@@ -44,19 +55,22 @@ export interface Revision {
 
 /** One knowledge row with its validity: from its first revision until the revision that closed it. */
 export type HistoryEntry =
-  | { entity: "symbol"; row: SymbolRow; from: number; to?: number }
-  | { entity: "region"; row: RegionRow; from: number; to?: number }
-  | { entity: "comment"; row: CommentRow; from: number; to?: number }
-  | { entity: "reference"; row: ReferenceRow; from: number; to?: number }
-  | { entity: "suppression"; row: SuppressionRow; from: number; to?: number }
-  | { entity: "module"; row: ModuleRow; from: number; to?: number }
-  | { entity: "operand"; row: OperandRow; from: number; to?: number };
+  | { entity: "symbol"; row: SymbolRow; from: string; to?: string }
+  | { entity: "region"; row: RegionRow; from: string; to?: string }
+  | { entity: "comment"; row: CommentRow; from: string; to?: string }
+  | { entity: "reference"; row: ReferenceRow; from: string; to?: string }
+  | { entity: "suppression"; row: SuppressionRow; from: string; to?: string }
+  | { entity: "module"; row: ModuleRow; from: string; to?: string }
+  | { entity: "operand"; row: OperandRow; from: string; to?: string }
+  | { entity: "patch"; row: PatchRow; from: string; to?: string }
+  | { entity: "macro"; row: MacroRow; from: string; to?: string }
+  | { entity: "macro-use"; row: MacroUseRow; from: string; to?: string };
 
 type Raw = Record<string, unknown>;
 
 function toRevision(row: Raw): Revision {
   const revision: Revision = {
-    id: row.id as number,
+    id: row.id as string,
     createdAt: row.created_at as string,
     origin: row.origin as Origin,
     operation: row.operation as string,
@@ -68,13 +82,14 @@ function toRevision(row: Raw): Revision {
 }
 
 function entry<E extends HistoryEntry["entity"]>(entity: E, row: unknown, raw: Raw): HistoryEntry {
-  const result = { entity, row, from: raw.valid_from_revision as number } as HistoryEntry;
-  if (raw.valid_to_revision !== null) result.to = raw.valid_to_revision as number;
+  const result = { entity, row, from: raw.valid_from_revision as string } as HistoryEntry;
+  if (raw.valid_to_revision !== null) result.to = raw.valid_to_revision as string;
   return result;
 }
 
+/** Revision ids sort in time order as text (D69); a current row sorts after every closed one. */
 function bySequence(a: HistoryEntry, b: HistoryEntry): number {
-  return a.from - b.from || (a.to ?? Infinity) - (b.to ?? Infinity);
+  return compareText(a.from, b.from) || compareText(a.to ?? "~", b.to ?? "~");
 }
 
 /** Every row, current or closed, that concerns one address of a space, oldest first. */
@@ -97,9 +112,23 @@ export function historyAt(db: DatabaseSync | undefined, address: number, space:
   }
   for (const raw of db.prepare(`SELECT ${MODULE_COLUMNS}${validity} FROM modules WHERE space = ? AND start_address = ?`).all(space, address) as Raw[]) entries.push(entry("module", toModule(raw), raw));
   for (const raw of db.prepare(`SELECT ${OPERAND_COLUMNS}${validity} FROM operands WHERE space = ? AND address = ?`).all(space, address) as Raw[]) entries.push(entry("operand", toOperand(raw), raw));
+  for (const raw of db.prepare(`SELECT ${PATCH_COLUMNS}${validity} FROM patches WHERE space = ? AND start_address <= ? AND end_address >= ?`).all(space, address, address) as Raw[]) {
+    entries.push(entry("patch", toPatch(raw), raw));
+  }
+  for (const raw of db.prepare(`SELECT ${MACRO_USE_COLUMNS}${validity} FROM macro_uses WHERE space = ? AND start_address <= ? AND end_address >= ?`).all(space, address, address) as Raw[]) {
+    entries.push(entry("macro-use", toMacroUse(raw), raw));
+  }
   return entries.sort(bySequence);
 }
 
+/** Every row of a macro with this name, and every use of it, oldest first. */
+export function historyOfMacro(db: DatabaseSync | undefined, name: string, space: Space = DEFAULT_SPACE): HistoryEntry[] {
+  if (db === undefined) return [];
+  const macros = (db.prepare(`SELECT ${MACRO_COLUMNS}, valid_to_revision FROM macros WHERE space = ? AND name = ?`).all(space, name) as Raw[]).map((raw) => entry("macro", toMacro(raw), raw));
+  const uses = (db.prepare(`SELECT ${MACRO_USE_COLUMNS}, valid_to_revision FROM macro_uses WHERE space = ? AND macro = ?`).all(space, name) as Raw[]).map((raw) => entry("macro-use", toMacroUse(raw), raw));
+  return [...macros, ...uses].sort(bySequence);
+}
+
 /** Every symbol row of a space that ever had this name, oldest first: a name can move between addresses. */
 export function historyNamed(db: DatabaseSync | undefined, name: string, space: Space = DEFAULT_SPACE): HistoryEntry[] {
   if (db === undefined) return [];
@@ -109,7 +138,7 @@ export function historyNamed(db: DatabaseSync | undefined, name: string, space:
 }
 
 /** Why a revision was written and what it rests on: its description and its evidence, when it has them. */
-export function revisionNote(db: DatabaseSync | undefined, id: number): { reason?: string; evidence?: Evidence[] } {
+export function revisionNote(db: DatabaseSync | undefined, id: string): { reason?: string; evidence?: Evidence[] } {
   const raw = db?.prepare("SELECT * FROM revisions WHERE id = ?").get(id) as Raw | undefined;
   if (db === undefined || raw === undefined) return {};
   const { description, evidence } = withEvidence(db, toRevision(raw));
@@ -125,13 +154,13 @@ function withEvidence(db: DatabaseSync, revision: Revision): Revision {
 }
 
 /** Revisions, newest first; with `before`, only revisions older than it. */
-export function revisions(db: DatabaseSync | undefined, options: { limit?: number; before?: number } = {}): Revision[] {
+export function revisions(db: DatabaseSync | undefined, options: { limit?: number; before?: string } = {}): Revision[] {
   if (db === undefined) return [];
-  return (
-    db
-      .prepare("SELECT * FROM revisions WHERE id < ? ORDER BY id DESC LIMIT ?")
-      .all(options.before ?? Number.MAX_SAFE_INTEGER, options.limit ?? 50) as Raw[]
-  ).map((row) => withEvidence(db, toRevision(row)));
+  const rows =
+    options.before === undefined
+      ? db.prepare("SELECT * FROM revisions ORDER BY id DESC LIMIT ?").all(options.limit ?? 50)
+      : db.prepare("SELECT * FROM revisions WHERE id < ? ORDER BY id DESC LIMIT ?").all(resolveRevision(db, options.before), options.limit ?? 50);
+  return (rows as Raw[]).map((row) => withEvidence(db, toRevision(row)));
 }
 
 export interface RevisionChanges {
@@ -143,7 +172,8 @@ export interface RevisionChanges {
 }
 
 /** One revision and exactly what it changed. */
-export function revision(db: DatabaseSync | undefined, id: number): RevisionChanges {
+export function revision(db: DatabaseSync | undefined, text: string): RevisionChanges {
+  const id = resolveRevision(db, text);
   const raw = db?.prepare("SELECT * FROM revisions WHERE id = ?").get(id) as Raw | undefined;
   if (db === undefined || raw === undefined) throw new KnowledgeError("not-found", `There is no revision ${id}.`);
   const tables = [
@@ -154,6 +184,9 @@ export function revision(db: DatabaseSync | undefined, id: number): RevisionChan
     ["suppression", "suppressions", SUPPRESSION_COLUMNS, toSuppression],
     ["module", "modules", MODULE_COLUMNS, toModule],
     ["operand", "operands", OPERAND_COLUMNS, toOperand],
+    ["patch", "patches", PATCH_COLUMNS, toPatch],
+    ["macro", "macros", MACRO_COLUMNS, toMacro],
+    ["macro-use", "macro_uses", MACRO_USE_COLUMNS, toMacroUse],
   ] as const;
   const added: HistoryEntry[] = [];
   const closed: HistoryEntry[] = [];
@@ -167,3 +200,4 @@ export function revision(db: DatabaseSync | undefined, id: number): RevisionChan
   }
   return { revision: withEvidence(db, toRevision(raw)), added, closed };
 }
+

package/src/knowledge/import.ts

@@ -55,7 +55,7 @@ export interface NormalizedFindings {
 
 export interface ImportContext {
   /** The revision the caller read; the import is refused if knowledge changed since. */
-  expectedRevision?: number;
+  expectedRevision?: string;
   description?: string;
   /** The SHA-256 of the analyzed image, as lowercase hex. */
   inputHash?: string;
@@ -92,7 +92,7 @@ export interface ImportCounts {
 
 export interface ImportResult {
   /** The new revision, or null when nothing changed. */
-  revision: number | null;
+  revision: string | null;
   symbols: ImportCounts;
   regions: ImportCounts;
   references: ImportCounts;
@@ -386,6 +386,7 @@ export function importFindings(db: DatabaseSync, findings: NormalizedFindings, c
     importSymbols(db, change, findings, coverage, result);
     importRegions(db, change, findings, coverage, result);
     importReferences(db, change, findings, coverage, result);
+    change.check();
     result.revision = change.revision;
     return result;
   });

package/src/knowledge/read.ts

@@ -1,10 +1,12 @@
-// Current-state knowledge queries. A project without a database
+// Current-state knowledge queries. A project without knowledge
 // reads as empty knowledge. Each query reads one address space (D53); the
 // default is the C64.
 
 import type { DatabaseSync } from "node:sqlite";
 
+import { KnowledgeError } from "./database.ts";
 import { DEFAULT_SPACE, type CommentPlacement, type OperandSelect, type Origin, type ReferenceKind, type RegionType, type Space, type SuppressionEntity, type SymbolKind } from "./schema.ts";
+import { NO_REVISION } from "./text.ts";
 
 export interface SymbolRow {
   space: Space;
@@ -12,7 +14,7 @@ export interface SymbolRow {
   name: string;
   kind: SymbolKind;
   origin: Origin;
-  revision: number;
+  revision: string;
 }
 
 export interface RegionRow {
@@ -23,7 +25,7 @@ export interface RegionRow {
   /** Bytes per element of a table; the length is a multiple of it (D42). */
   element?: number;
   origin: Origin;
-  revision: number;
+  revision: string;
 }
 
 export interface CommentRow {
@@ -32,7 +34,7 @@ export interface CommentRow {
   placement: CommentPlacement;
   text: string;
   origin: Origin;
-  revision: number;
+  revision: string;
 }
 
 export interface ReferenceRow {
@@ -41,7 +43,7 @@ export interface ReferenceRow {
   to: number;
   kind: ReferenceKind;
   origin: Origin;
-  revision: number;
+  revision: string;
 }
 
 /** A place that a user/LLM removal blocks for every analyzer (D36). `to` and `kind` are set for a reference only. */
@@ -53,7 +55,7 @@ export interface SuppressionRow {
   to?: number;
   kind?: ReferenceKind;
   origin: Extract<Origin, "user" | "llm">;
-  revision: number;
+  revision: string;
 }
 
 /** Where a file of the generated source starts (D48): it runs to the next module or the end of its segment. */
@@ -63,7 +65,7 @@ export interface ModuleRow {
   file: string;
   title?: string;
   origin: Extract<Origin, "user" | "llm">;
-  revision: number;
+  revision: string;
 }
 
 /**
@@ -79,9 +81,50 @@ export interface OperandRow {
   offset: number;
   expression?: string;
   origin: Extract<Origin, "user" | "llm">;
-  revision: number;
+  revision: string;
 }
 
+/**
+ * Code that replaces [start, end] when the build defines the switch as 1
+ * (D72). The code fits the range; NOP fills the rest. Empty code is only NOP.
+ */
+export interface PatchRow {
+  space: Space;
+  start: number;
+  end: number;
+  switch: string;
+  code: string;
+  comment?: string;
+  origin: Extract<Origin, "user" | "llm">;
+  revision: string;
+}
+
+/** An ACME macro of the generated source (D73). The body names a parameter with a dot in front: .dst. */
+export interface MacroRow {
+  space: Space;
+  name: string;
+  params: string[];
+  body: string;
+  comment?: string;
+  origin: Extract<Origin, "user" | "llm">;
+  revision: string;
+}
+
+/** The instructions in [start, end] written as one use of a macro, with one expression for each parameter (D73). */
+export interface MacroUseRow {
+  space: Space;
+  start: number;
+  end: number;
+  macro: string;
+  args: string[];
+  origin: Extract<Origin, "user" | "llm">;
+  revision: string;
+}
+
+/** A list of params or args as the knowledge stores it: the items with ", " between them. */
+export const listText = (items: readonly string[]) => items.join(", ");
+const items = (text: string) => (text.trim() === "" ? [] : text.split(",").map((item) => item.trim()));
+
 type Raw = Record<string, unknown>;
 
 export const SYMBOL_COLUMNS = "space, address, name, kind, origin, valid_from_revision";
@@ -91,9 +134,12 @@ export const REFERENCE_COLUMNS = "space, from_address, to_address, kind, origin,
 export const SUPPRESSION_COLUMNS = "space, entity, start_address, end_address, to_address, kind, origin, valid_from_revision";
 export const MODULE_COLUMNS = "space, start_address, file, title, origin, valid_from_revision";
 export const OPERAND_COLUMNS = "space, address, selector, symbol, offset, expression, origin, valid_from_revision";
+export const PATCH_COLUMNS = "space, start_address, end_address, switch_name, code, comment, origin, valid_from_revision";
+export const MACRO_COLUMNS = "space, name, params, body, comment, origin, valid_from_revision";
+export const MACRO_USE_COLUMNS = "space, start_address, end_address, macro, args, origin, valid_from_revision";
 
 export function toSymbol(row: Raw): SymbolRow {
-  return { space: row.space as Space, address: row.address as number, name: row.name as string, kind: row.kind as SymbolKind, origin: row.origin as Origin, revision: row.valid_from_revision as number };
+  return { space: row.space as Space, address: row.address as number, name: row.name as string, kind: row.kind as SymbolKind, origin: row.origin as Origin, revision: row.valid_from_revision as string };
 }
 
 export function toRegion(row: Raw): RegionRow {
@@ -103,7 +149,7 @@ export function toRegion(row: Raw): RegionRow {
     end: row.end_address as number,
     type: row.type as RegionType,
     origin: row.origin as Origin,
-    revision: row.valid_from_revision as number,
+    revision: row.valid_from_revision as string,
   };
   if (row.element !== null && row.element !== undefined) region.element = row.element as number;
   return region;
@@ -116,12 +162,12 @@ export function toComment(row: Raw): CommentRow {
     placement: row.placement as CommentPlacement,
     text: row.text as string,
     origin: row.origin as Origin,
-    revision: row.valid_from_revision as number,
+    revision: row.valid_from_revision as string,
   };
 }
 
 export function toReference(row: Raw): ReferenceRow {
-  return { space: row.space as Space, from: row.from_address as number, to: row.to_address as number, kind: row.kind as ReferenceKind, origin: row.origin as Origin, revision: row.valid_from_revision as number };
+  return { space: row.space as Space, from: row.from_address as number, to: row.to_address as number, kind: row.kind as ReferenceKind, origin: row.origin as Origin, revision: row.valid_from_revision as string };
 }
 
 export function toSuppression(row: Raw): SuppressionRow {
@@ -131,7 +177,7 @@ export function toSuppression(row: Raw): SuppressionRow {
     start: row.start_address as number,
     end: row.end_address as number,
     origin: row.origin as SuppressionRow["origin"],
-    revision: row.valid_from_revision as number,
+    revision: row.valid_from_revision as string,
   };
   if (row.to_address !== null) suppression.to = row.to_address as number;
   if (row.kind !== null) suppression.kind = row.kind as ReferenceKind;
@@ -139,7 +185,7 @@ export function toSuppression(row: Raw): SuppressionRow {
 }
 
 export function toModule(row: Raw): ModuleRow {
-  const module: ModuleRow = { space: row.space as Space, start: row.start_address as number, file: row.file as string, origin: row.origin as ModuleRow["origin"], revision: row.valid_from_revision as number };
+  const module: ModuleRow = { space: row.space as Space, start: row.start_address as number, file: row.file as string, origin: row.origin as ModuleRow["origin"], revision: row.valid_from_revision as string };
   if (row.title !== null && row.title !== undefined) module.title = row.title as string;
   return module;
 }
@@ -151,16 +197,68 @@ export function toOperand(row: Raw): OperandRow {
     select: row.selector as OperandSelect,
     offset: row.offset as number,
     origin: row.origin as OperandRow["origin"],
-    revision: row.valid_from_revision as number,
+    revision: row.valid_from_revision as string,
   };
   if (row.symbol !== null && row.symbol !== undefined) operand.symbol = row.symbol as string;
   if (row.expression !== null && row.expression !== undefined) operand.expression = row.expression as string;
   return operand;
 }
 
-export function currentRevision(db: DatabaseSync | undefined): number {
-  if (db === undefined) return 0;
-  return Number((db.prepare("SELECT value FROM meta WHERE key = 'current_revision'").get() as { value: string }).value);
+export function toPatch(row: Raw): PatchRow {
+  const patch: PatchRow = {
+    space: row.space as Space,
+    start: row.start_address as number,
+    end: row.end_address as number,
+    switch: row.switch_name as string,
+    code: row.code as string,
+    origin: row.origin as PatchRow["origin"],
+    revision: row.valid_from_revision as string,
+  };
+  if (row.comment !== null && row.comment !== undefined) patch.comment = row.comment as string;
+  return patch;
+}
+
+export function toMacro(row: Raw): MacroRow {
+  const macro: MacroRow = { space: row.space as Space, name: row.name as string, params: items(row.params as string), body: row.body as string, origin: row.origin as MacroRow["origin"], revision: row.valid_from_revision as string };
+  if (row.comment !== null && row.comment !== undefined) macro.comment = row.comment as string;
+  return macro;
+}
+
+export function toMacroUse(row: Raw): MacroUseRow {
+  return {
+    space: row.space as Space,
+    start: row.start_address as number,
+    end: row.end_address as number,
+    macro: row.macro as string,
+    args: items(row.args as string),
+    origin: row.origin as MacroUseRow["origin"],
+    revision: row.valid_from_revision as string,
+  };
+}
+
+/** The id of the newest revision, or "0" when the knowledge has none (D69). */
+export function currentRevision(db: DatabaseSync | undefined): string {
+  if (db === undefined) return "0";
+  return (db.prepare("SELECT max(id) AS id FROM revisions").get() as { id: string | null }).id ?? "0";
+}
+
+/** At most this many ids are named when a start of an id fits several revisions. */
+const NAMED_REVISIONS = 5;
+
+/**
+ * The revision that `text` names (D69): "0" (no revision), a full revision id,
+ * or a start of an id that only one revision has.
+ */
+export function resolveRevision(db: DatabaseSync | undefined, text: string): string {
+  if (text === NO_REVISION) return NO_REVISION;
+  if (!/^[0-9a-zT.-]+$/.test(text)) throw new KnowledgeError("invalid-input", `${JSON.stringify(text)} is not a revision id. A revision id looks like 20261015T214501.123-k3f9qz; its start is enough when only one revision has it.`);
+  const found = (db?.prepare("SELECT id FROM revisions WHERE substr(id, 1, ?) = ? ORDER BY id LIMIT ?").all(text.length, text, NAMED_REVISIONS + 1) ?? []) as Array<{ id: string }>;
+  if (found.length === 0) throw new KnowledgeError("not-found", `There is no revision ${text}.`);
+  if (found.length > 1) {
+    const named = found.slice(0, NAMED_REVISIONS).map((row) => row.id).join(", ");
+    throw new KnowledgeError("invalid-input", `${text} is the start of more than one revision: ${named}${found.length > NAMED_REVISIONS ? ", ..." : ""}. Give more of the id.`);
+  }
+  return found[0]!.id;
 }
 
 export function symbolAt(db: DatabaseSync | undefined, address: number, space: Space = DEFAULT_SPACE): SymbolRow | undefined {
@@ -249,6 +347,29 @@ export function operandAt(db: DatabaseSync | undefined, address: number, space:
   return row === undefined ? undefined : toOperand(row);
 }
 
+/** Current patches that share at least one address with [start, end], in address order. */
+export function patchesOverlapping(db: DatabaseSync | undefined, start: number, end: number, space: Space = DEFAULT_SPACE): PatchRow[] {
+  if (db === undefined) return [];
+  return db
+    .prepare(`SELECT ${PATCH_COLUMNS} FROM current_patches WHERE space = ? AND start_address <= ? AND end_address >= ? ORDER BY start_address`)
+    .all(space, end, start)
+    .map((row) => toPatch(row as Raw));
+}
+
+/** Current macro uses that share at least one address with [start, end], in address order. */
+export function macroUsesOverlapping(db: DatabaseSync | undefined, start: number, end: number, space: Space = DEFAULT_SPACE): MacroUseRow[] {
+  if (db === undefined) return [];
+  return db
+    .prepare(`SELECT ${MACRO_USE_COLUMNS} FROM current_macro_uses WHERE space = ? AND start_address <= ? AND end_address >= ? ORDER BY start_address`)
+    .all(space, end, start)
+    .map((row) => toMacroUse(row as Raw));
+}
+
+export function macroNamed(db: DatabaseSync | undefined, name: string, space: Space = DEFAULT_SPACE): MacroRow | undefined {
+  const row = db?.prepare(`SELECT ${MACRO_COLUMNS} FROM current_macros WHERE space = ? AND name = ?`).get(space, name) as Raw | undefined;
+  return row === undefined ? undefined : toMacro(row);
+}
+
 /** Everything currently known at one address: the main lookup for skills. */
 export interface AddressKnowledge {
   space: Space;
@@ -261,9 +382,13 @@ export interface AddressKnowledge {
   referencesTo: ReferenceRow[];
   /** How the operand of the instruction here is written (D65). */
   operand?: OperandRow;
+  /** The patch whose range holds the address (D72). */
+  patch?: PatchRow;
+  /** The macro use whose range holds the address (D73). */
+  macroUse?: MacroUseRow;
   /** What user/LLM removals block here for the analyzers. */
   suppressions: SuppressionRow[];
-  revision: number;
+  revision: string;
 }
 
 export function at(db: DatabaseSync | undefined, address: number, space: Space = DEFAULT_SPACE): AddressKnowledge {
@@ -282,6 +407,10 @@ export function at(db: DatabaseSync | undefined, address: number, space: Space =
   if (region !== undefined) result.region = region;
   const operand = operandAt(db, address, space);
   if (operand !== undefined) result.operand = operand;
+  const [patch] = patchesOverlapping(db, address, address, space);
+  if (patch !== undefined) result.patch = patch;
+  const [macroUse] = macroUsesOverlapping(db, address, address, space);
+  if (macroUse !== undefined) result.macroUse = macroUse;
   return result;
 }
 
@@ -362,12 +491,32 @@ export function listOperands(db: DatabaseSync | undefined, range: Range = ALL, o
     .filter(kept(origins));
 }
 
+/** Current patches that share an address with the range, of one switch or of all, in address order. */
+export function listPatches(db: DatabaseSync | undefined, range: Range = ALL, switchName?: string, origins?: OriginFilter, space: Space = DEFAULT_SPACE): PatchRow[] {
+  return patchesOverlapping(db, range.start, range.end, space).filter((patch) => (switchName === undefined || patch.switch === switchName) && kept(origins)(patch));
+}
+
+/** Current macros, by name. */
+export function listMacros(db: DatabaseSync | undefined, origins?: OriginFilter, space: Space = DEFAULT_SPACE): MacroRow[] {
+  if (db === undefined) return [];
+  return db
+    .prepare(`SELECT ${MACRO_COLUMNS} FROM current_macros WHERE space = ? ORDER BY name`)
+    .all(space)
+    .map((row) => toMacro(row as Raw))
+    .filter(kept(origins));
+}
+
+/** Current macro uses that share an address with the range, of one macro or of all, in address order. */
+export function listMacroUses(db: DatabaseSync | undefined, range: Range = ALL, macro?: string, origins?: OriginFilter, space: Space = DEFAULT_SPACE): MacroUseRow[] {
+  return macroUsesOverlapping(db, range.start, range.end, space).filter((use) => (macro === undefined || use.macro === macro) && kept(origins)(use));
+}
+
 /** The spaces that hold current knowledge, the C64 first. */
 export function listSpaces(db: DatabaseSync | undefined): Space[] {
   if (db === undefined) return [];
   const rows = db
     .prepare(
-      `SELECT space FROM current_symbols UNION SELECT space FROM current_regions UNION SELECT space FROM current_comments UNION SELECT space FROM current_references UNION SELECT space FROM current_suppressions UNION SELECT space FROM current_modules UNION SELECT space FROM current_operands`,
+      `SELECT space FROM current_symbols UNION SELECT space FROM current_regions UNION SELECT space FROM current_comments UNION SELECT space FROM current_references UNION SELECT space FROM current_suppressions UNION SELECT space FROM current_modules UNION SELECT space FROM current_operands UNION SELECT space FROM current_patches UNION SELECT space FROM current_macros UNION SELECT space FROM current_macro_uses`,
     )
     .all() as Array<{ space: Space }>;
   const order = (space: Space) => (space === "c64" ? -2 : space === "drive8" ? -1 : Number(space.slice(4)));