@markuplint/language-server 0.0.0-stage → 5.1.1

package/lib/server/server.js

@@ -0,0 +1,96 @@
+import { CodeActionKind, TextDocuments, TextDocumentSyncKind } from 'vscode-languageserver/node.js';
+import { TextDocument } from 'vscode-languageserver-textdocument';
+import { setLocale } from '../i18n.js';
+import { createClientChannel } from './client-channel.js';
+import { SOURCE_FIX_ALL_MARKUPLINT } from './code-actions.js';
+import { applySeverityMap } from './convert-diagnostics.js';
+import { verbosely } from './debug.js';
+import { createEventHandlers } from './document-events.js';
+import { createModuleResolver } from './get-module.js';
+import { resolveInitialization } from './initialize-params.js';
+import { createModuleNotices } from './module-notices.js';
+import { configureGitPath } from './suppression-support.js';
+const DEBUG = false;
+/**
+ * Bootstrap the LSP language server on a connection and start listening.
+ *
+ * Any LSP client can use the server, so nothing the client sends beyond the LSP itself is
+ * required: `initializationOptions` is optional (see {@link InitializationOptions}), and the
+ * `markuplint/*` custom messages are sent only to a client that opts in with `extendedProtocol`
+ * (see {@link createClientChannel}). Only the VS Code extension relies on both.
+ *
+ * The markuplint module is resolved lazily per working directory as documents open; the
+ * bundled-fallback notice is logged once per directory and the import assertion popup is shown
+ * once per session (see `createModuleNotices`).
+ *
+ * Diagnostics must not write to stdout: over `--stdio` it carries the protocol, and a client
+ * such as Claude Code disconnects the server on any other output. Logs go through the channel,
+ * and `debug` writes to stderr.
+ *
+ * @param connection - The connection to the client, from `createConnection`
+ */
+export function bootServer(connection) {
+    const channel = createClientChannel(connection);
+    const documents = new TextDocuments(TextDocument);
+    documents.listen(connection);
+    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+    let codeActionHandler = () => [];
+    connection.onCodeAction(params => codeActionHandler(params));
+    connection.onInitialize((params) => {
+        const { locale, options, workspaceFolders } = resolveInitialization(params);
+        channel.configure(options.extendedProtocol === true);
+        setLocale(locale);
+        const log = channel.log;
+        log('onInitialize');
+        const { langConfigs, workingDirectories, gitPath, severityMap } = options;
+        configureGitPath(gitPath);
+        const sendDiagnostics = ({ diagnostics, ...rest }) => {
+            void connection.sendDiagnostics({ ...rest, diagnostics: applySeverityMap(diagnostics, severityMap) });
+        };
+        connection.onInitialized(() => {
+            log('onInitialized');
+            if (DEBUG) {
+                verbosely();
+            }
+            log(`Locale: ${locale}`, 'info');
+            if (workingDirectories) {
+                log(`Working directories: ${JSON.stringify(workingDirectories)}`, 'info');
+            }
+            const notices = createModuleNotices({
+                log,
+                popup: channel.warningPopup,
+                sendStatus: channel.reportStatus,
+            });
+            const resolveModule = createModuleResolver({ log, onFirstResolve: notices.onFirstResolve });
+            const { onDidOpen, onDidChangeContent, onDidClose, onHover, onCodeAction } = createEventHandlers({
+                resolveModule,
+                locale,
+                langConfigs,
+                workingDirectories,
+                workspaceFolders,
+                log,
+                diagnosticsLog: channel.diagnosticsLog,
+                errorLog: channel.errorLog,
+                sendDiagnostics,
+                reportStatus: notices.reportStatus,
+            });
+            documents.onDidOpen(e => onDidOpen(e.document));
+            // eslint-disable-next-line unicorn/no-array-for-each
+            documents.all().forEach(onDidOpen);
+            documents.onDidChangeContent(e => onDidChangeContent(e.document));
+            documents.onDidClose(e => onDidClose(e.document));
+            connection.onHover(onHover);
+            codeActionHandler = onCodeAction;
+        });
+        return {
+            capabilities: {
+                textDocumentSync: TextDocumentSyncKind.Incremental,
+                hoverProvider: true,
+                codeActionProvider: {
+                    codeActionKinds: [CodeActionKind.QuickFix, SOURCE_FIX_ALL_MARKUPLINT],
+                },
+            },
+        };
+    });
+    connection.listen();
+}

package/lib/server/suppression-support.d.ts

@@ -0,0 +1,57 @@
+import type { Violation } from '@markuplint/ml-config';
+import type { SuppressionsData, DowngradedViolation } from 'markuplint/suppressions';
+import type { Log } from '../types.js';
+export type { DowngradedViolation } from 'markuplint/suppressions';
+/**
+ * @experimental
+ * Cached state for a workspace's suppression file.
+ */
+export type SuppressionCache = {
+    readonly data: SuppressionsData;
+    readonly filePath: string;
+    readonly lastCommitDate: Date | null;
+};
+/**
+ * @experimental
+ * Configures the git binary path for suppression support.
+ * Should be called once during server initialization.
+ *
+ * @param gitPath - Path to the git binary from the client's `gitPath` option
+ */
+export declare function configureGitPath(gitPath: string | undefined): void;
+/**
+ * @experimental
+ * Loads suppression data for a workspace, with TTL-based caching.
+ * Returns null if no suppressions file exists.
+ */
+export declare function loadSuppressions(workspace: string, log: Log): Promise<SuppressionCache | null>;
+/**
+ * @experimental
+ * Invalidates the suppression cache for a workspace.
+ * Should be called when the suppressions file changes.
+ */
+export declare function invalidateSuppressionCache(workspace: string): void;
+/**
+ * @experimental
+ * Applies suppression severity downgrade to violations.
+ *
+ * - If count <= suppressed count: all violations for that rule → info
+ * - If count > suppressed count: use git blame to distinguish old (→ info) vs new (→ original)
+ * - Falls back to original severity when git is unavailable
+ *
+ * The git blame date comparison uses the suppressions file's last commit date
+ * as the threshold. Lines authored before that date are considered "old"
+ * (existed when suppressions were generated) and downgraded to info.
+ * Lines authored after are considered "new" and keep their original severity.
+ */
+export declare function applySuppressionsToViolations(absoluteFilePath: string, violations: readonly Violation[], cache: SuppressionCache, log: Log): Promise<readonly DowngradedViolation[]>;
+/**
+ * @experimental
+ * Parses git blame porcelain output into a Map of line number → commit date.
+ *
+ * In porcelain format, the first occurrence of a commit SHA includes full
+ * header (author-time, etc.), but subsequent occurrences of the same SHA
+ * only include the abbreviated header (no author-time).
+ * We cache timestamps by SHA to handle repeated commits.
+ */
+export declare function parseBlamePorcelain(stdout: string): Map<number, Date>;

package/lib/server/suppression-support.js

@@ -0,0 +1,233 @@
+import { execFile } from 'node:child_process';
+import path from 'node:path';
+import { isFatalError, readSuppressionsFile, analyzeForDowngrade, applyDowngrade } from 'markuplint/suppressions';
+const suppressionCaches = new Map();
+/** Cache TTL in milliseconds. Re-reads the suppressions file after this period. */
+const CACHE_TTL_MS = 30_000;
+const DEFAULT_FILE_NAME = 'markuplint-suppressions.json';
+/**
+ * Path to the git binary. Resolved from the client's `gitPath` option,
+ * falling back to `'git'` (system PATH lookup).
+ */
+let gitBinaryPath = 'git';
+/**
+ * Tracks whether git is available in this environment.
+ * Once determined to be unavailable (ENOENT / EACCES), all git calls are skipped
+ * for the lifetime of the language server to avoid repeated child process failures.
+ */
+let gitAvailable;
+/**
+ * @experimental
+ * Configures the git binary path for suppression support.
+ * Should be called once during server initialization.
+ *
+ * @param gitPath - Path to the git binary from the client's `gitPath` option
+ */
+export function configureGitPath(gitPath) {
+    if (gitPath) {
+        gitBinaryPath = gitPath;
+    }
+}
+/**
+ * @experimental
+ * Resolves the suppressions file path for a workspace.
+ */
+function findSuppressionsFile(startDir) {
+    return path.resolve(startDir, DEFAULT_FILE_NAME);
+}
+/**
+ * @experimental
+ * Loads suppression data for a workspace, with TTL-based caching.
+ * Returns null if no suppressions file exists.
+ */
+export async function loadSuppressions(workspace, log) {
+    const filePath = findSuppressionsFile(workspace);
+    const cached = suppressionCaches.get(filePath);
+    if (cached && Date.now() < cached.expiresAt) {
+        return cached.cache;
+    }
+    const data = await readSuppressionsFile(filePath);
+    if (Object.keys(data).length === 0) {
+        suppressionCaches.delete(filePath);
+        return null;
+    }
+    const lastCommitDate = await getSuppressionsFileCommitDate(filePath, log);
+    const cache = { data, filePath, lastCommitDate };
+    suppressionCaches.set(filePath, { cache, expiresAt: Date.now() + CACHE_TTL_MS });
+    log(`Loaded suppressions from ${filePath} (committed: ${lastCommitDate?.toISOString() ?? 'uncommitted'})`, 'debug');
+    return cache;
+}
+/**
+ * @experimental
+ * Invalidates the suppression cache for a workspace.
+ * Should be called when the suppressions file changes.
+ */
+export function invalidateSuppressionCache(workspace) {
+    const filePath = findSuppressionsFile(workspace);
+    suppressionCaches.delete(filePath);
+}
+/**
+ * @experimental
+ * Gets the last commit date of the suppressions file via `git log`.
+ * Returns null if the file is not tracked or git is unavailable.
+ */
+async function getSuppressionsFileCommitDate(filePath, log) {
+    if (gitAvailable === false) {
+        return null;
+    }
+    try {
+        const stdout = await execGit(['log', '-1', '--format=%aI', '--', path.basename(filePath)], path.dirname(filePath));
+        gitAvailable = true;
+        const dateStr = stdout.trim();
+        if (!dateStr) {
+            return null;
+        }
+        return new Date(dateStr);
+    }
+    catch (error) {
+        if (isFatalError(error)) {
+            throw error;
+        }
+        if (isGitUnavailableError(error)) {
+            gitAvailable = false;
+            log('git is not available; git blame features will be disabled', 'warn');
+        }
+        else {
+            log('git log for suppressions file failed; git blame will be disabled', 'debug');
+        }
+        return null;
+    }
+}
+/**
+ * @experimental
+ * Gets blame dates for specific lines in a file.
+ * Returns a Map of line number → commit date.
+ */
+async function getBlameForLines(filePath, lines, log) {
+    const result = new Map();
+    if (lines.length === 0 || gitAvailable === false) {
+        return result;
+    }
+    try {
+        const args = ['blame', '--porcelain'];
+        for (const line of lines) {
+            args.push('-L', `${line},${line}`);
+        }
+        args.push('--', filePath);
+        const stdout = await execGit(args, path.dirname(filePath));
+        return parseBlamePorcelain(stdout);
+    }
+    catch (error) {
+        if (isFatalError(error)) {
+            throw error;
+        }
+        if (isGitUnavailableError(error)) {
+            gitAvailable = false;
+            log('git is not available; git blame features will be disabled', 'warn');
+        }
+        else {
+            log(`git blame failed for ${filePath}; treating all violations as old`, 'debug');
+        }
+    }
+    return result;
+}
+/**
+ * @experimental
+ * Applies suppression severity downgrade to violations.
+ *
+ * - If count <= suppressed count: all violations for that rule → info
+ * - If count > suppressed count: use git blame to distinguish old (→ info) vs new (→ original)
+ * - Falls back to original severity when git is unavailable
+ *
+ * The git blame date comparison uses the suppressions file's last commit date
+ * as the threshold. Lines authored before that date are considered "old"
+ * (existed when suppressions were generated) and downgraded to info.
+ * Lines authored after are considered "new" and keep their original severity.
+ */
+export async function applySuppressionsToViolations(absoluteFilePath, violations, 
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+cache, log) {
+    const { withinThreshold, exceedingThreshold } = analyzeForDowngrade(absoluteFilePath, violations, cache.data, cache.filePath);
+    // Collect all indices to downgrade
+    const downgradeIndices = new Set(withinThreshold);
+    // For exceeding threshold rules, use git blame if available
+    if (exceedingThreshold.size > 0 && cache.lastCommitDate) {
+        const uniqueLines = new Set();
+        for (const indices of exceedingThreshold.values()) {
+            for (const idx of indices) {
+                uniqueLines.add(violations[idx].line);
+            }
+        }
+        const blameDates = await getBlameForLines(absoluteFilePath, [...uniqueLines], log);
+        for (const indices of exceedingThreshold.values()) {
+            for (const idx of indices) {
+                const violation = violations[idx];
+                const blameDate = blameDates.get(violation.line);
+                if (blameDate && blameDate <= cache.lastCommitDate) {
+                    downgradeIndices.add(idx);
+                }
+            }
+        }
+    }
+    return applyDowngrade(violations, downgradeIndices);
+}
+/**
+ * @experimental
+ * Parses git blame porcelain output into a Map of line number → commit date.
+ *
+ * In porcelain format, the first occurrence of a commit SHA includes full
+ * header (author-time, etc.), but subsequent occurrences of the same SHA
+ * only include the abbreviated header (no author-time).
+ * We cache timestamps by SHA to handle repeated commits.
+ */
+export function parseBlamePorcelain(stdout) {
+    const result = new Map();
+    const commitTimestamps = new Map();
+    const shaLinePattern = /^([0-9a-f]{40}) \d+ (\d+)/gm;
+    const authorTimePattern = /^author-time (\d+)$/gm;
+    let shaMatch;
+    while ((shaMatch = shaLinePattern.exec(stdout)) !== null) {
+        const sha = shaMatch[1];
+        const lineNo = Number.parseInt(shaMatch[2], 10);
+        if (!commitTimestamps.has(sha)) {
+            authorTimePattern.lastIndex = shaMatch.index;
+            const timeMatch = authorTimePattern.exec(stdout);
+            if (timeMatch) {
+                const timestamp = Number.parseInt(timeMatch[1], 10);
+                commitTimestamps.set(sha, new Date(timestamp * 1000));
+            }
+        }
+        const date = commitTimestamps.get(sha);
+        if (date) {
+            result.set(lineNo, date);
+        }
+    }
+    return result;
+}
+/** Timeout for git commands (log, blame) in milliseconds. */
+const GIT_TIMEOUT_MS = 5000;
+/**
+ * Executes a git command and returns stdout.
+ */
+function execGit(args, cwd) {
+    return new Promise((resolve, reject) => {
+        execFile(gitBinaryPath, args, { cwd, timeout: GIT_TIMEOUT_MS }, (error, stdout) => {
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve(stdout);
+        });
+    });
+}
+/**
+ * Checks if an error indicates git is not available (not installed or permission denied).
+ * Used to permanently disable git features after the first failure.
+ */
+function isGitUnavailableError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    const code = error.code;
+    return code === 'ENOENT' || code === 'EACCES';
+}

package/lib/server/v2.d.ts

@@ -0,0 +1,12 @@
+import type { SendDiagnostics } from './document-events.js';
+import type { Config, Log } from '../types.js';
+import type { MLEngine as _MLEngine } from 'markuplint';
+import type { TextDocument } from 'vscode-languageserver-textdocument';
+export declare function onDidOpen(document: TextDocument, MLEngine: typeof _MLEngine, config: Config, locale: string, sendDiagnostics: SendDiagnostics, notFoundParserError: (e: unknown) => void, workspace: string, log?: Log): Promise<void>;
+export declare function onDidChangeContent(document: TextDocument, notFoundParserError: (e: unknown) => void): void;
+/**
+ * Handles the `textDocument/didClose` event by releasing the engine of the document.
+ *
+ * @param uri - The URI of the closed document
+ */
+export declare function onDidClose(uri: string): Promise<void>;

package/lib/server/v2.js

@@ -0,0 +1,109 @@
+import path from 'node:path';
+import { getFilePath } from '../utils/get-file-path.js';
+import { convertDiagnostics } from './convert-diagnostics.js';
+const engines = new Map();
+export async function onDidOpen(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+document, 
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+MLEngine, 
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+config, locale, sendDiagnostics, notFoundParserError, workspace, log) {
+    const key = document.uri;
+    console.log(`Opened: ${key}`);
+    const currentEngine = engines.get(key);
+    if (currentEngine) {
+        return;
+    }
+    const filePath = getFilePath(document.uri, document.languageId);
+    if (config.debug) {
+        console.log(filePath);
+    }
+    const absoluteFilePath = `${filePath.dirname}/${filePath.basename}`;
+    const sourceCode = document.getText();
+    // `name` must be the workspace-relative path (not just the basename), or
+    // MLFile.path collapses subdirectory files to workspace-root + basename —
+    // which breaks pretender import resolution, nested config discovery, and
+    // excludeFiles/overrides glob matching for anything outside the workspace root.
+    const relativeFilePath = path.relative(workspace, absoluteFilePath);
+    const file = await MLEngine.toMLFile({ sourceCode, name: relativeFilePath, workspace });
+    if (!file) {
+        console.warn(`File not found: ${filePath.basename}`);
+        return;
+    }
+    const engine = new MLEngine(file, {
+        locale,
+        debug: config.debug,
+        defaultConfig: config.defaultConfig,
+        watch: true,
+    });
+    engines.set(key, engine);
+    engine.on('config', (filePath, configSet) => {
+        if (config.debug) {
+            console.log(`get config: ${filePath}`, configSet);
+        }
+    });
+    engine.on('log', (phase, message) => {
+        if (config.debug) {
+            console.log(phase, message);
+        }
+    });
+    engine.on('lint-error', (_filePath, _sourceCode, error) => {
+        if (config.debug) {
+            console.log('❌', { error });
+        }
+    });
+    engine.on('lint', (filePath, sourceCode, violations, fixedCode, debug) => {
+        if (config.debug && debug) {
+            console.log(debug.join('\n'));
+        }
+        const date = new Date().toLocaleDateString();
+        const time = new Date().toLocaleTimeString();
+        console.log(`Linted(${date} ${time}): ${document.uri}`);
+        const diagnostics = convertDiagnostics({ filePath, sourceCode, violations, fixedCode, status: 'processed' });
+        sendDiagnostics({
+            uri: document.uri,
+            diagnostics,
+        });
+        console.log(`diagnostics: ${diagnostics.length}`);
+    });
+    console.log('exec (onDidOpen)');
+    engine.exec().catch((error) => notFoundParserError(error));
+}
+let debounceTimer;
+export function onDidChangeContent(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+document, notFoundParserError) {
+    clearTimeout(debounceTimer);
+    const key = document.uri;
+    const engine = engines.get(key);
+    debounceTimer = setTimeout(async () => {
+        // The document may have been closed within the debounce delay.
+        if (!engine || engines.get(key) !== engine) {
+            return;
+        }
+        const code = document.getText();
+        try {
+            await engine.setCode(code);
+            console.log('exec (onDidChangeContent)');
+            engine.exec().catch((error) => notFoundParserError(error));
+        }
+        catch (error) {
+            console.log(error);
+            // continue;
+        }
+    }, 300);
+}
+/**
+ * Handles the `textDocument/didClose` event by releasing the engine of the document.
+ *
+ * @param uri - The URI of the closed document
+ */
+export async function onDidClose(uri) {
+    const engine = engines.get(uri);
+    if (!engine) {
+        return;
+    }
+    engines.delete(uri);
+    await engine.close();
+}

package/lib/server/v3.d.ts

@@ -0,0 +1,19 @@
+import type { SendDiagnostics } from './document-events.js';
+import type { Config, Log } from '../types.js';
+import type { ARIAVersion } from '@markuplint/ml-spec';
+import type { MLEngine as _MLEngine } from 'markuplint';
+import type { Position, TextDocumentIdentifier } from 'vscode-languageserver';
+import type { TextDocument } from 'vscode-languageserver-textdocument';
+export declare function onDidOpen(document: TextDocument, MLEngine: typeof _MLEngine, config: Config, locale: string, log: Log, diagnosticsLog: Log, sendDiagnostics: SendDiagnostics, notFoundParserError: (e: unknown) => void, workspace: string): Promise<void>;
+export declare function onDidChangeContent(document: TextDocument, log: Log, notFoundParserError: (e: unknown) => void): void;
+/**
+ * Handles the `textDocument/didClose` event by releasing the engine of the document.
+ *
+ * @param uri - The URI of the closed document
+ */
+export declare function onDidClose(uri: string): Promise<void>;
+export declare function getNodeWithAccessibilityProps(textDocument: TextDocumentIdentifier, position: Position, ariaVersion: ARIAVersion): {
+    nodeName: string;
+    exposed: boolean;
+    aria: Record<string, string>;
+} | null;