kibi-cli 2.2.0 → 2.4.0

package/dist/traceability/trusted-pr-event.js

@@ -0,0 +1,105 @@
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+const OBJECT_ID = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/;
+function runGit(root, args) {
+    return execFileSync("git", [...args], {
+        cwd: root,
+        encoding: "utf8",
+        maxBuffer: 16 * 1024 * 1024,
+        stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+}
+function resolveCommit(root, input) {
+    if (!OBJECT_ID.test(input))
+        throw new Error("PR event contains an invalid Git object ID");
+    const resolved = runGit(root, [
+        "rev-parse",
+        "--verify",
+        "--end-of-options",
+        `${input}^{commit}`,
+    ]);
+    if (!OBJECT_ID.test(resolved))
+        throw new Error("Git returned an invalid commit ID");
+    return resolved;
+}
+function resolveTree(root, commit) {
+    const tree = runGit(root, [
+        "rev-parse",
+        "--verify",
+        "--end-of-options",
+        `${commit}^{tree}`,
+    ]);
+    if (!OBJECT_ID.test(tree))
+        throw new Error("Git returned an invalid tree ID");
+    return tree;
+}
+/** Verify a GitHub pull_request_target envelope against the protected checkout. */
+export function resolveTrustedPullRequestSnapshot(workspaceRoot, environment = process.env) {
+    if (environment.GITHUB_EVENT_NAME !== "pull_request_target")
+        throw new Error("Trusted impact gate requires pull_request_target context");
+    const eventPath = environment.GITHUB_EVENT_PATH;
+    const repository = environment.GITHUB_REPOSITORY;
+    const trustedTargetRef = environment.KIBI_IMPACT_TRUSTED_TARGET_REF;
+    const githubSha = environment.GITHUB_SHA;
+    if (!eventPath || !repository || !trustedTargetRef || !githubSha)
+        throw new Error("Trusted PR event, repository, target ref and GitHub event SHA are required");
+    if (!/^[^/]+\/[^/]+$/.test(repository))
+        throw new Error("GitHub repository identity is invalid");
+    if (!/^refs\/heads\/[A-Za-z0-9._/-]+$/.test(trustedTargetRef))
+        throw new Error("Trusted target must be a full refs/heads/... name");
+    const payload = JSON.parse(readFileSync(eventPath, "utf8"));
+    const request = payload.pull_request;
+    const base = request?.base;
+    const head = request?.head;
+    const baseRef = base?.ref;
+    const targetInput = base?.sha;
+    const headInput = head?.sha;
+    if (typeof baseRef !== "string" ||
+        typeof targetInput !== "string" ||
+        typeof headInput !== "string" ||
+        base?.repo?.full_name !== repository)
+        throw new Error("PR event does not identify this repository's base and head");
+    if (trustedTargetRef !== `refs/heads/${baseRef}`)
+        throw new Error("PR target does not match the configured protected branch");
+    if (payload.repository?.full_name !== repository)
+        throw new Error("PR event repository identity does not match the trusted checkout");
+    const targetCommit = resolveCommit(workspaceRoot, targetInput);
+    const headCommit = resolveCommit(workspaceRoot, headInput);
+    if (resolveCommit(workspaceRoot, githubSha) !== targetCommit)
+        throw new Error("GitHub event target SHA does not match its trusted payload");
+    const checkoutCommit = resolveCommit(workspaceRoot, runGit(workspaceRoot, ["rev-parse", "HEAD"]));
+    if (checkoutCommit !== targetCommit)
+        throw new Error("Trusted evaluator checkout is not the PR target commit");
+    if (runGit(workspaceRoot, ["rev-parse", "--is-shallow-repository"]) !== "false")
+        throw new Error("Complete Git history is required for impact evaluation");
+    const missing = runGit(workspaceRoot, [
+        "rev-list",
+        "--objects",
+        "--missing=print",
+        targetCommit,
+        headCommit,
+    ]);
+    if (missing.split("\n").some((line) => line.startsWith("?")))
+        throw new Error("PR target or head has missing reachable Git objects");
+    const mergeBases = runGit(workspaceRoot, [
+        "merge-base",
+        "--all",
+        targetCommit,
+        headCommit,
+    ])
+        .split("\n")
+        .filter(Boolean);
+    if (mergeBases.length !== 1)
+        throw new Error("PR target and head must have exactly one merge base");
+    const mergeBaseCommit = resolveCommit(workspaceRoot, mergeBases[0] ?? "");
+    return {
+        repository,
+        targetRef: trustedTargetRef,
+        targetCommit,
+        targetTree: resolveTree(workspaceRoot, targetCommit),
+        headCommit,
+        headTree: resolveTree(workspaceRoot, headCommit),
+        mergeBaseCommit,
+        mergeBaseTree: resolveTree(workspaceRoot, mergeBaseCommit),
+    };
+}

package/dist/utils/canonical-path.d.ts

@@ -0,0 +1,3 @@
+/** Resolve filesystem aliases while preserving a suffix that does not exist yet. */
+export declare function canonicalFilesystemPath(candidate: string): string;
+//# sourceMappingURL=canonical-path.d.ts.map

package/dist/utils/canonical-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-path.d.ts","sourceRoot":"","sources":["../../src/utils/canonical-path.ts"],"names":[],"mappings":"AAGA,oFAAoF;AACpF,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAwBjE"}

package/dist/utils/canonical-path.js

@@ -0,0 +1,33 @@
+import { lstatSync, realpathSync } from "node:fs";
+import path from "node:path";
+/** Resolve filesystem aliases while preserving a suffix that does not exist yet. */
+export function canonicalFilesystemPath(candidate) {
+    let existing = path.resolve(candidate);
+    const missing = [];
+    for (;;) {
+        try {
+            return path.resolve(realpathSync.native(existing), ...missing);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            // A dangling symlink is an existing entry, not a missing path segment.
+            // Refuse it rather than allowing a later write to follow an unknown target.
+            let entry;
+            try {
+                entry = lstatSync(existing);
+            }
+            catch (statError) {
+                if (statError.code !== "ENOENT")
+                    throw statError;
+            }
+            if (entry !== undefined)
+                throw error;
+            const parent = path.dirname(existing);
+            if (parent === existing)
+                throw error;
+            missing.unshift(path.basename(existing));
+            existing = parent;
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cli",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "type": "module",
   "description": "Kibi CLI for knowledge base management",
   "engines": {
@@ -10,7 +10,15 @@
   "bin": {
     "kibi": "bin/kibi"
   },
-  "files": ["dist", "bin", "schema", "src/schemas", "src/public", "templates"],
+  "files": [
+    "dist",
+    "bin",
+    "schema",
+    "src/schemas",
+    "src/public",
+    "src/traceability/*.schema.json",
+    "templates"
+  ],
   "scripts": {
     "build": "tsc -p tsconfig.json && rm -rf dist/public/skills && mkdir -p dist/public/skills dist/report && cp -r src/public/skills/. dist/public/skills/ && cp src/report/html-report.css dist/report/html-report.css && node ../../scripts/generate-entity-schema.mjs --check",
     "test": "node ../../scripts/run-owned-engine-tests.mjs -- bun test --timeout 15000 .",
@@ -227,9 +235,10 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-core": "^0.14.0",
-    "kibi-plugin-builtin": "^0.3.0",
-    "kibi-plugin-sdk": "^0.3.0",
+    "kibi-core": "^0.14.1",
+    "kibi-plugin-builtin": "^0.4.0",
+    "kibi-plugin-sdk": "^0.4.0",
+    "kibi-swipl": "^1.0.0",
     "saxes": "^6.0.0",
     "ignore": "^5.3.0",
     "yaml": "^2.9.0"

package/src/public/diagnostic-usage.ts

@@ -1,6 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
-import { appendFileSync, mkdirSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 
 import {
   appendPayloadCountField,
@@ -241,6 +242,60 @@ export function deriveDiagnosticUsageFields(
   return fields;
 }
 
+/**
+ * Whether the operator opted into usage telemetry through the environment.
+ *
+ * `KIBI_DIAGNOSTIC_MODE` is the one opt-in shared with the MCP server, so a
+ * single setting covers both peer surfaces. `KIBI_CLI_DIAGNOSTIC_MODE` is the
+ * older CLI-only spelling and keeps working.
+ */
+export function diagnosticEnvOptIn(
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  return ["KIBI_DIAGNOSTIC_MODE", "KIBI_CLI_DIAGNOSTIC_MODE"].some((key) => {
+    const value = env[key]?.trim().toLowerCase();
+    return value === "1" || value === "true";
+  });
+}
+
+/**
+ * The host that ran this CLI call. Hosts that launch Kibi set `KIBI_HOST`;
+ * Claude Code marks every shell it runs with `CLAUDECODE=1`, which is the
+ * only ambient signal trusted here. Anything else stays `unknown`.
+ */
+export function diagnosticCliHost(
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  const explicit = env.KIBI_HOST?.trim() || env.KIBI_MCP_HOST?.trim();
+  if (explicit) return explicit;
+  return env.CLAUDECODE === "1" ? "claude-code" : "unknown";
+}
+
+let cachedCliPackageVersion: string | null | undefined;
+
+function cliPackageVersion(): string | null {
+  if (cachedCliPackageVersion !== undefined) return cachedCliPackageVersion;
+  cachedCliPackageVersion = null;
+  let current = path.dirname(fileURLToPath(import.meta.url));
+  while (true) {
+    const candidate = path.join(current, "package.json");
+    if (existsSync(candidate)) {
+      try {
+        const parsed: unknown = JSON.parse(readFileSync(candidate, "utf8"));
+        if (isRecord(parsed) && typeof parsed.version === "string") {
+          cachedCliPackageVersion = parsed.version;
+        }
+      } catch {
+        // An unreadable manifest leaves the version unknown.
+      }
+      return cachedCliPackageVersion;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
 export function appendCliDiagnosticUsage(input: DiagnosticUsageInput): void {
   const finishedAt = input.finishedAt ?? new Date();
   const requestId = input.requestId ?? `cli-${randomUUID()}`;
@@ -256,6 +311,9 @@ export function appendCliDiagnosticUsage(input: DiagnosticUsageInput): void {
       request_id: requestId,
       tool: input.tool,
       interface: "cli_json",
+      host: diagnosticCliHost(),
+      package_version: cliPackageVersion(),
+      workspace_root: input.workspaceRoot,
       telemetry: input.telemetry,
       business_args: input.businessArgs,
       status: input.status,

package/src/public/impact/analyzer.ts

@@ -1,4 +1,14 @@
 import * as path from "node:path";
+import {
+  createMaintenanceSourceAnalysisService,
+  readSnapshotSourceConfig,
+} from "../../plugins/maintenance-source-analysis.js";
+import {
+  analyzeSourceChanges,
+  assertSourceAnalysisGate,
+} from "../../plugins/source-change-analysis.js";
+import { captureStagedSnapshot } from "../../traceability/git-change-snapshot.js";
+import { readSnapshotKnowledge } from "../../traceability/snapshot-knowledge.js";
 import type { ExtractedSymbol } from "../../traceability/symbol-extract.js";
 import { extractSymbolsFromStagedFileAsync } from "../../traceability/symbol-extract.js";
 import {
@@ -9,6 +19,7 @@ import {
   createImpactManifestLookup,
   readImpactManifestResults,
 } from "./manifest.js";
+import { normalizeSourceFile } from "./source-changes.js";
 import { collectSourceChanges, uniqueSorted } from "./source-changes.js";
 import {
   buildNextActions,
@@ -25,16 +36,73 @@ export async function analyzeChangedFileImpact(
   options: ChangedFileImpactOptions,
 ): Promise<ChangedFileImpactResult> {
   const workspaceRoot = path.resolve(options.workspaceRoot);
-  const sourceChanges = collectSourceChanges({ ...options, workspaceRoot });
-  const sourceFiles = uniqueSorted(sourceChanges.map((change) => change.file));
-  const manifestResults = readImpactManifestResults(workspaceRoot);
+  const snapshot = options.staged
+    ? captureStagedSnapshot(workspaceRoot)
+    : undefined;
+  const filter = new Set(
+    (options.sourceFiles ?? []).map((file) =>
+      normalizeSourceFile(workspaceRoot, file),
+    ),
+  );
+  const snapshotAnalysisInventory = snapshot
+    ? snapshot.inventory.filter(
+        (file) => filter.size === 0 || filter.has(file.path),
+      )
+    : undefined;
+  const snapshotSourceInventory = snapshot
+    ? snapshot.inventory.filter(
+        (file) =>
+          file.analysisDepth !== "metadata" &&
+          !file.skipReason &&
+          file.content !== undefined &&
+          (filter.size === 0 || filter.has(file.path)),
+      )
+    : undefined;
+  const sourceChanges = snapshot
+    ? (snapshotSourceInventory ?? []).map((file) => ({
+        file: file.path,
+        status: file.status,
+        hunkRanges: file.hunkRanges,
+        content: file.content ?? "",
+      }))
+    : collectSourceChanges({ ...options, workspaceRoot });
+  const service = createMaintenanceSourceAnalysisService(
+    workspaceRoot,
+    snapshot ? readSnapshotSourceConfig(snapshot) : undefined,
+  );
+  const analyses = snapshot
+    ? await analyzeSourceChanges(snapshotAnalysisInventory ?? [], service)
+    : undefined;
+  if (analyses)
+    assertSourceAnalysisGate(snapshotAnalysisInventory ?? [], analyses);
+  const sourceFiles = uniqueSorted(
+    snapshot
+      ? snapshot.inventory
+          .filter(
+            (file) =>
+              file.analysisDepth !== "metadata" &&
+              (filter.size === 0 || filter.has(file.path)),
+          )
+          .map((file) => file.path)
+      : sourceChanges.map((change) => change.file),
+  );
+  const manifestResults = snapshot
+    ? readSnapshotKnowledge(
+        snapshot.readGit,
+        snapshot.headTree,
+        snapshot.readBlobs,
+      ).filter((result) => result.entity.type === "symbol")
+    : readImpactManifestResults(workspaceRoot);
   const manifestLookup = createImpactManifestLookup(manifestResults);
   const symbolsByFile = new Map<string, ExtractedSymbol[]>();
   const sourceContentByFile = new Map<string, string>();
+  const sourceSymbolsByFile = new Map<string, ExtractedSymbol[]>();
 
   for (const change of sourceChanges) {
     sourceContentByFile.set(change.file, change.content);
-    // Maintenance path: builtin-only (do not pass registry / workspaceRoot).
+    const analysis =
+      analyses?.get(change.file)?.after ??
+      (await service.analyzeTextV2(change.file, change.content));
     const extracted = await extractSymbolsFromStagedFileAsync(
       {
         path: change.file,
@@ -43,8 +111,21 @@ export async function analyzeChangedFileImpact(
         content: change.content,
       },
       manifestLookup,
-      {},
+      { analyzeText: async () => analysis },
+    );
+    const allSymbols = await extractSymbolsFromStagedFileAsync(
+      {
+        path: change.file,
+        status: change.status,
+        content: change.content,
+        hunkRanges: [
+          { start: 1, end: Math.max(1, change.content.split("\n").length) },
+        ],
+      },
+      manifestLookup,
+      { analyzeText: async () => analysis },
     );
+    sourceSymbolsByFile.set(change.file, allSymbols);
     symbolsByFile.set(
       change.file,
       extracted.filter((symbol) => symbol.hunkRanges.length > 0),
@@ -65,6 +146,7 @@ export async function analyzeChangedFileImpact(
             manifestResults: activeManifestResults,
             symbolsByFile,
             sourceContentByFile,
+            sourceSymbolsByFile,
             workspaceRoot,
           }),
           ...createSymbolQualityDiagnostics({
@@ -79,6 +161,7 @@ export async function analyzeChangedFileImpact(
       ? impactDiagnostics.slice(0, maxDiagnostics)
       : impactDiagnostics;
 
+  snapshot?.assertUnchanged();
   return {
     impactDiagnostics: cappedDiagnostics,
     sourceFiles,

package/src/public/impact/diagnostics.ts

@@ -74,11 +74,13 @@ function getGranularSymbolsForSourceFile(
   readonly candidateSymbols: readonly ExtractedSymbol[];
   readonly sourceSymbols: readonly ExtractedSymbol[];
 } {
-  const sourceSymbols = readSourceSymbols(
-    sourceFile,
-    options.sourceContentByFile,
-    options.workspaceRoot ?? process.cwd(),
-  );
+  const sourceSymbols = options.sourceSymbolsByFile
+    ? (options.sourceSymbolsByFile.get(sourceFile) ?? [])
+    : readSourceSymbols(
+        sourceFile,
+        options.sourceContentByFile,
+        options.workspaceRoot ?? process.cwd(),
+      );
   const changedSymbols = options.symbolsByFile.get(sourceFile);
 
   return {

package/src/public/impact/manifest.ts

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import * as path from "node:path";
 import { extractFromManifest } from "../../extractors/manifest.js";
 import type { ExtractionResult } from "../../extractors/markdown.js";
+import { createManifestLookupSentinelKey } from "../../traceability/symbol-extract.js";
 import type { ManifestLookup } from "../../traceability/symbol-extract.js";
 import { CANONICAL_ENTITY_PATHS } from "../../utils/kb-paths.js";
 import { isTraceabilityRelationshipType } from "../symbol-granularity.js";
@@ -42,10 +43,22 @@ export function createImpactManifestLookup(
   manifestResults: readonly ExtractionResult[],
 ): ManifestLookup {
   const manifestLookup: ManifestLookup = new Map();
+  manifestLookup.set(createManifestLookupSentinelKey(".kb/symbols.yaml"), {
+    id: "__captured_manifest__",
+    relationships: [],
+  });
+  const ambiguous = new Set<string>();
 
   for (const result of manifestResults) {
     const sourceFile = result.sourceFile ?? result.entity.source;
-    manifestLookup.set(`${sourceFile}:${result.entity.title}`, {
+    const key = `${sourceFile}:${result.entity.title}`;
+    if (ambiguous.has(key)) continue;
+    if (manifestLookup.has(key)) {
+      manifestLookup.delete(key);
+      ambiguous.add(key);
+      continue;
+    }
+    manifestLookup.set(key, {
       id: result.entity.id,
       relationships: toTraceabilityRelationships(result.relationships),
     });

package/src/public/impact/source-changes.ts

@@ -1,6 +1,7 @@
-import { execSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { execFileSync, execSync } from "node:child_process";
+import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
 import * as path from "node:path";
+import { isQualifiedSourcePath } from "../../plugins/source-classification.js";
 import type { HunkRange } from "../../traceability/git-staged.js";
 import {
   getStagedFiles,
@@ -9,19 +10,8 @@ import {
 import { hasMeaningfulSourceDiff } from "./diff-meaning.js";
 import type { ChangedFileImpactOptions, SourceChange } from "./types.js";
 
-const SOURCE_EXTENSIONS = new Set([
-  ".ts",
-  ".tsx",
-  ".js",
-  ".jsx",
-  ".mts",
-  ".cts",
-  ".mjs",
-  ".cjs",
-]);
-
 function isSupportedSourcePath(filePath: string): boolean {
-  return SOURCE_EXTENSIONS.has(path.extname(filePath));
+  return isQualifiedSourcePath(filePath);
 }
 
 export function normalizeSourceFile(
@@ -38,12 +28,12 @@ export function uniqueSorted(values: Iterable<string>): string[] {
   return [...new Set(values)].sort();
 }
 
-function escapeGitPath(filePath: string): string {
-  return filePath.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
-}
-
-function runGit(workspaceRoot: string, command: string): string {
-  return execSync(command, { cwd: workspaceRoot, encoding: "utf8" });
+function runGit(workspaceRoot: string, args: readonly string[]): string {
+  return execFileSync("git", [...args], {
+    cwd: workspaceRoot,
+    encoding: "utf8",
+    env: { ...process.env, GIT_LITERAL_PATHSPECS: "1" },
+  });
 }
 
 function readWorkingTreeSource(
@@ -51,8 +41,24 @@ function readWorkingTreeSource(
   sourceFile: string,
 ): string | null {
   const absolutePath = path.resolve(workspaceRoot, sourceFile);
-  if (!existsSync(absolutePath)) return null;
-  return readFileSync(absolutePath, "utf8");
+  const relative = path.relative(workspaceRoot, absolutePath);
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative))
+    throw new Error("Source path must remain inside the workspace");
+  if (!existsSync(absolutePath) || !lstatSync(absolutePath).isFile())
+    return null;
+  const actualRelative = path.relative(
+    realpathSync(workspaceRoot),
+    realpathSync(absolutePath),
+  );
+  if (actualRelative.startsWith("..") || path.isAbsolute(actualRelative))
+    throw new Error("Source path escapes the workspace");
+  const bytes = readFileSync(absolutePath);
+  if (bytes.includes(0)) return null;
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    return null;
+  }
 }
 
 function fullFileHunk(content: string): HunkRange[] {
@@ -62,9 +68,9 @@ function fullFileHunk(content: string): HunkRange[] {
 function getWorkingTreeDiffSourceFiles(workspaceRoot: string): string[] {
   try {
     return uniqueSorted(
-      runGit(workspaceRoot, "git diff --name-only --diff-filter=ACMR")
-        .split(/\r?\n/)
-        .map((filePath) => normalizeSourceFile(workspaceRoot, filePath.trim()))
+      runGit(workspaceRoot, ["diff", "--name-only", "-z", "--diff-filter=ACMR"])
+        .split("\0")
+        .map((filePath) => normalizeSourceFile(workspaceRoot, filePath))
         .filter((filePath) => filePath.length > 0)
         .filter(isSupportedSourcePath),
     );
@@ -78,10 +84,7 @@ function getWorkingTreeHunks(
   sourceFile: string,
 ): HunkRange[] {
   try {
-    const diffText = runGit(
-      workspaceRoot,
-      `git diff -U0 -- "${escapeGitPath(sourceFile)}"`,
-    );
+    const diffText = runGit(workspaceRoot, ["diff", "-U0", "--", sourceFile]);
     return parseHunksFromDiff(diffText);
   } catch {
     return [];
@@ -104,6 +107,7 @@ function getStagedSourceChanges(
     .flatMap((file): SourceChange[] => {
       if (file.content === undefined || file.hunkRanges.length === 0) return [];
       if (
+        !/\.(pyi?|go|rs)$/.test(file.path) &&
         file.diffText !== undefined &&
         !hasMeaningfulSourceDiff(file.diffText)
       ) {
@@ -132,11 +136,12 @@ function getWorkingTreeSourceChanges(
   return sourceFiles.flatMap((sourceFile): SourceChange[] => {
     const content = readWorkingTreeSource(workspaceRoot, sourceFile);
     if (content === null) return [];
-    const diffText = runGit(
-      workspaceRoot,
-      `git diff -U0 -- "${escapeGitPath(sourceFile)}"`,
-    );
-    if (!hasMeaningfulSourceDiff(diffText)) return [];
+    const diffText = runGit(workspaceRoot, ["diff", "-U0", "--", sourceFile]);
+    if (
+      !/\.(pyi?|go|rs)$/.test(sourceFile) &&
+      !hasMeaningfulSourceDiff(diffText)
+    )
+      return [];
     const hunkRanges = getWorkingTreeHunks(workspaceRoot, sourceFile);
     if (hunkRanges.length === 0) return [];
     return [{ file: sourceFile, status: "M", hunkRanges, content }];

package/src/public/impact/types.ts

@@ -39,6 +39,11 @@ export type SymbolGranularityDiagnosticsOptions = {
   readonly activeEntityIds?: ReadonlySet<string>;
   readonly symbolsByFile: SymbolsByFile;
   readonly sourceContentByFile?: ReadonlyMap<string, string>;
+  /** Complete snapshot analysis; when supplied, filesystem fallback is forbidden. */
+  readonly sourceSymbolsByFile?: ReadonlyMap<
+    string,
+    readonly ExtractedSymbol[]
+  >;
   readonly workspaceRoot?: string;
 };
 

package/src/public/operations/catalog.ts

@@ -6,6 +6,7 @@ import {
 import { planBootstrapSpec } from "./specs/bootstrap.js";
 import { checkSpec } from "./specs/check.js";
 import { querySpec, searchSpec, statusSpec } from "./specs/discovery.js";
+import { prepareImpactReviewSpec } from "./specs/impact-review-preparation.js";
 import {
   modelRequirementSpec,
   suggestPredicatesSpec,
@@ -49,6 +50,7 @@ export const OPERATION_CATALOG = [
   upsertSpec,
   deleteSpec,
   checkSpec,
+  prepareImpactReviewSpec,
   sparqlRemoteSpec,
   compileIntentSpec,
   applyPlanSpec,