@henols/c64-re-tools 2.1.0 → 2.1.2

package/src/opcodes.ts

@@ -4,7 +4,7 @@
 // spelling, ACME writes only one of them: the generator finds those with a
 // probe and writes the others as bytes.
 
-import { formatC64Byte, formatC64Address } from "./c64.ts";
+import { formatC64Byte, formatC64Address, SYMBOL_NAME } from "./c64.ts";
 
 export type Mode = "imp" | "imm" | "zp" | "zpx" | "zpy" | "abs" | "abx" | "aby" | "ind" | "izx" | "izy" | "rel";
 
@@ -45,6 +45,17 @@ export const MODE_LENGTH: Record<Mode, 1 | 2 | 3> = { imp: 1, imm: 2, zp: 2, zpx
 /** Every mnemonic in the table: a symbol with one of these names would read as an instruction. */
 export const MNEMONICS: ReadonlySet<string> = new Set(OPCODES.map((opcode) => opcode.mnemonic));
 
+/**
+ * Why ACME cannot take a name as a label, or undefined when it can. A label
+ * has label syntax (SYMBOL_NAME) and is no mnemonic in upper or lower case.
+ * The one rule for a symbol of the knowledge and a label of c64-source.
+ */
+export function labelProblem(name: string): string | undefined {
+  if (!SYMBOL_NAME.test(name)) return "A symbol name is a letter or underscore, then letters, digits or underscores (at most 64), with an optional leading dot.";
+  if (MNEMONICS.has(name.toLowerCase())) return `${name} is the name of a 6502 instruction, which ACME cannot read as a label. Give another name.`;
+  return undefined;
+}
+
 const ZERO_PAGE_OF: Partial<Record<Mode, Mode>> = { abs: "zp", abx: "zpx", aby: "zpy" };
 
 /** True when the mnemonic also has the zero-page form of an absolute mode: ACME would pick it for a small operand. */
@@ -78,26 +89,48 @@ export function useKind(opcode: number): UseKind {
 }
 
 
-/** The text of the instruction in `bytes` at `pc`, for example "sta $d011" or "bne $c002". */
-export function instructionText(bytes: readonly number[], pc: number): string {
-  const { mnemonic, mode } = OPCODES[bytes[0]!]!;
-  const low = bytes[1] ?? 0;
-  const word = low | ((bytes[2] ?? 0) << 8);
+/**
+ * The ACME text of an instruction with its operand as an expression: the
+ * mnemonic, the size suffix (+1 or +2, or none) and the operand in the syntax
+ * of its addressing mode, for example "lda #<table", "sta screen,x" or
+ * "lda (pointer),y". ACME reads an operand in brackets as indirect, so a
+ * non-immediate expression that starts with a bracket gets 0+ in front.
+ * The one place that writes an instruction: the generated source, the
+ * listing of the knowledge and the disassembly of the emulator use it.
+ */
+export function instructionWith(opcode: number, expression: string, suffix = ""): string {
+  const { mnemonic, mode } = OPCODES[opcode]!;
+  const value = mode !== "imm" && expression.startsWith("(") ? `0+${expression}` : expression;
   const operand: Record<Mode, string> = {
     imp: "",
-    imm: `#${formatC64Byte(low)}`,
-    zp: formatC64Byte(low),
-    zpx: `${formatC64Byte(low)},x`,
-    zpy: `${formatC64Byte(low)},y`,
-    abs: formatC64Address(word),
-    abx: `${formatC64Address(word)},x`,
-    aby: `${formatC64Address(word)},y`,
-    ind: `(${formatC64Address(word)})`,
-    izx: `(${formatC64Byte(low)},x)`,
-    izy: `(${formatC64Byte(low)}),y`,
-    rel: formatC64Address((pc + 2 + (low < 0x80 ? low : low - 0x100)) & 0xffff),
+    imm: `#${value}`,
+    zp: value,
+    zpx: `${value},x`,
+    zpy: `${value},y`,
+    abs: value,
+    abx: `${value},x`,
+    aby: `${value},y`,
+    ind: `(${value})`,
+    izx: `(${value},x)`,
+    izy: `(${value}),y`,
+    rel: value,
   };
-  return operand[mode] === "" ? mnemonic : `${mnemonic} ${operand[mode]}`;
+  return operand[mode] === "" ? `${mnemonic}${suffix}` : `${mnemonic}${suffix} ${operand[mode]}`;
+}
+
+/** The value of the operand of the instruction in `bytes` at `pc` as a number: a byte, a word, or the target of a branch. Empty for no operand. */
+export function operandNumber(bytes: readonly number[], pc: number): string {
+  const { mode } = OPCODES[bytes[0]!]!;
+  const low = bytes[1] ?? 0;
+  if (mode === "imp") return "";
+  if (mode === "rel") return formatC64Address((pc + 2 + (low < 0x80 ? low : low - 0x100)) & 0xffff);
+  return MODE_LENGTH[mode] === 3 ? formatC64Address(low | ((bytes[2] ?? 0) << 8)) : formatC64Byte(low);
+}
+
+/** The text of the instruction in `bytes` at `pc` as the monitor shows it, for example "STA $d011" or "BNE $c002". */
+export function instructionText(bytes: readonly number[], pc: number): string {
+  const { mnemonic } = OPCODES[bytes[0]!]!;
+  return `${mnemonic.toUpperCase()}${instructionWith(bytes[0]!, operandNumber(bytes, pc)).slice(mnemonic.length)}`;
 }
 
 /**

package/src/project.ts

@@ -5,7 +5,7 @@
 // the agent saves for itself and ignores itself in git.
 
 import { Refusal } from "./errors.ts";
-import { existsSync, mkdirSync, readdirSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { accessSync, constants, existsSync, lstatSync, mkdirSync, readdirSync, realpathSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 
@@ -117,9 +117,10 @@ export function namedProject(folder: string, cwd: string = process.cwd()): strin
   if (stat === undefined) throw new Refusal("not-found", `There is no folder ${folder}.`);
   if (!stat.isDirectory()) throw new Refusal("invalid-input", `${folder} is not a folder.`);
   if (path === homedir()) throw new Refusal("invalid-input", "The home folder is not a project folder.");
-  const outer = foldersUpFrom(path).slice(1).find(isProject);
+  // A project inside another project is a project of its own, as the lookup from a working directory in it finds.
+  const outer = isProject(path) ? undefined : foldersUpFrom(path).slice(1).find(isProject);
   if (outer !== undefined) {
-    throw new Refusal("invalid-input", `${folder} is inside the project ${relative(cwd, outer) || "."}. Give that project folder.`);
+    throw new Refusal("invalid-input", `${folder} is inside the project ${relative(cwd, outer) || outer}. Give that project folder.`);
   }
   return path;
 }
@@ -180,6 +181,113 @@ export function resolveProjectPath(path: string, root = projectRoot()): string {
   throw new Refusal("invalid-input", `${path} leads out of the project folder: give a path that stays inside it.`);
 }
 
+/** The folder of the committed knowledge text in PROJECT_DIRECTORY. The knowledge (src/knowledge/database.ts) has the same name. */
+export const KNOWLEDGE_TEXT_DIRECTORY = "knowledge";
+
+/** The index of the knowledge in LOCAL_DIRECTORY, and the files that SQLite keeps beside it. The knowledge has the same name. */
+const KNOWLEDGE_INDEX = /^knowledge\.db(?:-wal|-shm|-journal)?$/;
+
+/**
+ * The part of the knowledge that a path relative to the project folder is in:
+ * the text in .c64-re-tools/knowledge/ or the index in .c64-re-tools/local/.
+ * Undefined for every other path. Letter case does not count: some file
+ * systems do not tell the cases apart.
+ */
+export function knowledgePart(fromRoot: string): string | undefined {
+  const parts = fromRoot.split(/[\\/]+/).filter((part) => part !== "" && part !== ".").map((part) => part.toLowerCase());
+  if (parts[0] !== PROJECT_DIRECTORY) return undefined;
+  if (parts[1] === KNOWLEDGE_TEXT_DIRECTORY) return `${PROJECT_DIRECTORY}/${KNOWLEDGE_TEXT_DIRECTORY}/`;
+  if (parts[1] === LOCAL_DIRECTORY && parts.length === 3 && KNOWLEDGE_INDEX.test(parts[2]!)) return `${PROJECT_DIRECTORY}/${LOCAL_DIRECTORY}/${parts[2]}`;
+  return undefined;
+}
+
+/** What a command writes at an output path: one file, or files in a folder. */
+export type OutputKind = "file" | "folder";
+
+/** Why a file cannot be written, by the error code of the file system; the codes that are a fault of the path. */
+const WRITE_PROBLEMS: Record<string, string> = {
+  EISDIR: "is a folder. Give the path of a file",
+  EEXIST: "has a file where a folder must be. Give a path whose folders are folders",
+  ENOTDIR: "has a file where a folder must be. Give a path whose folders are folders",
+  ENOENT: "is in a folder that does not exist",
+  EACCES: "cannot be written: there is no permission. Give a path that you can write",
+  EPERM: "cannot be written: there is no permission. Give a path that you can write",
+  EROFS: "is on a file system that is read-only. Give another path",
+  ENAMETOOLONG: "is too long. Give a shorter path",
+};
+
+/**
+ * The message for a write that the file system refused because of the path
+ * (a folder, a file in place of a folder, no permission): the path and what
+ * to do. Undefined for another error, which is no fault of the path.
+ */
+export function writeProblem(error: unknown, path: string, what?: string): string | undefined {
+  const problem = WRITE_PROBLEMS[(error as NodeJS.ErrnoException | undefined)?.code ?? ""];
+  return problem === undefined ? undefined : `${what === undefined ? "" : `${what}: `}${path} ${problem}.`;
+}
+
+/**
+ * Checks a path that a command writes, before the command does any work. The
+ * path must stay inside the project, also through symbolic links, and must
+ * not be in the knowledge (only the c64-knowledge skill writes it). A file
+ * must not be a folder or a symbolic link; a folder must be a folder. The
+ * nearest folder that exists must be a folder that can be written. Returns
+ * the absolute path. Throws a Refusal (invalid-input) whose message starts
+ * with `what` (for example --out). writeProjectFile does the same check for
+ * each file that it writes.
+ */
+export function checkOutputPath(path: string, kind: OutputKind, options: { root?: string; what?: string } = {}): string {
+  const root = options.root ?? projectRoot();
+  const what = options.what;
+  const outside = () => new Refusal("invalid-input", `${what ?? path}: give a path relative to the project folder that stays inside it, not ${path}.`);
+  const problem = (error: unknown) => {
+    const message = writeProblem(error, path, what);
+    return message === undefined ? error : new Refusal("invalid-input", message);
+  };
+  const inKnowledge = (fromRoot: string) => {
+    const part = knowledgePart(fromRoot);
+    if (part !== undefined) {
+      throw new Refusal("invalid-input", `${what === undefined ? "" : `${what}: `}${path} is in ${part}, the knowledge of the project. Only the c64-knowledge skill writes it: a write there destroys the knowledge. Give a path outside ${PROJECT_DIRECTORY}/${KNOWLEDGE_TEXT_DIRECTORY}/, for example ${PROJECT_DIRECTORY}/${LOCAL_DIRECTORY}/<file>.`);
+    }
+  };
+  let target: string;
+  try {
+    target = resolveProjectPath(path, root);
+  } catch {
+    throw outside();
+  }
+  inKnowledge(relative(root, target));
+  // The nearest entry that exists: the path itself, or a folder above it.
+  let existing = target;
+  for (;;) {
+    let found;
+    try {
+      found = lstatSync(existing, { throwIfNoEntry: false });
+    } catch (error) {
+      throw problem(error);
+    }
+    if (found !== undefined) break;
+    existing = dirname(existing);
+  }
+  const realRoot = realpathSync(root);
+  if (existing === target && kind === "file" && lstatSync(target).isSymbolicLink()) throw outside();
+  const real = realpathSync(existing);
+  if (!isInside(realRoot, real)) throw outside();
+  inKnowledge(relative(realRoot, join(real, relative(existing, target))));
+  const stat = statSync(real);
+  if (existing === target && kind === "file") {
+    if (stat.isDirectory()) throw problem({ code: "EISDIR" });
+  } else if (!stat.isDirectory()) {
+    throw problem({ code: "ENOTDIR" });
+  }
+  try {
+    accessSync(real, constants.W_OK);
+  } catch (error) {
+    throw problem(error);
+  }
+  return target;
+}
+
 /** A project path in one spelling: relative to the project folder, with / and without ./, .. or a double /. Refuses a path as resolveProjectPath does. */
 export function projectRelative(path: string, root = projectRoot()): string {
   return relative(root, resolveProjectPath(path, root)).split(sep).join("/");

package/src/protocol/vice.ts

@@ -385,6 +385,8 @@ export interface MachineStatus {
   stopReason?: PointStopReason;
   /** The id of the breakpoint or watchpoint that stopped the machine. */
   pointId?: number;
+  /** With pc: the CPU whose address pc is, drive8 when a point in the drive stopped the machine. */
+  space?: "c64" | "drive8";
 }
 
 /** What stopped the machine outside a request that stops it. */
@@ -462,6 +464,8 @@ export interface ExecutionResult {
   stopReason?: "frames" | PointStopReason;
   /** The id of the breakpoint or watchpoint that stopped the run. */
   pointId?: number;
+  /** advance-frames only: the CPU that stopped, and so the space of pc. */
+  space?: "c64" | "drive8";
 }
 
 /** c64_run_until targets. */
@@ -1090,7 +1094,8 @@ export function validateViceResult<O extends ViceOperation>(op: O, value: unknow
         (value.pc === undefined || isInteger(value.pc, 0, 0xffff)) &&
         typeof value.cartridge === "boolean" &&
         (value.stopReason === undefined || isOneOf(POINT_STOP_REASONS, value.stopReason)) &&
-        (value.pointId === undefined || isInteger(value.pointId, 1, Number.MAX_SAFE_INTEGER));
+        (value.pointId === undefined || isInteger(value.pointId, 1, Number.MAX_SAFE_INTEGER)) &&
+        (value.space === undefined || isOneOf(SPACES, value.space));
       if (!ok) throw new ProtocolError("status result is malformed");
       break;
     }
@@ -1171,7 +1176,8 @@ export function validateViceResult<O extends ViceOperation>(op: O, value: unknow
         (value.executed === undefined || isInteger(value.executed, 0, MAX_EXECUTION_COUNT)) &&
         (value.advancedFrames === undefined || isInteger(value.advancedFrames, 0, MAX_EXECUTION_COUNT)) &&
         (value.stopReason === undefined || value.stopReason === "frames" || isOneOf(POINT_STOP_REASONS, value.stopReason)) &&
-        (value.pointId === undefined || isInteger(value.pointId, 1, Number.MAX_SAFE_INTEGER));
+        (value.pointId === undefined || isInteger(value.pointId, 1, Number.MAX_SAFE_INTEGER)) &&
+        (value.space === undefined || isOneOf(SPACES, value.space));
       if (!ok) throw new ProtocolError("execution result is malformed");
       break;
     }

package/src/script.ts

@@ -13,7 +13,7 @@ import { parseArgs } from "node:util";
 
 import { c64AddressOf, formatC64Address, SPACE_PATTERN, SYMBOL_NAME, type AddressRange } from "./c64.ts";
 import { isRefusal, Refusal, type ErrorCode } from "./errors.ts";
-import { projectRoot, resolveProjectPath, useProject } from "./project.ts";
+import { checkOutputPath, projectRoot, resolveProjectPath, useProject, type OutputKind } from "./project.ts";
 import { shownMessage } from "./protocol/messages.ts";
 import { elapsedMs, startTrace, trace, type TraceFields } from "./trace.ts";
 
@@ -59,6 +59,12 @@ export interface OptionSpec {
   max?: number;
   /** The value when the option is not given. */
   default?: number | string;
+  /**
+   * path only: the command writes there, a file or files in a folder. The
+   * path is checked before the command runs (checkOutputPath). Every option
+   * --out and --out-<name> has it.
+   */
+  output?: OutputKind;
 }
 
 /** The options that have one meaning in every script. A command can change the help, the value and whether it is required, never the kind. */
@@ -157,7 +163,7 @@ export class Call {
 
   /** The knowledge space of the command: --space, else c64. */
   get space(): string {
-    return "space" in this.#options ? this.string("space")! : "c64";
+    return ("space" in this.#options ? this.string("space") : undefined) ?? "c64";
   }
 
   /** Subject `index` as text. */
@@ -339,6 +345,8 @@ function commandOptions(command: CommandSpec): Record<string, OptionSpec> {
     const shared = (OPTIONS as Record<string, OptionSpec>)[name];
     if (shared !== undefined && shared.kind !== spec.kind) throw fault(`--${name} of ${command.name} is a ${spec.kind}, but OPTIONS has it as a ${shared.kind}`);
     if (name === "help" || name === "project") throw fault(`--${name} of ${command.name}: the contract owns this option`);
+    if (spec.kind === "path" && (name === "out" || name.startsWith("out-")) && spec.output === undefined) throw fault(`--${name} of ${command.name} has no output kind (file or folder)`);
+    if (spec.output !== undefined && spec.kind !== "path") throw fault(`--${name} of ${command.name} has an output kind, but it is a ${spec.kind}, not a path`);
   }
   return options;
 }
@@ -391,9 +399,49 @@ function checkPath(text: string, what: string): void {
   }
 }
 
+/**
+ * Refuses a range in two parts: two subjects '$1bc2' '$1bd0' where the command
+ * takes one <range>, or --start and --end where it takes a range option. The
+ * message gives the range as one token.
+ */
+function refuseSplitRange(command: CommandSpec, options: Readonly<Record<string, OptionSpec>>, argv: readonly string[], subjects?: readonly string[]): void {
+  if (subjects === undefined) {
+    const end = argv.indexOf("--");
+    const words = end < 0 ? argv : argv.slice(0, end);
+    const valueOf = (name: string) => {
+      const index = words.findIndex((word) => word === `--${name}` || word.startsWith(`--${name}=`));
+      if (index < 0) return undefined;
+      const word = words[index]!;
+      return word.includes("=") ? word.slice(word.indexOf("=") + 1) : (words[index + 1] ?? "");
+    };
+    const [start, last] = [valueOf("start"), valueOf("end")];
+    const range = Object.entries(options).find(([, spec]) => spec.kind === "range")?.[0];
+    if ((start === undefined && last === undefined) || range === undefined || "start" in options || "end" in options) return;
+    throw new UsageError(`${command.name} takes no --start or --end. Give the range as one option: --${range} '${start || "<start>"}-${last || "<end>"}'`);
+  }
+  const specs = command.subjects ?? [];
+  for (let index = 0; index + 1 < subjects.length; index++) {
+    const spec = specs[Math.min(index, specs.length - 1)];
+    const [first, second] = [subjects[index]!, subjects[index + 1]!];
+    if (spec === undefined || !spec.name.includes("range") || rangeParts(first) !== undefined || !isAddressText(first) || c64AddressOf(second) === undefined) continue;
+    throw new UsageError(`${spec.name} is one token <start>-<end>: give '${first}-${second}', not '${first}' '${second}'`);
+  }
+}
+
+/**
+ * Refuses an output path before the command does any work: a path that
+ * leaves the project, a path in the knowledge, a folder where a file must be,
+ * a file where a folder must be, or a folder that cannot be written.
+ */
+function checkOutput(text: string, what: string, kind: OutputKind): void {
+  checkPath(text, what);
+  checkOutputPath(text, kind, { root: projectRoot(), what });
+}
+
 /** Parses the command line of one command. Refuses a wrong count of subjects, an unknown option, a missing required option or a value of the wrong form. */
 export function parseCall(script: ScriptSpec, command: CommandSpec, argv: readonly string[]): Call {
   const options = commandOptions(command);
+  refuseSplitRange(command, options, argv);
   let parsed: ReturnType<typeof parseArgs>;
   try {
     parsed = parseArgs({
@@ -407,6 +455,7 @@ export function parseCall(script: ScriptSpec, command: CommandSpec, argv: readon
   }
   const values = parsed.values as Record<string, string | boolean | string[] | undefined>;
   const subjects = parsed.positionals;
+  refuseSplitRange(command, options, argv, subjects);
   const specs = command.subjects ?? [];
   const last = specs.at(-1);
   const least = specs.filter((subject) => !subject.optional).length;
@@ -428,7 +477,10 @@ export function parseCall(script: ScriptSpec, command: CommandSpec, argv: readon
       if (spec.kind === "range" && rangeParts(text) === undefined) throw new UsageError(`--${name} must be <start>-<end>, each ${ADDRESS_FORM}, for example '$c000-$cfff', not ${JSON.stringify(text)}`);
       if (spec.kind === "space" && !SPACE_PATTERN.test(text)) throw new UsageError(`--${name} must be c64, drive8, or bank0 to bank255, not ${JSON.stringify(text)}`);
       if (spec.kind === "choice" && !(spec.choices ?? []).includes(text)) throw new UsageError(`--${name} must be one of ${(spec.choices ?? []).join(", ")}, not ${JSON.stringify(text)}`);
-      if (spec.kind === "path") checkPath(text, `--${name}`);
+      if (spec.kind === "path") {
+        if (spec.output === undefined) checkPath(text, `--${name}`);
+        else checkOutput(text, `--${name}`, spec.output);
+      }
     }
   }
   const call = new Call(script.name, command.name, subjects, options, values, script.names);