@markuplint/language-server 0.0.0-stage → 5.1.1

package/lib/server/v5.js

@@ -0,0 +1,339 @@
+import path from 'node:path';
+import { isFatalError } from 'markuplint/suppressions';
+import { t } from '../i18n.js';
+import { getFilePath } from '../utils/get-file-path.js';
+import { createQuickFixActions, createFixAllAction } from './code-actions.js';
+import { convertDiagnostics } from './convert-diagnostics.js';
+import { getAccessibilityByLocation } from './get-accessibility-by-location.js';
+import { applySuppressionsToViolations, loadSuppressions } from './suppression-support.js';
+const engines = new Map();
+const fixStates = new Map();
+let moduleLog;
+/**
+ * Returns the latest fix state for a document.
+ *
+ * @param uri - The document URI
+ * @returns The fix state, or `undefined` if the document has not been linted yet
+ */
+export function getFixState(uri) {
+    return fixStates.get(uri);
+}
+/**
+ * Handles the `textDocument/didOpen` event by creating an MLEngine for the document.
+ *
+ * Sets up linting, diagnostics, fix-state tracking, and bulk suppression
+ * severity downgrade for the opened document.
+ *
+ * @param document - The opened text document
+ * @param MLEngine - The MLEngine constructor
+ * @param config - The language configuration
+ * @param locale - The locale for diagnostic messages
+ * @param log - Logger for general messages
+ * @param diagnosticsLog - Logger for diagnostic-specific messages
+ * @param sendDiagnostics - Callback to publish diagnostics to the client
+ * @param notFoundParserError - Callback invoked when a parser is not found
+ * @param workspace - The working directory the document belongs to; the base for config discovery
+ */
+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, log, diagnosticsLog, sendDiagnostics, notFoundParserError, workspace) {
+    moduleLog = log;
+    const key = document.uri;
+    log(`Opened: ${key}`, 'debug');
+    const currentEngine = engines.get(key);
+    if (currentEngine) {
+        return;
+    }
+    const filePath = getFilePath(document.uri, document.languageId);
+    log(`${filePath.dirname}/${filePath.basename}`, 'debug');
+    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) {
+        log(`File not found: ${filePath.basename}`, 'warn');
+        return;
+    }
+    const engine = new MLEngine(file, {
+        locale,
+        debug: config.debug,
+        defaultConfig: config.defaultConfig,
+        watch: true,
+        fix: true,
+    });
+    log(`Engine created: ${key}`);
+    let configSet = null;
+    engines.set(key, engine);
+    engine.on('config', (_, _configSet) => {
+        configSet = _configSet;
+    });
+    engine.on('log', (phase, message) => {
+        log(`[${phase}]: ${message}`, 'trace');
+    });
+    engine.on('lint-error', (_filePath, _sourceCode, error) => {
+        diagnosticsLog(error.message, 'error');
+    });
+    engine.on('config-errors', (_filePath, errors) => {
+        for (const error of errors) {
+            diagnosticsLog('ConfigError: ' + error.message, 'error');
+            log('ConfigError: ' + error.message, 'warn');
+        }
+    });
+    engine.on('lint', (lintFilePath, lintSourceCode, violations, fixedCode, debug, fixSummary) => {
+        clearTimeout(debounceTimers.get(key));
+        diagnosticsLog('', 'clear');
+        // Execute after 300ms from the last change.
+        debounceTimers.set(key, setTimeout(() => {
+            lint().catch((error) => {
+                log(String(error), 'error');
+            });
+        }, 300));
+        async function lint() {
+            diagnosticsLog(`Lint: ${document.uri}`);
+            // Apply bulk suppression severity downgrade and prefix suppressed messages
+            const suppressedPrefix = t('[suppressed] this warning is suppressed but should be fixed:');
+            const downgraded = await applyBulkSuppressions(absoluteFilePath, violations, workspace, log);
+            // The document may have been closed while the suppressions were loading; publishing
+            // now would resurrect the diagnostics `onDidClose` cleared and re-add the fix state.
+            if (engines.get(key) !== engine) {
+                return;
+            }
+            const effectiveViolations = downgraded.map(v => 'originalSeverity' in v && v.originalSeverity
+                ? { ...v, message: `${suppressedPrefix} ${v.message}` }
+                : v);
+            const errors = effectiveViolations.filter(v => v.severity === 'error');
+            const warns = effectiveViolations.filter(v => v.severity === 'warning');
+            const suppressed = effectiveViolations.filter(v => v.severity === 'info');
+            log(`Errors: ${errors.length}`, 'debug');
+            log(`Warnings: ${warns.length}`, 'debug');
+            if (suppressed.length > 0) {
+                log(`Suppressed (info): ${suppressed.length}`, 'debug');
+            }
+            if (debug) {
+                diagnosticsLog('  Tracing AST Mapping:\n' + debug.map(line => `  ${line}`).join('\n'), 'trace');
+            }
+            if (configSet) {
+                if (configSet.files.size > 0) {
+                    diagnosticsLog('  Used configs:');
+                    for (const files of configSet.files.values()) {
+                        diagnosticsLog(`    ${files}`);
+                    }
+                }
+                else {
+                    diagnosticsLog('  No use configs');
+                }
+                if (configSet.plugins.length > 0) {
+                    diagnosticsLog('  Used plugins:');
+                    for (const plugin of configSet.plugins.values()) {
+                        diagnosticsLog(`    ${plugin.name}`);
+                    }
+                }
+                else {
+                    diagnosticsLog('  No use plugins');
+                }
+            }
+            const diagnostics = convertDiagnostics({
+                filePath: lintFilePath,
+                sourceCode: lintSourceCode,
+                violations: effectiveViolations,
+                fixedCode,
+                status: 'processed',
+            });
+            fixStates.set(key, {
+                sourceCode: lintSourceCode,
+                violations: effectiveViolations,
+                fixedCode,
+                fixSummary,
+            });
+            if (diagnostics.length > 0) {
+                diagnosticsLog(`  Violations(${diagnostics.length}):`);
+                for (const d of diagnostics) {
+                    diagnosticsLog(`    [${d.line}:${d.col}] ${d.code}`);
+                }
+            }
+            else {
+                diagnosticsLog('  ✔ No violations');
+            }
+            sendDiagnostics({
+                uri: document.uri,
+                diagnostics,
+            });
+        }
+    });
+    log('Run `engine.exec()` in `onDidOpen`', 'debug');
+    engine.exec().catch((error) => {
+        log(String(error), 'error');
+        notFoundParserError(error);
+        throw error;
+    });
+}
+const debounceTimers = new Map();
+/**
+ * Handles the `textDocument/didChangeContent` event by re-running the lint engine.
+ *
+ * Debounces execution so that rapid successive changes do not trigger
+ * multiple lint passes.
+ *
+ * @param document - The changed text document
+ * @param log - Logger for messages
+ * @param notFoundParserError - Callback invoked when a parser is not found
+ */
+export function onDidChangeContent(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+document, log, notFoundParserError) {
+    const key = document.uri;
+    clearTimeout(debounceTimers.get(key));
+    const engine = engines.get(key);
+    debounceTimers.set(key, setTimeout(async () => {
+        if (!engine) {
+            return;
+        }
+        const code = document.getText();
+        try {
+            await engine.setCode(code);
+            log('Run `engine.exec()` in `onDidChangeContent`', 'debug');
+            engine.exec().catch((error) => notFoundParserError(error));
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                log(error.message, 'error');
+                return;
+            }
+            log(`UnknownError: ${error}`, 'error');
+        }
+    }, 300));
+}
+/**
+ * Handles the `textDocument/didClose` event by releasing everything kept for the document.
+ *
+ * Without it every document opened during a session would keep its engine, its DOM and
+ * its config watcher (`watch: true`) until the server exits.
+ *
+ * @param uri - The URI of the closed document
+ */
+export async function onDidClose(uri) {
+    clearTimeout(debounceTimers.get(uri));
+    debounceTimers.delete(uri);
+    fixStates.delete(uri);
+    const engine = engines.get(uri);
+    if (!engine) {
+        return;
+    }
+    engines.delete(uri);
+    await engine.close();
+}
+/**
+ * Retrieves the ARIA accessibility properties of the element at the given position.
+ *
+ * Used by the hover provider to display accessibility information such as
+ * role, exposed state, and ARIA property labels.
+ *
+ * @param textDocument - The text document identifier
+ * @param position - The cursor position within the document
+ * @param ariaVersion - The ARIA specification version to use
+ * @returns The node's accessibility properties, or null if unavailable
+ */
+export async function getNodeWithAccessibilityProps(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+textDocument, 
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+position, ariaVersion) {
+    const key = textDocument.uri;
+    const engine = engines.get(key);
+    if (!engine) {
+        return null;
+    }
+    const a11y = await getAccessibilityByLocation(engine, position.line + 1, position.character, ariaVersion);
+    if (!a11y) {
+        return null;
+    }
+    const { node, aria } = a11y;
+    if (!aria) {
+        return null;
+    }
+    if (aria.unknown) {
+        return {
+            nodeName: node,
+            unknown: true,
+        };
+    }
+    if (!aria.exposedToTree) {
+        return {
+            nodeName: node,
+            exposed: false,
+            labels: {},
+        };
+    }
+    const labels = {};
+    const requiredLabel = `\u26A0\uFE0F**${t('Required')}**`;
+    labels.role = aria.role ? `\`${aria.role}\`` : t('No corresponding role');
+    labels.name = aria.nameProhibited
+        ? `**${t('Prohibited')}**`
+        : // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
+            aria.name
+                ? typeof aria.name === 'string'
+                    ? `\`"${aria.name}"\``
+                    : `**${t('Unknown')}**`
+                : `${t('None')}${aria.nameRequired ? ` ${requiredLabel}` : ''}`;
+    labels.focusable = `\`${aria.focusable}\``;
+    for (const [propName, { value, required }] of Object.entries(aria.props ?? {})) {
+        labels[propName] =
+            value === undefined ? t('Undefined') + (required ? ` ${requiredLabel}` : '') : `\`${value}\``;
+    }
+    return {
+        nodeName: node,
+        exposed: true,
+        labels,
+    };
+}
+/**
+ * Handles `textDocument/codeAction` requests for markuplint v5.
+ *
+ * Returns per-violation QuickFix actions and a SourceFixAll action
+ * (`source.fixAll.markuplint`) when fixable violations exist.
+ *
+ * @param params - The LSP Code Action request parameters
+ * @returns An array of Code Actions (QuickFix and/or SourceFixAll)
+ */
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+export function onCodeAction(params) {
+    const uri = params.textDocument.uri;
+    const fixState = getFixState(uri);
+    if (!fixState) {
+        moduleLog?.(`onCodeAction: no fixState for ${uri}`, 'debug');
+        return [];
+    }
+    const fixableCount = fixState.violations.filter(v => v.fix).length;
+    moduleLog?.(`onCodeAction: ${fixState.violations.length} violations (${fixableCount} fixable), ${params.context.diagnostics.length} diagnostics`, 'debug');
+    const quickFixes = createQuickFixActions(uri, params.context.diagnostics, fixState);
+    const fixAll = createFixAllAction(uri, params.context.diagnostics, fixState);
+    return fixAll ? [...quickFixes, fixAll] : quickFixes;
+}
+/**
+ * Applies bulk suppression to violations, downgrading severity to 'info'
+ * for suppressed violations. Uses git blame for count-exceeded cases.
+ */
+async function applyBulkSuppressions(absoluteFilePath, violations, workspace, log) {
+    try {
+        const cache = await loadSuppressions(workspace, log);
+        if (!cache) {
+            return violations;
+        }
+        return await applySuppressionsToViolations(absoluteFilePath, violations, cache, log);
+    }
+    catch (error) {
+        if (isFatalError(error)) {
+            throw error;
+        }
+        log(`Bulk suppression failed: ${error instanceof Error ? error.message : String(error)}`, 'warn');
+        return violations;
+    }
+}

package/lib/types.d.ts

@@ -0,0 +1,88 @@
+import type { Config as MLConfig } from '@markuplint/ml-config';
+import type { ARIAVersion } from '@markuplint/ml-spec';
+import type { WorkingDirectoryEntry } from './utils/resolve-working-directory.js';
+/**
+ * Per-language configuration sent by clients that manage settings themselves (the VS Code extension).
+ */
+export type Config = {
+    enable: boolean;
+    debug: boolean;
+    /**
+     * Applied only when no config file is found. Left out, markuplint falls back to
+     * `markuplint:recommended`, exactly as the CLI does.
+     */
+    defaultConfig?: MLConfig;
+    hover: {
+        accessibility: {
+            enable: boolean;
+            ariaVersion?: ARIAVersion;
+        };
+    };
+};
+/**
+ * Status information sent from the language server to the client for the status bar.
+ */
+export type Status = {
+    readonly version: string;
+    readonly isLocalModule: boolean;
+    readonly message: string | null;
+};
+/**
+ * A map of language IDs to their markuplint configuration.
+ */
+export type LangConfigs = Record<string, Config>;
+/**
+ * The severities a diagnostic can be reported with.
+ */
+export type ReportedSeverity = 'error' | 'warning' | 'info' | 'hint';
+/**
+ * Maps the severity markuplint assigns to a violation onto the severity reported to the client.
+ * Severities missing from the map are reported unchanged.
+ */
+export type SeverityMap = Partial<Record<'error' | 'warning' | 'info', ReportedSeverity>>;
+/**
+ * Options a client may pass in `initializationOptions`. Every field is optional so that
+ * clients which know nothing about markuplint (Claude Code, OpenCode, Neovim) can start the
+ * server without configuring it.
+ */
+export type InitializationOptions = {
+    /**
+     * Per-language configuration. When present, only languages listed here with `enable: true`
+     * are linted. When absent, every document the client opens is linted.
+     */
+    readonly langConfigs?: LangConfigs;
+    /** User-configured working directories for monorepo support */
+    readonly workingDirectories?: readonly WorkingDirectoryEntry[];
+    /**
+     * Absolute paths of the workspace folders. Falls back to the LSP-standard
+     * `workspaceFolders` and `rootUri` of the `initialize` request.
+     */
+    readonly workspaceFolders?: readonly string[];
+    /**
+     * Path to the git binary. Falls back to `'git'` (PATH lookup) when unset.
+     */
+    readonly gitPath?: string;
+    /**
+     * Opts in to the `markuplint/*` custom requests and notifications (status bar, output
+     * channels, popups). Clients that do not set it receive `window/logMessage` and
+     * `window/showMessage` instead, which every LSP client understands.
+     */
+    readonly extendedProtocol?: boolean;
+    /**
+     * Re-reports diagnostics with another severity, for clients that surface only some
+     * severities to their user (OpenCode hands only errors to the model).
+     */
+    readonly severityMap?: SeverityMap;
+};
+/**
+ * A logging function that writes to an output channel.
+ */
+export type Log = (...args: LogArg) => void;
+/**
+ * Log severity levels for the output channels.
+ */
+export type LogType = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'clear';
+/**
+ * Arguments for a log call: a message string and an optional log type.
+ */
+export type LogArg = readonly [message: string, type?: LogType];

package/lib/types.js

@@ -0,0 +1 @@
+export {};

package/lib/utils/get-file-path.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Extracts a directory name and base file name from a document URI.
+ *
+ * Handles `file:` and `untitled:` URI schemes. For untitled documents,
+ * appends the language ID as a file extension so markuplint can detect
+ * the correct parser.
+ *
+ * @param uri - The document URI (e.g. `"file:///path/to/file.html"`)
+ * @param langId - The language identifier (e.g. `"html"`, `"vue"`)
+ * @returns An object with `dirname` (absolute directory path) and `basename` (file name)
+ */
+export declare function getFilePath(uri: string, langId: string): {
+    dirname: string;
+    basename: string;
+};

package/lib/utils/get-file-path.js

@@ -0,0 +1,45 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Extracts a directory name and base file name from a document URI.
+ *
+ * Handles `file:` and `untitled:` URI schemes. For untitled documents,
+ * appends the language ID as a file extension so markuplint can detect
+ * the correct parser.
+ *
+ * @param uri - The document URI (e.g. `"file:///path/to/file.html"`)
+ * @param langId - The language identifier (e.g. `"html"`, `"vue"`)
+ * @returns An object with `dirname` (absolute directory path) and `basename` (file name)
+ */
+export function getFilePath(uri, langId) {
+    if (/^untitled:/i.test(uri)) {
+        const name = uri.replace(/^untitled:/i, '');
+        const basename = `${name}.${langId}`;
+        return {
+            dirname: path.resolve(),
+            basename,
+        };
+    }
+    const decodePath = fileURLToPath(decodeURIComponent(uri));
+    let filePath;
+    let untitled = false;
+    if (decodePath.startsWith('file:')) {
+        filePath = decodePath.replace(/^file:\/+/i, '/');
+    }
+    else if (decodePath.startsWith('untitled:')) {
+        filePath = decodePath.replace(/^untitled:/i, '');
+        untitled = true;
+    }
+    else {
+        filePath = decodePath;
+    }
+    const dirname = path.resolve(path.dirname(filePath));
+    let basename = path.basename(filePath);
+    if (untitled) {
+        basename += `.${langId}`;
+    }
+    return {
+        dirname,
+        basename,
+    };
+}

package/lib/utils/resolve-working-directory.d.ts

@@ -0,0 +1,44 @@
+/**
+ * A working directory entry configuration, modeled after the ESLint VS Code extension.
+ *
+ * Supports:
+ * - Plain string: a directory path relative to the workspace folder
+ * - `{ directory, "!cwd"? }`: explicit directory with optional process.cwd control
+ * - `{ pattern, "!cwd"? }`: glob pattern for dynamic directory detection
+ * - `{ mode: "auto" | "location" }`: automatic working directory detection
+ */
+export type WorkingDirectoryEntry = string | {
+    readonly directory: string;
+    readonly '!cwd'?: boolean;
+} | {
+    readonly pattern: string;
+    readonly '!cwd'?: boolean;
+} | {
+    readonly mode: 'auto' | 'location';
+};
+/**
+ * The result of resolving a working directory for a file.
+ */
+export type ResolvedWorkingDirectory = {
+    /** The resolved working directory path */
+    readonly directory: string;
+};
+/**
+ * Converts a simple glob pattern (supporting `*` and `**`) into a RegExp.
+ *
+ * This is a simplified implementation for matching directory paths against
+ * patterns like `./packages/* /` or `./apps/** /`.
+ *
+ * @param pattern - A glob pattern string (e.g. `"./packages/* /"`)
+ * @returns A RegExp anchored at the start that matches directory paths
+ */
+export declare function convertGlobToRegex(pattern: string): RegExp;
+/**
+ * Resolves the working directory for a given file based on workingDirectories configuration.
+ *
+ * @param filePath - Absolute file path of the document being linted
+ * @param workspaceFolders - Workspace folder paths (absolute)
+ * @param workingDirectories - The user-configured working directories
+ * @returns The resolved working directory, or `undefined` to use the default behavior
+ */
+export declare function resolveWorkingDirectory(filePath: string, workspaceFolders: readonly string[], workingDirectories?: readonly WorkingDirectoryEntry[]): ResolvedWorkingDirectory | undefined;