@mrclrchtr/supi-code-intelligence 2.0.6 → 2.1.0

package/src/tool/result/errors.ts

@@ -0,0 +1,199 @@
+/**
+ * Tool-result error assembly factories for code-intelligence tool executors.
+ *
+ * Every factory returns a complete {@link CodeIntelResult} (content + typed
+ * details) so executors never need to inline the `{ content, details }`
+ * wrapper. Returned tool errors are result assembly concerns; whole-tool
+ * capability failures may still throw so PI marks the tool call as failed.
+ */
+
+import type {
+  CodeIntelResult,
+  ContextDetails,
+  HealthDetails,
+  ImpactDetails,
+  InspectDetails,
+  ResolveDetails,
+  SearchDetails,
+} from "../../types/index.ts";
+
+// ── Combined error-result factories (preferred) ──────────────────────
+
+/** Full error result for search-family tools (code_find, code_graph, code_refactor_plan). */
+export function searchErrorResult(
+  content: string,
+  opts?: { scope?: string | null; nextQueries?: string[] },
+): CodeIntelResult {
+  return {
+    content,
+    details: {
+      type: "search" as const,
+      data: {
+        confidence: "unavailable" as const,
+        scope: opts?.scope ?? null,
+        candidateCount: 0,
+        omittedCount: 0,
+        nextQueries: opts?.nextQueries ?? [],
+      },
+    },
+  };
+}
+
+/** Full error result for code_orientation (context-type details). */
+export function contextErrorResult(
+  content: string,
+  opts?: { nextQueries?: string[] },
+): CodeIntelResult {
+  return {
+    content,
+    details: {
+      type: "context" as const,
+      data: {
+        confidence: "unavailable" as const,
+        task: null,
+        focusTarget: null,
+        requestedSections: [],
+        renderedSections: [],
+        omittedCount: 0,
+        nextQueries: opts?.nextQueries ?? [],
+      },
+    },
+  };
+}
+
+/** Full error result for code_resolve. */
+export function resolveErrorResult(
+  content: string,
+  opts?: { nextQueries?: string[] },
+): CodeIntelResult {
+  return {
+    content,
+    details: {
+      type: "resolve" as const,
+      data: {
+        confidence: "unavailable" as const,
+        targetCount: 0,
+        omittedCount: 0,
+        targets: [],
+        nextQueries: opts?.nextQueries ?? [],
+      },
+    },
+  };
+}
+
+/** Full error result for code_inspect. */
+export function inspectErrorResult(
+  content: string,
+  opts?: { focusTarget?: string; nextQueries?: string[] },
+): CodeIntelResult {
+  return {
+    content,
+    details: {
+      type: "inspect" as const,
+      data: {
+        confidence: "unavailable" as const,
+        focusTarget: opts?.focusTarget ?? "",
+        unavailableSections: [],
+        nextQueries: opts?.nextQueries ?? [],
+      },
+    },
+  };
+}
+
+/** Full error result for code_impact. */
+export function impactErrorResult(
+  content: string,
+  opts?: { nextQueries?: string[] },
+): CodeIntelResult {
+  const data: ImpactDetails = {
+    confidence: "unavailable",
+    directCount: 0,
+    downstreamCount: 0,
+    riskLevel: "low",
+    checkNext: [],
+    likelyTests: [],
+    likelyTestCommands: [],
+    omittedCount: 0,
+    nextQueries: opts?.nextQueries ?? [],
+  };
+  return { content, details: { type: "impact" as const, data } };
+}
+
+/** Full error result for code_health. */
+export function healthErrorResult(content: string, reason?: string): CodeIntelResult {
+  return {
+    content,
+    details: {
+      type: "health" as const,
+      data: {
+        lspAvailable: false,
+        lspStatus: reason ?? content,
+        recovered: false,
+        diagnosticFileCount: 0,
+        serverCount: 0,
+      },
+    },
+  };
+}
+
+// ── Details-only helpers (thin wrappers — prefer combined factories above) ─
+
+export function unavailableSearchDetails(
+  scope: string | null,
+  nextQueries: string[],
+): { type: "search"; data: SearchDetails } {
+  return searchErrorResult("", { scope, nextQueries }).details as {
+    type: "search";
+    data: SearchDetails;
+  };
+}
+
+export function unavailableContextDetails(nextQueries: string[]): {
+  type: "context";
+  data: ContextDetails;
+} {
+  return contextErrorResult("", { nextQueries }).details as {
+    type: "context";
+    data: ContextDetails;
+  };
+}
+
+export function unavailableResolveDetails(nextQueries: string[]): {
+  type: "resolve";
+  data: ResolveDetails;
+} {
+  return resolveErrorResult("", { nextQueries }).details as {
+    type: "resolve";
+    data: ResolveDetails;
+  };
+}
+
+export function unavailableInspectDetails(
+  focusTarget: string,
+  nextQueries: string[],
+): { type: "inspect"; data: InspectDetails } {
+  return inspectErrorResult("", { focusTarget, nextQueries }).details as {
+    type: "inspect";
+    data: InspectDetails;
+  };
+}
+
+export function unavailableImpactDetails(nextQueries: string[]): {
+  type: "impact";
+  data: ImpactDetails;
+} {
+  return impactErrorResult("", { nextQueries }).details as {
+    type: "impact";
+    data: ImpactDetails;
+  };
+}
+
+export function unavailableHealthDetails(reason: string): {
+  type: "health";
+  data: HealthDetails;
+} {
+  return healthErrorResult("", reason).details as {
+    type: "health";
+    data: HealthDetails;
+  };
+}

package/src/tool/result/find.ts

@@ -0,0 +1,29 @@
+import type { ConfidenceMode } from "@mrclrchtr/supi-code-runtime/api";
+import type { EvidenceListMetadata } from "../../analysis/evidence.ts";
+import type { TestSurfaceDetails } from "../../analysis/tests/test-discovery.ts";
+import type { SearchDetails } from "./types.ts";
+
+export interface FindResultAssemblyInput {
+  confidence: ConfidenceMode;
+  scope: string | null;
+  candidateCount: number;
+  omittedCount?: number;
+  evidenceLists?: EvidenceListMetadata[];
+  nextQueries: string[];
+  tests?: TestSurfaceDetails;
+}
+
+/** Assemble code_find/search-family details before presentation adapters render content. */
+export function assembleFindResult(input: FindResultAssemblyInput): SearchDetails {
+  return {
+    confidence: input.confidence,
+    scope: input.scope,
+    candidateCount: input.candidateCount,
+    omittedCount:
+      input.omittedCount ??
+      (input.evidenceLists ?? []).reduce((sum, list) => sum + (list.omittedCount ?? 0), 0),
+    evidenceLists: input.evidenceLists,
+    nextQueries: input.nextQueries,
+    tests: input.tests,
+  };
+}

package/src/tool/result/graph.ts

@@ -0,0 +1,93 @@
+import type { ConfidenceMode } from "@mrclrchtr/supi-code-runtime/api";
+import type { EvidenceListMetadata } from "../../analysis/evidence.ts";
+import type { ReadNextItem } from "../../analysis/read-next.ts";
+import type { TestSurfaceDetails } from "../../analysis/tests/test-discovery.ts";
+import type { SearchDetails } from "./types.ts";
+
+/** Relation families accepted by code_graph. */
+export type GraphRelationKind =
+  | "all"
+  | "references"
+  | "callees"
+  | "imports"
+  | "exports"
+  | "implements"
+  | "tests";
+
+/** A relation section in an assembled code_graph result. */
+export type GraphSection =
+  | {
+      kind: "ok";
+      rel: GraphRelationKind;
+      count: number;
+      /** Relation body prepared for markdown/TUI presentation adapters. */
+      content: string;
+      evidenceLists?: EvidenceListMetadata[];
+      tests?: TestSurfaceDetails;
+      readNext?: ReadNextItem[];
+    }
+  | { kind: "unavailable"; rel: GraphRelationKind; message: string; tests?: TestSurfaceDetails }
+  | {
+      kind: "not-implemented";
+      rel: GraphRelationKind;
+      message: string;
+      tests?: TestSurfaceDetails;
+    };
+
+export interface GraphResultAssembly {
+  displayName: string;
+  sections: GraphSection[];
+  resolvedDisplayFile: string;
+  scope: string | undefined;
+  details: SearchDetails;
+}
+
+/** Assemble code_graph evidence/details before markdown and TUI adapters render it. */
+export function assembleGraphResult(input: {
+  displayName: string;
+  sections: GraphSection[];
+  resolvedDisplayFile: string;
+  scope: string | undefined;
+}): GraphResultAssembly {
+  const evidenceLists = input.sections.flatMap((section) =>
+    section.kind === "ok" ? (section.evidenceLists ?? []) : [],
+  );
+  const omittedCount = evidenceLists.reduce(
+    (sum, evidenceList) => sum + (evidenceList.omittedCount ?? 0),
+    0,
+  );
+
+  return {
+    ...input,
+    details: {
+      confidence: graphConfidence(input.sections),
+      scope: input.scope ?? null,
+      candidateCount: input.sections.reduce(
+        (sum, section) => sum + (section.kind === "ok" ? section.count : 0),
+        0,
+      ),
+      omittedCount,
+      evidenceLists,
+      nextQueries: [
+        "`code_orientation` on individual results for deeper orientation",
+        "`code_impact` for impact analysis",
+      ],
+      tests: input.sections.find((section) => section.rel === "tests")?.tests,
+    },
+  };
+}
+
+function graphConfidence(sections: GraphSection[]): ConfidenceMode {
+  const hasStructural = sections.some(
+    (s) =>
+      s.kind === "ok" &&
+      (s.rel === "callees" ||
+        s.rel === "imports" ||
+        s.rel === "exports" ||
+        (s.rel === "tests" && s.count > 0)),
+  );
+  const hasSemantic = sections.some(
+    (s) => s.kind === "ok" && (s.rel === "references" || s.rel === "implements"),
+  );
+  return hasSemantic ? "semantic" : hasStructural ? "structural" : "unavailable";
+}

package/src/tool/result/health.ts

@@ -0,0 +1,94 @@
+import type { CoverageWarningReport } from "../../analysis/coverage/coverage-warnings.ts";
+import type { EvidenceListMetadata } from "../../analysis/evidence.ts";
+import type { GitContext } from "../../analysis/signals/git.ts";
+import type { HealthDetails } from "./types.ts";
+
+export type HealthSection = "diagnostics" | "servers" | "dirty" | "coverage" | "unused";
+
+export interface HealthServerInfo {
+  name: string;
+  root: string;
+  fileTypes: string[];
+  status: string;
+}
+
+export interface HealthDiagnosticEntry {
+  file: string;
+  errors: number;
+  warnings: number;
+}
+
+export interface HealthCoverageEntry {
+  file: string;
+  pct: number;
+}
+
+export interface HealthCoverageData {
+  available: boolean;
+  entries: HealthCoverageEntry[];
+}
+
+export interface HealthUnusedExportEntry {
+  file: string;
+  name: string;
+}
+
+export interface HealthUnusedData {
+  available: boolean;
+  files: string[];
+  exports: HealthUnusedExportEntry[];
+}
+
+/** A suggested code action at a specific diagnostic location. */
+export interface CodeActionSuggestion {
+  file: string;
+  line: number;
+  title: string;
+  kind?: string;
+}
+
+export interface HealthData {
+  includedSections: HealthSection[];
+  lspAvailable: boolean;
+  lspStatus: string;
+  recovered: boolean;
+  /** Structural (tree-sitter) substrate readiness. Undefined when not evaluated. */
+  structuralStatus?: string;
+  diagnostics: HealthDiagnosticEntry[];
+  servers: HealthServerInfo[];
+  gitContext: GitContext | null;
+  scopeFilter: string | null;
+  level: "summary" | "detailed";
+  /** Code action suggestions collected from LSP (only populated in detailed mode). */
+  codeActions: CodeActionSuggestion[] | null;
+  coverage: HealthCoverageData | null;
+  unused: HealthUnusedData | null;
+  /** Coverage warnings for degraded semantic/structural substrate. Undefined when fully healthy. */
+  degradedCoverage?: CoverageWarningReport;
+  /** Seconds since diagnostics were last refreshed, or undefined if never refreshed. */
+  diagnosticAgeSeconds?: number;
+}
+
+export interface HealthResultAssembly {
+  data: HealthData;
+  details: HealthDetails;
+}
+
+/** Assemble public code_health evidence and details before presentation adapters render it. */
+export function assembleHealthResult(
+  data: HealthData,
+  evidenceLists: EvidenceListMetadata[],
+): HealthResultAssembly {
+  return {
+    data,
+    details: {
+      lspAvailable: data.lspAvailable,
+      lspStatus: data.lspStatus,
+      recovered: data.recovered,
+      structuralStatus: data.structuralStatus,
+      diagnosticFileCount: data.diagnostics.length,
+      serverCount: data.servers.length,
+      evidenceLists,
+    },
+  };
+}

package/src/tool/result/impact.ts

@@ -0,0 +1,50 @@
+import type { EvidenceListMetadata } from "../../analysis/evidence.ts";
+import type { PrioritySignalsSummary } from "../../analysis/signals/project.ts";
+import type { CodeIntelResult } from "../../types/index.ts";
+import type { ImpactAnalysis } from "../impact/types.ts";
+import type { AffectedDetails, ImpactDetails } from "./types.ts";
+
+// biome-ignore lint/complexity/useMaxParams: detail assembly keeps shared counts, queries, and signals explicit for both surfaces
+export function assembleImpactDetails(
+  analysis: ImpactAnalysis,
+  directCount: number,
+  omittedCount: number,
+  nextQueries: string[],
+  prioritySignals: PrioritySignalsSummary | null,
+  evidenceLists: EvidenceListMetadata[] = [],
+): AffectedDetails | ImpactDetails {
+  return {
+    confidence: analysis.confidence,
+    directCount,
+    downstreamCount: analysis.downstreamCount,
+    riskLevel: analysis.riskLevel,
+    checkNext: analysis.checkNext,
+    likelyTests: analysis.likelyTests,
+    likelyTestCommands: analysis.likelyTestCommands,
+    omittedCount,
+    evidenceLists,
+    nextQueries,
+    prioritySignals,
+    tests: analysis.tests,
+  };
+}
+
+export function unavailableImpactResult(content: string, nextQueries: string[]): CodeIntelResult {
+  return {
+    content,
+    details: {
+      type: "impact",
+      data: {
+        confidence: "unavailable",
+        directCount: 0,
+        downstreamCount: 0,
+        riskLevel: "low" as const,
+        checkNext: [],
+        likelyTests: [],
+        likelyTestCommands: [],
+        omittedCount: 0,
+        nextQueries,
+      },
+    },
+  };
+}

package/src/tool/result/inspect.ts

@@ -0,0 +1,60 @@
+import type { ConfidenceMode } from "@mrclrchtr/supi-code-runtime/api";
+import type { EvidenceListMetadata } from "../../analysis/evidence.ts";
+import type { InspectDetails } from "./types.ts";
+
+export interface InspectResultData {
+  relPath: string;
+  line: number;
+  character: number;
+  confidence: ConfidenceMode;
+  node: {
+    type: string;
+    text: string;
+    startLine: number;
+    startCharacter: number;
+    ancestry?: Array<
+      | string
+      | {
+          type: string;
+          startLine: number;
+          startCharacter: number;
+          endLine?: number;
+          endCharacter?: number;
+        }
+    >;
+  } | null;
+  enclosingSymbol: {
+    name: string;
+    kind: string;
+    startLine: number;
+    endLine: number;
+  } | null;
+  hover: string | null;
+  definitions: Array<{ file: string; line: number; character: number }>;
+  diagnostics: Array<{ line: number; severity: number | string; message: string }>;
+  codeActions: Array<{ title: string; kind?: string }>;
+  codeActionEvidence?: EvidenceListMetadata;
+  unavailableSections: string[];
+}
+
+export interface InspectResultAssembly {
+  data: InspectResultData;
+  details: InspectDetails;
+}
+
+/** Assemble code_inspect evidence/details before presentation adapters render it. */
+export function assembleInspectResult(
+  data: InspectResultData,
+  nextQueries: string[],
+): InspectResultAssembly {
+  return {
+    data,
+    details: {
+      confidence: data.confidence,
+      focusTarget: `${data.relPath}:${data.line}:${data.character}`,
+      unavailableSections: data.unavailableSections,
+      evidenceLists: data.codeActionEvidence ? [data.codeActionEvidence] : [],
+      nextQueries,
+    },
+  };
+}

package/src/tool/result/orientation.ts

@@ -0,0 +1,30 @@
+import type { ConfidenceMode } from "@mrclrchtr/supi-code-runtime/api";
+import type { TargetStoreEntry } from "../../session/target-store.ts";
+import type { ContextDetails } from "./types.ts";
+
+export interface OrientationDetailsInput {
+  confidence: ConfidenceMode;
+  task?: string | null;
+  focusTarget?: string | null;
+  requestedSections?: string[];
+  renderedSections?: string[];
+  omittedCount?: number;
+  nextQueries: string[];
+  target?: TargetStoreEntry;
+  candidates?: ContextDetails["candidates"];
+}
+
+/** Assemble code_orientation details before presentation adapters render content. */
+export function assembleOrientationDetails(input: OrientationDetailsInput): ContextDetails {
+  return {
+    confidence: input.confidence,
+    task: input.task ?? null,
+    focusTarget: input.focusTarget ?? null,
+    requestedSections: input.requestedSections ?? [],
+    renderedSections: input.renderedSections ?? [],
+    omittedCount: input.omittedCount ?? 0,
+    nextQueries: input.nextQueries,
+    target: input.target,
+    candidates: input.candidates,
+  };
+}

package/src/tool/result/refactor.ts

@@ -0,0 +1,35 @@
+import type { WorkspaceEdit } from "@mrclrchtr/supi-code-runtime/api";
+import { createEvidenceList } from "../../analysis/evidence.ts";
+import type { ApplyResult } from "../refactor-apply/apply.ts";
+import type { SearchDetails } from "./types.ts";
+
+export function assembleRefactorPlanDetails(
+  edits: WorkspaceEdit,
+  planId: string,
+  maxResults = 5,
+): SearchDetails {
+  const editEvidence = createEvidenceList({
+    key: "refactor.edits",
+    items: edits.edits,
+    maxResults,
+  }).metadata;
+
+  return {
+    confidence: "semantic",
+    scope: null,
+    candidateCount: edits.edits.length,
+    omittedCount: editEvidence.omittedCount ?? 0,
+    evidenceLists: [editEvidence],
+    nextQueries: [`Use code_refactor_apply with planId: "${planId}" to apply this refactor`],
+  };
+}
+
+export function assembleRefactorApplyDetails(applyResult: ApplyResult): SearchDetails {
+  return {
+    confidence: "semantic",
+    scope: null,
+    candidateCount: applyResult.kind === "applied" ? applyResult.totalEdits : 0,
+    omittedCount: 0,
+    nextQueries: ["`code_health` to check for new issues after the refactor"],
+  };
+}