@mrclrchtr/supi-tree-sitter 6.0.1 → 6.2.0

package/README.md

@@ -25,7 +25,6 @@ npm install @mrclrchtr/supi-tree-sitter
 
 This package provides the parser-backed structural substrate consumed by `@mrclrchtr/supi-code-intelligence`:
 
-- a shared session-scoped Tree-sitter service for structural analysis
 - an owned parsing session API for direct library consumers
 - a `StructuralProvider` adapter published through `./provider/tree-sitter-provider`
 - a long-lived owned Structural Worker that keeps Pi responsive during parser-backed work
@@ -59,18 +58,20 @@ Outline collection supports every listed family. HTML outlines contain elements
 `@mrclrchtr/supi-tree-sitter` is the **structural substrate** in SuPi's
 code-understanding stack. It depends on `@mrclrchtr/supi-core` and
 `@mrclrchtr/supi-code-runtime` for shared contracts, and provides structural
-analysis via a session-scoped Tree-sitter service that publishes its
-capabilities into the shared workspace runtime.
+analysis via a lifecycle controller that publishes its capabilities into
+the shared workspace runtime.
 
 ```text
 supi-code-runtime  ← shared contracts + workspace runtime
     ↑
-supi-tree-sitter  ← one owned Structural Worker + session-scoped service + runtime capabilities
+supi-tree-sitter  ← one owned Structural Worker + runtime capabilities
 ```
 
 ## Package surfaces
 
-- `@mrclrchtr/supi-tree-sitter/api` — reusable parsing session factory, shared session-scoped structural service access, and shared result types
+There is no package-root export. Use one of these explicit subpaths:
+
+- `@mrclrchtr/supi-tree-sitter/api` — reusable parsing session factory, lifecycle controller, language helpers, and shared result types
 - `@mrclrchtr/supi-tree-sitter/provider/tree-sitter-provider` — shared StructuralProvider adapter
 
 This is a **library-only** package. Public tool registration and pi event handlers belong to `@mrclrchtr/supi-code-intelligence`.
@@ -89,17 +90,6 @@ const callees = await session.calleesAt("src/index.ts", 42, 10);
 await session.dispose();
 ```
 
-Shared session-scoped service example:
-
-```ts
-import { getSessionTreeSitterService } from "@mrclrchtr/supi-tree-sitter/api";
-
-const state = getSessionTreeSitterService("/project");
-if (state.kind === "ready") {
-  const outline = await state.service.outline("src/index.ts");
-}
-```
-
 ## Structural performance baseline
 
 Run the stable outline fixture on the same machine and dependency versions:
@@ -117,7 +107,6 @@ All structural service operations accept optional `CodeRequestControl`. The pare
 ## Source
 
 - `src/api.ts` — public library entrypoint
-- `src/index.ts` — re-export surface
 - `src/worker/bootstrap.mjs` — package-owned Worker bootstrap and direct `jiti` loader
 - `src/worker/runtime.ts` — Worker-only parser and query runtime
 - `src/worker/parsed-file-store.ts` — Worker-only parsed-file and compiled-query reuse
@@ -125,6 +114,5 @@ All structural service operations accept optional `CodeRequestControl`. The pare
 - `src/session/runtime-controller.ts` — generation-fenced shared Worker lifecycle
 - `src/session/session.ts` — asynchronous Worker-proxy service and owned session API
 - `src/operation-support.ts` — authoritative operation-specific extension support
-- `src/session/service-registry.ts` — shared session-scoped structural service registry
 - `src/provider/tree-sitter-provider.ts` — `StructuralProvider` adapter consumed by `@mrclrchtr/supi-code-intelligence`
 - `src/tool/outline.ts`, `src/tool/outline-*.ts`, `src/tool/imports.ts`, `src/tool/exports.ts`, `src/tool/node-at.ts`, `src/tool/callees.ts`, `src/tool/call-sites.ts` — Worker-internal structural analyses

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

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

package/node_modules/@mrclrchtr/supi-code-runtime/src/capability/types.ts

@@ -75,9 +75,14 @@ export interface SemanticProvider {
     filePath: string,
     control?: CodeRequestControl,
   ): Promise<CodeQueryResult<DocumentCodeSymbol[]>>;
+  /**
+   * Collect workspace symbols from routes that can contribute within the
+   * optional canonical path scopes.
+   */
   workspaceSymbols(
     query: string,
     control?: CodeRequestControl,
+    scopes?: readonly string[],
   ): Promise<CodeQueryResult<CodeSymbol[]>>;
 
   /** Optional definition capability with explicit completed-empty semantics. */

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

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

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

@@ -0,0 +1,11 @@
+/** Maximum UTF-16 code-unit length of one debug identity string. */
+export const MAX_DEBUG_IDENTITY_STRING = 512;
+
+/** Marker appended to a truncated debug identity string. */
+export const DEBUG_IDENTITY_TRUNCATION_MARKER = "…";
+
+/** Bound one debug identity string, including its truncation marker. */
+export function truncateDebugIdentity(value: string): string {
+  if (value.length <= MAX_DEBUG_IDENTITY_STRING) return value;
+  return `${value.slice(0, MAX_DEBUG_IDENTITY_STRING - 1)}${DEBUG_IDENTITY_TRUNCATION_MARKER}`;
+}

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

@@ -3,6 +3,11 @@
 // Kept separate from debug-registry.ts so debug-timing.ts can import the
 // registry without creating an import cycle through the barrel re-export.
 
+export {
+  DEBUG_IDENTITY_TRUNCATION_MARKER,
+  MAX_DEBUG_IDENTITY_STRING,
+  truncateDebugIdentity,
+} from "./debug-identity.ts";
 // biome-ignore lint/performance/noReExportAll: preserve the stable debug domain entry point
 export * from "./debug-registry.ts";
 // biome-ignore lint/performance/noReExportAll: preserve the stable debug domain entry point

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-tree-sitter",
-  "version": "6.0.1",
+  "version": "6.2.0",
   "description": "Structural AST analysis for SuPi code intelligence",
   "license": "MIT",
   "repository": {
@@ -30,14 +30,13 @@
     "src/**/*.mjs",
     "src/**/*.json",
     "resources",
-    "scripts/*.mjs",
     "!__tests__"
   ],
   "dependencies": {
     "jiti": "^2.7.0",
     "web-tree-sitter": "^0.26.8",
-    "@mrclrchtr/supi-code-runtime": "6.0.1",
-    "@mrclrchtr/supi-core": "6.0.1"
+    "@mrclrchtr/supi-code-runtime": "6.2.0",
+    "@mrclrchtr/supi-core": "6.2.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-code-runtime",
@@ -45,7 +44,6 @@
     "jiti",
     "web-tree-sitter"
   ],
-  "main": "src/api.ts",
   "exports": {
     "./api": "./src/api.ts",
     "./package.json": "./package.json",

package/resources/grammars/kotlin/tree-sitter-kotlin.wasm.json

@@ -6,7 +6,7 @@
     "releaseAsset": "https://github.com/fwcd/tree-sitter-kotlin/releases/download/0.3.8/tree-sitter-kotlin.wasm"
   },
   "generatedWith": {
-    "treeSitterCli": "0.26.12"
+    "treeSitterCli": "0.26.13"
   },
   "sha256": "e08447e36ad5d86f39f91f13defce0636aea1490b8d65dafde6fa72649422061"
 }

package/resources/grammars/sql/tree-sitter-sql.wasm.json

@@ -5,7 +5,7 @@
     "repository": "https://github.com/derekstride/tree-sitter-sql"
   },
   "generatedWith": {
-    "treeSitterCli": "0.26.12"
+    "treeSitterCli": "0.26.13"
   },
   "sha256": "9b93a15dc3eade66df4347731f2687b939daf987c8382660d6118e863604ab09",
   "trust": {

package/src/api.ts

@@ -1,4 +1,4 @@
-// Public tree-sitter session factory, shared session service access, and shared types.
+// Public Tree-sitter session factory, lifecycle controller, and shared types.
 //
 // This package is library-only — no pi extension surface.
 // Exports structured runtime/service APIs only.
@@ -7,19 +7,11 @@
 // Language detection helpers
 export {
   detectGrammar,
-  getSupportedExtension,
   getSupportedExtensions,
-  isJsTsGrammar,
-  isSupportedFile,
 } from "./language.ts";
 export type { StructuralSearchOperation } from "./operation-support.ts";
 export { getStructuralSearchSupportedExtensions } from "./operation-support.ts";
-export type {
-  TsControllerState,
-  TsStartResult,
-} from "./session/runtime-controller.ts";
 export { TreeSitterRuntimeController } from "./session/runtime-controller.ts";
-export { getSessionTreeSitterService } from "./session/service-registry.ts";
 export { createTreeSitterSession } from "./session/session.ts";
 
 // Shared types
@@ -32,8 +24,6 @@ export type {
   NodeAtResult,
   OutlineItem,
   QueryCapture,
-  SessionTreeSitterService,
-  SessionTreeSitterServiceState,
   SourceRange,
   SupportedExtension,
   TreeSitterResult,

package/src/coordinates.ts

@@ -81,6 +81,25 @@ export function nodeToRange(
   };
 }
 
+/** Validate that a public position exists in the source bounds. */
+export function validatePublicPositionBounds(
+  line: number,
+  character: number,
+  source: string,
+): { kind: "validation-error"; message: string } | null {
+  const lines = splitSourceLines(source);
+  if (line > lines.length) {
+    return { kind: "validation-error", message: "line is beyond end of file" };
+  }
+
+  const lineText = lines[line - 1] ?? "";
+  if (character > lineText.length + 1) {
+    return { kind: "validation-error", message: "character is beyond end of line" };
+  }
+
+  return null;
+}
+
 /** Split source into logical lines without CRLF line-ending bytes. */
 export function splitSourceLines(source: string): string[] {
   return source.replace(/\r\n?/g, "\n").split("\n");

package/src/language.ts

@@ -12,7 +12,7 @@ import type { GrammarId, SupportedExtension } from "./types.ts";
 const sourceDir = path.dirname(fileURLToPath(import.meta.url));
 
 /** Mapping from file extension to grammar identifier. */
-const EXTENSION_GRAMMAR: Record<string, GrammarId> = {
+const EXTENSION_GRAMMAR = {
   ".js": "javascript",
   ".jsx": "javascript",
   ".mjs": "javascript",
@@ -48,17 +48,12 @@ const EXTENSION_GRAMMAR: Record<string, GrammarId> = {
   ".xhtml": "html",
   ".r": "r",
   ".sql": "sql",
-};
-
-const SUPPORTED_EXTENSIONS = new Set<string>(Object.keys(EXTENSION_GRAMMAR));
+} satisfies Record<SupportedExtension, GrammarId>;
 
-/** Check if a file extension is supported. */
-export function isSupportedFile(filePath: string): boolean {
-  return detectGrammar(filePath) !== undefined;
-}
+const SUPPORTED_EXTENSIONS = Object.keys(EXTENSION_GRAMMAR) as SupportedExtension[];
 
 /** Return all supported file extensions (with leading dot). */
-export function getSupportedExtensions(): string[] {
+export function getSupportedExtensions(): SupportedExtension[] {
   return [...SUPPORTED_EXTENSIONS];
 }
 
@@ -69,23 +64,10 @@ export function getSupportedExtensionGrammarEntries(): Array<
   return Object.entries(EXTENSION_GRAMMAR) as Array<readonly [SupportedExtension, GrammarId]>;
 }
 
-/** Get the file extension if it's supported, otherwise undefined. */
-export function getSupportedExtension(filePath: string): SupportedExtension | undefined {
-  const ext = path.extname(filePath).toLowerCase();
-  return SUPPORTED_EXTENSIONS.has(ext) ? (ext as SupportedExtension) : undefined;
-}
-
 /** Detect the grammar for a file. Returns undefined if unsupported. */
 export function detectGrammar(filePath: string): GrammarId | undefined {
   const ext = path.extname(filePath).toLowerCase();
-  return EXTENSION_GRAMMAR[ext];
-}
-
-const JS_TS_GRAMMARS: ReadonlySet<GrammarId> = new Set(["javascript", "typescript", "tsx"]);
-
-/** Returns true if the grammar is one the JS/TS extractors understand. */
-export function isJsTsGrammar(grammarId: GrammarId): boolean {
-  return JS_TS_GRAMMARS.has(grammarId);
+  return EXTENSION_GRAMMAR[ext as SupportedExtension];
 }
 
 /** Grammar WASM file names within the vendored resources directory. */

package/src/operation-support.ts

@@ -1,25 +1,7 @@
-import { getSupportedExtensionGrammarEntries, isJsTsGrammar } from "./language.ts";
+import { getSupportedExtensionGrammarEntries } from "./language.ts";
 import { supportsCallSitesGrammar } from "./tool/call-sites.ts";
 import type { GrammarId, SupportedExtension } from "./types.ts";
 
-const OUTLINE_GRAMMARS: ReadonlySet<GrammarId> = new Set([
-  "javascript",
-  "typescript",
-  "tsx",
-  "python",
-  "rust",
-  "go",
-  "c",
-  "cpp",
-  "java",
-  "kotlin",
-  "ruby",
-  "bash",
-  "html",
-  "r",
-  "sql",
-]);
-
 /** Structural collection operations whose language support defines an AST Scan universe. */
 const STRUCTURAL_SEARCH_OPERATIONS = ["outline", "imports", "exports", "call-sites"] as const;
 
@@ -49,10 +31,10 @@ export function supportsGrammarOperation(
     case "call-sites":
       return supportsCallSitesGrammar(grammar);
     case "outline":
-      return OUTLINE_GRAMMARS.has(grammar);
+      return true;
     case "imports":
     case "exports":
-      return isJsTsGrammar(grammar);
+      return grammar === "javascript" || grammar === "typescript" || grammar === "tsx";
     default:
       throw new TypeError(`Unsupported structural search operation: ${String(operation)}`);
   }

package/src/provider/tree-sitter-provider.ts

@@ -35,31 +35,27 @@ export function createTreeSitterProvider(service: TreeSitterService): Structural
     },
 
     async exports(file, control?) {
-      const result = control ? await service.exports(file, control) : await service.exports(file);
+      const result = await service.exports(file, control);
       return mapTreeSitterResult(result, mapExportRecords);
     },
 
     async outline(file, control?) {
-      const result = control ? await service.outline(file, control) : await service.outline(file);
+      const result = await service.outline(file, control);
       return mapTreeSitterResult(result, mapOutlineItems);
     },
 
     async imports(file, control?) {
-      const result = control ? await service.imports(file, control) : await service.imports(file);
+      const result = await service.imports(file, control);
       return mapTreeSitterResult(result, mapImportRecords);
     },
 
     async nodeAt(file, line, character, control?) {
-      const result = control
-        ? await service.nodeAt(file, line, character, control)
-        : await service.nodeAt(file, line, character);
+      const result = await service.nodeAt(file, line, character, control);
       return mapTreeSitterResult(result, mapNodeAtResult);
     },
 
     async callSites(file, control?) {
-      const result = control
-        ? await service.callSites(file, control)
-        : await service.callSites(file);
+      const result = await service.callSites(file, control);
       return mapTreeSitterResult(result, mapCallSites);
     },
   };

package/src/session/runtime-controller.ts

@@ -2,16 +2,12 @@
 
 import { fileURLToPath } from "node:url";
 import type { WorkspaceRuntime } from "@mrclrchtr/supi-code-runtime/api";
-import type { SessionTreeSitterService, TreeSitterService, TreeSitterSession } from "../types.ts";
-import {
-  registerTreeSitterCapabilities,
-  unregisterTreeSitterCapabilities,
-} from "./runtime-registration.ts";
-import { clearSessionTreeSitterService, setSessionTreeSitterService } from "./service-registry.ts";
+import { createTreeSitterProvider } from "../provider/tree-sitter-provider.ts";
+import type { TreeSitterService, TreeSitterSession } from "../types.ts";
 import { createTreeSitterSession } from "./session.ts";
 
 /** Starting state before or after shutdown. */
-export type TsControllerState = TsControllerInitial | TsControllerReady | TsControllerUnavailable;
+type TsControllerState = TsControllerInitial | TsControllerReady | TsControllerUnavailable;
 
 interface TsControllerInitial {
   kind: "initial";
@@ -29,20 +25,20 @@ interface TsControllerUnavailable {
 }
 
 /** Result type from {@link TreeSitterRuntimeController.start}. */
-export type TsStartResult = { kind: "ready" } | { kind: "unavailable"; reason: string };
+type TsStartResult = { kind: "ready" } | { kind: "unavailable"; reason: string };
 
 /** Pi-independent lifecycle for one shared workspace Structural Worker. */
 export class TreeSitterRuntimeController {
   readonly #cwd: string;
   #state: TsControllerState = { kind: "initial" };
-  #runtime: WorkspaceRuntime | null;
+  readonly #runtime: WorkspaceRuntime;
   #pendingSession: TreeSitterSession | null = null;
   #generation = 0;
   #transition = Promise.resolve();
 
-  constructor(cwd: string, runtime?: WorkspaceRuntime) {
+  constructor(cwd: string, runtime: WorkspaceRuntime) {
     this.#cwd = cwd;
-    this.#runtime = runtime ?? null;
+    this.#runtime = runtime;
   }
 
   get cwd(): string {
@@ -53,14 +49,10 @@ export class TreeSitterRuntimeController {
     return this.#state.kind;
   }
 
-  get service(): SessionTreeSitterService | null {
+  get service(): TreeSitterService | null {
     return this.#state.kind === "ready" ? this.#state.service : null;
   }
 
-  setRuntime(runtime: WorkspaceRuntime): void {
-    this.#runtime = runtime;
-  }
-
   /** Start and validate one Structural Worker before capability publication. */
   start(): Promise<TsStartResult> {
     const generation = ++this.#generation;
@@ -95,8 +87,7 @@ export class TreeSitterRuntimeController {
       if (generation !== this.#generation || this.#pendingSession !== session) {
         return supersededStart();
       }
-      setSessionTreeSitterService(this.#cwd, session);
-      if (this.#runtime) registerTreeSitterCapabilities(this.#runtime, this.#cwd, session);
+      this.#runtime.registerStructural(this.#cwd, createTreeSitterProvider(session));
       this.#pendingSession = null;
       this.#state = { kind: "ready", session, service: session };
       return { kind: "ready" };
@@ -119,8 +110,7 @@ export class TreeSitterRuntimeController {
   }
 
   #takeOwnedSessions(): Set<TreeSitterSession> {
-    if (this.#runtime) unregisterTreeSitterCapabilities(this.#runtime, this.#cwd);
-    clearSessionTreeSitterService(this.#cwd);
+    this.#runtime.clearStructural(this.#cwd);
     const sessions = new Set<TreeSitterSession>();
     if (this.#pendingSession) sessions.add(this.#pendingSession);
     if (this.#state.kind === "ready") sessions.add(this.#state.session);

package/src/session/session.ts

@@ -44,7 +44,13 @@ export function createTreeSitterService(client: StructuralWorkerClient): TreeSit
       const control = typeof depthOrOptions === "string" ? undefined : depthOrOptions?.control;
       return execute<CalleesAtResult>(
         client,
-        { operation: "calleesAt", file, line, character, depth },
+        {
+          operation: "calleesAt",
+          file,
+          line,
+          character,
+          ...(depth === undefined ? {} : { depth }),
+        },
         control,
       );
     },

package/src/session/structural-worker-client.ts

@@ -4,8 +4,6 @@ import { Worker } from "node:worker_threads";
 import {
   type CodeRequestControl,
   CodeRequestDeadlineError,
-  isCodeRequestDeadlineError,
-  isCodeRequestInterruption,
   throwIfCodeRequestInterrupted,
 } from "@mrclrchtr/supi-code-runtime/api";
 import { isDebugOperationId, startDebugTimer } from "@mrclrchtr/supi-core/debug";
@@ -20,6 +18,7 @@ import {
   STRUCTURAL_WORKER_PROTOCOL_VERSION,
   type StructuralWorkerOperation,
   type StructuralWorkerToParentMessage,
+  validateStructuralWorkerOperation,
   validateWorkerToParentMessage,
 } from "./structural-worker-protocol.ts";
 
@@ -122,6 +121,10 @@ export class StructuralWorkerClient {
     input: StructuralWorkerOperation,
     control?: CodeRequestControl,
   ): Promise<TreeSitterResult<T>> {
+    const validation = validateStructuralWorkerOperation(input);
+    if (validation.kind === "invalid") {
+      return { kind: "validation-error", message: validation.reason };
+    }
     throwIfCodeRequestInterrupted(control);
     if (this.#closed) return runtimeError("Structural Worker is shut down");
     if (control?.operationId !== undefined && !isDebugOperationId(control.operationId)) {
@@ -308,6 +311,9 @@ export class StructuralWorkerClient {
     const active = this.#active;
     if (!active || active.id !== message.requestId)
       return this.#protocolFailure("Unknown chunk request id");
+    if (active.finalSequence !== null) {
+      return this.#protocolFailure("Structural Worker sent a chunk after the final chunk");
+    }
     if (active.awaitingAck !== null) {
       return this.#protocolFailure("Structural Worker sent more than one unacknowledged chunk");
     }
@@ -530,9 +536,7 @@ export class StructuralWorkerClient {
     if (request.settled) return;
     request.settled = true;
     request.cleanupControl();
-    if (isCodeRequestInterruption(error, request.control) || isCodeRequestDeadlineError(error))
-      request.reject(error);
-    else request.reject(error);
+    request.reject(error);
   }
 }