@mrclrchtr/supi-code-intelligence 3.2.0 → 4.0.0

package/src/session/find-workflow.ts

@@ -0,0 +1,141 @@
+/** Session-owned unified code search workflow. */
+
+import type { CodeSymbol } from "@mrclrchtr/supi-code-runtime/api";
+import { isWithinOrEqual } from "@mrclrchtr/supi-core/project";
+import { resolveScopeSet } from "../analysis/search/paths.ts";
+import { getStructuredPatternMatches } from "../analysis/search/pattern.ts";
+import { isCodeFindAstKind } from "../tool/find/ast-kinds.ts";
+import type { CapabilityAdapter } from "./capability-adapter.ts";
+import type { FindWorkflowInput, FindWorkflowOutcome } from "./find-types.ts";
+import { parseFindWorkflowInput } from "./input/workflows.ts";
+import { reportProgress, throwIfAborted, type WorkflowControl } from "./workflow-control.ts";
+
+export interface FindWorkflowDeps {
+  readonly cwd: string;
+  readonly capability: CapabilityAdapter;
+}
+
+/** Search one explicit substrate without silently falling back to another mode. */
+export async function runFindWorkflow(
+  input: FindWorkflowInput,
+  deps: FindWorkflowDeps,
+  control?: WorkflowControl,
+): Promise<FindWorkflowOutcome> {
+  const parsed = parseFindWorkflowInput(input);
+  if (parsed.kind === "invalid-input") return parsed;
+  const request = parsed.value;
+  const query = request.query;
+  const mode = request.mode;
+
+  const scope = resolveScopeSet(request.scope ? [...request.scope] : undefined, deps.cwd);
+  if (scope.kind === "error") return { kind: "invalid-input", message: scope.reason };
+
+  throwIfAborted(control);
+  reportProgress(control, {
+    intent: "find",
+    phase: mode,
+    message: `Searching in ${mode} mode`,
+  });
+
+  const maxResults = request.maxResults ?? 8;
+  const scopeLabel = scope.display ?? ".";
+  if (mode === "semantic") {
+    return runSemanticSearch({
+      query,
+      scopePaths: scope.paths,
+      scopeLabel,
+      maxResults,
+      deps,
+      control,
+    });
+  }
+  return runAstSearch({
+    query,
+    input: request,
+    scopePaths: scope.paths,
+    scopeLabel,
+    maxResults,
+    deps,
+    control,
+  });
+}
+
+async function runSemanticSearch(options: {
+  query: string;
+  scopePaths: readonly string[];
+  scopeLabel: string;
+  maxResults: number;
+  deps: FindWorkflowDeps;
+  control?: WorkflowControl;
+}): Promise<FindWorkflowOutcome> {
+  const { query, scopePaths, scopeLabel, maxResults, deps, control } = options;
+  const readiness = await deps.capability.ensureSemanticReadiness(deps.cwd, {
+    kind: "workspace",
+  });
+  if (readiness.kind === "timeout") {
+    return { kind: "unavailable", reason: "Semantic readiness timed out." };
+  }
+  if (readiness.kind === "unavailable") return readiness;
+  throwIfAborted(control);
+
+  const provider = deps.capability.getSemanticProvider(deps.cwd);
+  if (!provider?.workspaceSymbols) {
+    return { kind: "unavailable", reason: "No semantic workspace-symbol provider is active." };
+  }
+  const result = await provider.workspaceSymbols(query);
+  if (result.kind === "unavailable") {
+    return { kind: "unavailable", reason: result.reason };
+  }
+  const scopedSymbols: CodeSymbol[] = result.data.filter((symbol) =>
+    scopePaths.some((scopePath) => isWithinOrEqual(scopePath, symbol.file)),
+  );
+  return {
+    kind: "completed",
+    query,
+    mode: "semantic",
+    scopeLabel,
+    maxResults,
+    data: {
+      kind: "semantic",
+      symbols: scopedSymbols,
+      partialReason: result.kind === "partial" ? result.reason : null,
+    },
+  };
+}
+
+async function runAstSearch(options: {
+  query: string;
+  input: FindWorkflowInput;
+  scopePaths: readonly string[];
+  scopeLabel: string;
+  maxResults: number;
+  deps: FindWorkflowDeps;
+  control?: WorkflowControl;
+}): Promise<FindWorkflowOutcome> {
+  const { query, input, scopePaths, scopeLabel, maxResults, deps, control } = options;
+  if (!isCodeFindAstKind(input.kind)) {
+    return { kind: "invalid-input", message: "Unsupported AST kind." };
+  }
+  const provider = deps.capability.getStructuralProvider(deps.cwd);
+  if (!provider) {
+    return { kind: "unavailable", reason: "No structural provider is active." };
+  }
+  throwIfAborted(control);
+  const outcome = await getStructuredPatternMatches({
+    params: { pattern: query, kind: input.kind },
+    roots: scopePaths,
+    cwd: deps.cwd,
+    structural: provider,
+    control: { signal: control?.signal },
+  });
+  if (outcome.kind === "invalid-input") return outcome;
+  if (outcome.kind === "unavailable") return outcome;
+  return {
+    kind: "completed",
+    query,
+    mode: "ast",
+    scopeLabel,
+    maxResults,
+    data: { kind: "ast", astKind: input.kind, result: outcome.result },
+  };
+}

package/src/session/graph/collect.ts

@@ -0,0 +1,181 @@
+/** Presentation-neutral relation collection used by the session-owned graph workflow. */
+
+import type { CodeProvider } from "../../analysis/provider.ts";
+import {
+  readNextEnclosingScope,
+  readNextTarget,
+  readNextTopSites,
+} from "../../analysis/read-next.ts";
+import { collectCallees } from "../../analysis/relations/callees.ts";
+import { collectImplementations } from "../../analysis/relations/implementations.ts";
+import { collectCallers } from "../../analysis/relations/references.ts";
+import type { CallEntry } from "../../analysis/relations/types.ts";
+import { toDisplayPath } from "../../analysis/search/paths.ts";
+import type { GraphRelationKind, GraphSection } from "../graph-types.ts";
+import type { AnchorKind } from "../target-store.ts";
+
+/** Inputs shared by relation collectors. */
+export interface CollectRelationOptions {
+  file: string;
+  position: { line: number; character: number };
+  displayName: string;
+  cwd: string;
+  provider: CodeProvider | null;
+  maxResults: number;
+  semanticReadinessError: string | null;
+  anchorKind: AnchorKind;
+  calleeDepth?: "direct" | "deep";
+}
+
+/** Collect one evidence-backed graph relation without rendering it. */
+export async function collectRelation(
+  relation: GraphRelationKind,
+  options: CollectRelationOptions,
+): Promise<GraphSection> {
+  if (options.semanticReadinessError && (relation === "references" || relation === "implements")) {
+    return { kind: "unavailable", rel: relation, message: options.semanticReadinessError };
+  }
+
+  try {
+    switch (relation) {
+      case "references":
+        return collectReferences(options);
+      case "callees":
+        return collectCalleesRelation(options);
+      case "implements":
+        return collectImplementationsRelation(options);
+    }
+  } catch (error) {
+    return {
+      kind: "unavailable",
+      rel: relation,
+      message: error instanceof Error ? error.message : "Unknown relation failure",
+    };
+  }
+}
+
+async function collectReferences(options: CollectRelationOptions): Promise<GraphSection> {
+  if (!options.provider?.references) {
+    return { kind: "unavailable", rel: "references", message: "No semantic references provider" };
+  }
+
+  const result = await collectCallers(options.file, options.position, options.displayName, {
+    cwd: options.cwd,
+    provider: { references: options.provider.references },
+  });
+  if (result.confidence === "unavailable") {
+    return { kind: "unavailable", rel: "references", message: "References unavailable" };
+  }
+
+  const targetLine = options.position.line + 1;
+  const references = result.references;
+  return {
+    kind: "ok",
+    rel: "references",
+    data: {
+      references,
+      externalCount: result.externalCount,
+      invalidLocationCount: result.invalidLocationCount,
+      partialReason: result.partialReason,
+      confidence: "semantic",
+    },
+    readNext: [
+      readNextTarget(
+        toDisplayPath(options.cwd, options.file),
+        targetLine,
+        "inspect the resolved target before editing",
+      ),
+      ...readNextTopSites(
+        references.slice(0, options.maxResults).map((reference) => ({
+          file: toDisplayPath(options.cwd, reference.file),
+          line: reference.line,
+        })),
+        2,
+        "reference",
+      ),
+    ],
+  };
+}
+
+async function collectCalleesRelation(options: CollectRelationOptions): Promise<GraphSection> {
+  if (options.anchorKind === "declaration") {
+    return {
+      kind: "unavailable",
+      rel: "callees",
+      message:
+        "Callees require a name anchor. Resolve an identifier coordinate with code_resolve and retry.",
+    };
+  }
+  if (!options.provider?.calleesAt) {
+    return { kind: "unavailable", rel: "callees", message: "No structural callee provider" };
+  }
+
+  const result = await collectCallees(
+    options.file,
+    options.position.line + 1,
+    options.position.character + 1,
+    options.displayName,
+    { cwd: options.cwd, provider: { calleesAt: options.provider.calleesAt } },
+    undefined,
+    options.calleeDepth ?? "direct",
+  );
+  if (result.confidence === "unavailable") {
+    return { kind: "unavailable", rel: "callees", message: "Callees unavailable" };
+  }
+
+  const enclosingScope = result.enclosingScope ?? {
+    name: options.displayName,
+    file: options.file,
+    startLine: options.position.line + 1,
+    endLine: options.position.line + 1,
+  };
+  const calls: CallEntry[] = result.callees.map((callee) => ({
+    name: callee.name,
+    file: callee.file,
+    line: callee.line,
+  }));
+  return {
+    kind: "ok",
+    rel: "callees",
+    data: { enclosingScope, calls, depth: result.depth },
+    readNext: [
+      readNextEnclosingScope(
+        toDisplayPath(options.cwd, options.file),
+        enclosingScope,
+        options.position.line + 1,
+      ),
+    ],
+  };
+}
+
+async function collectImplementationsRelation(
+  options: CollectRelationOptions,
+): Promise<GraphSection> {
+  if (!options.provider?.implementation) {
+    return {
+      kind: "unavailable",
+      rel: "implements",
+      message: "No semantic implementations provider",
+    };
+  }
+
+  const result = await collectImplementations(options.file, options.position, options.displayName, {
+    cwd: options.cwd,
+    provider: { implementation: options.provider.implementation },
+  });
+  if (result.confidence === "unavailable") {
+    return { kind: "unavailable", rel: "implements", message: "Implementations unavailable" };
+  }
+
+  return {
+    kind: "ok",
+    rel: "implements",
+    data: {
+      implementations: result.implementations,
+      externalCount: result.externalCount,
+      invalidLocationCount: result.invalidLocationCount,
+      partialReason: result.partialReason,
+    },
+    readNext: [],
+  };
+}

package/src/session/graph-types.ts

@@ -0,0 +1,77 @@
+import type { ReadNextItem } from "../analysis/read-next.ts";
+import type { RelationLocationPartialReason } from "../analysis/relations/provider-locations.ts";
+import type {
+  CallEntry,
+  CalleeScope,
+  ImplementationEntry,
+  ReferenceEntry,
+} from "../analysis/relations/types.ts";
+import type { GraphTargetInput } from "./target-input.ts";
+import type { TargetWorkflowOutcome } from "./target-workflow.ts";
+
+/** Concrete graph relation families. */
+export type GraphRelationKind = "references" | "callees" | "implements";
+export type RequestedGraphRelation = GraphRelationKind | "all";
+
+/** Canonical input to the session-owned graph workflow. */
+export interface GraphWorkflowInput {
+  readonly target: GraphTargetInput;
+  readonly relations?: readonly RequestedGraphRelation[];
+  readonly calleeDepth?: "direct" | "deep";
+  readonly maxResults?: number;
+}
+
+/** Presentation-neutral relation sections. */
+export type GraphSection =
+  | {
+      readonly kind: "ok";
+      readonly rel: "references";
+      readonly data: {
+        readonly references: readonly ReferenceEntry[];
+        readonly externalCount: number;
+        readonly invalidLocationCount: number;
+        readonly partialReason: RelationLocationPartialReason | null;
+        readonly confidence: "semantic";
+      };
+      readonly readNext: readonly ReadNextItem[];
+    }
+  | {
+      readonly kind: "ok";
+      readonly rel: "callees";
+      readonly data: {
+        readonly enclosingScope: CalleeScope;
+        readonly calls: readonly CallEntry[];
+        readonly depth: "direct" | "deep";
+      };
+      readonly readNext: readonly ReadNextItem[];
+    }
+  | {
+      readonly kind: "ok";
+      readonly rel: "implements";
+      readonly data: {
+        readonly implementations: readonly ImplementationEntry[];
+        readonly externalCount: number;
+        readonly invalidLocationCount: number;
+        readonly partialReason: RelationLocationPartialReason | null;
+      };
+      readonly readNext: readonly ReadNextItem[];
+    }
+  | {
+      readonly kind: "unavailable";
+      readonly rel: GraphRelationKind;
+      readonly message: string;
+    };
+
+/** Completed graph facts after one Target workflow execution. */
+export interface CompletedGraphWorkflow {
+  readonly kind: "completed";
+  readonly displayName: string;
+  readonly resolvedDisplayFile: string;
+  readonly maxResults: number;
+  readonly sections: readonly GraphSection[];
+}
+
+/** Graph workflow outcome, preserving target disambiguation and failure states. */
+export type GraphWorkflowOutcome =
+  | CompletedGraphWorkflow
+  | Exclude<TargetWorkflowOutcome, { kind: "resolved" } | { kind: "target-group" }>;

package/src/session/graph-workflow.ts

@@ -0,0 +1,152 @@
+/** Session-owned graph workflow: one Target workflow followed by relation collection. */
+
+import { toDisplayPath } from "../analysis/search/paths.ts";
+import type { CapabilityAdapter } from "./capability-adapter.ts";
+import { collectRelation } from "./graph/collect.ts";
+import type {
+  GraphRelationKind,
+  GraphSection,
+  GraphWorkflowInput,
+  GraphWorkflowOutcome,
+} from "./graph-types.ts";
+import { parseGraphWorkflowInput } from "./input/workflows.ts";
+import type { TargetInput } from "./target-input.ts";
+import {
+  resolveTargetWorkflow,
+  type TargetWorkflowDeps,
+  type TargetWorkflowOutcome,
+} from "./target-workflow.ts";
+import { reportProgress, throwIfAborted, type WorkflowControl } from "./workflow-control.ts";
+
+const DEFAULT_RELATIONS: readonly GraphRelationKind[] = ["references"];
+const ALL_RELATIONS: readonly GraphRelationKind[] = ["references", "callees", "implements"];
+
+export interface GraphWorkflowDeps extends TargetWorkflowDeps {
+  readonly capability: CapabilityAdapter;
+}
+
+/** Execute graph analysis without assembling or rendering a public Tool result. */
+export async function runGraphWorkflow(
+  input: GraphWorkflowInput,
+  deps: GraphWorkflowDeps,
+  control?: WorkflowControl,
+): Promise<GraphWorkflowOutcome> {
+  const parsed = parseGraphWorkflowInput(input);
+  if (parsed.kind === "invalid-input") return parsed;
+  const request = parsed.value;
+  const relations = normalizeRelations(request.relations);
+  if (typeof relations === "string") {
+    return { kind: "invalid-input", message: relations };
+  }
+
+  throwIfAborted(control);
+  reportProgress(control, {
+    intent: "graph",
+    phase: "target",
+    message: "Resolving graph target",
+  });
+
+  const targetOutcome = await resolveTargetWorkflow(
+    request.target as TargetInput,
+    {
+      fileLevelAllowed: false,
+      nameAnchorRequired: false,
+      maxResults: request.maxResults,
+    },
+    deps,
+  );
+  if (targetOutcome.kind === "target-group") {
+    return {
+      kind: "invalid-input",
+      message: "Graph analysis requires one member handle from a Target group.",
+    };
+  }
+  if (targetOutcome.kind !== "resolved") return targetOutcome;
+
+  const entry = targetOutcome.entry;
+  const semanticReadinessError = await getSemanticReadinessError(
+    relations,
+    entry.file,
+    deps.capability,
+    deps.cwd,
+  );
+  const provider = deps.capability.getProvider(deps.cwd);
+  const maxResults = request.maxResults ?? 8;
+  const displayName =
+    entry.name ?? `symbol at ${toDisplayPath(deps.cwd, entry.file)}:${entry.displayLine}`;
+
+  const sections: GraphSection[] = [];
+  for (const relation of relations) {
+    throwIfAborted(control);
+    reportProgress(control, {
+      intent: "graph",
+      phase: relation,
+      message: `Collecting ${relation}`,
+    });
+    sections.push(
+      await collectRelation(relation, {
+        file: entry.file,
+        position: entry.position,
+        displayName,
+        cwd: deps.cwd,
+        provider,
+        maxResults,
+        semanticReadinessError,
+        anchorKind: entry.anchorKind,
+        calleeDepth: request.calleeDepth,
+      }),
+    );
+  }
+
+  if (sections.length > 0 && sections.every((section) => section.kind === "unavailable")) {
+    return {
+      kind: "unavailable",
+      reason: sections.map((section) => section.message).join("; "),
+    };
+  }
+
+  return Object.freeze({
+    kind: "completed",
+    displayName,
+    resolvedDisplayFile: toDisplayPath(deps.cwd, entry.file),
+    maxResults,
+    sections: Object.freeze(sections),
+  });
+}
+
+function normalizeRelations(
+  requested: readonly (GraphRelationKind | "all")[] | undefined,
+): readonly GraphRelationKind[] | string {
+  if (!requested || requested.length === 0) return DEFAULT_RELATIONS;
+  if (requested.includes("all")) {
+    if (requested.length !== 1) {
+      return '`relations: ["all"]` cannot be combined with named relations.';
+    }
+    return ALL_RELATIONS;
+  }
+  return requested as readonly GraphRelationKind[];
+}
+
+async function getSemanticReadinessError(
+  relations: readonly GraphRelationKind[],
+  file: string,
+  capability: CapabilityAdapter,
+  cwd: string,
+): Promise<string | null> {
+  if (!relations.some((relation) => relation === "references" || relation === "implements")) {
+    return null;
+  }
+  const readiness = await capability.ensureSemanticReadiness(cwd, { kind: "file", file });
+  if (readiness.kind === "ready") return null;
+  if (readiness.kind === "timeout") {
+    return "Semantic readiness timed out. Retry shortly or inspect code_health.";
+  }
+  return readiness.reason;
+}
+
+/** Narrow helper retained for session method typing. */
+export function isTargetFailure(
+  outcome: TargetWorkflowOutcome,
+): outcome is Exclude<TargetWorkflowOutcome, { kind: "resolved" } | { kind: "target-group" }> {
+  return outcome.kind !== "resolved" && outcome.kind !== "target-group";
+}

package/src/session/health-types.ts

@@ -0,0 +1,134 @@
+import type { CapabilityWarningReport } from "../analysis/capability/capability-warnings.ts";
+
+export type HealthSection = "diagnostics" | "servers";
+
+/** Final semantic-diagnostics readiness after routing and requested recovery. */
+export type SemanticHealthState =
+  | { readonly kind: "ready" }
+  | { readonly kind: "pending"; readonly reason: string }
+  | { readonly kind: "inactive"; readonly reason: string }
+  | { readonly kind: "disabled"; readonly reason: string }
+  | { readonly kind: "unavailable"; readonly reason: string };
+
+export interface HealthWorkflowInput {
+  readonly scope?: string;
+  readonly refresh?: boolean;
+  readonly include?: readonly HealthSection[];
+  readonly level?: "summary" | "detailed";
+}
+
+export interface HealthServerInfo {
+  readonly name: string;
+  readonly root: string;
+  readonly fileTypes: readonly string[];
+  readonly status: string;
+  readonly ready: boolean;
+}
+
+/** A single diagnostic message extracted for detailed health output. */
+export interface HealthDiagnosticMessage {
+  readonly line: number;
+  readonly severity: "error" | "warning";
+  readonly message: string;
+  readonly source?: string;
+}
+
+export interface HealthDiagnosticEntry {
+  readonly file: string;
+  readonly errors: number;
+  readonly warnings: number;
+  /** Individual messages, present only in detailed mode. Capped per file. */
+  readonly messages?: readonly HealthDiagnosticMessage[];
+}
+
+/** The evidence boundary for diagnostics collected by one health request. */
+export type HealthDiagnosticScope =
+  | { readonly kind: "file"; readonly path: string }
+  | { readonly kind: "tracked-files"; readonly filter: string | null };
+
+/** A diagnostic observation that preserves completed-empty, partial, and unavailable states. */
+export type HealthDiagnosticObservation =
+  | { readonly kind: "not-requested"; readonly entries: readonly HealthDiagnosticEntry[] }
+  | {
+      readonly kind: "completed";
+      readonly scope: HealthDiagnosticScope;
+      readonly entries: readonly HealthDiagnosticEntry[];
+    }
+  | {
+      readonly kind: "partial";
+      readonly scope: HealthDiagnosticScope;
+      readonly entries: readonly HealthDiagnosticEntry[];
+      readonly reason: string;
+    }
+  | {
+      readonly kind: "unavailable";
+      readonly scope: HealthDiagnosticScope;
+      readonly entries: readonly HealthDiagnosticEntry[];
+      readonly reason: string;
+    };
+
+/** Bounded stale-diagnostic metadata from a completed workspace recovery pass. */
+export interface HealthStaleAssessment {
+  readonly suspected: boolean;
+  readonly matchedFileCount: number;
+  readonly warning: string | null;
+}
+
+/** A diagnostic refresh attempt against the workspace LSP runtime. */
+export type HealthRefreshAttempt =
+  | {
+      readonly kind: "completed";
+      readonly attemptedAt: number;
+      /** The diagnostic evidence scope requested by the caller, not the runtime operation scope. */
+      readonly requestedDiagnosticScope: HealthDiagnosticScope;
+      /** Recovery always operates against the workspace runtime. */
+      readonly operationScope: "workspace-runtime";
+      /** Active clients targeted by the best-effort refresh; this is not a confirmed-success count. */
+      readonly attemptedActiveClients: number;
+      readonly restartedClients: number;
+      readonly staleAssessment: HealthStaleAssessment;
+    }
+  | {
+      readonly kind: "failed";
+      readonly attemptedAt: number;
+      readonly requestedDiagnosticScope: HealthDiagnosticScope;
+      readonly operationScope: "workspace-runtime";
+      readonly reason: string;
+    };
+
+/** Refresh state for this health call, retaining the prior actual attempt when none ran. */
+export type HealthRefreshState =
+  | HealthRefreshAttempt
+  | {
+      readonly kind: "not-requested";
+      readonly reason: string;
+      readonly lastAttempt: HealthRefreshAttempt | null;
+    }
+  | {
+      readonly kind: "not-attempted";
+      readonly reason: string;
+      readonly lastAttempt: HealthRefreshAttempt | null;
+    };
+
+/** Presentation-neutral health facts. */
+export interface HealthData {
+  readonly includedSections: readonly HealthSection[];
+  /** Final semantic state, or null when no semantic health section was requested. */
+  readonly semanticState: SemanticHealthState | null;
+  /** Whether server inventory was observed from a live owner or explicit disabled state. */
+  readonly serverInventoryAvailable: boolean;
+  /** True only when the structural capability is explicitly ready. */
+  readonly structuralAvailable?: boolean;
+  readonly structuralStatus?: string;
+  readonly diagnostics: HealthDiagnosticObservation;
+  /** Server inventory is always workspace-wide, independent of diagnostic scope. */
+  readonly servers: readonly HealthServerInfo[];
+  readonly refresh: HealthRefreshState;
+  readonly level: "summary" | "detailed";
+  readonly capabilityWarnings?: CapabilityWarningReport;
+}
+
+export type HealthWorkflowOutcome =
+  | { readonly kind: "completed"; readonly data: HealthData }
+  | { readonly kind: "invalid-input"; readonly message: string }
+  | { readonly kind: "unavailable"; readonly reason: string };