c64bridge 1.0.6 → 1.1.0

package/dist/tools/translation/assembler.js

@@ -109,6 +109,11 @@ const DIRECTIVE_ALIASES = {
     "RES": "reserve",
     ".DS": "reserve",
     "DS": "reserve",
+    ".EQU": "equ",
+    ".FILL": "fill",
+    ".ALIGN": "align",
+    ".TEXT": "text",
+    ".ASCII": "text",
     ".INCLUDE": "include",
     "INCLUDE": "include",
 };
@@ -151,17 +156,28 @@ class Parser {
         for (let index = 0; index < lines.length; index += 1) {
             const originalLine = lines[index] ?? "";
             const location = { file: fileName, line: index + 1, text: originalLine };
-            const tokens = tokenize(originalLine);
-            if (tokens.length === 0) {
-                continue;
+            let labels = [];
+            let statement;
+            try {
+                const tokens = tokenize(originalLine);
+                if (tokens.length === 0) {
+                    continue;
+                }
+                const stream = new TokenStream(tokens);
+                labels = [];
+                while (stream.peek()?.kind === "symbol" && stream.peek(1)?.kind === "punct" && stream.peek(1).value === ":") {
+                    labels.push(stream.consumeSymbol());
+                    stream.consumePunct(":");
+                }
+                statement = this.parseStatement(stream, location, includeStack, statements);
             }
-            const stream = new TokenStream(tokens);
-            const labels = [];
-            while (stream.peek()?.kind === "symbol" && stream.peek(1)?.kind === "punct" && stream.peek(1).value === ":") {
-                labels.push(stream.consumeSymbol());
-                stream.consumePunct(":");
+            catch (error) {
+                // Name the source line for syntax errors as well.
+                if (error instanceof AssemblyError) {
+                    throw error;
+                }
+                throw new AssemblyError(error instanceof Error ? error.message : String(error), location);
             }
-            const statement = this.parseStatement(stream, location, includeStack, statements);
             statements.push({
                 labels,
                 statement,
@@ -200,6 +216,15 @@ class Parser {
         if (first.kind !== "symbol") {
             throw new AssemblyError("Expected an opcode, directive, or assignment", location);
         }
+        // "name .equ expr", the same as "name = expr".
+        const second = stream.peek(1);
+        if (second?.kind === "symbol" && second.value.toUpperCase() === ".EQU") {
+            const target = stream.consumeSymbol();
+            stream.consumeSymbol();
+            const expr = parseExpression(stream, new Set());
+            stream.expectEnd();
+            return { kind: "assignment", target, expr, isLocationCounter: false };
+        }
         const upper = stream.consumeSymbol().toUpperCase();
         if (upper in DIRECTIVE_ALIASES) {
             const directive = DIRECTIVE_ALIASES[upper];
@@ -228,7 +253,26 @@ class Parser {
                     this.parseInto(statements, normalizeSource(includeContent), includeName, [...includeStack, includePath]);
                     return undefined;
                 }
+                case "equ": {
+                    // ".equ name, expr", the same as "name = expr".
+                    const target = stream.consumeSymbol(".equ expects a symbol name");
+                    stream.consumePunct(",", ".equ expects a comma between the name and the value");
+                    const expr = parseExpression(stream, new Set());
+                    stream.expectEnd();
+                    return { kind: "assignment", target, expr, isLocationCounter: false };
+                }
+                case "fill":
+                case "align": {
+                    const args = [{ kind: "expr", expr: parseExpression(stream, new Set([","])) }];
+                    if (stream.peek()?.kind === "punct" && stream.peek().value === ",") {
+                        stream.consumePunct(",");
+                        args.push({ kind: "expr", expr: parseExpression(stream, new Set()) });
+                    }
+                    stream.expectEnd();
+                    return { kind: "directive", name: directive, args };
+                }
                 case "byte":
+                case "text":
                 case "word": {
                     const args = [];
                     while (!stream.isAtEnd()) {
@@ -638,13 +682,34 @@ class SymbolTable {
     constructor() {
         this.globals = new Map();
         this.locals = new Map();
+        this.definitions = new Map();
     }
     reset() {
         this.globals = new Map();
         this.locals = new Map();
+        this.definitions.clear();
         this.currentScope = undefined;
     }
-    setLabel(label, value) {
+    /**
+     * Records where a name was first defined and rejects a second definition.
+     * Redefining a constant with the same value is allowed.
+     */
+    recordDefinition(label, value, isLabel, location) {
+        if (!location)
+            return;
+        const key = label.startsWith(".") ? `${this.currentScope ?? ""}\u0000${label}` : label;
+        const previous = this.definitions.get(key);
+        if (previous && (previous.isLabel || isLabel || previous.value !== value)) {
+            const kind = isLabel || previous.isLabel ? "label" : "symbol";
+            throw new Error(`Duplicate ${kind} "${label}" (first defined at ${previous.location.file}:${previous.location.line})`);
+        }
+        this.definitions.set(key, { location, value, isLabel });
+    }
+    setLabel(label, value, location) {
+        if (label.startsWith(".") && !this.currentScope) {
+            throw new Error(`Local label "${label}" defined before any global label`);
+        }
+        this.recordDefinition(label, value, true, location);
         if (label.startsWith(".")) {
             if (!this.currentScope) {
                 throw new Error(`Local label "${label}" defined before any global label`);
@@ -668,7 +733,11 @@ class SymbolTable {
     ensureAssignment(label, expected) {
         this.ensureUnchanged(label, expected);
     }
-    setAssignment(label, value) {
+    setAssignment(label, value, location) {
+        if (label.startsWith(".") && !this.currentScope) {
+            throw new Error(`Local constant "${label}" defined before any global label`);
+        }
+        this.recordDefinition(label, value, false, location);
         if (label.startsWith(".")) {
             if (!this.currentScope) {
                 throw new Error(`Local constant "${label}" defined before any global label`);
@@ -814,7 +883,7 @@ class Assembler {
     processLine(line, pass) {
         for (const label of line.labels) {
             if (pass === 0) {
-                this.symbolTable.setLabel(label, this.pc);
+                this.symbolTable.setLabel(label, this.pc, line.location);
             }
             else {
                 this.symbolTable.ensureLabel(label, this.pc);
@@ -840,13 +909,13 @@ class Assembler {
     handleAssignment(statement, pass, location) {
         const value = this.evaluate(statement.expr, pass, location);
         if (value === undefined) {
-            throw new AssemblyError("Assignment depends on an undefined symbol", location);
+            throw this.undefinedError(statement.expr, location, "Assignment depends on an undefined symbol");
         }
         if (statement.isLocationCounter) {
             this.pc = value & 0xffff;
         }
         else if (pass === 0) {
-            this.symbolTable.setAssignment(statement.target, value);
+            this.symbolTable.setAssignment(statement.target, value, location);
         }
         else {
             this.symbolTable.ensureAssignment(statement.target, value);
@@ -860,17 +929,23 @@ class Assembler {
                 }
                 const value = this.evaluate(statement.args[0]?.expr, pass, location);
                 if (value === undefined) {
-                    throw new AssemblyError("org directive requires a defined value", location);
+                    throw this.undefinedError(statement.args[0].expr, location, "org directive requires a defined value");
                 }
                 this.pc = value & 0xffff;
                 break;
             }
-            case "byte": {
+            case "byte":
+            case "text": {
+                const isText = statement.name === "text";
                 for (const arg of statement.args) {
                     if (arg.kind === "string") {
                         if (pass === 1) {
                             for (const char of arg.value) {
-                                this.writeByte(char.charCodeAt(0), location);
+                                const code = isText ? asciiToPetscii(char, location) : char.charCodeAt(0);
+                                if (code > 0xff) {
+                                    throw new AssemblyError(`byte directive character '${char}' (code ${code}) does not fit in one byte`, location);
+                                }
+                                this.writeByte(code, location);
                             }
                         }
                         else {
@@ -881,7 +956,10 @@ class Assembler {
                         const value = this.evaluate(arg.expr, pass, location);
                         if (pass === 1) {
                             if (value === undefined) {
-                                throw new AssemblyError("byte directive contains undefined expression", location);
+                                throw this.undefinedError(arg.expr, location, "byte directive contains undefined expression");
+                            }
+                            if (value < -128 || value > 255) {
+                                throw new AssemblyError(`byte directive value ${value} is outside -128..255 and would be truncated`, location);
                             }
                             this.writeByte(value, location);
                         }
@@ -908,11 +986,14 @@ class Assembler {
                         const value = this.evaluate(arg.expr, pass, location);
                         if (value === undefined) {
                             if (pass === 1) {
-                                throw new AssemblyError("word directive contains undefined expression", location);
+                                throw this.undefinedError(arg.expr, location, "word directive contains undefined expression");
                             }
                             this.pc += 2;
                         }
                         else if (pass === 1) {
+                            if (value < -32768 || value > 65535) {
+                                throw new AssemblyError(`word directive value ${value} is outside -32768..65535 and would be truncated`, location);
+                            }
                             this.writeWord(value, location);
                         }
                         else {
@@ -922,22 +1003,62 @@ class Assembler {
                 }
                 break;
             }
+            case "fill": {
+                const count = this.evaluateDefined(statement.args[0], pass, location, "fill directive");
+                if (!Number.isInteger(count) || count < 0 || count > 0x10000) {
+                    throw new AssemblyError(`fill directive requires a count of 0..65536, got ${count}`, location);
+                }
+                const value = statement.args[1] ? this.evaluateDefined(statement.args[1], pass, location, "fill directive") : 0;
+                if (pass === 1) {
+                    this.checkByteValue(value, "fill directive", location);
+                    for (let index = 0; index < count; index += 1)
+                        this.writeByte(value, location);
+                }
+                else {
+                    this.pc += count;
+                }
+                break;
+            }
+            case "align": {
+                const boundary = this.evaluateDefined(statement.args[0], pass, location, "align directive");
+                if (!Number.isInteger(boundary) || boundary < 1 || boundary > 0x10000) {
+                    throw new AssemblyError(`align directive requires a boundary of 1..65536, got ${boundary}`, location);
+                }
+                const value = statement.args[1] ? this.evaluateDefined(statement.args[1], pass, location, "align directive") : 0;
+                const padding = (boundary - (this.pc % boundary)) % boundary;
+                if (pass === 1) {
+                    this.checkByteValue(value, "align directive", location);
+                    for (let index = 0; index < padding; index += 1)
+                        this.writeByte(value, location);
+                }
+                else {
+                    this.pc += padding;
+                }
+                break;
+            }
+            case "equ": {
+                // Parsed as an assignment; never reaches the directive handler.
+                break;
+            }
             case "reserve": {
                 if (statement.args.length !== 1 || statement.args[0]?.kind !== "expr") {
                     throw new AssemblyError("reserve directive expects a single expression", location);
                 }
                 const amount = this.evaluate(statement.args[0]?.expr, pass, location);
                 if (amount === undefined) {
-                    throw new AssemblyError("reserve directive requires a defined value", location);
+                    throw this.undefinedError(statement.args[0].expr, location, "reserve directive requires a defined value");
                 }
                 if (amount < 0) {
                     throw new AssemblyError("reserve directive requires a non-negative size", location);
                 }
                 // Reserved space advances the PC without emitting; buildPrg includes it
                 // (zero-filled) only where it adjoins emitted bytes.
+                if (this.pc + amount > MAX_ADDRESS + 1) {
+                    throw new AssemblyError(`reserve directive of ${amount} bytes at ${formatHex(this.pc)} passes $FFFF`, location);
+                }
                 if (amount > 0)
-                    this.reserved.push([this.pc, Math.min(0xffff, this.pc + amount - 1)]);
-                this.pc = (this.pc + amount) & 0xffff;
+                    this.reserved.push([this.pc, this.pc + amount - 1]);
+                this.pc += amount;
                 break;
             }
             case "include": {
@@ -957,7 +1078,8 @@ class Assembler {
             return;
         }
         if (modeExpectsValue(info.mode) && info.value === undefined) {
-            throw new AssemblyError("Undefined expression", location);
+            const operand = statement.operand;
+            throw this.undefinedError("expr" in operand ? operand.expr : undefined, location, "Undefined expression");
         }
         const opcode = lookupOpcode(statement.mnemonic, info.mode, location);
         this.writeByte(opcode, location);
@@ -989,6 +1111,46 @@ class Assembler {
                 throw new AssemblyError(`Unhandled addressing mode ${info.mode}`, location);
         }
     }
+    evaluateDefined(arg, pass, location, context) {
+        if (arg.kind !== "expr") {
+            throw new AssemblyError(`${context} expects a numeric expression`, location);
+        }
+        const value = this.evaluate(arg.expr, pass, location);
+        if (value === undefined) {
+            throw this.undefinedError(arg.expr, location, `${context} requires a defined value`);
+        }
+        return value;
+    }
+    checkByteValue(value, context, location) {
+        if (value < -128 || value > 255) {
+            throw new AssemblyError(`${context} value ${value} is outside -128..255 and would be truncated`, location);
+        }
+    }
+    undefinedSymbols(expr) {
+        if (!expr)
+            return [];
+        switch (expr.type) {
+            case "number":
+                return [];
+            case "symbol":
+                return expr.name !== "*" && this.symbolTable.get(expr.name) === undefined ? [expr.name] : [];
+            case "unary":
+                return this.undefinedSymbols(expr.operand);
+            case "binary":
+                return [...new Set([...this.undefinedSymbols(expr.left), ...this.undefinedSymbols(expr.right)])];
+            default:
+                return [];
+        }
+    }
+    /** Names the undefined symbols of an expression; falls back to the generic message. */
+    undefinedError(expr, location, fallback) {
+        const names = this.undefinedSymbols(expr);
+        if (names.length === 0) {
+            return new AssemblyError(fallback, location);
+        }
+        const quoted = names.map((name) => `"${name}"`).join(", ");
+        return new AssemblyError(`Undefined symbol${names.length > 1 ? "s" : ""} ${quoted}`, location);
+    }
     evaluate(expr, pass, location) {
         switch (expr.type) {
             case "number":
@@ -1071,12 +1233,17 @@ class Assembler {
         }
     }
     writeByte(value, location) {
+        if (this.pc > MAX_ADDRESS) {
+            throw new AssemblyError(`Output passes $FFFF: a byte would be written at ${formatHex(this.pc)}, outside the 64 KB address space`, location);
+        }
         const masked = value & 0xff;
         this.memory[this.pc] = masked;
         this.written[this.pc] = 1;
         this.lowestWritten = Math.min(this.lowestWritten, this.pc);
         this.highestWritten = Math.max(this.highestWritten, this.pc);
-        this.pc = (this.pc + 1) & 0xffff;
+        // The counter may reach $10000 so that a following write is detected; a
+        // wrapped counter would silently overwrite the start of the image.
+        this.pc += 1;
     }
     writeWord(value, location) {
         const masked = value & 0xffff;
@@ -1084,10 +1251,28 @@ class Assembler {
         this.writeByte((masked >> 8) & 0xff, location);
     }
 }
+/**
+ * ASCII to PETSCII for .text/.ascii in the default upper-case/graphics
+ * character set: a-z and A-Z both become the PETSCII upper-case codes
+ * $41-$5A, newline becomes RETURN ($0D), every other ASCII character is
+ * unchanged. Characters above $7F have no mapping.
+ */
+function asciiToPetscii(char, location) {
+    const code = char.charCodeAt(0);
+    if (code > 0x7f) {
+        throw new AssemblyError(`text directive character '${char}' (code ${code}) is not ASCII and has no PETSCII mapping`, location);
+    }
+    if (code >= 0x61 && code <= 0x7a)
+        return code - 0x20;
+    if (code === 0x0a)
+        return 0x0d;
+    return code;
+}
 function determineInstruction(statement, pass, evaluator, locationCounter, location) {
     if (statement.resolvedMode && pass === 1) {
         const value = statement.operand.kind === "none" ? undefined : resolveOperandValue(statement.operand, evaluator, pass, location);
         assertZeroPageOperand(statement.mnemonic, statement.resolvedMode, value, location);
+        assertOperandRange(statement.mnemonic, statement.resolvedMode, value, location);
         const size = instructionSize(statement.resolvedMode);
         return {
             mode: statement.resolvedMode,
@@ -1207,6 +1392,44 @@ function assertZeroPageOperand(mnemonic, mode, value, location) {
     }
     throw new AssemblyError(`Instruction ${mnemonic} does not support ${absoluteMode} addressing (operand ${formatHex(value)} is outside zero page)`, location);
 }
+/**
+ * Rejects operands that the encoding would truncate. Runs in the final pass
+ * only, where every symbol has a value; in the first pass a forward reference
+ * is still undefined and is sized as absolute.
+ */
+function assertOperandRange(mnemonic, mode, value, location) {
+    if (value === undefined)
+        return;
+    switch (mode) {
+        case AddressingMode.Immediate:
+            if (value < -128 || value > 255) {
+                throw new AssemblyError(`Immediate operand ${value} of ${mnemonic} is outside -128..255 and would be truncated to one byte`, location);
+            }
+            return;
+        case AddressingMode.IndirectX:
+        case AddressingMode.IndirectY:
+            if (value < 0 || value > 0xff) {
+                const form = mode === AddressingMode.IndirectX ? "(zp,X)" : "(zp),Y";
+                throw new AssemblyError(`Instruction ${mnemonic} ${form} requires a zero-page operand ($00-$FF), got ${value < 0 ? value : formatHex(value)}`, location);
+            }
+            return;
+        case AddressingMode.ZeroPageS:
+            if (value < 0 || value > 0xff) {
+                throw new AssemblyError(`Stack-relative operand ${value} of ${mnemonic} is outside 0..255`, location);
+            }
+            return;
+        case AddressingMode.Absolute:
+        case AddressingMode.AbsoluteX:
+        case AddressingMode.AbsoluteY:
+        case AddressingMode.Indirect:
+            if (value < 0 || value > 0xffff) {
+                throw new AssemblyError(`Address operand ${value} of ${mnemonic} is outside $0000-$FFFF`, location);
+            }
+            return;
+        default:
+            return;
+    }
+}
 const ZERO_PAGE_TO_ABSOLUTE_MODE = new Map([
     [AddressingMode.ZeroPage, AddressingMode.Absolute],
     [AddressingMode.ZeroPageX, AddressingMode.AbsoluteX],

package/dist/tools/translation/basicDetokenizer.js

@@ -0,0 +1,80 @@
+/*
+C64 Bridge - An MCP Server for the Commodore 64 Ultimate
+Copyright (C) 2025 Christian Gleissner
+
+Licensed under the GNU General Public License v2.0 or later.
+See <https://www.gnu.org/licenses/> for details.
+*/
+import { petsciiToAscii } from "../../petscii.js";
+import { basicTokenText } from "./basicTokenizer.js";
+import { ToolExecutionError } from "../errors.js";
+/** Largest program image accepted, matching the 64 KiB address space. */
+export const MAX_BASIC_IMAGE_BYTES = 0x10000;
+function hex16(value) {
+    return `$${value.toString(16).toUpperCase().padStart(4, "0")}`;
+}
+function plainChar(byte) {
+    if (byte === 0x20 || byte === 0xa0)
+        return " ";
+    const ch = petsciiToAscii(Uint8Array.of(byte));
+    return ch.length === 1 && ch > " " && ch <= "~" ? ch : `{$${byte.toString(16).toUpperCase().padStart(2, "0")}}`;
+}
+/** Expands tokens outside quotes like LIST; quoted text is never detokenised. */
+export function detokenizeLine(bytes) {
+    let out = "";
+    let inString = false;
+    for (const byte of bytes) {
+        if (byte === 0x22) {
+            inString = !inString;
+            out += '"';
+            continue;
+        }
+        if (!inString && byte >= 0x80) {
+            out += basicTokenText(byte) ?? plainChar(byte);
+            continue;
+        }
+        out += plainChar(byte);
+    }
+    return out;
+}
+/**
+ * Walks the link pointers of a tokenised BASIC program held in `image`, which
+ * starts at memory address `base`. Throws when a link does not move forward or
+ * leaves the image, so a corrupt program cannot loop.
+ */
+export function listBasicProgram(image, base) {
+    if (image.length > MAX_BASIC_IMAGE_BYTES) {
+        throw new ToolExecutionError("BASIC program image is larger than 64 KiB", { details: { length: image.length } });
+    }
+    const lines = [];
+    let offset = 0;
+    while (offset + 2 <= image.length) {
+        const link = image[offset] | (image[offset + 1] << 8);
+        if (link === 0)
+            return lines;
+        const linkOffset = link - base;
+        const address = hex16(base + offset);
+        if (linkOffset <= offset + 4) {
+            throw new ToolExecutionError(`Corrupt BASIC link at ${address}: link ${hex16(link)} does not point past the line`, {
+                details: { address, link },
+            });
+        }
+        if (linkOffset > image.length) {
+            throw new ToolExecutionError(`Corrupt BASIC link at ${address}: link ${hex16(link)} is outside the program area`, {
+                details: { address, link },
+            });
+        }
+        const number = image[offset + 2] | (image[offset + 3] << 8);
+        let end = offset + 4;
+        while (end < linkOffset && image[end] !== 0)
+            end += 1;
+        if (end >= linkOffset) {
+            throw new ToolExecutionError(`Corrupt BASIC line ${number} at ${address}: no end-of-line byte before the next link`, {
+                details: { address, number },
+            });
+        }
+        lines.push({ number, text: detokenizeLine(image.subarray(offset + 4, end)) });
+        offset = linkOffset;
+    }
+    return lines;
+}

package/dist/tools/translation/basicTokenizer.js

@@ -7,6 +7,7 @@ See <https://www.gnu.org/licenses/> for details.
 */
 import { Buffer } from "node:buffer";
 import { asciiToPetscii, encodeStringWithNames } from "../../petscii.js";
+import { ToolValidationError } from "../errors.js";
 const DEFAULT_START_ADDRESS = 0x0801;
 const REM_TOKEN = 0x8f;
 const DATA_TOKEN = 0x83;
@@ -14,6 +15,10 @@ const PRINT_TOKEN = 0x99;
 // Highest line number the BASIC V2 line parser (LINGET) accepts; larger values give ?SYNTAX ERROR.
 const MAX_LINE_NUMBER = 63999;
 const TOKEN_TABLE = buildTokenTable();
+/** Keyword text for a BASIC V2 token byte (0x80-0xCB), or undefined. */
+export function basicTokenText(byte) {
+    return TOKEN_TABLE.find((entry) => entry.byte === byte)?.text;
+}
 export function basicToPrg(source, options) {
     const startAddress = options?.startAddress ?? DEFAULT_START_ADDRESS;
     const normalizedSource = normalize(source);
@@ -21,18 +26,18 @@ export function basicToPrg(source, options) {
     // Like typing lines into the C64, lines are kept in ascending order, a later
     // duplicate replaces the earlier line, and a bare line number deletes it.
     const programLines = new Map();
-    for (const rawLine of lines) {
+    for (const [lineIndex, rawLine] of lines.entries()) {
         const trimmedRight = rawLine.replace(/\s+$/u, "");
         if (trimmedRight === "") {
             continue;
         }
         const match = /^\s*(\d+)\s*(.*)$/u.exec(trimmedRight);
         if (!match) {
-            throw new Error(`Expected line number at: "${rawLine}"`);
+            throw new ToolValidationError(`Expected a line number at the start of line ${lineIndex + 1} of the program: "${rawLine}"`, { path: "$.program" });
         }
         const lineNumber = Number.parseInt(match[1], 10);
         if (!Number.isInteger(lineNumber) || lineNumber < 0 || lineNumber > MAX_LINE_NUMBER) {
-            throw new Error(`Line number out of range: ${match[1]} (C64 BASIC accepts 0-${MAX_LINE_NUMBER})`);
+            throw new ToolValidationError(`Line number out of range: ${match[1]} on line ${lineIndex + 1} of the program (C64 BASIC accepts 0-${MAX_LINE_NUMBER})`, { path: "$.program" });
         }
         const content = match[2] ?? "";
         if (content === "") {

package/dist/tools/translation/disassembler.js

@@ -102,6 +102,20 @@ export function disassemble(bytes, baseAddress, countOrOptions, symbols) {
             continue;
         }
         const size = modeSize(op.mode);
+        if (offset + size > bytes.length) {
+            // The input ends inside this instruction: its operand bytes are unknown,
+            // so show the bytes that exist as data instead of inventing an operand.
+            const remaining = Array.from(bytes.subarray(offset));
+            lines.push({
+                address: instrAddr,
+                bytes: remaining,
+                label,
+                mnemonic: ".byte",
+                operand: remaining.map((value) => `$${hex2(value)}`).join(","),
+                undocumented: false,
+            });
+            break;
+        }
         const instrBytes = [];
         for (let i = 0; i < size && offset + i < bytes.length; i += 1) {
             instrBytes.push(bytes[offset + i] ?? 0);