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

package/skills/c64-static-analysis/scripts/macros.ts

@@ -0,0 +1,233 @@
+// Macro candidates (D73): runs of instructions that are a known 6502 idiom,
+// such as a 16-bit increment, and that a macro can write as one line. They
+// are only reported, never written: the LLM applies them as macro uses with
+// c64-knowledge, and c64-source writes a use only when it gives the bytes of
+// the image.
+//
+// The catalogue is fixed, so each candidate has a name and a body that is
+// known to be correct. A search for any repeated sequence was weighed and not
+// chosen: it gives many candidates without a name (D73).
+
+import { instructionLength } from "#src/c64.ts";
+import type { ImageByte } from "./coverage.ts";
+
+/** A macro of the catalogue: its params and its ACME body, which names a param with a dot. */
+export interface MacroIdiom {
+  name: string;
+  params: string[];
+  body: string;
+  comment: string;
+}
+
+export const CATALOGUE: readonly MacroIdiom[] = [
+  { name: "inc16", params: ["dst"], body: ["        inc .dst", "        bne +", "        inc .dst+1", "+"].join("\n"), comment: "Adds 1 to the 16-bit value at dst." },
+  { name: "dec16", params: ["dst"], body: ["        lda .dst", "        bne +", "        dec .dst+1", "+       dec .dst"].join("\n"), comment: "Subtracts 1 from the 16-bit value at dst. It changes A." },
+  {
+    name: "add16_8",
+    params: ["dst", "value"],
+    body: ["        clc", "        lda .dst", "        adc #.value", "        sta .dst", "        bcc +", "        inc .dst+1", "+"].join("\n"),
+    comment: "Adds the 8-bit value to the 16-bit value at dst. It changes A.",
+  },
+  {
+    name: "add16",
+    params: ["dst", "value"],
+    body: ["        clc", "        lda .dst", "        adc #<.value", "        sta .dst", "        lda .dst+1", "        adc #>.value", "        sta .dst+1"].join("\n"),
+    comment: "Adds the 16-bit value to the 16-bit value at dst. It changes A.",
+  },
+  {
+    name: "sub16",
+    params: ["dst", "value"],
+    body: ["        sec", "        lda .dst", "        sbc #<.value", "        sta .dst", "        lda .dst+1", "        sbc #>.value", "        sta .dst+1"].join("\n"),
+    comment: "Subtracts the 16-bit value from the 16-bit value at dst. It changes A.",
+  },
+  {
+    name: "set16",
+    params: ["dst", "value"],
+    body: ["        lda #<.value", "        sta .dst", "        lda #>.value", "        sta .dst+1"].join("\n"),
+    comment: "Puts the 16-bit value at dst. It changes A.",
+  },
+  {
+    name: "mov16",
+    params: ["dst", "src"],
+    body: ["        lda .src", "        sta .dst", "        lda .src+1", "        sta .dst+1"].join("\n"),
+    comment: "Copies the 16-bit value at src to dst. It changes A.",
+  },
+  { name: "wait_line", params: ["line"], body: ["        lda #.line", "-       cmp $d012", "        bne -"].join("\n"), comment: "Waits until the raster line (bits 0-7) is line. It changes A." },
+];
+
+/** A run of instructions that one macro of the catalogue can write, with its args as ACME expressions. */
+export interface MacroCandidate {
+  macro: string;
+  start: number;
+  end: number;
+  args: string[];
+}
+
+/** One instruction: its opcode, its length and its operand value. */
+interface Instruction {
+  opcode: number;
+  length: number;
+  value: number;
+}
+
+/** An address operand: zero page or absolute, of the same memory in one idiom. */
+interface Operand {
+  value: number;
+  absolute: boolean;
+}
+
+/** Opcodes by mnemonic, zero page first, then absolute. */
+const MEMORY = {
+  lda: [0xa5, 0xad],
+  sta: [0x85, 0x8d],
+  inc: [0xe6, 0xee],
+  dec: [0xc6, 0xce],
+} as const;
+const IMMEDIATE = { lda: 0xa9, adc: 0x69, sbc: 0xe9 } as const;
+const CLC = 0x18;
+const SEC = 0x38;
+const BNE = 0xd0;
+const BCC = 0x90;
+const CMP_ABSOLUTE = 0xcd;
+
+/**
+ * Names the args of a candidate: `address` gives the name of an address in
+ * the knowledge, or undefined. An absolute operand below $0100 keeps four
+ * digits, so ACME writes the absolute form again.
+ */
+export type Namer = (address: number) => string | undefined;
+
+const hex2 = (value: number) => `$${value.toString(16).padStart(2, "0")}`;
+const hex4 = (value: number) => `$${value.toString(16).padStart(4, "0")}`;
+
+function addressArg(operand: Operand, name: Namer): string {
+  const named = name(operand.value);
+  // A name of a zero-page address gives the zero-page form: an absolute operand there keeps its number.
+  if (named !== undefined && (operand.value >= 0x100 || !operand.absolute)) return named;
+  return operand.absolute ? hex4(operand.value) : hex2(operand.value);
+}
+
+/** The memory operand of `instruction` when it is one of the opcodes of the mnemonic. */
+function memory(instruction: Instruction | undefined, mnemonic: keyof typeof MEMORY): Operand | undefined {
+  if (instruction === undefined) return undefined;
+  const index = (MEMORY[mnemonic] as readonly number[]).indexOf(instruction.opcode);
+  return index < 0 ? undefined : { value: instruction.value, absolute: index === 1 };
+}
+
+const same = (a: Operand | undefined, b: Operand | undefined, offset = 0): boolean => a !== undefined && b !== undefined && a.absolute === b.absolute && b.value === a.value + offset;
+const immediate = (instruction: Instruction | undefined, opcode: number) => (instruction?.opcode === opcode ? instruction.value : undefined);
+/** A branch past the next instruction only: its distance is the length of that instruction. */
+const skips = (branch: Instruction | undefined, opcode: number, next: Instruction | undefined) => branch?.opcode === opcode && next !== undefined && branch.value === next.length;
+
+/** Each idiom: how many instructions it takes, and its args when the instructions match. */
+const MATCHERS: Record<string, { count: number; match: (run: Instruction[], name: Namer) => string[] | undefined }> = {
+  inc16: {
+    count: 3,
+    match: ([low, branch, high], name) => {
+      const dst = memory(low, "inc");
+      return same(dst, memory(high, "inc"), 1) && skips(branch, BNE, high) ? [addressArg(dst!, name)] : undefined;
+    },
+  },
+  dec16: {
+    count: 4,
+    match: ([load, branch, high, low], name) => {
+      const dst = memory(load, "lda");
+      return same(dst, memory(low, "dec")) && same(dst, memory(high, "dec"), 1) && skips(branch, BNE, high) ? [addressArg(dst!, name)] : undefined;
+    },
+  },
+  add16_8: {
+    count: 6,
+    match: ([clc, load, add, store, branch, high], name) => {
+      const dst = memory(load, "lda");
+      const value = immediate(add, IMMEDIATE.adc);
+      const ok = clc?.opcode === CLC && value !== undefined && same(dst, memory(store, "sta")) && same(dst, memory(high, "inc"), 1) && skips(branch, BCC, high);
+      return ok ? [addressArg(dst!, name), hex2(value)] : undefined;
+    },
+  },
+  add16: { count: 7, match: (run, name) => wide(run, name, CLC, IMMEDIATE.adc) },
+  sub16: { count: 7, match: (run, name) => wide(run, name, SEC, IMMEDIATE.sbc) },
+  set16: {
+    count: 4,
+    match: ([loadLow, storeLow, loadHigh, storeHigh], name) => {
+      const low = immediate(loadLow, IMMEDIATE.lda);
+      const high = immediate(loadHigh, IMMEDIATE.lda);
+      const dst = memory(storeLow, "sta");
+      if (low === undefined || high === undefined || !same(dst, memory(storeHigh, "sta"), 1)) return undefined;
+      const value = low | (high << 8);
+      return [addressArg(dst!, name), name(value) ?? hex4(value)];
+    },
+  },
+  mov16: {
+    count: 4,
+    match: ([loadLow, storeLow, loadHigh, storeHigh], name) => {
+      const src = memory(loadLow, "lda");
+      const dst = memory(storeLow, "sta");
+      if (!same(src, memory(loadHigh, "lda"), 1) || !same(dst, memory(storeHigh, "sta"), 1)) return undefined;
+      return [addressArg(dst!, name), addressArg(src!, name)];
+    },
+  },
+  wait_line: {
+    count: 3,
+    match: ([load, compare, branch]) => {
+      const line = immediate(load, IMMEDIATE.lda);
+      // BNE back to the CMP: 5 bytes back from the end of the BNE.
+      return line !== undefined && compare?.opcode === CMP_ABSOLUTE && compare.value === 0xd012 && branch?.opcode === BNE && branch.value === 0xfb ? [hex2(line)] : undefined;
+    },
+  },
+};
+
+/** add16 and sub16: the carry, then the low and the high byte, each with an immediate of the 16-bit value. */
+function wide([carry, loadLow, low, storeLow, loadHigh, high, storeHigh]: Instruction[], name: Namer, carryOpcode: number, opcode: number): string[] | undefined {
+  const dst = memory(loadLow, "lda");
+  const lowValue = immediate(low, opcode);
+  const highValue = immediate(high, opcode);
+  const ok =
+    carry?.opcode === carryOpcode && lowValue !== undefined && highValue !== undefined && same(dst, memory(storeLow, "sta")) && same(dst, memory(loadHigh, "lda"), 1) && same(dst, memory(storeHigh, "sta"), 1);
+  return ok ? [addressArg(dst!, name), hex4(lowValue | (highValue << 8))] : undefined;
+}
+
+/** The instruction at `at`, or undefined when a byte of it is outside the range or the image. */
+function instructionAt(byteAt: ImageByte, at: number, end: number): Instruction | undefined {
+  const opcode = byteAt(at);
+  if (opcode === undefined) return undefined;
+  const length = instructionLength(opcode);
+  if (at + length - 1 > end) return undefined;
+  const bytes = Array.from({ length: length - 1 }, (_, offset) => byteAt(at + 1 + offset));
+  if (bytes.some((byte) => byte === undefined)) return undefined;
+  return { opcode, length, value: length === 1 ? 0 : length === 2 ? bytes[0]! : bytes[0]! | (bytes[1]! << 8) };
+}
+
+/**
+ * Finds the macro candidates in code regions. Each region is read as
+ * instructions from its start; at each instruction the idioms of the
+ * catalogue are tried in order, and a match is a candidate. Candidates do not
+ * overlap: the scan goes on after the end of a match.
+ */
+export function findMacroUses(byteAt: ImageByte, regions: ReadonlyArray<{ start: number; end: number }>, name: Namer): MacroCandidate[] {
+  const candidates: MacroCandidate[] = [];
+  for (const region of [...regions].sort((a, b) => a.start - b.start)) {
+    const run: Array<Instruction & { at: number }> = [];
+    for (let at = region.start; at <= region.end; ) {
+      const instruction = instructionAt(byteAt, at, region.end);
+      if (instruction === undefined) break;
+      run.push({ ...instruction, at });
+      at += instruction.length;
+    }
+    for (let index = 0; index < run.length; ) {
+      const found = CATALOGUE.flatMap((idiom) => {
+        const matcher = MATCHERS[idiom.name]!;
+        const part = run.slice(index, index + matcher.count);
+        const args = part.length === matcher.count ? matcher.match(part, name) : undefined;
+        return args === undefined ? [] : [{ idiom, count: matcher.count, args }];
+      })[0];
+      if (found === undefined) {
+        index++;
+        continue;
+      }
+      const last = run[index + found.count - 1]!;
+      candidates.push({ macro: found.idiom.name, start: run[index]!.at, end: last.at + last.length - 1, args: found.args });
+      index += found.count;
+    }
+  }
+  return candidates;
+}

package/src/knowledge/conflicts.ts

@@ -9,15 +9,21 @@ import type { DatabaseSync } from "node:sqlite";
 import type { HistoryEntry } from "./history.ts";
 import {
   COMMENT_COLUMNS,
+  MACRO_COLUMNS,
+  MACRO_USE_COLUMNS,
   MODULE_COLUMNS,
   OPERAND_COLUMNS,
+  PATCH_COLUMNS,
   REFERENCE_COLUMNS,
   REGION_COLUMNS,
   SUPPRESSION_COLUMNS,
   SYMBOL_COLUMNS,
   toComment,
+  toMacro,
+  toMacroUse,
   toModule,
   toOperand,
+  toPatch,
   toReference,
   toRegion,
   toSuppression,
@@ -39,6 +45,9 @@ export const CONFLICT_RULES = {
   "suppression-symbol": "the same symbol suppression two times",
   "suppression-reference": "the same reference suppression two times",
   "suppression-region": "region suppressions that overlap",
+  patch: "patches that overlap",
+  macro: "two macros with one name",
+  "macro-use": "macro uses that overlap",
 } as const;
 export type ConflictRule = keyof typeof CONFLICT_RULES;
 
@@ -86,6 +95,9 @@ const RULES: readonly TableRule[] = [
     where: "entity = 'reference'",
   },
   { rule: "suppression-region", table: "suppressions", entity: "suppression", columns: SUPPRESSION_COLUMNS, map: toSuppression, key: "overlap", where: "entity = 'region'" },
+  { rule: "patch", table: "patches", entity: "patch", columns: PATCH_COLUMNS, map: toPatch, key: "overlap" },
+  { rule: "macro", table: "macros", entity: "macro", columns: MACRO_COLUMNS, map: toMacro, key: ["name"] },
+  { rule: "macro-use", table: "macro_uses", entity: "macro-use", columns: MACRO_USE_COLUMNS, map: toMacroUse, key: "overlap" },
 ];
 
 function conflictRow(rule: TableRule, raw: Raw): ConflictRow {

package/src/knowledge/history.ts

@@ -6,23 +6,32 @@ 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,
@@ -52,7 +61,10 @@ export type HistoryEntry =
   | { 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: "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>;
 
@@ -100,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 [];
@@ -158,6 +184,9 @@ export function revision(db: DatabaseSync | undefined, text: string): RevisionCh
     ["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[] = [];

package/src/knowledge/read.ts

@@ -84,6 +84,47 @@ export interface OperandRow {
   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";
@@ -93,6 +134,9 @@ 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 string };
@@ -160,6 +204,38 @@ export function toOperand(row: Raw): OperandRow {
   return operand;
 }
 
+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";
@@ -271,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;
@@ -283,6 +382,10 @@ 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: string;
@@ -304,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;
 }
 
@@ -384,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)));

package/src/knowledge/schema.ts

@@ -50,8 +50,14 @@ export type SuppressionEntity = (typeof SUPPRESSION_ENTITIES)[number];
 
 /** A module file of the generated source (D48): a plain name that ends in .asm, no directory. */
 export const MODULE_FILE = /^[A-Za-z0-9_][A-Za-z0-9_-]{0,59}\.asm$/;
+/** A switch of the generated source (D72): upper case, so it reads as a build option and not as a label. */
+export const SWITCH_NAME = /^[A-Z][A-Z0-9_]{1,31}$/;
+/** A macro name and a macro parameter (D73). The body names a parameter with a dot in front: .dst. */
+export const MACRO_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,31}$/;
+export const MACRO_PARAM = /^[a-z_][a-z0-9_]{0,31}$/;
+
 /** Files that c64-source writes itself: no module can have these names. */
-export const GENERATED_FILES = ["main.asm", "loader.asm", "constants.asm"] as const;
+export const GENERATED_FILES = ["main.asm", "loader.asm", "constants.asm", "macros.asm"] as const;
 
 /** True for a generated file name in any letter case: the file systems of macOS and Windows ignore case. */
 export function isGeneratedFile(file: string): boolean {
@@ -193,6 +199,43 @@ function createSchema(db: DatabaseSync): void {
       );
       CREATE INDEX operands_current ON operands (space, address) WHERE valid_to_revision IS NULL;
       CREATE INDEX operands_address ON operands (space, address);
+      CREATE TABLE patches (
+        id                  TEXT PRIMARY KEY,
+        space               TEXT NOT NULL DEFAULT 'c64' CHECK (${SPACE_CHECK}),
+        start_address       INTEGER NOT NULL CHECK (start_address BETWEEN 0 AND 65535),
+        end_address         INTEGER NOT NULL CHECK (end_address BETWEEN start_address AND 65535),
+        switch_name         TEXT NOT NULL CHECK (length(switch_name) > 0),
+        code                TEXT NOT NULL,
+        comment             TEXT CHECK (comment IS NULL OR length(comment) > 0),
+        origin              TEXT NOT NULL CHECK (origin IN ('user', 'llm')),
+        valid_from_revision TEXT NOT NULL REFERENCES revisions (id),
+        valid_to_revision   TEXT REFERENCES revisions (id)
+      );
+      CREATE INDEX patches_start ON patches (space, start_address);
+      CREATE TABLE macros (
+        id                  TEXT PRIMARY KEY,
+        space               TEXT NOT NULL DEFAULT 'c64' CHECK (${SPACE_CHECK}),
+        name                TEXT NOT NULL CHECK (length(name) > 0),
+        params              TEXT NOT NULL,
+        body                TEXT NOT NULL CHECK (length(body) > 0),
+        comment             TEXT CHECK (comment IS NULL OR length(comment) > 0),
+        origin              TEXT NOT NULL CHECK (origin IN ('user', 'llm')),
+        valid_from_revision TEXT NOT NULL REFERENCES revisions (id),
+        valid_to_revision   TEXT REFERENCES revisions (id)
+      );
+      CREATE INDEX macros_name ON macros (space, name);
+      CREATE TABLE macro_uses (
+        id                  TEXT PRIMARY KEY,
+        space               TEXT NOT NULL DEFAULT 'c64' CHECK (${SPACE_CHECK}),
+        start_address       INTEGER NOT NULL CHECK (start_address BETWEEN 0 AND 65535),
+        end_address         INTEGER NOT NULL CHECK (end_address BETWEEN start_address AND 65535),
+        macro               TEXT NOT NULL CHECK (length(macro) > 0),
+        args                TEXT NOT NULL,
+        origin              TEXT NOT NULL CHECK (origin IN ('user', 'llm')),
+        valid_from_revision TEXT NOT NULL REFERENCES revisions (id),
+        valid_to_revision   TEXT REFERENCES revisions (id)
+      );
+      CREATE INDEX macro_uses_start ON macro_uses (space, start_address);
       CREATE VIEW current_symbols AS SELECT * FROM symbols WHERE valid_to_revision IS NULL;
       CREATE VIEW current_regions AS SELECT * FROM regions WHERE valid_to_revision IS NULL;
       CREATE VIEW current_comments AS SELECT * FROM comments WHERE valid_to_revision IS NULL;
@@ -200,11 +243,14 @@ function createSchema(db: DatabaseSync): void {
       CREATE VIEW current_suppressions AS SELECT * FROM suppressions WHERE valid_to_revision IS NULL;
       CREATE VIEW current_modules AS SELECT * FROM modules WHERE valid_to_revision IS NULL;
       CREATE VIEW current_operands AS SELECT * FROM operands WHERE valid_to_revision IS NULL;
+      CREATE VIEW current_patches AS SELECT * FROM patches WHERE valid_to_revision IS NULL;
+      CREATE VIEW current_macros AS SELECT * FROM macros WHERE valid_to_revision IS NULL;
+      CREATE VIEW current_macro_uses AS SELECT * FROM macro_uses WHERE valid_to_revision IS NULL;
     `);
 }
 
 /** The version of the index this build makes. An index with another version is emptied and made again. */
-export const INDEX_VERSION = 1;
+export const INDEX_VERSION = 2;
 
 function indexVersion(db: DatabaseSync): number | undefined {
   const hasMeta = db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'meta'").get();