M3.3: engine wiring for Phpactor and diagnostics

- One Phpactor per open project on its own session thread, started when
  the toolchain is ready; ordered document sync from buffer.edit and the
  pump; lspStatus, diagnosticsChanged, diagnostics.list, lsp.status,
  lsp.restart; app.quit stops the server synchronously.
- Phpactor 2026.06.25.0 on Windows: keep-alive $/lutra/tick (its event
  loop only runs on stdin input), in-process diagnostics and a polling
  watcher through initializationOptions (amphp subprocesses fail), 500 ms
  shutdown timeout.
- Editor lint extension (underlines, gutter dots, hover; tokens only) and
  a Problems tab in the bottom panel; problems.open Mod+Alt+P.
- Tests: engine tests against the fake server (incl. sync proptest), an
  ignored real-Phpactor test, a TCP test, Vitest for lint and Problems.
- Docs: architecture, gaps G6, parity (Inspections 4% est.), ui-parity,
  roadmap, ROADMAP.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-21 18:58:32 +02:00
parent 65c6966588
commit 13c76d3046
34 changed files with 3562 additions and 37 deletions

View file

@ -11,6 +11,7 @@ import { EditorView } from "@codemirror/view";
import type { Extension } from "@codemirror/state";
import { basicSetup } from "codemirror";
import { languageExtensions, type SYNTAX_CLASS, type SyntaxToken } from "./language";
import { lintExtensions } from "./lint";
/**
* Colours of the highlight classes (`language.ts`), one `--lt-syntax-*`
@ -110,5 +111,5 @@ export const lutraEditorTheme: Extension = EditorView.theme({
* omitted or unknown.
*/
export function editorExtensions(path = ""): Extension {
return [basicSetup, lutraEditorTheme, languageExtensions(path)];
return [basicSetup, lutraEditorTheme, languageExtensions(path), lintExtensions(path)];
}

View file

@ -0,0 +1,212 @@
/**
* 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 tokens: errors `--lt-error`, warnings `--lt-accent`, information and
* hints `--lt-fg-muted`.
*
* @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-error)"),
".cm-lintRange-warning": underline("var(--lt-accent)"),
".cm-lintRange-info, .cm-lintRange-hint": underline("var(--lt-fg-muted)"),
".cm-lintRange-active": { backgroundColor: "var(--lt-editor-match-bg)" },
".cm-lintPoint:after": { borderBottomColor: "var(--lt-error)" },
".cm-lintPoint-warning:after": { borderBottomColor: "var(--lt-accent)" },
".cm-lintPoint-info:after, .cm-lintPoint-hint:after": { borderBottomColor: "var(--lt-fg-muted)" },
".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-error)"),
".cm-lint-marker-warning": marker("var(--lt-accent)"),
".cm-lint-marker-info, .cm-lint-marker-hint": marker("var(--lt-fg-muted)"),
".cm-diagnostic": { padding: "4px 8px", color: "var(--lt-fg)", whiteSpace: "pre-wrap" },
".cm-diagnostic-error": { borderLeft: "3px solid var(--lt-error)" },
".cm-diagnostic-warning": { borderLeft: "3px solid var(--lt-accent)" },
".cm-diagnostic-info, .cm-diagnostic-hint": { borderLeft: "3px solid var(--lt-fg-muted)" },
".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)];
}