@mrclrchtr/supi-code-intelligence 3.2.0 → 4.1.0

package/src/session/input/health-refactor.ts

@@ -0,0 +1,169 @@
+/** Runtime parsers for health and refactor session workflows. */
+
+import type { HealthSection, HealthWorkflowInput } from "../health-types.ts";
+import type {
+  PublicSourceRange,
+  RefactorApplyWorkflowInput,
+  RefactorOperationInput,
+  RefactorPlanWorkflowInput,
+} from "../refactor-types.ts";
+import type { RefactorTargetInput } from "../target-input.ts";
+import {
+  type InputValidation,
+  invalid,
+  optionalString,
+  parsePosition,
+  parseTargetInput,
+  requireOnlyKeys,
+  requireRecord,
+  requireString,
+  valid,
+} from "./common.ts";
+
+const HEALTH_SECTIONS = new Set<HealthSection>(["diagnostics", "servers"]);
+
+export function parseHealthWorkflowInput(value: unknown): InputValidation<HealthWorkflowInput> {
+  const record = requireRecord(value, "code_health input");
+  if (record.kind === "invalid-input") return record;
+  const keysError = requireOnlyKeys(
+    record.value,
+    ["scope", "refresh", "include", "level"],
+    "code_health input",
+  );
+  if (keysError) return invalid(keysError);
+  const scope = optionalString(record.value.scope, "scope");
+  if (scope.kind === "invalid-input") return scope;
+  const refresh = parseRefresh(record.value.refresh);
+  if (refresh.kind === "invalid-input") return refresh;
+  const level = parseHealthLevel(record.value.level);
+  if (level.kind === "invalid-input") return level;
+  const include = parseHealthSections(record.value.include);
+  if (include.kind === "invalid-input") return include;
+  return valid({
+    ...(scope.value === undefined ? {} : { scope: scope.value }),
+    ...(refresh.value === undefined ? {} : { refresh: refresh.value }),
+    ...(include.value === undefined ? {} : { include: include.value }),
+    ...(level.value === undefined ? {} : { level: level.value }),
+  });
+}
+
+function parseRefresh(value: unknown): InputValidation<boolean | undefined> {
+  if (value === undefined || typeof value === "boolean") return valid(value);
+  return invalid("refresh must be a boolean.");
+}
+
+function parseHealthLevel(value: unknown): InputValidation<"summary" | "detailed" | undefined> {
+  if (value === undefined || value === "summary" || value === "detailed") return valid(value);
+  return invalid('level must be "summary" or "detailed".');
+}
+
+function parseHealthSections(
+  value: unknown,
+): InputValidation<readonly HealthSection[] | undefined> {
+  if (value === undefined) return valid(undefined);
+  if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
+    return invalid("include must be an array of health sections.");
+  }
+  if (
+    new Set(value).size !== value.length ||
+    !value.every((item) => HEALTH_SECTIONS.has(item as HealthSection))
+  ) {
+    return invalid("include contains an unsupported or duplicate health section.");
+  }
+  return valid(value as HealthSection[]);
+}
+
+export function parseRefactorPlanWorkflowInput(
+  value: unknown,
+): InputValidation<RefactorPlanWorkflowInput> {
+  const record = requireRecord(value, "code_refactor_plan input");
+  if (record.kind === "invalid-input") return record;
+  const keysError = requireOnlyKeys(
+    record.value,
+    ["target", "operation"],
+    "code_refactor_plan input",
+  );
+  if (keysError) return invalid(keysError);
+  const target = parseTargetInput(record.value.target, ["handle", "anchor"]);
+  if (target.kind === "invalid-input") return target;
+  const operation = parseRefactorOperation(record.value.operation);
+  if (operation.kind === "invalid-input") return operation;
+  return valid({ target: target.value as RefactorTargetInput, operation: operation.value });
+}
+
+function parseRefactorOperation(value: unknown): InputValidation<RefactorOperationInput> {
+  const record = requireRecord(value, "operation");
+  if (record.kind === "invalid-input") return record;
+  const keysError = requireOnlyKeys(
+    record.value,
+    ["rename_symbol", "extract_function", "extract_variable"],
+    "operation",
+  );
+  if (keysError) return invalid(keysError);
+  const selected = (["rename_symbol", "extract_function", "extract_variable"] as const).filter(
+    (key) => record.value[key] !== undefined,
+  );
+  if (selected.length !== 1) return invalid("Select exactly one refactor operation.");
+
+  const name = selected[0];
+  const payload = requireRecord(record.value[name], `operation.${name}`);
+  if (payload.kind === "invalid-input") return payload;
+  if (name === "rename_symbol") return parseRenameOperation(payload.value);
+  return parseExtractOperation(name, payload.value);
+}
+
+function parseRenameOperation(
+  payload: Record<string, unknown>,
+): InputValidation<RefactorOperationInput> {
+  const payloadError = requireOnlyKeys(payload, ["newName"], "operation.rename_symbol");
+  if (payloadError) return invalid(payloadError);
+  const newName = requireString(payload.newName, "operation.rename_symbol.newName", {
+    nonEmpty: true,
+  });
+  return newName.kind === "valid" ? valid({ rename_symbol: { newName: newName.value } }) : newName;
+}
+
+function parseExtractOperation(
+  name: "extract_function" | "extract_variable",
+  payload: Record<string, unknown>,
+): InputValidation<RefactorOperationInput> {
+  const payloadError = requireOnlyKeys(payload, ["newName", "range"], `operation.${name}`);
+  if (payloadError) return invalid(payloadError);
+  const newName = requireString(payload.newName, `operation.${name}.newName`, { nonEmpty: true });
+  if (newName.kind === "invalid-input") return newName;
+  const range = parsePublicRange(payload.range);
+  if (range.kind === "invalid-input") return range;
+  return name === "extract_function"
+    ? valid({ extract_function: { newName: newName.value, range: range.value } })
+    : valid({ extract_variable: { newName: newName.value, range: range.value } });
+}
+
+function parsePublicRange(value: unknown): InputValidation<PublicSourceRange> {
+  const record = requireRecord(value, "range");
+  if (record.kind === "invalid-input") return record;
+  const keysError = requireOnlyKeys(record.value, ["start", "end"], "range");
+  if (keysError) return invalid(keysError);
+  const start = parsePosition(record.value.start, "range.start");
+  if (start.kind === "invalid-input") return start;
+  const end = parsePosition(record.value.end, "range.end");
+  if (end.kind === "invalid-input") return end;
+  if (
+    end.value.line < start.value.line ||
+    (end.value.line === start.value.line && end.value.character <= start.value.character)
+  ) {
+    return invalid("range.end must be after range.start.");
+  }
+  return valid({ start: start.value, end: end.value });
+}
+
+export function parseRefactorApplyWorkflowInput(
+  value: unknown,
+): InputValidation<RefactorApplyWorkflowInput> {
+  const record = requireRecord(value, "code_refactor_apply input");
+  if (record.kind === "invalid-input") return record;
+  const keysError = requireOnlyKeys(record.value, ["planId"], "code_refactor_apply input");
+  if (keysError) return invalid(keysError);
+  const planId = requireString(record.value.planId, "planId");
+  if (planId.kind === "invalid-input") return planId;
+  return planId.value.trim() ? valid({ planId: planId.value }) : invalid("planId is required.");
+}

package/src/session/input/workflows.ts

@@ -0,0 +1,211 @@
+/** Runtime parsers for inspection, Orientation, graph, and find workflows. */
+
+import { type CodeFindAstKind, isCodeFindAstKind } from "../../tool/find/ast-kinds.ts";
+import { CODE_FIND_MODES } from "../../tool/find/modes.ts";
+import type { FindMode, FindWorkflowInput } from "../find-types.ts";
+import type { GraphWorkflowInput, RequestedGraphRelation } from "../graph-types.ts";
+import type { InspectWorkflowInput } from "../inspect-types.ts";
+import type { OrientationFocusInput, OrientationWorkflowInput } from "../orientation-types.ts";
+import type { GraphTargetInput, OrientationTargetInput } from "../target-input.ts";
+import {
+  type InputValidation,
+  invalid,
+  optionalPositiveInteger,
+  parseSourcePoint,
+  parseTargetInput,
+  requireOnlyKeys,
+  requireRecord,
+  requireString,
+  valid,
+} from "./common.ts";
+
+const FIND_MODES = new Set<FindMode>(CODE_FIND_MODES);
+const GRAPH_RELATIONS = new Set<RequestedGraphRelation>([
+  "all",
+  "references",
+  "callees",
+  "implements",
+]);
+
+export function parseInspectWorkflowInput(value: unknown): InputValidation<InspectWorkflowInput> {
+  const record = requireRecord(value, "code_inspect input");
+  if (record.kind === "invalid-input") return record;
+  const keysError = requireOnlyKeys(record.value, ["point", "maxResults"], "code_inspect input");
+  if (keysError) return invalid(keysError);
+  const point = parseSourcePoint(record.value.point);
+  if (point.kind === "invalid-input") return point;
+  const maxResults = optionalPositiveInteger(record.value.maxResults, "maxResults");
+  if (maxResults.kind === "invalid-input") return maxResults;
+  return valid({
+    point: point.value,
+    ...(maxResults.value === undefined ? {} : { maxResults: maxResults.value }),
+  });
+}
+
+export function parseOrientationWorkflowInput(
+  value: unknown,
+): InputValidation<OrientationWorkflowInput> {
+  const record = requireRecord(value, "code_orientation input");
+  if (record.kind === "invalid-input") return record;
+  const keysError = requireOnlyKeys(
+    record.value,
+    ["focus", "maxResults"],
+    "code_orientation input",
+  );
+  if (keysError) return invalid(keysError);
+  const focus = parseOrientationFocus(record.value.focus);
+  if (focus.kind === "invalid-input") return focus;
+  const maxResults = optionalPositiveInteger(record.value.maxResults, "maxResults");
+  if (maxResults.kind === "invalid-input") return maxResults;
+  return valid({
+    ...(focus.value === undefined ? {} : { focus: focus.value }),
+    ...(maxResults.value === undefined ? {} : { maxResults: maxResults.value }),
+  });
+}
+
+function parseOrientationFocus(value: unknown): InputValidation<OrientationFocusInput | undefined> {
+  if (value === undefined) return valid(undefined);
+  const record = requireRecord(value, "focus");
+  if (record.kind === "invalid-input") return record;
+  const keysError = requireOnlyKeys(record.value, ["path", "module", "target"], "focus");
+  if (keysError) return invalid(keysError);
+  const selected = (["path", "module", "target"] as const).filter(
+    (key) => record.value[key] !== undefined,
+  );
+  if (selected.length !== 1) {
+    return invalid("focus must contain exactly one of `path`, `module`, or `target`.");
+  }
+  if (selected[0] === "path") {
+    const path = requireString(record.value.path, "focus.path", { nonEmpty: true });
+    return path.kind === "valid" ? valid({ path: path.value }) : path;
+  }
+  if (selected[0] === "module") {
+    const module = requireString(record.value.module, "focus.module", { nonEmpty: true });
+    return module.kind === "valid" ? valid({ module: module.value }) : module;
+  }
+  const target = parseTargetInput(record.value.target, ["handle", "anchor", "symbol"]);
+  return target.kind === "valid"
+    ? valid({ target: target.value as OrientationTargetInput })
+    : target;
+}
+
+export function parseGraphWorkflowInput(value: unknown): InputValidation<GraphWorkflowInput> {
+  const record = requireRecord(value, "code_graph input");
+  if (record.kind === "invalid-input") return record;
+  const keysError = requireOnlyKeys(
+    record.value,
+    ["target", "relations", "calleeDepth", "maxResults"],
+    "code_graph input",
+  );
+  if (keysError) return invalid(keysError);
+  const target = parseTargetInput(record.value.target, ["handle", "anchor", "symbol"]);
+  if (target.kind === "invalid-input") return target;
+  const relations = parseRelations(record.value.relations);
+  if (relations.kind === "invalid-input") return relations;
+  const calleeDepth = parseCalleeDepth(record.value.calleeDepth);
+  if (calleeDepth.kind === "invalid-input") return calleeDepth;
+  const maxResults = optionalPositiveInteger(record.value.maxResults, "maxResults");
+  if (maxResults.kind === "invalid-input") return maxResults;
+  return valid({
+    target: target.value as GraphTargetInput,
+    ...(relations.value === undefined ? {} : { relations: relations.value }),
+    ...(calleeDepth.value === undefined ? {} : { calleeDepth: calleeDepth.value }),
+    ...(maxResults.value === undefined ? {} : { maxResults: maxResults.value }),
+  });
+}
+
+function parseRelations(
+  value: unknown,
+): InputValidation<readonly RequestedGraphRelation[] | undefined> {
+  if (value === undefined) return valid(undefined);
+  if (
+    !Array.isArray(value) ||
+    value.length === 0 ||
+    !value.every((item) => typeof item === "string")
+  ) {
+    return invalid("relations must be a non-empty array of supported relation names.");
+  }
+  if (
+    new Set(value).size !== value.length ||
+    !value.every((item) => GRAPH_RELATIONS.has(item as RequestedGraphRelation))
+  ) {
+    return invalid("relations contains an unsupported or duplicate relation.");
+  }
+  if (value.includes("all") && value.length !== 1) {
+    return invalid('`relations: ["all"]` cannot be combined with named relations.');
+  }
+  return valid(value as RequestedGraphRelation[]);
+}
+
+function parseCalleeDepth(value: unknown): InputValidation<"direct" | "deep" | undefined> {
+  if (value === undefined) return valid(undefined);
+  return value === "direct" || value === "deep"
+    ? valid(value)
+    : invalid('calleeDepth must be "direct" or "deep".');
+}
+
+export function parseFindWorkflowInput(value: unknown): InputValidation<FindWorkflowInput> {
+  const record = requireRecord(value, "code_find input");
+  if (record.kind === "invalid-input") return record;
+  const keysError = requireOnlyKeys(
+    record.value,
+    ["query", "scope", "mode", "kind", "maxResults"],
+    "code_find input",
+  );
+  if (keysError) return invalid(keysError);
+  const query = requireString(record.value.query, "query", { nonEmpty: true });
+  if (query.kind === "invalid-input") return query;
+  const scope = parseFindScope(record.value.scope);
+  if (scope.kind === "invalid-input") return scope;
+  const mode = parseFindMode(record.value.mode);
+  if (mode.kind === "invalid-input") return mode;
+  const patternKind = parsePatternKind(record.value.kind);
+  if (patternKind.kind === "invalid-input") return patternKind;
+  const modeError = validateFindModeFields(mode.value, patternKind.value);
+  if (modeError) return invalid(modeError);
+  const maxResults = optionalPositiveInteger(record.value.maxResults, "maxResults");
+  if (maxResults.kind === "invalid-input") return maxResults;
+  return valid({
+    query: query.value,
+    ...(scope.value === undefined ? {} : { scope: scope.value }),
+    mode: mode.value,
+    ...(patternKind.value === undefined ? {} : { kind: patternKind.value }),
+    ...(maxResults.value === undefined ? {} : { maxResults: maxResults.value }),
+  });
+}
+
+function parseFindScope(value: unknown): InputValidation<readonly string[] | undefined> {
+  if (value === undefined) return valid(undefined);
+  if (
+    !Array.isArray(value) ||
+    value.length === 0 ||
+    !value.every((item) => typeof item === "string")
+  ) {
+    return invalid("scope must be a non-empty array of workspace-relative paths.");
+  }
+  if (value.some((item) => item.trim().length === 0)) {
+    return invalid("scope must not contain empty paths.");
+  }
+  return valid(value);
+}
+
+function parseFindMode(value: unknown): InputValidation<FindMode> {
+  return typeof value === "string" && FIND_MODES.has(value as FindMode)
+    ? valid(value as FindMode)
+    : invalid("mode is required and must be one of ast or semantic.");
+}
+
+function parsePatternKind(value: unknown): InputValidation<CodeFindAstKind | undefined> {
+  if (value === undefined) return valid(undefined);
+  return isCodeFindAstKind(value) ? valid(value) : invalid("Unsupported AST kind.");
+}
+
+function validateFindModeFields(
+  mode: FindMode,
+  patternKind: CodeFindAstKind | undefined,
+): string | null {
+  if (mode === "ast" && patternKind === undefined) return 'mode "ast" requires kind.';
+  return mode !== "ast" && patternKind !== undefined
+    ? `kind is not valid with mode "${mode}".`
+    : null;
+}

package/src/session/inspect/collect.ts

@@ -0,0 +1,304 @@
+/** Independent substrate collection for exact point inspection. */
+
+import {
+  type CodePosition,
+  mapCodeQueryResult,
+  type OutlineData,
+  type SemanticProvider,
+  type StructuralProvider,
+  unavailableCodeQuery,
+} from "@mrclrchtr/supi-code-runtime/api";
+import { uriToFile } from "@mrclrchtr/supi-core/path";
+import type { WorkspaceLspRuntimeState } from "@mrclrchtr/supi-lsp/api";
+import { relativeDisplayPath } from "../../analysis/search/paths.ts";
+import { diagnosticMessageString } from "../../substrate/lsp/utils.ts";
+import type {
+  InspectDefinition,
+  InspectDiagnostic,
+  InspectEnclosingSymbol,
+  InspectNode,
+  InspectObservation,
+  InspectSections,
+} from "../inspect-types.ts";
+
+export interface InspectCollectionInput {
+  readonly cwd: string;
+  readonly file: string;
+  readonly line: number;
+  readonly character: number;
+  readonly lineCount: number;
+  readonly structural: StructuralProvider | null;
+  readonly semantic: SemanticProvider | null;
+  readonly semanticUnavailableReason: string;
+  readonly lspState: WorkspaceLspRuntimeState;
+}
+
+/** Collect every inspection section independently so one failure cannot erase siblings. */
+export async function collectInspectSections(
+  input: InspectCollectionInput,
+): Promise<InspectSections> {
+  const node = await collectNode(input);
+  const enclosingSymbol = await collectEnclosingSymbol(input);
+  const hover = await collectHover(input);
+  const definition = await collectDefinition(input);
+  const diagnostics = await collectDiagnostics(input);
+  return { node, enclosingSymbol, hover, definition, diagnostics };
+}
+
+async function collectNode(
+  input: InspectCollectionInput,
+): Promise<InspectObservation<InspectNode | null>> {
+  if (!input.structural) return unavailableCodeQuery("No structural node provider is active.");
+  try {
+    const result = await input.structural.nodeAt(input.file, input.line, input.character);
+    if (result.kind !== "success") return unavailableCodeQuery(result.message);
+    return {
+      kind: "completed",
+      data: {
+        type: result.data.type,
+        text: result.data.text,
+        startLine: result.data.startLine,
+        startCharacter: result.data.startCharacter,
+        endLine: result.data.endLine,
+        endCharacter: result.data.endCharacter,
+        ancestry: result.data.ancestry ?? [],
+      },
+    };
+  } catch (error) {
+    return unavailableCodeQuery(failureReason("Structural node lookup", error));
+  }
+}
+
+async function collectEnclosingSymbol(
+  input: InspectCollectionInput,
+): Promise<InspectObservation<InspectEnclosingSymbol | null>> {
+  if (!input.structural) return unavailableCodeQuery("No structural outline provider is active.");
+  try {
+    const result = await input.structural.outline(input.file);
+    if (result.kind !== "success") return unavailableCodeQuery(result.message);
+    return {
+      kind: "completed",
+      data: narrowestEnclosingSymbol(result.data, {
+        line: input.line,
+        character: input.character,
+      }),
+    };
+  } catch (error) {
+    return unavailableCodeQuery(failureReason("Structural outline lookup", error));
+  }
+}
+
+async function collectHover(
+  input: InspectCollectionInput,
+): Promise<InspectObservation<string | null>> {
+  if (!input.semantic?.hover) return unavailableCodeQuery(input.semanticUnavailableReason);
+  try {
+    return mapCodeQueryResult(
+      await input.semantic.hover(input.file, toLspPosition(input)),
+      (hover) => hover?.contents ?? null,
+    );
+  } catch (error) {
+    return unavailableCodeQuery(failureReason("Hover lookup", error));
+  }
+}
+
+async function collectDefinition(
+  input: InspectCollectionInput,
+): Promise<InspectObservation<readonly InspectDefinition[]>> {
+  if (!input.semantic?.definition) return unavailableCodeQuery(input.semanticUnavailableReason);
+  try {
+    const result = await input.semantic.definition(input.file, toLspPosition(input));
+    if (result.kind === "unavailable") return result;
+    const definitions: InspectDefinition[] = [];
+    let invalidCount = 0;
+    for (const location of result.data) {
+      try {
+        const file = uriToFile(location.uri);
+        definitions.push({
+          file: relativeDisplayPath(input.cwd, file, file),
+          line: location.range.start.line + 1,
+          character: location.range.start.character + 1,
+        });
+      } catch {
+        invalidCount++;
+      }
+    }
+    const reasons = [
+      ...(result.kind === "partial" ? [result.reason] : []),
+      ...(invalidCount > 0 ? [`${invalidCount} invalid definition location(s) omitted.`] : []),
+    ];
+    return reasons.length > 0
+      ? { kind: "partial", data: definitions, reason: reasons.join(" ") }
+      : { kind: "completed", data: definitions };
+  } catch (error) {
+    return unavailableCodeQuery(failureReason("Definition lookup", error));
+  }
+}
+
+async function collectDiagnostics(
+  input: InspectCollectionInput,
+): Promise<InspectObservation<readonly InspectDiagnostic[]>> {
+  if (input.lspState.kind !== "ready") {
+    return unavailableCodeQuery(lspUnavailableReason(input.lspState));
+  }
+  try {
+    const result = await input.lspState.runtime.fileDiagnostics(input.file, 4);
+    if (result.kind === "unavailable") return result;
+    const diagnostics = result.data
+      .filter((diagnostic) => diagnosticOverlapsWindow(diagnostic.range, input))
+      .map((diagnostic) => ({
+        line: diagnostic.range.start.line + 1,
+        character: diagnostic.range.start.character + 1,
+        endLine: diagnostic.range.end.line + 1,
+        endCharacter: diagnostic.range.end.character + 1,
+        severity: diagnostic.severity ?? 1,
+        message: diagnosticMessageString(diagnostic),
+      }))
+      .sort((left, right) => compareDiagnostics(left, right, input.line));
+    return result.kind === "partial"
+      ? { kind: "partial", data: diagnostics, reason: result.reason }
+      : { kind: "completed", data: diagnostics };
+  } catch (error) {
+    return unavailableCodeQuery(failureReason("Diagnostic lookup", error));
+  }
+}
+
+function toLspPosition(input: Pick<InspectCollectionInput, "line" | "character">): CodePosition {
+  return { line: input.line - 1, character: input.character - 1 };
+}
+
+interface OutlineCandidate extends InspectEnclosingSymbol {
+  readonly depth: number;
+  readonly order: number;
+}
+
+function narrowestEnclosingSymbol(
+  outline: readonly OutlineData[],
+  point: { line: number; character: number },
+): InspectEnclosingSymbol | null {
+  const candidates = flattenOutline(outline).filter((candidate) => containsPoint(candidate, point));
+  const selected = candidates.sort(compareOutlineCandidates)[0];
+  if (!selected) return null;
+  const { depth: _depth, order: _order, ...symbol } = selected;
+  return symbol;
+}
+
+function flattenOutline(
+  outline: readonly OutlineData[],
+  depth = 0,
+  state: { order: number } = { order: 0 },
+): OutlineCandidate[] {
+  return outline.flatMap((item) => {
+    const candidate: OutlineCandidate = {
+      name: item.name,
+      kind: item.kind,
+      startLine: item.startLine,
+      startCharacter: item.startCharacter,
+      endLine: item.endLine,
+      endCharacter: item.endCharacter,
+      depth,
+      order: state.order++,
+    };
+    return [candidate, ...flattenOutline(item.children ?? [], depth + 1, state)];
+  });
+}
+
+function containsPoint(
+  range: InspectEnclosingSymbol,
+  point: { line: number; character: number },
+): boolean {
+  return (
+    comparePosition(range.startLine, range.startCharacter, point.line, point.character) <= 0 &&
+    comparePosition(point.line, point.character, range.endLine, range.endCharacter) < 0
+  );
+}
+
+function compareOutlineCandidates(left: OutlineCandidate, right: OutlineCandidate): number {
+  const leftContainsRight = containsRange(left, right);
+  const rightContainsLeft = containsRange(right, left);
+  if (leftContainsRight !== rightContainsLeft) return leftContainsRight ? 1 : -1;
+
+  // Provider ranges may overlap without nesting. Prefer the smaller full range,
+  // then use source order so malformed or duplicate outlines remain deterministic.
+  const byLineSpan = left.endLine - left.startLine - (right.endLine - right.startLine);
+  const byCharacterSpan =
+    left.endCharacter - left.startCharacter - (right.endCharacter - right.startCharacter);
+  return (
+    byLineSpan ||
+    byCharacterSpan ||
+    right.depth - left.depth ||
+    comparePosition(left.startLine, left.startCharacter, right.startLine, right.startCharacter) ||
+    left.order - right.order
+  );
+}
+
+function containsRange(outer: InspectEnclosingSymbol, inner: InspectEnclosingSymbol): boolean {
+  return (
+    comparePosition(outer.startLine, outer.startCharacter, inner.startLine, inner.startCharacter) <=
+      0 &&
+    comparePosition(outer.endLine, outer.endCharacter, inner.endLine, inner.endCharacter) >= 0
+  );
+}
+
+function diagnosticOverlapsWindow(
+  range: { start: CodePosition; end: CodePosition },
+  input: Pick<InspectCollectionInput, "line" | "lineCount">,
+): boolean {
+  const startLine = Math.max(1, input.line - 2) - 1;
+  const endExclusiveLine = Math.min(input.lineCount, input.line + 2);
+  const startsBeforeWindowEnd =
+    comparePosition(range.start.line, range.start.character, endExclusiveLine, 0) < 0;
+  const endsAfterWindowStart =
+    comparePosition(range.end.line, range.end.character, startLine, 0) > 0;
+  const emptyInsideWindow =
+    comparePosition(
+      range.start.line,
+      range.start.character,
+      range.end.line,
+      range.end.character,
+    ) === 0 &&
+    range.start.line >= startLine &&
+    range.start.line < endExclusiveLine;
+  return startsBeforeWindowEnd && (endsAfterWindowStart || emptyInsideWindow);
+}
+
+function compareDiagnostics(
+  left: InspectDiagnostic,
+  right: InspectDiagnostic,
+  pointLine: number,
+): number {
+  return (
+    Math.abs(left.line - pointLine) - Math.abs(right.line - pointLine) ||
+    left.line - right.line ||
+    left.character - right.character ||
+    left.severity - right.severity ||
+    left.message.localeCompare(right.message)
+  );
+}
+
+function comparePosition(
+  leftLine: number,
+  leftCharacter: number,
+  rightLine: number,
+  rightCharacter: number,
+): number {
+  return leftLine - rightLine || leftCharacter - rightCharacter;
+}
+
+function lspUnavailableReason(state: Exclude<WorkspaceLspRuntimeState, { kind: "ready" }>): string {
+  switch (state.kind) {
+    case "unavailable":
+      return state.reason;
+    case "pending":
+      return "LSP diagnostics are still pending.";
+    case "inactive":
+      return "LSP diagnostics are inactive.";
+    case "disabled":
+      return "LSP diagnostics are disabled.";
+  }
+}
+
+function failureReason(operation: string, error: unknown): string {
+  const detail = error instanceof Error ? error.message : String(error);
+  return `${operation} failed: ${detail}`;
+}