@mrclrchtr/supi-tree-sitter 8.0.1 → 9.1.0

package/README.md

@@ -27,7 +27,7 @@ This package provides the parser-backed structural substrate consumed by `@mrclr
 
 - 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
+- one long-lived Structural Worker in a dedicated Node process; the Worker keeps Pi responsive during parser-backed work
 - `CodeRequestControl` cancellation, absolute deadlines, shared atomic interruption, and hard-stop termination
 - structural outline/import/export/node/callee/call-site operations through the asynchronous service surface
 - operation-specific extension discovery through `getStructuralSearchSupportedExtensions()`
@@ -50,8 +50,13 @@ Coordinates in the library APIs use **1-based** line and character columns. Char
 - HTML (`.html`, `.htm`, `.xhtml`)
 - R (`.r`)
 - SQL (`.sql`)
+- LaTeX (`.tex`, `.sty`, `.cls`)
 
-Outline collection supports every listed family. HTML outlines contain elements with non-empty `id` attributes; SQL outlines contain `CREATE` declarations and shallow table/type members. Import and export collection remains JavaScript/TypeScript-only, and call-site collection supports every listed family except HTML and SQL. Go module manifests and ERB templates are intentionally excluded because the Go and Ruby grammars do not parse those mixed or separate syntaxes; `supi-lsp` still handles them semantically. Consumers performing a bulk structural scan should use `getStructuralSearchSupportedExtensions(operation)` rather than treating parser support as operation support.
+Outline collection supports every listed family. HTML outlines list elements with a non-empty `id` attribute. SQL outlines list `CREATE` declarations and their first-level table and type members. LaTeX outlines list section headings and command, environment, label, acronym, glossary-entry, and color definitions.
+
+Import collection supports JavaScript, TypeScript, TSX, and LaTeX. LaTeX imports include package, class, source, and bibliography directives. Export collection supports JavaScript, TypeScript, and TSX only. Call-site collection supports every listed family except HTML, SQL, and LaTeX. LaTeX does not support export collection, callee queries, or call-site collection. The LaTeX grammar does not parse `.bib` files.
+
+The Go and Ruby grammars do not parse Go module manifests or ERB templates. `supi-lsp` still handles them semantically. For a bulk scan, use `getStructuralSearchSupportedExtensions(operation)`. Parser support does not mean that each operation is supported.
 
 ## Architecture
 
@@ -102,15 +107,19 @@ The benchmark reports cold and repeated outline results. It also reports cold an
 
 The Structural Worker reads files asynchronously. It identifies fresh parsed files by canonical path, grammar, and SHA-256 content hash. Cached trees use true least-recently-used eviction with limits of 128 files and 32 MiB of retained UTF-8 source bytes. Compiled queries use the same policy with limits of 128 queries and 512 KiB of retained UTF-8 query text. Source and query byte counts are memory-related proxies because `web-tree-sitter` does not report WASM resource sizes. Cached canonical trees stay private in the Worker.
 
-All structural service operations accept optional `CodeRequestControl`. The parent converts cancellation to one shared atomic flag and forwards absolute deadlines. When present, it forwards only the opaque Debug Operation ID through the Worker protocol so parse and query timing events keep direct request ownership. Direct library calls have no ID. Worker read phases observe a local abort signal. Parser and query progress callbacks observe the flag and deadline. If cooperative interruption does not settle in the fixed 250 ms grace period, the parent terminates the Worker. Valid queued work keeps FIFO order on one fresh Worker with cold caches. There is no main-thread parser fallback.
+The Structural Worker runs in a dedicated Node child process. The process uses `--liftoff-only` so V8 avoids the optimizing WebAssembly compiler that uses unsafe amounts of memory for large grammars. This applies to every grammar in the Worker. Pi's main process does not receive this flag, and a V8 failure in the Worker process cannot crash Pi.
+
+All structural service operations accept optional `CodeRequestControl`. The parent converts cancellation to one shared atomic flag and forwards absolute deadlines. When present, it forwards only the opaque Debug Operation ID through the Worker protocol so parse and query timing events keep direct request ownership. Direct library calls have no ID. The process host creates a shared atomic flag for its Worker thread because Node IPC cannot share the parent flag. Worker read phases observe a local abort signal. Parser and query progress callbacks observe the flag and deadline. If cooperative interruption does not settle in the fixed 250 ms grace period, the parent terminates the Worker process. Valid queued work keeps FIFO order on one fresh Worker with cold caches. There is no main-thread parser fallback.
 
 ## Source
 
 - `src/api.ts` — public library entrypoint
+- `src/worker/process-host.mjs` — process bridge and Worker-local cancellation flags
 - `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
 - `src/session/structural-worker-client.ts` — bounded FIFO mailbox, protocol, cancellation, and restart ownership
+- `src/session/structural-worker-process.ts` — isolated Node process and IPC bridge
 - `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

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

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

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

@@ -94,6 +94,10 @@ export type ConfidenceMode = "semantic" | "structural" | "heuristic" | "unavaila
 export interface OutlineData {
   name: string;
   kind: string;
+  /** Exact 1-based start of the declaration name token, when known. */
+  nameAnchor?: SymbolAnchor;
+  /** Exclusive 1-based end of a verified literal name span, when known. */
+  nameEndAnchor?: SymbolAnchor;
   startLine: number;
   startCharacter: number;
   endLine: number;
@@ -216,7 +220,12 @@ export type RefactorResult =
       authorizedMutationRoots: string[];
     }
   | { kind: "ambiguous"; candidates: DisambiguationCandidate[] }
-  | { kind: "unavailable"; reason: string };
+  | {
+      kind: "unavailable";
+      reason: string;
+      /** Roots authorized by the routed LSP client, when a route returned no edit. */
+      authorizedMutationRoots?: string[];
+    };
 
 // ── Structural data shapes (value types, range-flattened) ──────────────
 

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

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

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

@@ -6,6 +6,9 @@
 
 export type DebugLevel = "debug" | "info" | "warning" | "error";
 export type DebugAgentAccess = "off" | "sanitized" | "raw";
+
+/** Custom session-entry type used to persist sanitized debug events. */
+export const DEBUG_EVENT_ENTRY_TYPE = "supi-debug-event";
 export interface DebugRegistryConfig {
   /** Whether producers should retain debug events. */
   enabled: boolean;
@@ -212,7 +215,7 @@ function toSanitizedView(event: DebugEvent): DebugEventView {
     category: event.category,
     message: event.message,
     cwd: event.cwd,
-    data: event.data,
+    data: event.data === undefined ? undefined : redactDebugData(event.data),
   };
 }
 
@@ -241,15 +244,17 @@ export function recordDebugEvent(input: DebugEventInput): DebugEvent | null {
   };
   state.events.push(event);
   trimToMaxEvents(state);
-  const view = toSanitizedView(event);
   for (const listener of state.listeners) {
     try {
-      listener(view);
+      listener(toSanitizedView(event));
     } catch {
       // Debug-event consumers must not alter producer behavior.
     }
   }
-  return { ...event };
+  return {
+    ...event,
+    data: event.data === undefined ? undefined : redactDebugData(event.data),
+  };
 }
 
 /** Query retained debug events newest-first. Results are sanitized unless raw access is requested and allowed. */

package/node_modules/@mrclrchtr/supi-core/src/session-capabilities.ts

@@ -1,3 +1,9 @@
+import {
+  decodeSessionCapabilityProfileSnapshot,
+  type SessionCapabilityProfile,
+  type SessionCapabilityProfileSnapshot,
+} from "./session-capability-profiles.ts";
+
 /** Session-only tool and skill visibility state. */
 export interface SessionCapabilityState {
   version: 1;
@@ -7,6 +13,8 @@ export interface SessionCapabilityState {
   /** Tools that the user explicitly enabled for this session. */
   toolEnabledNames?: string[];
   hiddenSkillNames: string[];
+  /** Original profile identity and exclusions. Later configuration changes do not affect this copy. */
+  profileSnapshot?: SessionCapabilityProfileSnapshot;
 }
 
 /** A model-visible skill that a provider can offer to the selector. */
@@ -94,8 +102,9 @@ export function decodeSessionCapabilities(value: unknown): SessionCapabilityStat
     (name) => !initiallyInactive.has(name),
   );
   const eligible = new Set(eligibleToolNames);
-  const toolDenylist = stringList(record.toolDenylist).filter((name) => eligible.has(name));
+  const toolDenylist = stringList(record.toolDenylist);
   const denied = new Set(toolDenylist);
+  const profileSnapshot = decodeSessionCapabilityProfileSnapshot(record.profileSnapshot);
 
   return {
     version: 1,
@@ -106,9 +115,54 @@ export function decodeSessionCapabilities(value: unknown): SessionCapabilityStat
       (name) => eligible.has(name) && !denied.has(name),
     ),
     hiddenSkillNames: stringList(record.hiddenSkillNames),
+    ...(profileSnapshot ? { profileSnapshot } : {}),
+  };
+}
+
+/** Copy current exclusion sets for saving. Do not use inventory to remove names. */
+export function captureSessionCapabilityExclusions(
+  state: SessionCapabilityState,
+): SessionCapabilityProfile {
+  return {
+    excludedTools: [...new Set(state.toolDenylist)],
+    hiddenSkills: [...new Set(state.hiddenSkillNames)],
   };
 }
 
+/**
+ * Replace exclusions and capture a profile copy. Return undefined for an invalid profile.
+ * Do not mutate the input state or activate tools. The caller owns runtime restoration.
+ */
+export function applySessionCapabilityProfile(
+  state: SessionCapabilityState,
+  profile: unknown,
+): SessionCapabilityState | undefined {
+  const profileSnapshot = decodeSessionCapabilityProfileSnapshot(profile);
+  if (!profileSnapshot) return undefined;
+  return decodeSessionCapabilities({
+    ...state,
+    toolDenylist: profileSnapshot.excludedTools,
+    hiddenSkillNames: profileSnapshot.hiddenSkills,
+    profileSnapshot,
+  });
+}
+
+function equalNameSets(left: readonly string[], right: readonly string[]): boolean {
+  const leftSet = new Set(left);
+  const rightSet = new Set(right);
+  return leftSet.size === rightSet.size && [...leftSet].every((name) => rightSet.has(name));
+}
+
+/** Compare current exclusions with the applied copy. No profile means no Modified marker. */
+export function isSessionCapabilityProfileModified(state: SessionCapabilityState): boolean {
+  const snapshot = state.profileSnapshot;
+  return (
+    snapshot !== undefined &&
+    (!equalNameSets(state.toolDenylist, snapshot.excludedTools) ||
+      !equalNameSets(state.hiddenSkillNames, snapshot.hiddenSkills))
+  );
+}
+
 /** Return a safe copy of the latest valid snapshot in all session entries. */
 export function findSessionCapabilities(
   entries: readonly unknown[],

package/node_modules/@mrclrchtr/supi-core/src/session-capability-profiles.ts

@@ -0,0 +1,240 @@
+/** Exact names to exclude. Omitted configuration lists mean empty sets. */
+export interface SessionCapabilityProfileDefinition {
+  excludedTools?: string[];
+  hiddenSkills?: string[];
+}
+
+/** Validated exclusion sets. Names need not match the current inventory. */
+export interface SessionCapabilityProfile {
+  excludedTools: string[];
+  hiddenSkills: string[];
+}
+
+/** A profile is available only when validation has no errors. */
+export interface SessionCapabilityProfileValidation {
+  profile?: SessionCapabilityProfile;
+  errors: string[];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function readNames(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const names: unknown[] = [...new Set(value)];
+  return names.every((name): name is string => typeof name === "string") ? names : undefined;
+}
+
+/** Validate and copy a complete definition. Do not check inventory or expand patterns. */
+export function validateSessionCapabilityProfile(
+  value: unknown,
+): SessionCapabilityProfileValidation {
+  if (!isRecord(value)) return { errors: ["Profile must be an object."] };
+  const excludedTools = Object.hasOwn(value, "excludedTools") ? readNames(value.excludedTools) : [];
+  const hiddenSkills = Object.hasOwn(value, "hiddenSkills") ? readNames(value.hiddenSkills) : [];
+  const errors = Object.keys(value)
+    .filter((key) => key !== "excludedTools" && key !== "hiddenSkills")
+    .map((key) => `Unknown profile field: ${key}.`);
+  if (!excludedTools) errors.push("excludedTools must be an array of strings.");
+  if (!hiddenSkills) errors.push("hiddenSkills must be an array of strings.");
+  if (errors.length || !excludedTools || !hiddenSkills) return { errors };
+  return { profile: { excludedTools, hiddenSkills }, errors };
+}
+
+/** Configuration scope that supplied a profile or default. */
+export type SessionCapabilityProfileScope = "global" | "project";
+
+/** Configuration values for the sessionCapabilities section. */
+export interface SessionCapabilityProfilesSection {
+  profiles?: Record<string, SessionCapabilityProfileDefinition>;
+  defaultProfile?: string | null;
+}
+
+/** Session-owned identity and original exclusion sets, independent of configuration. */
+export interface SessionCapabilityProfileSnapshot extends SessionCapabilityProfile {
+  id: string;
+  source: SessionCapabilityProfileScope;
+}
+
+/** A configuration error with a scope and field path for display. */
+export interface SessionCapabilityProfileDiagnostic {
+  scope: SessionCapabilityProfileScope;
+  path: string;
+  message: string;
+}
+
+/** A scoped definition, including invalid definitions and hidden global definitions. */
+export interface SessionCapabilityProfileEntry {
+  id: string;
+  source: SessionCapabilityProfileScope;
+  shadowed: boolean;
+  profile?: SessionCapabilityProfile;
+  errors: SessionCapabilityProfileDiagnostic[];
+}
+
+/** Default selection source can differ from the effective profile source. */
+export type SessionCapabilityProfileDefault =
+  | { status: "none"; source?: SessionCapabilityProfileScope }
+  | {
+      status: "resolved";
+      source: SessionCapabilityProfileScope;
+      id: string;
+      profile: SessionCapabilityProfileSnapshot;
+    }
+  | { status: "invalid"; source: SessionCapabilityProfileScope; id?: string };
+
+/** Raw sections, not merged configuration. Callers must check trust before project reads. */
+export interface ResolveSessionCapabilityProfilesOptions {
+  global?: unknown;
+  project?: unknown;
+  projectTrusted: boolean;
+}
+
+/** Data for profile rows, scoped actions, and default warnings. No I/O is performed. */
+export interface SessionCapabilityProfilesResolution {
+  entries: SessionCapabilityProfileEntry[];
+  effectiveProfiles: SessionCapabilityProfileSnapshot[];
+  default: SessionCapabilityProfileDefault;
+  errors: SessionCapabilityProfileDiagnostic[];
+}
+
+/** IDs contain lowercase ASCII words separated by single hyphens. */
+export function isSessionCapabilityProfileId(value: unknown): value is string {
+  return typeof value === "string" && /^[a-z]+(?:-[a-z]+)*$/.test(value);
+}
+
+/** Validate and copy stored identity and original lists. Invalid metadata has no identity. */
+export function decodeSessionCapabilityProfileSnapshot(
+  value: unknown,
+): SessionCapabilityProfileSnapshot | undefined {
+  if (!isRecord(value) || !isSessionCapabilityProfileId(value.id)) return undefined;
+  if (value.source !== "global" && value.source !== "project") return undefined;
+  const { id, source, ...definition } = value;
+  if (!Object.hasOwn(definition, "excludedTools") || !Object.hasOwn(definition, "hiddenSkills"))
+    return undefined;
+  const result = validateSessionCapabilityProfile(definition);
+  return result.profile ? { id, source, ...result.profile } : undefined;
+}
+
+function readEntries(
+  value: unknown,
+  source: SessionCapabilityProfileScope,
+): SessionCapabilityProfileEntry[] {
+  if (!isRecord(value) || !isRecord(value.profiles)) return [];
+  return Object.entries(value.profiles).map(([id, definition]) => {
+    const result = validateSessionCapabilityProfile(definition);
+    if (!isSessionCapabilityProfileId(id))
+      result.errors.push("Invalid profile ID: use lowercase words with single hyphens.");
+    return {
+      id,
+      source,
+      shadowed: false,
+      profile: result.errors.length ? undefined : result.profile,
+      errors: result.errors.map((message) => ({ scope: source, path: `profiles.${id}`, message })),
+    };
+  });
+}
+
+type DefaultReference =
+  | SessionCapabilityProfileDefault
+  | { status: "pending"; source: SessionCapabilityProfileScope; id: string };
+
+function readDefault(
+  value: unknown,
+  source: SessionCapabilityProfileScope,
+  errors: SessionCapabilityProfileDiagnostic[],
+): DefaultReference | undefined {
+  if (!isRecord(value) || !Object.hasOwn(value, "defaultProfile")) return undefined;
+  if (value.defaultProfile === null) return { status: "none", source };
+  if (isSessionCapabilityProfileId(value.defaultProfile)) {
+    return { status: "pending", source, id: value.defaultProfile };
+  }
+  errors.push({
+    scope: source,
+    path: "defaultProfile",
+    message: "defaultProfile must be null or a valid profile ID.",
+  });
+  return { status: "invalid", source };
+}
+
+function resolveDefault(
+  selected: DefaultReference | undefined,
+  profiles: SessionCapabilityProfileSnapshot[],
+  errors: SessionCapabilityProfileDiagnostic[],
+): SessionCapabilityProfileDefault {
+  if (!selected) return { status: "none" };
+  if (selected.status !== "pending") return selected;
+  const { source, id } = selected;
+  const profile = profiles.find((entry) => entry.id === id);
+  if (profile) return { status: "resolved", source, id, profile };
+  errors.push({
+    scope: source,
+    path: "defaultProfile",
+    message: `Default profile ${id} is missing or invalid. No profile will be applied.`,
+  });
+  return { status: "invalid", source, id };
+}
+
+interface ScopedProfiles {
+  entries: SessionCapabilityProfileEntry[];
+  errors: SessionCapabilityProfileDiagnostic[];
+  default?: DefaultReference;
+}
+
+/** Reject malformed sections, but retain known IDs to prevent global fallback. */
+function readSection(value: unknown, scope: SessionCapabilityProfileScope): ScopedProfiles {
+  if (value === undefined) return { entries: [], errors: [] };
+  if (!isRecord(value)) {
+    return {
+      entries: [],
+      default: { status: "invalid", source: scope },
+      errors: [
+        { scope, path: "sessionCapabilities", message: "sessionCapabilities must be an object." },
+      ],
+    };
+  }
+  const sectionErrors = Object.keys(value)
+    .filter((key) => key !== "profiles" && key !== "defaultProfile")
+    .map((key) => ({ scope, path: key, message: `Unknown section field: ${key}.` }));
+  if (Object.hasOwn(value, "profiles") && !isRecord(value.profiles)) {
+    sectionErrors.push({ scope, path: "profiles", message: "profiles must be an object." });
+  }
+  const entries = readEntries(value, scope);
+  const errors = [...sectionErrors, ...entries.flatMap((entry) => entry.errors)];
+  const selection = readDefault(value, scope, errors);
+  if (sectionErrors.length) {
+    for (const entry of entries) {
+      entry.profile = undefined;
+      entry.errors.push(...sectionErrors);
+    }
+    return { entries, errors, default: { status: "invalid", source: scope } };
+  }
+  return { entries, errors, default: selection };
+}
+
+/**
+ * Resolve whole profiles by ID. Ignore project data unless projectTrusted is true.
+ * An absent section is undefined. Malformed sections cannot supply profiles or a default.
+ */
+export function resolveSessionCapabilityProfiles(
+  options: ResolveSessionCapabilityProfilesOptions,
+): SessionCapabilityProfilesResolution {
+  const global = readSection(options.global, "global");
+  const project = readSection(options.projectTrusted ? options.project : undefined, "project");
+  const entries = [...global.entries, ...project.entries];
+  const errors = [...global.errors, ...project.errors];
+  const selected = new Map(entries.map((entry) => [entry.id, entry]));
+  for (const entry of entries) entry.shadowed = selected.get(entry.id) !== entry;
+  const effectiveProfiles = [...selected.values()].flatMap((entry) =>
+    entry.profile ? [{ id: entry.id, source: entry.source, ...entry.profile }] : [],
+  );
+  return {
+    entries,
+    effectiveProfiles,
+    default: resolveDefault(project.default ?? global.default, effectiveProfiles, errors),
+    errors,
+  };
+}

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

@@ -7,17 +7,39 @@ export type {
   SessionCapabilityState,
 } from "./session-capabilities.ts";
 export {
+  applySessionCapabilityProfile,
+  captureSessionCapabilityExclusions,
   clearPendingSessionCapabilityForks,
   createEmptySessionCapabilityState,
   decodeSessionCapabilities,
   findSessionCapabilities,
   getSessionCapabilitySkillProvider,
+  isSessionCapabilityProfileModified,
   readPendingSessionCapabilityFork,
   registerSessionCapabilitySkillProvider,
   SESSION_CAPABILITIES_ENTRY,
   sessionCapabilityState,
   setPendingSessionCapabilityFork,
 } from "./session-capabilities.ts";
+export type {
+  ResolveSessionCapabilityProfilesOptions,
+  SessionCapabilityProfile,
+  SessionCapabilityProfileDefault,
+  SessionCapabilityProfileDefinition,
+  SessionCapabilityProfileDiagnostic,
+  SessionCapabilityProfileEntry,
+  SessionCapabilityProfileScope,
+  SessionCapabilityProfileSnapshot,
+  SessionCapabilityProfilesResolution,
+  SessionCapabilityProfilesSection,
+  SessionCapabilityProfileValidation,
+} from "./session-capability-profiles.ts";
+export {
+  decodeSessionCapabilityProfileSnapshot,
+  isSessionCapabilityProfileId,
+  resolveSessionCapabilityProfiles,
+  validateSessionCapabilityProfile,
+} from "./session-capability-profiles.ts";
 export type { SessionNameTrackerHost } from "./session-utils.ts";
 export {
   createSessionNameTracker,