@stateward/language-server 0.0.0-stage → 1.0.1-rc.1

package/dist/mapping.js

@@ -0,0 +1,193 @@
+import { CodeActionKind, DiagnosticSeverity, SemanticTokensBuilder, } from "vscode-languageserver";
+import { ignoreFix } from "@stateward/core/internal";
+export function buildLineIndex(text) {
+    const starts = [0];
+    for (let i = 0; i < text.length; i++) {
+        if (text.charCodeAt(i) === 10)
+            starts.push(i + 1);
+    }
+    return { starts, length: text.length };
+}
+/** The 0-based line and UTF-16 character of `offset`, clamped to the text. */
+export function positionAt(index, offset) {
+    const clamped = Math.min(Math.max(offset, 0), index.length);
+    let low = 0;
+    let high = index.starts.length - 1;
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        if ((index.starts[middle] ?? 0) <= clamped)
+            low = middle;
+        else
+            high = middle - 1;
+    }
+    return { line: low, character: clamped - (index.starts[low] ?? 0) };
+}
+/** The offset of `position`, clamped to the end of its line (and to the text). */
+export function offsetAt(index, position) {
+    const start = index.starts[position.line];
+    if (start === undefined)
+        return index.length;
+    const next = index.starts[position.line + 1] ?? index.length + 1;
+    return Math.min(start + position.character, next - 1, index.length);
+}
+export function toRange(index, location) {
+    return { start: positionAt(index, location.start), end: positionAt(index, location.end) };
+}
+export function toDiagnosticSeverity(severity) {
+    switch (severity) {
+        case "error":
+            return DiagnosticSeverity.Error;
+        case "warning":
+            return DiagnosticSeverity.Warning;
+        case "info":
+            return DiagnosticSeverity.Information;
+        default: {
+            const unreachable = severity;
+            return unreachable;
+        }
+    }
+}
+/** The same words as the terminal: the headline, then the fix. */
+function diagnosticMessage(finding, baselined) {
+    return `${baselined ? "baselined: " : ""}${finding.message}\nFix: ${finding.hint}`;
+}
+/**
+ * A finding the baseline accepts is a Hint (shown faintly, not in the Problems count) whatever
+ * its severity, and its message starts with `baselined: `.
+ */
+export function toDiagnostic(finding, files, baselined = false) {
+    const range = toRange(files.indexOf(finding.location.file), finding.location);
+    switch (finding.kind) {
+        case "problem":
+            return {
+                range,
+                severity: baselined ? DiagnosticSeverity.Hint : toDiagnosticSeverity(finding.severity),
+                code: finding.ruleId,
+                source: "stateward",
+                message: diagnosticMessage(finding, baselined),
+                ...(finding.related.length === 0
+                    ? {}
+                    : {
+                        relatedInformation: finding.related.map((related) => ({
+                            location: {
+                                uri: files.uriOf(related.location.file),
+                                range: toRange(files.indexOf(related.location.file), related.location),
+                            },
+                            message: related.message,
+                        })),
+                    }),
+            };
+        case "unknown":
+            return {
+                range,
+                // A rule's place not checked is a faint hint (hundreds of info squiggles would
+                // bury the problems); as a warning (`unknowns: "warning"`) it is something to act on,
+                // and stateward's own (a file it could not read) stays an info.
+                severity: baselined
+                    ? DiagnosticSeverity.Hint
+                    : finding.shown === "warning"
+                        ? DiagnosticSeverity.Warning
+                        : finding.ruleId.startsWith("stateward/")
+                            ? DiagnosticSeverity.Information
+                            : DiagnosticSeverity.Hint,
+                code: finding.ruleId,
+                source: "stateward",
+                message: diagnosticMessage(finding, baselined),
+            };
+        case "failure":
+            return {
+                range,
+                severity: DiagnosticSeverity.Warning,
+                code: finding.ruleId,
+                source: "stateward",
+                message: diagnosticMessage(finding, false),
+            };
+        default: {
+            const unreachable = finding;
+            return unreachable;
+        }
+    }
+}
+/** An information at the start of the file for findings that are counted but not listed. */
+export function toHiddenDiagnostic(hidden) {
+    return {
+        range: { start: { line: 0, character: 0 }, end: { line: 0, character: 0 } },
+        severity: DiagnosticSeverity.Information,
+        code: hidden.ruleId,
+        source: "stateward",
+        message: `${String(hidden.count)} more ${hidden.ruleId} findings in this file are not shown`,
+    };
+}
+/** Core's edits as LSP edits, by document URI. */
+export function toLspChanges(edits, files) {
+    const changes = {};
+    for (const edit of edits) {
+        const uri = files.uriOf(edit.location.file);
+        const range = toRange(files.indexOf(edit.location.file), edit.location);
+        (changes[uri] ??= []).push({ range, newText: edit.newText });
+    }
+    return changes;
+}
+/** A quickfix that applies `fix`; its edits may touch several files. */
+function toCodeAction(fix, diagnostic, files) {
+    const changes = toLspChanges(fix.edits, files);
+    return {
+        title: fix.title,
+        kind: CodeActionKind.QuickFix,
+        diagnostics: [diagnostic],
+        edit: { changes },
+    };
+}
+/**
+ * One quickfix per fix of a problem. Give it a finding whose fixes were tried (`reviewFixes`): a
+ * fix that was not is offered as it is.
+ */
+export function toCodeActions(finding, diagnostic, files) {
+    if (finding.kind !== "problem")
+        return [];
+    return finding.fixes.map((fix) => toCodeAction(fix, diagnostic, files));
+}
+/**
+ * "Ignore this case here" (core's `ignoreFix`): offered for any finding that a comment can cover,
+ * after the fixes, and never applied by "fix all".
+ */
+export function toIgnoreAction(finding, diagnostic, files) {
+    const form = ignoreFix(finding, files.textOf(finding.location.file));
+    return form === undefined ? undefined : toCodeAction(form, diagnostic, files);
+}
+function isBefore(a, b) {
+    return a.line < b.line || (a.line === b.line && a.character < b.character);
+}
+/** Ranges that overlap or touch. */
+export function rangesIntersect(a, b) {
+    return !isBefore(a.end, b.start) && !isBefore(b.end, a.start);
+}
+const TOKEN_INDEX = {
+    class: 0,
+    function: 1,
+    variable: 2,
+    type: 3,
+    decorator: 4,
+    keyword: 5,
+};
+/** The LSP semantic token legend: the TokenType list, in index order. */
+export const TOKEN_TYPES = Object.entries(TOKEN_INDEX)
+    .sort(([, a], [, b]) => a - b)
+    .map(([name]) => name);
+/**
+ * Encodes tokens for LSP. Tokens are sorted by position; a token that spans lines is cut at the
+ * end of its first line, because LSP semantic tokens are single-line.
+ */
+export function encodeTokens(tokens, index) {
+    const builder = new SemanticTokensBuilder();
+    const sorted = [...tokens].sort((a, b) => a.location.start - b.location.start);
+    for (const { location, type } of sorted) {
+        const start = positionAt(index, location.start);
+        const lineEnd = (index.starts[start.line + 1] ?? index.length + 1) - 1;
+        const length = Math.min(location.end, lineEnd) - location.start;
+        if (length > 0)
+            builder.push(start.line, start.character, length, TOKEN_INDEX[type], 0);
+    }
+    return builder.build();
+}
+//# sourceMappingURL=mapping.js.map

package/dist/memory.d.ts

@@ -0,0 +1,13 @@
+/**
+ * How far, in percent, V8 lets the heap grow past what the last full garbage collection kept before
+ * it collects again. Left to itself V8 picks 10% to 300% from how fast it collects, and the server,
+ * whose every edit drops a type checker's worth of objects, then reached 2 to 3 times what it keeps
+ * (1.1 to 1.6 GB on the 3,000-file bench, 1.5 GB on excalidraw).
+ */
+export declare const HEAP_GROWING_PERCENT = 10;
+/**
+ * Sets V8's heap growth for this process (`--heap-growing-percent`). For the server's own process,
+ * called before it starts: V8 reads the flag at each collection, so it holds from the next one on.
+ */
+export declare function limitHeapGrowth(): void;
+//# sourceMappingURL=memory.d.ts.map

package/dist/memory.js

@@ -0,0 +1,16 @@
+import v8 from "node:v8";
+/**
+ * How far, in percent, V8 lets the heap grow past what the last full garbage collection kept before
+ * it collects again. Left to itself V8 picks 10% to 300% from how fast it collects, and the server,
+ * whose every edit drops a type checker's worth of objects, then reached 2 to 3 times what it keeps
+ * (1.1 to 1.6 GB on the 3,000-file bench, 1.5 GB on excalidraw).
+ */
+export const HEAP_GROWING_PERCENT = 10;
+/**
+ * Sets V8's heap growth for this process (`--heap-growing-percent`). For the server's own process,
+ * called before it starts: V8 reads the flag at each collection, so it holds from the next one on.
+ */
+export function limitHeapGrowth() {
+    v8.setFlagsFromString(`--heap-growing-percent=${String(HEAP_GROWING_PERCENT)}`);
+}
+//# sourceMappingURL=memory.js.map

package/dist/merge.d.ts

@@ -0,0 +1,16 @@
+import type { CheckResult, Finding, HiddenFindings } from "@stateward/core/internal";
+/** What is known about one file: its findings in order, and the counts of those not listed. */
+export type FileFindings = {
+    findings: readonly Finding[];
+    hidden: readonly HiddenFindings[];
+};
+/**
+ * The findings of `file` after a fast pass: the fast pass's file-rule findings only. The project
+ * rules' findings of that file are dropped until the next full pass (about a second later): their
+ * offsets belong to the text before the edit, so kept they would be drawn in the wrong place.
+ */
+export declare function mergeFastPass({ file, fast, }: {
+    file: string;
+    fast: Pick<CheckResult, "findings" | "hidden">;
+}): FileFindings;
+//# sourceMappingURL=merge.d.ts.map

package/dist/merge.js

@@ -0,0 +1,20 @@
+import { compareFindings, toTypeScriptPath } from "@stateward/core/internal";
+function compareText(a, b) {
+    if (a < b)
+        return -1;
+    return a > b ? 1 : 0;
+}
+/**
+ * The findings of `file` after a fast pass: the fast pass's file-rule findings only. The project
+ * rules' findings of that file are dropped until the next full pass (about a second later): their
+ * offsets belong to the text before the edit, so kept they would be drawn in the wrong place.
+ */
+export function mergeFastPass({ file, fast, }) {
+    const key = toTypeScriptPath(file);
+    const inFile = (found) => toTypeScriptPath(found.file) === key;
+    return {
+        findings: fast.findings.filter((finding) => inFile(finding.location)).sort(compareFindings),
+        hidden: fast.hidden.filter(inFile).sort((a, b) => compareText(a.ruleId, b.ruleId)),
+    };
+}
+//# sourceMappingURL=merge.js.map

package/dist/progress.d.ts

@@ -0,0 +1,16 @@
+/** The moves of a work-done progress that the server makes. */
+export type ProgressReporter = {
+    begin(title: string): void;
+    /** Where the work stands: a short message and a percentage from 0 to 100. */
+    report(message: string, percentage: number): void;
+    done(): void;
+};
+/** What a client that shows no progress gets: every move does nothing. */
+export declare const SILENT_PROGRESS: ProgressReporter;
+/**
+ * Runs `work` inside a progress titled `title`; `work` reports on it. `begin` is always followed by `done`, also when
+ * `work` throws (the error then goes on to the caller). A progress that cannot be opened (the
+ * client refused it) does not stop the work.
+ */
+export declare function withProgress<T>(open: () => Promise<ProgressReporter>, title: string, work: (reporter: ProgressReporter) => Promise<T>): Promise<T>;
+//# sourceMappingURL=progress.d.ts.map

package/dist/progress.js

@@ -0,0 +1,22 @@
+/** What a client that shows no progress gets: every move does nothing. */
+export const SILENT_PROGRESS = {
+    begin: () => undefined,
+    report: () => undefined,
+    done: () => undefined,
+};
+/**
+ * Runs `work` inside a progress titled `title`; `work` reports on it. `begin` is always followed by `done`, also when
+ * `work` throws (the error then goes on to the caller). A progress that cannot be opened (the
+ * client refused it) does not stop the work.
+ */
+export async function withProgress(open, title, work) {
+    const reporter = await open().catch(() => undefined);
+    reporter?.begin(title);
+    try {
+        return await work(reporter ?? SILENT_PROGRESS);
+    }
+    finally {
+        reporter?.done();
+    }
+}
+//# sourceMappingURL=progress.js.map

package/dist/report.d.ts

@@ -0,0 +1,21 @@
+import type { CheckResult, LongestStep } from "@stateward/core/internal";
+export type Counts = {
+    errors: number;
+    warnings: number;
+    infos: number;
+};
+/** How many findings of each editor severity a result has. */
+export declare function countFindings(result: CheckResult): Counts;
+/** `checked 3002 files in 1.4 s: 0 errors, 1 warnings, 2 infos`: the line logged after a full pass. */
+export declare function fullPassLine(result: CheckResult): string;
+/** `checked src/App.tsx in 38 ms`: the line logged after a fast pass. */
+export declare function fastPassLine(files: readonly string[], result: CheckResult): string;
+/** A step this long is logged: an edit made during it waited that long for its findings. */
+export declare const LONG_STEP_MS = 300;
+/**
+ * `longest step 2900 ms: errors/result-unchecked on src/a.tsx`: logged after a project check
+ * whose longest step kept edits waiting at least `LONG_STEP_MS`; undefined
+ * otherwise. Paths are relative to `cwd`, with `/`.
+ */
+export declare function longestStepLine(longest: LongestStep, cwd: string): string | undefined;
+//# sourceMappingURL=report.d.ts.map

package/dist/report.js

@@ -0,0 +1,70 @@
+import { displayPath } from "@stateward/core/internal";
+/** How a finding is counted: a problem by its own severity, an unknown with the infos (shown as a faint hint) or the warnings (as `unknowns` says), a failure as a warning. */
+function bucket(finding) {
+    switch (finding.kind) {
+        case "problem":
+            switch (finding.severity) {
+                case "error":
+                    return "errors";
+                case "warning":
+                    return "warnings";
+                case "info":
+                    return "infos";
+                default: {
+                    const unreachable = finding.severity;
+                    return unreachable;
+                }
+            }
+        case "unknown":
+            return finding.shown === "warning" ? "warnings" : "infos";
+        case "failure":
+            return "warnings";
+        default: {
+            const unreachable = finding;
+            return unreachable;
+        }
+    }
+}
+/** How many findings of each editor severity a result has. */
+export function countFindings(result) {
+    const counts = { errors: 0, warnings: 0, infos: 0 };
+    for (const finding of result.findings)
+        counts[bucket(finding)] += 1;
+    return counts;
+}
+/** `checked 3002 files in 1.4 s: 0 errors, 1 warnings, 2 infos`: the line logged after a full pass. */
+export function fullPassLine(result) {
+    const counts = countFindings(result);
+    const seconds = (result.stats.durationMs / 1000).toFixed(1);
+    return `checked ${String(result.stats.files)} files in ${seconds} s: ${String(counts.errors)} errors, ${String(counts.warnings)} warnings, ${String(counts.infos)} infos`;
+}
+/** `checked src/App.tsx in 38 ms`: the line logged after a fast pass. */
+export function fastPassLine(files, result) {
+    return `checked ${files.join(", ")} in ${String(result.stats.durationMs)} ms`;
+}
+/** A step this long is logged: an edit made during it waited that long for its findings. */
+export const LONG_STEP_MS = 300;
+/**
+ * `longest step 2900 ms: errors/result-unchecked on src/a.tsx`: logged after a project check
+ * whose longest step kept edits waiting at least `LONG_STEP_MS`; undefined
+ * otherwise. Paths are relative to `cwd`, with `/`.
+ */
+export function longestStepLine(longest, cwd) {
+    if (longest.ms < LONG_STEP_MS)
+        return undefined;
+    const ms = String(Math.round(longest.ms));
+    const at = longest.at;
+    if (at === undefined)
+        return `longest step ${ms} ms: finishing the project check`;
+    if (at.phase === "files" && at.done === 0 && at.rule === undefined) {
+        return `longest step ${ms} ms: building the programs`;
+    }
+    const file = at.file === undefined ? undefined : displayPath(cwd, at.file);
+    if (at.rule !== undefined && file !== undefined) {
+        return `longest step ${ms} ms: ${at.rule} on ${file}`;
+    }
+    if (at.rule !== undefined)
+        return `longest step ${ms} ms: ${at.rule} over the whole project`;
+    return `longest step ${ms} ms: ${at.phase === "files" ? "checking files" : "project rules"}`;
+}
+//# sourceMappingURL=report.js.map

package/dist/server.d.ts

@@ -0,0 +1,34 @@
+import { type Connection } from "vscode-languageserver/node";
+/** The wait after a config load, a watched-file change or a closed document, before a full pass. */
+export declare const DEBOUNCE_MS = 200;
+/** Quiet time after an edit before the fast pass (the edited file's own rules). */
+export declare const FAST_MS = 100;
+/** Quiet time after an edit before the full pass (the whole project); a save does not wait. */
+export declare const FULL_MS = 1000;
+export declare const PROGRESS_TITLE = "Stateward: checking project";
+/** Tells the extension a config's full pass started or ended, for its status bar. */
+export declare const CHECKING_NOTIFICATION = "stateward/checking";
+export declare const FIX_ALL_KIND: string;
+export declare const EXPLAIN_COMMAND = "stateward.explain";
+export declare const EXPLAIN_REQUEST = "stateward/explain";
+/** Quiet time after the last file of a nested config's project is closed, before its engine stops. */
+export declare const ENGINE_IDLE_MS: number;
+/**
+ * The least time between two writes of a config's results cache to disk: a write follows a full
+ * pass that completed, at most this often, and a config that stops (or a server that shuts down)
+ * writes what it has not written yet.
+ */
+export declare const DISK_SAVE_MS: number;
+/**
+ * Wires the stateward language server to `connection`. The caller starts listening. The returned
+ * function stops the server's timers (also done on shutdown); call it before disposing the connection.
+ */
+export declare function startServer(connection: Connection, { idleMs, cacheDir, saveMs, }?: {
+    /** How long a nested config's engine waits, with none of its files open, before it stops. */
+    idleMs?: number;
+    /** The results cache folder of a project, as the CLI finds it; undefined for none. */
+    cacheDir?: (project: string) => string | undefined;
+    /** The least time between two writes of a config's results cache. */
+    saveMs?: number;
+}): () => void;
+//# sourceMappingURL=server.d.ts.map