@mrclrchtr/supi-tree-sitter 1.7.0 → 1.9.0

package/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/src/tool-framework.ts

@@ -0,0 +1,116 @@
+// Shared tool framework for SuPi extensions.
+//
+// Provides a standard ToolSpec→PromptSurface→registerTool pipeline so
+// individual packages do not duplicate spec interfaces, guidance derivation,
+// registration loops, or common TypeBox parameter schemas.
+
+import type {
+  AgentToolResult,
+  AgentToolUpdateCallback,
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { type TSchema, Type } from "typebox";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Minimum contract for a SuPi tool definition. */
+export interface SuiPiToolSpec {
+  name: string;
+  label: string;
+  description: string;
+  promptSnippet: string;
+  promptGuidelines: string[];
+  parameters: TSchema;
+}
+
+/** Derived prompt surface — what pi flattens into the system prompt. */
+export interface SuiPiToolPromptSurface {
+  description: string;
+  promptSnippet: string;
+  promptGuidelines: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Guidance derivation
+// ---------------------------------------------------------------------------
+
+/**
+ * Static derivation: copies spec fields into a prompt surface.
+ *
+ * Packages that need dynamic guidance (e.g. server-coverage injection) should
+ * build their own surfaces, optionally starting from the output of this helper.
+ */
+export function derivePromptSurface(spec: SuiPiToolSpec): SuiPiToolPromptSurface {
+  return {
+    description: spec.description,
+    promptSnippet: spec.promptSnippet,
+    promptGuidelines: [...spec.promptGuidelines],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+// biome-ignore lint/complexity/useMaxParams: matches pi ToolDefinition.execute signature
+export type ToolExecuteFn = (
+  toolCallId: string,
+  params: unknown,
+  signal: AbortSignal | undefined,
+  onUpdate: AgentToolUpdateCallback<Record<string, unknown>> | undefined,
+  ctx: ExtensionContext,
+) => Promise<AgentToolResult<Record<string, unknown>>>;
+
+/**
+ * Register a set of tools from specs + pre-derived surfaces.
+ *
+ * `createExecute` receives the spec and returns a pi-compatible execute
+ * function.  This keeps execute-logic package-local while the framework owns
+ * the declarative surface and registration boilerplate.
+ */
+export function registerSuiPiTools(
+  pi: ExtensionAPI,
+  specs: readonly SuiPiToolSpec[],
+  surfaces: Record<string, SuiPiToolPromptSurface>,
+  createExecute: (spec: SuiPiToolSpec) => ToolExecuteFn,
+): void {
+  for (const spec of specs) {
+    const surface = surfaces[spec.name];
+    pi.registerTool({
+      name: spec.name,
+      label: spec.label,
+      description: surface?.description ?? spec.description,
+      promptSnippet: surface?.promptSnippet ?? spec.promptSnippet,
+      promptGuidelines: surface?.promptGuidelines ?? [...spec.promptGuidelines],
+      parameters: spec.parameters,
+      execute: createExecute(spec),
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Shared parameter builders
+// ---------------------------------------------------------------------------
+
+/** File path (relative or absolute). */
+export const FileParam = Type.String({ description: "File path (relative or absolute)" });
+
+/** 1-based line number. */
+export const LineParam = Type.Number({ description: "1-based line number", minimum: 1 });
+
+/** 1-based character column (UTF-16). */
+export const CharacterParam = Type.Number({
+  description: "1-based column number (UTF-16)",
+  minimum: 1,
+});
+
+/** Symbol name for discovery-based resolution. */
+export const SymbolParam = Type.String({
+  description: "Symbol name for discovery-based resolution",
+});
+
+/** Maximum results to return. */
+export const MaxResultsParam = Type.Number({ description: "Maximum results to return" });

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

@@ -0,0 +1,2 @@
+// supi-core types domain — shared substrate types (zero dependencies, pure types).
+export type { CodeLocation, CodePosition } from "./substrate-types.ts";

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

@@ -0,0 +1,40 @@
+{
+  "name": "@mrclrchtr/supi-code-runtime",
+  "version": "1.9.0",
+  "description": "SuPi code-runtime — shared workspace context, capability contracts, and canonical types for the code-understanding stack",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrclrchtr/supi.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "pi",
+    "pi-coding-agent"
+  ],
+  "files": [
+    "src/**/*.ts",
+    "!__tests__"
+  ],
+  "dependencies": {
+    "@mrclrchtr/supi-core": "1.9.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "bundledDependencies": [
+    "@mrclrchtr/supi-core"
+  ],
+  "main": "src/api.ts",
+  "exports": {
+    "./api": "./src/api.ts",
+    "./package.json": "./package.json"
+  }
+}

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

@@ -0,0 +1,35 @@
+/**
+ * Public API surface for @mrclrchtr/supi-code-runtime.
+ *
+ * This package exports shared canonical types, capability interfaces,
+ * workspace runtime primitives, and typed request context helpers.
+ * It is a library-only package with no pi extension entrypoint.
+ */
+
+// Capability interfaces and availability states
+export type {
+  CapabilityState,
+  SemanticProvider,
+  StructuralProvider,
+  StructuralResult,
+} from "./capability/types.ts";
+// Shared canonical types
+export type {
+  CalleesData,
+  CodeLocation,
+  CodePosition,
+  CodeResult,
+  CodeSymbol,
+  ConfidenceMode,
+  ExportData,
+  ImportData,
+  NodeAtData,
+  OutlineData,
+  SourceRange,
+} from "./types.ts";
+export type { WorkspaceContext } from "./workspace/context.ts";
+// Workspace context
+export { createWorkspaceContext } from "./workspace/context.ts";
+export type { WorkspaceCapabilities } from "./workspace/runtime.ts";
+// Workspace runtime
+export { getDefaultWorkspaceRuntime, WorkspaceRuntime } from "./workspace/runtime.ts";

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

@@ -0,0 +1,68 @@
+/**
+ * Capability interfaces and availability states for the code-understanding
+ * stack. These define the contracts through which substrates (LSP,
+ * tree-sitter) advertise what they can do.
+ */
+
+import type {
+  CalleesData,
+  CodeLocation,
+  CodePosition,
+  CodeResult,
+  CodeSymbol,
+  ExportData,
+  ImportData,
+  NodeAtData,
+  OutlineData,
+} from "../types.ts";
+
+// ── Availability state ─────────────────────────────────────────────────
+
+/**
+ * Availability state for a capability within a workspace.
+ *
+ * - `pending`: the capability may become ready soon (e.g., server starting)
+ * - `ready`: the capability is active and can be used
+ * - `inactive`: the capability exists but is intentionally turned off
+ * - `disabled`: the capability is unavailable for workspace-specific reasons
+ * - `unavailable`: the capability cannot be provided at all
+ */
+export type CapabilityState =
+  | { kind: "pending" }
+  | { kind: "ready" }
+  | { kind: "inactive" }
+  | { kind: "disabled" }
+  | { kind: "unavailable"; reason: string };
+
+// ── Provider interfaces ────────────────────────────────────────────────
+
+/**
+ * Semantic analysis capability backed by a language server (LSP).
+ *
+ * Methods return `null` to signal absence (unavailable / inactive) and
+ * an array to signal a successful query (possibly empty).
+ */
+export interface SemanticProvider {
+  references(filePath: string, position: CodePosition): Promise<CodeLocation[] | null>;
+  implementation(filePath: string, position: CodePosition): Promise<CodeLocation[] | null>;
+  documentSymbols(filePath: string): Promise<CodeSymbol[] | null>;
+  workspaceSymbols(query: string): Promise<CodeSymbol[] | null>;
+}
+
+/**
+ * Structural analysis capability backed by a parser (tree-sitter).
+ *
+ * Methods return a discriminated `CodeResult` union that explicitly encodes
+ * success, unsupported-language, file-access error, validation error,
+ * and runtime error states.
+ */
+export interface StructuralProvider {
+  calleesAt(file: string, line: number, character: number): Promise<CodeResult<CalleesData>>;
+  exports(file: string): Promise<CodeResult<ExportData[]>>;
+  outline(file: string): Promise<CodeResult<OutlineData[]>>;
+  imports(file: string): Promise<CodeResult<ImportData[]>>;
+  nodeAt(file: string, line: number, character: number): Promise<CodeResult<NodeAtData>>;
+}
+
+/** Convenience alias for `CodeResult` used in structural contexts. */
+export type StructuralResult<T> = CodeResult<T>;

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

@@ -0,0 +1,31 @@
+/**
+ * Package-root re-export surface for @mrclrchtr/supi-code-runtime.
+ *
+ * Prefer importing from `@mrclrchtr/supi-code-runtime/api` for explicit
+ * access to the shared contracts and workspace primitives.
+ */
+
+export type {
+  CalleesData,
+  CapabilityState,
+  CodeLocation,
+  CodePosition,
+  CodeResult,
+  CodeSymbol,
+  ConfidenceMode,
+  ExportData,
+  ImportData,
+  NodeAtData,
+  OutlineData,
+  SemanticProvider,
+  SourceRange,
+  StructuralProvider,
+  StructuralResult,
+  WorkspaceCapabilities,
+  WorkspaceContext,
+} from "./api.ts";
+export {
+  createWorkspaceContext,
+  getDefaultWorkspaceRuntime,
+  WorkspaceRuntime,
+} from "./api.ts";

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

@@ -0,0 +1,110 @@
+/**
+ * Canonical shared types for the SuPi code-understanding stack.
+ *
+ * These types are package-agnostic and used across supi-lsp, supi-tree-sitter,
+ * and supi-code-intelligence for communicating code analysis results,
+ * capability availability, and structural data shapes.
+ */
+
+// ── Position and location types ────────────────────────────────────────
+
+/** 0-based LSP position. */
+export interface CodePosition {
+  line: number;
+  character: number;
+}
+
+/** A source range spanning two CodePositions. */
+export interface SourceRange {
+  start: CodePosition;
+  end: CodePosition;
+}
+
+/** A code location (file URI + range). */
+export interface CodeLocation {
+  uri: string;
+  range: SourceRange;
+}
+
+// ── Symbol types ───────────────────────────────────────────────────────
+
+/** A discovered symbol / declaration. */
+export interface CodeSymbol {
+  name: string;
+  kind: string;
+  file: string;
+  line: number;
+  character: number;
+  container?: string | null;
+}
+
+// ── Result types ───────────────────────────────────────────────────────
+
+/**
+ * Discriminated result union for provider operations.
+ *
+ * Used primarily by structural (tree-sitter-backed) operations that
+ * have explicit error and unsupported-language states. Semantic operations
+ * use `null` to signal absence.
+ */
+export type CodeResult<T> =
+  | { kind: "success"; data: T }
+  | { kind: "unsupported-language"; file: string; message: string }
+  | { kind: "file-access-error"; file: string; message: string }
+  | { kind: "validation-error"; message: string }
+  | { kind: "runtime-error"; message: string }
+  | { kind: "unavailable"; message: string };
+
+/** Result confidence classification. */
+export type ConfidenceMode = "semantic" | "structural" | "heuristic" | "unavailable";
+
+// ── Structural data shapes (value types, range-flattened) ──────────────
+
+export interface OutlineData {
+  name: string;
+  kind: string;
+  startLine: number;
+  startCharacter: number;
+  endLine: number;
+  endCharacter: number;
+  children?: OutlineData[];
+}
+
+export interface ExportData {
+  name: string;
+  kind: string;
+  startLine: number;
+  startCharacter: number;
+  endLine: number;
+  endCharacter: number;
+  moduleSpecifier?: string;
+}
+
+export interface ImportData {
+  moduleSpecifier: string;
+  startLine: number;
+  startCharacter: number;
+  endLine: number;
+  endCharacter: number;
+}
+
+export interface NodeAtData {
+  type: string;
+  startLine: number;
+  startCharacter: number;
+  endLine: number;
+  endCharacter: number;
+  text: string;
+  ancestry: Array<{
+    type: string;
+    startLine: number;
+    startCharacter: number;
+    endLine: number;
+    endCharacter: number;
+  }>;
+}
+
+export interface CalleesData {
+  enclosingScope: { name: string; startLine: number; endLine: number };
+  callees: Array<{ name: string; startLine: number }>;
+}

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

@@ -0,0 +1,41 @@
+/**
+ * Typed request context helper for consumers that need a convenient view
+ * of the capability state for a workspace cwd.
+ *
+ * This is the primary way that `supi-code-intelligence` reads capability
+ * state from the shared runtime. Substrates register providers through
+ * {@link WorkspaceRuntime} directly.
+ */
+
+import type { CapabilityState, SemanticProvider, StructuralProvider } from "../capability/types.ts";
+import type { WorkspaceRuntime } from "./runtime.ts";
+
+/**
+ * A workspace-scoped request context that provides access to active
+ * semantic and structural capabilities along with their availability
+ * state and the cached project model.
+ */
+export interface WorkspaceContext {
+  /** The working directory this context is scoped to. */
+  cwd: string;
+  /** Semantic analysis capability state and provider. */
+  semantic: { state: CapabilityState; provider: SemanticProvider | null };
+  /** Structural analysis capability state and provider. */
+  structural: { state: CapabilityState; provider: StructuralProvider | null };
+}
+
+/**
+ * Create a typed workspace context from the shared runtime.
+ *
+ * @param cwd - The working directory for this context.
+ * @param runtime - The shared workspace runtime instance.
+ * @returns A snapshot of the capability state for this workspace.
+ */
+export function createWorkspaceContext(cwd: string, runtime: WorkspaceRuntime): WorkspaceContext {
+  const ws = runtime.getWorkspace(cwd);
+  return {
+    cwd,
+    semantic: ws.semantic,
+    structural: ws.structural,
+  };
+}

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

@@ -0,0 +1,170 @@
+/**
+ * Workspace-scoped capability registry.
+ *
+ * Substrates (LSP, tree-sitter) register their capabilities per cwd
+ * at session startup. Code-intelligence reads capability state from
+ * this registry instead of maintaining a local provider composition
+ * layer.
+ *
+ * Capabilities are independent: registering a semantic provider does not
+ * affect an already-registered structural provider for the same cwd.
+ */
+
+import type { CapabilityState, SemanticProvider, StructuralProvider } from "../capability/types.ts";
+
+// ── Public types ───────────────────────────────────────────────────────
+
+/**
+ * The combined capability state for a workspace.
+ * Each capability slot includes both the availability state and the
+ * provider instance (null when not ready).
+ */
+export interface WorkspaceCapabilities {
+  semantic: { state: CapabilityState; provider: SemanticProvider | null };
+  structural: { state: CapabilityState; provider: StructuralProvider | null };
+}
+
+// ── Defaults ───────────────────────────────────────────────────────────
+
+const DEFAULT_UNAVAILABLE_REASON = "No provider registered for this workspace";
+
+function createDefaultCapabilities(): WorkspaceCapabilities {
+  return {
+    semantic: {
+      state: { kind: "unavailable", reason: DEFAULT_UNAVAILABLE_REASON },
+      provider: null,
+    },
+    structural: {
+      state: { kind: "unavailable", reason: DEFAULT_UNAVAILABLE_REASON },
+      provider: null,
+    },
+  };
+}
+
+// ── Runtime ────────────────────────────────────────────────────────────
+
+/**
+ * Workspace-scoped capability registry keyed by cwd/project root.
+ *
+ * Each workspace stores independent capability state for semantic
+ * (LSP-backed) and structural (tree-sitter-backed) analysis. Substrates
+ * register their capabilities at session start; consumers read them
+ * as needed.
+ *
+ * The registry is intentionally unopinionated about which capabilities
+ * are required — a workspace may have only semantic, only structural,
+ * both, or neither.
+ */
+export class WorkspaceRuntime {
+  readonly #workspaces = new Map<string, WorkspaceCapabilities>();
+
+  /**
+   * Get the capability state for a workspace cwd.
+   * Returns a default "unavailable" state if the workspace
+   * has never been registered.
+   */
+  getWorkspace(cwd: string): WorkspaceCapabilities {
+    return this.#workspaces.get(cwd) ?? createDefaultCapabilities();
+  }
+
+  /**
+   * Register a semantic provider for a workspace.
+   * Replaces any existing semantic provider for the same cwd
+   * without affecting the structural provider.
+   */
+  registerSemantic(cwd: string, provider: SemanticProvider): void {
+    const existing = this.#workspaces.get(cwd);
+    if (existing) {
+      existing.semantic = { state: { kind: "ready" }, provider };
+    } else {
+      this.#workspaces.set(cwd, {
+        semantic: { state: { kind: "ready" }, provider },
+        structural: createDefaultCapabilities().structural,
+      });
+    }
+  }
+
+  /**
+   * Register a structural provider for a workspace.
+   * Replaces any existing structural provider for the same cwd
+   * without affecting the semantic provider.
+   */
+  registerStructural(cwd: string, provider: StructuralProvider): void {
+    const existing = this.#workspaces.get(cwd);
+    if (existing) {
+      existing.structural = { state: { kind: "ready" }, provider };
+    } else {
+      this.#workspaces.set(cwd, {
+        semantic: createDefaultCapabilities().semantic,
+        structural: { state: { kind: "ready" }, provider },
+      });
+    }
+  }
+
+  /**
+   * Remove all capability state for a single workspace cwd.
+   */
+  clearWorkspace(cwd: string): void {
+    this.#workspaces.delete(cwd);
+  }
+
+  /**
+   * Clear only the semantic capability slot for a workspace.
+   * Leaves the structural slot untouched.
+   */
+  clearSemantic(cwd: string): void {
+    const ws = this.#workspaces.get(cwd);
+    if (!ws) return;
+    ws.semantic = createDefaultCapabilities().semantic;
+    // If both slots are now unavailable, remove the entire entry
+    if (ws.semantic.state.kind === "unavailable" && ws.structural.state.kind === "unavailable") {
+      this.#workspaces.delete(cwd);
+    }
+  }
+
+  /**
+   * Clear only the structural capability slot for a workspace.
+   * Leaves the semantic slot untouched.
+   */
+  clearStructural(cwd: string): void {
+    const ws = this.#workspaces.get(cwd);
+    if (!ws) return;
+    ws.structural = createDefaultCapabilities().structural;
+    // If both slots are now unavailable, remove the entire entry
+    if (ws.semantic.state.kind === "unavailable" && ws.structural.state.kind === "unavailable") {
+      this.#workspaces.delete(cwd);
+    }
+  }
+
+  /**
+   * Remove all capability state for every workspace.
+   */
+  clearAll(): void {
+    this.#workspaces.clear();
+  }
+}
+
+// ── Default singleton ───────────────────────────────────────────────────
+
+const RUNTIME_SYMBOL = Symbol.for("@mrclrchtr/supi-code-runtime/default-runtime");
+
+/**
+ * Get the shared default workspace runtime instance.
+ *
+ * Backed by `globalThis` + `Symbol.for` so that all jiti module instances
+ * (even duplicate loads through separate `node_modules` paths) share the
+ * same WorkspaceRuntime. Without this, standalone installs where
+ * `supi-lsp`, `supi-tree-sitter`, and `supi-code-intelligence` each bundle
+ * their own copy of `@mrclrchtr/supi-code-runtime` would get separate
+ * runtimes — LSP/tree-sitter would register capabilities into one while
+ * code-intelligence reads from another.
+ */
+export function getDefaultWorkspaceRuntime(): WorkspaceRuntime {
+  const g = globalThis as Record<symbol, unknown>;
+  let runtime = g[RUNTIME_SYMBOL] as WorkspaceRuntime | undefined;
+  if (!runtime) {
+    runtime = new WorkspaceRuntime();
+    g[RUNTIME_SYMBOL] = runtime;
+  }
+  return runtime;
+}

package/node_modules/@mrclrchtr/supi-core/README.md

@@ -1,29 +1,20 @@
+![SuPi](assets/logo.png)
+
 # @mrclrchtr/supi-core
 
 Shared infrastructure for SuPi extensions.
 
-This package is mainly for extension authors. It gives you a common config system, settings plumbing, context helpers, registries, and a small extension surface that registers `/supi-settings`.
+This is a **pure library** — it does not register any pi commands or tools. The `/supi-settings` command is now available through `@mrclrchtr/supi-settings`.
 
 ## Install
 
-### As a dependency for another extension
-
 ```bash
 pnpm add @mrclrchtr/supi-core
 ```
 
-### As a pi package
-
-```bash
-pi install npm:@mrclrchtr/supi-core
-```
-
-Installing it as a pi package adds the minimal `/supi-settings` extension surface.
-
 ## Package surfaces
 
 - `@mrclrchtr/supi-core/api` — reusable helpers for other packages and extensions
-- `@mrclrchtr/supi-core/extension` — minimal pi extension that registers `/supi-settings`
 
 ## What you get from the API
 
@@ -101,7 +92,6 @@ const message = wrapExtensionContext("my-extension", "hello", {
 ## Source
 
 - `src/api.ts` — exported library surface
-- `src/extension.ts` — minimal `/supi-settings` entrypoint
 - `src/config.ts` — shared config loading and writing
 - `src/config-settings.ts` — config-backed settings registration helper
 - `src/settings-ui.ts` — shared settings overlay