@razdolbai/merls 0.1.0

package/src/asm/metadata.ts

@@ -0,0 +1,150 @@
+export type AddressingMode =
+  | "implied"
+  | "accumulator"
+  | "immediate"
+  | "zeroPage"
+  | "zeroPageX"
+  | "zeroPageY"
+  | "relative"
+  | "absolute"
+  | "absoluteX"
+  | "absoluteY"
+  | "indirect"
+  | "indexedIndirect"
+  | "indirectIndexed";
+
+export type DirectiveKind =
+  | "assembler"
+  | "build"
+  | "data"
+  | "include"
+  | "mode"
+  | "storage";
+
+export type OpcodeDefinition = {
+  mnemonic: string;
+  modes: readonly AddressingMode[];
+};
+
+export type DirectiveDefinition = {
+  name: string;
+  kind: DirectiveKind;
+  supported: boolean;
+  summary: string;
+};
+
+function defineOpcode(
+  mnemonic: string,
+  modes: readonly AddressingMode[]
+): OpcodeDefinition {
+  return {
+    mnemonic,
+    modes
+  };
+}
+
+function defineDirective(
+  name: string,
+  kind: DirectiveKind,
+  supported: boolean,
+  summary: string
+): DirectiveDefinition {
+  return {
+    name,
+    kind,
+    supported,
+    summary
+  };
+}
+
+export const opcodeDefinitions: readonly OpcodeDefinition[] = [
+  defineOpcode("adc", ["immediate", "zeroPage", "zeroPageX", "absolute", "absoluteX", "absoluteY", "indexedIndirect", "indirectIndexed"]),
+  defineOpcode("and", ["immediate", "zeroPage", "zeroPageX", "absolute", "absoluteX", "absoluteY", "indexedIndirect", "indirectIndexed"]),
+  defineOpcode("asl", ["accumulator", "zeroPage", "zeroPageX", "absolute", "absoluteX"]),
+  defineOpcode("bcc", ["relative"]),
+  defineOpcode("bcs", ["relative"]),
+  defineOpcode("beq", ["relative"]),
+  defineOpcode("bit", ["zeroPage", "absolute"]),
+  defineOpcode("bmi", ["relative"]),
+  defineOpcode("bne", ["relative"]),
+  defineOpcode("bpl", ["relative"]),
+  defineOpcode("brk", ["implied"]),
+  defineOpcode("bvc", ["relative"]),
+  defineOpcode("bvs", ["relative"]),
+  defineOpcode("clc", ["implied"]),
+  defineOpcode("cld", ["implied"]),
+  defineOpcode("cli", ["implied"]),
+  defineOpcode("clv", ["implied"]),
+  defineOpcode("cmp", ["immediate", "zeroPage", "zeroPageX", "absolute", "absoluteX", "absoluteY", "indexedIndirect", "indirectIndexed"]),
+  defineOpcode("cpx", ["immediate", "zeroPage", "absolute"]),
+  defineOpcode("cpy", ["immediate", "zeroPage", "absolute"]),
+  defineOpcode("dec", ["zeroPage", "zeroPageX", "absolute", "absoluteX"]),
+  defineOpcode("dex", ["implied"]),
+  defineOpcode("dey", ["implied"]),
+  defineOpcode("eor", ["immediate", "zeroPage", "zeroPageX", "absolute", "absoluteX", "absoluteY", "indexedIndirect", "indirectIndexed"]),
+  defineOpcode("inc", ["zeroPage", "zeroPageX", "absolute", "absoluteX"]),
+  defineOpcode("inx", ["implied"]),
+  defineOpcode("iny", ["implied"]),
+  defineOpcode("jmp", ["absolute", "indirect"]),
+  defineOpcode("jsr", ["absolute"]),
+  defineOpcode("lda", ["immediate", "zeroPage", "zeroPageX", "absolute", "absoluteX", "absoluteY", "indexedIndirect", "indirectIndexed"]),
+  defineOpcode("ldx", ["immediate", "zeroPage", "zeroPageY", "absolute", "absoluteY"]),
+  defineOpcode("ldy", ["immediate", "zeroPage", "zeroPageX", "absolute", "absoluteX"]),
+  defineOpcode("lsr", ["accumulator", "zeroPage", "zeroPageX", "absolute", "absoluteX"]),
+  defineOpcode("nop", ["implied"]),
+  defineOpcode("ora", ["immediate", "zeroPage", "zeroPageX", "absolute", "absoluteX", "absoluteY", "indexedIndirect", "indirectIndexed"]),
+  defineOpcode("pha", ["implied"]),
+  defineOpcode("php", ["implied"]),
+  defineOpcode("pla", ["implied"]),
+  defineOpcode("plp", ["implied"]),
+  defineOpcode("rol", ["accumulator", "zeroPage", "zeroPageX", "absolute", "absoluteX"]),
+  defineOpcode("ror", ["accumulator", "zeroPage", "zeroPageX", "absolute", "absoluteX"]),
+  defineOpcode("rti", ["implied"]),
+  defineOpcode("rts", ["implied"]),
+  defineOpcode("sbc", ["immediate", "zeroPage", "zeroPageX", "absolute", "absoluteX", "absoluteY", "indexedIndirect", "indirectIndexed"]),
+  defineOpcode("sec", ["implied"]),
+  defineOpcode("sed", ["implied"]),
+  defineOpcode("sei", ["implied"]),
+  defineOpcode("sta", ["zeroPage", "zeroPageX", "absolute", "absoluteX", "absoluteY", "indexedIndirect", "indirectIndexed"]),
+  defineOpcode("stx", ["zeroPage", "zeroPageY", "absolute"]),
+  defineOpcode("sty", ["zeroPage", "zeroPageX", "absolute"]),
+  defineOpcode("tax", ["implied"]),
+  defineOpcode("tay", ["implied"]),
+  defineOpcode("tsx", ["implied"]),
+  defineOpcode("txa", ["implied"]),
+  defineOpcode("txs", ["implied"]),
+  defineOpcode("tya", ["implied"])
+];
+
+export const opcodeTable = new Map(
+  opcodeDefinitions.map((definition) => [definition.mnemonic, definition] as const)
+);
+
+export const directiveDefinitions: readonly DirectiveDefinition[] = [
+  defineDirective("asm", "include", true, "Assemble another source file immediately."),
+  defineDirective("asc", "data", true, "Emit an ASCII string."),
+  defineDirective("da", "data", true, "Emit an address-sized value."),
+  defineDirective("db", "data", true, "Emit byte data."),
+  defineDirective("dend", "storage", true, "End a DUM storage section."),
+  defineDirective("dsk", "build", true, "Set the output disk or image name."),
+  defineDirective("ds", "storage", true, "Reserve storage bytes."),
+  defineDirective("dum", "storage", true, "Begin a DUM storage section."),
+  defineDirective("end", "assembler", true, "End assembly."),
+  defineDirective("equ", "assembler", true, "Define a symbolic constant."),
+  defineDirective("err", "assembler", true, "Force an assembly error."),
+  defineDirective("hex", "data", true, "Emit raw hexadecimal bytes."),
+  defineDirective("mac", "assembler", true, "Begin a macro definition."),
+  defineDirective("mx", "mode", false, "65816-only accumulator and index width control."),
+  defineDirective("org", "assembler", true, "Set or restore the assembly origin."),
+  defineDirective("put", "include", true, "Include another source file."),
+  defineDirective("sav", "build", true, "Save an output file."),
+  defineDirective("sna", "build", true, "Set the output file name."),
+  defineDirective("str", "data", true, "Emit a Merlin string."),
+  defineDirective("typ", "build", true, "Set the output file type."),
+  defineDirective("use", "include", true, "Include a library-style source file."),
+  defineDirective("xc", "mode", false, "65816-only extended instruction mode control.")
+];
+
+export const directiveTable = new Map(
+  directiveDefinitions.map((definition) => [definition.name, definition] as const)
+);

package/src/asm/parser.ts

@@ -0,0 +1,197 @@
+import { directiveTable } from "./metadata";
+import { type Expression, type Operand, parseExpression, parseOperand } from "./expression";
+import { type LexedLine, lexSource, type Token } from "./lexer";
+
+export type ParsedLine =
+  | EmptyLine
+  | CommentLine
+  | LabelOnlyLine
+  | EquateLine
+  | InstructionLine
+  | DirectiveLine
+  | DataLine
+  | MalformedLine;
+
+export type EmptyLine = {
+  shape: "empty";
+  text: string;
+};
+
+export type CommentLine = {
+  shape: "commentOnly";
+  text: string;
+  comment: string;
+};
+
+export type LabelOnlyLine = {
+  shape: "labelOnly";
+  text: string;
+  label: string;
+};
+
+export type EquateLine = {
+  shape: "equate";
+  text: string;
+  label: string;
+  expression: Expression;
+};
+
+export type InstructionLine = {
+  shape: "instruction";
+  text: string;
+  label: string | null;
+  mnemonic: string;
+  operand: Operand | null;
+};
+
+export type DirectiveLine = {
+  shape: "directive";
+  text: string;
+  label: string | null;
+  directive: string;
+  operand: Expression | null;
+};
+
+export type DataLine = {
+  shape: "data";
+  text: string;
+  label: string | null;
+  directive: string;
+  payload: string;
+};
+
+export type MalformedLine = {
+  shape: "malformed";
+  text: string;
+  message: string;
+};
+
+const dataDirectiveKinds = new Set(["data"]);
+
+export function parseSourceLines(source: string): readonly ParsedLine[] {
+  return lexSource(source).lines.map(parseLexedLine);
+}
+
+export function parseLexedLine(line: LexedLine): ParsedLine {
+  const tokens = stripTrailingComment(line.tokens);
+
+  if (tokens.length === 0) {
+    const commentToken = line.tokens[0];
+    if (commentToken?.kind === "comment") {
+      return {
+        shape: "commentOnly",
+        text: line.text,
+        comment: commentToken.lexeme
+      };
+    }
+
+    return {
+      shape: "empty",
+      text: line.text
+    };
+  }
+
+  try {
+    return parseStructuredLine(line.text, tokens);
+  } catch (error) {
+    return {
+      shape: "malformed",
+      text: line.text,
+      message: error instanceof Error ? error.message : "unknown parse failure"
+    };
+  }
+}
+
+function parseStructuredLine(text: string, tokens: readonly Token[]): ParsedLine {
+  let index = 0;
+  let label: string | null = null;
+
+  if (tokens[index]?.kind === "label" || tokens[index]?.kind === "localLabel") {
+    label = tokens[index]?.lexeme ?? null;
+    index += 1;
+  }
+
+  const token = tokens[index];
+  if (token === undefined) {
+    if (label !== null) {
+      return {
+        shape: "labelOnly",
+        text,
+        label
+      };
+    }
+
+    return {
+      shape: "empty",
+      text
+    };
+  }
+
+  if (token.kind === "expressionOperator" && token.lexeme === "=") {
+    if (label === null) {
+      throw new Error("equate requires a label");
+    }
+
+    const parsed = parseExpression(tokens, index + 1);
+    return {
+      shape: "equate",
+      text,
+      label,
+      expression: parsed.expression
+    };
+  }
+
+  if (token.kind === "mnemonic") {
+    const operandTokens = tokens.slice(index + 1);
+    const operand = operandTokens.length > 0 ? parseOperand(operandTokens).operand : null;
+    return {
+      shape: "instruction",
+      text,
+      label,
+      mnemonic: token.lexeme.toLowerCase(),
+      operand
+    };
+  }
+
+  if (token.kind === "directive") {
+    const directive = directiveTable.get(token.lexeme.toLowerCase());
+    if (directive !== undefined && dataDirectiveKinds.has(directive.kind)) {
+      return {
+        shape: "data",
+        text,
+        label,
+        directive: token.lexeme.toLowerCase(),
+        payload: tokens.slice(index + 1).map((current) => current.lexeme).join("")
+      };
+    }
+
+    const operandTokens = tokens.slice(index + 1);
+    const directiveName = token.lexeme.toLowerCase();
+
+    if (operandTokens.length > 0 && (directiveName === "end" || directiveName === "dend" || directiveName === "xc")) {
+      throw new Error(`unexpected operand for ${directiveName}`);
+    }
+
+    const operand = operandTokens.length > 0
+      ? parseExpression(operandTokens).expression
+      : null;
+    return {
+      shape: "directive",
+      text,
+      label,
+      directive: directiveName,
+      operand
+    };
+  }
+
+  throw new Error(`unsupported line start: ${token.lexeme}`);
+}
+
+function stripTrailingComment(tokens: readonly Token[]): readonly Token[] {
+  const commentIndex = tokens.findIndex((token) => token.kind === "comment");
+  if (commentIndex === -1) {
+    return tokens;
+  }
+
+  return tokens.slice(0, commentIndex);
+}

package/src/asm/symbols.ts

@@ -0,0 +1,55 @@
+import { directiveTable } from "./metadata";
+import { type ParsedDocument } from "./document";
+
+export type SymbolKind = "label" | "equate" | "data";
+
+export type SymbolDefinition = {
+  name: string;
+  kind: SymbolKind;
+  line: number;
+};
+
+export function collectSymbols(document: ParsedDocument): Map<string, SymbolDefinition> {
+  const symbols = new Map<string, SymbolDefinition>();
+
+  for (const line of document.lines) {
+    const node = line.node;
+
+    if (node.shape === "equate") {
+      symbols.set(node.label, defineSymbol(node.label, "equate", line.line));
+      continue;
+    }
+
+    if (node.shape === "labelOnly") {
+      symbols.set(node.label, defineSymbol(node.label, "label", line.line));
+      continue;
+    }
+
+    if (node.shape === "instruction" && node.label !== null) {
+      symbols.set(node.label, defineSymbol(node.label, "label", line.line));
+      continue;
+    }
+
+    if (node.shape === "directive" && node.label !== null) {
+      const directive = directiveTable.get(node.directive);
+      if (directive?.kind === "data" || directive?.kind === "storage") {
+        symbols.set(node.label, defineSymbol(node.label, "data", line.line));
+      }
+      continue;
+    }
+
+    if (node.shape === "data" && node.label !== null) {
+      symbols.set(node.label, defineSymbol(node.label, "data", line.line));
+    }
+  }
+
+  return symbols;
+}
+
+function defineSymbol(name: string, kind: SymbolKind, line: number): SymbolDefinition {
+  return {
+    name,
+    kind,
+    line
+  };
+}

package/src/asm/syntax.ts

@@ -0,0 +1,76 @@
+export type TokenKindDefinition = {
+  name: string;
+  description: string;
+  captureExamples: readonly string[];
+};
+
+export type LineShapeDefinition = {
+  name: string;
+  description: string;
+  allowsLabel: boolean;
+  allowsExpression: boolean;
+  requiresOperand: boolean;
+  terminal: boolean;
+};
+
+function defineTokenKind(
+  name: string,
+  description: string,
+  captureExamples: readonly string[]
+): TokenKindDefinition {
+  return {
+    name,
+    description,
+    captureExamples
+  };
+}
+
+function defineLineShape(
+  name: string,
+  description: string,
+  allowsLabel: boolean,
+  allowsExpression: boolean,
+  requiresOperand: boolean,
+  terminal: boolean
+): LineShapeDefinition {
+  return {
+    name,
+    description,
+    allowsLabel,
+    allowsExpression,
+    requiresOperand,
+    terminal
+  };
+}
+
+export const tokenKindDefinitions: readonly TokenKindDefinition[] = [
+  defineTokenKind("comment", "Line or trailing comment text.", ["; trailing note", "* monitor addresses"]),
+  defineTokenKind("label", "Global symbol at the start of a line.", ["TEST_START", "GetKey"]),
+  defineTokenKind("localLabel", "Merlin local label form.", ["]loop", ":good"]),
+  defineTokenKind("directive", "Assembler directive or pseudo-op.", ["org", "dum", "hex"]),
+  defineTokenKind("mnemonic", "6502 instruction mnemonic.", ["lda", "adc", "jmp"]),
+  defineTokenKind("string", "Quoted string literal.", ["\"THE END\"", "'A'"]),
+  defineTokenKind("numericLiteral", "Numeric literal in Merlin syntax.", ["$800", "#0", "%00"]),
+  defineTokenKind("modifier", "Unary byte or bank selector modifier.", ["<value", ">value", "^value"]),
+  defineTokenKind("expressionOperator", "Operator inside an expression.", ["+", "-", "*"]),
+  defineTokenKind("identifier", "Non-label symbol reference.", ["_tmp", "dumSize", "DOSWARM"])
+];
+
+export const tokenKindTable = new Map(
+  tokenKindDefinitions.map((definition) => [definition.name, definition] as const)
+);
+
+export const lineShapeDefinitions: readonly LineShapeDefinition[] = [
+  defineLineShape("empty", "Whitespace-only line.", false, false, false, true),
+  defineLineShape("commentOnly", "Full-line comment.", false, false, false, true),
+  defineLineShape("labelOnly", "Standalone label with no operation.", true, false, false, true),
+  defineLineShape("instruction", "Instruction mnemonic with optional operand.", true, true, false, true),
+  defineLineShape("directive", "Directive with optional operand depending on directive kind.", true, true, false, true),
+  defineLineShape("equate", "Symbol definition using an expression.", true, true, true, true),
+  defineLineShape("data", "Data-emitting directive such as ASC, DB, or HEX.", true, true, true, true),
+  defineLineShape("malformed", "Token sequence that does not match a known line shape.", true, true, false, true)
+];
+
+export const lineShapeTable = new Map(
+  lineShapeDefinitions.map((definition) => [definition.name, definition] as const)
+);

package/src/asm/workspace.ts

@@ -0,0 +1,105 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { parseDocument, type ParsedDocument } from "./document";
+import { type Expression } from "./expression";
+import { collectSymbols } from "./symbols";
+
+export type WorkspaceSymbol = {
+  name: string;
+  kind: "label" | "equate" | "data";
+  line: number;
+  filePath: string;
+};
+
+export type IndexedWorkspace = {
+  documents: Map<string, ParsedDocument>;
+  dependencies: Map<string, readonly string[]>;
+  loadOrder: readonly string[];
+  symbols: Map<string, WorkspaceSymbol>;
+};
+
+const includeDirectives = new Set(["asm", "put", "use"]);
+
+export function indexWorkspace(entryPath: string): IndexedWorkspace {
+  const documents = new Map<string, ParsedDocument>();
+  const dependencies = new Map<string, readonly string[]>();
+  const loadOrder: string[] = [];
+  const symbols = new Map<string, WorkspaceSymbol>();
+
+  visitFile(path.resolve(entryPath), documents, dependencies, loadOrder);
+
+  for (const filePath of loadOrder) {
+    const document = documents.get(filePath);
+    if (document === undefined) {
+      continue;
+    }
+
+    for (const symbol of collectSymbols(document).values()) {
+      symbols.set(symbol.name, {
+        ...symbol,
+        filePath
+      });
+    }
+  }
+
+  return {
+    documents,
+    dependencies,
+    loadOrder,
+    symbols
+  };
+}
+
+function visitFile(
+  filePath: string,
+  documents: Map<string, ParsedDocument>,
+  dependencies: Map<string, readonly string[]>,
+  loadOrder: string[]
+): void {
+  if (documents.has(filePath)) {
+    return;
+  }
+
+  const source = fs.readFileSync(filePath, "utf8");
+  const document = parseDocument(source);
+  documents.set(filePath, document);
+  loadOrder.push(filePath);
+
+  const resolvedDependencies = document.lines
+    .flatMap((line) => {
+      const node = line.node;
+      if (node.shape !== "directive" || !includeDirectives.has(node.directive)) {
+        return [];
+      }
+
+      const includePath = readIncludePath(node.operand);
+      if (includePath === null) {
+        return [];
+      }
+
+      return [path.resolve(path.dirname(filePath), includePath)];
+    });
+
+  dependencies.set(filePath, resolvedDependencies);
+
+  for (const dependencyPath of resolvedDependencies) {
+    visitFile(dependencyPath, documents, dependencies, loadOrder);
+  }
+}
+
+function readIncludePath(expression: Expression | null): string | null {
+  if (expression === null) {
+    return null;
+  }
+
+  if (expression.kind === "identifier") {
+    return expression.value;
+  }
+
+  if (expression.kind === "string") {
+    return expression.value;
+  }
+
+  return null;
+}

package/src/cli.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+
+import { startServer } from "./server";
+
+const usage = "Usage: merls --stdio";
+
+export function runCli(argv: readonly string[]): number {
+  if (argv.length === 1 && argv[0] === "--stdio") {
+    startServer();
+    return 0;
+  }
+
+  if (argv.length === 1 && (argv[0] === "--help" || argv[0] === "-h")) {
+    process.stdout.write(`${usage}\n`);
+    return 0;
+  }
+
+  process.stderr.write(`${usage}\n`);
+  return 1;
+}
+
+if (require.main === module) {
+  process.exitCode = runCli(process.argv.slice(2));
+}

package/src/index.ts

@@ -0,0 +1 @@
+export const projectName = "merls";

package/src/lsp/completion.ts

@@ -0,0 +1,42 @@
+import {
+  CompletionItemKind,
+  type CompletionItem
+} from "vscode-languageserver/node";
+
+import { directiveDefinitions, opcodeDefinitions } from "../asm/metadata";
+import { parseDocument } from "../asm/document";
+import { collectSymbols } from "../asm/symbols";
+
+export function buildCompletionItems(
+  openDocuments: ReadonlyMap<string, string>,
+  uri: string,
+  line: number
+): CompletionItem[] {
+  const source = openDocuments.get(uri);
+  if (source === undefined) {
+    return [];
+  }
+
+  const document = parseDocument(source);
+  const text = document.lines[line]?.node.text.trimStart().toLowerCase() ?? "";
+
+  if (text === "ld" || text === "ld\n" || text.startsWith("ld")) {
+    return opcodeDefinitions.map((opcode) => ({
+      label: opcode.mnemonic,
+      kind: CompletionItemKind.Keyword
+    }));
+  }
+
+  if (text === "du" || text.startsWith("du")) {
+    return directiveDefinitions.map((directive) => ({
+      label: directive.name,
+      kind: CompletionItemKind.Function
+    }));
+  }
+
+  const symbols = collectSymbols(document);
+  return [...symbols.values()].map((symbol) => ({
+    label: symbol.name,
+    kind: CompletionItemKind.Variable
+  }));
+}