@markuplint/language-server 0.0.0-stage → 5.1.0

package/lib/server/convert-diagnostics.d.ts

@@ -0,0 +1,28 @@
+import type { MLResultInfo } from 'markuplint';
+import type { SeverityMap } from '../types.js';
+import type { Diagnostic } from 'vscode-languageserver/node.js';
+/**
+ * Re-reports diagnostics with the severities a client asked for.
+ *
+ * Runs on the LSP severity rather than on the markuplint one, so one place covers the v2–v5
+ * handlers. `convertDiagnostics` maps the two one to one, which makes the keys of the map
+ * mean the same on both sides.
+ *
+ * @param diagnostics - The diagnostics to re-report
+ * @param map - The client's `severityMap`; severities it does not list are kept
+ * @returns New diagnostics. The input is not modified.
+ */
+export declare function applySeverityMap<T extends Diagnostic>(diagnostics: readonly T[], map: SeverityMap | undefined): T[];
+/**
+ * Converts markuplint violations into LSP diagnostics.
+ *
+ * Each diagnostic includes a `data.violationIndex` property that maps back
+ * to the original violation for use in Code Action resolution.
+ *
+ * @param result - The markuplint lint result, or null if no result is available
+ * @returns An array of LSP diagnostics augmented with line and col numbers
+ */
+export declare function convertDiagnostics(result: MLResultInfo | null): (Diagnostic & {
+    line: number;
+    col: number;
+})[];

package/lib/server/convert-diagnostics.js

@@ -0,0 +1,82 @@
+import { DiagnosticSeverity } from 'vscode-languageserver/node.js';
+import { NAME, WEBSITE_URL_RULE_PAGE } from '../const.js';
+const REPORTED = {
+    error: DiagnosticSeverity.Error,
+    warning: DiagnosticSeverity.Warning,
+    info: DiagnosticSeverity.Information,
+    hint: DiagnosticSeverity.Hint,
+};
+/**
+ * Re-reports diagnostics with the severities a client asked for.
+ *
+ * Runs on the LSP severity rather than on the markuplint one, so one place covers the v2–v5
+ * handlers. `convertDiagnostics` maps the two one to one, which makes the keys of the map
+ * mean the same on both sides.
+ *
+ * @param diagnostics - The diagnostics to re-report
+ * @param map - The client's `severityMap`; severities it does not list are kept
+ * @returns New diagnostics. The input is not modified.
+ */
+export function applySeverityMap(diagnostics, map) {
+    if (!map) {
+        return [...diagnostics];
+    }
+    return diagnostics.map(diagnostic => {
+        const from = diagnostic.severity === DiagnosticSeverity.Error
+            ? 'error'
+            : diagnostic.severity === DiagnosticSeverity.Warning
+                ? 'warning'
+                : diagnostic.severity === DiagnosticSeverity.Information
+                    ? 'info'
+                    : undefined;
+        const to = from && map[from];
+        return to ? { ...diagnostic, severity: REPORTED[to] } : diagnostic;
+    });
+}
+/**
+ * Converts markuplint violations into LSP diagnostics.
+ *
+ * Each diagnostic includes a `data.violationIndex` property that maps back
+ * to the original violation for use in Code Action resolution.
+ *
+ * @param result - The markuplint lint result, or null if no result is available
+ * @returns An array of LSP diagnostics augmented with line and col numbers
+ */
+export function convertDiagnostics(result) {
+    const diagnostics = [];
+    if (!result) {
+        return diagnostics;
+    }
+    for (const [i, violation] of result.violations.entries()) {
+        diagnostics.push({
+            severity: violation.severity === 'error'
+                ? DiagnosticSeverity.Error
+                : violation.severity === 'warning'
+                    ? DiagnosticSeverity.Warning
+                    : DiagnosticSeverity.Information,
+            line: violation.line,
+            col: violation.col,
+            range: {
+                start: {
+                    line: Math.max(violation.line - 1, 0),
+                    character: Math.max(violation.col - 1, 0),
+                },
+                end: {
+                    line: Math.max(violation.line - 1, 0),
+                    character: Math.max(violation.col + violation.raw.length - 1, 0),
+                },
+            },
+            message: violation.message +
+                (violation.specConformance ? ` [${violation.specConformance}]` : '') +
+                (violation.reason ? ' / ' + violation.reason : '') +
+                (violation.name ? ` (${violation.ruleId})` : ''),
+            source: NAME,
+            code: violation.name ?? violation.ruleId,
+            codeDescription: {
+                href: `${WEBSITE_URL_RULE_PAGE}${violation.ruleId}`,
+            },
+            data: { violationIndex: i },
+        });
+    }
+    return diagnostics;
+}

package/lib/server/debug.d.ts

@@ -0,0 +1,3 @@
+import debug from 'debug';
+export declare const log: debug.Debugger;
+export declare function verbosely(): void;

package/lib/server/debug.js

@@ -0,0 +1,7 @@
+import debug from 'debug';
+export const log = debug('vscode:markuplint');
+const NAMESPACES = 'vscode:markuplint*,markuplint*,ml-*';
+export function verbosely() {
+    debug.enable(NAMESPACES);
+    log(`[Debug] Enable: "${NAMESPACES}"`);
+}

package/lib/server/document-events.d.ts

@@ -0,0 +1,78 @@
+import type { Module, ModuleResolver } from './get-module.js';
+import type { Config, LangConfigs, Log } from '../types.js';
+import type { WorkingDirectoryEntry } from '../utils/resolve-working-directory.js';
+import type { CodeAction, CodeActionParams, PublishDiagnosticsParams, HoverParams } from 'vscode-languageserver/node.js';
+import type { TextDocument } from 'vscode-languageserver-textdocument';
+/**
+ * The configuration of a language for a client that sends no `langConfigs`. It enables
+ * linting and leaves `defaultConfig` unset, so config discovery and the
+ * `markuplint:recommended` fallback behave as they do in the CLI.
+ */
+export declare const DEFAULT_LANG_CONFIG: Config;
+/**
+ * Callback for publishing diagnostics from the language server to the client.
+ */
+export type SendDiagnostics = (params: PublishDiagnosticsParams) => void;
+/**
+ * Options for creating the document event handlers.
+ */
+export type EventHandlerOptions = {
+    /** Loads the markuplint module for a document's working directory */
+    resolveModule: ModuleResolver;
+    /** The user's locale (e.g. `"en"`, `"ja"`) */
+    locale: string;
+    /**
+     * Per-language configuration from the client's settings. Without it every document is
+     * linted with {@link DEFAULT_LANG_CONFIG}.
+     */
+    langConfigs?: LangConfigs;
+    /** User-configured working directories for monorepo support */
+    workingDirectories?: readonly WorkingDirectoryEntry[];
+    /** Absolute paths of the workspace folders */
+    workspaceFolders: readonly string[];
+    log: Log;
+    diagnosticsLog: Log;
+    errorLog: Log;
+    sendDiagnostics: SendDiagnostics;
+    /**
+     * Called on every document open with the module that document is linted with.
+     * The status bar therefore reflects the most recently opened document, not the active editor.
+     */
+    reportStatus: (mod: Module) => void;
+    /** Path to the git binary used for bulk suppression. */
+    gitPath?: string;
+};
+/**
+ * Determines the working directory a document belongs to.
+ *
+ * Both config discovery and markuplint module resolution are anchored here, so the two never
+ * disagree about which installation governs the document.
+ *
+ * @param document - The text document
+ * @param workspaceFolders - Absolute paths of the workspace folders
+ * @param workingDirectories - User-configured working directories
+ * @param log - Logger for general messages
+ * @returns The matched working directory, or the document's own directory when nothing matches
+ */
+export declare function resolveDocumentWorkspace(document: TextDocument, workspaceFolders: readonly string[], workingDirectories: readonly WorkingDirectoryEntry[] | undefined, log: Log): string;
+/**
+ * Creates version-aware event handlers for document open, change, code action, and hover events.
+ *
+ * Each document is linted with the markuplint module resolved from its own working directory,
+ * and dispatched to the handler (v2, v3, v4, or v5) matching that module's version.
+ *
+ * @param options - Configuration including the module resolver, locale, and settings
+ * @returns An object containing `onDidOpen`, `onDidChangeContent`, `onDidClose`, `onCodeAction`, and `onHover` handlers
+ */
+export declare function createEventHandlers(options: EventHandlerOptions): {
+    onDidOpen(document: TextDocument): void;
+    onDidChangeContent(document: TextDocument): void;
+    onDidClose(document: TextDocument): void;
+    onCodeAction(params: CodeActionParams): CodeAction[];
+    onHover(params: HoverParams): Promise<{
+        contents: {
+            kind: "markdown";
+            value: string;
+        };
+    } | undefined>;
+};

package/lib/server/document-events.js

@@ -0,0 +1,299 @@
+import { isFatalError } from 'markuplint/suppressions';
+import { satisfies, lt, gte } from 'semver';
+import { MarkupKind } from 'vscode-languageserver/node.js';
+import { t } from '../i18n.js';
+import { getFilePath } from '../utils/get-file-path.js';
+import { resolveWorkingDirectory } from '../utils/resolve-working-directory.js';
+import { createParserErrorHandler } from './parser-load-failure.js';
+import * as v2 from './v2.js';
+import * as v3 from './v3.js';
+import * as v4 from './v4.js';
+import * as v5 from './v5.js';
+/**
+ * The configuration of a language for a client that sends no `langConfigs`. It enables
+ * linting and leaves `defaultConfig` unset, so config discovery and the
+ * `markuplint:recommended` fallback behave as they do in the CLI.
+ */
+export const DEFAULT_LANG_CONFIG = {
+    enable: true,
+    debug: false,
+    hover: { accessibility: { enable: true } },
+};
+/**
+ * Determines the working directory a document belongs to.
+ *
+ * Both config discovery and markuplint module resolution are anchored here, so the two never
+ * disagree about which installation governs the document.
+ *
+ * @param document - The text document
+ * @param workspaceFolders - Absolute paths of the workspace folders
+ * @param workingDirectories - User-configured working directories
+ * @param log - Logger for general messages
+ * @returns The matched working directory, or the document's own directory when nothing matches
+ */
+export function resolveDocumentWorkspace(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+document, workspaceFolders, workingDirectories, log) {
+    const filePath = getFilePath(document.uri, document.languageId);
+    const absoluteFilePath = `${filePath.dirname}/${filePath.basename}`;
+    const resolved = resolveWorkingDirectory(absoluteFilePath, workspaceFolders, workingDirectories);
+    const workspace = resolved?.directory ?? filePath.dirname;
+    if (resolved) {
+        log(`Resolved working directory: ${workspace} (for ${filePath.basename})`, 'debug');
+    }
+    return workspace;
+}
+/**
+ * Creates version-aware event handlers for document open, change, code action, and hover events.
+ *
+ * Each document is linted with the markuplint module resolved from its own working directory,
+ * and dispatched to the handler (v2, v3, v4, or v5) matching that module's version.
+ *
+ * @param options - Configuration including the module resolver, locale, and settings
+ * @returns An object containing `onDidOpen`, `onDidChangeContent`, `onDidClose`, `onCodeAction`, and `onHover` handlers
+ */
+export function createEventHandlers(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+options) {
+    const documentModules = new Map();
+    const queues = new Map();
+    /**
+     * Documents whose close has been received but not yet carried out. The module of a
+     * document is only forgotten when the queued close runs, which is after any open still in
+     * progress; until then change, code action and hover requests must not reach the engine.
+     */
+    const closedDocuments = new Map();
+    function activeModule(uri) {
+        return closedDocuments.has(uri) ? undefined : documentModules.get(uri);
+    }
+    /**
+     * Runs `task` after every earlier open/close of the same document has finished.
+     *
+     * Opening is asynchronous (module resolution, then engine setup), so a close that
+     * arrives meanwhile would find nothing to release and the engine created afterwards
+     * would leak; a reopen that overlapped the release would start a second engine on
+     * the file while the first one's watcher is still shutting down.
+     *
+     * `task` must handle its own failures; only an error that must not be swallowed (a
+     * fatal one) may escape, and it is rethrown outside the queue so that it surfaces
+     * as an uncaught exception instead of stalling the document's later events.
+     */
+    function enqueue(uri, task) {
+        const tail = (queues.get(uri) ?? Promise.resolve())
+            .then(task)
+            .catch((error) => {
+            queueMicrotask(() => {
+                throw error;
+            });
+        })
+            .then(() => {
+            if (queues.get(uri) === tail) {
+                queues.delete(uri);
+            }
+        });
+        queues.set(uri, tail);
+    }
+    function parserErrorHandler(mod, languageId) {
+        return createParserErrorHandler({
+            languageId,
+            isLocalModule: mod.isLocalModule,
+            version: mod.version,
+            workspace: mod.workspace,
+            fallbackReason: mod.fallbackReason,
+        }, options.errorLog);
+    }
+    function dispatchOpen(mod, 
+    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+    document, 
+    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+    langConfig, workspace) {
+        const onError = parserErrorHandler(mod, document.languageId);
+        if (satisfies(mod.version, '2.x')) {
+            return v2.onDidOpen(document, mod.markuplint.MLEngine, langConfig, options.locale, options.sendDiagnostics, onError, workspace, options.log);
+        }
+        if (satisfies(mod.version, '3.x')) {
+            return v3.onDidOpen(document, mod.markuplint.MLEngine, langConfig, options.locale, options.log, options.diagnosticsLog, options.sendDiagnostics, onError, workspace);
+        }
+        if (satisfies(mod.version, '4.x')) {
+            return v4.onDidOpen(document, mod.markuplint.MLEngine, langConfig, options.locale, options.log, options.diagnosticsLog, options.sendDiagnostics, onError, workspace);
+        }
+        // v5+
+        return v5.onDidOpen(document, mod.markuplint.MLEngine, langConfig, options.locale, options.log, options.diagnosticsLog, options.sendDiagnostics, onError, workspace);
+    }
+    return {
+        onDidOpen(
+        // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+        document) {
+            const languageId = document.languageId;
+            const langConfig = options.langConfigs ? (options.langConfigs[languageId] ?? null) : DEFAULT_LANG_CONFIG;
+            if (!langConfig?.enable) {
+                options.log(`Disabled for languageId:${languageId} according to the settings of the client.`, 'warn');
+                return;
+            }
+            options.log(`Evaluate ${document.uri} from languageId:${languageId}`, 'info');
+            const workspace = resolveDocumentWorkspace(document, options.workspaceFolders, options.workingDirectories, options.log);
+            closedDocuments.delete(document.uri);
+            enqueue(document.uri, async () => {
+                let mod;
+                try {
+                    mod = documentModules.get(document.uri) ?? (await options.resolveModule(workspace));
+                }
+                catch (error) {
+                    if (isFatalError(error)) {
+                        throw error;
+                    }
+                    options.errorLog(`Failed to load markuplint for ${workspace}: ${error}`);
+                    return;
+                }
+                // Recorded before the engine exists so change events arriving during the
+                // asynchronous engine setup are routed to the same version handler.
+                documentModules.set(document.uri, mod);
+                options.reportStatus(mod);
+                try {
+                    await dispatchOpen(mod, document, langConfig, workspace);
+                }
+                catch (error) {
+                    if (isFatalError(error)) {
+                        throw error;
+                    }
+                    options.errorLog(`Failed to open ${document.uri} with markuplint ${mod.version}: ${error}`);
+                }
+            });
+        },
+        onDidChangeContent(
+        // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+        document) {
+            const mod = activeModule(document.uri);
+            if (!mod) {
+                return;
+            }
+            const onError = parserErrorHandler(mod, document.languageId);
+            if (satisfies(mod.version, '2.x')) {
+                v2.onDidChangeContent(document, onError);
+                return;
+            }
+            if (satisfies(mod.version, '3.x')) {
+                v3.onDidChangeContent(document, options.log, onError);
+                return;
+            }
+            if (satisfies(mod.version, '4.x')) {
+                v4.onDidChangeContent(document, options.log, onError);
+                return;
+            }
+            // v5+
+            v5.onDidChangeContent(document, options.log, onError);
+        },
+        onDidClose(
+        // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+        document) {
+            const uri = document.uri;
+            const closing = Symbol(uri);
+            closedDocuments.set(uri, closing);
+            enqueue(uri, async () => {
+                const mod = documentModules.get(uri);
+                if (!mod) {
+                    if (closedDocuments.get(uri) === closing) {
+                        closedDocuments.delete(uri);
+                    }
+                    return;
+                }
+                documentModules.delete(uri);
+                const release = satisfies(mod.version, '2.x')
+                    ? v2.onDidClose
+                    : satisfies(mod.version, '3.x')
+                        ? v3.onDidClose
+                        : satisfies(mod.version, '4.x')
+                            ? v4.onDidClose
+                            : v5.onDidClose;
+                try {
+                    await release(uri);
+                }
+                catch (error) {
+                    if (isFatalError(error)) {
+                        throw error;
+                    }
+                    options.errorLog(`Failed to release markuplint for ${uri}: ${error}`);
+                }
+                finally {
+                    // The client keeps showing the last diagnostics of a document until told
+                    // otherwise. Sent after the release: the engine's listeners are gone by then,
+                    // so no lint can publish over it.
+                    options.sendDiagnostics({ uri, diagnostics: [] });
+                    if (closedDocuments.get(uri) === closing) {
+                        closedDocuments.delete(uri);
+                    }
+                }
+            });
+        },
+        // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+        onCodeAction(params) {
+            const uri = params.textDocument.uri;
+            const mod = activeModule(uri);
+            if (!mod) {
+                options.log(`Code Actions skipped: no module for ${uri}`, 'debug');
+                return [];
+            }
+            // Code Actions require v5.0.0+ (Violation.fix data + lint event fixSummary)
+            // Use '5.0.0-0' to include alpha/beta prereleases
+            if (!gte(mod.version, '5.0.0-0')) {
+                options.log(`Code Actions skipped: markuplint ${mod.version} < 5.0.0`, 'debug');
+                return [];
+            }
+            const actions = v5.onCodeAction(params);
+            options.log(`Code Actions: ${actions.length} for ${uri}`, 'debug');
+            return actions;
+        },
+        async onHover(
+        // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+        params) {
+            const hoverSettings = (options.langConfigs ? options.langConfigs['html'] : DEFAULT_LANG_CONFIG)?.hover
+                .accessibility;
+            if (!hoverSettings?.enable) {
+                return;
+            }
+            const mod = activeModule(params.textDocument.uri);
+            if (!mod) {
+                return;
+            }
+            const ariaVersion = hoverSettings.ariaVersion ?? mod.ariaRecommendedVersion;
+            if (lt(mod.version, '4.0.0')) {
+                const node = v3.getNodeWithAccessibilityProps(params.textDocument, params.position, ariaVersion);
+                if (!node) {
+                    return;
+                }
+                const heading = `\`<${node.nodeName}>\` **${t('Computed Accessibility Properties')}**:\n`;
+                const props = node.exposed
+                    ? `${Object.entries(node.aria)
+                        .map(([key, value]) => `- ${key}: ${value}`)
+                        .join('\n')}`
+                    : `\n**${t('No exposed to accessibility tree')}** (${t('hidden element')})`;
+                return {
+                    contents: {
+                        kind: MarkupKind.Markdown,
+                        value: heading + props,
+                    },
+                };
+            }
+            const aria = satisfies(mod.version, '4.x')
+                ? await v4.getNodeWithAccessibilityProps(params.textDocument, params.position, ariaVersion)
+                : await v5.getNodeWithAccessibilityProps(params.textDocument, params.position, ariaVersion);
+            if (!aria) {
+                return;
+            }
+            const heading = `\`<${aria.nodeName}>\` **${t('Computed Accessibility Properties')}**:\n`;
+            const body = 'unknown' in aria
+                ? `\n**${t('Unknown')}**`
+                : aria.exposed
+                    ? `${Object.entries(aria.labels)
+                        .map(([key, value]) => `- ${key}: ${value}`)
+                        .join('\n')}`
+                    : `\n**${t('No exposed to accessibility tree')}** (${t('hidden element')})`;
+            return {
+                contents: {
+                    kind: MarkupKind.Markdown,
+                    value: heading + body,
+                },
+            };
+        },
+    };
+}

package/lib/server/get-accessibility-by-location.d.ts

@@ -0,0 +1,6 @@
+import type { ARIAVersion } from '@markuplint/ml-spec';
+import type { MLEngine } from 'markuplint';
+export declare function getAccessibilityByLocation(engine: MLEngine, line: number, col: number, ariaVersion: ARIAVersion): Promise<{
+    node: string;
+    aria: import("@markuplint/ml-core").AccessibilityProperties | null;
+} | null>;

package/lib/server/get-accessibility-by-location.js

@@ -0,0 +1,19 @@
+export async function getAccessibilityByLocation(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+engine, line, col, ariaVersion) {
+    if (!engine?.document) {
+        await engine.exec();
+    }
+    if (!engine?.document) {
+        return null;
+    }
+    const node = engine.document.searchNodeByLocation(line, col);
+    if (!node || !node.is(node.ELEMENT_NODE)) {
+        return null;
+    }
+    const aria = engine.document.getAccessibilityProp(node, ariaVersion);
+    return {
+        node: node.localName,
+        aria,
+    };
+}

package/lib/server/get-module.d.ts

@@ -0,0 +1,127 @@
+import type { Log } from '../types.js';
+import { type ARIAVersion } from '@markuplint/ml-spec';
+/**
+ * Convert a module path into a specifier that Node's ESM `import()` accepts.
+ *
+ * On Windows, raw drive-letter paths like `c:\foo` are rejected by the ESM
+ * loader (`ERR_UNSUPPORTED_ESM_URL_SCHEME: Received protocol 'c:'`) because
+ * the drive letter is parsed as a URL scheme. They must be converted to
+ * `file://` URLs first.
+ *
+ * Detection is OS-independent so that POSIX CI can exercise the Windows
+ * code path.
+ *
+ * Mirrors `packages/@markuplint/file-resolver/src/general-import.ts` —
+ * keep the two in sync when adjusting Windows-path handling. Note:
+ * file-resolver currently still relies on `pathToFileURL()` and carries
+ * the same Windows / POSIX-absolute mismatch; tracked separately as
+ * #3840 (dev / v5).
+ *
+ * @param modPath - A module specifier — typically the result of `Files.resolve`
+ *   or `require.resolve`, which may be a bare module name (`markuplint`), a
+ *   relative path (`./foo`), or an absolute path (Windows or POSIX).
+ * @returns A specifier safe to pass to `import()`. Absolute paths are converted
+ *   to `file://` URLs with each segment percent-encoded; bare and relative
+ *   specifiers are returned unchanged. UNC paths (`\\server\share\...`) are
+ *   passed through unchanged as a known limitation.
+ * @see https://github.com/markuplint/markuplint/issues/3795
+ * @see https://github.com/markuplint/markuplint/issues/3836
+ * @see https://github.com/markuplint/markuplint/issues/3842
+ * @see https://nodejs.org/api/esm.html#urls
+ */
+export declare function toImportSpecifier(modPath: string): string;
+/**
+ * Resolve and load the markuplint module for a working directory.
+ *
+ * Attempts to load a markuplint installed upward from `workspace` first.
+ * If the local module fails to load (not installed, or import assertion incompatibility
+ * on Node.js 22+), falls back to the version installed with the language server.
+ *
+ * @param workspace - Absolute directory used as the resolution base
+ * @param log - Logger function for diagnostic output
+ * @param deps - Module system access; defaults to Node's own (injectable for tests)
+ * @returns The resolved module metadata including version, type, and optional fallback reason
+ */
+export declare function loadModule(workspace: string, log: Log, deps?: LoadDeps): Promise<Module>;
+type LoadDeps = {
+    readonly resolveEntry: (workspace: string, log: (message: string) => void) => string;
+    readonly importModule: (specifier: string) => Promise<any>;
+    readonly importBundledPackageJson: () => Promise<any>;
+    readonly readPackageJson: (packageJsonPath: string) => any;
+};
+/**
+ * Loads the markuplint module for a working directory.
+ */
+export type ModuleResolver = (workspace: string) => Promise<Module>;
+/**
+ * Create a resolver that loads the markuplint module per working directory and caches it.
+ *
+ * Resolution must follow the working directory rather than the workspace root: the modules a
+ * config refers to (`parser` / `specs` / `plugins`) are imported by `@markuplint/file-resolver`
+ * relative to the loaded markuplint installation, so a parser installed only in a sub-package
+ * is reachable only when markuplint itself is loaded from that sub-package. Falling back to the
+ * bundled copy there leaves the parser unreachable and the document silently undiagnosed.
+ *
+ * `onFirstResolve` fires once per distinct directory — the place for one-shot notices such as
+ * the bundled-fallback warning — whereas callers may report per-document status freely.
+ * A failed load is not cached so the next document in that directory retries.
+ *
+ * @param options.log - Logger function for diagnostic output
+ * @param options.onFirstResolve - Called once per directory when its module is first loaded
+ * @param options.load - Module loader (injectable for tests)
+ * @returns A resolver keyed by the normalized absolute directory
+ * @see https://github.com/markuplint/markuplint/issues/4048
+ */
+export declare function createModuleResolver(options: {
+    readonly log: Log;
+    readonly onFirstResolve?: (mod: Module) => void;
+    readonly load?: (workspace: string, log: Log) => Promise<Module>;
+}): ModuleResolver;
+/**
+ * Metadata for the resolved markuplint module.
+ */
+export type Module = {
+    /** Whether the module was loaded from a node_modules found upward from `workspace` */
+    isLocalModule: boolean;
+    /** The semver version string of the loaded module */
+    version: string;
+    /** The module system type declared in package.json */
+    moduleType: 'commonjs' | 'module';
+    /** The loaded markuplint module exports */
+    markuplint: any;
+    /** The ARIA specification version recommended by the loaded module */
+    ariaRecommendedVersion: ARIAVersion;
+    /**
+     * Reason the local module was skipped in favor of the bundled version.
+     * Set to `'import-assertion-compat'` when the local markuplint uses
+     * `assert { type: 'json' }` syntax that was removed in Node.js 22.
+     */
+    fallbackReason?: 'import-assertion-compat';
+    /** The normalized absolute working directory the module was resolved for */
+    readonly workspace: string;
+};
+type RequireDeps = {
+    readonly requireResolve: (name: string, options: {
+        readonly paths: readonly string[];
+    }) => string;
+    readonly readPackageJson: (packageJsonPath: string) => any;
+};
+/**
+ * Resolve the `markuplint` entry point with Node's CommonJS resolver, walking up from `dir`.
+ *
+ * Resolution stays in-process: `Files.resolve` from `vscode-languageserver` forks a Node process
+ * per call, which was acceptable for a single session-wide lookup but not for one lookup per
+ * working directory (every opened file's directory when `workingDirectories` is unset).
+ *
+ * `require.resolve` rejects a package whose `exports` map has no `require` condition (markuplint
+ * ships ESM only), so the entry point is then read from that `package.json` directly. The
+ * resolver functions are injectable because the server bundle is CommonJS while the test runner
+ * executes this file as ESM, where `require` is not defined.
+ *
+ * @param dir - Absolute directory to start the `node_modules` walk from
+ * @param log - Logger function for diagnostic output
+ * @param deps - `require.resolve` and `require` equivalents; defaults to Node's own
+ * @returns The absolute path of the markuplint entry point
+ */
+export declare function resolveWithRequire(dir: string, log: (message: string) => void, deps?: RequireDeps): string;
+export {};