@henols/c64-re-tools 2.1.0-rc.1 → 2.1.0

package/skills/c64-provenance/scripts/lib/library.ts

@@ -7,10 +7,11 @@
 import { mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 
+import { Refusal } from "#src/errors.ts";
 import { formatC64Address, instructionLength } from "#src/c64.ts";
-import { evaluate, ExpressionError, identifiers, operandText } from "#src/knowledge/expression.ts";
+import { evaluate, identifiers, operandText } from "#src/knowledge/expression.ts";
 import type { CommentRow, OperandRow, ReferenceRow, RegionRow, SymbolRow } from "#src/knowledge/read.ts";
-import { COMMENT_PLACEMENTS, OPERAND_SELECTS, REFERENCE_KINDS, REGION_TYPES, SYMBOL_KINDS, type CommentPlacement, type OperandSelect, type ReferenceKind, type RegionType, type SymbolKind } from "#src/knowledge/schema.ts";
+import { COMMENT_PLACEMENTS, type CommentPlacement, isSemantic, OPERAND_SELECTS, type OperandSelect, REFERENCE_KINDS, type ReferenceKind, REGION_TYPES, type RegionType, SYMBOL_KINDS, type SymbolKind } from "#src/knowledge/schema.ts";
 import { PROJECT_DIRECTORY } from "#src/project.ts";
 
 /** A routine shorter than this is not saved and not searched: its bytes occur by chance. */
@@ -22,17 +23,6 @@ const ROUTINE_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
 /** Bytes on each line of a routine file, so that git shows a small diff. */
 const BYTES_PER_LINE = 16;
 
-/** A refusal of the library rules, with a stable code. */
-export class LibraryError extends Error {
-  override name = "LibraryError";
-  readonly code: "invalid-input" | "not-found" | "conflict";
-
-  constructor(code: "invalid-input" | "not-found" | "conflict", message: string) {
-    super(message);
-    this.code = code;
-  }
-}
-
 /**
  * Bytes that move with the routine: a word, or the low or high byte, of the
  * address at `value` (an offset from the routine start; -1 for the RTS entry
@@ -110,9 +100,9 @@ export interface LeftOut {
 export function routineFrom(source: RoutineSource): { routine: Routine; leftOut: LeftOut[] } {
   const { start, end } = source;
   const where = (address: number) => formatC64Address(address);
-  if (!ROUTINE_NAME.test(source.name)) throw new LibraryError("invalid-input", `A routine name is a letter or underscore, then letters, digits or underscores (at most 64), not ${source.name}.`);
+  if (!ROUTINE_NAME.test(source.name)) throw new Refusal("invalid-input", `A routine name is a letter or underscore, then letters, digits or underscores (at most 64), not ${source.name}.`);
   const length = end - start + 1;
-  if (length < MIN_ROUTINE) throw new LibraryError("invalid-input", `${where(start)}-${where(end)} has ${length} bytes. A routine has at least ${MIN_ROUTINE}, because shorter byte sequences occur by chance.`);
+  if (length < MIN_ROUTINE) throw new Refusal("invalid-input", `${where(start)}-${where(end)} has ${length} bytes. A routine has at least ${MIN_ROUTINE}, because shorter byte sequences occur by chance.`);
   const inside = (address: number) => address >= start && address <= end;
   const bytes = Uint8Array.from({ length }, (_, index) => source.byteAt(start + index));
   const leftOut: LeftOut[] = [];
@@ -125,11 +115,11 @@ export function routineFrom(source: RoutineSource): { routine: Routine; leftOut:
   for (const region of codeRegions) {
     for (let at = Math.max(region.start, next); at <= Math.min(region.end, end); at = next) {
       next = at + instructionLength(bytes[at - start]!);
-      if (next - 1 > end) throw new LibraryError("invalid-input", `The instruction at ${where(at)} runs past the end ${where(end)} of the routine. Give an end after it.`);
+      if (next - 1 > end) throw new Refusal("invalid-input", `The instruction at ${where(at)} runs past the end ${where(end)} of the routine. Give an end after it.`);
       instructions.push(at - start);
     }
   }
-  if (instructions.length === 0) throw new LibraryError("invalid-input", `The knowledge has no code region in ${where(start)}-${where(end)}. Run c64-static-analysis first, or classify the code.`);
+  if (instructions.length === 0) throw new Refusal("invalid-input", `The knowledge has no code region in ${where(start)}-${where(end)}. Run c64-static-analysis first, or classify the code.`);
 
   // The operands: an address inside the routine moves with it; one outside may differ.
   const relocations = new Map<number, Relocation>();
@@ -246,7 +236,7 @@ export function routineText(routine: Routine): string {
 /** Reads the text of a routine file. Throws LibraryError for a file that is no routine. */
 export function parseRoutine(text: string, file: string): Routine {
   const fail = (what: string): never => {
-    throw new LibraryError("invalid-input", `${file} is not a routine file of the library: ${what}.`);
+    throw new Refusal("invalid-input", `${file} is not a routine file of the library: ${what}.`);
   };
   let value: Record<string, unknown>;
   try {
@@ -305,15 +295,15 @@ export function parseRoutine(text: string, file: string): Routine {
  * `create`, a missing folder is made.
  */
 export function libraryFolder(folder: string, options: { create: boolean; cwd?: string }): string {
-  if (folder.length === 0) throw new LibraryError("invalid-input", "The library folder must not be empty.");
+  if (folder.length === 0) throw new Refusal("invalid-input", "The library folder must not be empty.");
   const path = resolve(options.cwd ?? process.cwd(), folder);
   const stat = statSync(path, { throwIfNoEntry: false });
   if (stat === undefined) {
-    if (!options.create) throw new LibraryError("not-found", `There is no library folder ${folder}. Save a routine to it first with routine.`);
+    if (!options.create) throw new Refusal("not-found", `There is no library folder ${folder}. Save a routine to it first with routine.`);
     mkdirSync(path, { recursive: true });
-  } else if (!stat.isDirectory()) throw new LibraryError("invalid-input", `${folder} is not a folder.`);
+  } else if (!stat.isDirectory()) throw new Refusal("invalid-input", `${folder} is not a folder.`);
   if (statSync(join(path, PROJECT_DIRECTORY), { throwIfNoEntry: false }) !== undefined) {
-    throw new LibraryError("invalid-input", `${folder} is a project folder. A library is a plain folder beside the projects, for example library/ at the workspace root.`);
+    throw new Refusal("invalid-input", `${folder} is a project folder. A library is a plain folder beside the projects, for example library/ at the workspace root.`);
   }
   return path;
 }
@@ -331,7 +321,7 @@ export function readLibrary(folder: string): Routine[] {
 export function saveRoutine(folder: string, routine: Routine, replace: boolean): string {
   const file = join(folder, `${routine.name}.json`);
   if (!replace && statSync(file, { throwIfNoEntry: false }) !== undefined) {
-    throw new LibraryError("conflict", `The library already has the routine ${routine.name}. Give another --name, or give --replace to save over it.`);
+    throw new Refusal("conflict", `The library already has the routine ${routine.name}. Give another --name, or give --replace to save over it.`);
   }
   const temporary = `${file}.${process.pid}.tmp`;
   writeFileSync(temporary, routineText(routine));
@@ -449,7 +439,7 @@ export interface Suggestions {
   leftOut: Skipped[];
 }
 
-const semantic = (row: { origin: string }) => row.origin === "user" || row.origin === "llm";
+const semantic = (row: { origin: string }) => isSemantic(row.origin);
 
 /**
  * The names, regions, comments, references and operand expressions of each
@@ -573,7 +563,7 @@ function operandProblem(address: number, text: string, image: Searched, resolveN
   try {
     value = evaluate(text, resolveName);
   } catch (error) {
-    if (error instanceof ExpressionError) return error.message;
+    if (error instanceof Refusal) return error.message;
     throw error;
   }
   const range = size === 2 ? 0x100 : 0x10000;

package/skills/c64-provenance/scripts/lib/runtime.ts

@@ -4,14 +4,15 @@
 // Watchpoints and range breakpoints stop the run at an access; the coverage
 // map then tells which range and which access it was.
 
-import { COVERAGE, formatC64Address, instructionLength } from "#src/c64.ts";
+import { type AddressRange, COVERAGE, formatC64Address, instructionLength } from "#src/c64.ts";
 import { runProgram } from "#src/host-client/autostart.ts";
 import { readCoverage } from "#src/host-client/coverage.ts";
+import { startAtEntry, type EntryState } from "#src/host-client/entry-state.ts";
 import { runActionStep, type ActionStep } from "#src/host-client/steps.ts";
-import { MAX_MEMORY_READ, MAX_MEMORY_WRITE } from "#src/host-client/tools.ts";
+import { knowledgeAt } from "#src/knowledge/names.ts";
+import { MAX_MEMORY_READ } from "#src/host-client/tools.ts";
 import { readProjectFile } from "#src/host-client/transfer.ts";
 import type { ViceSessionClient } from "#src/host-client/vice-session.ts";
-import type { Range } from "./compare.ts";
 
 export type FirstAccess = "read" | "write" | "execute" | "none";
 
@@ -21,26 +22,12 @@ export interface RangeAccess {
   changed: boolean;
 }
 
-/** How a release starts in the emulator. */
+/** How a release starts in the emulator: autostart of a PRG, or the captured program at its entry. */
 export type Start =
   | { kind: "program"; path: string }
-  | { kind: "image"; segments: Range[]; byteAt: (address: number) => number; state: ImageState };
-
-export interface ImageState {
-  pc: number;
-  a: number;
-  x: number;
-  y: number;
-  sp: number;
-  flags: { n: boolean; v: boolean; d: boolean; i: boolean; z: boolean; c: boolean };
-  port: [number, number];
-  /** $0000-$03ff at the entry. */
-  pages: Uint8Array;
-}
+  | { kind: "image"; segments: AddressRange[]; byteAt: (address: number) => number; state: EntryState };
 
 const MAX_WATCH = 256;
-/** Frames until the KERNAL is at the READY prompt, before an image is written. */
-const READY_FRAMES = 150;
 
 const READ = COVERAGE.ramRead | COVERAGE.romRead | COVERAGE.ioRead;
 const WRITE = COVERAGE.ramWrite | COVERAGE.ioWrite;
@@ -62,20 +49,7 @@ async function start(client: ViceSessionClient, how: Start): Promise<string | un
     if (failed === "not-started") return "The program did not start after RUN; it needs a BASIC start line.";
     return undefined;
   }
-  await client.reset({ mode: "hard", run: true });
-  await client.execution({ action: "advance-frames", count: READY_FRAMES, space: "c64" });
-  for (const segment of how.segments) {
-    for (let at = segment.start; at <= segment.end; at += MAX_MEMORY_WRITE) {
-      const last = Math.min(segment.end, at + MAX_MEMORY_WRITE - 1);
-      const bytes = Buffer.from(Array.from({ length: last - at + 1 }, (_, offset) => how.byteAt(at + offset)));
-      await client.memoryWrite({ address: at, data: bytes.toString("hex"), space: "c64", view: "ram" });
-    }
-  }
-  const { state } = how;
-  // Pages 0 to 3 from $0002, then the CPU port: the port bits switch what the CPU sees.
-  await client.memoryWrite({ address: 0x0002, data: Buffer.from(state.pages.subarray(2)).toString("hex"), space: "c64", view: "ram" });
-  await client.memoryWrite({ address: 0x0000, data: Buffer.from(state.port).toString("hex"), space: "c64", view: "cpu" });
-  await client.registersSet("c64", { pc: state.pc, a: state.a, x: state.x, y: state.y, sp: state.sp, flags: state.flags });
+  await startAtEntry(client, how, how.state);
   return undefined;
 }
 
@@ -86,7 +60,7 @@ async function start(client: ViceSessionClient, how: Start): Promise<string | un
 export async function watchRelease(
   client: ViceSessionClient,
   how: Start,
-  ranges: Range[],
+  ranges: AddressRange[],
   release: (address: number) => number,
   run: { frames: number; steps: ActionStep[] },
 ): Promise<{ started: true; accesses: RangeAccess[] } | { started: false; reason: string }> {
@@ -151,6 +125,7 @@ export async function watchRelease(
       if (left > 0 && !(await settle())) left--;
     }
   };
+  const at = knowledgeAt();
   for (const step of run.steps) {
     if ("frames" in step) {
       await runFrames(step.frames);
@@ -159,13 +134,13 @@ export async function watchRelease(
     if ("runUntil" in step) {
       // A stop at a point is not the target: settle and run to the target again.
       while (guard-- > 0) {
-        const reached = await runActionStep(client, step, (location) => Number.parseInt(location.slice(1), 16));
+        const reached = await runActionStep(client, step, at);
         if (reached === undefined || reached.stopReason !== "watchpoint" && reached.stopReason !== "breakpoint") break;
         await settle();
       }
       continue;
     }
-    await runActionStep(client, step, (location) => Number.parseInt(location.slice(1), 16));
+    await runActionStep(client, step, at);
   }
   await runFrames(run.frames);
   if (points.size > 0) await settle();
@@ -188,4 +163,4 @@ export async function watchRelease(
   return { started: true, accesses };
 }
 
-export const showRange = (range: Range) => `${formatC64Address(range.start)}-${formatC64Address(range.end)}`;
+export const showRange = (range: AddressRange) => `${formatC64Address(range.start)}-${formatC64Address(range.end)}`;

package/skills/c64-provenance/scripts/lib/separate.ts

@@ -4,31 +4,30 @@
 // entry; and what the program reads or executes outside the image. Evidence
 // only: nothing here decides what is original.
 
-import { COVERAGE, executedRamCode } from "#src/c64.ts";
-import type { Range } from "./compare.ts";
+import { type AddressRange, COVERAGE, executedRamCode } from "#src/c64.ts";
 
 export type Access = "executed" | "read" | "written" | "read-written" | "untouched";
 
 export interface SeparationInput {
-  segments: Range[];
+  segments: AddressRange[];
   /** 64 KiB with the image bytes at their addresses. */
   memory: Uint8Array;
   entry?: number;
   /** The stages of an unpacker capture, in order; the last one is the program. */
-  stages?: Array<{ entry: number; wrote: Range[] }>;
+  stages?: Array<{ entry: number; wrote: AddressRange[] }>;
   /** Joined coverage files. */
   coverage?: Uint8Array;
-  codeRegions: Array<Range & { type: string }>;
+  codeRegions: Array<AddressRange & { type: string }>;
   references: Array<{ from: number; to: number; kind: string }>;
 }
 
-export interface EvidenceRange extends Range {
+export interface EvidenceRange extends AddressRange {
   /** The last stage that wrote the range; absent when no stage wrote it. */
   stage?: number;
   access?: Access;
 }
 
-export interface CodeRegionEvidence extends Range {
+export interface CodeRegionEvidence extends AddressRange {
   type: string;
   /** Absent when the image has no entry. */
   reachable?: boolean;
@@ -45,14 +44,14 @@ export interface Separation {
    * those bytes there), and `generated` it wrote and then executed, in
    * pieces of code with gaps of up to two operand bytes.
    */
-  outside: { read: Range[]; executed: Range[]; generated: Range[] };
+  outside: { read: AddressRange[]; executed: AddressRange[]; generated: AddressRange[] };
 }
 
 const SYSTEM_PAGES_END = 0x03ff;
 
 /** Joins addresses in order into ranges; `gap` is the most bytes between two addresses in one range. */
-function merge(addresses: number[], gap = 0, joins: (from: number, to: number) => boolean = () => true): Range[] {
-  const ranges: Range[] = [];
+function merge(addresses: number[], gap = 0, joins: (from: number, to: number) => boolean = () => true): AddressRange[] {
+  const ranges: AddressRange[] = [];
   for (const address of addresses) {
     const last = ranges.at(-1);
     if (last !== undefined && address - last.end - 1 <= gap && joins(last.end, address)) last.end = address;