/** * Diagnostics in the editor (M3.3): wavy underlines, gutter markers and * the message on hover, from the language server's `diagnosticsChanged` * events, through CodeMirror's lint extension. * * The Problems store ({@link useProblemsStore}) owns the diagnostics and * hands every file's list to {@link publishDiagnostics}. This module keeps * them by path; each editor state built for a path carries a view plugin * that applies the file's list when the view shows the state and whenever * it changes. Editor states of tabs in the background are brought up to * date when they are shown again. Between two publications CodeMirror maps * the ranges through the user's edits. * * Positions are 0-based lines with UTF-16 columns, converted with * {@link positionOf} (CRLF-safe, clamped to the document). Colours come * from the severity tokens `--lt-diag-error`, `--lt-diag-warning`, * `--lt-diag-info` and `--lt-diag-hint`. * * @see useProblemsStore in `../problems/problems.ts`. */ import { lintGutter, setDiagnostics, type Diagnostic } from "@codemirror/lint"; import type { Extension, Text } from "@codemirror/state"; import { EditorView, ViewPlugin, type PluginValue } from "@codemirror/view"; import { positionOf } from "./engineText"; /** Severity of a diagnostic, as the engine names it. */ export type DiagnosticSeverity = "error" | "warning" | "info" | "hint"; /** A 0-based position; the column counts UTF-16 code units. */ export interface DiagnosticPosition { /** Line. */ line: number; /** Column. */ column: number; } /** One diagnostic of a file, as `diagnosticsChanged` carries it. */ export interface DiagnosticItem { /** Where it applies; the end is exclusive. */ range: { start: DiagnosticPosition; end: DiagnosticPosition }; /** How severe it is. */ severity: DiagnosticSeverity; /** The message. */ message: string; /** Who reported it (`phpactor`, …). */ source?: string; /** The diagnostic code. */ code?: string; } /** Diagnostics by project-relative path. */ const byPath = new Map(); /** Plugins listening for changes, by path. */ const listeners = new Map void>>(); /** * Stores the diagnostics of a file and updates the editors showing it. * * @param path - project-relative path with `/`. * @param items - the file's diagnostics; empty clears them. */ export function publishDiagnostics(path: string, items: readonly DiagnosticItem[]): void { if (items.length === 0) { byPath.delete(path); } else { byPath.set(path, items); } for (const listener of listeners.get(path) ?? []) { listener(); } } /** Drops every file's diagnostics (project closed) and updates the editors. */ export function clearDiagnostics(): void { const paths = [...byPath.keys()]; byPath.clear(); for (const path of paths) { for (const listener of listeners.get(path) ?? []) { listener(); } } } /** * The diagnostics stored for a file. * * @param path - project-relative path. */ export function diagnosticsOf(path: string): readonly DiagnosticItem[] { return byPath.get(path) ?? []; } /** * Converts a file's diagnostics into CodeMirror's, against `doc`. * * @param doc - the document they apply to. * @param items - the diagnostics. * @returns CodeMirror diagnostics, sorted by start as the lint state needs. */ export function toCodeMirror(doc: Text, items: readonly DiagnosticItem[]): Diagnostic[] { const out: Diagnostic[] = items.map((item) => { const from = positionOf(doc, item.range.start.line, item.range.start.column); const to = Math.max(from, positionOf(doc, item.range.end.line, item.range.end.column)); const source = [item.source, item.code].filter((part) => part !== undefined && part !== "").join(" "); const diagnostic: Diagnostic = { from, to, severity: item.severity, message: item.message }; if (source !== "") { diagnostic.source = source; } return diagnostic; }); return out.sort((a, b) => a.from - b.from || a.to - b.to); } /** * A view plugin that keeps the lint state of a path's editor in step with * {@link publishDiagnostics}. It applies the current list right after the * view shows the state (the dispatch waits a microtask: a plugin may not * dispatch while the view is updating) and on every change. * * @param path - project-relative path of the editor's file. */ function diagnosticsPlugin(path: string): Extension { return ViewPlugin.define((view): PluginValue => { let alive = true; const apply = (): void => { if (!alive) { return; } view.dispatch(setDiagnostics(view.state, toCodeMirror(view.state.doc, diagnosticsOf(path)))); }; let set = listeners.get(path); if (!set) { set = new Set(); listeners.set(path, set); } set.add(apply); queueMicrotask(apply); return { destroy(): void { alive = false; const current = listeners.get(path); current?.delete(apply); if (current?.size === 0) { listeners.delete(path); } }, }; }); } /** Wavy underline of one severity in a token colour. */ function underline(colour: string): Record { return { backgroundImage: "none", textDecoration: `underline wavy ${colour}`, textDecorationSkipInk: "none", textUnderlineOffset: "3px", }; } /** Gutter dot of one severity in a token colour. */ function marker(colour: string): Record { return { content: "none", width: "8px", height: "8px", margin: "0 auto", borderRadius: "50%", backgroundColor: colour, }; } /** Lint colours from tokens, replacing CodeMirror's built-in ones. */ const lintTheme: Extension = EditorView.theme({ ".cm-lintRange-error": underline("var(--lt-diag-error)"), ".cm-lintRange-warning": underline("var(--lt-diag-warning)"), ".cm-lintRange-info": underline("var(--lt-diag-info)"), ".cm-lintRange-hint": underline("var(--lt-diag-hint)"), ".cm-lintRange-active": { backgroundColor: "var(--lt-editor-match-bg)" }, ".cm-lintPoint:after": { borderBottomColor: "var(--lt-diag-error)" }, ".cm-lintPoint-warning:after": { borderBottomColor: "var(--lt-diag-warning)" }, ".cm-lintPoint-info:after": { borderBottomColor: "var(--lt-diag-info)" }, ".cm-lintPoint-hint:after": { borderBottomColor: "var(--lt-diag-hint)" }, ".cm-gutter-lint": { width: "14px" }, ".cm-gutter-lint .cm-gutterElement": { display: "flex", alignItems: "center", padding: "0" }, ".cm-lint-marker": { width: "8px", height: "8px" }, ".cm-lint-marker-error": marker("var(--lt-diag-error)"), ".cm-lint-marker-warning": marker("var(--lt-diag-warning)"), ".cm-lint-marker-info": marker("var(--lt-diag-info)"), ".cm-lint-marker-hint": marker("var(--lt-diag-hint)"), ".cm-diagnostic": { padding: "4px 8px", color: "var(--lt-fg)", whiteSpace: "pre-wrap" }, ".cm-diagnostic-error": { borderLeft: "3px solid var(--lt-diag-error)" }, ".cm-diagnostic-warning": { borderLeft: "3px solid var(--lt-diag-warning)" }, ".cm-diagnostic-info": { borderLeft: "3px solid var(--lt-diag-info)" }, ".cm-diagnostic-hint": { borderLeft: "3px solid var(--lt-diag-hint)" }, ".cm-diagnosticSource": { color: "var(--lt-fg-muted)", opacity: "1" }, ".cm-tooltip-lint": { maxWidth: "640px" }, ".cm-panel.cm-panel-lint": { backgroundColor: "var(--lt-bg)", color: "var(--lt-fg)" }, ".cm-panel.cm-panel-lint ul [aria-selected]": { backgroundColor: "var(--lt-editor-selection-bg)" }, }); /** * The lint extensions of an editor for `path`: the lint state with its * hover tooltips, the gutter column, the token theme and the plugin that * feeds them. Files without diagnostics get them too, so a first * publication shows at once. * * @param path - project-relative path of the file; empty for none. */ export function lintExtensions(path: string): Extension { if (path === "") { return []; } return [lintGutter(), lintTheme, diagnosticsPlugin(path)]; }