@mrclrchtr/supi-code-intelligence 4.8.0 → 4.9.0

package/node_modules/@mrclrchtr/supi-code-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-code-runtime",
-  "version": "4.8.0",
+  "version": "4.9.0",
   "description": "Shared workspace context and capability contracts for code intelligence",
   "license": "MIT",
   "repository": {

package/node_modules/@mrclrchtr/supi-core/README.md

@@ -48,7 +48,7 @@ Config file locations:
 ### Shared registries
 
 - context-provider registry for `/supi-context`
-- debug-event registry for producers that want shared debug capture
+- debug-event registry and monotonic phase timers for producers that want shared debug capture
 - settings registry used by `/supi-settings`
 
 ### Project and session helpers
@@ -108,5 +108,7 @@ export default function myExtension(pi: ExtensionAPI) {
 
 - `src/api.ts` — exported library surface
 - `src/config.ts` — shared config loading and writing
+- `src/debug-registry.ts` — Debug domain surface, event state, retention, redaction, listeners, and queries
+- `src/debug-timing.ts` — monotonic total and phase timers for Debug Event Producers
 - `src/settings/` — settings registry, schema, scope resolution, and persistence
 - `src/report.ts` — shared text/report rendering helpers

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "4.8.0",
+  "version": "4.9.0",
   "description": "Shared settings, configuration, reporting, and session infrastructure",
   "license": "MIT",
   "repository": {

package/node_modules/@mrclrchtr/supi-core/src/debug-registry.ts

@@ -4,6 +4,9 @@
 // supi-debug extension owns policy/configuration and exposes events through a
 // command/tool while this module stays dependency-free for producers.
 
+// biome-ignore lint/performance/noReExportAll: preserve the stable debug domain entry point
+export * from "./debug-timing.ts";
+
 export type DebugLevel = "debug" | "info" | "warning" | "error";
 export type DebugAgentAccess = "off" | "sanitized" | "raw";
 export interface DebugRegistryConfig {
@@ -180,6 +183,11 @@ export function getDebugRegistryConfig(): DebugRegistryConfig {
   return cloneConfig(getState().config);
 }
 
+/** Return whether the Debug Registry currently retains producer events. */
+export function isDebugRegistryEnabled(): boolean {
+  return getState().config.enabled;
+}
+
 /** Best-effort redaction helper for data exposed through sanitized debug views. */
 export function redactDebugData<T>(value: T): T {
   return redactValue(value, 8) as T;

package/node_modules/@mrclrchtr/supi-core/src/debug-timing.ts

@@ -0,0 +1,107 @@
+import { performance } from "node:perf_hooks";
+import {
+  type DebugEvent,
+  type DebugEventInput,
+  isDebugRegistryEnabled,
+  recordDebugEvent,
+} from "./debug-registry.ts";
+
+/** Monotonic duration data added to a timed debug event. */
+export interface DebugTiming {
+  readonly durationMs: number;
+  readonly phasesMs: Readonly<Record<string, number>>;
+}
+
+/** Debug event input whose data can receive the reserved `timing` field. */
+export interface TimedDebugEventInput extends Omit<DebugEventInput, "data"> {
+  readonly data?: Readonly<Record<string, unknown>>;
+}
+
+/** Test seam for the monotonic clock used by a debug timer. */
+export interface DebugTimerOptions {
+  readonly now?: () => number;
+}
+
+/** Lazy timed-event input that is not evaluated when Debug is disabled. */
+export type TimedDebugEventFactory = () => TimedDebugEventInput;
+
+/** One-shot debug timer with optional sequential phase measurements. */
+export interface DebugTimer {
+  /** Whether this timer sampled Debug as enabled when it started. */
+  readonly enabled: boolean;
+  /** Finish the current phase and start the next unnamed interval. */
+  mark(phase: string): void;
+  /** Record one event. A second call returns `null` without recording another event. */
+  finish(
+    input: TimedDebugEventInput | TimedDebugEventFactory,
+    finalPhase?: string,
+  ): DebugEvent | null;
+}
+
+/**
+ * Start a monotonic timer for one debug event.
+ *
+ * Each `mark(name)` stores the interval since the previous mark. `finish()`
+ * stores the total duration and can name the final interval. Repeated phase
+ * names are accumulated. Event data reserves the `timing` field. When Debug is
+ * disabled at start, this returns a no-op timer and does not read the clock.
+ * Pass a factory to `finish()` to avoid event-data construction when disabled.
+ */
+export function startDebugTimer(options: DebugTimerOptions = {}): DebugTimer {
+  if (!isDebugRegistryEnabled()) return DISABLED_DEBUG_TIMER;
+  const now = options.now ?? performance.now.bind(performance);
+  const startedAt = now();
+  let previousAt = startedAt;
+  let finished = false;
+  const phases = new Map<string, number>();
+
+  const markAt = (phase: string, current: number): void => {
+    const name = phase.trim();
+    if (!name) return;
+    phases.set(name, (phases.get(name) ?? 0) + Math.max(0, current - previousAt));
+    previousAt = current;
+  };
+
+  return {
+    enabled: true,
+    mark(phase) {
+      if (finished) return;
+      markAt(phase, now());
+    },
+    finish(input, finalPhase) {
+      if (finished) return null;
+      if (!isDebugRegistryEnabled()) {
+        finished = true;
+        return null;
+      }
+      const completedAt = now();
+      if (finalPhase) markAt(finalPhase, completedAt);
+      finished = true;
+      const phasesMs = Object.fromEntries(
+        [...phases.entries()].map(([name, value]) => [name, duration(value)]),
+      );
+      const timing: DebugTiming = {
+        durationMs: duration(completedAt - startedAt),
+        phasesMs,
+      };
+      const eventInput = typeof input === "function" ? input() : input;
+      return recordDebugEvent({
+        ...eventInput,
+        data: { ...eventInput.data, timing },
+      });
+    },
+  };
+}
+
+const DISABLED_DEBUG_TIMER: DebugTimer = Object.freeze({
+  enabled: false,
+  mark() {},
+  finish() {
+    return null;
+  },
+});
+
+function duration(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return Math.round(Math.max(0, value) * 10) / 10;
+}

package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-code-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-code-runtime",
-  "version": "4.8.0",
+  "version": "4.9.0",
   "description": "Shared workspace context and capability contracts for code intelligence",
   "license": "MIT",
   "repository": {

package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-core/README.md

@@ -48,7 +48,7 @@ Config file locations:
 ### Shared registries
 
 - context-provider registry for `/supi-context`
-- debug-event registry for producers that want shared debug capture
+- debug-event registry and monotonic phase timers for producers that want shared debug capture
 - settings registry used by `/supi-settings`
 
 ### Project and session helpers
@@ -108,5 +108,7 @@ export default function myExtension(pi: ExtensionAPI) {
 
 - `src/api.ts` — exported library surface
 - `src/config.ts` — shared config loading and writing
+- `src/debug-registry.ts` — Debug domain surface, event state, retention, redaction, listeners, and queries
+- `src/debug-timing.ts` — monotonic total and phase timers for Debug Event Producers
 - `src/settings/` — settings registry, schema, scope resolution, and persistence
 - `src/report.ts` — shared text/report rendering helpers

package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "4.8.0",
+  "version": "4.9.0",
   "description": "Shared settings, configuration, reporting, and session infrastructure",
   "license": "MIT",
   "repository": {

package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-core/src/debug-registry.ts

@@ -4,6 +4,9 @@
 // supi-debug extension owns policy/configuration and exposes events through a
 // command/tool while this module stays dependency-free for producers.
 
+// biome-ignore lint/performance/noReExportAll: preserve the stable debug domain entry point
+export * from "./debug-timing.ts";
+
 export type DebugLevel = "debug" | "info" | "warning" | "error";
 export type DebugAgentAccess = "off" | "sanitized" | "raw";
 export interface DebugRegistryConfig {
@@ -180,6 +183,11 @@ export function getDebugRegistryConfig(): DebugRegistryConfig {
   return cloneConfig(getState().config);
 }
 
+/** Return whether the Debug Registry currently retains producer events. */
+export function isDebugRegistryEnabled(): boolean {
+  return getState().config.enabled;
+}
+
 /** Best-effort redaction helper for data exposed through sanitized debug views. */
 export function redactDebugData<T>(value: T): T {
   return redactValue(value, 8) as T;

package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-core/src/debug-timing.ts

@@ -0,0 +1,107 @@
+import { performance } from "node:perf_hooks";
+import {
+  type DebugEvent,
+  type DebugEventInput,
+  isDebugRegistryEnabled,
+  recordDebugEvent,
+} from "./debug-registry.ts";
+
+/** Monotonic duration data added to a timed debug event. */
+export interface DebugTiming {
+  readonly durationMs: number;
+  readonly phasesMs: Readonly<Record<string, number>>;
+}
+
+/** Debug event input whose data can receive the reserved `timing` field. */
+export interface TimedDebugEventInput extends Omit<DebugEventInput, "data"> {
+  readonly data?: Readonly<Record<string, unknown>>;
+}
+
+/** Test seam for the monotonic clock used by a debug timer. */
+export interface DebugTimerOptions {
+  readonly now?: () => number;
+}
+
+/** Lazy timed-event input that is not evaluated when Debug is disabled. */
+export type TimedDebugEventFactory = () => TimedDebugEventInput;
+
+/** One-shot debug timer with optional sequential phase measurements. */
+export interface DebugTimer {
+  /** Whether this timer sampled Debug as enabled when it started. */
+  readonly enabled: boolean;
+  /** Finish the current phase and start the next unnamed interval. */
+  mark(phase: string): void;
+  /** Record one event. A second call returns `null` without recording another event. */
+  finish(
+    input: TimedDebugEventInput | TimedDebugEventFactory,
+    finalPhase?: string,
+  ): DebugEvent | null;
+}
+
+/**
+ * Start a monotonic timer for one debug event.
+ *
+ * Each `mark(name)` stores the interval since the previous mark. `finish()`
+ * stores the total duration and can name the final interval. Repeated phase
+ * names are accumulated. Event data reserves the `timing` field. When Debug is
+ * disabled at start, this returns a no-op timer and does not read the clock.
+ * Pass a factory to `finish()` to avoid event-data construction when disabled.
+ */
+export function startDebugTimer(options: DebugTimerOptions = {}): DebugTimer {
+  if (!isDebugRegistryEnabled()) return DISABLED_DEBUG_TIMER;
+  const now = options.now ?? performance.now.bind(performance);
+  const startedAt = now();
+  let previousAt = startedAt;
+  let finished = false;
+  const phases = new Map<string, number>();
+
+  const markAt = (phase: string, current: number): void => {
+    const name = phase.trim();
+    if (!name) return;
+    phases.set(name, (phases.get(name) ?? 0) + Math.max(0, current - previousAt));
+    previousAt = current;
+  };
+
+  return {
+    enabled: true,
+    mark(phase) {
+      if (finished) return;
+      markAt(phase, now());
+    },
+    finish(input, finalPhase) {
+      if (finished) return null;
+      if (!isDebugRegistryEnabled()) {
+        finished = true;
+        return null;
+      }
+      const completedAt = now();
+      if (finalPhase) markAt(finalPhase, completedAt);
+      finished = true;
+      const phasesMs = Object.fromEntries(
+        [...phases.entries()].map(([name, value]) => [name, duration(value)]),
+      );
+      const timing: DebugTiming = {
+        durationMs: duration(completedAt - startedAt),
+        phasesMs,
+      };
+      const eventInput = typeof input === "function" ? input() : input;
+      return recordDebugEvent({
+        ...eventInput,
+        data: { ...eventInput.data, timing },
+      });
+    },
+  };
+}
+
+const DISABLED_DEBUG_TIMER: DebugTimer = Object.freeze({
+  enabled: false,
+  mark() {},
+  finish() {
+    return null;
+  },
+});
+
+function duration(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return Math.round(Math.max(0, value) * 10) / 10;
+}

package/node_modules/@mrclrchtr/supi-lsp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-lsp",
-  "version": "4.8.0",
+  "version": "4.9.0",
   "description": "Language Server Protocol runtime for SuPi code intelligence",
   "license": "MIT",
   "repository": {
@@ -37,8 +37,8 @@
     "vscode-jsonrpc": "^9.0.0",
     "vscode-languageserver-protocol": "^3.17.5",
     "vscode-languageserver-types": "^3.17.5",
-    "@mrclrchtr/supi-core": "4.8.0",
-    "@mrclrchtr/supi-code-runtime": "4.8.0"
+    "@mrclrchtr/supi-core": "4.9.0",
+    "@mrclrchtr/supi-code-runtime": "4.9.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-code-runtime",

package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-code-runtime",
-  "version": "4.8.0",
+  "version": "4.9.0",
   "description": "Shared workspace context and capability contracts for code intelligence",
   "license": "MIT",
   "repository": {

package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-core/README.md

@@ -48,7 +48,7 @@ Config file locations:
 ### Shared registries
 
 - context-provider registry for `/supi-context`
-- debug-event registry for producers that want shared debug capture
+- debug-event registry and monotonic phase timers for producers that want shared debug capture
 - settings registry used by `/supi-settings`
 
 ### Project and session helpers
@@ -108,5 +108,7 @@ export default function myExtension(pi: ExtensionAPI) {
 
 - `src/api.ts` — exported library surface
 - `src/config.ts` — shared config loading and writing
+- `src/debug-registry.ts` — Debug domain surface, event state, retention, redaction, listeners, and queries
+- `src/debug-timing.ts` — monotonic total and phase timers for Debug Event Producers
 - `src/settings/` — settings registry, schema, scope resolution, and persistence
 - `src/report.ts` — shared text/report rendering helpers

package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "4.8.0",
+  "version": "4.9.0",
   "description": "Shared settings, configuration, reporting, and session infrastructure",
   "license": "MIT",
   "repository": {

package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-core/src/debug-registry.ts

@@ -4,6 +4,9 @@
 // supi-debug extension owns policy/configuration and exposes events through a
 // command/tool while this module stays dependency-free for producers.
 
+// biome-ignore lint/performance/noReExportAll: preserve the stable debug domain entry point
+export * from "./debug-timing.ts";
+
 export type DebugLevel = "debug" | "info" | "warning" | "error";
 export type DebugAgentAccess = "off" | "sanitized" | "raw";
 export interface DebugRegistryConfig {
@@ -180,6 +183,11 @@ export function getDebugRegistryConfig(): DebugRegistryConfig {
   return cloneConfig(getState().config);
 }
 
+/** Return whether the Debug Registry currently retains producer events. */
+export function isDebugRegistryEnabled(): boolean {
+  return getState().config.enabled;
+}
+
 /** Best-effort redaction helper for data exposed through sanitized debug views. */
 export function redactDebugData<T>(value: T): T {
   return redactValue(value, 8) as T;

package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-core/src/debug-timing.ts

@@ -0,0 +1,107 @@
+import { performance } from "node:perf_hooks";
+import {
+  type DebugEvent,
+  type DebugEventInput,
+  isDebugRegistryEnabled,
+  recordDebugEvent,
+} from "./debug-registry.ts";
+
+/** Monotonic duration data added to a timed debug event. */
+export interface DebugTiming {
+  readonly durationMs: number;
+  readonly phasesMs: Readonly<Record<string, number>>;
+}
+
+/** Debug event input whose data can receive the reserved `timing` field. */
+export interface TimedDebugEventInput extends Omit<DebugEventInput, "data"> {
+  readonly data?: Readonly<Record<string, unknown>>;
+}
+
+/** Test seam for the monotonic clock used by a debug timer. */
+export interface DebugTimerOptions {
+  readonly now?: () => number;
+}
+
+/** Lazy timed-event input that is not evaluated when Debug is disabled. */
+export type TimedDebugEventFactory = () => TimedDebugEventInput;
+
+/** One-shot debug timer with optional sequential phase measurements. */
+export interface DebugTimer {
+  /** Whether this timer sampled Debug as enabled when it started. */
+  readonly enabled: boolean;
+  /** Finish the current phase and start the next unnamed interval. */
+  mark(phase: string): void;
+  /** Record one event. A second call returns `null` without recording another event. */
+  finish(
+    input: TimedDebugEventInput | TimedDebugEventFactory,
+    finalPhase?: string,
+  ): DebugEvent | null;
+}
+
+/**
+ * Start a monotonic timer for one debug event.
+ *
+ * Each `mark(name)` stores the interval since the previous mark. `finish()`
+ * stores the total duration and can name the final interval. Repeated phase
+ * names are accumulated. Event data reserves the `timing` field. When Debug is
+ * disabled at start, this returns a no-op timer and does not read the clock.
+ * Pass a factory to `finish()` to avoid event-data construction when disabled.
+ */
+export function startDebugTimer(options: DebugTimerOptions = {}): DebugTimer {
+  if (!isDebugRegistryEnabled()) return DISABLED_DEBUG_TIMER;
+  const now = options.now ?? performance.now.bind(performance);
+  const startedAt = now();
+  let previousAt = startedAt;
+  let finished = false;
+  const phases = new Map<string, number>();
+
+  const markAt = (phase: string, current: number): void => {
+    const name = phase.trim();
+    if (!name) return;
+    phases.set(name, (phases.get(name) ?? 0) + Math.max(0, current - previousAt));
+    previousAt = current;
+  };
+
+  return {
+    enabled: true,
+    mark(phase) {
+      if (finished) return;
+      markAt(phase, now());
+    },
+    finish(input, finalPhase) {
+      if (finished) return null;
+      if (!isDebugRegistryEnabled()) {
+        finished = true;
+        return null;
+      }
+      const completedAt = now();
+      if (finalPhase) markAt(finalPhase, completedAt);
+      finished = true;
+      const phasesMs = Object.fromEntries(
+        [...phases.entries()].map(([name, value]) => [name, duration(value)]),
+      );
+      const timing: DebugTiming = {
+        durationMs: duration(completedAt - startedAt),
+        phasesMs,
+      };
+      const eventInput = typeof input === "function" ? input() : input;
+      return recordDebugEvent({
+        ...eventInput,
+        data: { ...eventInput.data, timing },
+      });
+    },
+  };
+}
+
+const DISABLED_DEBUG_TIMER: DebugTimer = Object.freeze({
+  enabled: false,
+  mark() {},
+  finish() {
+    return null;
+  },
+});
+
+function duration(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return Math.round(Math.max(0, value) * 10) / 10;
+}

package/node_modules/@mrclrchtr/supi-tree-sitter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-tree-sitter",
-  "version": "4.8.0",
+  "version": "4.9.0",
   "description": "Structural AST analysis for SuPi code intelligence",
   "license": "MIT",
   "repository": {
@@ -34,8 +34,8 @@
   ],
   "dependencies": {
     "web-tree-sitter": "^0.26.8",
-    "@mrclrchtr/supi-core": "4.8.0",
-    "@mrclrchtr/supi-code-runtime": "4.8.0"
+    "@mrclrchtr/supi-code-runtime": "4.9.0",
+    "@mrclrchtr/supi-core": "4.9.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-code-runtime",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-code-intelligence",
-  "version": "4.8.0",
+  "version": "4.9.0",
   "description": "LSP and AST navigation, search, diagnostics, and refactoring",
   "license": "MIT",
   "repository": {
@@ -35,10 +35,10 @@
   ],
   "dependencies": {
     "yaml": "^2.9.0",
-    "@mrclrchtr/supi-code-runtime": "4.8.0",
-    "@mrclrchtr/supi-core": "4.8.0",
-    "@mrclrchtr/supi-lsp": "4.8.0",
-    "@mrclrchtr/supi-tree-sitter": "4.8.0"
+    "@mrclrchtr/supi-code-runtime": "4.9.0",
+    "@mrclrchtr/supi-core": "4.9.0",
+    "@mrclrchtr/supi-tree-sitter": "4.9.0",
+    "@mrclrchtr/supi-lsp": "4.9.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-code-runtime",

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

@@ -0,0 +1,59 @@
+import { startDebugTimer } from "@mrclrchtr/supi-core/debug";
+import type { StructuralSearchOperation } from "@mrclrchtr/supi-tree-sitter/api";
+import type { StructuredFileAnalysis, StructuredPatternParams } from "./pattern-analysis.ts";
+
+interface ScanContext {
+  readonly cwd: string;
+  readonly params: StructuredPatternParams;
+}
+
+interface EnumerationMetrics {
+  readonly eligibleFileCount: number | null;
+}
+
+interface AstScanTimingInput {
+  readonly context: ScanContext;
+  readonly operation: StructuralSearchOperation;
+  readonly roots: readonly string[];
+  readonly enumeration: EnumerationMetrics;
+  readonly analysis: StructuredFileAnalysis;
+  readonly complete: boolean;
+}
+
+/** One-shot timer that records aggregate AST scan phases. */
+export interface AstScanTimer {
+  enumerationCompleted(): void;
+  record(input: AstScanTimingInput): void;
+}
+
+/** Start one AST scan timer without adding paths to debug-event data. */
+export function startAstScanTimer(): AstScanTimer {
+  const timer = startDebugTimer();
+  return {
+    enumerationCompleted() {
+      timer.mark("enumeration");
+    },
+    record(input) {
+      timer.finish(
+        () => ({
+          source: "code-intelligence",
+          level: "debug",
+          category: "ast-scan.timing",
+          message: `AST ${input.context.params.kind} scan analyzed ${input.analysis.analyzedFileCount} files`,
+          cwd: input.context.cwd,
+          data: {
+            kind: input.context.params.kind,
+            operation: input.operation,
+            rootCount: input.roots.length,
+            eligibleFileCount: input.enumeration.eligibleFileCount,
+            analyzedFileCount: input.analysis.analyzedFileCount,
+            matchCount: input.analysis.matches.length,
+            failureCount: input.analysis.failures.length,
+            complete: input.complete,
+          },
+        }),
+        "analysis",
+      );
+    },
+  };
+}

package/src/analysis/search/pattern-analysis.ts

@@ -0,0 +1,230 @@
+import type {
+  CodeResult,
+  OutlineData,
+  StructuralProvider as StructuralSubstrate,
+} from "@mrclrchtr/supi-code-runtime/api";
+import type { CodeFindAstKind } from "../../tool/find/ast-kinds.ts";
+import type { AstScanLimitation } from "./ast-scan.ts";
+import { callableExpressionForMatching } from "./call-name.ts";
+import { settleByDeadline } from "./deadline.ts";
+import { relativeDisplayPath } from "./paths.ts";
+
+export interface StructuredPatternParams {
+  readonly pattern: string;
+  readonly kind: CodeFindAstKind;
+}
+
+export interface StructuredMatch {
+  readonly file: string;
+  readonly name: string;
+  readonly kind: string;
+  readonly line: number;
+}
+
+export type StructuredFailureKind = Exclude<CodeResult<never>, { kind: "success" }>["kind"];
+
+export interface StructuredFailure {
+  readonly file: string;
+  readonly kind: StructuredFailureKind;
+  readonly reason: string;
+}
+
+export type StructuredScanLimitation = AstScanLimitation | ProviderScanLimitation;
+
+export interface ProviderScanLimitation {
+  readonly reason: "provider-failure";
+  readonly pathCount: number;
+  readonly examples: readonly string[];
+}
+
+export interface StructuredFileAnalysis {
+  readonly matches: StructuredMatch[];
+  readonly failures: StructuredFailure[];
+  readonly limitations: StructuredScanLimitation[];
+  readonly analyzedFileCount: number;
+}
+
+interface AnalyzeStructuredFilesOptions {
+  readonly files: readonly string[];
+  readonly displayBase: string;
+  readonly params: StructuredPatternParams;
+  readonly structural: StructuralSubstrate;
+  readonly deadline: number;
+  readonly now: () => number;
+  readonly signal?: AbortSignal;
+  readonly initialLimitations: readonly AstScanLimitation[];
+}
+
+/** Analyze enumerated files through the operation-specific structural provider method. */
+export async function analyzeStructuredFiles(
+  options: AnalyzeStructuredFilesOptions,
+): Promise<StructuredFileAnalysis> {
+  const matches: StructuredMatch[] = [];
+  const failures: StructuredFailure[] = [];
+  const limitations: StructuredScanLimitation[] = [...options.initialLimitations];
+  const matcher = createStructuredMatcher(options.params.pattern);
+  let analyzedFileCount = 0;
+
+  for (const [index, absoluteFile] of options.files.entries()) {
+    options.signal?.throwIfAborted();
+    if (options.now() > options.deadline) {
+      addAnalysisTimeout(limitations, options.files.slice(index), options.displayBase);
+      break;
+    }
+    const relativeFile = relativeDisplayPath(options.displayBase, absoluteFile);
+    const fileMatches: StructuredMatch[] = [];
+    const fileFailures: StructuredFailure[] = [];
+    const outcome = await settleByDeadline(
+      async () => {
+        try {
+          await collectMatchesForFile(
+            fileMatches,
+            fileFailures,
+            options.structural,
+            relativeFile,
+            options.params.kind,
+            matcher,
+          );
+        } catch (error) {
+          fileFailures.push({
+            file: relativeFile,
+            kind: "runtime-error",
+            reason: errorMessage(error),
+          });
+        }
+      },
+      { deadline: options.deadline, now: options.now, signal: options.signal },
+    );
+    if (outcome.kind === "timeout") {
+      addAnalysisTimeout(limitations, options.files.slice(index), options.displayBase);
+      break;
+    }
+    options.signal?.throwIfAborted();
+    matches.push(...fileMatches);
+    failures.push(...fileFailures);
+    if (fileFailures.length === 0) analyzedFileCount += 1;
+  }
+
+  if (failures.length > 0) {
+    limitations.push({
+      reason: "provider-failure",
+      pathCount: failures.length,
+      examples: failures.slice(0, 5).map((failure) => failure.file),
+    });
+  }
+  return { matches, failures, limitations, analyzedFileCount };
+}
+
+function addAnalysisTimeout(
+  limitations: StructuredScanLimitation[],
+  remainingFiles: readonly string[],
+  cwd: string,
+): void {
+  if (limitations.some((limitation) => limitation.reason === "timeout")) return;
+  limitations.push({
+    reason: "timeout",
+    pathCount: remainingFiles.length,
+    examples: remainingFiles.slice(0, 5).map((file) => relativeDisplayPath(cwd, file)),
+  });
+}
+
+// biome-ignore lint/complexity/useMaxParams: helper takes explicit collection inputs to avoid intermediate objects in the hot path
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: kind-specific tree-sitter matching is clearest as one helper
+async function collectMatchesForFile(
+  matches: StructuredMatch[],
+  failures: StructuredFailure[],
+  structural: StructuralSubstrate,
+  relFile: string,
+  kind: CodeFindAstKind,
+  matcher: (value: string) => boolean,
+): Promise<void> {
+  const recordFailure = (kind: StructuredFailureKind, reason: string) => {
+    failures.push({ file: relFile, kind, reason });
+  };
+
+  if (kind === "definition") {
+    const outline = await structural.outline(relFile);
+    if (!handleStructuralResult(outline, recordFailure)) return;
+    for (const item of flattenOutlineItems(outline.data)) {
+      if (!matcher(item.name)) continue;
+      matches.push({ file: relFile, name: item.name, kind: item.kind, line: item.startLine });
+    }
+    return;
+  }
+
+  if (kind === "export") {
+    const exportsResult = await structural.exports(relFile);
+    if (!handleStructuralResult(exportsResult, recordFailure)) return;
+    for (const item of exportsResult.data) {
+      if (!matcher(item.name)) continue;
+      matches.push({ file: relFile, name: item.name, kind: item.kind, line: item.startLine });
+    }
+    return;
+  }
+
+  if (kind === "import") {
+    const importsResult = await structural.imports(relFile);
+    if (!handleStructuralResult(importsResult, recordFailure)) return;
+    for (const item of importsResult.data) {
+      if (!matcher(item.moduleSpecifier)) continue;
+      matches.push({
+        file: relFile,
+        name: item.moduleSpecifier,
+        kind: "import",
+        line: item.startLine,
+      });
+    }
+    return;
+  }
+
+  if (kind === "call") {
+    const callResult = await structural.callSites(relFile);
+    if (!handleStructuralResult(callResult, recordFailure)) return;
+    for (const call of callResult.data) {
+      if (!matcher(callableExpressionForMatching(call.name))) continue;
+      matches.push({ file: relFile, name: call.name, kind: "call", line: call.startLine });
+    }
+    return;
+  }
+
+  const outline = await structural.outline(relFile);
+  if (!handleStructuralResult(outline, recordFailure)) return;
+  for (const item of flattenOutlineItems(outline.data)) {
+    if (kind === "type" && !TYPE_KIND.test(item.kind.toLowerCase())) continue;
+    if (kind === "interface" && item.kind.toLowerCase() !== "interface") continue;
+    if (kind === "class" && item.kind.toLowerCase() !== "class") continue;
+    if (kind === "method" && item.kind.toLowerCase() !== "method") continue;
+    if (kind === "enum" && item.kind.toLowerCase() !== "enum") continue;
+    if (!matcher(item.name)) continue;
+    matches.push({ file: relFile, name: item.name, kind: item.kind, line: item.startLine });
+  }
+}
+
+/** Flatten provider outlines so nested class/interface/enum declarations remain searchable. */
+function flattenOutlineItems(items: readonly OutlineData[]): OutlineData[] {
+  return items.flatMap((item) => [item, ...flattenOutlineItems(item.children ?? [])]);
+}
+
+function handleStructuralResult<T>(
+  result: CodeResult<T>,
+  recordFailure: (kind: StructuredFailureKind, reason: string) => void,
+): result is { kind: "success"; data: T } {
+  if (result.kind === "success") return true;
+  recordFailure(result.kind, result.message);
+  return false;
+}
+
+function createStructuredMatcher(pattern: string): (value: string) => boolean {
+  const ignoreCase = !/[A-Z]/.test(pattern);
+  const needle = ignoreCase ? pattern.toLowerCase() : pattern;
+  return (value: string) => {
+    const haystack = ignoreCase ? value.toLowerCase() : value;
+    return haystack.includes(needle);
+  };
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : "Structural provider failed.";
+}
+
+const TYPE_KIND = /^(?:class|interface|type|enum|struct|union|record|object|concept)$/;

package/src/analysis/search/pattern.ts

@@ -1,51 +1,33 @@
-import type {
-  CodeResult,
-  OutlineData,
-  StructuralProvider as StructuralSubstrate,
-} from "@mrclrchtr/supi-code-runtime/api";
+import type { StructuralProvider as StructuralSubstrate } from "@mrclrchtr/supi-code-runtime/api";
 import type { StructuralSearchOperation } from "@mrclrchtr/supi-tree-sitter/api";
 import type { CodeFindAstKind } from "../../tool/find/ast-kinds.ts";
 import type { EvidencePartialReason } from "../evidence.ts";
 import {
   type AstScanExclusion,
-  type AstScanLimitation,
   type AstScanOperations,
   type AstScanPolicy,
   DEFAULT_AST_SCAN_MAX_FILES,
   DEFAULT_AST_SCAN_TIMEOUT_MS,
   enumerateAstFiles,
 } from "./ast-scan.ts";
-import { callableExpressionForMatching } from "./call-name.ts";
-import { settleByDeadline } from "./deadline.ts";
+import { startAstScanTimer } from "./ast-scan-timing.ts";
 import { relativeDisplayPath } from "./paths.ts";
-
-export interface StructuredPatternParams {
-  readonly pattern: string;
-  readonly kind: CodeFindAstKind;
-}
-
-export interface StructuredMatch {
-  readonly file: string;
-  readonly name: string;
-  readonly kind: string;
-  readonly line: number;
-}
-
-export type StructuredFailureKind = Exclude<CodeResult<never>, { kind: "success" }>["kind"];
-
-export interface StructuredFailure {
-  readonly file: string;
-  readonly kind: StructuredFailureKind;
-  readonly reason: string;
-}
-
-export type StructuredScanLimitation = AstScanLimitation | ProviderScanLimitation;
-
-export interface ProviderScanLimitation {
-  readonly reason: "provider-failure";
-  readonly pathCount: number;
-  readonly examples: readonly string[];
-}
+import {
+  analyzeStructuredFiles,
+  type StructuredFailure,
+  type StructuredMatch,
+  type StructuredPatternParams,
+  type StructuredScanLimitation,
+} from "./pattern-analysis.ts";
+
+export type {
+  ProviderScanLimitation,
+  StructuredFailure,
+  StructuredFailureKind,
+  StructuredMatch,
+  StructuredPatternParams,
+  StructuredScanLimitation,
+} from "./pattern-analysis.ts";
 
 /** Structured completeness state for the AST source-file scan. */
 export interface StructuredScanSummary {
@@ -98,6 +80,7 @@ export interface StructuredPatternSearchOptions {
 export async function getStructuredPatternMatches(
   options: StructuredPatternSearchOptions,
 ): Promise<StructuredPatternOutcome> {
+  const scanTimer = startAstScanTimer();
   const now = options.control?.now ?? Date.now;
   const maxFiles = options.control?.maxFiles ?? DEFAULT_AST_SCAN_MAX_FILES;
   const timeoutMs = options.control?.timeoutMs ?? DEFAULT_AST_SCAN_TIMEOUT_MS;
@@ -143,6 +126,7 @@ export async function getStructuredPatternMatches(
     };
   }
 
+  scanTimer.enumerationCompleted();
   const analysis = await analyzeStructuredFiles({
     files: enumeration.files,
     displayBase: enumeration.displayBase,
@@ -156,13 +140,14 @@ export async function getStructuredPatternMatches(
   const capabilityMismatches = analysis.failures.filter(
     (failure) => failure.kind === "unsupported-language",
   );
+  const complete = enumeration.complete && analysis.limitations.length === 0;
+  scanTimer.record({ context: options, operation, roots, enumeration, analysis, complete });
   if (capabilityMismatches.length > 0) {
     return {
       kind: "unavailable",
       reason: `Structural provider rejected ${capabilityMismatches.length} file${capabilityMismatches.length === 1 ? "" : "s"} declared eligible for ${operation} analysis.`,
     };
   }
-  const complete = enumeration.complete && analysis.limitations.length === 0;
   return {
     kind: "completed",
     result: {
@@ -183,92 +168,6 @@ export async function getStructuredPatternMatches(
   };
 }
 
-interface AnalyzeStructuredFilesOptions {
-  readonly files: readonly string[];
-  readonly displayBase: string;
-  readonly params: StructuredPatternParams;
-  readonly structural: StructuralSubstrate;
-  readonly deadline: number;
-  readonly now: () => number;
-  readonly signal?: AbortSignal;
-  readonly initialLimitations: readonly AstScanLimitation[];
-}
-
-async function analyzeStructuredFiles(options: AnalyzeStructuredFilesOptions): Promise<{
-  matches: StructuredMatch[];
-  failures: StructuredFailure[];
-  limitations: StructuredScanLimitation[];
-  analyzedFileCount: number;
-}> {
-  const matches: StructuredMatch[] = [];
-  const failures: StructuredFailure[] = [];
-  const limitations: StructuredScanLimitation[] = [...options.initialLimitations];
-  const matcher = createStructuredMatcher(options.params.pattern);
-  let analyzedFileCount = 0;
-
-  for (const [index, absoluteFile] of options.files.entries()) {
-    options.signal?.throwIfAborted();
-    if (options.now() > options.deadline) {
-      addAnalysisTimeout(limitations, options.files.slice(index), options.displayBase);
-      break;
-    }
-    const relativeFile = relativeDisplayPath(options.displayBase, absoluteFile);
-    const fileMatches: StructuredMatch[] = [];
-    const fileFailures: StructuredFailure[] = [];
-    const outcome = await settleByDeadline(
-      async () => {
-        try {
-          await collectMatchesForFile(
-            fileMatches,
-            fileFailures,
-            options.structural,
-            relativeFile,
-            options.params.kind,
-            matcher,
-          );
-        } catch (error) {
-          fileFailures.push({
-            file: relativeFile,
-            kind: "runtime-error",
-            reason: errorMessage(error),
-          });
-        }
-      },
-      { deadline: options.deadline, now: options.now, signal: options.signal },
-    );
-    if (outcome.kind === "timeout") {
-      addAnalysisTimeout(limitations, options.files.slice(index), options.displayBase);
-      break;
-    }
-    options.signal?.throwIfAborted();
-    matches.push(...fileMatches);
-    failures.push(...fileFailures);
-    if (fileFailures.length === 0) analyzedFileCount += 1;
-  }
-
-  if (failures.length > 0) {
-    limitations.push({
-      reason: "provider-failure",
-      pathCount: failures.length,
-      examples: failures.slice(0, 5).map((failure) => failure.file),
-    });
-  }
-  return { matches, failures, limitations, analyzedFileCount };
-}
-
-function addAnalysisTimeout(
-  limitations: StructuredScanLimitation[],
-  remainingFiles: readonly string[],
-  cwd: string,
-): void {
-  if (limitations.some((limitation) => limitation.reason === "timeout")) return;
-  limitations.push({
-    reason: "timeout",
-    pathCount: remainingFiles.length,
-    examples: remainingFiles.slice(0, 5).map((file) => relativeDisplayPath(cwd, file)),
-  });
-}
-
 function primaryPartialReason(
   limitations: readonly StructuredScanLimitation[],
 ): EvidencePartialReason {
@@ -282,94 +181,6 @@ function primaryPartialReason(
   return "provider-limited";
 }
 
-// biome-ignore lint/complexity/useMaxParams: helper takes explicit collection inputs to avoid intermediate objects in the hot path
-// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: kind-specific tree-sitter matching is clearest as one helper
-async function collectMatchesForFile(
-  matches: StructuredMatch[],
-  failures: StructuredFailure[],
-  structural: StructuralSubstrate,
-  relFile: string,
-  kind: CodeFindAstKind,
-  matcher: (value: string) => boolean,
-): Promise<void> {
-  const recordFailure = (kind: StructuredFailureKind, reason: string) => {
-    failures.push({ file: relFile, kind, reason });
-  };
-
-  if (kind === "definition") {
-    const outline = await structural.outline(relFile);
-    if (!handleStructuralResult(outline, recordFailure)) return;
-    for (const item of flattenOutlineItems(outline.data)) {
-      if (!matcher(item.name)) continue;
-      matches.push({ file: relFile, name: item.name, kind: item.kind, line: item.startLine });
-    }
-    return;
-  }
-
-  if (kind === "export") {
-    const exportsResult = await structural.exports(relFile);
-    if (!handleStructuralResult(exportsResult, recordFailure)) return;
-    for (const item of exportsResult.data) {
-      if (!matcher(item.name)) continue;
-      matches.push({ file: relFile, name: item.name, kind: item.kind, line: item.startLine });
-    }
-    return;
-  }
-
-  if (kind === "import") {
-    const importsResult = await structural.imports(relFile);
-    if (!handleStructuralResult(importsResult, recordFailure)) return;
-    for (const item of importsResult.data) {
-      if (!matcher(item.moduleSpecifier)) continue;
-      matches.push({
-        file: relFile,
-        name: item.moduleSpecifier,
-        kind: "import",
-        line: item.startLine,
-      });
-    }
-    return;
-  }
-
-  if (kind === "call") {
-    const callResult = await structural.callSites(relFile);
-    if (!handleStructuralResult(callResult, recordFailure)) return;
-    for (const call of callResult.data) {
-      if (!matcher(callableExpressionForMatching(call.name))) continue;
-      matches.push({ file: relFile, name: call.name, kind: "call", line: call.startLine });
-    }
-    return;
-  }
-
-  const outline = await structural.outline(relFile);
-  if (!handleStructuralResult(outline, recordFailure)) return;
-  for (const item of flattenOutlineItems(outline.data)) {
-    if (kind === "type" && !TYPE_KIND.test(item.kind.toLowerCase())) continue;
-    if (kind === "interface" && item.kind.toLowerCase() !== "interface") continue;
-    if (kind === "class" && item.kind.toLowerCase() !== "class") continue;
-    if (kind === "method" && item.kind.toLowerCase() !== "method") continue;
-    if (kind === "enum" && item.kind.toLowerCase() !== "enum") continue;
-    if (!matcher(item.name)) continue;
-    matches.push({ file: relFile, name: item.name, kind: item.kind, line: item.startLine });
-  }
-}
-
-/** Flatten provider outlines so nested class/interface/enum declarations remain searchable. */
-function flattenOutlineItems(items: readonly OutlineData[]): OutlineData[] {
-  return items.flatMap((item) => [item, ...flattenOutlineItems(item.children ?? [])]);
-}
-
-function handleStructuralResult<T>(
-  result: CodeResult<T>,
-  recordFailure: (kind: StructuredFailureKind, reason: string) => void,
-): result is { kind: "success"; data: T } {
-  if (result.kind === "success") return true;
-  recordFailure(result.kind, result.message);
-  return false;
-}
-
-const TYPE_KIND = /^(?:class|interface|type|enum|struct|union|record|object|concept)$/;
-
 const AST_KIND_OPERATIONS = {
   definition: "outline",
   import: "imports",
@@ -385,16 +196,3 @@ const AST_KIND_OPERATIONS = {
 function structuralOperationForKind(kind: CodeFindAstKind): StructuralSearchOperation {
   return AST_KIND_OPERATIONS[kind];
 }
-
-function createStructuredMatcher(pattern: string): (value: string) => boolean {
-  const ignoreCase = !/[A-Z]/.test(pattern);
-  const needle = ignoreCase ? pattern.toLowerCase() : pattern;
-  return (value: string) => {
-    const haystack = ignoreCase ? value.toLowerCase() : value;
-    return haystack.includes(needle);
-  };
-}
-
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : "Structural provider failed.";
-}