@razdolbai/merls 0.1.0

package/dist/src/asm/syntax.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lineShapeTable = exports.lineShapeDefinitions = exports.tokenKindTable = exports.tokenKindDefinitions = void 0;
+function defineTokenKind(name, description, captureExamples) {
+    return {
+        name,
+        description,
+        captureExamples
+    };
+}
+function defineLineShape(name, description, allowsLabel, allowsExpression, requiresOperand, terminal) {
+    return {
+        name,
+        description,
+        allowsLabel,
+        allowsExpression,
+        requiresOperand,
+        terminal
+    };
+}
+exports.tokenKindDefinitions = [
+    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"])
+];
+exports.tokenKindTable = new Map(exports.tokenKindDefinitions.map((definition) => [definition.name, definition]));
+exports.lineShapeDefinitions = [
+    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)
+];
+exports.lineShapeTable = new Map(exports.lineShapeDefinitions.map((definition) => [definition.name, definition]));

package/dist/src/asm/workspace.js

@@ -0,0 +1,73 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.indexWorkspace = indexWorkspace;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const document_1 = require("./document");
+const symbols_1 = require("./symbols");
+const includeDirectives = new Set(["asm", "put", "use"]);
+function indexWorkspace(entryPath) {
+    const documents = new Map();
+    const dependencies = new Map();
+    const loadOrder = [];
+    const symbols = new Map();
+    visitFile(node_path_1.default.resolve(entryPath), documents, dependencies, loadOrder);
+    for (const filePath of loadOrder) {
+        const document = documents.get(filePath);
+        if (document === undefined) {
+            continue;
+        }
+        for (const symbol of (0, symbols_1.collectSymbols)(document).values()) {
+            symbols.set(symbol.name, {
+                ...symbol,
+                filePath
+            });
+        }
+    }
+    return {
+        documents,
+        dependencies,
+        loadOrder,
+        symbols
+    };
+}
+function visitFile(filePath, documents, dependencies, loadOrder) {
+    if (documents.has(filePath)) {
+        return;
+    }
+    const source = node_fs_1.default.readFileSync(filePath, "utf8");
+    const document = (0, document_1.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 [node_path_1.default.resolve(node_path_1.default.dirname(filePath), includePath)];
+    });
+    dependencies.set(filePath, resolvedDependencies);
+    for (const dependencyPath of resolvedDependencies) {
+        visitFile(dependencyPath, documents, dependencies, loadOrder);
+    }
+}
+function readIncludePath(expression) {
+    if (expression === null) {
+        return null;
+    }
+    if (expression.kind === "identifier") {
+        return expression.value;
+    }
+    if (expression.kind === "string") {
+        return expression.value;
+    }
+    return null;
+}

package/dist/src/cli.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCli = runCli;
+const server_1 = require("./server");
+const usage = "Usage: merls --stdio";
+function runCli(argv) {
+    if (argv.length === 1 && argv[0] === "--stdio") {
+        (0, server_1.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/dist/src/index.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectName = void 0;
+exports.projectName = "merls";

package/dist/src/lsp/completion.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCompletionItems = buildCompletionItems;
+const node_1 = require("vscode-languageserver/node");
+const metadata_1 = require("../asm/metadata");
+const document_1 = require("../asm/document");
+const symbols_1 = require("../asm/symbols");
+function buildCompletionItems(openDocuments, uri, line) {
+    const source = openDocuments.get(uri);
+    if (source === undefined) {
+        return [];
+    }
+    const document = (0, document_1.parseDocument)(source);
+    const text = document.lines[line]?.node.text.trimStart().toLowerCase() ?? "";
+    if (text === "ld" || text === "ld\n" || text.startsWith("ld")) {
+        return metadata_1.opcodeDefinitions.map((opcode) => ({
+            label: opcode.mnemonic,
+            kind: node_1.CompletionItemKind.Keyword
+        }));
+    }
+    if (text === "du" || text.startsWith("du")) {
+        return metadata_1.directiveDefinitions.map((directive) => ({
+            label: directive.name,
+            kind: node_1.CompletionItemKind.Function
+        }));
+    }
+    const symbols = (0, symbols_1.collectSymbols)(document);
+    return [...symbols.values()].map((symbol) => ({
+        label: symbol.name,
+        kind: node_1.CompletionItemKind.Variable
+    }));
+}

package/dist/src/lsp/diagnostics.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectDiagnosticsByUri = collectDiagnosticsByUri;
+const node_url_1 = require("node:url");
+const node_1 = require("vscode-languageserver/node");
+const document_1 = require("../asm/document");
+const diagnostics_1 = require("../asm/diagnostics");
+function collectDiagnosticsByUri(openDocuments) {
+    const sourcesByFilePath = new Map();
+    const uriByFilePath = new Map();
+    const entries = [];
+    for (const [uri, source] of openDocuments.entries()) {
+        const filePath = uriToFilePath(uri);
+        sourcesByFilePath.set(filePath, source);
+        uriByFilePath.set(filePath, uri);
+        entries.push({
+            filePath,
+            document: (0, document_1.parseDocument)(source)
+        });
+    }
+    const diagnosticsByFilePath = new Map();
+    for (const entry of entries) {
+        diagnosticsByFilePath.set(entry.filePath, []);
+    }
+    for (const diagnostic of (0, diagnostics_1.collectWorkspaceDiagnostics)(entries)) {
+        const source = sourcesByFilePath.get(diagnostic.filePath);
+        const diagnostics = diagnosticsByFilePath.get(diagnostic.filePath);
+        if (source === undefined || diagnostics === undefined) {
+            continue;
+        }
+        diagnostics.push(toLspDiagnostic(source, diagnostic));
+    }
+    const diagnosticsByUri = new Map();
+    for (const [filePath, uri] of uriByFilePath.entries()) {
+        diagnosticsByUri.set(uri, diagnosticsByFilePath.get(filePath) ?? []);
+    }
+    return diagnosticsByUri;
+}
+function toLspDiagnostic(source, diagnostic) {
+    const lineText = source.split(/\r?\n/)[diagnostic.line] ?? "";
+    return {
+        severity: node_1.DiagnosticSeverity.Error,
+        message: diagnostic.message,
+        source: "merls",
+        code: diagnostic.code,
+        range: {
+            start: {
+                line: diagnostic.line,
+                character: 0
+            },
+            end: {
+                line: diagnostic.line,
+                character: lineText.length
+            }
+        }
+    };
+}
+function uriToFilePath(uri) {
+    if (uri.startsWith("file://")) {
+        return (0, node_url_1.fileURLToPath)(uri);
+    }
+    return uri;
+}

package/dist/src/lsp/document-symbols.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildDocumentSymbols = buildDocumentSymbols;
+const node_1 = require("vscode-languageserver/node");
+const document_1 = require("../asm/document");
+function buildDocumentSymbols(uri, source) {
+    const document = (0, document_1.parseDocument)(source);
+    const symbols = [];
+    for (const line of document.lines) {
+        const symbol = toSymbolInformation(uri, line.node, line.line);
+        if (symbol !== null) {
+            symbols.push(symbol);
+        }
+    }
+    return symbols;
+}
+function toSymbolInformation(uri, node, line) {
+    const name = getNodeName(node);
+    const kind = getNodeKind(node);
+    if (name === null || kind === null) {
+        return null;
+    }
+    return {
+        name,
+        kind,
+        location: createLocation(uri, line, name)
+    };
+}
+function getNodeName(node) {
+    if (node.shape === "equate") {
+        return node.label;
+    }
+    if (node.shape === "labelOnly") {
+        return node.label;
+    }
+    if (node.shape === "instruction" && node.label !== null) {
+        return node.label;
+    }
+    if (node.shape === "directive" && node.label !== null) {
+        return node.label;
+    }
+    if (node.shape === "data" && node.label !== null) {
+        return node.label;
+    }
+    return null;
+}
+function getNodeKind(node) {
+    if (node.shape === "equate") {
+        return node_1.SymbolKind.Variable;
+    }
+    if (node.shape === "labelOnly") {
+        return node_1.SymbolKind.Method;
+    }
+    if (node.shape === "instruction" && node.label !== null) {
+        return node_1.SymbolKind.Method;
+    }
+    if (node.shape === "directive" && node.label !== null) {
+        return node_1.SymbolKind.Field;
+    }
+    if (node.shape === "data" && node.label !== null) {
+        return node_1.SymbolKind.Field;
+    }
+    return null;
+}
+function createLocation(uri, line, name) {
+    const range = {
+        start: {
+            line,
+            character: 0
+        },
+        end: {
+            line,
+            character: name.length
+        }
+    };
+    return {
+        uri,
+        range
+    };
+}

package/dist/src/lsp/hover.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildHover = buildHover;
+const metadata_1 = require("../asm/metadata");
+const document_1 = require("../asm/document");
+const lexer_1 = require("../asm/lexer");
+const symbol_navigation_1 = require("./symbol-navigation");
+function buildHover(openDocuments, uri, line, character) {
+    const source = openDocuments.get(uri);
+    if (source === undefined) {
+        return null;
+    }
+    const documentLine = (0, document_1.parseDocument)(source).lines[line];
+    const lexedLine = (0, lexer_1.lexSource)(source).lines[line];
+    if (documentLine === undefined || lexedLine === undefined) {
+        return null;
+    }
+    const token = tokenAtCharacter(lexedLine.tokens, character);
+    if (token?.kind === "mnemonic") {
+        const definition = metadata_1.opcodeTable.get(token.lexeme.toLowerCase());
+        if (definition !== undefined) {
+            return {
+                contents: `Opcode ${definition.mnemonic}: ${definition.modes.join(", ")}`
+            };
+        }
+    }
+    if (token?.kind === "directive") {
+        const definition = metadata_1.directiveTable.get(token.lexeme.toLowerCase());
+        if (definition !== undefined) {
+            return {
+                contents: `Directive ${definition.name}: ${definition.summary}`
+            };
+        }
+    }
+    if (token?.kind === "identifier" || token?.kind === "label" || token?.kind === "localLabel") {
+        const lexemeLower = token.lexeme.toLowerCase();
+        if (lexemeLower === "a" || lexemeLower === "x" || lexemeLower === "y") {
+            return {
+                contents: `Register ${token.lexeme.toUpperCase()}`
+            };
+        }
+        const definition = (0, symbol_navigation_1.findDefinition)(openDocuments, uri, line);
+        if (definition !== null) {
+            return {
+                contents: `Symbol ${token.lexeme} defined at line ${definition.range.start.line}`
+            };
+        }
+    }
+    const node = documentLine.node;
+    if (node.shape === "instruction") {
+        const definition = metadata_1.opcodeTable.get(node.mnemonic);
+        if (definition !== undefined) {
+            return {
+                contents: `Opcode ${definition.mnemonic}: ${definition.modes.join(", ")}`
+            };
+        }
+    }
+    if (node.shape === "directive") {
+        const definition = metadata_1.directiveTable.get(node.directive);
+        if (definition !== undefined) {
+            return {
+                contents: `Directive ${definition.name}: ${definition.summary}`
+            };
+        }
+    }
+    return null;
+}
+function tokenAtCharacter(tokens, character) {
+    for (const token of tokens) {
+        if (character >= token.start && character < token.end) {
+            return token;
+        }
+    }
+    return null;
+}

package/dist/src/lsp/symbol-navigation.js

@@ -0,0 +1,181 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findDefinition = findDefinition;
+exports.findReferences = findReferences;
+const document_1 = require("../asm/document");
+function findDefinition(openDocuments, uri, line) {
+    const targetName = getSymbolAtLine(openDocuments.get(uri), line);
+    if (targetName === null) {
+        return null;
+    }
+    for (const [documentUri, source] of openDocuments.entries()) {
+        for (const definition of collectDefinitions(documentUri, source)) {
+            if (definition.name === targetName) {
+                return definition.location;
+            }
+        }
+    }
+    return null;
+}
+function findReferences(openDocuments, uri, line, includeDeclaration) {
+    const targetName = getSymbolAtLine(openDocuments.get(uri), line);
+    if (targetName === null) {
+        return [];
+    }
+    const locations = [];
+    for (const [documentUri, source] of openDocuments.entries()) {
+        if (includeDeclaration) {
+            for (const definition of collectDefinitions(documentUri, source)) {
+                if (definition.name === targetName) {
+                    locations.push(definition.location);
+                }
+            }
+        }
+        for (const reference of collectReferences(documentUri, source)) {
+            if (reference.name === targetName) {
+                locations.push(reference.location);
+            }
+        }
+    }
+    return locations;
+}
+function getSymbolAtLine(source, line) {
+    if (source === undefined) {
+        return null;
+    }
+    const node = (0, document_1.parseDocument)(source).lines[line]?.node;
+    if (node === undefined) {
+        return null;
+    }
+    if (node.shape === "labelOnly") {
+        return node.label;
+    }
+    if (node.shape === "instruction") {
+        if (node.label !== null) {
+            return node.label;
+        }
+        return readOperandIdentifier(node.operand);
+    }
+    if (node.shape === "directive") {
+        if (node.label !== null) {
+            return node.label;
+        }
+        return readExpressionIdentifier(node.operand);
+    }
+    if (node.shape === "equate") {
+        return node.label;
+    }
+    if (node.shape === "data" && node.label !== null) {
+        return node.label;
+    }
+    return null;
+}
+function collectDefinitions(uri, source) {
+    const document = (0, document_1.parseDocument)(source);
+    const definitions = [];
+    for (const line of document.lines) {
+        const name = getDefinedName(line.node);
+        if (name === null) {
+            continue;
+        }
+        definitions.push({
+            name,
+            location: createLocation(uri, line.line, name)
+        });
+    }
+    return definitions;
+}
+function collectReferences(uri, source) {
+    const document = (0, document_1.parseDocument)(source);
+    const references = [];
+    for (const line of document.lines) {
+        for (const name of getReferencedNames(line.node)) {
+            references.push({
+                name,
+                location: createLocation(uri, line.line, name)
+            });
+        }
+    }
+    return references;
+}
+function getDefinedName(node) {
+    if (node.shape === "equate") {
+        return node.label;
+    }
+    if (node.shape === "labelOnly") {
+        return node.label;
+    }
+    if (node.shape === "instruction" && node.label !== null) {
+        return node.label;
+    }
+    if (node.shape === "directive" && node.label !== null) {
+        return node.label;
+    }
+    if (node.shape === "data" && node.label !== null) {
+        return node.label;
+    }
+    return null;
+}
+function getReferencedNames(node) {
+    if (node.shape === "instruction" && node.operand !== null) {
+        return collectExpressionIdentifiers(node.operand.expression);
+    }
+    if (node.shape === "directive" && node.operand !== null) {
+        return collectExpressionIdentifiers(node.operand);
+    }
+    if (node.shape === "equate") {
+        return collectExpressionIdentifiers(node.expression);
+    }
+    return [];
+}
+function readOperandIdentifier(operand) {
+    if (operand === null) {
+        return null;
+    }
+    return readExpressionIdentifier(operand.expression);
+}
+function readExpressionIdentifier(expression) {
+    if (expression === null) {
+        return null;
+    }
+    if (expression.kind === "identifier") {
+        return expression.value;
+    }
+    if (expression.kind === "modifier") {
+        return readExpressionIdentifier(expression.expression);
+    }
+    if (expression.kind === "binary") {
+        return readExpressionIdentifier(expression.left);
+    }
+    return null;
+}
+function collectExpressionIdentifiers(expression) {
+    switch (expression.kind) {
+        case "identifier":
+            return [expression.value];
+        case "modifier":
+            return collectExpressionIdentifiers(expression.expression);
+        case "binary":
+            return [
+                ...collectExpressionIdentifiers(expression.left),
+                ...collectExpressionIdentifiers(expression.right)
+            ];
+        default:
+            return [];
+    }
+}
+function createLocation(uri, line, name) {
+    return {
+        uri,
+        range: {
+            start: {
+                line,
+                character: 0
+            },
+            end: {
+                line,
+                character: name.length
+            }
+        }
+    };
+}

package/dist/src/lsp/workspace-symbols.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildWorkspaceSymbols = buildWorkspaceSymbols;
+const document_symbols_1 = require("./document-symbols");
+function buildWorkspaceSymbols(openDocuments, query) {
+    const normalizedQuery = query.trim().toLowerCase();
+    const symbols = [];
+    for (const [uri, source] of openDocuments.entries()) {
+        for (const symbol of (0, document_symbols_1.buildDocumentSymbols)(uri, source)) {
+            if (normalizedQuery.length === 0 ||
+                symbol.name.toLowerCase().includes(normalizedQuery)) {
+                symbols.push(symbol);
+            }
+        }
+    }
+    return symbols;
+}

package/dist/src/server.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createServerConnection = createServerConnection;
+exports.startServer = startServer;
+const node_1 = require("vscode-languageserver/node");
+const document_symbols_1 = require("./lsp/document-symbols");
+const completion_1 = require("./lsp/completion");
+const diagnostics_1 = require("./lsp/diagnostics");
+const hover_1 = require("./lsp/hover");
+const symbol_navigation_1 = require("./lsp/symbol-navigation");
+const workspace_symbols_1 = require("./lsp/workspace-symbols");
+function createServerConnection(inputStream = process.stdin, outputStream = process.stdout) {
+    return (0, node_1.createConnection)(node_1.ProposedFeatures.all, inputStream, outputStream);
+}
+function startServer(inputStream = process.stdin, outputStream = process.stdout) {
+    const connection = createServerConnection(inputStream, outputStream);
+    const openDocuments = new Map();
+    connection.onInitialize(() => ({
+        capabilities: {
+            completionProvider: {},
+            definitionProvider: true,
+            documentSymbolProvider: true,
+            hoverProvider: true,
+            referencesProvider: true,
+            workspaceSymbolProvider: true,
+            textDocumentSync: {
+                openClose: true,
+                change: node_1.TextDocumentSyncKind.Full
+            }
+        }
+    }));
+    connection.onDidOpenTextDocument((params) => {
+        openDocuments.set(params.textDocument.uri, params.textDocument.text);
+        publishDiagnostics();
+    });
+    connection.onDidChangeTextDocument((params) => {
+        const nextText = params.contentChanges.at(-1)?.text;
+        if (nextText === undefined) {
+            return;
+        }
+        openDocuments.set(params.textDocument.uri, nextText);
+        publishDiagnostics();
+    });
+    connection.onDidCloseTextDocument((params) => {
+        openDocuments.delete(params.textDocument.uri);
+        connection.sendDiagnostics({
+            uri: params.textDocument.uri,
+            diagnostics: []
+        });
+        publishDiagnostics();
+    });
+    connection.onDocumentSymbol((params) => {
+        const source = openDocuments.get(params.textDocument.uri);
+        if (source === undefined) {
+            return [];
+        }
+        return (0, document_symbols_1.buildDocumentSymbols)(params.textDocument.uri, source);
+    });
+    connection.onWorkspaceSymbol((params) => (0, workspace_symbols_1.buildWorkspaceSymbols)(openDocuments, params.query));
+    connection.onDefinition((params) => (0, symbol_navigation_1.findDefinition)(openDocuments, params.textDocument.uri, params.position.line));
+    connection.onReferences((params) => (0, symbol_navigation_1.findReferences)(openDocuments, params.textDocument.uri, params.position.line, params.context.includeDeclaration));
+    connection.onHover((params) => (0, hover_1.buildHover)(openDocuments, params.textDocument.uri, params.position.line, params.position.character));
+    connection.onCompletion((params) => (0, completion_1.buildCompletionItems)(openDocuments, params.textDocument.uri, params.position.line));
+    function publishDiagnostics() {
+        for (const [uri, diagnostics] of (0, diagnostics_1.collectDiagnosticsByUri)(openDocuments).entries()) {
+            connection.sendDiagnostics({
+                uri,
+                diagnostics: [...diagnostics]
+            });
+        }
+    }
+    connection.listen();
+    return connection;
+}
+if (require.main === module) {
+    startServer();
+}

package/dist/test/bootstrap.test.js

@@ -0,0 +1,11 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runBootstrapTest = runBootstrapTest;
+const strict_1 = __importDefault(require("node:assert/strict"));
+const index_1 = require("../src/index");
+function runBootstrapTest() {
+    strict_1.default.equal(index_1.projectName, "merls");
+}