@mrclrchtr/supi-code-intelligence 2.0.6 → 2.2.0

package/src/session/capability-adapter.ts

@@ -0,0 +1,218 @@
+/**
+ * Capability adapter — injected dependency for WorkspaceCodeIntelligenceSession.
+ *
+ * Encapsulates provider access and readiness so the session target
+ * workflow can be tested with an in-memory adapter. Two adapters
+ * (production and test) justify the seam.
+ *
+ * @mrclrchtr/supi-code-intelligence — internal, not exported via api.ts
+ */
+
+import type { SemanticProvider, StructuralProvider } from "@mrclrchtr/supi-code-runtime/api";
+import { getDefaultWorkspaceRuntime } from "@mrclrchtr/supi-code-runtime/api";
+import type { SessionLspServiceState } from "@mrclrchtr/supi-lsp/api";
+import {
+  type CodeProvider,
+  type CodeProviderState,
+  getCodeProviderState,
+} from "../analysis/provider.ts";
+import { ensureSemanticReadiness } from "../analysis/readiness.ts";
+
+// ── Interface ─────────────────────────────────────────────────────────
+
+/**
+ * Readiness scope for semantic provider gating.
+ * `workspace` waits for all servers; `file` waits for a specific file's server.
+ */
+export type ReadinessScope = { kind: "workspace" } | { kind: "file"; file: string };
+
+/** Outcome of a readiness wait. */
+export type ReadinessOutcome =
+  | { kind: "ready" }
+  | { kind: "timeout" }
+  | { kind: "unavailable"; reason: string };
+
+/**
+ * Injected capability adapter.
+ *
+ * Production adapter reads the global workspace runtime. Test adapter
+ * provides semantic/structural providers in memory without global state.
+ */
+export interface CapabilityAdapter {
+  /** Get the composite code provider state for a workspace. */
+  getProviderState(cwd: string): CodeProviderState;
+
+  /** Convenience: get the ready composite provider, or null. */
+  getProvider(cwd: string): CodeProvider | null;
+
+  /** Get the raw semantic provider, or null. */
+  getSemanticProvider(cwd: string): SemanticProvider | null;
+
+  /** Get the raw structural provider, or null. */
+  getStructuralProvider(cwd: string): StructuralProvider | null;
+
+  /**
+   * Wait for semantic (LSP) readiness. Returns a typed outcome so
+   * the target workflow can decide whether to proceed, return a
+   * timeout note, or return an unavailable result.
+   */
+  ensureSemanticReadiness(cwd: string, scope: ReadinessScope): Promise<ReadinessOutcome>;
+}
+
+// ── Production adapter ────────────────────────────────────────────────
+
+/**
+ * Production capability adapter that reads from the global workspace
+ * runtime. Used in the real pi session.
+ */
+export class WorkspaceCapabilityAdapter implements CapabilityAdapter {
+  getProviderState(cwd: string): CodeProviderState {
+    return getCodeProviderState(cwd);
+  }
+
+  getProvider(cwd: string): CodeProvider | null {
+    const state = this.getProviderState(cwd);
+    return state.kind === "ready" ? state.provider : null;
+  }
+
+  getSemanticProvider(cwd: string): SemanticProvider | null {
+    const runtime = getDefaultWorkspaceRuntime();
+    const ws = runtime.getWorkspace(cwd);
+    if (
+      (ws.semantic.state.kind === "ready" || ws.semantic.state.kind === "pending") &&
+      ws.semantic.provider !== null
+    ) {
+      return ws.semantic.provider as SemanticProvider;
+    }
+    return null;
+  }
+
+  getStructuralProvider(cwd: string): StructuralProvider | null {
+    const runtime = getDefaultWorkspaceRuntime();
+    const ws = runtime.getWorkspace(cwd);
+    if (ws.structural.state.kind === "ready" && ws.structural.provider !== null) {
+      return ws.structural.provider as StructuralProvider;
+    }
+    return null;
+  }
+
+  async ensureSemanticReadiness(cwd: string, scope: ReadinessScope): Promise<ReadinessOutcome> {
+    const result = await ensureSemanticReadiness(cwd, scope);
+    return result;
+  }
+
+  /** Convenience: LSP service state for impact/health consumers still using it directly. */
+  getLspService(cwd: string): SessionLspServiceState {
+    const state = this.getProviderState(cwd);
+    return state.kind === "ready"
+      ? state.lspService
+      : { kind: "unavailable" as const, reason: "No provider" };
+  }
+}
+
+// ── Test adapter ──────────────────────────────────────────────────────
+
+/**
+ * In-memory capability adapter for tests.
+ *
+ * Pass explicit providers and readiness outcomes without touching
+ * the global workspace runtime.
+ */
+export class TestCapabilityAdapter implements CapabilityAdapter {
+  readonly #semantic: SemanticProvider | null;
+  readonly #structural: StructuralProvider | null;
+  readonly #readiness: ReadinessOutcome;
+  readonly #lspService: SessionLspServiceState;
+
+  constructor(options: {
+    semantic?: SemanticProvider | null;
+    structural?: StructuralProvider | null;
+    readiness?: ReadinessOutcome;
+    lspService?: SessionLspServiceState;
+  }) {
+    this.#semantic = options.semantic ?? null;
+    this.#structural = options.structural ?? null;
+    this.#readiness = options.readiness ?? { kind: "ready" };
+    this.#lspService = options.lspService ?? {
+      kind: "unavailable" as const,
+      reason: "no test LSP",
+    };
+  }
+
+  getProviderState(_cwd: string): CodeProviderState {
+    if (!this.#semantic && !this.#structural) {
+      return { kind: "unavailable", reason: "No providers in test adapter" };
+    }
+    return {
+      kind: "ready",
+      provider: this.getProvider(_cwd) as CodeProvider,
+      lspService: this.#lspService,
+    };
+  }
+
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: adapter maps many provider methods; splitting would degrade readability
+  getProvider(_cwd: string): CodeProvider | null {
+    if (!this.#semantic && !this.#structural) return null;
+    return {
+      // Semantic pass-through
+      references: this.#semantic?.references
+        ? (...args: Parameters<SemanticProvider["references"]>) =>
+            this.#semantic?.references?.(...args)
+        : async () => null,
+      implementation: this.#semantic?.implementation
+        ? (...args) => this.#semantic?.implementation?.(...args)
+        : async () => null,
+      documentSymbols: this.#semantic?.documentSymbols
+        ? (...args) => this.#semantic?.documentSymbols?.(...args)
+        : async () => [],
+      workspaceSymbols: this.#semantic?.workspaceSymbols
+        ? (...args) => this.#semantic?.workspaceSymbols?.(...args)
+        : async () => [],
+      hover: this.#semantic?.hover ? (...args) => this.#semantic?.hover?.(...args) : undefined,
+      definition: this.#semantic?.definition
+        ? (...args) => this.#semantic?.definition?.(...args)
+        : undefined,
+      codeActions: this.#semantic?.codeActions
+        ? (...args) => this.#semantic?.codeActions?.(...args)
+        : undefined,
+      codeActionTitles: this.#semantic?.codeActionTitles
+        ? (...args) => this.#semantic?.codeActionTitles?.(...args)
+        : undefined,
+      rename: this.#semantic?.rename ? (...args) => this.#semantic?.rename?.(...args) : undefined,
+      refactor: this.#semantic?.refactor
+        ? (...args) => this.#semantic?.refactor?.(...args)
+        : undefined,
+      // Structural pass-through
+      calleesAt: this.#structural?.calleesAt
+        ? (...args) => this.#structural?.calleesAt?.(...args)
+        : async () => ({ kind: "unavailable" as const, message: "no test structural" }),
+      exports: this.#structural?.exports
+        ? (...args) => this.#structural?.exports?.(...args)
+        : async () => ({ kind: "unavailable" as const, message: "no test structural" }),
+      outline: this.#structural?.outline
+        ? (...args) => this.#structural?.outline?.(...args)
+        : async () => ({ kind: "unavailable" as const, message: "no test structural" }),
+      imports: this.#structural?.imports
+        ? (...args) => this.#structural?.imports?.(...args)
+        : async () => ({ kind: "unavailable" as const, message: "no test structural" }),
+      nodeAt: this.#structural?.nodeAt
+        ? (...args) => this.#structural?.nodeAt?.(...args)
+        : async () => ({ kind: "unavailable" as const, message: "no test structural" }),
+      callSites: this.#structural?.callSites
+        ? (...args) => this.#structural?.callSites?.(...args)
+        : async () => ({ kind: "unavailable" as const, message: "no test structural" }),
+    } as CodeProvider;
+  }
+
+  getSemanticProvider(_cwd: string): SemanticProvider | null {
+    return this.#semantic;
+  }
+
+  getStructuralProvider(_cwd: string): StructuralProvider | null {
+    return this.#structural;
+  }
+
+  async ensureSemanticReadiness(_cwd: string, _scope: ReadinessScope): Promise<ReadinessOutcome> {
+    return this.#readiness;
+  }
+}

package/src/session/session.ts

@@ -15,6 +15,8 @@
  * @mrclrchtr/supi-code-intelligence — internal, not exported via api.ts
  */
 
+import * as path from "node:path";
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
 import {
   getDefaultWorkspaceRuntime,
   type SemanticProvider,
@@ -24,6 +26,7 @@ import type { LspRuntimeController } from "@mrclrchtr/supi-lsp/api";
 import { CoverageWarningState } from "../analysis/coverage/coverage-warnings.ts";
 import type { CodeProvider } from "../analysis/provider.ts";
 import { getCodeProvider } from "../analysis/provider.ts";
+import { type CapabilityAdapter, WorkspaceCapabilityAdapter } from "./capability-adapter.ts";
 import { getPlan, type RefactorPlan, removePlan, storePlan } from "./refactor-plans.ts";
 import {
   getWorkflowTarget,
@@ -33,11 +36,18 @@ import {
   type TargetRegistrationOutput,
   type TargetStoreEntry,
 } from "./target-store.ts";
+import {
+  resolveTargetWorkflow,
+  type TargetWorkflowInput,
+  type TargetWorkflowOutcome,
+  type TargetWorkflowPolicy,
+} from "./target-workflow.ts";
 
 // ── Re-export types consumed by callers ───────────────────────────────
 
 export type { CoverageWarningState } from "../analysis/coverage/coverage-warnings.ts";
 export type { CodeProvider, CodeProviderState } from "../analysis/provider.ts";
+export type { CapabilityAdapter } from "./capability-adapter.ts";
 export type { RefactorPlan } from "./refactor-plans.ts";
 export type {
   TargetLookupResult,
@@ -45,6 +55,11 @@ export type {
   TargetRegistrationOutput,
   TargetStoreEntry,
 } from "./target-store.ts";
+export type {
+  TargetWorkflowInput,
+  TargetWorkflowOutcome,
+  TargetWorkflowPolicy,
+} from "./target-workflow.ts";
 
 // ── Target ID expansion result ────────────────────────────────────────
 
@@ -74,6 +89,9 @@ export class WorkspaceCodeIntelligenceSession {
   /** Canonical workspace directory for this session. */
   readonly cwd: string;
 
+  /** Injected capability adapter — two adapters (production/test) justify the seam. */
+  readonly #capability: CapabilityAdapter;
+
   /** Whether the hidden architecture overview has been injected. */
   hasInjectedOverview = false;
 
@@ -88,6 +106,12 @@ export class WorkspaceCodeIntelligenceSession {
    */
   readonly coverageWarningState = new CoverageWarningState();
 
+  /** Absolute instruction files already loaded by PI's native context-file mechanism. */
+  readonly nativeInstructionPaths = new Set<string>();
+
+  /** Absolute directories whose instruction files were already surfaced by code_orientation. */
+  readonly surfacedInstructionDirs = new Set<string>();
+
   /**
    * Optional LSP controller reference — attached by LSP lifecycle module
    * for coverage evaluation and server management.
@@ -100,8 +124,62 @@ export class WorkspaceCodeIntelligenceSession {
    */
   tsController: import("@mrclrchtr/supi-tree-sitter/api").TreeSitterRuntimeController | null = null;
 
-  constructor(cwd: string) {
+  constructor(cwd: string, capability?: CapabilityAdapter) {
     this.cwd = cwd;
+    this.#capability = capability ?? new WorkspaceCapabilityAdapter();
+  }
+
+  // ── Target workflow (deep seam) ───────────────────────────────────
+
+  /**
+   * Resolve target input into an immutable resolved target.
+   *
+   * This is the deep module interface. Tool executors call this instead
+   * of `expandTargetId` or direct `resolveTarget`/`resolveAnchoredSymbolTarget`
+   * calls. Returns typed outcomes — no markdown, no mutated params.
+   */
+  async resolveTarget(
+    input: TargetWorkflowInput,
+    policy: TargetWorkflowPolicy,
+  ): Promise<TargetWorkflowOutcome> {
+    return resolveTargetWorkflow(input, policy, {
+      cwd: this.cwd,
+      capability: this.#capability,
+      lookupTargetId: (id) => this.lookupTargetId(id),
+      registerTarget: (inp) => this.registerTarget(inp),
+    });
+  }
+
+  // ── Instruction-file state ───────────────────────────────────────
+
+  /** Remember instruction/context file paths already loaded by PI natively. */
+  captureNativeInstructionPaths(files: Array<{ path: string }>): void {
+    for (const file of files) {
+      this.nativeInstructionPaths.add(path.resolve(this.cwd, file.path));
+    }
+  }
+
+  /** Mark directory-local instruction files as surfaced after a successful orientation render. */
+  markInstructionDirsSurfaced(directories: string[]): void {
+    for (const directory of directories) {
+      this.surfacedInstructionDirs.add(path.resolve(this.cwd, directory));
+    }
+  }
+
+  /** Clear instruction-file dedup state after compaction. */
+  resetSurfacedInstructionDirs(): void {
+    this.surfacedInstructionDirs.clear();
+  }
+
+  /** Reconstruct surfaced instruction directories from branch tool-result details after compaction. */
+  reconstructInstructionState(branch: SessionEntry[]): void {
+    this.surfacedInstructionDirs.clear();
+    const entries = entriesAfterLatestCompaction(branch);
+    for (const entry of entries) {
+      for (const directory of extractInstructionDirectories(entry)) {
+        this.surfacedInstructionDirs.add(path.resolve(this.cwd, directory));
+      }
+    }
   }
 
   // ── Provider access ───────────────────────────────────────────────
@@ -252,9 +330,36 @@ export class WorkspaceCodeIntelligenceSession {
   clearStores(): void {
     this.#refactorPlans.clear();
     this.#workflowTargets.clear();
+    this.surfacedInstructionDirs.clear();
+    this.nativeInstructionPaths.clear();
   }
 }
 
+function entriesAfterLatestCompaction(branch: SessionEntry[]): SessionEntry[] {
+  let start = 0;
+  for (let i = 0; i < branch.length; i++) {
+    if (branch[i]?.type === "compaction") start = i + 1;
+  }
+  return branch.slice(start);
+}
+
+function extractInstructionDirectories(entry: SessionEntry): string[] {
+  if (entry.type !== "message" || entry.message.role !== "toolResult") return [];
+  if (entry.message.toolName !== "code_orientation") return [];
+
+  const details = entry.message.details as
+    | { type?: string; data?: { instructions?: { files?: Array<{ directory?: unknown }> } } }
+    | undefined;
+  if (details?.type !== "context") return [];
+
+  const files = details.data?.instructions?.files;
+  if (!Array.isArray(files)) return [];
+
+  return files
+    .map((file) => file.directory)
+    .filter((directory): directory is string => typeof directory === "string");
+}
+
 // ── Standalone target-id expansion helper ─────────────────────────────
 
 /**