@stateward/language-server 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the stateward authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,13 @@
-# Temporary Holding Version
+# @stateward/language-server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The language server behind the Stateward VS Code extension: [stateward](https://github.com/khoing1111/ts-stateward#readme)'s
+findings as you type, quick fixes, and hints about the errors a function can throw, for any editor
+that speaks the Language Server Protocol.
+
+```bash
+npm install --save-dev @stateward/language-server
+```
+
+Start it with `npx stateward-language-server`. It talks over stdin and stdout and checks the
+project of the nearest `stateward.config.ts`. The VS Code extension uses the copy installed in your
+project, else its own.

package/dist/adoption.d.ts

@@ -0,0 +1,73 @@
+import type { CheckResult, Config, PlanRow } from "@stateward/core/internal";
+import { type Counts } from "./report.js";
+export declare const STATUS_NOTIFICATION = "stateward/status";
+export declare const PLAN_REQUEST = "stateward/plan";
+export declare const NEXT_REQUEST = "stateward/next";
+export declare const RECHECK_REQUEST = "stateward/recheck";
+/** Where the project stands after a full pass: the counts and, with rollout on, the rule being fixed. */
+export type StatusReport = Counts & {
+    /** Findings the baseline accepts: not in the counts above. */
+    baselined: number;
+    /** Set when the config turns no rule on (a plugin alone turns nothing on). */
+    noRulesOn?: true;
+    rollout: {
+        on: boolean;
+        /** The rule turned on last and its findings; absent when rollout is off or no rule is on yet. */
+        current?: {
+            ruleId: string;
+            findings: number;
+        };
+        enabled: number;
+        total: number;
+    };
+};
+/**
+ * The status for a full pass of `config`. `result` is the configured pass, which has the findings
+ * of every rule that is on, which is all the status needs: the current rule is one of them.
+ */
+export declare function statusReport(config: Config, result: CheckResult, baselined?: number): StatusReport;
+/** The answer to `stateward/plan`: the plan rows, in order, and where the rollout stands. */
+export type PlanAnswer = {
+    rollout: boolean;
+    /** The rules turned on, in order; empty when rollout is off (every rule runs then). */
+    enabled: readonly string[];
+    rules: readonly PlanRow[];
+};
+/** `result` must come from a run of the `all` selection, like `stateward plan`. */
+export declare function planAnswer(config: Config, result: CheckResult): PlanAnswer;
+/** The answer to `stateward/next`. Every kind carries the text to show. */
+export type NextAnswer = {
+    kind: "turned-on";
+    message: string;
+} | {
+    kind: "all-on";
+    message: string;
+}
+/** The rule turned on last still has findings; asking again with `anyway` moves on. */
+ | {
+    kind: "blocked";
+    message: string;
+} | {
+    kind: "rollout-off";
+    message: string;
+}
+/** The config cannot be used, a rule failed or the rollout file is broken. */
+ | {
+    kind: "failed";
+    message: string;
+};
+/** The `stateward/next` params are not `{ anyway?: boolean }`. */
+export declare class InvalidNextParamsError extends Error {
+    constructor();
+}
+/** The `anyway` flag of the params; nothing sent means false. */
+export declare function parseNextParams(params: unknown): boolean;
+/** What the editor tells the developer when the project has no rollout. */
+export declare function rolloutOffAnswer(configFileName: string): NextAnswer;
+/**
+ * What `stateward next` does: writes the rollout file through core's writer and says what it did
+ * in the CLI's words. `result` must come from a run of the `all` selection. A rule that failed
+ * makes the plan incomplete, so nothing is written then.
+ */
+export declare function applyNext(config: Config, result: CheckResult, anyway: boolean): NextAnswer;
+//# sourceMappingURL=adoption.d.ts.map

package/dist/adoption.js

@@ -0,0 +1,122 @@
+import { RolloutError, advance, buildPlan, describeTurnOn, readRollout, ruleIsOn, writeRollout, } from "@stateward/core/internal";
+import { countFindings } from "./report.js";
+export const STATUS_NOTIFICATION = "stateward/status";
+export const PLAN_REQUEST = "stateward/plan";
+export const NEXT_REQUEST = "stateward/next";
+export const RECHECK_REQUEST = "stateward/recheck";
+/** Whether the config turns any rule on, in itself or in an override. */
+function anyRuleOn(config) {
+    return config.plugins.some((plugin) => Object.entries(plugin.rules).some(([key, rule]) => ruleIsOn(config, plugin.name, key, rule.meta)));
+}
+/**
+ * The status for a full pass of `config`. `result` is the configured pass, which has the findings
+ * of every rule that is on, which is all the status needs: the current rule is one of them.
+ */
+export function statusReport(config, result, baselined = 0) {
+    const counts = {
+        ...countFindings(result),
+        ...(anyRuleOn(config) ? {} : { noRulesOn: true }),
+    };
+    if (!config.rollout) {
+        return { ...counts, baselined, rollout: { on: false, enabled: 0, total: 0 } };
+    }
+    const enabled = readRollout(config);
+    const plan = buildPlan(config, result);
+    const lastId = enabled.at(-1);
+    const last = plan.rules.find((row) => row.ruleId === lastId);
+    return {
+        ...counts,
+        baselined,
+        rollout: {
+            on: true,
+            ...(last === undefined ? {} : { current: { ruleId: last.ruleId, findings: last.findings } }),
+            enabled: enabled.length,
+            total: plan.rules.length,
+        },
+    };
+}
+/** `result` must come from a run of the `all` selection, like `stateward plan`. */
+export function planAnswer(config, result) {
+    return {
+        rollout: config.rollout,
+        enabled: config.rollout ? readRollout(config) : [],
+        rules: buildPlan(config, result).rules,
+    };
+}
+function countOf(count, noun) {
+    return `${String(count)} ${noun}${count === 1 ? "" : "s"}`;
+}
+/** The `stateward/next` params are not `{ anyway?: boolean }`. */
+export class InvalidNextParamsError extends Error {
+    constructor() {
+        super("stateward/next expects { anyway?: boolean }");
+        this.name = "InvalidNextParamsError";
+        Object.setPrototypeOf(this, InvalidNextParamsError.prototype);
+    }
+}
+/** The `anyway` flag of the params; nothing sent means false. */
+export function parseNextParams(params) {
+    if (params === null || params === undefined)
+        return false;
+    if (typeof params !== "object")
+        throw new InvalidNextParamsError();
+    if (!("anyway" in params))
+        return false;
+    if (typeof params.anyway !== "boolean")
+        throw new InvalidNextParamsError();
+    return params.anyway;
+}
+/** What the editor tells the developer when the project has no rollout. */
+export function rolloutOffAnswer(configFileName) {
+    return {
+        kind: "rollout-off",
+        message: `Turn on \`rollout: true\` in ${configFileName} first: without it every rule runs, and there is no next rule to turn on.`,
+    };
+}
+/**
+ * What `stateward next` does: writes the rollout file through core's writer and says what it did
+ * in the CLI's words. `result` must come from a run of the `all` selection. A rule that failed
+ * makes the plan incomplete, so nothing is written then.
+ */
+export function applyNext(config, result, anyway) {
+    const failures = result.findings.filter((finding) => finding.kind === "failure");
+    if (failures.length > 0) {
+        return { kind: "failed", message: failures.map((finding) => finding.message).join("\n") };
+    }
+    try {
+        const enabled = readRollout(config);
+        const step = advance(buildPlan(config, result), enabled, anyway);
+        switch (step.kind) {
+            case "all-on":
+                return {
+                    kind: "all-on",
+                    message: "Every rule is on; you can remove stateward.rollout.json and `rollout`.",
+                };
+            case "blocked":
+                return {
+                    kind: "blocked",
+                    message: `\`${step.row.ruleId}\` still has ${countOf(step.row.findings, "finding")}; fix them, turn the next rule on anyway, or accept them with \`stateward baseline\` in a terminal.`,
+                };
+            case "turn-on": {
+                // The rule with findings goes last: it is the one the next step waits on.
+                const clean = step.clean.map((row) => row.ruleId);
+                writeRollout(config, [
+                    ...enabled,
+                    ...clean,
+                    ...(step.row === undefined ? [] : [step.row.ruleId]),
+                ]);
+                return { kind: "turned-on", message: describeTurnOn(step).join("\n") };
+            }
+            default: {
+                const unreachable = step;
+                return unreachable;
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof RolloutError)
+            return { kind: "failed", message: error.message };
+        throw error;
+    }
+}
+//# sourceMappingURL=adoption.js.map

package/dist/baseline.d.ts

@@ -0,0 +1,17 @@
+import type { CheckResult, Config, Finding, HiddenFindings } from "@stateward/core/internal";
+/** What the editor shows after the baseline is laid over a pass. */
+export type BaselinedPass = {
+    /** New and baselined findings together, in the order of a plain check. */
+    findings: readonly Finding[];
+    hidden: readonly HiddenFindings[];
+    /** The findings the baseline accepts: shown as hints. */
+    baselined: ReadonlySet<Finding>;
+    /** Only the new ones, for the counts. */
+    fresh: CheckResult;
+};
+/**
+ * Lays the project's baseline (if it has one) over an uncapped `result`. `ran` is the rules the
+ * pass ran. Throws `BaselineError` for a baseline file that cannot be used; the caller reports it.
+ */
+export declare function layBaseline(config: Config, result: CheckResult, ran: ReadonlySet<string>, open: ReadonlyMap<string, string>): BaselinedPass;
+//# sourceMappingURL=baseline.d.ts.map

package/dist/baseline.js

@@ -0,0 +1,32 @@
+import { readFileSync } from "node:fs";
+import { applyBaseline, compareFindings, readBaseline } from "@stateward/core/internal";
+/** The text of `file` as the editor has it: unsaved text first, then the disk. */
+function textOf(open, file) {
+    const unsaved = open.get(file);
+    if (unsaved !== undefined)
+        return unsaved;
+    try {
+        return readFileSync(file, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Lays the project's baseline (if it has one) over an uncapped `result`. `ran` is the rules the
+ * pass ran. Throws `BaselineError` for a baseline file that cannot be used; the caller reports it.
+ */
+export function layBaseline(config, result, ran, open) {
+    const view = applyBaseline(readBaseline(config), result, {
+        configDir: config.configDir,
+        readText: (file) => textOf(open, file),
+        ran,
+    });
+    return {
+        findings: [...view.fresh.findings, ...view.baselined].sort(compareFindings),
+        hidden: view.fresh.hidden,
+        baselined: new Set(view.baselined),
+        fresh: view.fresh,
+    };
+}
+//# sourceMappingURL=baseline.js.map

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { createConnection } from "vscode-languageserver/node";
+import { limitHeapGrowth } from "./memory.js";
+import { startServer } from "./server.js";
+limitHeapGrowth();
+const connection = createConnection(process.stdin, process.stdout);
+startServer(connection);
+connection.listen();
+//# sourceMappingURL=bin.js.map

package/dist/configs.d.ts

@@ -0,0 +1,13 @@
+/** The innermost of `folders` that holds `file`, or undefined when none does. */
+export declare function folderOf(file: string, folders: readonly string[]): string | undefined;
+/** Which config each file belongs to: the nearest `stateward.config.*` above it, inside the workspace folders. */
+export type ConfigLocator = {
+    /** The config file of `file`, or undefined when no config above it is inside a workspace folder. */
+    configOf(file: string): string | undefined;
+    /** The configs at the root of a workspace folder, in the folders' order: checked from the start. */
+    rootConfigs(): readonly string[];
+    /** A config file was created or deleted: look again. */
+    forget(): void;
+};
+export declare function createConfigLocator(folders: readonly string[]): ConfigLocator;
+//# sourceMappingURL=configs.d.ts.map

package/dist/configs.js

@@ -0,0 +1,53 @@
+import path from "node:path";
+import { findConfigFile, findConfigUpward, toTypeScriptPath } from "@stateward/core/internal";
+/** Whether `file` is `folder` or inside it (paths compared as TypeScript writes them). */
+function isInside(file, folder) {
+    const relative = path.relative(folder, file);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+/** The innermost of `folders` that holds `file`, or undefined when none does. */
+export function folderOf(file, folders) {
+    return folders
+        .filter((folder) => isInside(file, folder))
+        .sort((a, b) => b.length - a.length)
+        .at(0);
+}
+/**
+ * The outermost of `folders` that holds `file`: where the config search stops. With nested
+ * workspace folders (`/repo` and `/repo/packages/app`), a file of the inner one still finds the
+ * config at `/repo`.
+ */
+function outermostFolderOf(file, folders) {
+    return folders
+        .filter((folder) => isInside(file, folder))
+        .sort((a, b) => a.length - b.length)
+        .at(0);
+}
+export function createConfigLocator(folders) {
+    /** By folder: the config that folder's files belong to (null: none), so a lookup walks once. */
+    const known = new Map();
+    return {
+        configOf(file) {
+            const folder = outermostFolderOf(file, folders);
+            if (folder === undefined)
+                return undefined;
+            const dir = toTypeScriptPath(path.dirname(file));
+            let found = known.get(dir);
+            if (found === undefined) {
+                found = findConfigUpward(path.dirname(file), folder) ?? null;
+                known.set(dir, found);
+            }
+            return found ?? undefined;
+        },
+        rootConfigs() {
+            return folders.flatMap((folder) => {
+                const found = findConfigFile(folder);
+                return found === undefined ? [] : [found];
+            });
+        },
+        forget() {
+            known.clear();
+        },
+    };
+}
+//# sourceMappingURL=configs.js.map

package/dist/explain.d.ts

@@ -0,0 +1,11 @@
+import type { Config } from "@stateward/core/internal";
+/** The `stateward/explain` request's params are not `{ ruleId: string }`. */
+export declare class InvalidExplainParamsError extends Error {
+    constructor();
+}
+/**
+ * The markdown for the rule id in `params`; null for an id no rule has, or when there is no config
+ * (the folder is not set up); a lazy rule's module is loaded for it. It is the text of the installed version, so it works offline.
+ */
+export declare function answerExplain(config: Config | undefined, params: unknown): Promise<string | null>;
+//# sourceMappingURL=explain.d.ts.map

package/dist/explain.js

@@ -0,0 +1,22 @@
+import { explain } from "@stateward/core/internal";
+/** The `stateward/explain` request's params are not `{ ruleId: string }`. */
+export class InvalidExplainParamsError extends Error {
+    constructor() {
+        super("stateward/explain expects { ruleId: string }");
+        this.name = "InvalidExplainParamsError";
+    }
+}
+/**
+ * The markdown for the rule id in `params`; null for an id no rule has, or when there is no config
+ * (the folder is not set up); a lazy rule's module is loaded for it. It is the text of the installed version, so it works offline.
+ */
+export async function answerExplain(config, params) {
+    if (typeof params !== "object" || params === null || !("ruleId" in params)) {
+        throw new InvalidExplainParamsError();
+    }
+    const { ruleId } = params;
+    if (typeof ruleId !== "string")
+        throw new InvalidExplainParamsError();
+    return config === undefined ? null : ((await explain(config, ruleId)) ?? null);
+}
+//# sourceMappingURL=explain.js.map

package/dist/fix-all.d.ts

@@ -0,0 +1,44 @@
+import type { FixForm } from "@stateward/core/internal";
+import type { CodeAction, Range, TextEdit, WorkspaceEdit } from "vscode-languageserver/node";
+/**
+ * Where one finding is, and the quick fixes it offers (the first is the one "fix all" applies).
+ * `extra` are offered after them but never applied by "fix all": "Ignore this case here" is a
+ * decision for a person, not a fix.
+ */
+export type FixSite = {
+    range: Range;
+    actions: readonly CodeAction[];
+    extra?: readonly CodeAction[];
+    /** The fix of the first action as core offered it, for verifying the fixes of a file together. */
+    form?: FixForm;
+};
+/**
+ * Verifies the fixes "fix all" chose (by site index) as one set (`Checker.verifyFixSet`): which
+ * are kept, and the edits of this file that apply them, imports they leave unused removed.
+ */
+export type VerifyFixSet = (chosen: readonly number[]) => {
+    kept: readonly boolean[];
+    edits: readonly TextEdit[];
+};
+/**
+ * One edit for the file `uri` that applies the first fix of every site, in file order. A fix goes
+ * in whole or not at all: it is left out when it edits another file, or clashes with a fix already
+ * taken (the earlier site wins). With `verify`, the fixes taken are then tried together: one
+ * that breaks with the others is left out, and imports the set leaves unused are removed. `count` is the number of fixes taken.
+ */
+export declare function fixAllEdits(sites: readonly FixSite[], uri: string, verify?: VerifyFixSet): {
+    edits: readonly TextEdit[];
+    count: number;
+};
+/** Whether a code action request with these `only` kinds wants an action of `kind` (`source` covers `source.fixAll`). */
+export declare function kindWanted(only: readonly string[] | undefined, kind: string): boolean;
+/**
+ * The same edit as `documentChanges`, each document with the version the fixes were computed
+ * against (`null`: the file is not open, so there is no version to check). The editor rejects an
+ * edit whose version is not the document's current one, so a fix computed before an edit can
+ * never be applied to the text after it.
+ */
+export declare function versionedEdit(changes: Readonly<Record<string, readonly TextEdit[]>>, versionOf: (uri: string) => number | null): WorkspaceEdit;
+/** `action` with its `changes` edit turned into versioned `documentChanges`; unchanged when it has none. */
+export declare function versionedAction(action: CodeAction, versionOf: (uri: string) => number | null): CodeAction;
+//# sourceMappingURL=fix-all.d.ts.map

package/dist/fix-all.js

@@ -0,0 +1,92 @@
+function compare(a, b) {
+    return a.line - b.line || a.character - b.character;
+}
+/**
+ * Edits clash when their ranges share a character, or both insert at one point; two equal edits
+ * (two fixes adding the same import) do not, and are made once.
+ */
+function clashes(a, b) {
+    if (a.newText === b.newText && compare(a.range.start, b.range.start) === 0) {
+        if (compare(a.range.end, b.range.end) === 0)
+            return false;
+    }
+    return clash(a.range, b.range);
+}
+function clash(a, b) {
+    if (compare(a.start, a.end) === 0 && compare(b.start, b.end) === 0) {
+        return compare(a.start, b.start) === 0;
+    }
+    return compare(a.start, b.end) < 0 && compare(b.start, a.end) < 0;
+}
+function independent(edits) {
+    return edits.every((edit, i) => edits.slice(i + 1).every((other) => !clash(edit.range, other.range)));
+}
+/**
+ * One edit for the file `uri` that applies the first fix of every site, in file order. A fix goes
+ * in whole or not at all: it is left out when it edits another file, or clashes with a fix already
+ * taken (the earlier site wins). With `verify`, the fixes taken are then tried together: one
+ * that breaks with the others is left out, and imports the set leaves unused are removed. `count` is the number of fixes taken.
+ */
+export function fixAllEdits(sites, uri, verify) {
+    const taken = [];
+    const chosen = [];
+    for (const [index, site] of sites.entries()) {
+        const changes = site.actions[0]?.edit?.changes;
+        if (changes === undefined)
+            continue;
+        const files = Object.keys(changes);
+        const edits = changes[uri];
+        if (files.length !== 1 || edits === undefined || edits.length === 0)
+            continue;
+        if (!independent(edits))
+            continue;
+        if (edits.some((edit) => taken.some((other) => clashes(edit, other))))
+            continue;
+        taken.push(...edits.filter((edit) => !taken.some((other) => same(edit, other))));
+        chosen.push(index);
+    }
+    if (verify === undefined || chosen.length === 0) {
+        return {
+            edits: taken.sort((a, b) => compare(a.range.start, b.range.start)),
+            count: chosen.length,
+        };
+    }
+    const review = verify(chosen);
+    return {
+        edits: [...review.edits].sort((a, b) => compare(a.range.start, b.range.start)),
+        count: review.kept.filter((kept) => kept).length,
+    };
+}
+function same(a, b) {
+    return (a.newText === b.newText &&
+        compare(a.range.start, b.range.start) === 0 &&
+        compare(a.range.end, b.range.end) === 0);
+}
+/** Whether a code action request with these `only` kinds wants an action of `kind` (`source` covers `source.fixAll`). */
+export function kindWanted(only, kind) {
+    if (only === undefined || only.length === 0)
+        return true;
+    return only.some((wanted) => kind === wanted || kind.startsWith(`${wanted}.`));
+}
+/**
+ * The same edit as `documentChanges`, each document with the version the fixes were computed
+ * against (`null`: the file is not open, so there is no version to check). The editor rejects an
+ * edit whose version is not the document's current one, so a fix computed before an edit can
+ * never be applied to the text after it.
+ */
+export function versionedEdit(changes, versionOf) {
+    return {
+        documentChanges: Object.entries(changes).map(([uri, edits]) => ({
+            textDocument: { uri, version: versionOf(uri) },
+            edits: [...edits],
+        })),
+    };
+}
+/** `action` with its `changes` edit turned into versioned `documentChanges`; unchanged when it has none. */
+export function versionedAction(action, versionOf) {
+    const changes = action.edit?.changes;
+    if (changes === undefined)
+        return action;
+    return { ...action, edit: versionedEdit(changes, versionOf) };
+}
+//# sourceMappingURL=fix-all.js.map

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { startServer } from "./server.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,2 @@
+export { startServer } from "./server.js";
+//# sourceMappingURL=index.js.map

package/dist/inlay-hints.d.ts

@@ -0,0 +1,22 @@
+import { type InlayHint } from "vscode-languageserver/node";
+import type { EditorHint } from "@stateward/core/internal";
+import { type LineIndex } from "./mapping.js";
+/**
+ * Which kinds of inline hint are on, by the kind a plugin gives its hints
+ * (`stateward.inlayHints.<kind>` in the editor's settings). A kind the settings do not mention is
+ * on.
+ */
+export type HintSettings = ReadonlyMap<string, boolean>;
+export declare const DEFAULT_HINT_SETTINGS: HintSettings;
+/**
+ * The hint settings from the `stateward` section of the editor's settings
+ * (`{ inlayHints: { throws: false } }`); anything else is "all on".
+ */
+export declare function readHintSettings(section: unknown): HintSettings;
+export declare function hintEnabled(settings: HintSettings, kind: string): boolean;
+/** The LSP hints of the plugins' hints that fall inside `range` (offsets, end excluded), as plain type labels. */
+export declare function toInlayHints(hints: readonly EditorHint[], index: LineIndex, range: {
+    start: number;
+    end: number;
+}): InlayHint[];
+//# sourceMappingURL=inlay-hints.d.ts.map

package/dist/inlay-hints.js

@@ -0,0 +1,34 @@
+import { InlayHintKind, MarkupKind } from "vscode-languageserver/node";
+import { positionAt } from "./mapping.js";
+export const DEFAULT_HINT_SETTINGS = new Map();
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * The hint settings from the `stateward` section of the editor's settings
+ * (`{ inlayHints: { throws: false } }`); anything else is "all on".
+ */
+export function readHintSettings(section) {
+    const hints = isRecord(section) ? section.inlayHints : undefined;
+    if (!isRecord(hints))
+        return DEFAULT_HINT_SETTINGS;
+    return new Map(Object.entries(hints).flatMap(([kind, on]) => (typeof on === "boolean" ? [[kind, on]] : [])));
+}
+export function hintEnabled(settings, kind) {
+    return settings.get(kind) !== false;
+}
+/** The LSP hints of the plugins' hints that fall inside `range` (offsets, end excluded), as plain type labels. */
+export function toInlayHints(hints, index, range) {
+    return hints
+        .filter((hint) => hint.offset >= range.start && hint.offset <= range.end)
+        .map((hint) => ({
+        position: positionAt(index, hint.offset),
+        label: hint.label,
+        kind: InlayHintKind.Type,
+        ...(hint.paddingLeft === true ? { paddingLeft: true } : {}),
+        ...(hint.tooltip === undefined
+            ? {}
+            : { tooltip: { kind: MarkupKind.Markdown, value: hint.tooltip } }),
+    }));
+}
+//# sourceMappingURL=inlay-hints.js.map

package/dist/mapping.d.ts

@@ -0,0 +1,52 @@
+import { DiagnosticSeverity, type CodeAction, type Diagnostic, type Position, type Range, type SemanticTokens, type TextEdit as LspTextEdit } from "vscode-languageserver";
+import type { Finding, HiddenFindings, Location, Severity, TextEdit, TokenType } from "@stateward/core/internal";
+/** Where each line of a text starts, so offsets and positions convert without rescanning. */
+export type LineIndex = {
+    readonly starts: readonly number[];
+    readonly length: number;
+};
+export declare function buildLineIndex(text: string): LineIndex;
+/** The 0-based line and UTF-16 character of `offset`, clamped to the text. */
+export declare function positionAt(index: LineIndex, offset: number): Position;
+/** The offset of `position`, clamped to the end of its line (and to the text). */
+export declare function offsetAt(index: LineIndex, position: Position): number;
+export declare function toRange(index: LineIndex, location: Location): Range;
+export declare function toDiagnosticSeverity(severity: Severity): DiagnosticSeverity;
+export type FileMapper = {
+    uriOf: (file: string) => string;
+    indexOf: (file: string) => LineIndex;
+    /** The text of a file as the editor has it. */
+    textOf: (file: string) => string;
+};
+/**
+ * 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 declare function toDiagnostic(finding: Finding, files: FileMapper, baselined?: boolean): Diagnostic;
+/** An information at the start of the file for findings that are counted but not listed. */
+export declare function toHiddenDiagnostic(hidden: HiddenFindings): Diagnostic;
+/** Core's edits as LSP edits, by document URI. */
+export declare function toLspChanges(edits: readonly TextEdit[], files: FileMapper): Record<string, LspTextEdit[]>;
+/**
+ * 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 declare function toCodeActions(finding: Finding, diagnostic: Diagnostic, files: FileMapper): CodeAction[];
+/**
+ * "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 declare function toIgnoreAction(finding: Finding, diagnostic: Diagnostic, files: FileMapper): CodeAction | undefined;
+/** Ranges that overlap or touch. */
+export declare function rangesIntersect(a: Range, b: Range): boolean;
+/** The LSP semantic token legend: the TokenType list, in index order. */
+export declare const TOKEN_TYPES: readonly string[];
+/**
+ * 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 declare function encodeTokens(tokens: readonly {
+    location: Location;
+    type: TokenType;
+}[], index: LineIndex): SemanticTokens;
+//# sourceMappingURL=mapping.d.ts.map