@mrclrchtr/supi-code-intelligence 6.3.0 → 7.0.0

package/src/substrate/lsp/source-tracking.ts

@@ -0,0 +1,252 @@
+import { statSync } from "node:fs";
+import * as path from "node:path";
+import {
+  type CodeRequestControl,
+  throwIfCodeRequestInterrupted,
+} from "@mrclrchtr/supi-code-runtime/api";
+import { isWithinOrEqual } from "@mrclrchtr/supi-core/api";
+import type {
+  BulkTrackFileOutcome,
+  WorkspaceLspRuntime,
+  WorkspaceSourceInventory,
+} from "@mrclrchtr/supi-lsp/api";
+import { isMissingFileError, MAX_BULK_TRACK_FILES } from "@mrclrchtr/supi-lsp/api";
+
+/** Typed session state for sentinel maintenance and automatic source tracking. */
+export interface LspMaintenanceState {
+  readonly sentinelSnapshot: Map<string, number>;
+  readonly sourceBaseline: ReadonlySet<string> | null;
+  readonly createdSourceQueue: readonly string[];
+}
+
+/** Source discovery and tracking facts from one broad diagnostic refresh. */
+export interface SourceTrackingReport {
+  readonly status: WorkspaceSourceInventory["status"];
+  readonly reason: WorkspaceSourceInventory["reason"];
+  readonly observedFileCount: number;
+  readonly discovered: readonly string[];
+  readonly tracked: readonly string[];
+  /**
+   * Candidates skipped by automatic policy or tracking preconditions. This can
+   * include policy exclusions, unsupported automatic routes, and paths that
+   * are no longer regular; it is not a server capability result.
+   */
+  readonly skipped: readonly string[];
+  readonly unavailable: readonly string[];
+  readonly deferred: number;
+}
+
+/** Create empty source state with an optional lifecycle-seeded sentinel snapshot. */
+export function createLspMaintenanceState(
+  sentinelSnapshot: Map<string, number> = new Map(),
+): LspMaintenanceState {
+  return {
+    sentinelSnapshot,
+    sourceBaseline: null,
+    createdSourceQueue: [],
+  };
+}
+
+/** Replace the sentinel portion of maintenance state without source state. */
+export function withSentinelSnapshot(
+  state: LspMaintenanceState,
+  sentinelSnapshot: Map<string, number>,
+): LspMaintenanceState {
+  return { ...state, sentinelSnapshot };
+}
+
+/** Discover source additions and process a bounded queue for one refresh. */
+export async function trackCreatedSources(options: {
+  readonly runtime: WorkspaceLspRuntime;
+  readonly cwd: string;
+  readonly state: LspMaintenanceState;
+  readonly scope?: string | null;
+  readonly control?: CodeRequestControl;
+}): Promise<{ state: LspMaintenanceState; report: SourceTrackingReport }> {
+  const inventory = await options.runtime.scanWorkspaceSources(options.control);
+  throwIfCodeRequestInterrupted(options.control);
+  if (inventory.status === "limited") {
+    return {
+      state: options.state,
+      report: createReport({
+        cwd: options.cwd,
+        inventory,
+        discovered: [],
+        tracked: [],
+        skipped: [],
+        unavailable: [],
+        deferred: options.state.createdSourceQueue,
+        control: options.control,
+      }),
+    };
+  }
+
+  const discovered = discoverCreatedPaths(
+    options.state.sourceBaseline,
+    inventory.files,
+    options.control,
+  );
+  const queue = removeMissingPaths(
+    options.state.sourceBaseline === null
+      ? []
+      : deduplicatePaths([...options.state.createdSourceQueue, ...discovered], options.control),
+    options.control,
+  );
+  const selected = selectScopedPaths(queue, options.cwd, options.scope, options.control).slice(
+    0,
+    MAX_BULK_TRACK_FILES,
+  );
+  const batch =
+    selected.length === 0
+      ? { outcomes: [] as const }
+      : await options.runtime.bulkTrackFiles(selected, options.control);
+  const nextQueue = retainQueuePaths(queue, selected, batch.outcomes, options.control);
+  const nextState: LspMaintenanceState = {
+    sentinelSnapshot: options.state.sentinelSnapshot,
+    sourceBaseline: new Set(inventory.files),
+    createdSourceQueue: nextQueue,
+  };
+
+  const tracked = pathsForOutcome(batch.outcomes, "tracked");
+  const skipped = pathsForOutcome(batch.outcomes, "skipped");
+  const unavailable = pathsForOutcome(batch.outcomes, "unavailable");
+  return {
+    state: nextState,
+    report: createReport({
+      cwd: options.cwd,
+      inventory,
+      discovered,
+      tracked,
+      skipped,
+      unavailable,
+      deferred: nextQueue,
+      control: options.control,
+    }),
+  };
+}
+
+function discoverCreatedPaths(
+  baseline: ReadonlySet<string> | null,
+  current: readonly string[],
+  control?: CodeRequestControl,
+): string[] {
+  if (baseline === null) return [];
+  const discovered: string[] = [];
+  for (const filePath of current) {
+    throwIfCodeRequestInterrupted(control);
+    if (!baseline.has(filePath)) discovered.push(filePath);
+  }
+  return discovered;
+}
+
+function selectScopedPaths(
+  queue: readonly string[],
+  cwd: string,
+  scope: string | null | undefined,
+  control?: CodeRequestControl,
+): string[] {
+  const resolvedScope = scope === null || scope === undefined ? null : path.resolve(cwd, scope);
+  const selected: string[] = [];
+  for (const filePath of queue) {
+    throwIfCodeRequestInterrupted(control);
+    if (resolvedScope === null || isWithinOrEqual(resolvedScope, filePath)) selected.push(filePath);
+  }
+  return selected;
+}
+
+function retainQueuePaths(
+  queue: readonly string[],
+  selected: readonly string[],
+  outcomes: readonly BulkTrackFileOutcome[],
+  control?: CodeRequestControl,
+): string[] {
+  const selectedSet = new Set(selected);
+  const outcomeByPath = new Map(outcomes.map((outcome) => [outcome.file, outcome] as const));
+  const unstarted: string[] = [];
+  const unavailable: string[] = [];
+
+  for (const filePath of queue) {
+    throwIfCodeRequestInterrupted(control);
+    if (!selectedSet.has(filePath)) {
+      unstarted.push(filePath);
+      continue;
+    }
+    const outcome = outcomeByPath.get(filePath);
+    if (!outcome) {
+      unstarted.push(filePath);
+    } else if (outcome.kind === "unavailable") {
+      unavailable.push(filePath);
+    }
+  }
+  return [...unstarted, ...unavailable];
+}
+
+function pathsForOutcome(
+  outcomes: readonly BulkTrackFileOutcome[],
+  kind: BulkTrackFileOutcome["kind"],
+): string[] {
+  return outcomes.filter((outcome) => outcome.kind === kind).map((outcome) => outcome.file);
+}
+
+function createReport(options: {
+  cwd: string;
+  inventory: WorkspaceSourceInventory;
+  discovered: readonly string[];
+  tracked: readonly string[];
+  skipped: readonly string[];
+  unavailable: readonly string[];
+  deferred: readonly string[];
+  control?: CodeRequestControl;
+}): SourceTrackingReport {
+  return {
+    status: options.inventory.status,
+    reason: options.inventory.reason,
+    observedFileCount: options.inventory.observedFileCount,
+    discovered: displayPaths(options.cwd, options.discovered, options.control),
+    tracked: displayPaths(options.cwd, options.tracked, options.control),
+    skipped: displayPaths(options.cwd, options.skipped, options.control),
+    unavailable: displayPaths(options.cwd, options.unavailable, options.control),
+    deferred: options.deferred.length,
+  };
+}
+
+function displayPaths(
+  cwd: string,
+  filePaths: readonly string[],
+  control?: CodeRequestControl,
+): string[] {
+  const displayed: string[] = [];
+  for (const filePath of filePaths) {
+    throwIfCodeRequestInterrupted(control);
+    const relativePath = path.relative(cwd, filePath);
+    displayed.push((relativePath || path.basename(filePath)).replaceAll(path.sep, "/"));
+  }
+  return displayed;
+}
+
+function deduplicatePaths(filePaths: readonly string[], control?: CodeRequestControl): string[] {
+  const unique = new Set<string>();
+  for (const filePath of filePaths) {
+    throwIfCodeRequestInterrupted(control);
+    unique.add(filePath);
+  }
+  return [...unique];
+}
+
+function removeMissingPaths(filePaths: readonly string[], control?: CodeRequestControl): string[] {
+  const existing: string[] = [];
+  for (const filePath of filePaths) {
+    throwIfCodeRequestInterrupted(control);
+    if (!isMissingFile(filePath)) existing.push(filePath);
+  }
+  return existing;
+}
+
+function isMissingFile(filePath: string): boolean {
+  try {
+    statSync(filePath);
+    return false;
+  } catch (error) {
+    return isMissingFileError(error);
+  }
+}

package/src/tool/code_find/guidance.ts

@@ -1,8 +1,8 @@
 export const toolDescription =
-  'Search source shape with mode:"ast" or LSP workspace symbols with mode:"semantic". Modes never silently fall back. Unscoped AST scans cover visible supported files, skipping hidden and generated/dependency directories.';
+  "Search workspace symbols in semantic mode, or declaration, import, export, and call names in AST mode. Use PI grep for literal or regular-expression file-content search. The selected mode does not switch to another search method.";
 
-export const promptSnippet = "explicit structural or semantic code search";
+export const promptSnippet = "search code structure or workspace symbols";
 
 export const promptGuidelines = [
-  "Use code_find for structural or semantic search evidence; use PI grep for literal/regex source search and code_graph references for symbol-identity relationships.",
+  "Use code_find for broad code-aware discovery, code_resolve for target identity, and code_graph for relationships.",
 ];

package/src/tool/code_find/spec.ts

@@ -1,7 +1,7 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
 import type { CodeIntelToolExecCtx } from "../../types/index.ts";
-import { FindScopeParam, MaxResultsParam, QueryParam } from "../schemas.ts";
+import { FindQueryParam, FindScopeParam, MaxResultsParam } from "../schemas.ts";
 import { CODE_FIND_AST_KINDS } from "./ast-kinds.ts";
 import { executeFindTool } from "./execute.ts";
 import { CODE_FIND_MODES } from "./modes.ts";
@@ -16,14 +16,15 @@ export const codeFindSpec = {
   label: CODE_FIND_TOOL_LABEL,
   parameters: Type.Object(
     {
-      query: QueryParam,
+      query: FindQueryParam,
       scope: Type.Optional(FindScopeParam),
       mode: StringEnum(CODE_FIND_MODES, {
-        description: 'Required code-aware search mode. mode:"ast" requires `kind`.',
+        description:
+          "Required code-aware search mode. AST mode requires `kind`; semantic mode rejects `kind`.",
       }),
       kind: Type.Optional(
         StringEnum(CODE_FIND_AST_KINDS, {
-          description: 'AST kind for mode:"ast".',
+          description: 'AST structure kind; required only for mode:"ast".',
         }),
       ),
       maxResults: Type.Optional(MaxResultsParam),

package/src/tool/code_find/tui.ts

@@ -37,5 +37,11 @@ export function renderFindResult(
   theme: Theme,
   context: ToolRendererContext | undefined,
 ): ReturnType<typeof renderSimpleResult> {
-  return renderSimpleResult(result, options, theme, "Searching…", context);
+  return renderSimpleResult(
+    result,
+    options,
+    theme,
+    { progress: "Searching…", failure: "code_find failed" },
+    context,
+  );
 }

package/src/tool/code_graph/details.ts

@@ -0,0 +1,32 @@
+import type { EvidenceListMetadata } from "../../analysis/evidence.ts";
+import type { ReadNextItem } from "../../analysis/read-next.ts";
+import type { CalleeScope } from "../../analysis/relations/types.ts";
+import type { GraphRelationKind } from "../../session/graph-types.ts";
+
+/** File heading for the next count rows in the relation's bounded display section. */
+export interface GraphFileGroup {
+  file: string;
+  count: number;
+}
+
+/** Relation status and context kept for the human transcript. Counts live in evidenceLists. */
+export interface GraphSectionDetails {
+  rel: GraphRelationKind;
+  source: "semantic" | "structural";
+  status: "complete" | "partial" | "unavailable";
+  message: string | null;
+  externalCount: number;
+  enclosingScope: CalleeScope | null;
+  depth: "direct" | "deep" | null;
+  /** Absent in older results whose display rows already contain full paths. */
+  fileGroups?: GraphFileGroup[];
+}
+
+/** Persisted graph facts. The TUI does not read or parse agent Markdown. */
+export interface GraphDetails {
+  targetName: string;
+  targetFile: string;
+  sections: GraphSectionDetails[];
+  evidenceLists: EvidenceListMetadata[];
+  readNext: ReadNextItem[];
+}

package/src/tool/code_graph/display.ts

@@ -0,0 +1,54 @@
+import type { CallEntry, ReferenceEntry } from "../../analysis/relations/types.ts";
+import { toDisplayPath } from "../../analysis/search/paths.ts";
+import { createToolDisplaySection } from "../result/display.ts";
+import type { ToolDisplaySection } from "../result/types.ts";
+import type { GraphFileGroup } from "./details.ts";
+import { compactGraphLabel } from "./format.ts";
+import type { AssembledGraphSection } from "./result.ts";
+
+/** Bound sites before grouping them. Each file group partitions the display rows. */
+export function graphDisplaySection(
+  section: AssembledGraphSection,
+  cwd: string,
+): {
+  display: ToolDisplaySection;
+  fileGroups: GraphFileGroup[];
+} {
+  if (section.kind === "unavailable") {
+    return {
+      display: createToolDisplaySection({
+        key: `graph.${section.rel}`,
+        title: section.rel,
+        items: [],
+        format: () => "",
+      }),
+      fileGroups: [],
+    };
+  }
+  const items = section.evidence.items as readonly (CallEntry | ReferenceEntry)[];
+  const display = createToolDisplaySection({
+    key: `graph.${section.rel}`,
+    title: section.rel,
+    items,
+    totalCount: section.evidence.metadata.totalCount,
+    omittedCount: section.evidence.metadata.omittedCount,
+    partialReason: section.evidence.metadata.partialReason,
+    format: (item) => {
+      const site = `L${item.line}:${item.character}`;
+      if (section.rel !== "callees") return site;
+      const call = item as CallEntry;
+      return `${site} — ${compactGraphLabel(call.displayName ?? call.name)}`;
+    },
+  });
+  const groups = new Map<string, string[]>();
+  for (let index = 0; index < display.shownCount; index++) {
+    const file = toDisplayPath(cwd, items[index].file);
+    const rows = groups.get(file) ?? [];
+    rows.push(display.lines[index]);
+    groups.set(file, rows);
+  }
+  return {
+    display: { ...display, lines: [...groups.values()].flat() },
+    fileGroups: [...groups].map(([file, rows]) => ({ file, count: rows.length })),
+  };
+}

package/src/tool/code_graph/format.ts

@@ -0,0 +1,60 @@
+import type { EvidenceListMetadata } from "../../analysis/evidence.ts";
+
+/** Format graph counts and all known limits in one place. */
+export function formatGraphEvidence(
+  metadata: Omit<EvidenceListMetadata, "partialReason"> & { partialReason: string | null },
+  noun: "locations" | "call sites" | "candidates",
+  externalCount = 0,
+): string {
+  const { shownCount, totalCount, omittedCount, partialReason, invalidLocationCount } = metadata;
+  const count = totalCount ?? shownCount;
+  const label = count === 1 ? singularGraphNoun(noun) : noun;
+  let text =
+    totalCount === null
+      ? `${shownCount} ${label} shown${omittedCount ? `; ${omittedCount} collected omitted` : ""}; more may exist — ${partialReason}`
+      : omittedCount
+        ? `${shownCount} of ${totalCount} ${label} shown; ${omittedCount} omitted`
+        : `${totalCount} ${label}`;
+  if (externalCount > 0)
+    text += `; ${externalCount} external location${externalCount === 1 ? "" : "s"}`;
+  if (invalidLocationCount) {
+    const invalidNoun = invalidLocationCount === 1 ? "location" : "locations";
+    text += `; ${invalidLocationCount} invalid provider ${invalidNoun} omitted (invalid-provider-location)`;
+  }
+  return text;
+}
+
+function singularGraphNoun(noun: "locations" | "call sites" | "candidates"): string {
+  switch (noun) {
+    case "locations":
+      return "location";
+    case "call sites":
+      return "call site";
+    case "candidates":
+      return "candidate";
+  }
+}
+
+/** Format a 1-based source-line range for either graph presentation. */
+export function formatGraphRange(scope: { startLine: number; endLine: number }): string {
+  return scope.startLine === scope.endLine
+    ? `L${scope.startLine}`
+    : `L${scope.startLine}–L${scope.endLine}`;
+}
+
+/** Bound a source label while keeping both ends of a chained expression. */
+export function compactGraphLabel(value: string, limit = 100): string {
+  const text = value.replace(/\s+/g, " ").trim();
+  if (text.length <= limit) return text;
+  const tail = Math.floor(limit / 3);
+  return `${text.slice(0, limit - tail - 1)}…${text.slice(-tail)}`;
+}
+
+/** Quote source text that can contain Markdown backticks. */
+export function graphCodeSpan(text: string): string {
+  const runs = text.match(/`+/g) ?? [];
+  const delimiter = "`".repeat(Math.max(0, ...runs.map((run) => run.length)) + 1);
+  return text.startsWith("`") || text.endsWith("`")
+    ? `${delimiter} ${text} ${delimiter}`
+    : `${delimiter}${text}${delimiter}`;
+}

package/src/tool/code_graph/guidance.ts

@@ -1,6 +1,6 @@
 export const toolDescription =
-  "Collect references, structural callees, and implementations for one target. Callees match source shape, not symbol identity.";
+  "Find semantic references and implementations, or non-symbol-aware structural calls written inside a target's enclosing scope.";
 
-export const promptSnippet = "provider-backed and structural relation evidence";
+export const promptSnippet = "trace code relationships";
 
 export const promptGuidelines: string[] = [];