Lutra/ui/src/components/editor/lint.ts
danny 9801a346b6 H5: banner-aligned themes, diagnostic and VCS tokens
Both themes follow the README banner without taking it over: calm,
near-neutral surfaces (cream-tinted light, faintly plum-tinted dark),
the raspberry only as the accent, retuned syntax colours and the
terminal on the editor surface. Approved by the owner from before/after
screenshots.

New tokens `--lt-diag-error|warning|info|hint` (lint underlines, gutter,
tooltips, Problems icons) and `--lt-vcs-added|modified|deleted|untracked|
ignored|conflicted` (for M4.4), listed in `theme::DIAGNOSTIC_TOKENS` and
`theme::VCS_TOKENS`. Completion kind icons take the syntax colour of
their kind. The contrast test checks every new colour (4.5:1 text,
3:1 icons) in both themes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-25 13:58:38 +01:00

216 lines
7.8 KiB
TypeScript

/**
* 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<string, readonly DiagnosticItem[]>();
/** Plugins listening for changes, by path. */
const listeners = new Map<string, Set<() => 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<string, string> {
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<string, string> {
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)];
}