@mrclrchtr/supi-code-intelligence 1.16.1 → 2.0.1

package/src/{targeting/resolve-file.ts → analysis/target/file.ts}

@@ -9,10 +9,14 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { normalizePath } from "../search-helpers.ts";
-import { highestConfidence } from "../semantic-action-helpers.ts";
-import type { SemanticSubstrate, StructuralSubstrate } from "../substrates/types.ts";
-import { getCodeProvider } from "../workspace/request-context.ts";
+import type {
+  SemanticProvider as SemanticSubstrate,
+  StructuralProvider as StructuralSubstrate,
+} from "@mrclrchtr/supi-code-runtime/api";
+import type { AnchorKind } from "../../session/target-store.ts";
+import { highestConfidence } from "../helpers.ts";
+import { getCodeProvider } from "../provider.ts";
+import { normalizePath } from "../search/ripgrep.ts";
 import type { ResolvedTargetData, ResolvedTargetGroupData } from "./types.ts";
 
 const BINARY_EXTENSIONS = new Set([
@@ -73,7 +77,7 @@ export async function resolveFileTargetGroup(
   if (isBinaryFile(resolvedFile)) {
     return {
       kind: "error",
-      message: `File type not supported for semantic analysis: \`${file}\`. Use \`code_pattern\` for explicit text search.`,
+      message: `File type not supported for semantic analysis: \`${file}\`. Use \`code_find\` with \`mode: "text"\` for explicit text search.`,
     };
   }
 
@@ -122,25 +126,37 @@ async function resolveViaSemantic(
 
     const topLevel = symbols
       .filter((s) => !s.container)
-      .map((s) => ({
-        file: resolvedFile,
-        position: { line: s.line - 1, character: s.character - 1 },
-        displayLine: s.line,
-        displayCharacter: s.character,
-        name: s.name,
-        kind: s.kind,
-        confidence: "semantic" as const,
-      }));
+      .map((s) => {
+        const a = s.nameAnchor ?? s.declarationAnchor;
+        return {
+          file: resolvedFile,
+          position: { line: a.line - 1, character: a.character - 1 },
+          displayLine: a.line,
+          displayCharacter: a.character,
+          name: s.name,
+          kind: s.kind,
+          confidence: "semantic" as const,
+          anchorKind: (s.nameAnchor ? "name" : "declaration") as AnchorKind,
+          container: s.container ?? null,
+        };
+      });
 
     if (topLevel.length === 0) return structuralTargets;
-    if (!structuralTargets || structuralTargets.length === 0) return dedupeTargets(topLevel);
 
-    const matched = structuralTargets.map((target) => {
-      const byName = topLevel.find((candidate) => candidate.name === target.name);
-      return byName ?? target;
-    });
+    // Semantic symbols are available — prefer them over structural exports.
+    // Only fall back to structural targets that have no semantic counterpart
+    // (different position).
+    if (!structuralTargets || structuralTargets.length === 0) return dedupeTargets(topLevel);
 
-    return dedupeTargets(matched);
+    // Build a position-based dedup: for each position, prefer the semantic entry.
+    const byPos = new Map<string, ResolvedTargetData>();
+    for (const t of structuralTargets) {
+      byPos.set(`${t.position.line}:${t.position.character}`, t);
+    }
+    for (const t of topLevel) {
+      byPos.set(`${t.position.line}:${t.position.character}`, t);
+    }
+    return [...byPos.values()];
   } catch {
     return structuralTargets;
   }
@@ -169,6 +185,10 @@ async function resolveViaStructral(
         name: record.name,
         kind: record.kind,
         confidence: "structural" as const,
+        // Structural exports use the node start (startLine/startCharacter) =
+        // declaration anchor; no name anchor is derivable from exports alone.
+        anchorKind: "declaration",
+        container: null,
       })),
     );
   } catch {

package/src/{planner → analysis/target}/planner.ts

@@ -5,11 +5,13 @@
  * routing decisions for each tool intent. Keeps the execution strategy
  * explicit and centralized instead of scattering capability checks
  * across per-tool execute files.
+ *
+ * This is the canonical planner — src/planner/planner.ts becomes a
+ * thin forwarder to here.
  */
 
 import { getDefaultWorkspaceRuntime } from "@mrclrchtr/supi-code-runtime/api";
-import type { PlannerRoute } from "../intent/types.ts";
-import type { CodeIntelligenceToolName, CodeRelationsKind } from "../tool/tool-specs.ts";
+import type { CodeIntelligenceToolName, PlannerRoute } from "../../types/index.ts";
 
 interface RouteAvailability {
   semanticAvailable: boolean;
@@ -22,7 +24,8 @@ function readAvailability(cwd: string): RouteAvailability {
   const workspace = runtime.getWorkspace(cwd);
   return {
     semanticAvailable:
-      workspace.semantic.state.kind === "ready" && workspace.semantic.provider !== null,
+      (workspace.semantic.state.kind === "ready" || workspace.semantic.state.kind === "pending") &&
+      workspace.semantic.provider !== null,
     structuralAvailable:
       workspace.structural.state.kind === "ready" && workspace.structural.provider !== null,
     refactorAvailable: workspace.semantic.refactorAvailable,
@@ -40,10 +43,6 @@ function semanticOnly(availability: RouteAvailability): PlannerRoute["preferred"
   return availability.semanticAvailable ? "semantic" : "unavailable";
 }
 
-function structuralOnly(availability: RouteAvailability): PlannerRoute["preferred"] {
-  return availability.structuralAvailable ? "structural" : "unavailable";
-}
-
 function briefPreferred(availability: RouteAvailability): PlannerRoute["preferred"] {
   if (availability.semanticAvailable) return "semantic";
   if (availability.structuralAvailable) return "structural";
@@ -53,30 +52,41 @@ function briefPreferred(availability: RouteAvailability): PlannerRoute["preferre
 /**
  * Get the routing decision for a tool intent in a workspace.
  */
-export function routeFor(
-  cwd: string,
-  tool: CodeIntelligenceToolName,
-  relationsKind?: CodeRelationsKind,
-): PlannerRoute {
+export function routeFor(cwd: string, tool: CodeIntelligenceToolName): PlannerRoute {
   const availability = readAvailability(cwd);
 
-  if (tool === "code_pattern") {
-    return withPreferred(availability, "search");
+  if (tool === "code_graph") {
+    // code_graph dispatches per-relation at execution time. Return the best
+    // available preference; the executor handles per-relation unavailability.
+    if (availability.semanticAvailable) return withPreferred(availability, "semantic");
+    if (availability.structuralAvailable) return withPreferred(availability, "structural");
+    return withPreferred(availability, "unavailable");
   }
 
-  if (tool === "code_relations") {
-    const preferred =
-      relationsKind === "callees" ? structuralOnly(availability) : semanticOnly(availability);
-    return withPreferred(availability, preferred);
+  if (tool === "code_orientation" || tool === "code_inspect") {
+    return withPreferred(availability, briefPreferred(availability));
   }
 
-  if (tool === "code_affected") {
+  if (tool === "code_impact") {
     return withPreferred(availability, semanticOnly(availability));
   }
 
-  if (tool === "code_refactor") {
+  if (tool === "code_refactor_plan") {
     return withPreferred(availability, availability.refactorAvailable ? "semantic" : "unavailable");
   }
 
+  if (tool === "code_refactor_apply") {
+    // Plan application does not require a live semantic provider — validity
+    // is enforced through fingerprint comparison in the executor.
+    // Return semantic-preferred so the route check never blocks valid plans.
+    return withPreferred(availability, "semantic");
+  }
+
+  if (tool === "code_health") {
+    // code_health reads diagnostics and server state from the LSP service
+    // directly; it does not require live semantic/structural providers.
+    return withPreferred(availability, "search");
+  }
+
   return withPreferred(availability, briefPreferred(availability));
 }

package/src/{targeting → analysis/target}/query.ts

@@ -24,9 +24,10 @@ export interface QueryInput {
  *
  * Priority order:
  * 1. anchored: file + line + character
- * 2. file: file without coordinates
- * 3. symbol: symbol without file
- * 4. invalid: neither file nor symbol
+ * 2. scoped symbol: file + symbol (without coordinates) — uses file as path scope for symbol discovery
+ * 3. file: file without coordinates or symbol
+ * 4. symbol: symbol without file
+ * 5. invalid: neither file nor symbol
  */
 export function normalizeQuery(input: QueryInput): NormalizedQuery {
   if (input.file && input.line != null && input.character != null) {
@@ -38,6 +39,19 @@ export function normalizeQuery(input: QueryInput): NormalizedQuery {
     };
   }
 
+  // Scoped symbol: both file and symbol present, no line/character.
+  // The file acts as a path scope for symbol discovery — resolves to a
+  // precise target within that file rather than a file-level group.
+  if (input.file && input.symbol) {
+    return {
+      kind: "symbol",
+      symbol: input.symbol,
+      path: input.file,
+      symbolKind: input.kind,
+      exportedOnly: input.exportedOnly,
+    };
+  }
+
   if (input.file) {
     return { kind: "file", file: input.file };
   }

package/src/analysis/target/resolve-common.ts

@@ -0,0 +1,115 @@
+/**
+ * Shared code_resolve result contracts and registration helpers.
+ *
+ * Kept separate from service.ts and file-resolution.ts so file-level
+ * resolution can reuse the public resolve result shape without importing the
+ * service implementation back, avoiding a runtime import cycle.
+ */
+
+import { resolve } from "node:path";
+import type { ConfidenceMode } from "@mrclrchtr/supi-code-runtime/api";
+import type { WorkspaceCodeIntelligenceSession } from "../../session/session.ts";
+import type { TargetRegistrationInput, TargetStoreEntry } from "../../session/target-store.ts";
+import type { DisambiguationCandidateData } from "./types.ts";
+
+export interface ResolveServiceParams {
+  query?: string;
+  scope?: string;
+  kind?: string;
+  file?: string;
+  line?: number;
+  character?: number;
+  maxResults?: number;
+}
+
+/**
+ * A disambiguation candidate with a registered target handle.
+ *
+ * Composes {@link DisambiguationCandidateData} with the stored
+ * {@link TargetStoreEntry} so renderers get both candidate metadata and stable
+ * handles.
+ */
+export interface DisambiguationCandidate extends DisambiguationCandidateData {
+  targetId: string;
+  /** Full stored entry for tool details. */
+  entry: TargetStoreEntry;
+}
+
+export type ResolveServiceResult =
+  | {
+      kind: "resolved";
+      /** Registered target entries from the session store (absolute paths). */
+      targets: TargetStoreEntry[];
+      confidence: ConfidenceMode;
+      omittedCount: number;
+      nextQueries: string[];
+    }
+  | {
+      kind: "disambiguation";
+      candidates: DisambiguationCandidate[];
+      omittedCount: number;
+      nextQueries: string[];
+    }
+  | {
+      kind: "error";
+      message: string;
+    };
+
+/**
+ * Register a single resolved target from the targeting pipeline into the
+ * workflow target store and return the full stored entry.
+ */
+export function registerFromTarget(
+  target: {
+    file: string;
+    position: { line: number; character: number };
+    displayLine: number;
+    displayCharacter: number;
+    name: string | null;
+    kind: string | null;
+    confidence: string;
+    anchorKind: TargetStoreEntry["anchorKind"];
+    container: string | null;
+    resolution?: import("../../types/index.ts").AnchoredResolutionMetadata;
+  },
+  session: WorkspaceCodeIntelligenceSession,
+  provenance: string,
+): TargetStoreEntry {
+  const input: TargetRegistrationInput = {
+    file: target.file,
+    position: target.position,
+    displayLine: target.displayLine,
+    displayCharacter: target.displayCharacter,
+    name: target.name,
+    kind: target.kind,
+    confidence: target.confidence as ConfidenceMode,
+    provenance,
+    anchorKind: target.anchorKind,
+    container: target.container,
+    resolution: target.resolution,
+  };
+  const { entry } = session.registerTarget(input);
+  return entry;
+}
+
+/** Register a disambiguation candidate in the target store and return it with handles. */
+export function registerCandidate(
+  c: DisambiguationCandidateData,
+  session: WorkspaceCodeIntelligenceSession,
+): DisambiguationCandidate {
+  const cwd = session.cwd;
+  const input: TargetRegistrationInput = {
+    file: resolve(cwd, c.file),
+    position: { line: c.line - 1, character: c.character - 1 },
+    displayLine: c.line,
+    displayCharacter: c.character,
+    name: c.name,
+    kind: c.kind,
+    confidence: "semantic" as ConfidenceMode,
+    provenance: "disambiguation",
+    anchorKind: c.anchorKind,
+    container: c.container,
+  };
+  const { targetId, entry } = session.registerTarget(input);
+  return { ...c, targetId, entry };
+}

package/src/analysis/target/service.ts

@@ -0,0 +1,229 @@
+/**
+ * code_resolve business logic.
+ *
+ * Normalizes code_resolve params (query, scope, kind, file, line, character)
+ * into the existing targeting pipeline, registers resolved targets in the
+ * target store, and returns a typed intermediate result that the tool
+ * executor renders into markdown + details.
+ */
+import { existsSync } from "node:fs";
+import type { WorkspaceCodeIntelligenceSession } from "../../session/session.ts";
+import type { CodeProvider } from "../provider.ts";
+import { getCodeProviderState } from "../provider.ts";
+import { normalizePath } from "../search/ripgrep.ts";
+import { resolveAnchoredSymbolTarget } from "./anchored.ts";
+import { resolveFileOnlyInput, tryPathLikeQuery } from "./file-resolution.ts";
+import {
+  type ResolveServiceParams,
+  type ResolveServiceResult,
+  registerCandidate,
+  registerFromTarget,
+} from "./resolve-common.ts";
+import { resolveSymbolTarget as resolveSymbol } from "./symbol.ts";
+import type { TargetOutcome } from "./types.ts";
+
+export type {
+  DisambiguationCandidate,
+  ResolveServiceParams,
+  ResolveServiceResult,
+} from "./resolve-common.ts";
+
+// ── Validation ────────────────────────────────────────────────────────
+
+/**
+ * Cross-field validation for code_resolve params — defense-in-depth.
+ *
+ * The tool executor pipeline already validates via
+ * {@link ../../tool/infra/cross-field.ts!resolveCrossFieldRules}, which is the
+ * canonical source of these rules for tool-level use. This copy exists so
+ * the resolve service validates its own inputs when called outside the
+ * pipeline (e.g. from code_orientation's coordinate resolution).
+ *
+ * TypeBox (via pi schema validation) already enforces:
+ * - kind must be a valid StringEnum value
+ * - line/character must be numbers >= 1
+ * - additionalProperties: false
+ */
+export function validateResolveParams(params: ResolveServiceParams): string | null {
+  const hasQuery = params.query !== undefined && params.query.length > 0;
+  const hasFile = params.file !== undefined && params.file.length > 0;
+  const hasLine = params.line !== undefined;
+  const hasCharacter = params.character !== undefined;
+  if (!hasQuery && !hasFile) {
+    return "**Error:** `code_resolve` requires either `query` (for symbol/search resolution) or `file` (for anchored/file-level resolution).";
+  }
+  if (hasLine !== hasCharacter) {
+    return "**Error:** `line` and `character` must be provided together.";
+  }
+  if ((hasLine || hasCharacter) && !hasFile) {
+    return "**Error:** `line` and `character` require `file`.";
+  }
+  return null;
+}
+
+// ── Resolver sub-routines ─────────────────────────────────────────────
+
+/** Resolve anchored (file + line + character) input via provider-backed symbol resolution. */
+async function resolveAnchoredInput(
+  params: ResolveServiceParams,
+  session: WorkspaceCodeIntelligenceSession,
+  _maxResults: number,
+  provider: CodeProvider | null,
+): Promise<ResolveServiceResult> {
+  const cwd = session.cwd;
+  const file = params.file;
+  const line = params.line;
+  const character = params.character;
+  if (!file) {
+    return { kind: "error", message: "**Error:** File required for anchored resolution." };
+  }
+  if (line == null || character == null) {
+    return {
+      kind: "error",
+      message: "**Error:** Line and character required for anchored resolution.",
+    };
+  }
+  const resolvedFile = normalizePath(file, cwd);
+  if (!existsSync(resolvedFile)) {
+    return { kind: "error", message: `**Error:** File not found: \`${file}\`` };
+  }
+  const outcome = await resolveAnchoredSymbolTarget(resolvedFile, line, character, provider);
+  if (outcome.kind === "error") {
+    return { kind: "error", message: outcome.message };
+  }
+  if (outcome.kind === "resolved") {
+    const entry = registerFromTarget(outcome.target, session, "anchored");
+    return {
+      kind: "resolved",
+      targets: [entry],
+      confidence: entry.confidence,
+      omittedCount: 0,
+      nextQueries: [
+        "`code_graph` for usages of this target",
+        '`code_graph` with `relations: ["callees"]` for direct structural calls from this target',
+        "`code_impact` for blast radius",
+      ],
+    };
+  }
+  // Disambiguation — register each candidate and surface targetIds.
+  const disambig = outcome as Extract<TargetOutcome, { kind: "disambiguation" }>;
+  const candidates = disambig.candidates.map((c) => registerCandidate(c, session));
+  return {
+    kind: "disambiguation",
+    candidates,
+    omittedCount: disambig.omittedCount,
+    nextQueries: [
+      "Use `file` + `line` + `character` for one of the candidates above (pass the identifier coordinate)",
+      "Or refine with `query` + `scope` or `kind` filters",
+    ],
+  };
+}
+
+/** Resolve query/symbol input via semantic workspace symbols. */
+async function resolveQueryTarget(opts: {
+  query: string;
+  kind: string | undefined;
+  scope: string | undefined;
+  session: WorkspaceCodeIntelligenceSession;
+  provider: CodeProvider;
+  maxResults: number;
+}): Promise<ResolveServiceResult> {
+  const { query, kind, scope, session, provider, maxResults } = opts;
+  const cwd = session.cwd;
+
+  const scopePath = scope ? normalizePath(scope, cwd) : undefined;
+  const symbolKind = kind !== undefined && kind !== "symbol" ? kind : undefined;
+  const exportedOnly = kind === "export" ? true : undefined;
+
+  const outcome = await resolveSymbol(query, cwd, provider, {
+    path: scopePath,
+    kind: symbolKind,
+    exportedOnly,
+    maxResults,
+  });
+  if (outcome.kind === "error") {
+    return { kind: "error", message: outcome.message };
+  }
+  if (outcome.kind === "resolved") {
+    const entry = registerFromTarget(outcome.target, session, "symbol");
+    return {
+      kind: "resolved",
+      targets: [entry],
+      confidence: entry.confidence,
+      omittedCount: 0,
+      nextQueries: [
+        "`code_graph` for usages of this target",
+        '`code_graph` with `relations: ["callees"]` for direct structural calls from this target',
+        "`code_impact` for blast radius",
+      ],
+    };
+  }
+  // resolveSymbol never returns "group", so only disambiguation remains
+  const disambig = outcome as Extract<TargetOutcome, { kind: "disambiguation" }>;
+  const candidates = disambig.candidates.map((c) => registerCandidate(c, session));
+  return {
+    kind: "disambiguation",
+    candidates,
+    omittedCount: disambig.omittedCount,
+    nextQueries: [
+      "Use `file` + `line` + `character` for one of the candidates above",
+      "Or refine the query with `scope` or `kind` filters",
+    ],
+  };
+}
+
+// ── Main entry ────────────────────────────────────────────────────────
+
+/**
+ * Execute the code_resolve service.
+ *
+ * Returns a structured intermediate result (resolved, disambiguation, or error)
+ * that the tool executor renders into user-facing markdown + details.
+ */
+export async function executeResolveService(
+  params: ResolveServiceParams,
+  session: WorkspaceCodeIntelligenceSession,
+): Promise<ResolveServiceResult> {
+  const cwd = session.cwd;
+  const validationError = validateResolveParams(params);
+  if (validationError) {
+    return { kind: "error", message: validationError };
+  }
+  const providerState = getCodeProviderState(cwd);
+  const provider = providerState.kind === "ready" ? providerState.provider : null;
+  const maxResults = params.maxResults ?? 10;
+  // Anchored resolution
+  if (params.file && params.line != null && params.character != null) {
+    return resolveAnchoredInput(params, session, maxResults, provider);
+  }
+  // File-only resolution
+  if (params.file && !params.query) {
+    return resolveFileOnlyInput(params, session, maxResults, provider);
+  }
+  // Query resolution
+  if (!params.query) {
+    return {
+      kind: "error",
+      message: "**Error:** Provide a `query` or `file` for resolution.",
+    };
+  }
+  // Special case: path-like query with kind file
+  const pathResult = await tryPathLikeQuery(params, session, maxResults, provider);
+  if (pathResult) return pathResult;
+  // Standard symbol resolution requires semantic provider
+  if (provider === null) {
+    return {
+      kind: "error",
+      message:
+        "**Error:** Symbol query requires active LSP. Use anchored coordinates (file + line + character) or a file-only query.",
+    };
+  }
+  return resolveQueryTarget({
+    query: params.query,
+    kind: params.kind,
+    scope: params.scope,
+    session,
+    provider,
+    maxResults,
+  });
+}