@mrclrchtr/supi-code-intelligence 3.2.0 → 4.0.0

package/src/tool/infra/cross-field.ts

@@ -1,335 +0,0 @@
-/**
- * Cross-field validation rules for tool parameters.
- *
- * pi validates structural types, required fields, and enum values against
- * the TypeBox schemas in ./schemas.ts before calling tool executors. These
- * composable rules cover constraints that TypeBox cannot express:
- *
- * - Cross-field requirements (e.g. "query OR file required")
- * - Filesystem checks (e.g. "file exists and is not a directory")
- * - Semantic consistency (e.g. "kind only valid with mode: ast")
- *
- * TypeBox already enforces, and rules here must NOT duplicate:
- * - Required vs optional fields
- * - Enum value membership (StringEnum)
- * - Number ranges (minimum/maximum)
- * - additionalProperties: false
- */
-
-import { existsSync, statSync } from "node:fs";
-import { normalizePath } from "../../analysis/search/ripgrep.ts";
-import { inspectParam } from "./pipeline.ts";
-
-/** A cross-field validation rule. Returns an error message string or null if valid. */
-export type CrossFieldRule<P> = (params: P, cwd: string) => string | null;
-
-/** Compose multiple cross-field rules — stops at the first error. */
-export function composeRules<P>(...rules: CrossFieldRule<P>[]): CrossFieldRule<P> {
-  return (params, cwd) => {
-    for (const rule of rules) {
-      const error = rule(params, cwd);
-      if (error) return error;
-    }
-    return null;
-  };
-}
-
-// ── Primitives ────────────────────────────────────────────────────────
-
-/**
- * Require at least one of the named keys to be present and non-empty.
- * A key is "present" when its value is not undefined, null, or empty-string.
- */
-export function requireAtLeastOne<P>(...keys: (keyof P & string)[]): CrossFieldRule<P> {
-  return (params) => {
-    const present = keys.filter((k) => {
-      const v = inspectParam(params, k);
-      return v !== undefined && v !== null && (typeof v !== "string" || v.length > 0);
-    });
-    if (present.length === 0) {
-      const names = keys.map((k) => `\`${k}\``).join(" or ");
-      return `**Error:** At least one of ${names} is required.`;
-    }
-    return null;
-  };
-}
-
-/**
- * Require that the named keys appear together — all present or all absent.
- * A key is "present" when its value is not undefined or null.
- */
-export function requirePaired<P>(...keys: (keyof P & string)[]): CrossFieldRule<P> {
-  return (params) => {
-    const present = keys.map(
-      (k) => inspectParam(params, k) !== undefined && inspectParam(params, k) !== null,
-    );
-    const allPresent = present.every(Boolean);
-    const allAbsent = present.every((p) => !p);
-    if (!allPresent && !allAbsent) {
-      const names = keys.map((k) => `\`${k}\``).join(" and ");
-      return `**Error:** ${names} must be provided together.`;
-    }
-    return null;
-  };
-}
-
-/**
- * Require that when any of `dependentKeys` is present, `requiredKey` must
- * also be present.
- */
-export function requireWith<P>(
-  requiredKey: keyof P & string,
-  ...dependentKeys: (keyof P & string)[]
-): CrossFieldRule<P> {
-  return (params) => {
-    const needed = dependentKeys.some(
-      (k) => inspectParam(params, k) !== undefined && inspectParam(params, k) !== null,
-    );
-    if (
-      needed &&
-      (inspectParam(params, requiredKey) === undefined ||
-        inspectParam(params, requiredKey) === null)
-    ) {
-      const depNames = dependentKeys.map((k) => `\`${k}\``).join(" or ");
-      return `**Error:** ${depNames} requires \`${requiredKey}\`.`;
-    }
-    return null;
-  };
-}
-
-/**
- * Reject when any of `positionKeys` are present alongside `pathKey`.
- * Positions (line/character) only anchor into files, not scope/path params.
- */
-export function noPositionOnPath<P>(
-  pathKey: keyof P & string,
-  lineKey: keyof P & string,
-  charKey: keyof P & string,
-): CrossFieldRule<P> {
-  return (params) => {
-    const hasPath = inspectParam(params, pathKey) !== undefined;
-    const hasPos =
-      inspectParam(params, lineKey) !== undefined || inspectParam(params, charKey) !== undefined;
-    if (hasPath && hasPos) {
-      return `**Error:** \`${lineKey}\` and \`${charKey}\` require \`file\`, not \`${pathKey}\`. Use \`${pathKey}\` to scope; use \`file\` to anchor a position.`;
-    }
-    return null;
-  };
-}
-
-// ── Filesystem primitives ─────────────────────────────────────────────
-
-/** Ensure the value at `key` resolves to an existing file. */
-export function fileMustExist<P>(key: keyof P & string): CrossFieldRule<P> {
-  return (params, cwd) => {
-    const file = inspectParam(params, key) as string | undefined;
-    if (!file) return null;
-    const resolved = normalizePath(file, cwd);
-    if (!existsSync(resolved)) {
-      return `**Error:** File not found: \`${file}\`.`;
-    }
-    return null;
-  };
-}
-
-/** Ensure the value at `key` resolves to a file, not a directory. */
-export function fileNotDirectory<P>(key: keyof P & string): CrossFieldRule<P> {
-  return (params, cwd) => {
-    const file = inspectParam(params, key) as string | undefined;
-    if (!file) return null;
-    const resolved = normalizePath(file, cwd);
-    if (existsSync(resolved) && statSync(resolved).isDirectory()) {
-      return `**Error:** \`${key}\` points to a directory. Use \`scope\` for a directory; use \`file\` to anchor a position in a file.`;
-    }
-    return null;
-  };
-}
-
-// ── Tool-specific composed rules ──────────────────────────────────────
-
-/**
- * Standard cross-field rules for tools that accept anchored coordinates
- * (file + line + character). Used by code_graph, code_impact, code_inspect,
- * and any future tool that takes position params.
- *
- * TypeBox already enforces:
- * - Types: file (String), line (Number >= 1), character (Number >= 1)
- * - additionalProperties: false
- */
-export function focusedToolRules<P>(
-  pathKey: keyof P & string = "scope" as keyof P & string,
-): CrossFieldRule<P> {
-  return composeRules<P>(
-    noPositionOnPath(pathKey, "line" as keyof P & string, "character" as keyof P & string),
-    fileNotDirectory("file" as keyof P & string),
-    requireWith(
-      "file" as keyof P & string,
-      "line" as keyof P & string,
-      "character" as keyof P & string,
-    ),
-  );
-}
-
-/**
- * Cross-field rules for code_resolve.
- *
- * TypeBox already enforces:
- * - kind must be a valid StringEnum value
- * - line/character must be numbers >= 1
- * - additionalProperties: false
- */
-export const resolveCrossFieldRules: CrossFieldRule<{
-  query?: string;
-  file?: string;
-  line?: number;
-  character?: number;
-}> = composeRules(
-  requireAtLeastOne("query", "file"),
-  requirePaired("line", "character"),
-  requireWith("file", "line", "character"),
-);
-
-/**
- * Cross-field rules for code_orientation coordinate mode
- * (focus + line + character).
- *
- * TypeBox already enforces:
- * - line/character types and min >= 1
- * - additionalProperties: false
- */
-export function orientationCoordinateRules<
-  P extends {
-    focus?: string;
-    line?: number;
-    character?: number;
-  },
->(): CrossFieldRule<P> {
-  return composeRules<P>(
-    requirePaired(
-      "focus" as keyof P & string,
-      "line" as keyof P & string,
-      "character" as keyof P & string,
-    ),
-    fileMustExist("focus" as keyof P & string),
-    fileNotDirectory("focus" as keyof P & string),
-  );
-}
-
-/**
- * Cross-field rules for code_find mode+kind consistency.
- *
- * TypeBox already enforces:
- * - mode must be a valid StringEnum value
- * - kind must be a valid StringEnum value
- * - query is required (not optional)
- */
-const SUPPORTED_AST_KINDS = [
-  "definition",
-  "import",
-  "export",
-  "call",
-  "type",
-  "interface",
-  "class",
-  "method",
-  "enum",
-  "test",
-] as const;
-
-const SUPPORTED_AST_KINDS_TEXT = SUPPORTED_AST_KINDS.map((k) => `\`${k}\``).join(", ");
-
-export function findModeKindRules<P extends { mode?: string; kind?: string }>(): CrossFieldRule<P> {
-  return (params) => {
-    const mode = params.mode ?? "text";
-    const kind = params.kind;
-    if ((mode === "text" || mode === "regex" || mode === "semantic") && kind) {
-      return `**Error:** code_find does not accept \`kind\` with \`mode: "${mode}"\`. Use \`mode: "ast"\` with \`kind\`.`;
-    }
-    if (mode === "ast" && !kind) {
-      return `**Error:** code_find with \`mode: "ast"\` requires \`kind\`. Supported AST kinds: ${SUPPORTED_AST_KINDS_TEXT}.`;
-    }
-    return null;
-  };
-}
-
-/**
- * Cross-field rules for code_refactor_plan.
- *
- * TypeBox already enforces:
- * - operation must be a valid StringEnum value
- * - range shape (start/end with line/character)
- * - additionalProperties: false
- */
-// ── Refactor plan sub-rules (split for complexity) ────────────────────
-
-function checkExtractRange<
-  P extends {
-    operation: string;
-    range?: {
-      start: { line: number; character: number };
-      end: { line: number; character: number };
-    };
-  },
->(params: P): string | null {
-  const isExtract =
-    params.operation === "extract_function" || params.operation === "extract_variable";
-  if (!isExtract) return null;
-  if (!params.range) {
-    return "**Error:** `range` is required for `extract_function` and `extract_variable`.";
-  }
-  const { start, end } = params.range;
-  if (end.line < start.line || (end.line === start.line && end.character <= start.character)) {
-    return "**Error:** `range.end` must be after `range.start`.";
-  }
-  return null;
-}
-
-function checkNewNameRequired<P extends { operation: string; newName?: string }>(
-  params: P,
-): string | null {
-  const needsName =
-    params.operation === "rename_symbol" ||
-    params.operation === "extract_function" ||
-    params.operation === "extract_variable";
-  if (needsName && !params.newName) {
-    return `**Error:** \`newName\` is required for \`${params.operation}\`.`;
-  }
-  return null;
-}
-
-/**
- * Cross-field rules for code_refactor_plan.
- *
- * TypeBox already enforces:
- * - operation must be a valid StringEnum value
- * - range shape (start/end with line/character)
- * - additionalProperties: false
- */
-export function refactorPlanCrossFieldRules<
-  P extends {
-    operation: string;
-    targetId?: string;
-    file?: string;
-    line?: number;
-    character?: number;
-    range?: {
-      start: { line: number; character: number };
-      end: { line: number; character: number };
-    };
-    newName?: string;
-  },
->(): CrossFieldRule<P> {
-  return composeRules<P>(
-    (params) => {
-      const hasTarget =
-        Boolean(params.targetId) ||
-        (Boolean(params.file) && params.line != null && params.character != null);
-      if (!hasTarget) {
-        return "**Error:** Refactor preview requires `targetId` (from `code_resolve`) or `file` + `line` + `character`.";
-      }
-      return null;
-    },
-    checkExtractRange as CrossFieldRule<P>,
-    checkNewNameRequired as CrossFieldRule<P>,
-  );
-}

package/src/tool/infra/pipeline.ts

@@ -1,334 +0,0 @@
-/**
- * Lightweight tool-execution pipeline.
- *
- * Executors compose stages that gate before the tool-specific logic:
- * targetId expansion, scope resolution, param validation, semantic
- * readiness, and capability checks. Each stage returns a
- * {@link PipeOutcome}: `{ kind: "continue" }` to proceed to the next
- * stage, or `{ kind: "error", result }` to short-circuit the pipeline.
- *
- * Usage in an executor:
- *
- * ```ts
- * return runPipe(params, ctx, [
- *   expandTargetId((msg) => ({ content: msg, details: ... })),
- *   resolveScopeParam((reason) => ({ content: reason, details: ... })),
- *   validateParams(myValidator, (msg) => ({ content: msg, details: ... })),
- *   gateSemanticReadiness("code_graph"),
- * ], async (p, c) => {
- *   // tool-specific execution
- * });
- * ```
- */
-
-import { match } from "ts-pattern";
-import { ensureSemanticReadiness } from "../../analysis/readiness.ts";
-import { resolveScope, resolveScopeSet } from "../../analysis/search/ripgrep.ts";
-import { routeFor } from "../../analysis/target/planner.ts";
-import type {
-  CodeIntelligenceToolName,
-  CodeIntelResult,
-  CodeIntelToolExecCtx,
-} from "../../types/index.ts";
-import { searchErrorResult } from "./error-results.ts";
-import { renderSemanticReadinessTimeout } from "./readiness-message.ts";
-
-// Re-export for stage consumers
-export type { CodeIntelligenceToolName };
-
-// ── Param accessors ──────────────────────────────────────────────────
-
-/**
- * Read a param value for runtime inspection in generic pipeline stages
- * and cross-field validation rules.
- *
- * Centralizes the {@link Record}<string, unknown> cast needed when
- * generic code accesses params by dynamic/computed keys. Callers get
- * `unknown` back and must narrow to the expected type.
- */
-export function inspectParam<P>(params: P, key: keyof P & string): unknown {
-  return (params as Record<string, unknown>)[key];
-}
-
-/**
- * Set a param value in generic pipeline code.
- *
- * Companion to {@link inspectParam} for mutation stages like
- * {@link expandTargetId} and {@link resolveScopeParam}.
- */
-export function setParam<P>(params: P, key: keyof P & string, value: unknown): void {
-  (params as Record<string, unknown>)[key] = value;
-}
-
-// ── Types ─────────────────────────────────────────────────────────────
-
-/**
- * Outcome of a single pipeline stage.
- *
- * `continue` — proceed to the next stage (or the execute function).
- * `error`    — short-circuit the pipeline with the given result.
- */
-export type PipeOutcome = { kind: "continue" } | { kind: "error"; result: CodeIntelResult };
-
-/**
- * A pipeline stage: receives (possibly mutated) params and the execution
- * context. Returns {@link PipeOutcome} — `{ kind: "continue" }` to
- * advance to the next stage, or `{ kind: "error", result }` to
- * short-circuit immediately.
- */
-export type PipeStage<P> = (
-  params: P,
-  ctx: CodeIntelToolExecCtx,
-) => Promise<PipeOutcome> | PipeOutcome;
-
-// ── Orchestrator ──────────────────────────────────────────────────────
-
-/**
- * Run a sequence of gating stages then the tool-specific execute function.
- *
- * Stages are executed in order. The first stage that returns
- * `{ kind: "error" }` short-circuits the pipeline and its result is
- * returned to the caller. If every stage returns `{ kind: "continue" }`,
- * `execute(params, ctx)` runs.
- */
-export async function runPipe<P>(
-  params: P,
-  ctx: CodeIntelToolExecCtx,
-  stages: PipeStage<P>[],
-  execute: (params: P, ctx: CodeIntelToolExecCtx) => Promise<CodeIntelResult>,
-): Promise<CodeIntelResult> {
-  for (const stage of stages) {
-    const outcome = await stage(params, ctx);
-    if (outcome.kind === "error") return outcome.result;
-  }
-  return execute(params, ctx);
-}
-
-// ── Stage factories ───────────────────────────────────────────────────
-
-/** Minimum parameter shape needed by `expandTargetId`. */
-export interface HasTargetParams {
-  targetId?: string;
-  file?: string;
-  line?: number;
-  character?: number;
-  /** Set by expandTargetId stage — resolved name from the stored target entry. */
-  _expandedName?: string | null;
-  /** Set by expandTargetId stage — anchor kind from the stored target entry. */
-  _expandedAnchorKind?: string | null;
-}
-
-/**
- * Expand an optional `targetId` into file/line/character params.
- *
- * On success the stage mutates `params.file`, `params.line`, and
- * `params.character` from the stored entry. On error it calls
- * `onError(message)` to build a tool-appropriate error result.
- *
- * A missing/null targetId is not an error — the stage passes through
- * (no expansion, params unchanged).
- */
-export function expandTargetId<P extends HasTargetParams>(
-  onError: (message: string) => CodeIntelResult,
-): PipeStage<P> {
-  return (params, ctx) => {
-    const expansion = ctx.session.expandTargetId(params);
-    if (expansion.kind === "error") return { kind: "error", result: onError(expansion.message) };
-    if (expansion.kind === "ok") {
-      params.file = expansion.file;
-      params.line = expansion.line;
-      params.character = expansion.character;
-      params._expandedName = expansion.targetName;
-      params._expandedAnchorKind = expansion.entry.anchorKind;
-    }
-    return { kind: "continue" };
-  };
-}
-
-/** Minimum parameter shape needed by `resolveScope`. */
-export interface HasScopeParam {
-  scope?: string;
-}
-
-/** Minimum parameter shape needed by `resolveScopeSetParam`. */
-export interface HasScopeSetParam {
-  scope?: string | string[];
-  /** Set by resolveScopeSetParam — absolute search roots for code_find. */
-  _resolvedScopePaths?: string[];
-  /** Set by resolveScopeSetParam — display label for requested search roots. */
-  _resolvedScopeDisplay?: string | null;
-}
-
-/**
- * Resolve the `scope` parameter to an absolute path.
- *
- * Mutates `params.scope` to the resolved absolute path. An undefined
- * scope passes through unchanged. On resolution error calls
- * `onError(reason)`.
- *
- * @param paramName — defaults to `"scope"`.
- */
-export function resolveScopeParam<P extends HasScopeParam>(
-  onError: (reason: string) => CodeIntelResult,
-  paramName: keyof P & string = "scope" as keyof P & string,
-): PipeStage<P> {
-  return (params, ctx) => {
-    const raw = inspectParam(params, paramName) as string | undefined;
-    if (raw === undefined) return { kind: "continue" };
-
-    const result = resolveScope(raw, ctx.cwd);
-    if (result.kind === "error") return { kind: "error", result: onError(result.reason) };
-
-    setParam(params, paramName, result.path);
-    return { kind: "continue" };
-  };
-}
-
-/** Resolve code_find's one-or-many `scope` input to absolute search roots. */
-export function resolveScopeSetParam<P extends HasScopeSetParam>(
-  onError: (reason: string) => CodeIntelResult,
-): PipeStage<P> {
-  return (params, ctx) => {
-    const result = resolveScopeSet(params.scope, ctx.cwd);
-    if (result.kind === "error") return { kind: "error", result: onError(result.reason) };
-
-    params._resolvedScopePaths = [...result.paths];
-    params._resolvedScopeDisplay = result.display;
-    return { kind: "continue" };
-  };
-}
-
-/**
- * Apply cross-field validation rules after TypeBox schema validation.
- *
- * pi already validates structural types, required fields, and enum
- * values against the TypeBox schema in {@link ./schemas.ts} before
- * calling executors. This stage handles only cross-field constraints
- * that TypeBox cannot express (pairing, mutual exclusion, filesystem
- * checks, semantic consistency).
- *
- * The validator receives `(params, cwd)` and returns `null` when
- * valid, or an error message string. The stage calls `onError(message)`
- * to build a tool-appropriate error result.
- */
-export function validateParams<P>(
-  validator: (params: P, cwd: string) => string | null,
-  onError: (message: string) => CodeIntelResult,
-): PipeStage<P> {
-  return (params, ctx) => {
-    const message = validator(params, ctx.cwd);
-    if (message) return { kind: "error", result: onError(message) };
-    return { kind: "continue" };
-  };
-}
-
-/** Options for {@link gateSemanticReadiness}. */
-export interface SemanticGateOptions {
-  /**
-   * Optional param key for the file path used for file-scoped readiness.
-   * When provided, readiness waits for the specific file. Defaults to
-   * workspace-scoped readiness.
-   */
-  fileParam?: string;
-
-  /** Build a result when readiness times out. */
-  onTimeout?: (toolName: string, timeoutMs: number) => CodeIntelResult;
-
-  /** When true, throw (whole-tool unavailable) instead of returning an error result. */
-  throwOnUnavailable?: boolean;
-
-  /**
-   * When true, let "unavailable" pass through to the execute function
-   * instead of returning an error. Use when the use-case layer handles
-   * missing providers with explicit unavailable-section notes.
-   * `throwOnUnavailable` takes precedence when both are true.
-   */
-  passThroughOnUnavailable?: boolean;
-
-  /** Build a result when readiness is permanently unavailable. */
-  onUnavailable?: (reason: string) => CodeIntelResult;
-}
-
-/**
- * Gate execution behind semantic (LSP) readiness.
- *
- * Waits up to the default timeout for the LSP to be ready for the
- * workspace (or a specific file). On timeout, calls `onTimeout` if
- * provided, otherwise builds a default timeout result. When
- * `throwOnUnavailable` is true and the provider is permanently
- * unavailable, the stage throws so pi marks the call as an error.
- */
-export function gateSemanticReadiness<P>(
-  toolName: CodeIntelligenceToolName,
-  opts: SemanticGateOptions = {},
-): PipeStage<P> {
-  return async (params, ctx) => {
-    // opts.fileParam is a runtime string from an options bag, not a
-    // compile-time keyof P — keep the cast local instead of routing
-    // through inspectParam which requires keyof P & string.
-    const file = opts.fileParam
-      ? ((params as Record<string, unknown>)[opts.fileParam] as string | undefined)
-      : undefined;
-
-    const scope = file ? { kind: "file" as const, file } : { kind: "workspace" as const };
-    const readiness = await ensureSemanticReadiness(ctx.cwd, scope);
-
-    if (readiness.kind === "ready") return { kind: "continue" };
-
-    return handleNonReadyReadiness(readiness, toolName, opts);
-  };
-}
-
-/** Handle timeout or unavailable readiness, applying tool-specific callbacks. */
-function handleNonReadyReadiness(
-  readiness: { kind: "timeout" } | { kind: "unavailable"; reason: string },
-  toolName: CodeIntelligenceToolName,
-  opts: SemanticGateOptions,
-): PipeOutcome {
-  return match(readiness)
-    .with({ kind: "timeout" }, () => {
-      if (opts.onTimeout)
-        return { kind: "error" as const, result: opts.onTimeout(toolName, 15_000) };
-      return defaultTimeoutOutcome(toolName);
-    })
-    .with({ kind: "unavailable" }, ({ reason }) => {
-      if (opts.throwOnUnavailable) throw new Error(reason);
-      if (opts.passThroughOnUnavailable) return { kind: "continue" as const };
-      if (opts.onUnavailable) return { kind: "error" as const, result: opts.onUnavailable(reason) };
-      return defaultUnavailableOutcome(reason);
-    })
-    .exhaustive() as PipeOutcome;
-}
-
-function defaultTimeoutOutcome(toolName: string): PipeOutcome {
-  return {
-    kind: "error",
-    result: searchErrorResult(renderSemanticReadinessTimeout(toolName, 15_000)),
-  };
-}
-
-function defaultUnavailableOutcome(reason: string): PipeOutcome {
-  return { kind: "error", result: searchErrorResult(`**Error:** ${reason}`) };
-}
-
-/**
- * Gate execution behind capability availability.
- *
- * Calls `routeFor(cwd, toolName)`. When `preferred === "unavailable"`
- * the stage throws (whole-tool capability-unavailable) so pi marks the
- * call as an error. Partial per-relation unavailability is NOT gated
- * here — executors surface that through best-effort notes.
- *
- * This is a sync stage — no async work.
- */
-export function gateCapability<P>(toolName: CodeIntelligenceToolName): PipeStage<P> {
-  return (_params, ctx) => {
-    const route = routeFor(ctx.cwd, toolName);
-    if (route.preferred === "unavailable") {
-      throw new Error(
-        `No analysis provider is available for this workspace. Check \`code_health\` for LSP and tree-sitter status.`,
-      );
-    }
-    return { kind: "continue" };
-  };
-}

package/src/tool/infra/readiness-message.ts

@@ -1,5 +0,0 @@
-/** Render user-facing semantic readiness messages for tool executors. */
-export function renderSemanticReadinessTimeout(toolName: string, timeoutMs: number): string {
-  const seconds = Math.max(1, Math.round(timeoutMs / 1000));
-  return `**Error:** Semantic analysis for \`${toolName}\` is still warming for this workspace (LSP indexing/startup not finished after ${seconds}s). Try again shortly or check \`code_health\`.`;
-}