@mrclrchtr/supi-code-intelligence 4.10.0 → 5.0.0

package/node_modules/@mrclrchtr/supi-tree-sitter/src/session/runtime-controller.ts

@@ -1,22 +1,14 @@
-// Tree-sitter session runtime controller — pi-independent lifecycle for structural analysis.
-//
-// This controller owns runtime creation/disposal for one cwd:
-//   - Creates and disposes the TreeSitterRuntime
-//   - Creates TreeSitterService from the runtime
-//   - Publishes SessionTreeSitterService state through the existing registry
-//   - Exposes ready/unavailable lifecycle for umbrella adapter consumption
+// Tree-sitter lifecycle controller — owns one Structural Worker for one cwd.
 
+import { fileURLToPath } from "node:url";
 import type { WorkspaceRuntime } from "@mrclrchtr/supi-code-runtime/api";
-import type { SessionTreeSitterService, TreeSitterService } from "../types.ts";
-import { TreeSitterRuntime } from "./runtime.ts";
+import type { SessionTreeSitterService, TreeSitterService, TreeSitterSession } from "../types.ts";
 import {
   registerTreeSitterCapabilities,
   unregisterTreeSitterCapabilities,
 } from "./runtime-registration.ts";
 import { clearSessionTreeSitterService, setSessionTreeSitterService } from "./service-registry.ts";
-import { createTreeSitterService } from "./session.ts";
-
-// ── Types ─────────────────────────────────────────────────────────────
+import { createTreeSitterSession } from "./session.ts";
 
 /** Starting state before or after shutdown. */
 export type TsControllerState = TsControllerInitial | TsControllerReady | TsControllerUnavailable;
@@ -27,7 +19,7 @@ interface TsControllerInitial {
 
 interface TsControllerReady {
   kind: "ready";
-  runtime: TreeSitterRuntime;
+  session: TreeSitterSession;
   service: TreeSitterService;
 }
 
@@ -39,119 +31,105 @@ interface TsControllerUnavailable {
 /** Result type from {@link TreeSitterRuntimeController.start}. */
 export type TsStartResult = { kind: "ready" } | { kind: "unavailable"; reason: string };
 
-// ── Controller ────────────────────────────────────────────────────────
-
-/**
- * Pi-independent Tree-sitter session lifecycle controller.
- *
- * Use this in the umbrella extension (supi-code-intelligence) instead of
- * reaching into substrate extension internals.
- *
- * @example
- * ```ts
- * const controller = new TreeSitterRuntimeController(cwd);
- * const result = await controller.start();
- * if (result.kind === "ready") {
- *   // use controller.service, controller.runtime
- * }
- * // later
- * await controller.shutdown();
- * ```
- */
+/** Pi-independent lifecycle for one shared workspace Structural Worker. */
 export class TreeSitterRuntimeController {
   readonly #cwd: string;
-  #state: TsControllerState;
+  #state: TsControllerState = { kind: "initial" };
   #runtime: WorkspaceRuntime | null;
+  #pendingSession: TreeSitterSession | null = null;
+  #generation = 0;
+  #transition = Promise.resolve();
 
   constructor(cwd: string, runtime?: WorkspaceRuntime) {
     this.#cwd = cwd;
-    this.#state = { kind: "initial" };
     this.#runtime = runtime ?? null;
   }
 
-  /** The workspace cwd this controller was created for. */
   get cwd(): string {
     return this.#cwd;
   }
 
-  /** Current controller state. */
   get kind(): TsControllerState["kind"] {
     return this.#state.kind;
   }
 
-  /** The TreeSitterService (structural operations), available when state is "ready". */
   get service(): SessionTreeSitterService | null {
     return this.#state.kind === "ready" ? this.#state.service : null;
   }
 
-  /** The TreeSitterRuntime, available when state is "ready". */
-  get runtime(): TreeSitterRuntime | null {
-    return this.#state.kind === "ready" ? this.#state.runtime : null;
-  }
-
-  /** Attach a WorkspaceRuntime for capability registration. */
   setRuntime(runtime: WorkspaceRuntime): void {
     this.#runtime = runtime;
   }
 
-  /**
-   * Start the Tree-sitter session.
-   *
-   * Creates the runtime, wires the service, and publishes state
-   * into the shared registries. Validates that WASM initialization
-   * succeeds, returning `unavailable` if it fails.
-   */
-  async start(): Promise<TsStartResult> {
-    // Restart safety: dispose any existing runtime
-    if (this.#state.kind === "ready") {
-      this.#state.runtime.dispose();
-      if (this.#runtime) unregisterTreeSitterCapabilities(this.#runtime, this.#cwd);
-      clearSessionTreeSitterService(this.#cwd);
-    }
+  /** Start and validate one Structural Worker before capability publication. */
+  start(): Promise<TsStartResult> {
+    const generation = ++this.#generation;
+    let result: TsStartResult = supersededStart();
+    const transition = this.#transition.then(async () => {
+      if (generation !== this.#generation) return;
+      result = await this.#startGeneration(generation);
+    });
+    this.#transition = transition.catch(() => undefined);
+    return transition.then(() => result);
+  }
 
+  /** Stop publication, terminate owned Workers, and await their exit. */
+  async shutdown(): Promise<void> {
+    const generation = ++this.#generation;
+    const sessions = this.#takeOwnedSessions();
+    await Promise.all([...sessions].map((session) => session.dispose()));
+    if (generation === this.#generation) this.#state = { kind: "initial" };
+  }
+
+  async #startGeneration(generation: number): Promise<TsStartResult> {
+    const previous = this.#takeOwnedSessions();
+    await Promise.all([...previous].map((session) => session.dispose()));
+    if (generation !== this.#generation) return supersededStart();
     this.#state = { kind: "unavailable", reason: "Initializing Tree-sitter" };
 
+    const session = createTreeSitterSession(this.#cwd);
+    this.#pendingSession = session;
     try {
-      const treeSitterRuntime = new TreeSitterRuntime(this.#cwd);
-
-      // Probe WASM initialization by loading the JavaScript grammar
-      // (always vendored). This catches missing web-tree-sitter or
-      // corrupted WASM early rather than deferring to first tool use.
-      await treeSitterRuntime.ensureGrammarParser("javascript");
-
-      const service = createTreeSitterService(treeSitterRuntime);
-      setSessionTreeSitterService(this.#cwd, service);
-
-      if (this.#runtime) {
-        registerTreeSitterCapabilities(this.#runtime, this.#cwd, service);
+      const probe = await session.canParse(fileURLToPath(import.meta.url));
+      if (probe.kind !== "success") throw new Error(probe.message);
+      if (generation !== this.#generation || this.#pendingSession !== session) {
+        return supersededStart();
       }
-
-      this.#state = { kind: "ready", runtime: treeSitterRuntime, service };
+      setSessionTreeSitterService(this.#cwd, session);
+      if (this.#runtime) registerTreeSitterCapabilities(this.#runtime, this.#cwd, session);
+      this.#pendingSession = null;
+      this.#state = { kind: "ready", session, service: session };
       return { kind: "ready" };
-    } catch (error: unknown) {
+    } catch (error) {
+      if (generation !== this.#generation || this.#pendingSession !== session) {
+        return supersededStart();
+      }
+      await session.dispose();
+      this.#pendingSession = null;
       const reason = error instanceof Error ? error.message : String(error);
+      await this.#clearPublishedSession();
       this.#state = { kind: "unavailable", reason };
-      clearSessionTreeSitterService(this.#cwd);
       return { kind: "unavailable", reason };
     }
   }
 
-  /**
-   * Shut down the Tree-sitter session.
-   *
-   * Disposes the runtime and clears all published state.
-   */
-  async shutdown(): Promise<void> {
-    if (this.#runtime && this.#cwd) {
-      unregisterTreeSitterCapabilities(this.#runtime, this.#cwd);
-    }
+  async #clearPublishedSession(): Promise<void> {
+    const sessions = this.#takeOwnedSessions();
+    await Promise.all([...sessions].map((session) => session.dispose()));
+  }
 
+  #takeOwnedSessions(): Set<TreeSitterSession> {
+    if (this.#runtime) unregisterTreeSitterCapabilities(this.#runtime, this.#cwd);
     clearSessionTreeSitterService(this.#cwd);
-
-    if (this.#state.kind === "ready") {
-      this.#state.runtime.dispose();
-    }
-
+    const sessions = new Set<TreeSitterSession>();
+    if (this.#pendingSession) sessions.add(this.#pendingSession);
+    if (this.#state.kind === "ready") sessions.add(this.#state.session);
+    this.#pendingSession = null;
     this.#state = { kind: "initial" };
+    return sessions;
   }
 }
+
+function supersededStart(): TsStartResult {
+  return { kind: "unavailable", reason: "Startup superseded" };
+}

package/node_modules/@mrclrchtr/supi-tree-sitter/src/session/session.ts

@@ -1,15 +1,6 @@
-// Session factory — creates runtime-backed Tree-sitter services and owned sessions.
+// Session factory — creates asynchronous Structural Worker proxies and owned sessions.
 
-import { detectGrammar } from "../language.ts";
-import { supportsGrammarOperation } from "../operation-support.ts";
-import {
-  extractCallSites,
-  extractExports,
-  extractImports,
-  extractOutline,
-  lookupCalleesAt,
-  lookupNodeAt,
-} from "../tool/structure.ts";
+import type { CodeRequestControl } from "@mrclrchtr/supi-code-runtime/api";
 import type {
   CalleesAtResult,
   CallSiteMatch,
@@ -22,108 +13,69 @@ import type {
   TreeSitterService,
   TreeSitterSession,
 } from "../types.ts";
-import { TreeSitterRuntime } from "./runtime.ts";
+import {
+  StructuralWorkerClient,
+  type StructuralWorkerFactory,
+} from "./structural-worker-client.ts";
 
-/** Create a runtime-backed structural service without taking ownership of disposal. */
-export function createTreeSitterService(runtime: TreeSitterRuntime): TreeSitterService {
+/** Create one asynchronous service backed by an owned Structural Worker client. */
+export function createTreeSitterService(client: StructuralWorkerClient): TreeSitterService {
   return {
-    async canParse(file: string) {
-      const result = await runtime.parseFile(file);
-      if (result.kind !== "success") return result;
-      const { resolvedPath, grammarId, tree } = result.data;
-      try {
-        return {
-          kind: "success",
-          data: { file: resolvedPath, language: grammarId },
-        };
-      } finally {
-        tree.delete();
-      }
+    canParse(file, control) {
+      return execute(client, { operation: "canParse", file }, control);
     },
-
-    async query(file: string, queryString: string): Promise<TreeSitterResult<QueryCapture[]>> {
-      return runtime.queryFile(file, queryString);
+    query(file, query, control) {
+      return execute<QueryCapture[]>(client, { operation: "query", file, query }, control);
     },
-
-    async outline(file: string): Promise<TreeSitterResult<OutlineItem[]>> {
-      const grammarId = detectGrammar(file);
-      if (grammarId && !supportsGrammarOperation(grammarId, "outline")) {
-        return {
-          kind: "unsupported-language",
-          file,
-          message: `outline is not supported for ${grammarId} files`,
-        };
-      }
-      const parseResult = await runtime.parseFile(file);
-      if (parseResult.kind !== "success") return parseResult;
-      const { tree, source } = parseResult.data;
-      try {
-        const items = extractOutline(tree.rootNode, source);
-        return { kind: "success", data: items };
-      } finally {
-        tree.delete();
-      }
+    outline(file, control) {
+      return execute<OutlineItem[]>(client, { operation: "outline", file }, control);
     },
-
-    async imports(file: string): Promise<TreeSitterResult<ImportRecord[]>> {
-      const grammarId = detectGrammar(file);
-      if (grammarId && !supportsGrammarOperation(grammarId, "imports")) {
-        return {
-          kind: "unsupported-language",
-          file,
-          message: `imports is not supported for ${grammarId} files`,
-        };
-      }
-      return extractImports(runtime, file);
+    imports(file, control) {
+      return execute<ImportRecord[]>(client, { operation: "imports", file }, control);
     },
-
-    async exports(file: string): Promise<TreeSitterResult<ExportRecord[]>> {
-      const grammarId = detectGrammar(file);
-      if (grammarId && !supportsGrammarOperation(grammarId, "exports")) {
-        return {
-          kind: "unsupported-language",
-          file,
-          message: `exports is not supported for ${grammarId} files`,
-        };
-      }
-      return extractExports(runtime, file);
+    exports(file, control) {
+      return execute<ExportRecord[]>(client, { operation: "exports", file }, control);
     },
-
-    async nodeAt(
-      file: string,
-      line: number,
-      character: number,
-    ): Promise<TreeSitterResult<NodeAtResult>> {
-      return lookupNodeAt(runtime, file, line, character);
+    nodeAt(file, line, character, control) {
+      return execute<NodeAtResult>(client, { operation: "nodeAt", file, line, character }, control);
     },
-
-    async calleesAt(
-      file: string,
-      line: number,
-      character: number,
-      depth?: "direct" | "deep",
-    ): Promise<TreeSitterResult<CalleesAtResult>> {
-      return lookupCalleesAt(runtime, file, line, character, depth);
+    calleesAt(file, line, character, depthOrOptions) {
+      const depth = typeof depthOrOptions === "string" ? depthOrOptions : depthOrOptions?.depth;
+      const control = typeof depthOrOptions === "string" ? undefined : depthOrOptions?.control;
+      return execute<CalleesAtResult>(
+        client,
+        { operation: "calleesAt", file, line, character, depth },
+        control,
+      );
     },
-
-    async callSites(file: string): Promise<TreeSitterResult<CallSiteMatch[]>> {
-      return extractCallSites(runtime, file);
+    callSites(file, control) {
+      return execute<CallSiteMatch[]>(client, { operation: "callSites", file }, control);
     },
   };
 }
 
 /**
- * Create a new Tree-sitter session bound to the given working directory.
- * The session owns parser/grammar reuse and must be disposed when done.
+ * Create one Tree-sitter session bound to a working directory.
+ * Await disposal to prove that its Structural Worker has terminated.
  */
-export function createTreeSitterSession(cwd: string): TreeSitterSession {
-  const runtime = new TreeSitterRuntime(cwd);
-  const service = createTreeSitterService(runtime);
-
+export function createTreeSitterSession(
+  cwd: string,
+  options: { readonly workerFactory?: StructuralWorkerFactory } = {},
+): TreeSitterSession {
+  const client = new StructuralWorkerClient(cwd, options.workerFactory);
+  const service = createTreeSitterService(client);
   return {
     ...service,
     dispose() {
-      runtime.dispose();
+      return client.dispose();
     },
   };
 }
+
+function execute<T>(
+  client: StructuralWorkerClient,
+  input: Parameters<StructuralWorkerClient["execute"]>[0],
+  control?: CodeRequestControl,
+): Promise<TreeSitterResult<T>> {
+  return control ? client.execute<T>(input, control) : client.execute<T>(input);
+}

package/node_modules/@mrclrchtr/supi-tree-sitter/src/session/structural-timing.ts

@@ -0,0 +1,147 @@
+import { performance } from "node:perf_hooks";
+import { recordDebugEvent, startDebugTimer } from "@mrclrchtr/supi-core/debug";
+import type { StructuralCacheObservation } from "../worker/parsed-file-store.ts";
+
+/** Plain sanitized event sent from the Structural Worker to the parent. */
+export interface StructuralTimingEvent {
+  readonly operationId?: string;
+  readonly source: "tree-sitter";
+  readonly level: "debug";
+  readonly category: "structural.parse.timing" | "structural.query.timing";
+  readonly message: string;
+  readonly data: Readonly<Record<string, unknown>> & {
+    readonly timing: {
+      readonly durationMs: number;
+      readonly phasesMs: Readonly<Record<string, number>>;
+    };
+  };
+}
+
+interface StructuralTimer {
+  mark(phase: string): void;
+  finish(
+    event: Omit<StructuralTimingEvent, "data"> & { data: Record<string, unknown> },
+    finalPhase: string,
+  ): void;
+}
+
+export type ParserState = "cold" | "initializing" | "reused";
+export type ParseTimingPhase =
+  | "cache-lookup"
+  | "content-hash"
+  | "file-read"
+  | "parse"
+  | "parser-setup";
+export type QueryTimingPhase = "query-cache" | "query-compilation" | "query-execution";
+
+export type StructuralTimingObservation =
+  | {
+      readonly operation: "parse";
+      readonly grammar: string;
+      readonly parserState: ParserState;
+      readonly outcome:
+        | "cancelled"
+        | "completed"
+        | "file-access-error"
+        | "runtime-error"
+        | "timeout";
+      readonly cache?: StructuralCacheObservation;
+      readonly finalPhase: ParseTimingPhase;
+    }
+  | {
+      readonly operation: "query";
+      readonly grammar: string;
+      readonly outcome:
+        | "cancelled"
+        | "completed"
+        | "runtime-error"
+        | "timeout"
+        | "validation-error";
+      readonly captureCount: number;
+      readonly cache: StructuralCacheObservation;
+      readonly finalPhase: QueryTimingPhase;
+    };
+
+/** Start one failure-isolated Tree-sitter timing observation. */
+export function startStructuralTiming(
+  operationId?: string,
+  forward?: (event: StructuralTimingEvent) => void,
+): StructuralTimer {
+  if (forward) return createForwardedTimer(operationId, forward);
+  const timer = startDebugTimer();
+  return {
+    mark(phase) {
+      timer.mark(phase);
+    },
+    finish(event, finalPhase) {
+      timer.finish({ ...event, operationId }, finalPhase);
+    },
+  };
+}
+
+/** Finish one sanitized Tree-sitter timing observation. */
+export function finishStructuralTiming(
+  timer: StructuralTimer,
+  observation: StructuralTimingObservation,
+): void {
+  const { finalPhase, ...data } = observation;
+  timer.finish(
+    {
+      source: "tree-sitter",
+      level: "debug",
+      category: `structural.${data.operation}.timing`,
+      message: `Tree-sitter ${data.operation} ${data.outcome}`,
+      data: { ...data },
+    },
+    finalPhase,
+  );
+}
+
+/** Publish one validated Worker timing event into the parent Debug Registry. */
+export function publishStructuralTimingEvent(event: StructuralTimingEvent): void {
+  recordDebugEvent(event);
+}
+
+function createForwardedTimer(
+  operationId: string | undefined,
+  forward: (event: StructuralTimingEvent) => void,
+): StructuralTimer {
+  const startedAt = performance.now();
+  let previousAt = startedAt;
+  let finished = false;
+  const phases = new Map<string, number>();
+
+  const mark = (phase: string, current: number) => {
+    phases.set(phase, (phases.get(phase) ?? 0) + Math.max(0, current - previousAt));
+    previousAt = current;
+  };
+
+  return {
+    mark(phase) {
+      if (!finished) mark(phase, performance.now());
+    },
+    finish(event, finalPhase) {
+      if (finished) return;
+      finished = true;
+      const completedAt = performance.now();
+      mark(finalPhase, completedAt);
+      forward({
+        ...event,
+        ...(operationId ? { operationId } : {}),
+        data: {
+          ...event.data,
+          timing: {
+            durationMs: duration(completedAt - startedAt),
+            phasesMs: Object.fromEntries(
+              [...phases.entries()].map(([name, value]) => [name, duration(value)]),
+            ),
+          },
+        },
+      } as StructuralTimingEvent);
+    },
+  };
+}
+
+function duration(value: number): number {
+  return Math.round(Math.max(0, value) * 10) / 10;
+}

package/node_modules/@mrclrchtr/supi-tree-sitter/src/session/structural-worker-client-lifecycle.ts

@@ -0,0 +1,39 @@
+interface OwnedWorkerLike {
+  terminate(): Promise<number>;
+}
+
+/** Serialize every Worker start, termination, and restart ownership transition. */
+export class StructuralWorkerLifecycle {
+  #transition = Promise.resolve();
+  #generation = 0;
+
+  /** Run one transition after every older transition settles. */
+  run<T>(operation: () => Promise<T>): Promise<T> {
+    const generation = this.#generation;
+    const current = this.#transition.then(
+      () => this.#runIfCurrent(generation, operation),
+      () => this.#runIfCurrent(generation, operation),
+    );
+    this.#transition = current.then(
+      () => undefined,
+      () => undefined,
+    );
+    return current;
+  }
+
+  /** Terminate one Worker as part of the serialized transition fence. */
+  async terminate(worker: OwnedWorkerLike | null): Promise<void> {
+    this.#generation += 1;
+    if (worker) await worker.terminate().catch(() => 0);
+  }
+
+  /** Await every transition admitted before this call. */
+  settled(): Promise<void> {
+    return this.#transition;
+  }
+
+  async #runIfCurrent<T>(generation: number, operation: () => Promise<T>): Promise<T> {
+    if (generation !== this.#generation) throw new Error("Structural Worker lifecycle superseded");
+    return operation();
+  }
+}