@mrclrchtr/supi-code-intelligence 3.2.0 → 4.1.0

package/src/{tool/graph → analysis/relations}/references.ts

@@ -5,6 +5,12 @@
  * ("semantic-references" since we use LSP references as caller evidence).
  */
 
+import {
+  isTargetLocation,
+  normalizeProviderLocations,
+  normalizeTargetFile,
+  type RelationLocationPartialReason,
+} from "./provider-locations.ts";
 import type { CallerEvidence, CallerReference, RelationsServiceDeps } from "./types.ts";
 
 export interface CallersResult {
@@ -12,6 +18,9 @@ export interface CallersResult {
   targetName: string;
   references: CallerReference[];
   externalCount: number;
+  /** Provider locations omitted because their URI or position was unusable. */
+  invalidLocationCount: number;
+  partialReason: RelationLocationPartialReason | null;
   evidence: CallerEvidence;
   confidence: "semantic" | "unavailable";
 }
@@ -33,40 +42,32 @@ export async function collectCallers(
       targetName: targetName ?? "symbol",
       references: [],
       externalCount: 0,
+      invalidLocationCount: 0,
+      partialReason: null,
       evidence: "semantic-references",
       confidence: "unavailable",
     };
   }
 
-  const refs = await deps.provider.references(targetFile, targetPosition);
-  if (!refs) {
+  const result = await deps.provider.references(targetFile, targetPosition);
+  if (result.kind === "unavailable") {
     return {
       kind: "callers",
       targetName: targetName ?? "symbol",
       references: [],
       externalCount: 0,
+      invalidLocationCount: 0,
+      partialReason: null,
       evidence: "semantic-references",
-      confidence: "semantic",
+      confidence: "unavailable",
     };
   }
 
-  const inProject: CallerReference[] = [];
-  let externalCount = 0;
-
-  for (const ref of refs) {
-    const uri = ref.uri ?? "";
-    const filePath = uri.startsWith("file://") ? uri.slice(7) : uri;
-    if (filePath.startsWith(deps.cwd)) {
-      inProject.push({
-        file: filePath,
-        line: ref.range.start.line + 1,
-        character: ref.range.start.character + 1,
-        name: targetName,
-      });
-    } else {
-      externalCount++;
-    }
-  }
+  const normalized = normalizeProviderLocations(result.data, deps.cwd);
+  const normalizedTargetFile = normalizeTargetFile(targetFile, deps.cwd);
+  const inProject: CallerReference[] = normalized.project
+    .filter((reference) => !isTargetLocation(reference, normalizedTargetFile, targetPosition))
+    .map((reference) => ({ ...reference, name: targetName }));
 
   void maxResults;
 
@@ -74,7 +75,10 @@ export async function collectCallers(
     kind: "callers",
     targetName: targetName ?? "symbol",
     references: inProject,
-    externalCount,
+    externalCount: normalized.external.length,
+    invalidLocationCount: normalized.invalidLocationCount,
+    partialReason:
+      normalized.partialReason ?? (result.kind === "partial" ? "provider-limited" : null),
     evidence: "semantic-references",
     confidence: "semantic",
   };

package/src/{tool/graph → analysis/relations}/types.ts

@@ -1,3 +1,5 @@
+import type { SemanticProvider } from "@mrclrchtr/supi-code-runtime/api";
+
 /**
  * Shared types for the relations analysis modules.
  *
@@ -50,25 +52,8 @@ export interface ImplementationEntry {
 export interface RelationsServiceDeps {
   cwd: string;
   provider: {
-    references?: (
-      file: string,
-      pos: { line: number; character: number },
-    ) => Promise<Array<{
-      uri: string;
-      range: {
-        start: { line: number; character: number };
-        end: { line: number; character: number };
-      };
-    }> | null>;
-    implementation?: (
-      file: string,
-      pos: { line: number; character: number },
-    ) => Promise<Array<{
-      uri?: string;
-      targetUri?: string;
-      range?: { start: { line: number }; end?: { line: number } };
-      targetRange?: { start: { line: number }; end?: { line: number } };
-    }> | null>;
+    references?: SemanticProvider["references"];
+    implementation?: SemanticProvider["implementation"];
     calleesAt?: (
       file: string,
       line: number,

package/src/analysis/search/ast-scan.ts

@@ -0,0 +1,376 @@
+import { type Dirent, promises as fs, type Stats } from "node:fs";
+import * as path from "node:path";
+import {
+  getStructuralSearchSupportedExtensions,
+  getSupportedExtensions,
+  type StructuralSearchOperation,
+} from "@mrclrchtr/supi-tree-sitter/api";
+import { type DeadlineOutcome, settleByDeadline } from "./deadline.ts";
+import { relativeDisplayPath } from "./paths.ts";
+
+/** Directory names excluded below an AST Scan root. */
+export const AST_SCAN_EXCLUDED_DIRECTORIES = Object.freeze([
+  ".git",
+  ".pnpm",
+  "node_modules",
+  "dist",
+  "build",
+  "out",
+  ".next",
+  ".nuxt",
+  "coverage",
+  ".turbo",
+  ".cache",
+  "__pycache__",
+] as const);
+
+const EXCLUDED_DIRECTORY_SET = new Set<string>(AST_SCAN_EXCLUDED_DIRECTORIES);
+
+/** Default eligible-file safety cap for one AST Scan. */
+export const DEFAULT_AST_SCAN_MAX_FILES = 5_000;
+/** Default wall-clock deadline for AST enumeration plus analysis. */
+export const DEFAULT_AST_SCAN_TIMEOUT_MS = 10_000;
+
+export type AstScanExclusionReason =
+  | "hidden-entry"
+  | "excluded-directory"
+  | "unsupported-extension"
+  | "unsupported-operation"
+  | "symlink"
+  | "non-regular";
+
+export type AstScanLimitationReason = "timeout" | "safety-limit" | "unreadable-path";
+
+/** Bounded examples and exact encountered-path count for one policy exclusion. */
+export interface AstScanExclusion {
+  readonly reason: AstScanExclusionReason;
+  readonly pathCount: number;
+  readonly examples: readonly string[];
+}
+
+/** Runtime condition that prevented complete AST file enumeration. */
+export interface AstScanLimitation {
+  readonly reason: AstScanLimitationReason;
+  readonly pathCount: number | null;
+  readonly examples: readonly string[];
+}
+
+/** Declared deterministic policy for one AST Scan. */
+export interface AstScanPolicy {
+  readonly operation: StructuralSearchOperation;
+  readonly supportedExtensions: readonly string[];
+  readonly excludedDirectories: readonly string[];
+  readonly hiddenEntries: "excluded";
+  readonly ignoreFiles: false;
+  readonly symlinks: "explicit-roots-only";
+  readonly maxFiles: number;
+  readonly timeoutMs: number;
+}
+
+/** Internal filesystem seam used to make enumeration failures deterministic in tests. */
+export interface AstScanOperations {
+  readonly realpath: (filePath: string) => Promise<string>;
+  readonly stat: (filePath: string) => Promise<Stats>;
+  readonly readDirectory: (directory: string) => Promise<Dirent[]>;
+}
+
+export interface EnumerateAstFilesOptions {
+  readonly cwd: string;
+  readonly roots: readonly string[];
+  readonly operation: StructuralSearchOperation;
+  readonly deadline: number;
+  readonly maxFiles: number;
+  readonly timeoutMs?: number;
+  readonly signal?: AbortSignal;
+  readonly now?: () => number;
+  readonly operations?: AstScanOperations;
+}
+
+export type AstFileEnumeration =
+  | {
+      readonly kind: "completed";
+      readonly files: readonly string[];
+      /** Canonical cwd used to render canonical file paths consistently. */
+      readonly displayBase: string;
+      readonly eligibleFileCount: number | null;
+      readonly complete: boolean;
+      readonly policy: AstScanPolicy;
+      readonly exclusions: readonly AstScanExclusion[];
+      readonly limitations: readonly AstScanLimitation[];
+    }
+  | { readonly kind: "invalid-root"; readonly path: string; readonly reason: string };
+
+/** Materialize the operation-aware policy disclosed in structured AST Scan details. */
+export function astScanPolicy(
+  operation: StructuralSearchOperation,
+  maxFiles: number,
+  timeoutMs: number,
+): AstScanPolicy {
+  return {
+    operation,
+    supportedExtensions: getStructuralSearchSupportedExtensions(operation).sort((a, b) =>
+      a.localeCompare(b),
+    ),
+    excludedDirectories: [...AST_SCAN_EXCLUDED_DIRECTORIES],
+    hiddenEntries: "excluded",
+    ignoreFiles: false,
+    symlinks: "explicit-roots-only",
+    maxFiles,
+    timeoutMs,
+  };
+}
+
+const DEFAULT_OPERATIONS: AstScanOperations = {
+  realpath: fs.realpath,
+  stat: fs.stat,
+  readDirectory: (directory) => fs.readdir(directory, { withFileTypes: true }),
+};
+
+interface MutableObservation<T extends string> {
+  reason: T;
+  pathCount: number;
+  examples: string[];
+}
+
+/**
+ * Enumerate the deterministic AST Scan universe behind one deep interface.
+ *
+ * Explicit roots are canonicalized and honored. Policy exclusions apply only
+ * below directory roots. The shared deadline and eligible-file safety cap stop
+ * traversal early, so interrupted scans deliberately leave the total unknown.
+ */
+export async function enumerateAstFiles(
+  options: EnumerateAstFilesOptions,
+): Promise<AstFileEnumeration> {
+  return new AstFileEnumerator(options).run();
+}
+
+class AstFileEnumerator {
+  readonly #operations: AstScanOperations;
+  readonly #now: () => number;
+  readonly #grammarExtensions = new Set(getSupportedExtensions());
+  readonly #operationExtensions: ReadonlySet<string>;
+  readonly #files = new Set<string>();
+  readonly #visitedDirectories = new Set<string>();
+  readonly #exclusions = new Map<
+    AstScanExclusionReason,
+    MutableObservation<AstScanExclusionReason>
+  >();
+  readonly #limitations = new Map<
+    AstScanLimitationReason,
+    MutableObservation<AstScanLimitationReason>
+  >();
+  #interrupted = false;
+  #safetyLimited = false;
+  #displayBase: string;
+
+  constructor(readonly options: EnumerateAstFilesOptions) {
+    this.#operations = options.operations ?? DEFAULT_OPERATIONS;
+    this.#now = options.now ?? Date.now;
+    this.#operationExtensions = new Set(getStructuralSearchSupportedExtensions(options.operation));
+    this.#displayBase = path.resolve(options.cwd);
+  }
+
+  async run(): Promise<AstFileEnumeration> {
+    this.options.signal?.throwIfAborted();
+    await this.#resolveDisplayBase();
+    for (const root of this.options.roots) {
+      if (!this.#checkControl()) break;
+      const invalid = await this.#processRoot(root);
+      if (invalid) return invalid;
+    }
+    return this.#completedResult();
+  }
+
+  async #resolveDisplayBase(): Promise<void> {
+    try {
+      const outcome = await this.#settle(() => this.#operations.realpath(this.options.cwd));
+      if (outcome.kind === "completed") this.#displayBase = outcome.value;
+    } catch {
+      this.options.signal?.throwIfAborted();
+      // Scope validation owns cwd existence; retain the resolved fallback.
+    }
+  }
+
+  async #processRoot(
+    root: string,
+  ): Promise<Extract<AstFileEnumeration, { kind: "invalid-root" }> | null> {
+    let canonicalRoot: string;
+    let rootStat: Stats;
+    try {
+      const realpathOutcome = await this.#settle(() => this.#operations.realpath(root));
+      if (realpathOutcome.kind === "timeout") return null;
+      canonicalRoot = realpathOutcome.value;
+      const statOutcome = await this.#settle(() => this.#operations.stat(canonicalRoot));
+      if (statOutcome.kind === "timeout") return null;
+      rootStat = statOutcome.value;
+    } catch {
+      this.options.signal?.throwIfAborted();
+      this.#record(this.#limitations, "unreadable-path", root);
+      this.#interrupted = true;
+      return null;
+    }
+
+    if (rootStat.isFile()) return this.#processFileRoot(canonicalRoot);
+    if (rootStat.isDirectory()) {
+      await this.#walk(canonicalRoot);
+      return null;
+    }
+    return {
+      kind: "invalid-root",
+      path: this.#display(canonicalRoot),
+      reason: "Explicit AST scope is not a regular file or directory.",
+    };
+  }
+
+  #processFileRoot(
+    canonicalRoot: string,
+  ): Extract<AstFileEnumeration, { kind: "invalid-root" }> | null {
+    const exclusion = this.#fileExclusion(canonicalRoot);
+    if (exclusion === null) {
+      this.#addFile(canonicalRoot);
+      return null;
+    }
+    return {
+      kind: "invalid-root",
+      path: this.#display(canonicalRoot),
+      reason:
+        exclusion === "unsupported-extension"
+          ? "Explicit AST file scope has no supported Tree-sitter grammar."
+          : `Explicit AST file scope does not support the ${this.options.operation} operation.`,
+    };
+  }
+
+  async #walk(directory: string): Promise<void> {
+    if (!this.#checkControl() || this.#visitedDirectories.has(directory)) return;
+    this.#visitedDirectories.add(directory);
+    const entries = await this.#readDirectory(directory);
+    if (!entries) return;
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      if (!this.#checkControl()) return;
+      await this.#processEntry(directory, entry);
+    }
+  }
+
+  async #readDirectory(directory: string): Promise<Dirent[] | null> {
+    try {
+      const outcome = await this.#settle(() => this.#operations.readDirectory(directory));
+      return outcome.kind === "completed" ? outcome.value : null;
+    } catch {
+      this.options.signal?.throwIfAborted();
+      this.#record(this.#limitations, "unreadable-path", directory);
+      this.#interrupted = true;
+      return null;
+    }
+  }
+
+  async #processEntry(directory: string, entry: Dirent): Promise<void> {
+    const entryPath = path.join(directory, entry.name);
+    const exclusion = this.#entryExclusion(entry);
+    if (exclusion) {
+      this.#record(this.#exclusions, exclusion, entryPath);
+      return;
+    }
+    if (entry.isDirectory()) {
+      await this.#walk(entryPath);
+      return;
+    }
+    if (entry.isFile()) this.#addFile(entryPath);
+  }
+
+  #entryExclusion(entry: Dirent): AstScanExclusionReason | null {
+    if (entry.name.startsWith(".")) return "hidden-entry";
+    if (entry.isSymbolicLink()) return "symlink";
+    if (entry.isDirectory()) {
+      return EXCLUDED_DIRECTORY_SET.has(entry.name) ? "excluded-directory" : null;
+    }
+    if (!entry.isFile()) return "non-regular";
+    return this.#fileExclusion(entry.name);
+  }
+
+  #checkControl(): boolean {
+    this.options.signal?.throwIfAborted();
+    if (this.#safetyLimited) return false;
+    if (this.#now() <= this.options.deadline) return true;
+    this.#markTimeout();
+    return false;
+  }
+
+  async #settle<T>(operation: () => Promise<T>): Promise<DeadlineOutcome<T>> {
+    const outcome = await settleByDeadline(operation, {
+      deadline: this.options.deadline,
+      now: this.#now,
+      signal: this.options.signal,
+    });
+    if (outcome.kind === "timeout") this.#markTimeout();
+    return outcome;
+  }
+
+  #markTimeout(): void {
+    if (!this.#limitations.has("timeout")) {
+      this.#record(this.#limitations, "timeout", this.#displayBase);
+    }
+    this.#interrupted = true;
+  }
+
+  #fileExclusion(
+    filePath: string,
+  ): Extract<AstScanExclusionReason, "unsupported-extension" | "unsupported-operation"> | null {
+    const extension = path.extname(filePath).toLowerCase();
+    if (!this.#grammarExtensions.has(extension)) return "unsupported-extension";
+    return this.#operationExtensions.has(extension) ? null : "unsupported-operation";
+  }
+
+  #addFile(filePath: string): void {
+    if (this.#files.has(filePath)) return;
+    if (this.#files.size < this.options.maxFiles) {
+      this.#files.add(filePath);
+      return;
+    }
+    this.#limitations.set("safety-limit", {
+      reason: "safety-limit",
+      pathCount: 0,
+      examples: [this.#display(filePath)],
+    });
+    this.#safetyLimited = true;
+    this.#interrupted = true;
+  }
+
+  #display(filePath: string): string {
+    return relativeDisplayPath(this.#displayBase, filePath, filePath);
+  }
+
+  #record<T extends string>(
+    target: Map<T, MutableObservation<T>>,
+    reason: T,
+    filePath: string,
+  ): void {
+    const observation = target.get(reason) ?? { reason, pathCount: 0, examples: [] };
+    observation.pathCount += 1;
+    if (observation.examples.length < 5) observation.examples.push(this.#display(filePath));
+    target.set(reason, observation);
+  }
+
+  #completedResult(): Extract<AstFileEnumeration, { kind: "completed" }> {
+    const ordered = [...this.#files].sort((a, b) => a.localeCompare(b));
+    return {
+      kind: "completed",
+      files: ordered,
+      displayBase: this.#displayBase,
+      eligibleFileCount: this.#interrupted ? null : ordered.length,
+      complete: !this.#interrupted,
+      policy: astScanPolicy(
+        this.options.operation,
+        this.options.maxFiles,
+        this.options.timeoutMs ?? DEFAULT_AST_SCAN_TIMEOUT_MS,
+      ),
+      exclusions: [...this.#exclusions.values()],
+      limitations: [...this.#limitations.values()].map((entry) => ({
+        ...entry,
+        pathCount:
+          entry.reason === "timeout" || entry.reason === "safety-limit" ? null : entry.pathCount,
+      })),
+    };
+  }
+}

package/src/analysis/search/call-name.ts

@@ -0,0 +1,68 @@
+interface CallableExpressionScanState {
+  expectedClosers: string[];
+  quote: "'" | '"' | "`" | null;
+  escaped: boolean;
+  normalized: string;
+}
+
+const CALLABLE_CLOSING_DELIMITERS = new Map([
+  ["(", ")"],
+  ["[", "]"],
+  ["{", "}"],
+]);
+
+/**
+ * Remove nested payload text from a full callee expression before name matching.
+ *
+ * Tree-sitter may report outer callees such as
+ * `items.filter(value => target(value)).sort` or `[target()].join()`. The
+ * nested `target` call is a separate call site and must not make the outer
+ * sort/join match a `target` query.
+ */
+export function callableExpressionForMatching(expression: string): string {
+  const state: CallableExpressionScanState = {
+    expectedClosers: [],
+    quote: null,
+    escaped: false,
+    normalized: "",
+  };
+
+  for (const character of expression) {
+    if (consumeQuotedCharacter(state, character)) continue;
+    if (startQuotedPayload(state, character)) continue;
+    if (startDelimitedPayload(state, character)) continue;
+    if (state.expectedClosers.length > 0) {
+      consumeNestedCloser(state, character);
+      continue;
+    }
+    state.normalized += character;
+  }
+  return state.normalized;
+}
+
+function consumeQuotedCharacter(state: CallableExpressionScanState, character: string): boolean {
+  if (!state.quote) return false;
+  if (state.escaped) state.escaped = false;
+  else if (character === "\\") state.escaped = true;
+  else if (character === state.quote) state.quote = null;
+  return true;
+}
+
+function startQuotedPayload(state: CallableExpressionScanState, character: string): boolean {
+  if (character !== "'" && character !== '"' && character !== "`") return false;
+  state.quote = character;
+  if (state.expectedClosers.length === 0) state.normalized += `${character}${character}`;
+  return true;
+}
+
+function startDelimitedPayload(state: CallableExpressionScanState, character: string): boolean {
+  const closer = CALLABLE_CLOSING_DELIMITERS.get(character);
+  if (!closer) return false;
+  if (state.expectedClosers.length === 0) state.normalized += `${character}${closer}`;
+  state.expectedClosers.push(closer);
+  return true;
+}
+
+function consumeNestedCloser(state: CallableExpressionScanState, character: string): void {
+  if (character === state.expectedClosers.at(-1)) state.expectedClosers.pop();
+}

package/src/analysis/search/deadline.ts

@@ -0,0 +1,84 @@
+export type ScheduleDeadline = (callback: () => void, delayMs: number) => () => void;
+
+export interface DeadlineControl {
+  readonly deadline: number;
+  readonly now: () => number;
+  readonly signal?: AbortSignal;
+  readonly schedule?: ScheduleDeadline;
+}
+
+export type DeadlineOutcome<T> =
+  | { readonly kind: "completed"; readonly value: T }
+  | { readonly kind: "timeout" };
+
+/**
+ * Settle an asynchronous operation before a shared wall-clock deadline.
+ *
+ * The underlying operation may not support cancellation, so a late result is
+ * ignored after the timeout or abort wins the race. Callers must keep any
+ * operation-local mutation isolated until this function reports completion.
+ */
+export async function settleByDeadline<T>(
+  operation: () => Promise<T>,
+  control: DeadlineControl,
+): Promise<DeadlineOutcome<T>> {
+  control.signal?.throwIfAborted();
+  const remainingMs = control.deadline - control.now();
+  if (remainingMs < 0) return { kind: "timeout" };
+
+  return new Promise<DeadlineOutcome<T>>((resolve, reject) => {
+    let settled = false;
+    let cancelTimer: (() => void) | undefined;
+
+    const cleanup = () => {
+      cancelTimer?.();
+      control.signal?.removeEventListener("abort", onAbort);
+    };
+    const complete = (outcome: DeadlineOutcome<T>) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve(outcome);
+    };
+    const fail = (error: unknown) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(error);
+    };
+    const onAbort = () => {
+      try {
+        control.signal?.throwIfAborted();
+      } catch (error) {
+        fail(error);
+      }
+    };
+
+    control.signal?.addEventListener("abort", onAbort, { once: true });
+    if (control.signal?.aborted) {
+      onAbort();
+      return;
+    }
+    if (Number.isFinite(remainingMs)) {
+      cancelTimer = (control.schedule ?? scheduleDeadline)(
+        () => complete({ kind: "timeout" }),
+        remainingMs,
+      );
+    }
+    Promise.resolve()
+      .then(operation)
+      .then(
+        (value) => {
+          complete(
+            control.now() > control.deadline ? { kind: "timeout" } : { kind: "completed", value },
+          );
+        },
+        (error: unknown) => fail(error),
+      );
+  });
+}
+
+const scheduleDeadline: ScheduleDeadline = (callback, delayMs) => {
+  const timer = setTimeout(callback, delayMs);
+  return () => clearTimeout(timer);
+};