@mrclrchtr/supi-code-intelligence 3.2.0 → 4.1.0

package/src/session/health-workflow.ts

@@ -0,0 +1,341 @@
+/** Session-owned workspace health workflow. */
+
+import type { CapabilityState } from "@mrclrchtr/supi-code-runtime/api";
+import type {
+  LspRuntimeController,
+  WorkspaceLspRuntime,
+  WorkspaceLspRuntimeState,
+} from "@mrclrchtr/supi-lsp/api";
+import {
+  evaluateCapabilityWarnings,
+  gatherCapabilityWarningInput,
+} from "../analysis/capability/capability-warnings.ts";
+import {
+  collectDiagnostics,
+  diagnosticScope,
+  isScopedFile,
+} from "../analysis/health/diagnostics.ts";
+import { describeStructuralState, recoverDiagnosticRuntime } from "../analysis/health/recovery.ts";
+import { collectServers } from "../analysis/health/signals.ts";
+import { resolveScope } from "../analysis/search/paths.ts";
+import { refreshLspMaintenance } from "../substrate/lsp/maintenance.ts";
+import type { CapabilityAdapter } from "./capability-adapter.ts";
+import type {
+  HealthData,
+  HealthDiagnosticScope,
+  HealthRefreshAttempt,
+  HealthRefreshState,
+  HealthSection,
+  HealthWorkflowInput,
+  HealthWorkflowOutcome,
+  SemanticHealthState,
+} from "./health-types.ts";
+import type { InputValidation } from "./input/common.ts";
+import { parseHealthWorkflowInput } from "./input/health-refactor.ts";
+import { reportProgress, throwIfAborted, type WorkflowControl } from "./workflow-control.ts";
+
+const DEFAULT_INCLUDE: readonly HealthSection[] = ["diagnostics", "servers"];
+
+export interface HealthWorkflowDeps {
+  readonly cwd: string;
+  readonly capability: CapabilityAdapter;
+  readonly lspController: LspRuntimeController | null;
+  readonly lastRefreshAttempt: HealthRefreshAttempt | null;
+  readonly trackRefreshAttempt: (attempt: HealthRefreshAttempt) => void;
+  /** Workspace sentinel snapshot for change detection. */
+  readonly sentinelSnapshot: Map<string, number>;
+}
+
+/** Collect health facts without rendering a public result. */
+export async function runHealthWorkflow(
+  input: HealthWorkflowInput,
+  deps: HealthWorkflowDeps,
+  control?: WorkflowControl,
+): Promise<HealthWorkflowOutcome> {
+  const prepared = prepareHealthRequest(input, deps.cwd);
+  if (prepared.kind === "invalid-input") return prepared;
+  const { request, scopeFilter, included, level } = prepared.value;
+  const semanticRequested = healthNeedsSemantic(included);
+  throwIfAborted(control);
+
+  reportProgress(control, {
+    intent: "health",
+    phase: "collection",
+    message: "Collecting workspace health evidence",
+  });
+
+  const lspState = deps.capability.getLspRuntimeState(deps.cwd);
+  const capabilityStates = deps.capability.getCapabilityStates(deps.cwd);
+  const runtime = lspState.kind === "ready" ? lspState.runtime : null;
+  const serverInventoryAvailable = lspState.kind === "ready" || lspState.kind === "disabled";
+
+  const diagnosticsScope = diagnosticScope(scopeFilter);
+  const refresh = await collectRefreshState({
+    refreshRequested: request.refresh === true,
+    diagnosticsRequested: included.includes("diagnostics"),
+    runtime,
+    lspState,
+    diagnosticsScope,
+    deps,
+    control,
+  });
+  const semanticState = await establishSemanticHealthState({
+    requested: semanticRequested,
+    runtime,
+    scopeFilter,
+    lspState,
+    capabilityState: capabilityStates.semantic,
+  });
+  const semanticReady = semanticState?.kind === "ready";
+  throwIfAborted(control);
+
+  const diagnostics = await collectDiagnostics({
+    service: semanticReady ? runtime : null,
+    included,
+    scope: diagnosticsScope,
+    cwd: deps.cwd,
+    unavailableReason: diagnosticUnavailableReason(semanticState),
+    detailed: level === "detailed",
+  });
+  const servers = collectServers(runtime, included);
+  const capabilityWarnings = collectCapabilityWarnings(semanticRequested, deps);
+
+  const data: HealthData = {
+    includedSections: included,
+    semanticState,
+    serverInventoryAvailable,
+    structuralAvailable: capabilityStates.structural.kind === "ready",
+    structuralStatus: describeStructuralState(capabilityStates.structural),
+    diagnostics,
+    servers,
+    refresh,
+    level,
+    capabilityWarnings: capabilityWarnings?.hasWarnings ? capabilityWarnings : undefined,
+  };
+
+  return { kind: "completed", data };
+}
+
+function healthNeedsSemantic(included: readonly HealthSection[]): boolean {
+  return included.includes("diagnostics") || included.includes("servers");
+}
+
+interface SemanticHealthStateOptions {
+  requested: boolean;
+  runtime: WorkspaceLspRuntime | null;
+  scopeFilter: string | null;
+  lspState: WorkspaceLspRuntimeState;
+  capabilityState: CapabilityState;
+}
+
+async function establishSemanticHealthState(
+  options: SemanticHealthStateOptions,
+): Promise<SemanticHealthState | null> {
+  if (!options.requested) return null;
+  if (options.runtime && isScopedFile(options.scopeFilter)) {
+    const readiness = await options.runtime.waitUntilReadyForFile(options.scopeFilter);
+    if (readiness.kind === "ready") return { kind: "ready" };
+    if (readiness.kind === "timeout") {
+      return { kind: "pending", reason: "File semantic readiness timed out" };
+    }
+    return { kind: "unavailable", reason: readiness.reason };
+  }
+  if (
+    options.runtime
+      ?.getProjectServers()
+      .some((server) => server.status === "running" && server.ready === true)
+  ) {
+    return { kind: "ready" };
+  }
+  return deriveNonReadySemanticState(options.lspState, options.capabilityState);
+}
+
+function deriveNonReadySemanticState(
+  lspState: WorkspaceLspRuntimeState,
+  capabilityState: CapabilityState,
+): Exclude<SemanticHealthState, { kind: "ready" }> {
+  switch (lspState.kind) {
+    case "pending":
+      return { kind: "pending", reason: "LSP is starting" };
+    case "inactive":
+      return { kind: "inactive", reason: "Inactive on the current session branch" };
+    case "disabled":
+      return { kind: "disabled", reason: "Disabled by configuration" };
+    case "unavailable":
+      return { kind: "unavailable", reason: lspState.reason };
+    case "ready":
+      return deriveReadyOwnerWithoutServerState(capabilityState);
+  }
+}
+
+function deriveReadyOwnerWithoutServerState(
+  capabilityState: CapabilityState,
+): Exclude<SemanticHealthState, { kind: "ready" }> {
+  switch (capabilityState.kind) {
+    case "inactive":
+      return { kind: "inactive", reason: "Inactive on the current session branch" };
+    case "disabled":
+      return { kind: "disabled", reason: "Disabled by configuration" };
+    case "unavailable":
+      return { kind: "unavailable", reason: capabilityState.reason };
+    case "pending":
+    case "ready":
+      return { kind: "pending", reason: "No active, ready project servers" };
+  }
+}
+
+function collectCapabilityWarnings(
+  semanticRequested: boolean,
+  deps: HealthWorkflowDeps,
+): HealthData["capabilityWarnings"] {
+  if (!semanticRequested) return undefined;
+  const report = evaluateCapabilityWarnings(
+    gatherCapabilityWarningInput(deps.cwd, deps.lspController),
+  );
+  return report.hasWarnings ? report : undefined;
+}
+
+interface RefreshStateOptions {
+  readonly refreshRequested: boolean;
+  readonly diagnosticsRequested: boolean;
+  readonly runtime: WorkspaceLspRuntime | null;
+  readonly lspState: WorkspaceLspRuntimeState;
+  readonly diagnosticsScope: HealthDiagnosticScope;
+  readonly deps: HealthWorkflowDeps;
+  readonly control?: WorkflowControl;
+}
+
+/** Run the requested workspace-runtime refresh and retain only facts the runtime establishes. */
+async function collectRefreshState(options: RefreshStateOptions): Promise<HealthRefreshState> {
+  const { deps, diagnosticsRequested, diagnosticsScope, lspState, runtime } = options;
+  if (!diagnosticsRequested) {
+    return {
+      kind: "not-requested",
+      reason: "Diagnostics were not requested.",
+      lastAttempt: deps.lastRefreshAttempt,
+    };
+  }
+  if (!options.refreshRequested) {
+    return {
+      kind: "not-requested",
+      reason: "Refresh was not requested.",
+      lastAttempt: deps.lastRefreshAttempt,
+    };
+  }
+  if (!runtime) {
+    return {
+      kind: "not-attempted",
+      reason: refreshUnavailableReason(lspState),
+      lastAttempt: deps.lastRefreshAttempt,
+    };
+  }
+
+  const attemptedAt = Date.now();
+  try {
+    reportProgress(options.control, {
+      intent: "health",
+      phase: "maintenance",
+      message: "Refreshing LSP state and sentinel snapshot",
+    });
+    updateSentinelSnapshot(
+      deps.sentinelSnapshot,
+      await refreshLspMaintenance(runtime, deps.cwd, deps.sentinelSnapshot),
+    );
+    if (diagnosticsScope.kind === "file") {
+      try {
+        await runtime.waitUntilReadyForFile(diagnosticsScope.path);
+      } catch {
+        // Recovery still gets a chance to restart a failed routed client.
+      }
+    }
+
+    const recovery = await recoverDiagnosticRuntime({
+      service: runtime,
+      progress: () =>
+        reportProgress(options.control, {
+          intent: "health",
+          phase: "recovery",
+          message: "Refreshing diagnostics and recovery state",
+        }),
+    });
+    const attempt: HealthRefreshAttempt = {
+      kind: "completed",
+      attemptedAt,
+      requestedDiagnosticScope: diagnosticsScope,
+      operationScope: "workspace-runtime",
+      attemptedActiveClients: recovery.attemptedClients,
+      restartedClients: recovery.restartedClients,
+      staleAssessment: {
+        suspected: recovery.staleAssessment.suspected,
+        matchedFileCount: recovery.staleAssessment.matchedFiles.length,
+        warning: recovery.staleAssessment.warning,
+      },
+    };
+    deps.trackRefreshAttempt(attempt);
+    return attempt;
+  } catch (error) {
+    const attempt: HealthRefreshAttempt = {
+      kind: "failed",
+      attemptedAt,
+      requestedDiagnosticScope: diagnosticsScope,
+      operationScope: "workspace-runtime",
+      reason: errorMessage(error),
+    };
+    deps.trackRefreshAttempt(attempt);
+    return attempt;
+  }
+}
+
+function updateSentinelSnapshot(target: Map<string, number>, next: Map<string, number>): void {
+  target.clear();
+  for (const [key, value] of next) target.set(key, value);
+}
+
+function refreshUnavailableReason(lspState: WorkspaceLspRuntimeState): string {
+  switch (lspState.kind) {
+    case "unavailable":
+      return `LSP runtime unavailable — ${lspState.reason}`;
+    case "disabled":
+      return "LSP runtime is disabled by configuration.";
+    case "inactive":
+      return "LSP runtime is inactive on the current session branch.";
+    case "pending":
+      return "LSP runtime is still starting.";
+    case "ready":
+      return "No ready LSP runtime is available.";
+  }
+}
+
+function diagnosticUnavailableReason(state: SemanticHealthState | null): string {
+  if (!state) return "Semantic diagnostics were not requested.";
+  return state.kind === "ready" ? "No ready LSP runtime is available." : state.reason;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error && error.message ? error.message : "Diagnostic refresh failed.";
+}
+
+function prepareHealthRequest(
+  input: HealthWorkflowInput,
+  cwd: string,
+): InputValidation<{
+  request: HealthWorkflowInput;
+  scopeFilter: string | null;
+  included: HealthSection[];
+  level: "summary" | "detailed";
+}> {
+  const parsed = parseHealthWorkflowInput(input);
+  if (parsed.kind === "invalid-input") return parsed;
+  const request = parsed.value;
+  const scope = resolveScope(request.scope, cwd);
+  if (scope.kind === "error") return { kind: "invalid-input", message: scope.reason };
+  return {
+    kind: "valid",
+    value: {
+      request,
+      scopeFilter: scope.path === cwd ? null : scope.path,
+      included: request.include === undefined ? [...DEFAULT_INCLUDE] : [...request.include],
+      level: request.level ?? "summary",
+    },
+  };
+}

package/src/session/input/common.ts

@@ -0,0 +1,216 @@
+/** Common runtime input-validation primitives for session workflows. */
+
+import {
+  type AnchorTargetInput,
+  type ResolveTargetInput,
+  type SourcePointInput,
+  type SymbolTargetInput,
+  TARGET_SYMBOL_KINDS,
+  type TargetInput,
+  type TargetSymbolKind,
+} from "../target-input.ts";
+
+/** A parsed workflow input or an agent-correctable validation error. */
+export type InputValidation<T> =
+  | { readonly kind: "valid"; readonly value: T }
+  | { readonly kind: "invalid-input"; readonly message: string };
+
+const SYMBOL_KINDS = new Set<TargetSymbolKind>(TARGET_SYMBOL_KINDS);
+
+type TargetBranch = "handle" | "anchor" | "symbol" | "file";
+
+export function valid<T>(value: T): InputValidation<T> {
+  return { kind: "valid", value };
+}
+
+export function invalid<T = never>(message: string): InputValidation<T> {
+  return { kind: "invalid-input", message };
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function requireRecord(
+  value: unknown,
+  label: string,
+): InputValidation<Record<string, unknown>> {
+  return isRecord(value) ? valid(value) : invalid(`${label} must be an object.`);
+}
+
+export function requireOnlyKeys(
+  value: Record<string, unknown>,
+  allowed: readonly string[],
+  label: string,
+): string | null {
+  const unexpected = Object.keys(value).filter((key) => !allowed.includes(key));
+  return unexpected.length > 0
+    ? `${label} contains unsupported field${unexpected.length === 1 ? "" : "s"}: ${unexpected.map((key) => `\`${key}\``).join(", ")}.`
+    : null;
+}
+
+export function requireString(
+  value: unknown,
+  label: string,
+  options: { nonEmpty?: boolean } = {},
+): InputValidation<string> {
+  if (typeof value !== "string") return invalid(`${label} must be a string.`);
+  if (options.nonEmpty && value.trim().length === 0) return invalid(`${label} must not be empty.`);
+  return valid(value);
+}
+
+export function optionalString(
+  value: unknown,
+  label: string,
+  options: { nonEmpty?: boolean } = {},
+): InputValidation<string | undefined> {
+  return value === undefined ? valid(undefined) : requireString(value, label, options);
+}
+
+export function optionalPositiveInteger(
+  value: unknown,
+  label: string,
+): InputValidation<number | undefined> {
+  if (value === undefined) return valid(undefined);
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+    return invalid(`${label} must be a positive integer.`);
+  }
+  return valid(value);
+}
+
+export function optionalNonNegativeInteger(
+  value: unknown,
+  label: string,
+): InputValidation<number | undefined> {
+  if (value === undefined) return valid(undefined);
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+    return invalid(`${label} must be a non-negative integer.`);
+  }
+  return valid(value);
+}
+
+export function parsePosition(
+  value: unknown,
+  label: string,
+): InputValidation<Omit<SourcePointInput, "file">> {
+  const record = requireRecord(value, label);
+  if (record.kind === "invalid-input") return record;
+  const keysError = requireOnlyKeys(record.value, ["line", "character"], label);
+  if (keysError) return invalid(keysError);
+  const line = optionalPositiveInteger(record.value.line, `${label}.line`);
+  if (line.kind === "invalid-input" || line.value === undefined) {
+    return line.kind === "invalid-input" ? line : invalid(`${label}.line is required.`);
+  }
+  const character = optionalPositiveInteger(record.value.character, `${label}.character`);
+  if (character.kind === "invalid-input" || character.value === undefined) {
+    return character.kind === "invalid-input"
+      ? character
+      : invalid(`${label}.character is required.`);
+  }
+  return valid({ line: line.value, character: character.value });
+}
+
+/** Parse one exact 1-based source point. */
+export function parseSourcePoint(
+  value: unknown,
+  label = "point",
+): InputValidation<SourcePointInput> {
+  const record = requireRecord(value, label);
+  if (record.kind === "invalid-input") return record;
+  const keysError = requireOnlyKeys(record.value, ["file", "line", "character"], label);
+  if (keysError) return invalid(keysError);
+  const file = requireString(record.value.file, `${label}.file`, { nonEmpty: true });
+  if (file.kind === "invalid-input") return file;
+  const position = parsePosition(
+    { line: record.value.line, character: record.value.character },
+    label,
+  );
+  if (position.kind === "invalid-input") return position;
+  return valid({ file: file.value, ...position.value });
+}
+
+function parseSymbolTarget(value: unknown): InputValidation<SymbolTargetInput> {
+  const record = requireRecord(value, "target.symbol");
+  if (record.kind === "invalid-input") return record;
+  const keysError = requireOnlyKeys(
+    record.value,
+    ["query", "scope", "symbolKind"],
+    "target.symbol",
+  );
+  if (keysError) return invalid(keysError);
+  const query = requireString(record.value.query, "target.symbol.query", { nonEmpty: true });
+  if (query.kind === "invalid-input") return query;
+  const scope = optionalString(record.value.scope, "target.symbol.scope", { nonEmpty: true });
+  if (scope.kind === "invalid-input") return scope;
+  const symbolKind = optionalString(record.value.symbolKind, "target.symbol.symbolKind");
+  if (symbolKind.kind === "invalid-input") return symbolKind;
+  if (symbolKind.value !== undefined && !SYMBOL_KINDS.has(symbolKind.value as TargetSymbolKind)) {
+    return invalid(
+      "target.symbol.symbolKind must be a provider-reported LSP SymbolKind; omit it when the provider category is uncertain.",
+    );
+  }
+  return valid({
+    query: query.value,
+    ...(scope.value === undefined ? {} : { scope: scope.value }),
+    ...(symbolKind.value === undefined ? {} : { symbolKind: symbolKind.value as TargetSymbolKind }),
+  });
+}
+
+/** Parse an exact-one target selector and enforce the branches an intent supports. */
+export function parseTargetInput(
+  value: unknown,
+  allowed: readonly TargetBranch[],
+): InputValidation<TargetInput> {
+  const record = requireRecord(value, "target");
+  if (record.kind === "invalid-input") return record;
+  const keysError = requireOnlyKeys(record.value, ["handle", "anchor", "symbol", "file"], "target");
+  if (keysError) return invalid(keysError);
+  const selected = (["handle", "anchor", "symbol", "file"] as const).filter(
+    (key) => record.value[key] !== undefined,
+  );
+  if (selected.length !== 1) {
+    return invalid(
+      "A target selector must contain exactly one of `handle`, `anchor`, `symbol`, or `file`.",
+    );
+  }
+  const branch = selected[0];
+  if (!allowed.includes(branch)) return invalid(`This workflow does not support target.${branch}.`);
+
+  switch (branch) {
+    case "handle": {
+      const handle = requireString(record.value.handle, "target.handle", { nonEmpty: true });
+      return handle.kind === "valid" ? valid({ handle: handle.value }) : handle;
+    }
+    case "anchor": {
+      const anchor = parseSourcePoint(record.value.anchor, "target.anchor");
+      return anchor.kind === "valid"
+        ? valid({ anchor: anchor.value } satisfies AnchorTargetInput)
+        : anchor;
+    }
+    case "symbol": {
+      const symbol = parseSymbolTarget(record.value.symbol);
+      return symbol.kind === "valid" ? valid({ symbol: symbol.value }) : symbol;
+    }
+    case "file": {
+      const file = requireString(record.value.file, "target.file", { nonEmpty: true });
+      return file.kind === "valid" ? valid({ file: file.value }) : file;
+    }
+  }
+}
+
+export function parseResolveRequest(
+  value: unknown,
+): InputValidation<{ readonly target: ResolveTargetInput; readonly maxResults?: number }> {
+  const record = requireRecord(value, "code_resolve input");
+  if (record.kind === "invalid-input") return record;
+  const keysError = requireOnlyKeys(record.value, ["target", "maxResults"], "code_resolve input");
+  if (keysError) return invalid(keysError);
+  const target = parseTargetInput(record.value.target, ["anchor", "symbol", "file"]);
+  if (target.kind === "invalid-input") return target;
+  const maxResults = optionalPositiveInteger(record.value.maxResults, "maxResults");
+  if (maxResults.kind === "invalid-input") return maxResults;
+  return valid({
+    target: target.value as ResolveTargetInput,
+    ...(maxResults.value === undefined ? {} : { maxResults: maxResults.value }),
+  });
+}