@mrclrchtr/supi-code-intelligence 1.16.1 → 2.0.1

package/src/tool/schemas.ts

@@ -0,0 +1,337 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { type TSchema, Type } from "typebox";
+import type { CodeIntelligenceToolName } from "../types/index.ts";
+
+const ScopeParam = Type.String({
+  description: "Workspace-relative path, package, or directory scope for the workflow query.",
+});
+const FileParam = Type.String({ description: "Target file path." });
+const QueryParam = Type.String({
+  description: "Human or code reference to resolve or search for.",
+});
+const LineParam = Type.Number({ description: "1-based line.", minimum: 1 });
+const CharacterParam = Type.Number({
+  description: "1-based UTF-16 column.",
+  minimum: 1,
+});
+const MaxResultsParam = Type.Number({
+  description: "Maximum number of ranked results.",
+  minimum: 1,
+});
+const SymbolParam = Type.String({ description: "Symbol name" });
+const TargetIdParam = Type.String({
+  description:
+    "Resolved target handle from `code_resolve`. Takes precedence over file/line/character/symbol.",
+});
+const RangeParam = Type.Object(
+  {
+    start: Type.Object({ line: LineParam, character: CharacterParam }),
+    end: Type.Object({ line: LineParam, character: CharacterParam }),
+  },
+  { description: "1-based selected source range for extract refactors." },
+);
+
+/**
+ * Planned `code_resolve` parameters.
+ *
+ * Runtime rule for future executors:
+ * - require `query` or `file`
+ * - require `file` when `line` or `character` is provided
+ */
+export const CodeResolveParameters = Type.Object(
+  {
+    query: Type.Optional(QueryParam),
+    scope: Type.Optional(ScopeParam),
+    kind: Type.Optional(
+      StringEnum(
+        [
+          "symbol",
+          "function",
+          "class",
+          "interface",
+          "file",
+          "export",
+          "variable",
+          "method",
+          "const",
+          "enum",
+        ],
+        {
+          description: "Preferred target kind when disambiguating the query.",
+        },
+      ),
+    ),
+    file: Type.Optional(FileParam),
+    line: Type.Optional(LineParam),
+    character: Type.Optional(CharacterParam),
+    maxResults: Type.Optional(MaxResultsParam),
+  },
+  { additionalProperties: false },
+);
+
+/** Planned `code_inspect` parameters. Requires a precise point in one file. */
+export const CodeInspectParameters = Type.Object(
+  {
+    file: FileParam,
+    line: LineParam,
+    character: CharacterParam,
+    maxResults: Type.Optional(MaxResultsParam),
+  },
+  { additionalProperties: false },
+);
+
+/**
+ * `code_orientation` parameters.
+ *
+ * Runtime rules:
+ * - no focus means workspace-level orientation
+ * - `focus` is a workspace-relative path or discovered module name
+ * - `focus` + `line` + `character` resolves a real symbol target through the same path as `code_resolve`
+ * - `targetId` takes precedence over focus/coordinates; stale target IDs do not fall back
+ */
+export const CodeOrientationParameters = Type.Object(
+  {
+    focus: Type.Optional(
+      Type.String({
+        description:
+          "Workspace-relative path or discovered module name to orient around. Omit for project orientation.",
+      }),
+    ),
+    targetId: Type.Optional(
+      Type.String({
+        description:
+          "Resolved target handle from `code_resolve`. Takes precedence over `focus`/`line`/`character`. If invalid or stale, the call errors and does not fall back to coordinates.",
+      }),
+    ),
+    line: Type.Optional(
+      Type.Number({
+        description: "1-based line for symbol orientation. Requires `focus` and `character`.",
+        minimum: 1,
+      }),
+    ),
+    character: Type.Optional(
+      Type.Number({
+        description: "1-based UTF-16 column for symbol orientation. Requires `focus` and `line`.",
+        minimum: 1,
+      }),
+    ),
+    maxResults: Type.Optional(MaxResultsParam),
+  },
+  { additionalProperties: false },
+);
+
+/**
+ * Planned `code_find` parameters.
+ *
+ * Phase 0 intentionally excludes speculative natural-language search. A future phase
+ * may add it only after a real implementation exists.
+ */
+export const CodeFindParameters = Type.Object(
+  {
+    query: QueryParam,
+    scope: Type.Optional(ScopeParam),
+    mode: Type.Optional(
+      StringEnum(["text", "regex", "ast", "semantic"], {
+        description:
+          'Search mode. Omit for literal text search. mode: "ast" requires `kind`; mode: "text", mode: "regex", and mode: "semantic" do not accept `kind`.',
+      }),
+    ),
+    kind: Type.Optional(
+      StringEnum(
+        [
+          "definition",
+          "import",
+          "export",
+          "call",
+          "type",
+          "interface",
+          "class",
+          "method",
+          "enum",
+          "test",
+        ],
+        {
+          description:
+            'Only valid with `mode: "ast"`. Supported AST kinds: `definition`, `import`, `export`, `call`, `type`, `interface`, `class`, `method`, `enum`, `test`. AST `call` matches call-site identifiers by name, not by symbol identity.',
+        },
+      ),
+    ),
+    contextLines: Type.Optional(
+      Type.Number({ description: "Context lines to include around matches.", minimum: 0 }),
+    ),
+    maxResults: Type.Optional(MaxResultsParam),
+  },
+  { additionalProperties: false },
+);
+
+/**
+ * `code_graph` parameters.
+ *
+ * Phase 0 uses `references` rather than `callers` so the public contract stays honest
+ * until a true incoming-call hierarchy exists.
+ *
+ * Runtime rule for future executors:
+ * - require `targetId`, `file` + `line` + `character`, `symbol`, or `scope`
+ */
+export const CodeGraphParameters = Type.Object(
+  {
+    targetId: Type.Optional(TargetIdParam),
+    file: Type.Optional(FileParam),
+    line: Type.Optional(LineParam),
+    character: Type.Optional(CharacterParam),
+    symbol: Type.Optional(SymbolParam),
+    scope: Type.Optional(ScopeParam),
+    relations: Type.Optional(
+      Type.Array(
+        StringEnum(["all", "references", "callees", "imports", "exports", "implements", "tests"], {
+          description:
+            'Relation families to include in the graph. Use `"all"` to expand to every relation family. `callees` is direct structural outgoing-call evidence: source-shape calls in the enclosing scope, not symbol-identity resolution.',
+        }),
+        {
+          description: 'Requested relation families. Defaults to ["references"] when omitted.',
+          uniqueItems: true,
+        },
+      ),
+    ),
+    maxResults: Type.Optional(MaxResultsParam),
+    calleeDepth: Type.Optional(
+      StringEnum(["direct", "deep"], {
+        description:
+          'Depth for callee collection. `"direct"` (default): only direct calls from the enclosing scope, excluding nested function/callback scopes. `"deep"`: include all callees within the enclosing scope, including those inside nested scopes.',
+      }),
+    ),
+  },
+  { additionalProperties: false },
+);
+
+/**
+ * Planned `code_impact` parameters.
+ *
+ * Runtime rule for future executors:
+ * - require at least one of `targetId`, `change`, or `changeSetFiles`
+ */
+export const CodeImpactParameters = Type.Object(
+  {
+    targetId: Type.Optional(
+      Type.String({ description: "Resolved target handle from `code_resolve`." }),
+    ),
+    change: Type.Optional(
+      Type.String({ description: "Proposed change description for blast-radius analysis." }),
+    ),
+    changeSetFiles: Type.Optional(
+      Type.Array(Type.String({ description: "Workspace-relative file in the change set." }), {
+        description:
+          "User-supplied files to analyze as the change set. This is not inferred from git and carries no line-level diff evidence.",
+        minItems: 1,
+        uniqueItems: true,
+      }),
+    ),
+    includeTests: Type.Optional(
+      Type.Boolean({
+        description:
+          "Whether likely tests should be included in the impact set. changeSetFiles analysis uses semantic references when available plus deterministic conventions; target-based analysis may combine semantic references with deterministic conventions.",
+      }),
+    ),
+    maxResults: Type.Optional(MaxResultsParam),
+  },
+  { additionalProperties: false },
+);
+
+/**
+ * Planned `code_refactor_plan` parameters.
+ *
+ * `operation` is the only intentional operation-style enum in the V2 skeleton.
+ * Phase 0 does not introduce a generic action mega-tool.
+ *
+ * Runtime rules for future executors:
+ * - require `targetId` or anchored `file` + `line` + `character`
+ * - `rename` (legacy alias), `rename_symbol`, and extract operations require `newName`
+ * - extract operations require `range`
+ */
+export const CodeRefactorParameters = Type.Object(
+  {
+    operation: StringEnum(["rename", "rename_symbol", "extract_function", "extract_variable"], {
+      description:
+        "Precise refactor operation to plan. `rename` is accepted as a compatibility alias for `rename_symbol`.",
+    }),
+    targetId: Type.Optional(
+      Type.String({ description: "Resolved target handle from `code_resolve`." }),
+    ),
+    file: Type.Optional(FileParam),
+    line: Type.Optional(LineParam),
+    character: Type.Optional(CharacterParam),
+    range: Type.Optional(RangeParam),
+    newName: Type.Optional(
+      Type.String({ description: "New symbol name for rename/extract operations." }),
+    ),
+  },
+  { additionalProperties: false },
+);
+
+/** Planned `code_refactor_apply` parameters. `planId` is required. */
+export const CodeApplyParameters = Type.Object(
+  {
+    planId: Type.String({
+      description: "Stored plan identifier returned by a previous refactor/plan step.",
+    }),
+  },
+  { additionalProperties: false },
+);
+
+/**
+ * Planned `code_health` parameters.
+ *
+ * This is the future diagnostics/status surface that will eventually replace direct
+ * public substrate diagnostics and recovery tools.
+ */
+export const CodeHealthParameters = Type.Object(
+  {
+    scope: Type.Optional(ScopeParam),
+    refresh: Type.Optional(
+      Type.Boolean({ description: "Refresh provider state before collecting health data." }),
+    ),
+    include: Type.Optional(
+      Type.Array(
+        StringEnum(["diagnostics", "servers", "dirty", "coverage", "unused"], {
+          description: "Health signals to include.",
+        }),
+        {
+          description: "Requested health-signal sections.",
+          uniqueItems: true,
+        },
+      ),
+    ),
+    level: Type.Optional(
+      StringEnum(["summary", "detailed"], {
+        description: "Detail level for the health report.",
+      }),
+    ),
+    coveragePath: Type.Optional(
+      Type.String({
+        description:
+          "Workspace-relative path to a coverage summary JSON file. Defaults to `coverage/coverage-summary.json`.",
+      }),
+    ),
+    unusedPath: Type.Optional(
+      Type.String({
+        description: "Workspace-relative path to a knip JSON report. Defaults to `knip.json`.",
+      }),
+    ),
+  },
+  { additionalProperties: false },
+);
+
+export type WorkflowCodeToolSchemaKey = CodeIntelligenceToolName;
+
+/** Code intelligence tool schemas keyed by public tool name. */
+export const CODE_INTELLIGENCE_TOOL_SCHEMAS = {
+  code_resolve: CodeResolveParameters,
+  code_inspect: CodeInspectParameters,
+  code_orientation: CodeOrientationParameters,
+  code_find: CodeFindParameters,
+  code_graph: CodeGraphParameters,
+  code_impact: CodeImpactParameters,
+  code_refactor_plan: CodeRefactorParameters,
+  code_refactor_apply: CodeApplyParameters,
+  code_health: CodeHealthParameters,
+} as const satisfies Record<CodeIntelligenceToolName, TSchema>;

package/src/tool/specs.ts

@@ -0,0 +1,257 @@
+import type { TSchema } from "typebox";
+import type {
+  CodeIntelligenceToolName,
+  CodeIntelResult,
+  CodeIntelToolExecCtx,
+} from "../types/index.ts";
+import { executeFindTool } from "./find/execute.ts";
+import { executeGraphTool } from "./graph/execute.ts";
+import { executeHealthTool } from "./health/execute.ts";
+import { executeImpactTool } from "./impact/execute.ts";
+import { emitToolProgress } from "./infra/progress.ts";
+import { executeInspectTool } from "./inspect/execute.ts";
+import { executeOrientationTool } from "./orientation/execute.ts";
+import { executeRefactorApplyTool } from "./refactor-apply/execute.ts";
+import { executeRefactorPlanTool } from "./refactor-plan/execute.ts";
+import { executeResolveTool } from "./resolve/execute.ts";
+import {
+  CodeApplyParameters,
+  CodeFindParameters,
+  CodeGraphParameters,
+  CodeHealthParameters,
+  CodeImpactParameters,
+  CodeInspectParameters,
+  CodeOrientationParameters,
+  CodeRefactorParameters,
+  CodeResolveParameters,
+} from "./schemas.ts";
+
+/** Substrate families that power a tool's implementation. */
+export type ToolSubstrate = "semantic" | "structural" | "search" | "git" | "diagnostics";
+
+/** Deployment phase for a tool. */
+export type ToolPhase = "phase-1" | "phase-2" | "phase-3" | "phase-4" | "phase-5" | "phase-6";
+
+/** Canonical spec for one code-intelligence tool — runtime registration config. */
+export interface CodeIntelligenceToolDefinitionSpec {
+  name: CodeIntelligenceToolName;
+  label: string;
+  parameters: TSchema;
+  /** Per-spec line-limit override for the adapter's head truncation. */
+  maxLines?: number;
+  /** Per-spec byte-limit override for the adapter's head truncation. */
+  maxBytes?: number;
+  /** When true, oversized truncated output spills to a temp file. */
+  spillToTempFile?: boolean;
+  run: (params: unknown, ctx: CodeIntelToolExecCtx) => Promise<CodeIntelResult> | CodeIntelResult;
+
+  // ── Design metadata ────────────────────────────────────────────────
+
+  /** One-line purpose summary for docs and tests. */
+  purpose?: string;
+  /** Key into CODE_INTELLIGENCE_TOOL_SCHEMAS. */
+  schemaKey?: CodeIntelligenceToolName;
+  /** Concise schema summary for future maintainers. */
+  schemaDocs?: string;
+  /** Legacy tools this tool absorbed (empty for new tools). */
+  absorbsTools?: string[];
+  /** Legacy behaviors this tool absorbed. */
+  absorbsBehaviors?: string[];
+  /** Substrate families that power the implementation. */
+  substrates?: ToolSubstrate[];
+  /** Deployment phase. */
+  phase?: ToolPhase;
+  /** Explicit non-goals — what the tool intentionally does NOT do. */
+  nonGoals?: string[];
+}
+
+/**
+ * Canonical code-intelligence tool specs — runtime registration data.
+ *
+ * Prompt descriptions and guidelines live in {@link ./guidance.ts}.
+ */
+export const CODE_INTELLIGENCE_TOOL_SPECS = [
+  {
+    name: "code_resolve",
+    label: "Code Resolve",
+    parameters: CodeResolveParameters,
+    run: (params, ctx) =>
+      executeResolveTool(params as Parameters<typeof executeResolveTool>[0], ctx),
+    purpose:
+      "Resolve human or code references into precise file/range/symbol targets and stable target handles.",
+    schemaKey: "code_resolve",
+    schemaDocs:
+      "Accepts a query or file-based anchor plus optional scope/kind/maxResults. Later phases validate that line/character require file.",
+    absorbsTools: [],
+    absorbsBehaviors: [],
+    substrates: ["semantic", "search"],
+    phase: "phase-1",
+    nonGoals: ["Target handles do not persist across sessions."],
+  },
+  {
+    name: "code_inspect",
+    label: "Code Inspect",
+    parameters: CodeInspectParameters,
+    run: (params, ctx) =>
+      executeInspectTool(params as Parameters<typeof executeInspectTool>[0], ctx),
+    purpose:
+      "Inspect one precise point in code with best-effort syntax, symbol, hover, definition, diagnostics, and code-action facts.",
+    schemaKey: "code_inspect",
+    schemaDocs:
+      "Requires file, line, and character plus optional maxResults. It is the explicit point-inspection surface; code_orientation handles broader orientation.",
+    absorbsTools: [],
+    absorbsBehaviors: ["anchored orientation inspection"],
+    substrates: ["semantic", "structural", "diagnostics"],
+    phase: "phase-2",
+    nonGoals: [
+      "Does not accept targetId in this first pass; inspection stays point-based.",
+      "Does not apply code actions.",
+    ],
+  },
+  {
+    name: "code_orientation",
+    label: "Code Orientation",
+    parameters: CodeOrientationParameters,
+    run: (params, ctx) =>
+      executeOrientationTool(params as Parameters<typeof executeOrientationTool>[0], ctx),
+    purpose:
+      "Orient around a project, discovered module, directory, file, or precise symbol before choosing surgical follow-up tools.",
+    schemaKey: "code_orientation",
+    schemaDocs:
+      "Accepts optional focus, targetId, line, character, and maxResults. Omitted focus returns workspace orientation; focus is path-first with discovered-module lookup; focus+line+character resolves a symbol; targetId wins over focus/coordinates.",
+    absorbsTools: ["code_brief", "code_context"],
+    absorbsBehaviors: [],
+    substrates: ["semantic", "structural", "diagnostics"],
+    phase: "phase-2",
+    nonGoals: [
+      "Does not provide relation, tests, or impact sections; use code_graph and code_impact.",
+      "Does not resolve bare symbol names; use code_resolve first.",
+    ],
+  },
+  {
+    name: "code_graph",
+    label: "Code Graph",
+    parameters: CodeGraphParameters,
+    spillToTempFile: true,
+    run: (params, ctx) => executeGraphTool(params as Parameters<typeof executeGraphTool>[0], ctx),
+    purpose:
+      "Show the graph of relationships touching a target, including references, callees, imports, exports, implementations, and tests.",
+    schemaKey: "code_graph",
+    schemaDocs:
+      "Accepts targetId plus relations and maxResults (per-relation result cap). Uses references rather than misleading callers labels.",
+    absorbsTools: ["code_references", "code_calls", "code_implementations"],
+    absorbsBehaviors: [],
+    substrates: ["semantic", "structural", "search"],
+    phase: "phase-3",
+    nonGoals: [
+      "Does not claim true incoming caller support until a real call hierarchy exists.",
+      "Does not collapse unrelated impact or search concerns into the graph surface.",
+    ],
+  },
+  {
+    name: "code_impact",
+    label: "Code Impact",
+    parameters: CodeImpactParameters,
+    spillToTempFile: true,
+    run: (params, ctx) => executeImpactTool(params as Parameters<typeof executeImpactTool>[0], ctx),
+    purpose:
+      "Estimate blast radius for a target, user-supplied change set, or proposed change description, including likely tests and docs.",
+    schemaKey: "code_impact",
+    schemaDocs:
+      "Accepts targetId, change, or changeSetFiles plus includeTests/maxResults. Runtime validation later requires at least one primary subject.",
+    absorbsTools: [],
+    absorbsBehaviors: [],
+    substrates: ["semantic", "structural", "search", "diagnostics"],
+    phase: "phase-4",
+    nonGoals: [
+      "Does not guarantee perfect downstream impact inference without substrate evidence.",
+    ],
+  },
+  {
+    name: "code_find",
+    label: "Code Find",
+    parameters: CodeFindParameters,
+    spillToTempFile: true,
+    run: (params, ctx) => executeFindTool(params as Parameters<typeof executeFindTool>[0], ctx),
+    purpose:
+      "Run unified ranked search across literal text, regex, AST, and semantic modes with one intent-level surface.",
+    schemaKey: "code_find",
+    schemaDocs:
+      "Requires query and supports scope, mode, kind, contextLines, and maxResults. Excludes speculative natural-language mode.",
+    absorbsTools: ["code_pattern"],
+    absorbsBehaviors: [],
+    substrates: ["semantic", "structural", "search"],
+    phase: "phase-2",
+    nonGoals: [
+      "Does not activate natural-language retrieval without a real implementation.",
+      "Removed code_pattern in Phase 2b (TNDM-057XHJ).",
+    ],
+  },
+  {
+    name: "code_refactor_plan",
+    label: "Code Refactor Plan",
+    parameters: CodeRefactorParameters,
+    run: async (params, ctx) => {
+      emitToolProgress(
+        ctx.onUpdate,
+        `code_refactor_plan: requesting ${(params as Record<string, unknown>).operation} plan from LSP...`,
+      );
+      return executeRefactorPlanTool(
+        params as Parameters<typeof executeRefactorPlanTool>[0],
+        ctx,
+        "code_refactor_plan",
+      );
+    },
+    purpose:
+      "Create precise refactor plans for named operations such as rename and extract refactors.",
+    schemaKey: "code_refactor_plan",
+    schemaDocs:
+      "Uses a scoped operation enum with target/file coordinates, optional selected range, and operation-specific options. This is the only intentional operation-style schema.",
+    absorbsTools: [],
+    absorbsBehaviors: [],
+    substrates: ["semantic", "structural", "search"],
+    phase: "phase-5",
+    nonGoals: [
+      "Does not introduce a broad action mega-tool.",
+      "code_refactor_plan is a pure planner; use code_refactor_apply to execute stored plans.",
+    ],
+  },
+  {
+    name: "code_refactor_apply",
+    label: "Code Refactor Apply",
+    parameters: CodeApplyParameters,
+    run: (params, ctx) =>
+      executeRefactorApplyTool(params as Parameters<typeof executeRefactorApplyTool>[0], ctx),
+    purpose: "Apply a previously stored plan through explicit, fingerprint-checked mutation.",
+    schemaKey: "code_refactor_apply",
+    schemaDocs:
+      "Requires a planId. Enforces stale-plan rejection, validation, and fingerprint checks before mutation.",
+    absorbsTools: [],
+    absorbsBehaviors: [],
+    substrates: ["semantic", "search", "git"],
+    phase: "phase-5",
+    nonGoals: [
+      "Does not bypass plan validation or fingerprint checks.",
+      "Format/verify modes are not implemented; they return explicit unavailable outcomes when added later.",
+    ],
+  },
+  {
+    name: "code_health",
+    label: "Code Health",
+    parameters: CodeHealthParameters,
+    run: (params, ctx) => executeHealthTool(params as Parameters<typeof executeHealthTool>[0], ctx),
+    purpose:
+      "Summarize diagnostics, provider state, dirty workspace signals, and maintenance cues from one workflow-oriented health surface.",
+    schemaKey: "code_health",
+    schemaDocs:
+      "Accepts scope, refresh, include sections, and detail level. It is the planned replacement for direct public diagnostic and recovery substrate access.",
+    absorbsTools: ["lsp_diagnostics", "lsp_recover"],
+    absorbsBehaviors: ["ci-status summary"],
+    substrates: ["semantic", "search", "git", "diagnostics"],
+    phase: "phase-6",
+    nonGoals: [
+      "Public lsp_* and tree_sitter_* tools were removed; only code_* tools remain on the public surface.",
+      "Does not act as a generic verification/test runner.",
+    ],
+  },
+] as const satisfies readonly CodeIntelligenceToolDefinitionSpec[];