@mrclrchtr/supi-code-intelligence 3.2.0 → 4.0.0

package/src/session/inspect/file-point.ts

@@ -0,0 +1,69 @@
+/** Filesystem and UTF-16 validation for exact point inspection. */
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { relative } from "node:path";
+import { normalizePath } from "../../analysis/search/paths.ts";
+import type { InputValidation } from "../input/common.ts";
+import type { SourcePointInput } from "../target-input.ts";
+
+export interface ValidatedInspectPoint {
+  readonly file: string;
+  readonly relPath: string;
+  readonly line: number;
+  readonly character: number;
+  readonly lineCount: number;
+}
+
+/** Validate a readable regular file and an in-bounds 1-based UTF-16 point. */
+export function validateInspectPoint(
+  point: SourcePointInput,
+  cwd: string,
+): InputValidation<ValidatedInspectPoint> {
+  const file = normalizePath(point.file, cwd);
+  if (!existsSync(file)) {
+    return { kind: "invalid-input", message: `File not found: \`${point.file}\`` };
+  }
+
+  try {
+    if (!statSync(file).isFile()) {
+      return { kind: "invalid-input", message: `Not a regular file: \`${point.file}\`` };
+    }
+  } catch {
+    return { kind: "invalid-input", message: `Cannot access file: \`${point.file}\`` };
+  }
+
+  let source: string;
+  try {
+    source = readFileSync(file, "utf-8");
+  } catch {
+    return { kind: "invalid-input", message: `Cannot read file: \`${point.file}\`` };
+  }
+
+  const lines = source.replace(/\r\n?/g, "\n").split("\n");
+  if (point.line > lines.length) {
+    return {
+      kind: "invalid-input",
+      message: `Point line ${point.line} is beyond the end of \`${point.file}\` (${lines.length} lines).`,
+    };
+  }
+
+  const lineText = lines[point.line - 1] ?? "";
+  const maximumCharacter = lineText.length + 1;
+  if (point.character > maximumCharacter) {
+    return {
+      kind: "invalid-input",
+      message: `Point character ${point.character} is beyond line ${point.line} of \`${point.file}\` (maximum ${maximumCharacter}, 1-based UTF-16).`,
+    };
+  }
+
+  return {
+    kind: "valid",
+    value: {
+      file,
+      relPath: relative(cwd, file) || point.file,
+      line: point.line,
+      character: point.character,
+      lineCount: lines.length,
+    },
+  };
+}

package/src/session/inspect-types.ts

@@ -0,0 +1,78 @@
+import type { CodeQueryResult, ConfidenceMode } from "@mrclrchtr/supi-code-runtime/api";
+import type { SourcePointInput } from "./target-input.ts";
+
+/** Canonical code_inspect workflow input. */
+export interface InspectWorkflowInput {
+  readonly point: SourcePointInput;
+  readonly maxResults?: number;
+}
+
+export type InspectObservation<T> = CodeQueryResult<T>;
+
+export interface InspectNode {
+  readonly type: string;
+  readonly text: string;
+  readonly startLine: number;
+  readonly startCharacter: number;
+  readonly endLine: number;
+  readonly endCharacter: number;
+  readonly ancestry: ReadonlyArray<{
+    readonly type: string;
+    readonly startLine: number;
+    readonly startCharacter: number;
+    readonly endLine: number;
+    readonly endCharacter: number;
+  }>;
+}
+
+export interface InspectEnclosingSymbol {
+  readonly name: string;
+  readonly kind: string;
+  readonly startLine: number;
+  readonly startCharacter: number;
+  readonly endLine: number;
+  readonly endCharacter: number;
+}
+
+export interface InspectDefinition {
+  readonly file: string;
+  readonly line: number;
+  readonly character: number;
+}
+
+export interface InspectDiagnostic {
+  readonly line: number;
+  readonly character: number;
+  readonly endLine: number;
+  readonly endCharacter: number;
+  readonly severity: number;
+  readonly message: string;
+}
+
+export interface InspectSections {
+  readonly node: InspectObservation<InspectNode | null>;
+  readonly enclosingSymbol: InspectObservation<InspectEnclosingSymbol | null>;
+  readonly hover: InspectObservation<string | null>;
+  readonly definition: InspectObservation<readonly InspectDefinition[]>;
+  readonly diagnostics: InspectObservation<readonly InspectDiagnostic[]>;
+}
+
+/** Presentation-neutral point inspection facts and per-section collection state. */
+export interface InspectResultData {
+  readonly relPath: string;
+  readonly line: number;
+  readonly character: number;
+  readonly maxResults: number;
+  readonly confidence: ConfidenceMode;
+  readonly diagnosticWindow: { readonly startLine: number; readonly endLine: number };
+  readonly sections: InspectSections;
+}
+
+export type InspectWorkflowOutcome =
+  | {
+      readonly kind: "completed";
+      readonly data: InspectResultData;
+      readonly nextQueries: readonly string[];
+    }
+  | { readonly kind: "invalid-input"; readonly message: string }
+  | { readonly kind: "unavailable"; readonly reason: string };

package/src/session/inspect-workflow.ts

@@ -0,0 +1,157 @@
+/** Session-owned point inspection workflow. */
+
+import type { WorkspaceLspRuntimeState } from "@mrclrchtr/supi-lsp/api";
+import type { CapabilityAdapter, ReadinessOutcome } from "./capability-adapter.ts";
+import { parseInspectWorkflowInput } from "./input/workflows.ts";
+import { collectInspectSections } from "./inspect/collect.ts";
+import { validateInspectPoint } from "./inspect/file-point.ts";
+import type {
+  InspectDefinition,
+  InspectResultData,
+  InspectSections,
+  InspectWorkflowInput,
+  InspectWorkflowOutcome,
+} from "./inspect-types.ts";
+import { reportProgress, throwIfAborted, type WorkflowControl } from "./workflow-control.ts";
+
+export interface InspectWorkflowDeps {
+  readonly cwd: string;
+  readonly capability: CapabilityAdapter;
+}
+
+/** Collect exact point facts without assembling or rendering a Tool result. */
+export async function runInspectWorkflow(
+  input: InspectWorkflowInput,
+  deps: InspectWorkflowDeps,
+  control?: WorkflowControl,
+): Promise<InspectWorkflowOutcome> {
+  const parsed = parseInspectWorkflowInput(input);
+  if (parsed.kind === "invalid-input") return parsed;
+  const request = parsed.value;
+  const point = validateInspectPoint(request.point, deps.cwd);
+  if (point.kind === "invalid-input") return point;
+  throwIfAborted(control);
+
+  reportProgress(control, {
+    intent: "inspect",
+    phase: "providers",
+    message: "Collecting point facts",
+  });
+  const readiness = await deps.capability.ensureSemanticReadiness(deps.cwd, {
+    kind: "file",
+    file: point.value.file,
+  });
+  throwIfAborted(control);
+
+  const semanticReady = readiness.kind === "ready";
+  const semantic = semanticReady ? deps.capability.getSemanticProvider(deps.cwd) : null;
+  const lspState = semanticReady
+    ? deps.capability.getLspRuntimeState(deps.cwd)
+    : unavailableLspState(readiness);
+  const sections = await collectInspectSections({
+    cwd: deps.cwd,
+    file: point.value.file,
+    line: point.value.line,
+    character: point.value.character,
+    lineCount: point.value.lineCount,
+    structural: deps.capability.getStructuralProvider(deps.cwd),
+    semantic,
+    semanticUnavailableReason: semantic
+      ? "Semantic point query unavailable."
+      : semanticReadinessReason(readiness),
+    lspState,
+  });
+  throwIfAborted(control);
+
+  if (everySectionUnavailable(sections)) {
+    return {
+      kind: "unavailable",
+      reason: "No semantic, structural, or diagnostic provider could inspect this point.",
+    };
+  }
+
+  const data: InspectResultData = {
+    relPath: point.value.relPath,
+    line: point.value.line,
+    character: point.value.character,
+    maxResults: request.maxResults ?? 5,
+    confidence: inspectConfidence(sections),
+    diagnosticWindow: {
+      startLine: Math.max(1, point.value.line - 2),
+      endLine: Math.min(point.value.lineCount, point.value.line + 2),
+    },
+    sections,
+  };
+  const definitions =
+    sections.definition.kind === "unavailable" ? [] : [...sections.definition.data];
+
+  return {
+    kind: "completed",
+    data,
+    nextQueries: Object.freeze(buildInspectNextQueries(data.relPath, definitions, semanticReady)),
+  };
+}
+
+function buildInspectNextQueries(
+  relPath: string,
+  definitions: readonly InspectDefinition[],
+  semanticReady: boolean,
+): string[] {
+  const queries: string[] = [];
+  const definition = definitions[0];
+  if (semanticReady && definition) {
+    const anchor = JSON.stringify({
+      file: definition.file,
+      line: definition.line,
+      character: definition.character,
+    });
+    queries.push(
+      `Use code_resolve with target.anchor ${anchor}, then code_graph with the returned handle`,
+    );
+  } else if (!semanticReady) {
+    queries.push(
+      `Use code_health with scope "${relPath}", refresh true, and include ["diagnostics","servers"] before semantic target or graph work`,
+    );
+  }
+  queries.push(`Use code_orientation with focus.path "${relPath}" for broader orientation`);
+  return queries;
+}
+
+function everySectionUnavailable(sections: InspectSections): boolean {
+  return (
+    sections.node.kind === "unavailable" &&
+    sections.enclosingSymbol.kind === "unavailable" &&
+    sections.hover.kind === "unavailable" &&
+    sections.definition.kind === "unavailable" &&
+    sections.diagnostics.kind === "unavailable"
+  );
+}
+
+function inspectConfidence(sections: InspectSections): InspectResultData["confidence"] {
+  const semanticAvailable =
+    sections.hover.kind !== "unavailable" ||
+    sections.definition.kind !== "unavailable" ||
+    sections.diagnostics.kind !== "unavailable";
+  if (semanticAvailable) return "semantic";
+  const structuralAvailable =
+    sections.node.kind !== "unavailable" || sections.enclosingSymbol.kind !== "unavailable";
+  return structuralAvailable ? "structural" : "unavailable";
+}
+
+function unavailableLspState(readiness: ReadinessOutcome): WorkspaceLspRuntimeState {
+  return {
+    kind: "unavailable",
+    reason: semanticReadinessReason(readiness),
+  };
+}
+
+function semanticReadinessReason(readiness: ReadinessOutcome): string {
+  switch (readiness.kind) {
+    case "ready":
+      return "No semantic provider is active for this file.";
+    case "timeout":
+      return "Semantic readiness timed out.";
+    case "unavailable":
+      return readiness.reason;
+  }
+}