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

package/skills/c64-testing/scripts/{replay.ts → lib/replay.ts}

@@ -1,81 +1,41 @@
-// The c64-testing replay script: replays a recording in the replay core
+// The replay of c64-testing: replays a recording in the replay core
 // (c64run). First on the original program, which must end with the recorded
 // state hash. Then, with --rebuild, on the rebuild: it compares the state at
 // each checkpoint with the original's. --checkpoint and --state choose the
 // comparison, else the record file gave it.
-// Exit status: 0 PASS, 1 FAIL, 3 INCONCLUSIVE, 2 a bad call.
 
 import { createHash } from "node:crypto";
-import { parseArgs } from "node:util";
 
-import { readProjectFile, writeProjectFile } from "#src/host-client/transfer.ts";
+import { readProjectFile, writeReported, type Written } from "#src/host-client/transfer.ts";
 import { C64RunSession } from "#src/native/c64run.ts";
 import { localToolContext } from "#src/native/local.ts";
 import { Workspace } from "#src/native/staging.ts";
-import { resolveProjectPath } from "#src/project.ts";
-import { runScript, UsageError } from "#src/script.ts";
-import { codeLabels, firstDifference, parseStateItem, pinLines, readRecording, replaySide, siteMap, type Comparison, type ReplayResult, type ReplaySubject } from "./lib/recording.ts";
-import { ScenarioError } from "./lib/scenario.ts";
+import { UsageError } from "#src/script.ts";
+import { firstDifference, parseStateItem, pinLines, readRecording, replaySide, siteMap, type Comparison, type ReplayResult, type ReplaySubject } from "./recording.ts";
+import { namesOf } from "./scenario.ts";
 
-const USAGE = `replay.ts <recording folder> [--checkpoint <routine> --state <item> ... [--pin <item> ...]] [--rebuild <prg> [--symbols <file>]] [--out <dir>]
-
-<recording folder> is a folder that record.ts wrote, relative to the project
-folder. --checkpoint is the name or $ address of a routine; each entry is a
-checkpoint. --state is a name or $ address with :size, one for each item.
---pin is random state in RAM in the same form: at each checkpoint the rebuild
-gets the original's values there.
-Without them, the replay uses the comparison of the record file. --symbols
-gives the names of the rebuild: the c64-assembler output (default: the
-symbols of the recording). A recording without names takes the names of the
-knowledge for the original. A $ address is an address of the original: on the
-rebuild it moves with the name before it. With --out, a FAIL writes the RAM
-of both sides at the first different checkpoint into <dir>. The result is one
-JSON object.`;
-
-const EXIT = { PASS: 0, FAIL: 1, INCONCLUSIVE: 3 } as const;
 const MAX_STATE_ITEMS = 16;
 
-async function run(argv: string[]): Promise<ReplayResult> {
-  const { values, positionals } = parseArgs({
-    args: argv,
-    strict: true,
-    allowPositionals: true,
-    options: {
-      checkpoint: { type: "string" },
-      state: { type: "string", multiple: true },
-      pin: { type: "string", multiple: true },
-      rebuild: { type: "string" },
-      symbols: { type: "string" },
-      out: { type: "string" },
-      help: { type: "boolean" },
-    },
-  });
-  if (values.help) throw new UsageError("");
-  if (positionals.length !== 1) throw new UsageError("give one recording folder");
+export interface ReplayOptions {
+  folder: string;
+  checkpoint?: string;
+  state: string[];
+  pin: string[];
+  rebuild?: string;
+  symbols?: string;
+  out?: string;
+}
+
+/** Replays the recording on the original, and with `rebuild` on the rebuild: PASS, FAIL or INCONCLUSIVE. */
+export async function replay(values: ReplayOptions): Promise<ReplayResult> {
   if (values.symbols !== undefined && values.rebuild === undefined) throw new UsageError("--symbols is for the rebuild: give --rebuild too");
-  if ((values.checkpoint === undefined) !== (values.state === undefined)) throw new UsageError("give --checkpoint and --state together");
-  if ((values.state?.length ?? 0) + (values.pin?.length ?? 0) > MAX_STATE_ITEMS) throw new UsageError(`give at most ${MAX_STATE_ITEMS} --state and --pin items`);
-  if (values.pin !== undefined && values.checkpoint === undefined) throw new UsageError("--pin needs --checkpoint and --state");
-  if (values.out !== undefined) {
-    try {
-      resolveProjectPath(values.out);
-    } catch {
-      throw new UsageError(`--out must be a path relative to the project folder that stays inside it, not ${values.out}`);
-    }
-  }
-  const folder = positionals[0]!.replace(/\/+$/, "").replace(/\/recording\.json$/, "");
-  let recording;
-  let given: Comparison | undefined;
-  try {
-    recording = readRecording(folder);
-    given =
-      values.checkpoint === undefined
-        ? undefined
-        : { checkpoint: values.checkpoint, state: values.state!.map(parseStateItem), ...(values.pin === undefined ? {} : { pin: values.pin.map(parseStateItem) }) };
-  } catch (error) {
-    if (error instanceof ScenarioError) throw new UsageError(error.message);
-    throw error;
-  }
+  if ((values.checkpoint === undefined) !== (values.state.length === 0)) throw new UsageError("give --checkpoint and --state together");
+  if (values.state.length + values.pin.length > MAX_STATE_ITEMS) throw new UsageError(`give at most ${MAX_STATE_ITEMS} --state and --pin items`);
+  if (values.pin.length > 0 && values.checkpoint === undefined) throw new UsageError("--pin needs --checkpoint and --state");
+  const folder = values.folder.replace(/\/+$/, "").replace(/\/recording\.json$/, "");
+  const recording = readRecording(folder);
+  const given: Comparison | undefined =
+    values.checkpoint === undefined ? undefined : { checkpoint: values.checkpoint, state: values.state.map(parseStateItem), ...(values.pin.length === 0 ? {} : { pin: values.pin.map(parseStateItem) }) };
   const compare = given ?? recording.compare;
   if (values.rebuild !== undefined && compare === undefined) throw new UsageError("the recording has no checkpoint and state: give --checkpoint and --state");
   const result = (outcome: ReplayResult["result"], side: ReplayResult["side"], fields: Partial<ReplayResult> = {}): ReplayResult => ({
@@ -97,14 +57,7 @@ async function run(argv: string[]): Promise<ReplayResult> {
     // A recording made without names takes the names that the knowledge has now.
     const originalSymbols = recording.symbols === "none" ? "knowledge" : recording.symbols;
     const original: ReplaySubject = { side: "original", program: recording.program, symbols: originalSymbols };
-    const side = async (subject: ReplaySubject, options: Parameters<typeof replaySide>[5]) => {
-      try {
-        return await replaySide(core, recording, folder, subject, workspace, options);
-      } catch (error) {
-        if (error instanceof ScenarioError) throw new UsageError(error.message);
-        throw error;
-      }
-    };
+    const side = (subject: ReplaySubject, options: Parameters<typeof replaySide>[5]) => replaySide(core, recording, folder, subject, workspace, options);
     // The self-check: the original ends the session with the recorded state, to the cycle.
     const self = await side(original, { ...(compare === undefined ? {} : { compare }) });
     if (self.problem !== undefined) return result("INCONCLUSIVE", "original", { reason: `the recording does not reproduce on the original: ${self.problem}` });
@@ -121,7 +74,7 @@ async function run(argv: string[]): Promise<ReplayResult> {
     const rebuild: ReplaySubject = { side: "rebuild", program: values.rebuild, symbols: values.symbols ?? originalSymbols };
     let movedSites: number;
     try {
-      movedSites = siteMap(recording.sites, codeLabels(originalSymbols), codeLabels(rebuild.symbols)).length;
+      movedSites = siteMap(recording.sites, namesOf(originalSymbols, "code"), namesOf(rebuild.symbols, "code")).length;
     } catch (error) {
       throw new UsageError(`--symbols ${rebuild.symbols}: ${(error as Error).message}`);
     }
@@ -137,12 +90,10 @@ async function run(argv: string[]): Promise<ReplayResult> {
         : `the rebuild came to ${replayed.samples.length} of ${expected.length} checkpoints${replayed.problem === undefined ? "" : `: ${replayed.problem}`}`;
     const failed = result("FAIL", "rebuild", { ...base, compared: (difference?.checkpoint ?? replayed.samples.length + 1) - 1, reason, ...(difference === undefined ? {} : { firstDifference: difference }) });
     if (values.out !== undefined && difference !== undefined) {
-      const files: string[] = [];
+      const files: Written[] = [];
       for (const subject of [original, rebuild]) {
         const dumped = await side(subject, { compare: compare!, dump: difference.checkpoint, ...(subject.side === "rebuild" ? { pins } : {}) });
-        const name = `${subject.side}-${difference.checkpoint}.bin`;
-        writeProjectFile(`${values.out}/${name}`, dumped.ram!, { what: "--out" });
-        files.push(name);
+        files.push(writeReported(`${values.out}/${subject.side}-${difference.checkpoint}.bin`, dumped.ram!, { what: "--out" }));
       }
       failed.files = files;
     }
@@ -152,12 +103,3 @@ async function run(argv: string[]): Promise<ReplayResult> {
     workspace.remove();
   }
 }
-
-await runScript(
-  async (argv) => {
-    const result = await run(argv);
-    process.exitCode = EXIT[result.result];
-    return result;
-  },
-  { usage: USAGE },
-);

package/skills/c64-testing/scripts/{run.ts → lib/runs.ts}

@@ -1,28 +1,17 @@
-// The c64-testing run script: runs steps in its own emulator, from a
-// program or a snapshot file, and writes what the steps ask for into a
-// directory: screens, coverage maps, snapshot files, and results.json with
-// the observations. One side, no comparison. Exit status: 0 when every step
-// ran, 1 when a step did not, 2 for a bad call.
-
-import { parseArgs } from "node:util";
+// The runs of c64-testing: steps in their own emulator, from a program or a
+// snapshot file, and what the steps ask for written into a folder: screens,
+// coverage maps, snapshot files, and results.json with the observations. One
+// side, no comparison.
 
 import { formatC64Address, formatSprite, formatVicii, parseC64Address } from "#src/c64.ts";
 import { runProgram } from "#src/host-client/autostart.ts";
 import { readCoverage } from "#src/host-client/coverage.ts";
-import { ACTION_STEP_KEYS, ACTION_STEP_KINDS, checkActionStep, isInteger, isObject, runActionStep, type ActionStep } from "#src/host-client/steps.ts";
+import { ACTION_STEP_KINDS, checkActionStep, isInteger, isObject, runActionStep, type ActionStep, type ActionStepKind } from "#src/host-client/steps.ts";
 import { MAX_MEMORY_READ, MAX_TRACE_FRAMES, MAX_TRACE_HITS, MAX_TRACE_POINTS, TRACE_KINDS, WireFailure, type TraceHit, type TraceKind } from "#src/host-client/tools.ts";
-import { readProjectFile, writeProjectFile } from "#src/host-client/transfer.ts";
+import { readProjectFile, writeReported, type Written } from "#src/host-client/transfer.ts";
 import { readMemoryInParts, ViceSessionClient } from "#src/host-client/vice-session.ts";
-import { resolveProjectPath } from "#src/project.ts";
-import { runScript, UsageError } from "#src/script.ts";
-import { loadSymbols } from "./lib/scenario.ts";
-
-const USAGE = `run.ts <run.json> --out <dir>
-
-<run.json> is a run file relative to the project folder: where to start,
-optional symbols, and the steps. See references/scenario-format.md, section
-Runs. The files that the steps write, and results.json, go into <dir>. The
-result is one JSON object.`;
+import { UsageError } from "#src/script.ts";
+import { namesOf } from "./scenario.ts";
 
 type RunStep =
   | ActionStep
@@ -30,8 +19,8 @@ type RunStep =
   | { save: string }
   | { screen: string }
   | { coverage: string }
-  | { trace: string; points: Array<{ kind: TraceKind; at: string; end?: string }>; frames: number; maxHits?: number }
-  | { observe: string; memory?: "all" | Array<string | { at: string; size?: number; view?: "cpu" | "ram" }>; registers?: boolean; vicii?: boolean; sprites?: number[] };
+  | { trace: string; points: Array<{ kind: TraceKind; start: string; end?: string }>; frames: number; maxHits?: number }
+  | { observe: string; memory?: "all" | Array<string | { address: string; size?: number; view?: "cpu" | "ram" }>; registers?: boolean; vicii?: boolean; sprites?: number[] };
 
 interface Run {
   name: string;
@@ -73,9 +62,13 @@ function readRun(path: string): Run {
     const kinds = "observe" in step ? ["observe"] : "trace" in step ? ["trace"] : Object.keys(step).filter((key) => (ACTION_STEP_KINDS as readonly string[]).includes(key) || (OWN_KINDS as readonly string[]).includes(key));
     if (kinds.length !== 1) return fail(`${at} must have exactly one of ${[...ACTION_STEP_KINDS, ...OWN_KINDS].join(", ")}`);
     const kind = kinds[0]!;
-    const allowed = kind === "observe" ? OBSERVE_KEYS : kind === "trace" ? TRACE_KEYS : (ACTION_STEP_KEYS[kind] ?? [kind]);
+    const allowed = kind === "observe" ? OBSERVE_KEYS : kind === "trace" ? TRACE_KEYS : [kind];
     for (const key of Object.keys(step)) if (!allowed.includes(key)) fail(`${at} has the key ${key}, which a ${kind} step does not have`);
-    if ((ACTION_STEP_KINDS as readonly string[]).includes(kind)) return checkActionStep(kind, step, at, fail);
+    if ((ACTION_STEP_KINDS as readonly string[]).includes(kind)) {
+      // The step with its defaults filled in, as the shared schema of the action steps gives it.
+      (value.steps as unknown[])[index] = checkActionStep(kind as ActionStepKind, step, at, fail);
+      return;
+    }
     const name = step[kind];
     if (kind === "snapshot") {
       if (typeof name !== "string" || name === "") fail(`${at}: snapshot needs a project file`);
@@ -86,11 +79,11 @@ function readRun(path: string): Run {
       if (labels.has(name as string)) fail(`${at} needs a new name`);
       labels.add(name as string);
       const points = step.points;
-      if (!Array.isArray(points) || points.length === 0 || points.length > MAX_TRACE_POINTS) return fail(`${at}: points is a list of 1 to ${MAX_TRACE_POINTS} objects with kind and at`);
+      if (!Array.isArray(points) || points.length === 0 || points.length > MAX_TRACE_POINTS) return fail(`${at}: points is a list of 1 to ${MAX_TRACE_POINTS} objects with kind and start`);
       for (const point of points as unknown[]) {
-        if (!isObject(point) || Object.keys(point).some((key) => !["kind", "at", "end"].includes(key))) return fail(`${at}: a point has kind, at and end, and nothing else`);
+        if (!isObject(point) || Object.keys(point).some((key) => !["kind", "start", "end"].includes(key))) return fail(`${at}: a point has kind, start and end, and nothing else`);
         if (!(TRACE_KINDS as readonly unknown[]).includes(point.kind)) fail(`${at}: a point kind is exec, read or write`);
-        if (typeof point.at !== "string" || (point.end !== undefined && typeof point.end !== "string")) fail(`${at}: a point needs at, and end when it is a range, as names or $ addresses`);
+        if (typeof point.start !== "string" || (point.end !== undefined && typeof point.end !== "string")) fail(`${at}: a point needs start, and end when it is a range, as names or $ addresses`);
       }
       if (!isInteger(step.frames, 1, MAX_TRACE_FRAMES)) fail(`${at}: frames must be a number from 1 to ${MAX_TRACE_FRAMES}`);
       if (step.maxHits !== undefined && !isInteger(step.maxHits, 1, MAX_TRACE_HITS)) fail(`${at}: maxHits must be a number from 1 to ${MAX_TRACE_HITS}`);
@@ -102,12 +95,12 @@ function readRun(path: string): Run {
     const memoryItem = (item: unknown) =>
       typeof item === "string" ||
       (isObject(item) &&
-        typeof item.at === "string" &&
-        Object.keys(item).every((key) => ["at", "size", "view"].includes(key)) &&
+        typeof item.address === "string" &&
+        Object.keys(item).every((key) => ["address", "size", "view"].includes(key)) &&
         (item.size === undefined || isInteger(item.size, 1, 0x10000)) &&
         (item.view === undefined || item.view === "cpu" || item.view === "ram"));
     if (step.memory !== undefined && step.memory !== "all" && (!Array.isArray(step.memory) || !step.memory.every(memoryItem))) {
-      fail(`${at}: memory is "all", or a list of names, $ addresses, or objects with at, size (1 to 65536) and view (cpu or ram)`);
+      fail(`${at}: memory is "all", or a list of names, $ addresses, or objects with address, size (1 to 65536) and view (cpu or ram)`);
     }
     if (step.registers !== undefined && typeof step.registers !== "boolean") fail(`${at}: registers must be true or false`);
     if (step.vicii !== undefined && typeof step.vicii !== "boolean") fail(`${at}: vicii must be true or false`);
@@ -121,9 +114,10 @@ function showHit(hit: TraceHit) {
   return { ...hit, pc: formatC64Address(hit.pc), ...(hit.address === undefined ? {} : { address: formatC64Address(hit.address) }) };
 }
 
-async function runFile(path: string, out: string): Promise<{ output: Record<string, unknown>; failed: boolean }> {
+/** Runs the run file and writes its files into `out`. failed: a step did not run. */
+export async function runFile(path: string, out: string): Promise<{ output: Record<string, unknown>; failed: boolean }> {
   const run = readRun(path);
-  const symbols = loadSymbols({ program: "", symbols: run.symbols ?? "none" });
+  const symbols = namesOf(run.symbols ?? "none");
   const at = (location: string): number => {
     if (location.startsWith("$")) return parseC64Address(location);
     const address = symbols.get(location);
@@ -131,8 +125,9 @@ async function runFile(path: string, out: string): Promise<{ output: Record<stri
     return address;
   };
   const files: string[] = [];
+  const written: Written[] = [];
   const write = (name: string, bytes: Uint8Array) => {
-    writeProjectFile(`${out}/${name}`, bytes, { what: "--out" });
+    written.push(writeReported(`${out}/${name}`, bytes, { what: "--out" }));
     files.push(name);
   };
   const observations: Record<string, unknown> = {};
@@ -158,7 +153,7 @@ async function runFile(path: string, out: string): Promise<{ output: Record<stri
       } else if ("save" in step) {
         await client.snapshot({ action: "save", name: "run-save" });
         write(`${step.save}.vsf`, await client.snapshotExport("run-save"));
-        await client.snapshot({ action: "discard", name: "run-save" });
+        await client.snapshot({ action: "remove", name: "run-save" });
       } else if ("screen" in step) {
         write(`${step.screen}.png`, Buffer.from((await client.screenCapture()).png, "base64"));
       } else if ("coverage" in step) {
@@ -166,7 +161,7 @@ async function runFile(path: string, out: string): Promise<{ output: Record<stri
         await client.memmap({ action: "clear" });
       } else if ("trace" in step) {
         // A trace: every hit of the points while the program runs on, to <name>.json.
-        const points = step.points.map((point) => ({ kind: point.kind, start: at(point.at), end: at(point.end ?? point.at) }));
+        const points = step.points.map((point) => ({ kind: point.kind, start: at(point.start), end: at(point.end ?? point.start) }));
         if (points.some((point) => point.end < point.start)) throw new UsageError(`the trace ${step.trace} has a point whose end is before its start`);
         const traced = await client.trace({ points, frames: step.frames, maxHits: step.maxHits ?? MAX_TRACE_HITS });
         write(`${step.trace}.json`, Buffer.from(`${JSON.stringify({ points: step.points, frames: traced.frames, end: traced.end, hits: traced.hits.map(showHit) }, null, 1)}\n`));
@@ -184,15 +179,15 @@ async function runFile(path: string, out: string): Promise<{ output: Record<stri
         } else if (step.memory !== undefined) {
           const memory: Record<string, string | { file: string }> = {};
           for (const item of step.memory) {
-            const spec = typeof item === "string" ? { at: item } : item;
+            const spec = typeof item === "string" ? { address: item } : item;
             const size = spec.size ?? 1;
-            const bytes = await readMemoryInParts(client, at(spec.at), size, spec.view ?? "cpu");
+            const bytes = await readMemoryInParts(client, at(spec.address), size, spec.view ?? "cpu");
             // More than one read gives goes to a file: results.json stays small.
-            if (size <= MAX_MEMORY_READ) memory[spec.at] = bytes.toString("hex");
+            if (size <= MAX_MEMORY_READ) memory[spec.address] = bytes.toString("hex");
             else {
-              const file = `${step.observe}-${spec.at.replace(/^\$/, "")}.bin`;
+              const file = `${step.observe}-${spec.address.replace(/^\$/, "")}.bin`;
               write(file, bytes);
-              memory[spec.at] = { file };
+              memory[spec.address] = { file };
             }
           }
           seen.memory = memory;
@@ -207,7 +202,7 @@ async function runFile(path: string, out: string): Promise<{ output: Record<stri
       } else {
         const notReached = await runActionStep(client, step, at);
         if (notReached !== undefined && "runUntil" in step) {
-          reason = `Step ${done + 1} did not reach its target in ${step.timeoutFrames} frames. It stopped by ${notReached.stopReason} at ${formatC64Address(notReached.pc)}.`;
+          reason = `Step ${done + 1} did not reach its target in ${step.runUntil.timeoutFrames} frames. It stopped by ${notReached.stopReason} at ${formatC64Address(notReached.pc)}.`;
           break;
         }
       }
@@ -216,26 +211,8 @@ async function runFile(path: string, out: string): Promise<{ output: Record<stri
     const pc = (await client.registersGet("c64")).pc;
     const results = { name: run.name, completed: reason === undefined, steps: run.steps.length, done, ...(reason === undefined ? {} : { reason }), pc: formatC64Address(pc), files: [...files], observations, ...(Object.keys(traces).length === 0 ? {} : { traces }) };
     write("results.json", Buffer.from(`${JSON.stringify(results, null, 2)}\n`));
-    return { output: { ...results, files, observations: Object.keys(observations), out }, failed: reason !== undefined };
+    return { output: { ...results, files: written, observations: Object.keys(observations), out }, failed: reason !== undefined };
   } finally {
     await client.close();
   }
 }
-
-await runScript(
-  async (argv) => {
-    const { values, positionals } = parseArgs({ args: argv, strict: true, allowPositionals: true, options: { out: { type: "string" }, help: { type: "boolean" } } });
-    if (values.help) throw new UsageError("");
-    if (positionals.length !== 1) throw new UsageError("give one run file");
-    if (values.out === undefined) throw new UsageError("run needs --out <dir>");
-    try {
-      resolveProjectPath(values.out);
-    } catch {
-      throw new UsageError(`--out must be a path relative to the project folder that stays inside it, not ${values.out}`);
-    }
-    const { output, failed } = await runFile(positionals[0]!, values.out);
-    if (failed) process.exitCode = 1;
-    return output;
-  },
-  { usage: USAGE },
-);