@mrclrchtr/supi-tree-sitter 10.0.0 → 11.0.0

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

@@ -0,0 +1,190 @@
+import * as path from "node:path";
+import picomatch from "picomatch";
+
+/** Language selected for a C-family source file. */
+export type CFamilyLanguage = "c" | "cpp";
+
+/** One ordered, project-relative language rule for an existing C-family file. */
+export interface CFamilyFileAssociationRule {
+  readonly pattern: string;
+  readonly language: CFamilyLanguage;
+}
+
+/** C-family suffixes that already have Tree-sitter and LSP support. */
+export const C_FAMILY_EXTENSIONS = Object.freeze([
+  ".c",
+  ".h",
+  ".cpp",
+  ".hpp",
+  ".cc",
+  ".cxx",
+  ".hxx",
+  ".c++",
+  ".h++",
+] as const);
+
+export type CFamilyExtension = (typeof C_FAMILY_EXTENSIONS)[number];
+
+const DEFAULT_C_FAMILY_LANGUAGES: Readonly<Record<CFamilyExtension, CFamilyLanguage>> =
+  Object.freeze({
+    ".c": "c",
+    ".h": "c",
+    ".cpp": "cpp",
+    ".hpp": "cpp",
+    ".cc": "cpp",
+    ".cxx": "cpp",
+    ".hxx": "cpp",
+    ".c++": "cpp",
+    ".h++": "cpp",
+  });
+
+/** Immutable C-family language selection for one workspace. */
+export interface CFamilyFileAssociationResolver {
+  /** Absolute root used to make project-relative paths. */
+  readonly workspaceRoot: string;
+  /** Validated ordered rules captured when the workspace host starts. */
+  readonly rules: readonly CFamilyFileAssociationRule[];
+  /** Select the configured language or the existing suffix default. */
+  languageForFile(filePath: string): CFamilyLanguage | undefined;
+}
+
+/** Return the current default language for one supported C-family suffix. */
+export function defaultCFamilyLanguage(extension: string): CFamilyLanguage | undefined {
+  return DEFAULT_C_FAMILY_LANGUAGES[extension.toLowerCase() as CFamilyExtension];
+}
+
+/**
+ * Validate and compile ordered C-family file associations for one workspace.
+ * Patterns are case-sensitive globs over POSIX-style, workspace-relative paths.
+ * Supported patterns use `*`, `?`, `**`, character classes, and brace alternatives.
+ * The first matching rule wins. Rules never expand the eligible suffix set.
+ *
+ * @throws If the rule list, a rule, a language, or a pattern is invalid.
+ */
+export function createCFamilyFileAssociationResolver(
+  workspaceRoot: string,
+  input: unknown = [],
+): CFamilyFileAssociationResolver {
+  const rules = validateRules(input);
+  const matchers = rules.map((rule, index) => ({
+    language: rule.language,
+    matches: compilePattern(rule.pattern, `code-intelligence.fileAssociations[${index}]`),
+  }));
+  const root = path.resolve(workspaceRoot);
+  return Object.freeze({
+    workspaceRoot: root,
+    rules,
+    languageForFile(filePath: string): CFamilyLanguage | undefined {
+      const extension = normalizeExtension(filePath);
+      const fallback = defaultCFamilyLanguage(extension);
+      if (!fallback) return undefined;
+
+      const absolutePath = path.resolve(root, filePath);
+      const relativePath = toPosixPath(path.relative(root, absolutePath));
+      if (
+        relativePath === ".." ||
+        relativePath.startsWith("../") ||
+        path.posix.isAbsolute(relativePath)
+      ) {
+        return fallback;
+      }
+      for (const rule of matchers) {
+        if (rule.matches(relativePath)) return rule.language;
+      }
+      return fallback;
+    },
+  });
+}
+
+function validateRules(input: unknown): readonly CFamilyFileAssociationRule[] {
+  if (!Array.isArray(input)) {
+    throw new Error('Invalid "code-intelligence.fileAssociations": expected an ordered array.');
+  }
+  if (input.length > 64) {
+    throw new Error('Invalid "code-intelligence.fileAssociations": use no more than 64 rules.');
+  }
+  const rules: CFamilyFileAssociationRule[] = [];
+  const seenPatterns = new Set<string>();
+  for (const [index, value] of input.entries()) {
+    const key = `code-intelligence.fileAssociations[${index}]`;
+    if (!isRecord(value) || !hasExactKeys(value, ["pattern", "language"])) {
+      throw new Error(`${key} must contain only "pattern" and "language" fields.`);
+    }
+    if (typeof value.pattern !== "string") {
+      throw new Error(`${key}.pattern must be a string.`);
+    }
+    if (value.language !== "c" && value.language !== "cpp") {
+      throw new Error(`${key}.language must be "c" or "cpp".`);
+    }
+    if (seenPatterns.has(value.pattern)) {
+      throw new Error(`${key}.pattern duplicates an earlier rule.`);
+    }
+    seenPatterns.add(value.pattern);
+    rules.push(Object.freeze({ pattern: value.pattern, language: value.language }));
+  }
+  return Object.freeze(rules);
+}
+
+function compilePattern(pattern: string, key: string): (file: string) => boolean {
+  if (
+    pattern.length === 0 ||
+    pattern.length > 512 ||
+    pattern !== pattern.trim() ||
+    pattern.includes("\\") ||
+    hasControlCharacter(pattern) ||
+    pattern.startsWith("/") ||
+    /^[A-Za-z]:/.test(pattern) ||
+    pattern.startsWith("!")
+  ) {
+    throw new Error(`${key}.pattern must be a safe workspace-relative glob using "/" separators.`);
+  }
+  const segments = pattern.split("/");
+  if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
+    throw new Error(`${key}.pattern contains an unsafe or unsupported path pattern.`);
+  }
+  try {
+    return picomatch(pattern, {
+      nocase: false,
+      windows: false,
+      dot: true,
+      strictBrackets: true,
+      nonegate: true,
+      noextglob: true,
+      maxLength: 512,
+    });
+  } catch (error) {
+    throw new Error(`${key}.pattern is not a valid glob: ${errorMessage(error)}`, { cause: error });
+  }
+}
+
+function hasControlCharacter(value: string): boolean {
+  for (const character of value) {
+    const code = character.charCodeAt(0);
+    if (code < 32 || code === 127) return true;
+  }
+  return false;
+}
+
+function normalizeExtension(filePath: string): string {
+  return path.posix.extname(toPosixPath(filePath)).toLowerCase();
+}
+
+function toPosixPath(value: string): string {
+  return value.replaceAll("\\", "/");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function hasExactKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+  const allowed = new Set(keys);
+  return (
+    keys.every((key) => Object.hasOwn(value, key)) &&
+    Object.keys(value).every((key) => allowed.has(key))
+  );
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

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

@@ -80,6 +80,14 @@ export interface DocumentCodeSymbol extends CodeSymbol {
  */
 export type CodeResult<T> =
   | { kind: "success"; data: T }
+  | {
+      kind: "partial";
+      data: T;
+      file: string;
+      reason: string;
+      /** Syntax error and missing-node ranges in 0-based UTF-16 coordinates. */
+      errorRanges: SourceRange[];
+    }
   | { kind: "unsupported-language"; file: string; message: string }
   | { kind: "file-access-error"; file: string; message: string }
   | { kind: "validation-error"; message: string }
@@ -93,7 +101,10 @@ export type ConfidenceMode = "semantic" | "structural" | "heuristic" | "unavaila
 
 export interface OutlineData {
   name: string;
+  /** Common structural search category. */
   kind: string;
+  /** Source-language declaration kind, separate from common search category. */
+  nativeKind?: 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. */
@@ -156,6 +167,12 @@ export interface FileEdit {
 /** A document-state precondition established when semantic edits are normalized. */
 export type DocumentEditPrecondition =
   | { file: string; kind: "open-document-version"; version: number }
+  | {
+      file: string;
+      kind: "open-document-content";
+      version: number;
+      fingerprint: string;
+    }
   | { file: string; kind: "disk-content" };
 
 /**
@@ -257,5 +274,10 @@ export interface CalleesData {
 /** A single call-site match with name and start line. */
 export interface CallSite {
   name: string;
+  /** 1-based UTF-16 start position of the written callee expression. */
   startLine: number;
+  startCharacter: number;
+  /** Exclusive 1-based UTF-16 end position of the captured source expression. */
+  endLine: number;
+  endCharacter: number;
 }

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-tree-sitter",
-  "version": "10.0.0",
+  "version": "11.0.0",
   "description": "Structural AST analysis for SuPi code intelligence",
   "license": "MIT",
   "repository": {
@@ -36,8 +36,8 @@
   "dependencies": {
     "jiti": "^2.7.0",
     "web-tree-sitter": "^0.27.0",
-    "@mrclrchtr/supi-code-runtime": "10.0.0",
-    "@mrclrchtr/supi-core": "10.0.0"
+    "@mrclrchtr/supi-code-runtime": "11.0.0",
+    "@mrclrchtr/supi-core": "11.0.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-code-runtime",

package/src/language.ts

@@ -7,9 +7,18 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
+import {
+  C_FAMILY_EXTENSIONS,
+  type CFamilyExtension,
+  type CFamilyFileAssociationResolver,
+  defaultCFamilyLanguage,
+} from "@mrclrchtr/supi-code-runtime/api";
 import type { GrammarId, SupportedExtension } from "./types.ts";
 
 const sourceDir = path.dirname(fileURLToPath(import.meta.url));
+const C_FAMILY_GRAMMAR = Object.fromEntries(
+  C_FAMILY_EXTENSIONS.map((extension) => [extension, defaultCFamilyLanguage(extension)]),
+) as Record<CFamilyExtension, GrammarId>;
 
 /** Mapping from file extension to grammar identifier. */
 const EXTENSION_GRAMMAR = {
@@ -25,15 +34,7 @@ const EXTENSION_GRAMMAR = {
   ".pyi": "python",
   ".rs": "rust",
   ".go": "go",
-  ".c": "c",
-  ".h": "c",
-  ".cpp": "cpp",
-  ".hpp": "cpp",
-  ".cc": "cpp",
-  ".cxx": "cpp",
-  ".hxx": "cpp",
-  ".c++": "cpp",
-  ".h++": "cpp",
+  ...C_FAMILY_GRAMMAR,
   ".java": "java",
   ".kt": "kotlin",
   ".kts": "kotlin",
@@ -68,7 +69,12 @@ export function getSupportedExtensionGrammarEntries(): Array<
 }
 
 /** Detect the grammar for a file. Returns undefined if unsupported. */
-export function detectGrammar(filePath: string): GrammarId | undefined {
+export function detectGrammar(
+  filePath: string,
+  associations?: CFamilyFileAssociationResolver,
+): GrammarId | undefined {
+  const familyLanguage = associations?.languageForFile(filePath);
+  if (familyLanguage) return familyLanguage;
   const ext = path.extname(filePath).toLowerCase();
   return EXTENSION_GRAMMAR[ext as SupportedExtension];
 }

package/src/operation-support.ts

@@ -4,6 +4,18 @@ import type { GrammarId, SupportedExtension } from "./types.ts";
 
 /** Structural collection operations whose language support defines an AST Scan universe. */
 const STRUCTURAL_SEARCH_OPERATIONS = ["outline", "imports", "exports", "call-sites"] as const;
+const IMPORT_GRAMMARS: ReadonlySet<GrammarId> = new Set([
+  "javascript",
+  "typescript",
+  "tsx",
+  "python",
+  "java",
+  "go",
+  "rust",
+  "c",
+  "cpp",
+  "latex",
+]);
 
 /** One Tree-sitter structural collection operation used by code-aware search. */
 export type StructuralSearchOperation = (typeof STRUCTURAL_SEARCH_OPERATIONS)[number];
@@ -33,12 +45,7 @@ export function supportsGrammarOperation(
     case "outline":
       return true;
     case "imports":
-      return (
-        grammar === "javascript" ||
-        grammar === "typescript" ||
-        grammar === "tsx" ||
-        grammar === "latex"
-      );
+      return IMPORT_GRAMMARS.has(grammar);
     case "exports":
       return grammar === "javascript" || grammar === "typescript" || grammar === "tsx";
     default:

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

@@ -70,6 +70,17 @@ function mapTreeSitterResult<T, U>(
   switch (result.kind) {
     case "success":
       return { kind: "success", data: mapData(result.data) };
+    case "partial":
+      return {
+        kind: "partial",
+        data: mapData(result.data),
+        file: result.file,
+        reason: result.reason,
+        errorRanges: result.errorRanges.map((range) => ({
+          start: { line: range.startLine - 1, character: range.startCharacter - 1 },
+          end: { line: range.endLine - 1, character: range.endCharacter - 1 },
+        })),
+      };
     case "unsupported-language":
       return { kind: "unsupported-language", file: result.file, message: result.message };
     case "file-access-error":
@@ -103,6 +114,7 @@ function mapOutlineItems(items: OutlineItem[]): OutlineData[] {
   return items.map((item) => ({
     name: item.name,
     kind: item.kind,
+    ...(item.nativeKind === undefined ? {} : { nativeKind: item.nativeKind }),
     ...(item.nameAnchor ? { nameAnchor: { ...item.nameAnchor } } : {}),
     ...(item.nameEndAnchor ? { nameEndAnchor: { ...item.nameEndAnchor } } : {}),
     ...takeRange(item.range),
@@ -156,5 +168,11 @@ function mapCalleesAtResult(result: CalleesAtResult): CalleesData {
 }
 
 function mapCallSites(matches: CallSiteMatch[]): CallSite[] {
-  return matches.map((m) => ({ name: m.name, startLine: m.startLine }));
+  return matches.map((match) => ({
+    name: match.name,
+    startLine: match.startLine,
+    startCharacter: match.startCharacter,
+    endLine: match.endLine,
+    endCharacter: match.endCharacter,
+  }));
 }

package/src/session/runtime-controller.ts

@@ -1,7 +1,10 @@
 // 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 {
+  CFamilyFileAssociationResolver,
+  WorkspaceRuntime,
+} from "@mrclrchtr/supi-code-runtime/api";
 import { createTreeSitterProvider } from "../provider/tree-sitter-provider.ts";
 import type { TreeSitterService, TreeSitterSession } from "../types.ts";
 import { createTreeSitterSession } from "./session.ts";
@@ -32,13 +35,20 @@ export class TreeSitterRuntimeController {
   readonly #cwd: string;
   #state: TsControllerState = { kind: "initial" };
   readonly #runtime: WorkspaceRuntime;
+  readonly #fileAssociations?: CFamilyFileAssociationResolver;
   #pendingSession: TreeSitterSession | null = null;
   #generation = 0;
   #transition = Promise.resolve();
 
-  constructor(cwd: string, runtime: WorkspaceRuntime) {
+  /** Create a controller with an optional workspace association snapshot. */
+  constructor(
+    cwd: string,
+    runtime: WorkspaceRuntime,
+    fileAssociations?: CFamilyFileAssociationResolver,
+  ) {
     this.#cwd = cwd;
     this.#runtime = runtime;
+    this.#fileAssociations = fileAssociations;
   }
 
   get cwd(): string {
@@ -79,11 +89,15 @@ export class TreeSitterRuntimeController {
     if (generation !== this.#generation) return supersededStart();
     this.#state = { kind: "unavailable", reason: "Initializing Tree-sitter" };
 
-    const session = createTreeSitterSession(this.#cwd);
+    const session = createTreeSitterSession(this.#cwd, {
+      fileAssociations: this.#fileAssociations?.rules,
+    });
     this.#pendingSession = session;
     try {
       const probe = await session.canParse(fileURLToPath(import.meta.url));
-      if (probe.kind !== "success") throw new Error(probe.message);
+      if (probe.kind !== "success") {
+        throw new Error(probe.kind === "partial" ? probe.reason : probe.message);
+      }
       if (generation !== this.#generation || this.#pendingSession !== session) {
         return supersededStart();
       }

package/src/session/session.ts

@@ -1,6 +1,9 @@
 // Session factory — creates asynchronous Structural Worker proxies and owned sessions.
 
-import type { CodeRequestControl } from "@mrclrchtr/supi-code-runtime/api";
+import type {
+  CFamilyFileAssociationRule,
+  CodeRequestControl,
+} from "@mrclrchtr/supi-code-runtime/api";
 import type {
   CalleesAtResult,
   CallSiteMatch,
@@ -62,13 +65,17 @@ export function createTreeSitterService(client: StructuralWorkerClient): TreeSit
 
 /**
  * Create one Tree-sitter session bound to a working directory.
+ * Pass trusted workspace associations when the caller owns config loading.
  * Await disposal to prove that its Structural Worker has terminated.
  */
 export function createTreeSitterSession(
   cwd: string,
-  options: { readonly workerFactory?: StructuralWorkerFactory } = {},
+  options: {
+    readonly workerFactory?: StructuralWorkerFactory;
+    readonly fileAssociations?: readonly CFamilyFileAssociationRule[];
+  } = {},
 ): TreeSitterSession {
-  const client = new StructuralWorkerClient(cwd, options.workerFactory);
+  const client = new StructuralWorkerClient(cwd, options.workerFactory, options.fileAssociations);
   const service = createTreeSitterService(client);
   return {
     ...service,

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

@@ -1,6 +1,7 @@
 // biome-ignore-all lint/style/noExcessiveLinesPerFile: one mailbox state machine owns all Worker lifecycle transitions
 import { setImmediate as yieldImmediate } from "node:timers/promises";
 import {
+  type CFamilyFileAssociationRule,
   type CodeRequestControl,
   CodeRequestDeadlineError,
   throwIfCodeRequestInterrupted,
@@ -28,6 +29,7 @@ import {
 export type StructuralWorkerFactory = (options: {
   readonly cwd: string;
   readonly generation: number;
+  readonly fileAssociations: readonly CFamilyFileAssociationRule[];
 }) => StructuralWorkerLike;
 
 const TEST_WORKER_FACTORY = Symbol.for("supi-tree-sitter/test-worker-factory");
@@ -74,6 +76,7 @@ interface ActiveWorker {
 export class StructuralWorkerClient {
   readonly #cwd: string;
   readonly #factory: StructuralWorkerFactory;
+  readonly #fileAssociations: readonly CFamilyFileAssociationRule[];
   #worker: ActiveWorker | null = null;
   #queue: PendingRequest<unknown>[] = [];
   #active: PendingRequest<unknown> | null = null;
@@ -86,9 +89,16 @@ export class StructuralWorkerClient {
   readonly #lifecycle = new StructuralWorkerLifecycle();
   #disposePromise: Promise<void> | null = null;
 
-  constructor(cwd: string, factory?: StructuralWorkerFactory) {
+  constructor(
+    cwd: string,
+    factory?: StructuralWorkerFactory,
+    fileAssociations: readonly CFamilyFileAssociationRule[] = [],
+  ) {
     this.#cwd = cwd;
     this.#factory = factory ?? testWorkerFactory() ?? createProductionWorker;
+    this.#fileAssociations = Object.freeze(
+      fileAssociations.map((rule) => Object.freeze({ ...rule })),
+    );
   }
 
   /** Start and validate the owned Worker without running parser work on the parent. */
@@ -187,7 +197,11 @@ export class StructuralWorkerClient {
 
   async #startGeneration(): Promise<void> {
     const generation = ++this.#generation;
-    const worker = this.#factory({ cwd: this.#cwd, generation });
+    const worker = this.#factory({
+      cwd: this.#cwd,
+      generation,
+      fileAssociations: this.#fileAssociations,
+    });
     let rejectStartup = (_message: string) => {};
     const active: ActiveWorker = {
       generation,
@@ -563,6 +577,7 @@ function testWorkerFactory(): StructuralWorkerFactory | undefined {
 function createProductionWorker(options: {
   cwd: string;
   generation: number;
+  fileAssociations: readonly CFamilyFileAssociationRule[];
 }): StructuralWorkerLike {
   return createStructuralWorkerProcess(options);
 }

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

@@ -1,11 +1,14 @@
 import { type ChildProcess, fork } from "node:child_process";
 import { EventEmitter } from "node:events";
 import { fileURLToPath } from "node:url";
+import type { CFamilyFileAssociationRule } from "@mrclrchtr/supi-code-runtime/api";
 import { decodeStructuralWorkerJsonMessage } from "./structural-worker-json.ts";
 import { resolveStructuralWorkerNode } from "./structural-worker-node.ts";
-import type {
-  ParentToStructuralWorkerMessage,
-  StructuralWorkerToParentMessage,
+import {
+  type ParentToStructuralWorkerMessage,
+  STRUCTURAL_WORKER_PROTOCOL_VERSION,
+  type StructuralWorkerInitializationMessage,
+  type StructuralWorkerToParentMessage,
 } from "./structural-worker-protocol.ts";
 
 const PARENT_CHANNEL = "supi-tree-sitter-parent";
@@ -23,6 +26,7 @@ export interface StructuralWorkerLike {
 export function createStructuralWorkerProcess(options: {
   readonly cwd: string;
   readonly generation: number;
+  readonly fileAssociations: readonly CFamilyFileAssociationRule[];
 }): StructuralWorkerLike {
   const hostPath = fileURLToPath(new URL("../worker/process-host.mjs", import.meta.url));
   const jsonIpc = Boolean(process.versions.bun);
@@ -36,7 +40,13 @@ export function createStructuralWorkerProcess(options: {
     stdio: ["ignore", "ignore", "inherit", "ipc"],
     windowsHide: true,
   });
-  return new StructuralWorkerProcess(child, jsonIpc);
+  return new StructuralWorkerProcess(child, jsonIpc, {
+    kind: "initialize",
+    version: STRUCTURAL_WORKER_PROTOCOL_VERSION,
+    generation: options.generation,
+    cwd: options.cwd,
+    fileAssociations: options.fileAssociations,
+  });
 }
 
 class StructuralWorkerProcess implements StructuralWorkerLike {
@@ -44,12 +54,19 @@ class StructuralWorkerProcess implements StructuralWorkerLike {
   readonly #child: ChildProcess;
   readonly #jsonIpc: boolean;
 
-  constructor(child: ChildProcess, jsonIpc: boolean) {
+  constructor(
+    child: ChildProcess,
+    jsonIpc: boolean,
+    initialization: StructuralWorkerInitializationMessage,
+  ) {
     this.#child = child;
     this.#jsonIpc = jsonIpc;
     child.on("message", (value: unknown) => this.#receive(value));
     child.on("error", (error) => this.#events.emit("error", error));
     child.on("exit", (code) => this.#events.emit("exit", code ?? 1));
+    child.send({ channel: PARENT_CHANNEL, message: initialization }, (error) => {
+      if (error) this.#events.emit("error", error);
+    });
   }
 
   postMessage(message: ParentToStructuralWorkerMessage): void {

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

@@ -1,4 +1,6 @@
 // biome-ignore-all lint/style/noExcessiveLinesPerFile: one private protocol module defines and validates the full closed contract
+
+import type { CFamilyFileAssociationRule } from "@mrclrchtr/supi-code-runtime/api";
 import { isDebugOperationId } from "@mrclrchtr/supi-core/debug";
 import type { TreeSitterResult } from "../types.ts";
 import type { StructuralTimingEvent } from "./structural-timing.ts";
@@ -37,6 +39,14 @@ export type StructuralWorkerOperation =
       readonly depth?: "direct" | "deep";
     };
 
+export interface StructuralWorkerInitializationMessage {
+  readonly kind: "initialize";
+  readonly version: typeof STRUCTURAL_WORKER_PROTOCOL_VERSION;
+  readonly generation: number;
+  readonly cwd: string;
+  readonly fileAssociations: readonly CFamilyFileAssociationRule[];
+}
+
 export interface StructuralWorkerRequestMessage {
   readonly kind: "request";
   readonly version: typeof STRUCTURAL_WORKER_PROTOCOL_VERSION;
@@ -427,7 +437,18 @@ function isStructuralTimingEvent(value: unknown): value is StructuralTimingEvent
 function assertTreeSitterResult(value: unknown): asserts value is TreeSitterResult<unknown> {
   if (!isRecord(value) || typeof value.kind !== "string")
     throw new Error("Invalid structural result");
-  if (value.kind === "success" && "data" in value) return;
+  if (value.kind === "success" && hasExactKeys(value, ["kind", "data"])) return;
+  if (
+    value.kind === "partial" &&
+    hasExactKeys(value, ["kind", "data", "file", "reason", "errorRanges"]) &&
+    isFileValue(value.file) &&
+    isBoundedString(value.reason, 2_048) &&
+    Array.isArray(value.errorRanges) &&
+    value.errorRanges.length <= 10_000 &&
+    value.errorRanges.every(isTreeSitterSourceRange)
+  ) {
+    return;
+  }
   if (
     value.kind === "unsupported-language" ||
     value.kind === "file-access-error" ||
@@ -527,6 +548,20 @@ function estimateChunkMessageBytes(payloadBytes: number): number {
   return payloadBytes + 1024;
 }
 
+function isTreeSitterSourceRange(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    hasExactKeys(value, ["startLine", "startCharacter", "endLine", "endCharacter"]) &&
+    isPositiveInteger(value.startLine) &&
+    isPositiveInteger(value.startCharacter) &&
+    isPositiveInteger(value.endLine) &&
+    isPositiveInteger(value.endCharacter) &&
+    (Number(value.startLine) < Number(value.endLine) ||
+      (value.startLine === value.endLine &&
+        Number(value.startCharacter) <= Number(value.endCharacter)))
+  );
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }