sift-light 1.0.0

package/src/tui/renderers.ts

@@ -0,0 +1,106 @@
+import { type Component } from "@earendil-works/pi-tui";
+import type { SiftLightLocale } from "../config.js";
+import type { SiftLightInput } from "../service.js";
+import type { SiftLightDetails } from "../types.js";
+import { dashboard } from "./dashboard.js";
+import { fit, renderDashboard, renderSiftLightCallLines, type SiftLightTheme } from "./layout.js";
+
+export interface SiftLightToolResult {
+  content: { type: string; text?: string }[];
+  details?: SiftLightDetails;
+  isError?: boolean;
+}
+export interface SiftLightRenderOptions {
+  expanded: boolean;
+  isError: boolean;
+  isPartial: boolean;
+}
+
+function component(render: (width: number) => string[], locale: SiftLightLocale): Component {
+  return {
+    render(width) {
+      try {
+        return render(width);
+      } catch {
+        return fit(
+          [locale === "zh-CN" ? "结果显示失败，请重试" : "Result display failed; retry"],
+          width,
+        );
+      }
+    },
+    invalidate() {},
+  };
+}
+
+function failure(text: string, locale: SiftLightLocale): string {
+  const zh = locale === "zh-CN";
+  if (/expired|cursor.*invalid/i.test(text))
+    return zh ? "结果已过期，请重新搜索" : "Results expired; run the search again";
+  if (/permission|access denied|EACCES/i.test(text))
+    return zh ? "无法访问文件，请检查权限" : "Cannot access files; check permissions";
+  if (/not found|ENOENT/i.test(text))
+    return zh ? "未找到目标，请检查文件路径" : "Target not found; check the file path";
+  if (/cancel/i.test(text)) return zh ? "搜索已取消" : "Search cancelled";
+  if (/timeout|deadline/i.test(text))
+    return zh ? "搜索超时，请缩小范围重试" : "Search timed out; narrow the search";
+  return zh ? "搜索未完成，请检查搜索条件后重试" : "Search failed; check the query and retry";
+}
+
+export function renderSiftLightCall(
+  input: SiftLightInput,
+  locale: SiftLightLocale,
+  theme: SiftLightTheme,
+): Component {
+  return component((width) => renderSiftLightCallLines(input, locale, theme, width), locale);
+}
+
+export function renderSiftLightResult(
+  result: SiftLightToolResult,
+  options: SiftLightRenderOptions,
+  locale: SiftLightLocale,
+  theme: SiftLightTheme,
+): Component {
+  return component((width) => {
+    const zh = locale === "zh-CN";
+    const text = result.content
+      .filter((item) => item.type === "text")
+      .map((item) => item.text ?? "")
+      .join("\n");
+    const state = result.details?.operation?.state ?? result.details?.status;
+    if (
+      options.isError ||
+      result.isError ||
+      state === "failed" ||
+      state === "cancelled" ||
+      state === "expired"
+    ) {
+      return fit(
+        [
+          theme.fg("error", zh ? "! 搜索未完成" : "! Search incomplete"),
+          failure(state === "cancelled" || state === "expired" ? state : text, locale),
+        ],
+        width,
+      );
+    }
+    if (options.isPartial || state === "running" || state === "waiting") {
+      // The worker reports phase-local counts, not an overall completion percentage.
+      return fit(
+        [
+          theme.fg("accent", zh ? "◌ 正在搜索…" : "◌ Searching…"),
+          theme.fg("muted", zh ? "等待搜索结果" : "Waiting for results"),
+        ],
+        width,
+      );
+    }
+    const view = dashboard(text, result.details);
+    if (!view)
+      return fit(
+        [
+          theme.fg("warning", zh ? "无法展示结果统计" : "Result statistics unavailable"),
+          theme.fg("muted", zh ? "请重试搜索" : "Retry the search"),
+        ],
+        width,
+      );
+    return renderDashboard(view, locale, theme, width, options.expanded);
+  }, locale);
+}

package/src/types.ts

@@ -0,0 +1,368 @@
+import type { AnalysisDetails } from "./analysis-types.js";
+import type { ValidationDetails } from "./validation-types.js";
+import type { SourceFragment } from "./source-pages.js";
+import type { ByteRange, SourceReference } from "./source-document.js";
+import type { SiftLightInput } from "./service.js";
+import type { OperationProgress } from "./operation-lifecycle.js";
+import type { RequestContractDetails } from "./request-contract.js";
+import type { LanguageCapabilityInventory } from "./language-capabilities.js";
+
+export const DEFAULT_PAGE_SIZE = 100;
+export const MAX_PAGE_SIZE = 100;
+export const DEFAULT_RESULT_TOKEN_BUDGET = 2_000;
+export const CONTEXT_BUDGET_POLICY = {
+  fullAboveRemainderPercent: 40,
+  criticalBelowRemainderPercent: 12,
+  resultTokenBudgets: {
+    full: DEFAULT_RESULT_TOKEN_BUDGET,
+    tight: 1_000,
+    critical: 500,
+  },
+} as const;
+export const ESTIMATED_CHARACTERS_PER_TOKEN = 4;
+export const DEFAULT_SUMMARY_FILE_LIMIT = 30;
+export const MAX_SELECTED_PATHS = 20;
+export const MAX_INSPECT_TARGETS = 5;
+export const MAX_DISPLAYED_OCCURRENCES = 20;
+export const MAX_STORED_MATCHES = 50_000;
+export const MAX_STORED_OCCURRENCES = 200_000;
+export const MAX_SEARCH_STORAGE_BYTES = 32 * 1024 * 1024;
+export const MAX_LINE_CHARACTERS = 500;
+export const MAX_RESULT_BYTES = 16 * 1024;
+export const MAX_CONTEXT_LINES = 20;
+export const MAX_PROTOCOL_LINE_BYTES = 16 * 1024 * 1024;
+export const MAX_SOURCE_FILE_BYTES = 5 * 1024 * 1024;
+export const MAX_PATH_CHARACTERS = 4_096;
+export const MAX_PATTERN_CHARACTERS = 64 * 1024;
+export const MAX_AUDIT_LITERAL_CHARACTERS = 256;
+export const MAX_FILE_FILTER_ITEMS = 64;
+export const MAX_SOURCE_REVISION_CONCURRENCY = 16;
+export const MAX_SOURCE_REVISION_FILES = 50_000;
+
+export type SearchMode =
+  | "audit"
+  | "concept"
+  | "hybrid"
+  | "structure"
+  | "files"
+  | "auto"
+  | "summary"
+  | "matches"
+  | "inspect"
+  | "outline"
+  | "imports"
+  | "tests"
+  | "validate"
+  | "capabilities"
+  | "await"
+  | "cancel";
+
+export type OperationResultState = "running" | "complete" | "failed" | "cancelled" | "expired";
+
+export type OperationProgressDetails = OperationProgress;
+
+export interface OperationDetails {
+  id: string;
+  mode: "concept" | "hybrid";
+  state: OperationResultState;
+  startedAt: number;
+  deadlineAt: number;
+  leaseExpiresAt: number;
+  progress?: OperationProgressDetails;
+  nextRequest?: SiftLightInput;
+  error?: string;
+}
+
+export type ContextBudgetTier = keyof typeof CONTEXT_BUDGET_POLICY.resultTokenBudgets;
+
+export interface ContextBudget {
+  tier: ContextBudgetTier;
+  contextRemainderPercent: number;
+  resultTokenBudget: number;
+}
+
+export interface TextPosition {
+  line: number;
+  character: number;
+}
+
+export interface TextRange {
+  start: TextPosition;
+  end: TextPosition;
+  encoding: "utf-8" | "utf-16";
+}
+
+export interface MatchOccurrence {
+  byteStart: number;
+  byteEnd: number;
+  range: TextRange;
+}
+
+export interface SourceRevision {
+  size: number;
+  mtimeMs: number;
+  ctimeMs?: number;
+  inode?: number;
+  device?: number;
+}
+
+export type StructureStatus =
+  | "available"
+  | "no-symbol"
+  | "provider-unavailable"
+  | "source-unavailable"
+  | "parse-error"
+  | "file-too-large"
+  | "source-changed";
+
+export type SourceBoundary = "syntax" | "requested-range" | "line-window" | "mixed";
+
+export interface SymbolRange {
+  startLine: number;
+  endLine: number;
+}
+
+export interface StructureSymbol {
+  name: string;
+  kind: string;
+  scope: string[];
+  range: SymbolRange;
+}
+
+export interface StructureDetails {
+  status: StructureStatus;
+  provider?: string;
+  reason?: string;
+  language?: string;
+  symbol?: StructureSymbol;
+  range?: SymbolRange;
+}
+
+export interface InspectTarget {
+  path: string;
+  line: number;
+}
+
+export interface SourceExcerptDetails {
+  range: SymbolRange;
+  omittedBefore: number;
+  omittedAfter: number;
+  truncatedLines: number[];
+  reference?: SourceReference;
+  targetRanges?: ByteRange[];
+  fragments?: SourceFragment[];
+  remainingRanges?: ByteRange[];
+  complete?: boolean;
+  boundary?: SourceBoundary;
+  nextRequest?: SiftLightInput;
+}
+
+export interface InspectRetry {
+  mode: "inspect";
+  cursor?: string;
+  matchIndex?: number;
+  path?: string;
+  line?: number;
+}
+
+export interface InspectBatchItemDetails {
+  inputIndex: number;
+  path?: string;
+  line?: number;
+  matchIndex?: number;
+  status: "returned" | "deferred" | "error";
+  block?: number;
+  structure?: StructureDetails;
+  source?: SourceExcerptDetails;
+  error?: string;
+  retry?: InspectRetry;
+}
+
+export interface SearchRequest {
+  scope?: "strict" | "expand";
+  wholeWord?: boolean;
+  pattern: string;
+  path?: string;
+  expandedFromPath?: string;
+  glob: string[];
+  exclude: string[];
+  literal: boolean;
+  ignoreCase?: boolean;
+  hidden: boolean;
+  ignorePolicy?: "respect" | "include";
+  binaryAsText?: boolean;
+  context: number;
+  pageSize: number;
+  redact?: boolean;
+  modifiedAfterMs?: number;
+  modifiedBeforeMs?: number;
+}
+
+export interface SearchScopeDetails {
+  path: string;
+  requestedPath: string;
+  glob: string[];
+  exclude: string[];
+  hidden: boolean;
+  ignorePolicy?: "respect" | "include";
+  expandedToProjectRoot: boolean;
+  assertion: "requested-scope" | "project-wide";
+  modifiedAfterMs?: number;
+  modifiedBeforeMs?: number;
+}
+
+export interface MatchRecord {
+  absolutePath: string;
+  displayPath: string;
+  lineNumber: number;
+  lineContent: string;
+  lineTruncated: boolean;
+  occurrences: MatchOccurrence[];
+}
+
+export interface SearchScan {
+  request: SearchRequest;
+  matches: MatchRecord[];
+  totalMatches: number;
+  fileCounts: Map<string, number>;
+  sourceRevisions: Map<string, SourceRevision>;
+  snapshotComplete: boolean;
+  filesystemCoverage?: "complete" | "policy-filtered" | "partial";
+  filesystemCoverageReasons?: string[];
+  ignoredFileCount?: number;
+  ignoredFileSamples?: string[];
+  searchedFileCount?: number;
+  truncatedLines: number;
+  retention?: SearchRetentionDetails;
+}
+
+export interface SearchRetentionDetails {
+  accountedBytes: number;
+  retainedOccurrences: number;
+  maxBytes: number;
+  maxOccurrences: number;
+  reasons: string[];
+}
+
+export interface SearchSnapshot extends SearchScan {
+  id: string;
+  createdAt: number;
+  lastAccessedAt: number;
+}
+
+export interface StatisticsEntry {
+  label: string;
+  count: number;
+}
+
+export interface StatisticsGroup {
+  dimension: string;
+  entries: StatisticsEntry[];
+  omitted: number;
+  total: number;
+}
+
+export interface ResultStatistics {
+  unit: string;
+  total: number;
+  files: number;
+  directories: number;
+  groups: StatisticsGroup[];
+  topFiles: StatisticsEntry[];
+  topFilesOmitted: number;
+}
+
+export interface SiftLightDetails {
+  inspectRequest?: SiftLightInput;
+  version: 1;
+  mode: SearchMode;
+  status: "complete" | "partial" | "waiting" | "running" | "cancelled" | "failed" | "expired";
+  error?: RequestContractDetails;
+  totalMatches: number;
+  storedMatches: number;
+  totalFiles: number;
+  returnedMatches: number;
+  snapshotComplete: boolean;
+  retention?: SearchRetentionDetails;
+  cursor?: string;
+  nextRequest?: SiftLightInput;
+  analysis?: AnalysisDetails;
+  statistics?: ResultStatistics;
+  validation?: ValidationDetails;
+  sourceBlocks?: { path: string; source: SourceExcerptDetails }[];
+  summaryFilesShown?: number;
+  summaryOffset?: number;
+  selectedPaths?: string[];
+  selectionMissingPaths?: string[];
+  summaryFilesOmitted?: number;
+  lineContentTruncated?: number;
+  occurrenceRangesOmitted?: number;
+  occurrenceMatchesTruncated?: number;
+  sourceUnverifiedFileCount?: number;
+  summaryPreviewsShown?: number;
+  summaryPreviewsOmitted?: number;
+  budgetTier?: ContextBudgetTier;
+  contextRemainderPercent?: number;
+  resultTokenBudget?: number;
+  contextOmittedFiles?: string[];
+  contextChangedFiles?: string[];
+  structure?: StructureDetails;
+  source?: SourceExcerptDetails;
+  inspections?: InspectBatchItemDetails[];
+  scope?: SearchScopeDetails;
+  redactedCount?: number;
+  redactionRequested?: boolean;
+  redactionApplied?: boolean;
+  operation?: OperationDetails;
+  capabilities?: LanguageCapabilityInventory;
+  audit?: AuditReceiptDetails;
+  searchCoverage?: {
+    retainedMatches: "complete" | "partial";
+    filesystem: "complete" | "policy-filtered" | "partial";
+    ignoredFiles: number;
+    ignoredFileSamples: string[];
+    searchedFiles: number;
+    reasons: string[];
+  };
+}
+
+export interface AuditPatternInput {
+  id: string;
+  literal: string;
+}
+
+export interface AuditFindingDetails {
+  id: string;
+  status: "present" | "absent_with_complete_coverage" | "unknown";
+  matches: number;
+  files: number;
+  evidence: { path: string; line: number }[];
+  reproduction: SiftLightInput;
+}
+
+export interface AuditReceiptDetails {
+  declaredScope: SearchScopeDetails;
+  coverage: {
+    filesDiscovered: number;
+    filesAdmitted: number;
+    filesSearched: number;
+    ignoredFiles: number;
+    ignoredFileSamples: string[];
+    ignoredFilesOmitted: number;
+    filesSkippedOther: number;
+    complete: boolean;
+    reasons: string[];
+    reasonsOmitted: number;
+  };
+  stability: {
+    status: "stable" | "changed_during_search" | "unknown";
+    changedFiles: string[];
+    changedFilesOmitted: number;
+  };
+  findings: AuditFindingDetails[];
+}
+
+export interface SiftLightResult {
+  text: string;
+  details: SiftLightDetails;
+}

package/src/validation-output.ts

@@ -0,0 +1,148 @@
+import type { AnalysisItem, AnalysisDetails } from "./analysis-types.js";
+import type { SiftLightDetails, SiftLightResult } from "./types.js";
+import type {
+  ValidationDetails,
+  EvidenceSourceStatus,
+  EvidenceSourceScope,
+} from "./validation-types.js";
+import type { SavedEvidenceValidationResult } from "./evidence-validation.js";
+
+function sourceItem(status: EvidenceSourceStatus, index: number): AnalysisItem {
+  return {
+    path: status.path,
+    line: 1,
+    label: `source ${status.status}`,
+    details: {
+      role: status.role,
+      status: status.status,
+      ...(status.reason ? { reason: status.reason } : {}),
+      index,
+    },
+  };
+}
+
+function publicSourceStatus(status: EvidenceSourceStatus): EvidenceSourceStatus {
+  const reference = status.current ?? status.expected;
+  const actualTarget =
+    status.actualTarget ??
+    (reference === undefined
+      ? undefined
+      : reference.origin.kind === "git"
+        ? "recorded-git"
+        : "current-worktree");
+  return {
+    path: status.path,
+    role: status.role,
+    status: status.status,
+    ...(actualTarget ? { actualTarget } : {}),
+    ...(status.reason ? { reason: status.reason } : {}),
+  };
+}
+
+function sourceStatusRank(status: EvidenceSourceStatus["status"]): number {
+  return status === "stale" ? 0 : status === "unknown" ? 1 : 2;
+}
+
+export function publicValidationDetails(
+  scope: EvidenceSourceScope,
+  sources: readonly EvidenceSourceStatus[],
+  values: Partial<ValidationDetails> &
+    Pick<
+      ValidationDetails,
+      "freshness" | "coverage" | "truncation" | "comparisonTarget" | "checkInterval"
+    >,
+): ValidationDetails {
+  const ordered = [...sources].toSorted((left, right) => {
+    return (
+      sourceStatusRank(left.status) - sourceStatusRank(right.status) ||
+      left.path.localeCompare(right.path)
+    );
+  });
+  const visible: EvidenceSourceStatus[] = [];
+  let sourceBytes = 0;
+  for (const source of ordered) {
+    const compact = publicSourceStatus(source);
+    const rowBytes = Buffer.byteLength(JSON.stringify(compact));
+    if (visible.length > 0 && sourceBytes + rowBytes > 4_096) break;
+    visible.push(compact);
+    sourceBytes += rowBytes;
+  }
+  const omitted = sources.length - visible.length;
+  return {
+    scope,
+    checked: visible.filter((source) => source.status !== "unknown"),
+    unchecked: visible.filter((source) => source.status === "unknown"),
+    ...(omitted > 0 ? { sourceOmitted: omitted } : {}),
+    ...values,
+  };
+}
+
+function base(
+  mode: "validate",
+  status: "complete" | "partial",
+  total: number,
+  files: number,
+  returned = total,
+): SiftLightDetails {
+  return {
+    version: 1,
+    mode,
+    status,
+    totalMatches: total,
+    storedMatches: total,
+    totalFiles: files,
+    returnedMatches: returned,
+    snapshotComplete: status === "complete",
+  };
+}
+
+export function validationResult(
+  state: SavedEvidenceValidationResult,
+  cursor: string,
+  checkInterval: { start: number; end: number; selected?: number },
+): SiftLightResult {
+  const { recheck, comparisonTarget, coverage } = state;
+  const status =
+    state.storedPartial || coverage === "partial" || recheck.validity !== "current"
+      ? "partial"
+      : "complete";
+  const reasons = [...new Set([...(state.reasons ?? []), ...recheck.reasons])];
+  const validation = publicValidationDetails(state.scope, recheck.sources, {
+    comparisonTarget,
+    freshness: recheck.validity,
+    coverage,
+    truncation: { truncated: state.storedPartial, reasons },
+    checkInterval,
+  });
+  const analysis: AnalysisDetails = {
+    kind: "validate",
+    unit: "evidence-items",
+    totalItems: recheck.sources.length,
+    returnedItems: validation.checked.length + validation.unchecked.length,
+    items: [...validation.checked, ...validation.unchecked].map((source, index) =>
+      Object.assign(sourceItem(source, index + 1), { index: index + 1 }),
+    ),
+    reasons,
+    validation,
+  };
+  const details: SiftLightDetails = {
+    ...base(
+      "validate",
+      status,
+      recheck.sources.length,
+      new Set(recheck.sources.map((source) => source.path)).size,
+      validation.checked.length + validation.unchecked.length,
+    ),
+    cursor,
+    analysis,
+    validation,
+  };
+  const sourceRows = [...validation.checked, ...validation.unchecked].map(
+    (source, index) =>
+      `#${String(index + 1)} ${JSON.stringify(source.path)}: ${source.status}${source.reason ? ` (${source.reason})` : ""}`,
+  );
+  return {
+    text: `Evidence validation is ${recheck.validity}; checked ${String(validation.checked.length)} source(s), ${String(validation.unchecked.length)} require attention; coverage ${coverage}; target ${comparisonTarget}; check interval ${String(checkInterval.start)}-${String(checkInterval.end)}.${validation.sourceOmitted ? ` ${String(validation.sourceOmitted)} source(s) omitted from this page.` : ""}${reasons.length ? ` ${reasons.join(" ")}` : ""}${sourceRows.length ? `\n${sourceRows.join("\n")}` : ""}`,
+    details,
+  };
+}

package/src/validation-types.ts

@@ -0,0 +1,48 @@
+import type { SourceReference } from "./source-document.js";
+
+export type EvidenceValidity = "current" | "stale" | "unknown";
+
+export type EvidenceComparisonTarget = "current-worktree" | "recorded-git" | "mixed";
+
+export type EvidenceCoverageStatus = "complete" | "partial" | "skipped" | "not-applicable";
+
+export interface EvidenceSourceScope {
+  /** Saved evidence root, expressed as an absolute or search-relative path. */
+  root: string;
+  include?: readonly string[];
+  exclude?: readonly string[];
+  /** Whether hidden files are admitted by the search source inventory. */
+  hidden?: boolean;
+}
+
+export type EvidenceDependencyRole = "source";
+
+export interface EvidenceSourceStatus {
+  path: string;
+  role: EvidenceDependencyRole;
+  status: EvidenceValidity;
+  expected?: SourceReference;
+  current?: SourceReference;
+  /** Actual source origin used for this item when it can be determined. */
+  actualTarget?: EvidenceComparisonTarget;
+  reason?: string;
+}
+
+export interface EvidenceRecheck {
+  validity: EvidenceValidity;
+  coverage: EvidenceCoverageStatus;
+  sources: readonly EvidenceSourceStatus[];
+  reasons: readonly string[];
+}
+
+export interface ValidationDetails {
+  freshness: EvidenceValidity;
+  coverage: EvidenceCoverageStatus;
+  scope: EvidenceSourceScope;
+  comparisonTarget: EvidenceComparisonTarget;
+  checked: readonly EvidenceSourceStatus[];
+  unchecked: readonly EvidenceSourceStatus[];
+  sourceOmitted?: number;
+  truncation: { truncated: boolean; reasons: readonly string[] };
+  checkInterval: { start: number; end: number; selected?: number };
+}