@mrclrchtr/supi-code-intelligence 1.16.0 → 2.0.0

package/src/types/details.ts

@@ -0,0 +1,188 @@
+import type { ConfidenceMode } from "@mrclrchtr/supi-code-runtime/api";
+import type { EvidenceListMetadata } from "../analysis/evidence.ts";
+import type { PrioritySignalsSummary } from "../analysis/signals/project.ts";
+import type { TestSurfaceDetails } from "../analysis/tests/test-discovery.ts";
+import type { AnchorKind, TargetStoreEntry } from "../session/target-store.ts";
+
+export type { TestSurfaceDetails } from "../analysis/tests/test-discovery.ts";
+
+// ── Anchored coordinate resolution metadata ───────────────────────────
+
+/**
+ * Provider-backed evidence source that identified an anchored coordinate
+ * target. Drives the markdown provenance note and structured resolution
+ * metadata per ADR 0003/0004.
+ *
+ * - `semantic` — LSP document symbols identified the symbol and its anchors.
+ * - `structural` — tree-sitter structural evidence (outline/exports/nodeAt)
+ *   identified the declaration and/or identifier.
+ * - `structural-identifier` — tree-sitter `nodeAt` classified the coordinate
+ *   as an identifier token and snapped it to a declaration via ancestry.
+ */
+export type AnchoredResolutionSource = "semantic" | "structural" | "structural-identifier";
+
+/**
+ * Resolution metadata for a target resolved from anchored coordinates.
+ *
+ * Records the requested coordinate, the resolved anchor coordinate, whether
+ * the resolved anchor differs from the request (a snap), and the
+ * provider-backed evidence source. Structured details always carry this when
+ * a target was resolved from coordinates; markdown surfaces a note only when
+ * the resolution was non-obvious (snapped or degraded).
+ */
+export interface AnchoredResolutionMetadata {
+  /** The 1-based coordinate the caller requested. */
+  requested: { line: number; character: number };
+  /** The 1-based anchor coordinate the target was resolved to. */
+  resolved: { line: number; character: number };
+  /** Whether the resolved anchor differs from the requested coordinate. */
+  snapped: boolean;
+  /** Provider-backed evidence source that identified the target. */
+  source: AnchoredResolutionSource;
+}
+
+/** Structured details metadata returned alongside markdown brief content. */
+export interface BriefDetails {
+  confidence: ConfidenceMode;
+  focusTarget: string | null;
+  startHere: Array<{ target: string; reason: string }>;
+  publicSurfaces: string[];
+  dependencySummary: { moduleCount: number; edgeCount: number } | null;
+  omittedCount: number;
+  evidenceLists?: EvidenceListMetadata[];
+  nextQueries: string[];
+  prioritySignals?: PrioritySignalsSummary | null;
+}
+
+/** Structured details metadata for relationship and pattern results. */
+export interface SearchDetails {
+  confidence: ConfidenceMode;
+  scope: string | null;
+  candidateCount: number;
+  omittedCount: number;
+  evidenceLists?: EvidenceListMetadata[];
+  nextQueries: string[];
+  tests?: TestSurfaceDetails;
+}
+
+/** Structured details metadata for affected analysis results. */
+export interface AffectedDetails {
+  confidence: ConfidenceMode;
+  directCount: number;
+  downstreamCount: number;
+  riskLevel: "low" | "medium" | "high";
+  checkNext: string[];
+  likelyTests: string[];
+  /** Concrete test commands to run relevant verification. */
+  likelyTestCommands: string[];
+  omittedCount: number;
+  evidenceLists?: EvidenceListMetadata[];
+  nextQueries: string[];
+  prioritySignals?: PrioritySignalsSummary | null;
+  tests?: TestSurfaceDetails;
+}
+
+/**
+ * Structured details metadata for workflow-oriented impact analysis results.
+ *
+ * Currently structurally identical to `AffectedDetails`. When adding own fields,
+ * audit callers in `orchestrate.ts` that construct `{ type: "impact", data }`
+ * so they return `ImpactDetails`, not just `AffectedDetails`.
+ */
+export interface ImpactDetails extends AffectedDetails {}
+
+// Canonical disambiguation candidate — re-exported from resolution/types.ts
+export type { DisambiguationCandidateData as DisambiguationCandidate } from "../analysis/target/types.ts";
+
+/** Structured details metadata for code_resolve results. */
+export interface ResolveDetails {
+  confidence: ConfidenceMode;
+  targetCount: number;
+  omittedCount: number;
+  evidenceLists?: EvidenceListMetadata[];
+  /** Resolved targets with relative paths (computed from {@link TargetStoreEntry} at detail-build time). */
+  targets: Array<{
+    targetId: string;
+    spanId: string;
+    /** Workspace-relative path. */
+    file: string;
+    displayLine: number;
+    displayCharacter: number;
+    name: string | null;
+    kind: string | null;
+    anchorKind: AnchorKind;
+    confidence: ConfidenceMode;
+    provenance: string;
+    /** Resolution provenance — present when the target was resolved from anchored coordinates. */
+    resolution?: AnchoredResolutionMetadata;
+  }>;
+  /** Disambiguation candidates from the resolve service. */
+  candidates?: Array<{
+    targetId: string;
+    name: string;
+    kind: string | null;
+    container: string | null;
+    file: string;
+    line: number;
+    character: number;
+    reason: string;
+    rank: number;
+    anchorKind: AnchorKind;
+  }>;
+  nextQueries: string[];
+}
+
+/** Structured details metadata for code_orientation results. */
+export interface ContextDetails {
+  confidence: ConfidenceMode;
+  task: string | null;
+  focusTarget: string | null;
+  requestedSections: string[];
+  renderedSections: string[];
+  omittedCount: number;
+  evidenceLists?: EvidenceListMetadata[];
+  nextQueries: string[];
+  tests?: TestSurfaceDetails;
+  /**
+   * Resolved target store entry — populated for both coordinate and targetId
+   * precise-target inputs. Absent for orientation/scope-only calls and for
+   * ambiguous coordinate resolution (see `candidates`).
+   * File paths are absolute; compute relative paths at render time.
+   */
+  target?: TargetStoreEntry;
+  /**
+   * Disambiguation candidates with targetIds — populated only when coordinate
+   * resolution was ambiguous. No task sections are rendered in that case.
+   */
+  candidates?: Array<{
+    targetId: string;
+    name: string;
+    kind: string | null;
+    container: string | null;
+    file: string;
+    line: number;
+    character: number;
+    rank: number;
+  }>;
+}
+
+/** Structured details metadata for code_inspect results. */
+export interface InspectDetails {
+  confidence: ConfidenceMode;
+  focusTarget: string;
+  unavailableSections: string[];
+  evidenceLists?: EvidenceListMetadata[];
+  nextQueries: string[];
+}
+
+/** Structured details metadata for code_health results. */
+export interface HealthDetails {
+  lspAvailable: boolean;
+  lspStatus: string;
+  recovered: boolean;
+  /** Structural (tree-sitter) substrate readiness. Undefined when not evaluated. */
+  structuralStatus?: string;
+  diagnosticFileCount: number;
+  serverCount: number;
+  evidenceLists?: EvidenceListMetadata[];
+}

package/src/types/execution.ts

@@ -0,0 +1,60 @@
+import type { AgentToolUpdateCallback } from "@earendil-works/pi-coding-agent";
+import type { WorkspaceCodeIntelligenceSession } from "../session/session.ts";
+import type {
+  BriefDetails,
+  ContextDetails,
+  HealthDetails,
+  ImpactDetails,
+  InspectDetails,
+  ResolveDetails,
+  SearchDetails,
+} from "./details.ts";
+
+/**
+ * Execution context passed to every code-intelligence tool executor.
+ *
+ * The adapter in `tool/register.ts` builds this from the pi
+ * `ToolDefinition.execute` arguments and forwards it to `spec.run`.
+ * `signal` and `onUpdate` are optional. An executor that does not yet use
+ * them can still type its ctx as `{ cwd: string }` (a structural supertype —
+ * it destructures only `cwd` and ignores the rest) and keep compiling; all
+ * current executors use this full type, and long-running ones forward `signal`
+ * to subprocesses / emit coarse `onUpdate` beats.
+ *
+ * The `session` property carries the per-workspace
+ * `WorkspaceCodeIntelligenceSession` facade (ADR 0008) for centralized
+ * provider access, target resolution, and plan management. Executors
+ * must prefer `ctx.session` over ad-hoc session factories.
+ */
+export interface CodeIntelToolExecCtx {
+  cwd: string;
+  /** Abort signal from the agent runtime; forward to long-running subprocesses. */
+  signal?: AbortSignal;
+  /** Progress callback; long-running executors emit coarse beats, not chatty ones. */
+  onUpdate?: AgentToolUpdateCallback;
+  /**
+   * Per-workspace code-intelligence session facade.
+   *
+   * Provides centralized access to:
+   * - Provider state: {@link WorkspaceCodeIntelligenceSession.getProviders}
+   * - Target resolution: {@link WorkspaceCodeIntelligenceSession.expandTargetId}
+   * - Plan management: {@link WorkspaceCodeIntelligenceSession.storePlan}
+   *
+   * Present on every execution. Executors that need it should destructure
+   * `{ cwd, session }` from their ctx parameter.
+   */
+  session: WorkspaceCodeIntelligenceSession;
+}
+
+/** Tool result shape returned by executeAction. */
+export interface CodeIntelResult {
+  content: string;
+  details?:
+    | { type: "brief"; data: BriefDetails }
+    | { type: "context"; data: ContextDetails }
+    | { type: "inspect"; data: InspectDetails }
+    | { type: "search"; data: SearchDetails }
+    | { type: "impact"; data: ImpactDetails }
+    | { type: "resolve"; data: ResolveDetails }
+    | { type: "health"; data: HealthDetails };
+}

package/src/types/index.ts

@@ -0,0 +1,28 @@
+// ── Tool names and routing ─────────────────────────────────────────────
+
+export {
+  CODE_INTELLIGENCE_TOOL_NAMES,
+  type CodeIntelligenceToolName,
+  type PlannerRoute,
+} from "./tool-names.ts";
+
+// ── Execution context and result ────────────────────────────────────────
+
+export type { CodeIntelResult, CodeIntelToolExecCtx } from "./execution.ts";
+
+// ── Detail types ────────────────────────────────────────────────────────
+
+export type {
+  AffectedDetails,
+  AnchoredResolutionMetadata,
+  AnchoredResolutionSource,
+  BriefDetails,
+  ContextDetails,
+  DisambiguationCandidate,
+  HealthDetails,
+  ImpactDetails,
+  InspectDetails,
+  ResolveDetails,
+  SearchDetails,
+  TestSurfaceDetails,
+} from "./details.ts";

package/src/{intent/types.ts → types/tool-names.ts}

@@ -1,7 +1,18 @@
-/**
- * Normalized intent and routing types for the code-intelligence planner.
- */
-import type { CodeIntelligenceToolName, CodeRelationsKind } from "../tool/tool-specs.ts";
+/** Canonical code-intelligence tool names. */
+export const CODE_INTELLIGENCE_TOOL_NAMES = [
+  "code_resolve",
+  "code_inspect",
+  "code_orientation",
+  "code_find",
+  "code_graph",
+  "code_impact",
+  "code_refactor_plan",
+  "code_refactor_apply",
+  "code_health",
+] as const;
+
+/** Canonical code-intelligence tool name. */
+export type CodeIntelligenceToolName = (typeof CODE_INTELLIGENCE_TOOL_NAMES)[number];
 
 /**
  * A route describes how the planner recommends handling a tool intent.
@@ -22,13 +33,3 @@ export interface PlannerRoute {
    */
   preferred: "semantic" | "structural" | "search" | "unavailable";
 }
-
-/**
- * A resolved intents for a tool execution request.
- * Provides the normalized target and routing info together.
- */
-export interface ResolvedIntent {
-  tool: CodeIntelligenceToolName;
-  relationsKind?: CodeRelationsKind;
-  route: PlannerRoute;
-}

package/src/ui/footer.ts

@@ -0,0 +1,52 @@
+/**
+ * LSP footer stats-end contribution for code-intelligence.
+ *
+ * Provides the persistent "| λ lsp • N servers • M open files" suffix on the
+ * footer stats line, after cost and context info. This was removed during the
+ * supi-lsp → supi-code-intelligence migration.
+ */
+
+import { footerContributions } from "@mrclrchtr/supi-core/footer-registry";
+import type { LspAdapterState } from "../substrate/lsp/state.ts";
+
+/** Build the LSP status text: "λ lsp • 2 servers • 5 open files" */
+export function buildLspStatusText(lspState: LspAdapterState): string | undefined {
+  const controller = lspState.controller;
+  const service = controller?.service;
+  if (!service) return undefined;
+
+  const servers = service.getProjectServers();
+  const runningServers = servers.filter((s) => s.status === "running").length;
+  const openFiles = servers.reduce((sum, s) => sum + s.openFiles.length, 0);
+
+  if (runningServers === 0 && openFiles === 0) return undefined;
+
+  const parts = ["λ lsp"];
+  if (runningServers > 0)
+    parts.push(`${runningServers} ${runningServers === 1 ? "server" : "servers"}`);
+  if (openFiles > 0) parts.push(`${openFiles} ${openFiles === 1 ? "open file" : "open files"}`);
+  return parts.join(" • ");
+}
+
+// ── Footer stats contribution ───────────────────────────────────────────
+
+const FOOTER_KEY = "lsp-status";
+
+/** Register the LSP stats-end footer contribution for the given adapter state. */
+export function registerLspFooterContribution(lspState: LspAdapterState): void {
+  footerContributions.register({
+    key: FOOTER_KEY,
+    placement: "stats-end",
+    priority: 100,
+    render: () => {
+      const text = buildLspStatusText(lspState);
+      if (!text) return "";
+      return `| ${text}`;
+    },
+  });
+}
+
+/** Remove the LSP stats footer contribution. */
+export function unregisterLspFooterContribution(): void {
+  footerContributions.unregister(FOOTER_KEY);
+}

package/src/ui/markdown/brief.ts

@@ -0,0 +1,218 @@
+// Brief markdown renderer — consumes use-case data and produces markdown content + details metadata.
+
+import * as path from "node:path";
+import type { ArchitectureModel } from "../../analysis/architecture/model.ts";
+import { findModuleForPath } from "../../analysis/architecture/model.ts";
+import type { BriefDetails } from "../../types/index.ts";
+
+interface TreeSitterContext {
+  nodeInfo: unknown;
+  outline: Array<{ name: string; kind: string; startLine: number; endLine: number }>;
+  imports: Array<{ moduleSpecifier: string }>;
+  exports: Array<{ name: string; kind: string }>;
+}
+
+// ── Symbol brief ──────────────────────────────────────────────────────
+
+export function renderSymbolBrief(params: {
+  relPath: string;
+  symbolName: string;
+  targetLine: number;
+  targetCharacter: number;
+  targetKind: string | null;
+  context: TreeSitterContext;
+  model: ArchitectureModel | null;
+  details: BriefDetails;
+  cwd: string;
+}): { content: string; details: BriefDetails } {
+  const lines: string[] = [];
+  lines.push(`# Symbol Brief: ${params.symbolName || params.relPath}`);
+  lines.push("");
+  lines.push(
+    `**Resolved to:** \`${params.relPath}:${params.targetLine}:${params.targetCharacter}\`${params.targetKind ? ` (${params.targetKind})` : ""}`,
+  );
+  lines.push("");
+
+  appendFileOrientationContext(lines, params.context);
+
+  if (params.model) {
+    const resolvedFile = path.resolve(params.cwd, params.relPath);
+    const mod = findModuleForPath(params.model, resolvedFile);
+    if (mod) {
+      const shortName = mod.name.replace(/^@[^/]+\//, "");
+      lines.push(`_Module: ${shortName} (\`${mod.relativePath}\`)_`);
+      lines.push("");
+    }
+  }
+
+  return { content: lines.join("\n"), details: params.details };
+}
+
+function getOutlinePrefix(kind: string): string {
+  if (kind === "function" || kind === "method") return "ƒ";
+  if (kind === "class") return "◆";
+  return "·";
+}
+
+function appendFileOrientationContext(lines: string[], context: TreeSitterContext): void {
+  if (context.outline.length > 0) {
+    lines.push("## File Outline");
+    const shown = context.outline.slice(0, 15);
+    for (const item of shown) {
+      const prefix = getOutlinePrefix(item.kind);
+      lines.push(`- ${prefix} \`${item.name}\` (${item.kind}) L${item.startLine}`);
+    }
+    if (context.outline.length > 15) {
+      lines.push(`- _+${context.outline.length - 15} more declarations_`);
+    }
+    lines.push("");
+  }
+
+  if (context.imports.length > 0) {
+    lines.push("## Imports");
+    const shown = context.imports.slice(0, 10);
+    for (const imp of shown) {
+      lines.push(`- \`${imp.moduleSpecifier}\``);
+    }
+    if (context.imports.length > 10) {
+      lines.push(`- _+${context.imports.length - 10} more_`);
+    }
+    lines.push("");
+  }
+
+  if (context.exports.length > 0) {
+    lines.push("## Exports");
+    const shown = context.exports.slice(0, 10);
+    for (const exp of shown) {
+      lines.push(`- \`${exp.name}\` (${exp.kind})`);
+    }
+    if (context.exports.length > 10) {
+      lines.push(`- _+${context.exports.length - 10} more_`);
+    }
+    lines.push("");
+  }
+}
+
+// ── File brief ───────────────────────────────────────────────────────
+
+interface FileBriefInput {
+  relPath: string;
+  lineCount: number;
+  isEntrypoint: boolean;
+  moduleName: string | null;
+  moduleRelativePath: string | null;
+  enrichment: {
+    outline: Array<{ name: string; kind: string; startLine: number; endLine: number }>;
+    imports: Array<{ moduleSpecifier: string }>;
+    exports: Array<{ name: string; kind: string }>;
+    diagnostics: Array<{ line: number; severity: number; message: string }>;
+  };
+  maxResults?: number;
+}
+
+export function renderFileBrief(input: FileBriefInput): string {
+  const lines: string[] = [];
+  lines.push(`# File: ${input.relPath}`);
+  lines.push("");
+
+  if (input.moduleName) {
+    lines.push(`_Module: ${input.moduleName} (\`${input.moduleRelativePath}\`)_`);
+    lines.push("");
+  }
+
+  if (input.isEntrypoint) {
+    lines.push("**This file is a module entrypoint.**");
+    lines.push("");
+  }
+
+  lines.push(`- Lines: ${input.lineCount}`);
+  lines.push("");
+
+  // Diagnostics section (inline first diagnostic messages)
+  appendDiagnosticsSection(lines, input.enrichment.diagnostics, input.maxResults);
+
+  // Structural context (outline, imports, exports)
+  if (input.enrichment.outline.length > 0) {
+    lines.push("## File Outline");
+    const shown = input.enrichment.outline;
+    for (const item of shown) {
+      const prefix = getOutlinePrefix(item.kind);
+      lines.push(`- ${prefix} \`${item.name}\` (${item.kind}) L${item.startLine}`);
+    }
+    lines.push("");
+  }
+
+  if (input.enrichment.imports.length > 0) {
+    lines.push("## Imports");
+    for (const imp of input.enrichment.imports) {
+      lines.push(`- \`${imp.moduleSpecifier}\``);
+    }
+    lines.push("");
+  }
+
+  if (input.enrichment.exports.length > 0) {
+    lines.push("## Exports");
+    for (const exp of input.enrichment.exports) {
+      lines.push(`- \`${exp.name}\` (${exp.kind})`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+// ── Module brief diagnostics section ─────────────────────────────────
+
+export function renderModuleDiagnostics(
+  fileDiagnostics: Array<{ file: string; errors: number; warnings: number }>,
+  maxResults?: number,
+): string | null {
+  if (fileDiagnostics.length === 0) return null;
+
+  const lines: string[] = [];
+  lines.push("## Diagnostics");
+  const cap = maxResults ?? 5;
+  for (const entry of fileDiagnostics.slice(0, cap)) {
+    const parts: string[] = [];
+    if (entry.errors > 0) parts.push(`${entry.errors} error${entry.errors > 1 ? "s" : ""}`);
+    if (entry.warnings > 0) parts.push(`${entry.warnings} warning${entry.warnings > 1 ? "s" : ""}`);
+    lines.push(`- \`${entry.file}\` — ${parts.join(", ")}`);
+  }
+  if (fileDiagnostics.length > cap) {
+    lines.push(`- _+${fileDiagnostics.length - cap} more files_`);
+  }
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+// ── Diagnostics section (inline) ─────────────────────────────────────
+
+function severityLabel(severity: number): string {
+  switch (severity) {
+    case 1:
+      return "Error";
+    case 2:
+      return "Warning";
+    case 3:
+      return "Info";
+    case 4:
+      return "Hint";
+    default:
+      return "Diagnostic";
+  }
+}
+
+function appendDiagnosticsSection(
+  lines: string[],
+  diagnostics: Array<{ line: number; severity: number; message: string }>,
+  _maxResults?: number,
+): void {
+  if (diagnostics.length === 0) return;
+
+  lines.push("## Diagnostics");
+  for (const d of diagnostics) {
+    lines.push(`- L${d.line}: ${severityLabel(d.severity)}: ${d.message}`);
+  }
+  lines.push("");
+}