sift-light 1.0.0

package/src/import-resolution.ts

@@ -0,0 +1,240 @@
+import { posix } from "node:path";
+import { MAX_IMPORT_FILES, MAX_IMPORT_HOPS } from "./analysis-limits.js";
+import { SiftLightError } from "./errors.js";
+import type { SourceReference } from "./source-document.js";
+import {
+  NavigationContext,
+  NavigationFailure,
+  moduleRange,
+  navigationError,
+  nodeLine,
+  nodeText,
+  type ExportBinding,
+  type ImportBinding,
+  type ModuleFacts,
+} from "./import-model.js";
+
+const EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs"];
+/** These are static source candidates, not Node/bundler runtime-resolution claims. */
+export const STATIC_MODULE_RESOLUTION =
+  "Exact relative path; extensionless source and index candidates (.ts/.tsx/.js/.jsx/.mts/.cts/.mjs/.cjs); .js→.ts/.tsx, .jsx→.tsx, .mjs→.mts, .cjs→.cts source candidates. Every existing candidate is considered; multiple candidates are ambiguous. No configuration is executed.";
+
+export interface ImportStep {
+  from: SourceReference;
+  line: number;
+  range: { start: number; end: number };
+  kind: "import" | "re-export" | "local-export";
+  specifier?: string;
+  imported?: string;
+  local?: string;
+  exported?: string;
+  to?: SourceReference;
+  resolution?: string;
+}
+export interface ImportDestination {
+  source: SourceReference;
+  line: number;
+  range: { start: number; end: number };
+  name: string;
+  kind: string;
+}
+export interface ImportTrace {
+  status: "resolved" | "module" | "unresolved";
+  reason?: string;
+  chain: ImportStep[];
+  destination?: ImportDestination;
+  module?: SourceReference;
+  candidates?: string[];
+}
+
+interface Resolution {
+  path?: string;
+  reason?: string;
+  candidates?: string[];
+}
+export async function resolveStaticModule(
+  context: NavigationContext,
+  from: string,
+  specifier: string | undefined,
+): Promise<Resolution> {
+  context.checkAbort();
+  // Navigation hosts can return native relative paths; resolution is always POSIX-based.
+  from = context.normalizePath(from);
+  if (specifier === undefined) return { reason: "nonliteral-module-specifier" };
+  if (!specifier.startsWith("./") && !specifier.startsWith("../"))
+    return { reason: "external-package-or-path-alias-unsupported" };
+  if (specifier.includes("\\") || specifier.includes("\0") || /[?#]/.test(specifier))
+    return { reason: "module-specifier-unsupported" };
+  const joined = posix.normalize(posix.join(posix.dirname(from), specifier));
+  let path: string;
+  try {
+    path = context.normalizePath(joined);
+  } catch (error) {
+    if (error instanceof SiftLightError) return { reason: "outside-workspace" };
+    throw error;
+  }
+  const candidates = new Set([path]);
+  const extension = posix.extname(path);
+  if (!extension) {
+    for (const suffix of EXTENSIONS) {
+      candidates.add(context.normalizePath(`${path}${suffix}`));
+      candidates.add(context.normalizePath(posix.join(path, `index${suffix}`)));
+    }
+  } else {
+    const mappings: Record<string, string[]> = {
+      ".js": [".ts", ".tsx"],
+      ".jsx": [".tsx"],
+      ".mjs": [".mts"],
+      ".cjs": [".cts"],
+    };
+    for (const suffix of mappings[extension] ?? [])
+      candidates.add(context.normalizePath(path.slice(0, -extension.length) + suffix));
+  }
+  const files = await context.files();
+  const existing = [...candidates].filter((candidate) => files.has(candidate)).toSorted();
+  if (existing.length === 0)
+    return { reason: "missing-or-excluded-module", candidates: [...candidates] };
+  if (existing.length > 1) return { reason: "ambiguous-module-candidates", candidates: existing };
+  const unique = existing[0];
+  if (unique === undefined) throw new Error("Missing unique module candidate");
+  return { path: unique };
+}
+
+function declaration(facts: ModuleFacts, node: number, name: string): ImportDestination {
+  return {
+    source: facts.document.reference,
+    line: nodeLine(facts, node),
+    range: moduleRange(facts, node),
+    name,
+    kind: facts.locations.get(node)?.kind ?? "unknown",
+  };
+}
+
+/** One path has its own hop/file budget even when E reuses a larger request context. */
+export async function traceImport(
+  context: NavigationContext,
+  initial: ModuleFacts,
+  binding: ImportBinding | ExportBinding,
+): Promise<ImportTrace> {
+  const chain: ImportStep[] = [];
+  const visited = new Set<string>();
+  const paths = new Set([initial.document.path]);
+  let hops = 0;
+  const unresolved = (reason: string, candidates?: string[]): ImportTrace => ({
+    status: "unresolved",
+    reason,
+    chain,
+    ...(candidates ? { candidates } : {}),
+  });
+  const visit = (facts: ModuleFacts, name: string): void => {
+    const key = JSON.stringify([facts.document.path, name]);
+    if (visited.has(key)) throw new NavigationFailure("circular-re-export");
+    visited.add(key);
+  };
+  const followModule = async (
+    facts: ModuleFacts,
+    source: string | undefined,
+    step: ImportStep,
+  ): Promise<ModuleFacts | ImportTrace> => {
+    if (hops >= MAX_IMPORT_HOPS) return unresolved("hop-budget-exhausted");
+    hops++;
+    chain.push(step);
+    const resolved = await resolveStaticModule(context, facts.document.path, source);
+    if (!resolved.path)
+      return unresolved(resolved.reason ?? "module-unresolved", resolved.candidates);
+    paths.add(resolved.path);
+    if (paths.size > MAX_IMPORT_FILES) return unresolved("file-budget-exhausted");
+    const next = await context.module(resolved.path);
+    step.to = next.document.reference;
+    step.resolution = "static-source-candidates";
+    return next;
+  };
+  const followImport = async (facts: ModuleFacts, current: ImportBinding): Promise<ImportTrace> => {
+    const next = await followModule(facts, current.source, {
+      from: facts.document.reference,
+      line: nodeLine(facts, current.statement),
+      range: moduleRange(facts, current.statement),
+      kind: "import",
+      ...(current.source !== undefined ? { specifier: current.source } : {}),
+      imported: current.imported,
+      ...(current.local !== undefined ? { local: current.local } : {}),
+    });
+    if (!("document" in next)) return next;
+    if (current.kind === "namespace" || current.kind === "side-effect")
+      return { status: "module", chain, module: next.document.reference };
+    return followExportName(next, current.imported);
+  };
+  const followLocal = async (facts: ModuleFacts, name: string): Promise<ImportTrace> => {
+    const imported = facts.imports.filter((current) => current.local === name);
+    const declared = facts.declarations.get(name) ?? [];
+    if (imported.length + declared.length > 1) return unresolved("ambiguous-local-binding");
+    if (imported[0]) return followImport(facts, imported[0]);
+    if (declared[0] !== undefined)
+      return { status: "resolved", chain, destination: declaration(facts, declared[0], name) };
+    return unresolved("local-binding-unresolved");
+  };
+  const followExport = async (facts: ModuleFacts, current: ExportBinding): Promise<ImportTrace> => {
+    if (current.kind === "star") return unresolved("export-star-unsupported");
+    if (current.definition !== undefined)
+      return {
+        status: "resolved",
+        chain,
+        destination: declaration(facts, current.definition, current.exported),
+      };
+    const step: ImportStep = {
+      from: facts.document.reference,
+      line: nodeLine(facts, current.statement),
+      range: moduleRange(facts, current.statement),
+      kind: current.source !== undefined ? "re-export" : "local-export",
+      exported: current.exported,
+      ...(current.local !== undefined ? { local: current.local, imported: current.local } : {}),
+      ...(current.source !== undefined ? { specifier: current.source } : {}),
+    };
+    if (current.source !== undefined) {
+      const next = await followModule(facts, current.source, step);
+      if (!("document" in next)) return next;
+      if (current.kind === "namespace")
+        return { status: "module", chain, module: next.document.reference };
+      if (current.local === undefined) return unresolved("export-binding-unresolved");
+      return followExportName(next, current.local);
+    }
+    chain.push(step);
+    if (current.local === undefined) return unresolved("export-binding-unresolved");
+    return followLocal(facts, current.local);
+  };
+  const followExportName = async (facts: ModuleFacts, name: string): Promise<ImportTrace> => {
+    visit(facts, name);
+    const exported = facts.exports.filter(
+      (current) => current.exported === name && current.kind !== "star",
+    );
+    if (exported.length > 1) return unresolved("ambiguous-export-binding");
+    if (!exported[0])
+      return unresolved(
+        facts.exports.some((current) => current.kind === "star")
+          ? "export-star-unsupported"
+          : "export-not-found",
+      );
+    return followExport(facts, exported[0]);
+  };
+  try {
+    if ("imported" in binding) return await followImport(initial, binding);
+    visit(initial, binding.exported);
+    return await followExport(initial, binding);
+  } catch (error) {
+    const reason = navigationError(error);
+    if (!reason) throw error;
+    return unresolved(reason);
+  }
+}
+
+export function tracePaths(trace: ImportTrace): string[] {
+  const paths = trace.chain.flatMap((step) => [step.from.path, ...(step.to ? [step.to.path] : [])]);
+  if (trace.destination) paths.push(trace.destination.source.path);
+  if (trace.module) paths.push(trace.module.path);
+  return [...new Set(paths)];
+}
+
+export function importStatementExcerpt(facts: ModuleFacts, statement: number): string {
+  const text = nodeText(facts, statement) ?? "";
+  return text.length > 500 ? `${text.slice(0, 500)}… [statement excerpt truncated]` : text;
+}

package/src/index.ts

@@ -0,0 +1,97 @@
+import { SIFT_LIGHT_DESCRIPTION, siftLightSchema } from "./tool-schema.js";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  normalizeSearchEnforcement,
+  readSiftLightConfig,
+  DEFAULT_SEMANTIC_JUDGE_CONFIG,
+  type SiftLightConfig,
+} from "./config.js";
+import { resolveContextBudget } from "./context-budget.js";
+import { createRipgrepRunner } from "./rg.js";
+import { createCtagsStructureProvider } from "./structure.js";
+import { SiftLightRuntime } from "./runtime.js";
+import { SESSION_STATUS_KEY } from "./session-summary.js";
+import { SiftLightService } from "./service.js";
+import { siftLightPromptGuidelines } from "./prompt-guidelines.js";
+import type { SiftLightDetails } from "./types.js";
+import { renderSiftLightCall, renderSiftLightResult } from "./tui/renderers.js";
+import { registerPiSearchPolicy } from "./pi-search-policy.js";
+import { modelErrorText } from "./model-error.js";
+import { createSemanticJudgeIntegration } from "./semantic-judge.js";
+
+const SIFT_LIGHT_LABEL = "sift-light";
+
+export { siftLightPromptGuidelines };
+
+export async function registerSiftLightExtension(
+  pi: ExtensionAPI,
+  config: SiftLightConfig,
+): Promise<void> {
+  const semanticJudge = createSemanticJudgeIntegration(
+    config.semanticJudge ?? DEFAULT_SEMANTIC_JUDGE_CONFIG,
+  );
+  const runtime = new SiftLightRuntime(
+    new SiftLightService({
+      runRipgrep: createRipgrepRunner(),
+      structure: createCtagsStructureProvider(),
+      semanticJudge,
+    }),
+  );
+  const { locale } = config;
+
+  pi.registerTool<typeof siftLightSchema, SiftLightDetails>({
+    name: "sift-light",
+    label: SIFT_LIGHT_LABEL,
+    description: SIFT_LIGHT_DESCRIPTION,
+    promptSnippet: "Search file contents without flooding context",
+    promptGuidelines: siftLightPromptGuidelines(),
+    parameters: siftLightSchema,
+
+    renderCall(params, theme) {
+      return renderSiftLightCall(params, locale, theme);
+    },
+
+    renderResult(result, { expanded, isPartial }, theme, context) {
+      return renderSiftLightResult(
+        result,
+        { expanded, isPartial, isError: context.isError },
+        locale,
+        theme,
+      );
+    },
+
+    async execute(...[_toolCallId, params, signal, _onUpdate, ctx]) {
+      try {
+        const result = await runtime.search(
+          params,
+          ctx.cwd,
+          signal,
+          resolveContextBudget(ctx.getContextUsage()),
+        );
+        ctx.ui.setStatus(SESSION_STATUS_KEY, runtime.formatSessionStatus(locale));
+        return {
+          content: [{ type: "text", text: result.text }],
+          details: result.details,
+        };
+      } catch (error) {
+        if (signal?.aborted) throw error;
+        runtime.recordFailure();
+        ctx.ui.setStatus(SESSION_STATUS_KEY, runtime.formatSessionStatus(locale));
+        // oxlint-disable-next-line preserve-caught-error -- the model boundary must not expose a recursive cause chain
+        throw new Error(modelErrorText(error));
+      }
+    },
+  });
+
+  const enforcement = normalizeSearchEnforcement(config.enforceSearch, "extension config");
+  if (enforcement !== "off") registerPiSearchPolicy(pi, enforcement);
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    await runtime.shutdown();
+    ctx.ui.setStatus(SESSION_STATUS_KEY, undefined);
+  });
+}
+
+export default async function siftLightExtension(pi: ExtensionAPI) {
+  await registerSiftLightExtension(pi, await readSiftLightConfig());
+}

package/src/inspect-batch.ts

@@ -0,0 +1,265 @@
+import { abortError, SiftLightError } from "./errors.js";
+import {
+  inspectionDescription,
+  inspectSourceEvidence,
+  resolveInspectionTarget,
+  sourceExcerptDetails,
+  type InspectionEvidence,
+  type InspectInput,
+  type InspectOptions,
+} from "./inspect.js";
+import {
+  sameSourceRevision,
+  SourceBudgetTooSmallError,
+  SourceLineUnavailableError,
+  type SourceExcerptLine,
+} from "./source.js";
+import {
+  MAX_INSPECT_TARGETS,
+  MAX_LINE_CHARACTERS,
+  MAX_RESULT_BYTES,
+  type InspectBatchItemDetails,
+  type InspectRetry,
+  type InspectTarget,
+  type SiftLightResult,
+  type SourceRevision,
+} from "./types.js";
+
+export interface InspectBatchInput extends InspectInput {
+  matchIndices?: number[];
+  targets?: InspectTarget[];
+}
+
+interface InspectionBlock {
+  path: string;
+  absolutePath: string;
+  revision: SourceRevision;
+  lines: Map<number, SourceExcerptLine>;
+}
+
+function batchInputs(input: InspectBatchInput): InspectInput[] {
+  if (input.path !== undefined || input.line !== undefined || input.matchIndex !== undefined) {
+    throw new SiftLightError("Batch inspection cannot be combined with path, line, or matchIndex");
+  }
+  if (input.matchIndices !== undefined && input.targets !== undefined) {
+    throw new SiftLightError("Use either matchIndices or targets for batch inspection");
+  }
+  const count = input.matchIndices?.length ?? input.targets?.length ?? 0;
+  if (count < 1 || count > MAX_INSPECT_TARGETS) {
+    throw new SiftLightError(`Batch inspection requires 1-${String(MAX_INSPECT_TARGETS)} targets`);
+  }
+  if (input.matchIndices) {
+    const { cursor } = input;
+    if (!cursor) throw new SiftLightError("matchIndices requires a cursor when mode=inspect");
+    return input.matchIndices.map((matchIndex) => ({ cursor, matchIndex }));
+  }
+  if (input.cursor !== undefined) {
+    throw new SiftLightError("targets cannot be combined with a cursor; use matchIndices");
+  }
+  if (!input.targets) throw new SiftLightError("Batch inspection requires targets or matchIndices");
+  return input.targets;
+}
+
+function blockText(block: InspectionBlock, index: number): string {
+  const lines = [...block.lines.values()].toSorted((left, right) => left.line - right.line);
+  const output = [`[Block #${String(index + 1)}] ${block.path}`];
+  let previous: number | undefined;
+  for (const line of lines) {
+    if (previous !== undefined && line.line > previous + 1) {
+      output.push(`… omitted lines ${String(previous + 1)}-${String(line.line - 1)}`);
+    }
+    output.push(`${String(line.line)}: ${line.text}`);
+    previous = line.line;
+  }
+  return output.join("\n");
+}
+
+function batchText(
+  items: InspectBatchItemDetails[],
+  blocks: InspectionBlock[],
+  descriptions: Map<number, string>,
+): string {
+  const returned = items.filter((item) => item.status === "returned").length;
+  const header = `Batch inspection: ${String(returned)} of ${String(items.length)} targets returned (${returned === items.length ? "complete" : "PARTIAL"}); shared ${String(MAX_RESULT_BYTES)}-byte output limit.`;
+  const rows = items.map((item) => {
+    let row = `Target #${String(item.inputIndex)} ${item.path ?? ""}:${String(item.line ?? "")}${item.matchIndex !== undefined ? ` {match #${String(item.matchIndex)}}` : ""}: ${item.status}`;
+    if (item.block !== undefined) row += `; Block #${String(item.block)}`;
+    if (item.structure)
+      row += `; structure=${item.structure.status}${item.structure.provider ? ` via ${item.structure.provider}` : ""}`;
+    const description = descriptions.get(item.inputIndex);
+    if (description) row += `; ${description}`;
+    if (item.error) row += `; ${item.error}`;
+    if (item.source) {
+      row += `; source lines ${String(item.source.range.startLine)}-${String(item.source.range.endLine)}`;
+      if (item.source.omittedBefore > 0 || item.source.omittedAfter > 0) {
+        row += `; omitted ${String(item.source.omittedBefore)} lines before and ${String(item.source.omittedAfter)} after`;
+      }
+      if (item.source.truncatedLines.length > 0) {
+        row += `; line excerpts truncated at ${item.source.truncatedLines.join(",")} (max ${String(MAX_LINE_CHARACTERS)} source characters)`;
+      }
+    }
+    if (item.retry)
+      row += `\nRetry target #${String(item.inputIndex)}: ${JSON.stringify(item.retry)}`;
+    return row;
+  });
+  return [header, ...rows, ...blocks.map(blockText)].join("\n\n");
+}
+
+function addEvidence(
+  blocks: InspectionBlock[],
+  evidence: InspectionEvidence,
+): { blocks: InspectionBlock[]; block: number } {
+  const { source, revision, target } = evidence;
+  if (!source || !revision)
+    throw new Error("Only verified source evidence may enter a batch block");
+  const next = blocks.map((block) => ({ ...block, lines: new Map(block.lines) }));
+  let index = next.findIndex(
+    (block) =>
+      block.absolutePath === target.absolutePath && sameSourceRevision(block.revision, revision),
+  );
+  if (index < 0) {
+    index = next.length;
+    next.push({ path: target.path, absolutePath: target.absolutePath, revision, lines: new Map() });
+  }
+  const block = next[index];
+  if (!block) throw new Error("Batch block is unavailable");
+  for (const line of source.lines) {
+    const previous = block.lines.get(line.line);
+    if (previous && previous.text !== line.text) {
+      // A focused excerpt and a neighboring context excerpt can show different
+      // portions of the same long line. Keep the target's focused excerpt.
+      if (line.line !== target.line) continue;
+    }
+    block.lines.set(line.line, line);
+  }
+  return { blocks: next, block: index + 1 };
+}
+
+export async function inspectSourceBatch(
+  input: InspectBatchInput,
+  cwd: string,
+  signal: AbortSignal | undefined,
+  options: InspectOptions,
+): Promise<SiftLightResult> {
+  if (signal?.aborted) throw abortError();
+  const inputs = batchInputs(input);
+  const targets = inputs.map((item) => resolveInspectionTarget(item, cwd, options.snapshots));
+  const retries: InspectRetry[] = inputs.map((item) => ({ mode: "inspect", ...item }));
+  const items: InspectBatchItemDetails[] = targets.map((target, index) => ({
+    inputIndex: index + 1,
+    path: target.path,
+    line: target.line,
+    ...(inputs[index]?.matchIndex !== undefined ? { matchIndex: inputs[index]?.matchIndex } : {}),
+    status: "deferred",
+    error: "not returned within the shared byte budget",
+    ...(retries[index] ? { retry: retries[index] } : {}),
+  }));
+  const descriptions = new Map<number, string>();
+  let blocks: InspectionBlock[] = [];
+  const initialBytes = Buffer.byteLength(batchText(items, blocks, descriptions));
+  if (initialBytes + 512 > MAX_RESULT_BYTES) {
+    throw new SiftLightError(
+      "Batch target metadata exceeds the result byte budget; inspect fewer targets",
+    );
+  }
+
+  for (const [index, target] of targets.entries()) {
+    if (signal?.aborted) throw abortError();
+    const previous = items[index];
+    if (!previous) throw new Error("Batch item is unavailable");
+    const remaining = MAX_RESULT_BYTES - Buffer.byteLength(batchText(items, blocks, descriptions));
+    const maxSourceBytes = Math.floor((remaining - 512) / (targets.length - index)) - 512;
+    if (maxSourceBytes <= 0) continue;
+    let evidence: InspectionEvidence;
+    try {
+      // Each target consumes part of the same output budget. Sequential reads
+      // also give cancellation one owner and do not fan out child processes.
+      // oxlint-disable-next-line no-await-in-loop -- shared batch output budget.
+      evidence = await inspectSourceEvidence(target, cwd, signal, options, maxSourceBytes);
+    } catch (error) {
+      if (signal?.aborted || (error instanceof Error && error.name === "AbortError"))
+        throw abortError();
+      if (error instanceof SourceBudgetTooSmallError) continue;
+      if (!(error instanceof SourceLineUnavailableError)) throw error;
+      items[index] = { ...previous, status: "error", error: error.message };
+      delete items[index]?.retry;
+      continue;
+    }
+    if (!evidence.source) {
+      items[index] = {
+        inputIndex: previous.inputIndex,
+        path: target.path,
+        line: target.line,
+        ...(previous.matchIndex !== undefined ? { matchIndex: previous.matchIndex } : {}),
+        status: "error",
+        structure: evidence.structure,
+        error: `${evidence.structure.status}; ${target.retainedMatch ? "refresh the search before inspecting this match" : "source evidence is unavailable"}`,
+      };
+      continue;
+    }
+    const sourceRevision = evidence.revision;
+    if (
+      sourceRevision &&
+      blocks.some(
+        (block) =>
+          block.absolutePath === target.absolutePath &&
+          !sameSourceRevision(block.revision, sourceRevision),
+      )
+    ) {
+      items[index] = {
+        inputIndex: previous.inputIndex,
+        path: target.path,
+        line: target.line,
+        ...(previous.matchIndex !== undefined ? { matchIndex: previous.matchIndex } : {}),
+        status: "error",
+        structure: { status: "source-changed" },
+        error: "source-changed during batch inspection; refresh the source before retrying",
+      };
+      continue;
+    }
+    const candidate = addEvidence(blocks, evidence);
+    const source = sourceExcerptDetails(evidence.source);
+    items[index] = {
+      inputIndex: previous.inputIndex,
+      path: target.path,
+      line: target.line,
+      ...(previous.matchIndex !== undefined ? { matchIndex: previous.matchIndex } : {}),
+      status: "returned",
+      block: candidate.block,
+      structure: evidence.structure,
+      source,
+      ...((source.omittedBefore > 0 || source.omittedAfter > 0) && retries[index]
+        ? { retry: retries[index] }
+        : {}),
+    };
+    descriptions.set(index + 1, inspectionDescription(evidence));
+    if (Buffer.byteLength(batchText(items, candidate.blocks, descriptions)) > MAX_RESULT_BYTES) {
+      items[index] = previous;
+      descriptions.delete(index + 1);
+    } else {
+      blocks = candidate.blocks;
+    }
+  }
+  if (signal?.aborted) throw abortError();
+  const text = batchText(items, blocks, descriptions);
+  if (Buffer.byteLength(text) > MAX_RESULT_BYTES) {
+    throw new SiftLightError(
+      "Batch result metadata exceeds the byte budget; inspect fewer targets",
+    );
+  }
+  const complete = items.every((item) => item.status === "returned");
+  return {
+    text,
+    details: {
+      version: 1,
+      mode: "inspect",
+      status: complete ? "complete" : "partial",
+      snapshotComplete: complete,
+      totalMatches: 0,
+      storedMatches: 0,
+      totalFiles: new Set(targets.map((target) => target.absolutePath)).size,
+      returnedMatches: blocks.reduce((total, block) => total + block.lines.size, 0),
+      inspections: items,
+    },
+  };
+}