@mrclrchtr/supi-code-intelligence 2.0.6 → 2.2.0

package/src/tool/infra/error-results.ts

@@ -1,199 +1,21 @@
 /**
- * Unified error-result factories for code-intelligence tool executors.
+ * Compatibility export for code-intelligence error result assembly.
  *
- * Every factory returns a complete {@link CodeIntelResult} (content + typed
- * details) so executors never need to inline the `{ content, details }`
- * wrapper. The old `unavailableXxxDetails()` functions are kept as thin
- * wrappers — prefer the combined `xxxErrorResult()` factories in new code.
+ * Returned tool errors are assembled behind `src/tool/result/` with the rest
+ * of public tool evidence. New tool code should import from
+ * `../result/errors.ts` directly.
  */
-
-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_find, 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;
-  };
-}
+export {
+  contextErrorResult,
+  healthErrorResult,
+  impactErrorResult,
+  inspectErrorResult,
+  resolveErrorResult,
+  searchErrorResult,
+  unavailableContextDetails,
+  unavailableHealthDetails,
+  unavailableImpactDetails,
+  unavailableInspectDetails,
+  unavailableResolveDetails,
+  unavailableSearchDetails,
+} from "../result/errors.ts";

package/src/tool/infra/pipeline.ts

@@ -23,7 +23,7 @@
 
 import { match } from "ts-pattern";
 import { ensureSemanticReadiness } from "../../analysis/readiness.ts";
-import { resolveScope } from "../../analysis/search/ripgrep.ts";
+import { resolveScope, resolveScopeSet } from "../../analysis/search/ripgrep.ts";
 import { routeFor } from "../../analysis/target/planner.ts";
 import type {
   CodeIntelligenceToolName,
@@ -150,6 +150,15 @@ export interface HasScopeParam {
   scope?: string;
 }
 
+/** Minimum parameter shape needed by `resolveScopeSetParam`. */
+export interface HasScopeSetParam {
+  scope?: string | string[];
+  /** Set by resolveScopeSetParam — absolute search roots for code_find. */
+  _resolvedScopePaths?: string[];
+  /** Set by resolveScopeSetParam — display label for requested search roots. */
+  _resolvedScopeDisplay?: string | null;
+}
+
 /**
  * Resolve the `scope` parameter to an absolute path.
  *
@@ -175,6 +184,20 @@ export function resolveScopeParam<P extends HasScopeParam>(
   };
 }
 
+/** Resolve code_find's one-or-many `scope` input to absolute search roots. */
+export function resolveScopeSetParam<P extends HasScopeSetParam>(
+  onError: (reason: string) => CodeIntelResult,
+): PipeStage<P> {
+  return (params, ctx) => {
+    const result = resolveScopeSet(params.scope, ctx.cwd);
+    if (result.kind === "error") return { kind: "error", result: onError(result.reason) };
+
+    params._resolvedScopePaths = [...result.paths];
+    params._resolvedScopeDisplay = result.display;
+    return { kind: "continue" };
+  };
+}
+
 /**
  * Apply cross-field validation rules after TypeBox schema validation.
  *

package/src/tool/inspect/markdown.ts

@@ -1,46 +1,9 @@
-import type { ConfidenceMode } from "@mrclrchtr/supi-code-runtime/api";
-import {
-  type EvidenceListMetadata,
-  renderEvidenceListMetadataDisclosure,
-} from "../../analysis/evidence.ts";
-
-export interface InspectRenderInput {
-  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[];
-}
+import { renderEvidenceListMetadataDisclosure } from "../../analysis/evidence.ts";
+import type { InspectResultAssembly } from "../result/inspect.ts";
 
 // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: inspect rendering keeps section ordering and unavailable-state handling explicit
-export function renderInspectResult(input: InspectRenderInput): string {
+export function renderInspectResult(assembly: InspectResultAssembly): string {
+  const input = assembly.data;
   const lines: string[] = [];
   lines.push(`# Inspect: ${input.relPath}:${input.line}:${input.character}`);
   lines.push("");

package/src/tool/inspect/orchestrate.ts

@@ -4,6 +4,7 @@ import { createEvidenceList } from "../../analysis/evidence.ts";
 import { normalizePath } from "../../analysis/search/ripgrep.ts";
 import { gatherNearbyDiagnostics, gatherTreeSitterContext } from "../../ui/markdown/gather.ts";
 import type { InspectDeps, InspectInput, InspectUseCaseResult } from "../../ui/markdown/types.ts";
+import { assembleInspectResult } from "../result/inspect.ts";
 import { renderInspectResult } from "./markdown.ts";
 
 // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: inspect orchestration keeps data gathering and unavailable-section derivation in one place
@@ -89,37 +90,35 @@ export async function executeInspect(
   });
 
   const nextQueries = buildNextQueries(relPath, input.line, input.character, confidence);
-  const content = renderInspectResult({
-    relPath,
-    line: input.line,
-    character: input.character,
-    confidence,
-    node: context.nodeInfo,
-    enclosingSymbol: enclosing
-      ? {
-          name: enclosing.name,
-          kind: enclosing.kind,
-          startLine: enclosing.startLine,
-          endLine: enclosing.endLine,
-        }
-      : null,
-    hover: context.hover?.contents ?? null,
-    definitions,
-    diagnostics,
-    codeActions: codeActions.items,
-    codeActionEvidence: codeActions.metadata,
-    unavailableSections: dedupe(unavailableSections),
-  });
-
-  return {
-    content,
-    details: {
+  const assembly = assembleInspectResult(
+    {
+      relPath,
+      line: input.line,
+      character: input.character,
       confidence,
-      focusTarget: `${relPath}:${input.line}:${input.character}`,
+      node: context.nodeInfo,
+      enclosingSymbol: enclosing
+        ? {
+            name: enclosing.name,
+            kind: enclosing.kind,
+            startLine: enclosing.startLine,
+            endLine: enclosing.endLine,
+          }
+        : null,
+      hover: context.hover?.contents ?? null,
+      definitions,
+      diagnostics,
+      codeActions: codeActions.items,
+      codeActionEvidence: codeActions.metadata,
       unavailableSections: dedupe(unavailableSections),
-      evidenceLists: [codeActions.metadata],
-      nextQueries,
     },
+    nextQueries,
+  );
+  const content = renderInspectResult(assembly);
+
+  return {
+    content,
+    details: assembly.details,
   };
 }
 

package/src/tool/orientation/mode.ts

@@ -6,10 +6,17 @@
  * orientation.
  */
 
-import { existsSync } from "node:fs";
+import { existsSync, statSync } from "node:fs";
 import type { ArchitectureModel } from "../../analysis/architecture/model.ts";
+import {
+  findInstructionFilesForDirectory,
+  insertInstructionsNearTop,
+  renderInstructionFiles,
+} from "../../analysis/instruction-files.ts";
 import { normalizePath } from "../../analysis/search/ripgrep.ts";
+import { loadCodeIntelligenceConfig } from "../../config.ts";
 import type { CodeIntelResult, CodeIntelToolExecCtx } from "../../types/index.ts";
+import type { OrientationUseCaseResult } from "../../ui/markdown/types.ts";
 import { unavailableContextDetails } from "../infra/error-results.ts";
 import { prepareOrientationDeps } from "./deps.ts";
 import type { CodeOrientationToolParams } from "./execute.ts";
@@ -50,8 +57,52 @@ export async function runOrientationMode(
     },
     { ...deps, cwd: ctx.cwd },
   );
+  const withInstructions = addInstructionFilesForDirectoryFocus(result, focusResolution.path, ctx);
 
-  return { content: result.content, details: { type: "context", data: result.details } };
+  return {
+    content: withInstructions.content,
+    details: { type: "context", data: withInstructions.details },
+  };
+}
+
+function addInstructionFilesForDirectoryFocus(
+  result: OrientationUseCaseResult,
+  focusPath: string | undefined,
+  ctx: CodeIntelToolExecCtx,
+): OrientationUseCaseResult {
+  if (!focusPath || !isDirectory(focusPath)) return result;
+
+  const config = loadCodeIntelligenceConfig(ctx.cwd);
+  const matches = findInstructionFilesForDirectory({
+    directory: focusPath,
+    cwd: ctx.cwd,
+    fileNames: config.instructionFileNames,
+    nativeContextPaths: ctx.session.nativeInstructionPaths,
+    surfacedDirectories: ctx.session.surfacedInstructionDirs,
+  });
+  if (matches.length === 0) return result;
+
+  const rendered = renderInstructionFiles(matches);
+  if (!rendered) return result;
+
+  ctx.session.markInstructionDirsSurfaced(rendered.metadata.files.map((file) => file.directory));
+
+  return {
+    content: insertInstructionsNearTop(result.content, rendered.markdown),
+    details: {
+      ...result.details,
+      renderedSections: ["instructions", ...result.details.renderedSections],
+      instructions: rendered.metadata,
+    },
+  };
+}
+
+function isDirectory(filePath: string): boolean {
+  try {
+    return statSync(filePath).isDirectory();
+  } catch {
+    return false;
+  }
 }
 
 /**

package/src/tool/orientation/orchestrate.ts

@@ -19,6 +19,7 @@ import type {
   OrientationTarget,
   OrientationUseCaseResult,
 } from "../../ui/markdown/types.ts";
+import { assembleOrientationDetails } from "../result/orientation.ts";
 import { type RenderedOrientationSection, renderOrientationResult } from "./markdown.ts";
 
 const DEFAULT_TARGET_SECTIONS: OrientationSection[] = ["defs", "docs", "diagnostics"];
@@ -59,15 +60,13 @@ async function executeOrientationContext(
     lspService: deps.lspService,
   });
 
-  const details: ContextDetails = {
+  const details: ContextDetails = assembleOrientationDetails({
     confidence: result.details.confidence,
-    task: null,
     focusTarget: input.focus ?? null,
-    requestedSections: [],
     renderedSections: ["orientation"],
     omittedCount: result.details.omittedCount,
     nextQueries: result.details.nextQueries,
-  };
+  });
 
   return {
     content: result.content,
@@ -107,15 +106,13 @@ async function executeTargetOrientation(
       ? "structural"
       : "unavailable";
 
-  const details: ContextDetails = {
+  const details: ContextDetails = assembleOrientationDetails({
     confidence,
-    task: null,
     focusTarget,
     requestedSections,
     renderedSections: sections.map((section) => section.key),
-    omittedCount: 0,
     nextQueries: buildNextQueries(input.target, deps.cwd),
-  };
+  });
 
   return {
     content: renderOrientationResult({