@mrclrchtr/supi-code-intelligence 0.1.0

package/node_modules/@mrclrchtr/supi-lsp/src/ui.ts

@@ -0,0 +1,358 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { DynamicBorder } from "@earendil-works/pi-coding-agent";
+import type { OverlayHandle } from "@earendil-works/pi-tui";
+import { Container, Spacer, Text } from "@earendil-works/pi-tui";
+import type { LspManager } from "./manager/manager.ts";
+import type { OutstandingDiagnosticSummaryEntry } from "./manager/manager-types.ts";
+import type { Diagnostic, ProjectServerInfo } from "./types.ts";
+import { DiagnosticSeverity } from "./types.ts";
+
+export interface LspInspectorState {
+  handle: OverlayHandle | null;
+  close: (() => void) | null;
+}
+
+export function updateLspUi(
+  ctx: ExtensionContext,
+  manager: LspManager,
+  inlineSeverity: number,
+  servers: ProjectServerInfo[],
+): void {
+  const diagnostics = manager.getOutstandingDiagnosticSummary(inlineSeverity);
+
+  ctx.ui.setStatus("lsp", buildLspStatus(ctx, servers, diagnostics));
+  ctx.ui.setWidget(
+    "lsp",
+    hasWidgetContent(diagnostics)
+      ? (_tui, theme) => buildLspWidgetComponent(theme, diagnostics)
+      : undefined,
+    { placement: "belowEditor" },
+  );
+}
+
+// biome-ignore lint/complexity/useMaxParams: overlay inputs travel together
+export function toggleLspStatusOverlay(
+  ctx: ExtensionContext,
+  manager: LspManager,
+  inlineSeverity: number,
+  inspector: LspInspectorState,
+  servers: ProjectServerInfo[],
+): void {
+  if (inspector.handle && inspector.close) {
+    inspector.close();
+    return;
+  }
+
+  void ctx.ui
+    .custom<void>(
+      (_tui, theme, _kb, done) => {
+        inspector.close = () => done(undefined);
+        return createLspInspectorComponent(theme, manager, inlineSeverity, servers);
+      },
+      {
+        overlay: true,
+        overlayOptions: {
+          anchor: "right-center",
+          width: "60%",
+          minWidth: 72,
+          maxHeight: "90%",
+          margin: { right: 1, top: 1, bottom: 1 },
+          nonCapturing: true,
+        },
+        onHandle: (handle) => {
+          inspector.handle = handle;
+        },
+      },
+    )
+    .finally(() => {
+      inspector.handle = null;
+      inspector.close = null;
+    });
+}
+
+function createLspInspectorComponent(
+  theme: ExtensionContext["ui"]["theme"],
+  manager: LspManager,
+  inlineSeverity: number,
+  servers: ProjectServerInfo[],
+): { render: (width: number) => string[]; invalidate: () => void } {
+  return {
+    render: (width) =>
+      buildLspInspectorContainer({
+        theme,
+        manager,
+        inlineSeverity,
+        servers,
+        width,
+      }).render(width),
+    invalidate: () => {},
+  };
+}
+
+interface LspInspectorContainerInput {
+  theme: ExtensionContext["ui"]["theme"];
+  manager: LspManager;
+  inlineSeverity: number;
+  servers: ProjectServerInfo[];
+  width: number;
+}
+
+function buildLspInspectorContainer(input: LspInspectorContainerInput): Container {
+  const diagnostics = input.manager.getOutstandingDiagnosticSummary(input.inlineSeverity);
+  const detailedDiagnostics = input.manager.getOutstandingDiagnostics(input.inlineSeverity);
+  const container = new Container();
+
+  const { theme, servers, width } = input;
+
+  container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+  container.addChild(
+    new Text(
+      theme.fg("accent", theme.bold(" λ LSP")) + theme.fg("dim", " inspector  /lsp-status toggles"),
+      1,
+      0,
+    ),
+  );
+
+  if (servers.length === 0 && diagnostics.length === 0) {
+    container.addChild(
+      new Text(theme.fg("dim", "no LSP servers available for this project"), 1, 0),
+    );
+    container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+    return container;
+  }
+
+  container.addChild(new Text(buildOverlaySummaryLine(theme, servers, diagnostics), 1, 0));
+  container.addChild(new Spacer(1));
+  container.addChild(
+    buildOverlaySection(theme, "Servers", buildOverlayServerLines(theme, servers)),
+  );
+  container.addChild(new Spacer(1));
+  container.addChild(
+    buildOverlaySection(
+      theme,
+      diagnostics.length > 0 ? "Problems" : "Diagnostics",
+      buildOverlayDiagnosticLines(theme, diagnostics, detailedDiagnostics, width),
+    ),
+  );
+  container.addChild(new Spacer(1));
+  container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+
+  return container;
+}
+
+function buildLspStatus(
+  ctx: ExtensionContext,
+  servers: ProjectServerInfo[],
+  diagnostics: OutstandingDiagnosticSummaryEntry[],
+): string | undefined {
+  const runningServers = servers.filter((server) => server.status === "running").length;
+  const openFiles = servers.reduce((sum, server) => sum + server.openFiles.length, 0);
+  const totals = collectDiagnosticTotals(diagnostics);
+
+  if (runningServers === 0 && openFiles === 0 && diagnostics.length === 0) {
+    return undefined;
+  }
+
+  const { theme } = ctx.ui;
+  const parts = [theme.fg("accent", "λ lsp")];
+  if (runningServers > 0) parts.push(theme.fg("dim", pluralize(runningServers, "server")));
+  if (openFiles > 0) parts.push(theme.fg("dim", pluralize(openFiles, "open file")));
+  if (totals.errors > 0) parts.push(theme.fg("error", pluralize(totals.errors, "error")));
+  if (totals.warnings > 0) parts.push(theme.fg("warning", pluralize(totals.warnings, "warning")));
+  if (totals.information > 0) parts.push(theme.fg("accent", pluralize(totals.information, "info")));
+  if (totals.hints > 0) parts.push(theme.fg("dim", pluralize(totals.hints, "hint")));
+  return parts.join(theme.fg("dim", " • "));
+}
+
+function hasWidgetContent(diagnostics: OutstandingDiagnosticSummaryEntry[]): boolean {
+  return diagnostics.length > 0;
+}
+
+function buildLspWidgetComponent(
+  theme: ExtensionContext["ui"]["theme"],
+  diagnostics: OutstandingDiagnosticSummaryEntry[],
+): Container {
+  const container = new Container();
+
+  for (const line of buildWidgetDiagnosticLines(theme, diagnostics)) {
+    container.addChild(new Text(line, 0, 0));
+  }
+
+  return container;
+}
+
+function buildWidgetDiagnosticLines(
+  theme: ExtensionContext["ui"]["theme"],
+  diagnostics: OutstandingDiagnosticSummaryEntry[],
+): string[] {
+  if (diagnostics.length === 1) {
+    const [entry] = diagnostics;
+    if (!entry) return [];
+    return [
+      `${theme.fg("error", "●")} ${entry.file} ${theme.fg("dim", `— ${formatDiagnosticCounts(entry)}`)}`,
+    ];
+  }
+
+  const totals = collectDiagnosticTotals(diagnostics);
+  const counts: string[] = [];
+  if (totals.errors > 0) counts.push(theme.fg("error", pluralize(totals.errors, "error")));
+  if (totals.warnings > 0) counts.push(theme.fg("warning", pluralize(totals.warnings, "warning")));
+  if (totals.information > 0)
+    counts.push(theme.fg("accent", pluralize(totals.information, "info")));
+  if (totals.hints > 0) counts.push(theme.fg("dim", pluralize(totals.hints, "hint")));
+
+  const visibleFiles = diagnostics.slice(0, 2).map((entry) => entry.file);
+  const remaining = diagnostics.length - visibleFiles.length;
+  const suffix = remaining > 0 ? `${theme.fg("dim", ` +${remaining} more`)}` : "";
+
+  return [
+    `${theme.fg("accent", theme.bold("λ LSP diagnostics"))} ${theme.fg("dim", `— ${pluralize(diagnostics.length, "file")}`)} ${counts.join(theme.fg("dim", " • "))}`,
+    `${theme.fg("error", "↳")} ${visibleFiles.join(", ")}${suffix}`,
+  ];
+}
+
+function buildOverlaySummaryLine(
+  theme: ExtensionContext["ui"]["theme"],
+  servers: ProjectServerInfo[],
+  diagnostics: OutstandingDiagnosticSummaryEntry[],
+): string {
+  const runningServers = servers.filter((server) => server.status === "running").length;
+  const openFiles = servers.reduce((sum, server) => sum + server.openFiles.length, 0);
+  const totals = collectDiagnosticTotals(diagnostics);
+
+  const parts = [
+    theme.fg(
+      "dim",
+      `${pluralize(runningServers, "server")} • ${pluralize(openFiles, "open file")}`,
+    ),
+  ];
+  if (totals.errors > 0) {
+    parts.push(theme.fg("error", pluralize(totals.errors, "error")));
+  } else if (totals.warnings > 0) {
+    parts.push(theme.fg("warning", pluralize(totals.warnings, "warning")));
+  } else if (totals.information > 0) {
+    parts.push(theme.fg("accent", pluralize(totals.information, "info")));
+  } else if (totals.hints > 0) {
+    parts.push(theme.fg("dim", pluralize(totals.hints, "hint")));
+  } else {
+    parts.push(theme.fg("success", "clean"));
+  }
+
+  return parts.join(theme.fg("dim", "   "));
+}
+
+function buildOverlaySection(
+  theme: ExtensionContext["ui"]["theme"],
+  title: string,
+  lines: string[],
+): Container {
+  const container = new Container();
+  container.addChild(new Text(theme.fg("accent", theme.bold(` ${title}`)), 1, 0));
+  for (const line of lines) {
+    container.addChild(new Text(line, 2, 0));
+  }
+  return container;
+}
+
+function buildOverlayServerLines(
+  theme: ExtensionContext["ui"]["theme"],
+  servers: ProjectServerInfo[],
+): string[] {
+  if (servers.length === 0) {
+    return [theme.fg("dim", "no LSP servers available for this project")];
+  }
+
+  return servers.flatMap((server) => {
+    const statusColor =
+      server.status === "running" ? "success" : server.status === "error" ? "error" : "warning";
+    const actions =
+      server.supportedActions.length > 0 ? server.supportedActions.join(", ") : "none";
+    const fileTypes = server.fileTypes.map((entry) => `.${entry}`).join(", ");
+    const openFiles =
+      server.openFiles.length > 0 ? server.openFiles.slice(0, 3).join(", ") : "none";
+    const remaining = server.openFiles.length - Math.min(server.openFiles.length, 3);
+    const suffix = remaining > 0 ? theme.fg("dim", ` +${remaining} more`) : "";
+
+    return [
+      `${theme.fg("accent", "◆")} ${server.name} ${theme.fg(statusColor, server.status)} ${theme.fg("dim", `— root: ${server.root}`)}`,
+      `${theme.fg("dim", "↳")} files: ${fileTypes}`,
+      `${theme.fg("dim", "↳")} actions: ${actions}`,
+      `${theme.fg("dim", "↳")} open: ${openFiles}${suffix}`,
+    ];
+  });
+}
+
+function buildOverlayDiagnosticLines(
+  theme: ExtensionContext["ui"]["theme"],
+  diagnostics: OutstandingDiagnosticSummaryEntry[],
+  detailedDiagnostics: Array<{ file: string; diagnostics: Diagnostic[] }>,
+  width: number,
+): string[] {
+  if (diagnostics.length === 0) {
+    return [theme.fg("success", "✓ no outstanding diagnostics")];
+  }
+
+  const lines: string[] = [];
+  const maxFiles = 5;
+  const maxMessagesPerFile = 5;
+  // Budget for prefix: 2 spaces + tree char + space + line:col + space + Text paddingX(2)*2
+  const maxMessageLen = Math.max(24, width - 18);
+
+  for (const entry of detailedDiagnostics.slice(0, maxFiles)) {
+    const summary = diagnostics.find((d) => d.file === entry.file);
+    const countLabel = summary ? formatDiagnosticCounts(summary) : "";
+    lines.push(`${theme.fg("error", "●")} ${entry.file} ${theme.fg("dim", `— ${countLabel}`)}`);
+
+    for (const diag of entry.diagnostics.slice(0, maxMessagesPerFile)) {
+      const line = diag.range.start.line + 1;
+      const col = diag.range.start.character + 1;
+      const sevColor = diag.severity === DiagnosticSeverity.Error ? "error" : "warning";
+      const message = truncate(diag.message, maxMessageLen);
+      lines.push(`  ${theme.fg(sevColor, "└")} ${line}:${col} ${theme.fg("dim", message)}`);
+    }
+
+    const remainingMessages = entry.diagnostics.length - maxMessagesPerFile;
+    if (remainingMessages > 0) {
+      lines.push(`  ${theme.fg("dim", `└ +${remainingMessages} more`)}`);
+    }
+  }
+
+  const remainingFiles = diagnostics.length - Math.min(diagnostics.length, maxFiles);
+  if (remainingFiles > 0) {
+    lines.push(theme.fg("dim", `↳ +${remainingFiles} more file${remainingFiles === 1 ? "" : "s"}`));
+  }
+
+  return lines;
+}
+
+function truncate(text: string, maxLength: number): string {
+  if (text.length <= maxLength) return text;
+  return `${text.slice(0, maxLength - 1)}…`;
+}
+
+function formatDiagnosticCounts(entry: OutstandingDiagnosticSummaryEntry): string {
+  const counts: string[] = [];
+  if (entry.errors > 0) counts.push(pluralize(entry.errors, "error"));
+  if (entry.warnings > 0) counts.push(pluralize(entry.warnings, "warning"));
+  if (entry.information > 0) counts.push(pluralize(entry.information, "info"));
+  if (entry.hints > 0) counts.push(pluralize(entry.hints, "hint"));
+  return counts.join(", ");
+}
+
+function collectDiagnosticTotals(
+  diagnostics: OutstandingDiagnosticSummaryEntry[],
+): Pick<OutstandingDiagnosticSummaryEntry, "errors" | "warnings" | "information" | "hints"> {
+  return diagnostics.reduce(
+    (totals, entry) => ({
+      errors: totals.errors + entry.errors,
+      warnings: totals.warnings + entry.warnings,
+      information: totals.information + entry.information,
+      hints: totals.hints + entry.hints,
+    }),
+    { errors: 0, warnings: 0, information: 0, hints: 0 },
+  );
+}
+
+function pluralize(count: number, word: string): string {
+  return `${count} ${word}${count === 1 ? "" : "s"}`;
+}

package/node_modules/@mrclrchtr/supi-lsp/src/utils.ts

@@ -0,0 +1,122 @@
+// URI and language utilities for LSP.
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+// ── URI Handling ──────────────────────────────────────────────────────
+
+/** Convert a file path to a file:// URI. */
+export function fileToUri(filePath: string): string {
+  const resolved = path.resolve(filePath);
+  if (process.platform === "win32") {
+    return `file:///${resolved.replace(/\\/g, "/")}`;
+  }
+  return `file://${resolved}`;
+}
+
+/** Convert a file:// URI to a file path. */
+export function uriToFile(uri: string): string {
+  if (!uri.startsWith("file://")) return uri;
+  let filePath = decodeURIComponent(uri.slice(7));
+  if (
+    process.platform === "win32" &&
+    filePath.startsWith("/") &&
+    /^[A-Za-z]:/.test(filePath.slice(1))
+  ) {
+    filePath = filePath.slice(1);
+  }
+  return filePath;
+}
+
+// ── Language ID Detection ─────────────────────────────────────────────
+
+const EXT_TO_LANGUAGE: Record<string, string> = {
+  ts: "typescript",
+  tsx: "typescriptreact",
+  js: "javascript",
+  jsx: "javascriptreact",
+  mts: "typescript",
+  cts: "typescript",
+  mjs: "javascript",
+  cjs: "javascript",
+  py: "python",
+  pyi: "python",
+  rs: "rust",
+  go: "go",
+  mod: "go",
+  c: "c",
+  h: "c",
+  cpp: "cpp",
+  hpp: "cpp",
+  cc: "cpp",
+  cxx: "cpp",
+  hxx: "cpp",
+  "c++": "cpp",
+  "h++": "cpp",
+  json: "json",
+  yaml: "yaml",
+  yml: "yaml",
+  md: "markdown",
+  html: "html",
+  htm: "html",
+  xhtml: "html",
+  css: "css",
+  scss: "scss",
+  sh: "shellscript",
+  bash: "shellscript",
+  zsh: "shellscript",
+  ksh: "shellscript",
+  toml: "toml",
+  xml: "xml",
+  sql: "sql",
+  r: "r",
+  rb: "ruby",
+  erb: "ruby",
+  gemspec: "ruby",
+  java: "java",
+  kt: "kotlin",
+  kts: "kotlin",
+  swift: "swift",
+  lua: "lua",
+  zig: "zig",
+};
+
+/** Detect the LSP languageId from a file path. */
+export function detectLanguageId(filePath: string): string {
+  const ext = path.extname(filePath).slice(1).toLowerCase();
+  return EXT_TO_LANGUAGE[ext] ?? ext;
+}
+
+/** Get the file extension (without dot) from a file path. */
+export function getFileExtension(filePath: string): string {
+  return path.extname(filePath).slice(1).toLowerCase();
+}
+
+// ── PATH Validation ───────────────────────────────────────────────────
+
+/**
+ * Check if a command exists on PATH.
+ * Uses synchronous check to avoid complexity.
+ */
+export function commandExists(command: string): boolean {
+  // If it's an absolute path, check directly
+  if (path.isAbsolute(command)) {
+    return fs.existsSync(command);
+  }
+
+  const pathDirs = (process.env.PATH ?? "").split(path.delimiter);
+  const extensions =
+    process.platform === "win32" ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";") : [""];
+
+  for (const dir of pathDirs) {
+    for (const ext of extensions) {
+      const fullPath = path.join(dir, command + ext);
+      try {
+        fs.accessSync(fullPath, fs.constants.X_OK);
+        return true;
+      } catch {
+        // Not found here, continue
+      }
+    }
+  }
+  return false;
+}

package/node_modules/@mrclrchtr/supi-lsp/src/workspace-sentinels.ts

@@ -0,0 +1,114 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { FileChangeType, type FileEvent } from "./types.ts";
+import { fileToUri } from "./utils.ts";
+
+const IGNORED_DIRECTORIES = new Set(["node_modules", ".pnpm", ".git", "dist", "coverage"]);
+const ROOT_LOCKFILES = ["pnpm-lock.yaml", "package-lock.json", "yarn.lock", "bun.lockb"];
+
+/** Build a fresh snapshot of workspace sentinel files and their mtimes. */
+export function scanWorkspaceSentinels(cwd: string): Map<string, number> {
+  const resolvedCwd = path.resolve(cwd);
+  const snapshot = new Map<string, number>();
+
+  if (!fs.existsSync(resolvedCwd)) return snapshot;
+
+  try {
+    walkWorkspace(resolvedCwd, resolvedCwd, snapshot);
+  } catch {
+    return snapshot;
+  }
+
+  return snapshot;
+}
+
+/** Diff two sentinel snapshots into LSP file change events. */
+export function diffWorkspaceSentinelSnapshot(
+  previous: Map<string, number>,
+  next: Map<string, number>,
+): FileEvent[] {
+  const changes: FileEvent[] = [];
+
+  for (const [filePath, mtime] of next) {
+    const previousMtime = previous.get(filePath);
+    if (previousMtime === undefined) {
+      changes.push({ uri: fileToUri(filePath), type: FileChangeType.Created });
+      continue;
+    }
+    if (previousMtime !== mtime) {
+      changes.push({ uri: fileToUri(filePath), type: FileChangeType.Changed });
+    }
+  }
+
+  for (const filePath of previous.keys()) {
+    if (next.has(filePath)) continue;
+    changes.push({ uri: fileToUri(filePath), type: FileChangeType.Deleted });
+  }
+
+  return changes.sort((a, b) => a.uri.localeCompare(b.uri));
+}
+
+/** Refresh a previous snapshot and return the new snapshot plus change events. */
+export function syncWorkspaceSentinelSnapshot(
+  cwd: string,
+  previous: Map<string, number>,
+): { snapshot: Map<string, number>; changes: FileEvent[] } {
+  const snapshot = scanWorkspaceSentinels(cwd);
+  return {
+    snapshot,
+    changes: diffWorkspaceSentinelSnapshot(previous, snapshot),
+  };
+}
+
+/** Determine whether a file path should trigger workspace recovery. */
+export function isWorkspaceRecoveryTrigger(filePath: string, cwd: string): boolean {
+  const root = path.resolve(cwd);
+  return isWorkspaceSentinelPath(path.resolve(root, filePath), root);
+}
+
+function walkWorkspace(root: string, directory: string, snapshot: Map<string, number>): void {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(directory, { withFileTypes: true });
+  } catch {
+    // Permission error or deleted directory — skip it rather than
+    // failing the entire scan. A partial snapshot still detects
+    // changes in accessible subtrees.
+    return;
+  }
+
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (IGNORED_DIRECTORIES.has(entry.name)) continue;
+      walkWorkspace(root, path.join(directory, entry.name), snapshot);
+      continue;
+    }
+
+    if (!entry.isFile()) continue;
+
+    const filePath = path.join(directory, entry.name);
+    if (!isWorkspaceSentinelPath(filePath, root)) continue;
+    try {
+      snapshot.set(filePath, fs.statSync(filePath).mtimeMs);
+    } catch {
+      // File deleted between readdir and stat — skip.
+    }
+  }
+}
+
+function isWorkspaceSentinelPath(filePath: string, root: string): boolean {
+  const name = path.basename(filePath);
+
+  if (name === "package.json") return true;
+  if (name === "jsconfig.json") return true;
+  if (name === "tsconfig.json") return true;
+  if (name.startsWith("tsconfig.") && name.endsWith(".json")) return true;
+  if (filePath.endsWith(".d.ts")) return true;
+
+  return isRootLockfile(filePath, root);
+}
+
+function isRootLockfile(filePath: string, root: string): boolean {
+  if (path.dirname(filePath) !== root) return false;
+  return ROOT_LOCKFILES.includes(path.basename(filePath));
+}

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

@@ -0,0 +1,97 @@
+# @mrclrchtr/supi-tree-sitter
+
+Tree-sitter structural analysis for the [pi coding agent](https://github.com/earendil-works/pi).
+
+This package registers a `tree_sitter` tool and also exports a small TypeScript service API for other SuPi extensions. It is designed as a standalone structural-analysis substrate: it does not depend on `supi-lsp` or semantic language-server tooling, and it remains correct and useful when installed by itself.
+
+## Install
+
+```bash
+pi install npm:@mrclrchtr/supi-tree-sitter
+```
+
+Standalone installs include the runtime grammar dependencies needed for the supported non-vendored languages. Kotlin and SQL use vendored WASM grammars bundled with this package.
+
+It is also bundled by the full SuPi meta-package:
+
+```bash
+pi install npm:@mrclrchtr/supi
+```
+
+## Supported files
+
+The runtime can parse these file families:
+
+- **JavaScript / TypeScript** — `.ts`, `.tsx`, `.mts`, `.cts`, `.js`, `.jsx`, `.mjs`, `.cjs`
+- **Python** — `.py`, `.pyi`
+- **Rust** — `.rs`
+- **Go** — `.go`, `.mod`
+- **C / C++** — `.c`, `.h`, `.cpp`, `.hpp`, `.cc`, `.cxx`, `.hxx`, `.c++`, `.h++`
+- **Java** — `.java`
+- **Kotlin** — `.kt`, `.kts`
+- **Ruby** — `.rb`
+- **Bash / Shell** — `.sh`, `.bash`, `.zsh`
+- **HTML** — `.html`, `.htm`, `.xhtml`
+- **R** — `.r`
+- **SQL** — `.sql`
+
+Grammar `.wasm` files are resolved from installed package metadata for npm-shipped grammars, not from repository-relative paths.
+
+## `tree_sitter` tool
+
+Actions:
+
+- `outline` — list structural declarations such as functions, classes, interfaces, methods, and variables (**currently JavaScript / TypeScript only**)
+- `imports` — list import statements and module specifiers (**currently JavaScript / TypeScript only**)
+- `exports` — list exported declarations, re-exports, and TypeScript `export =` assignments (**currently JavaScript / TypeScript only**)
+- `node_at` — return the smallest syntax node at a 1-based `line`/`character` position, plus ancestry (all supported grammars)
+- `query` — run a custom Tree-sitter query and return captures (all supported grammars)
+- `callees` — find outgoing function/method calls from a position; supports all grammars with a callee query configured
+
+Coordinates are 1-based and compatible with the `lsp` tool. `character` is a UTF-16 code-unit column. Relative file paths resolve from the pi session working directory.
+
+Large result sets are capped at 100 emitted items per tool response. For outlines, nested children count toward the same cap so deeply nested classes do not bypass the limit.
+
+## Service API
+
+```ts
+import { createTreeSitterSession } from "@mrclrchtr/supi-tree-sitter";
+
+const session = createTreeSitterSession(process.cwd());
+try {
+  const parseable = await session.canParse("src/index.ts");
+  if (parseable.kind === "success") {
+    console.log(parseable.data.file, parseable.data.language);
+  }
+
+  const outline = await session.outline("src/index.ts");
+  if (outline.kind === "success") {
+    console.log(outline.data);
+  }
+
+  const callees = await session.calleesAt("src/index.ts", 1, 10);
+  if (callees.kind === "success") {
+    console.log(callees.data.enclosingScope.name, callees.data.callees);
+  }
+} finally {
+  session.dispose();
+}
+```
+
+`canParse(file)` validates that a supported file can be read and parsed, then returns the resolved file path and grammar id. It does not expose the raw Tree-sitter tree; use `outline`, `query`, `imports`, `exports`, `nodeAt`, or `calleesAt` for structured results.
+
+`calleesAt(file, line, character)` extracts structural outgoing calls from the enclosing function/method scope at the given position. It returns the enclosing scope name and a deduplicated list of callees with their source ranges.
+
+Exported types include `TreeSitterResult`, `TreeSitterSession`, `OutlineItem`, `ImportRecord`, `ExportRecord`, `NodeAtResult`, `QueryCapture`, `CalleesAtResult`, `SourceRange`, `GrammarId`, and `SupportedExtension`.
+
+Always call `dispose()` when the session is no longer needed. The runtime lazily initializes grammars, reuses parser instances within a session, deduplicates concurrent first-use grammar initialization, and retries after initialization failures.
+
+## Positioning
+
+`supi-tree-sitter` is the structural-analysis substrate in SuPi's layered code-understanding stack:
+
+- `supi-tree-sitter` — parser-backed structural analysis (this package)
+- `supi-lsp` — live semantic analysis through language servers
+- `supi-code-intelligence` — higher-level agent-facing analysis built on top of both substrates
+
+Each substrate can be installed and used independently. `supi-tree-sitter` does not require `supi-lsp` to be present, and its prompt guidance is written so it remains correct in standalone installs.