kibi-cli 2.35.1 → 2.38.0

package/dist/utils/branch-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"branch-resolver.d.ts","sourceRoot":"","sources":["../../src/utils/branch-resolver.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"branch-resolver.d.ts","sourceRoot":"","sources":["../../src/utils/branch-resolver.ts"],"names":[],"mappings":"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"}

package/dist/utils/branch-resolver.js

@@ -45,6 +45,7 @@ export function _setBranchResolverDepsForTests(deps) {
 // Files to exclude when copying branch snapshots (volatile artifacts)
 const VOLATILE_ARTIFACTS = new Set([
     "sync-cache.json",
+    "source-analysis-cache.json",
     "journal.log",
     "audit.log",
     "lock",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cli",
-  "version": "2.35.1",
+  "version": "2.38.0",
   "type": "module",
   "description": "Kibi CLI for knowledge base management",
   "engines": {
@@ -239,13 +239,14 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-core": "^0.26.1",
+    "kibi-core": "^0.27.0",
     "kibi-plugin-builtin": "^0.5.3",
-    "kibi-plugin-sdk": "^0.5.0",
+    "kibi-plugin-sdk": "^0.5.1",
     "kibi-swipl": "^1.0.1",
     "saxes": "^6.0.0",
     "ignore": "^5.3.0",
-    "yaml": "^2.9.1"
+    "yaml": "^2.9.1",
+    "kibi-agent-core": "^0.10.0"
   },
   "devDependencies": {
     "@types/node": "latest",

package/src/public/impact/coverage-depth-quality.ts

@@ -33,12 +33,59 @@ type RelationshipLookup = {
 };
 
 type IncomingLookup = {
-  readonly manifestResults: readonly ExtractionResult[];
+  readonly index: CoverageIndex;
   readonly targetId: string;
   readonly relationshipType: string;
   readonly type: string;
 };
 
+/**
+ * Built once per report, so each requirement's coverage is a lookup rather
+ * than a scan over every manifest result.
+ */
+type CoverageIndex = {
+  readonly resultsById: ReadonlyMap<string, ExtractionResult>;
+  /** Source entities by `${type}\0${relationshipType}\0${targetId}`, in manifest order. */
+  readonly incomingByTarget: ReadonlyMap<string, readonly ExtractedEntity[]>;
+};
+
+function incomingKey(
+  type: string,
+  relationshipType: string,
+  targetId: string,
+): string {
+  return `${type}\0${relationshipType}\0${targetId}`;
+}
+
+function coverageIndex(
+  manifestResults: readonly ExtractionResult[],
+): CoverageIndex {
+  const incomingByTarget = new Map<string, ExtractedEntity[]>();
+  // A result linking the same target twice is listed twice; every reader
+  // dedupes by entity id.
+  for (const result of manifestResults) {
+    for (const relationship of result.relationships) {
+      const key = incomingKey(
+        result.entity.type,
+        relationship.type,
+        relationship.to,
+      );
+      const list = incomingByTarget.get(key);
+      if (list === undefined) incomingByTarget.set(key, [result.entity]);
+      else list.push(result.entity);
+    }
+  }
+  return {
+    resultsById: new Map(
+      manifestResults.map((manifestResult) => [
+        manifestResult.entity.id,
+        manifestResult,
+      ]),
+    ),
+    incomingByTarget,
+  };
+}
+
 function entitiesById(
   manifestResults: readonly ExtractionResult[],
 ): ReadonlyMap<string, ExtractedEntity> {
@@ -58,16 +105,11 @@ function outgoingTargets(
 }
 
 function incomingSources(lookup: IncomingLookup): readonly ExtractedEntity[] {
-  return lookup.manifestResults.flatMap((result) => {
-    if (result.entity.type !== lookup.type) return [];
-    return result.relationships.some(
-      (relationship) =>
-        relationship.type === lookup.relationshipType &&
-        relationship.to === lookup.targetId,
-    )
-      ? [result.entity]
-      : [];
-  });
+  return (
+    lookup.index.incomingByTarget.get(
+      incomingKey(lookup.type, lookup.relationshipType, lookup.targetId),
+    ) ?? []
+  );
 }
 
 function uniqueEntities(
@@ -213,15 +255,10 @@ function createDiagnostic(
 
 function coverageForRequirement(
   result: ExtractionResult,
-  manifestResults: readonly ExtractionResult[],
+  index: CoverageIndex,
   entities: ReadonlyMap<string, ExtractedEntity>,
 ): RequirementCoverage {
-  const resultsById = new Map(
-    manifestResults.map((manifestResult) => [
-      manifestResult.entity.id,
-      manifestResult,
-    ]),
-  );
+  const resultsById = index.resultsById;
   const scenarios = outgoingTargets({
     result,
     relationshipType: "specified_by",
@@ -242,7 +279,7 @@ function coverageForRequirement(
       entities,
     }),
     ...incomingSources({
-      manifestResults,
+      index,
       targetId: result.entity.id,
       relationshipType: "validates",
       type: "test",
@@ -253,7 +290,7 @@ function coverageForRequirement(
       const scenarioResult = resultsById.get(scenario.id);
       return [
         ...incomingSources({
-          manifestResults,
+          index,
           targetId: scenario.id,
           relationshipType: "validates",
           type: "test",
@@ -331,6 +368,7 @@ export function createCoverageDepthQualityDiagnostics(
 ): readonly QualityDiagnostic[] {
   const entities = entitiesById(manifestResults);
   const superseded = supersededRequirementIds(manifestResults);
+  const index = coverageIndex(manifestResults);
   return manifestResults
     .filter(
       (result) =>
@@ -339,7 +377,7 @@ export function createCoverageDepthQualityDiagnostics(
     )
     .flatMap((result) => {
       const diagnostic = createDiagnostic(
-        coverageForRequirement(result, manifestResults, entities),
+        coverageForRequirement(result, index, entities),
         proofByRequirement.get(result.entity.id),
       );
       return diagnostic === undefined ? [] : [diagnostic];

package/src/public/impact/full-kb-quality.ts

@@ -47,6 +47,12 @@ type FullKbQualityDiagnosticsOptions = {
   readonly now?: Date;
   readonly proofSnapshot?: string;
   readonly checkedAt?: string;
+  /**
+   * The per-contract receipt bindings kb_coverage uses (a Prolog
+   * TestId -> binding hash dict), or null for strict snapshot binding. Read
+   * lazily so a check without proof evidence never pays for it.
+   */
+  readonly proofTestBindings?: () => Promise<string | null>;
 };
 
 type CoverageEvidencePayload = Readonly<{
@@ -633,6 +639,7 @@ async function loadCoverageProofEvidence(
   requirementCount: number,
   proofSnapshot: string | undefined,
   checkedAt: string | undefined,
+  proofTestBindings: (() => Promise<string | null>) | undefined,
 ): Promise<
   ReadonlyMap<
     string,
@@ -653,6 +660,12 @@ async function loadCoverageProofEvidence(
   }
   let payload: CoverageEvidencePayload;
   try {
+    // Judge receipts with the binding kb_coverage uses; under strict snapshot
+    // binding any unrelated change since kibi prove would read every receipt
+    // as stale and bring back the weak-depth review.
+    const bindings = (await proofTestBindings?.()) ?? null;
+    const binding =
+      bindings === null ? "strict_snapshot, _{}" : `per_contract, ${bindings}`;
     // W1 push-down: the slim evidence projection returns only the fields the
     // quality diagnostics consume, keeping the response far below the output
     // capacity limit on large KBs (the full coverage report rows were the
@@ -660,7 +673,7 @@ async function loadCoverageProofEvidence(
     payload = await runOperationJsonQuery<CoverageEvidencePayload>(
       prolog as PrologPort,
       "discovery.pl",
-      `discovery:coverage_evidence_json(${toPrologList([])}, ${toPrologAtom(proofSnapshot)}, ${toPrologAtom(checkedAt)}, ${PROOF_RECEIPT_MAX_AGE_SECONDS}, JsonString)`,
+      `discovery:coverage_evidence_json(${toPrologList([])}, ${binding}, ${toPrologAtom(proofSnapshot)}, ${toPrologAtom(checkedAt)}, ${PROOF_RECEIPT_MAX_AGE_SECONDS}, JsonString)`,
       "Quality diagnostic coverage evidence",
     );
   } catch {
@@ -776,6 +789,7 @@ export async function collectFullKbQualityDiagnostics(
     manifestResults.filter((result) => result.entity.type === "req").length,
     options.proofSnapshot,
     options.checkedAt,
+    options.proofTestBindings,
   );
   const coverageDepthDiagnostics = createCoverageDepthQualityDiagnostics(
     manifestResults,

package/src/public/impact/requirement-quality.ts

@@ -70,55 +70,111 @@ function targetHasType(
   return targetType === undefined || targetType === type;
 }
 
+type FanoutIndex = {
+  readonly relationshipsByEntityId: ReadonlyMap<
+    string,
+    readonly ExtractionResult["relationships"][number][]
+  >;
+  readonly implementerIdsByRequirementId: ReadonlyMap<
+    string,
+    readonly string[]
+  >;
+  readonly dependentRequirementIdsByRequirementId: ReadonlyMap<
+    string,
+    readonly string[]
+  >;
+};
+
+/** One pass over every relationship, so each requirement's fanout is a lookup. */
+function fanoutIndex(results: readonly ExtractionResult[]): FanoutIndex {
+  const relationshipsByEntityId = new Map<
+    string,
+    ExtractionResult["relationships"][number][]
+  >();
+  const implementerIdsByRequirementId = new Map<string, string[]>();
+  const dependentRequirementIdsByRequirementId = new Map<string, string[]>();
+  const append = (
+    index: Map<string, string[]>,
+    key: string,
+    value: string,
+  ): void => {
+    const list = index.get(key);
+    if (list === undefined) index.set(key, [value]);
+    else list.push(value);
+  };
+  for (const result of results) {
+    const relationships = relationshipsByEntityId.get(result.entity.id);
+    if (relationships === undefined) {
+      relationshipsByEntityId.set(result.entity.id, [...result.relationships]);
+    } else {
+      relationships.push(...result.relationships);
+    }
+    for (const relationship of result.relationships) {
+      if (relationship.type === "implements") {
+        append(
+          implementerIdsByRequirementId,
+          relationship.to,
+          result.entity.id,
+        );
+      }
+      if (relationship.type === "depends_on" && result.entity.type === "req") {
+        append(
+          dependentRequirementIdsByRequirementId,
+          relationship.to,
+          result.entity.id,
+        );
+      }
+    }
+  }
+  return {
+    relationshipsByEntityId,
+    implementerIdsByRequirementId,
+    dependentRequirementIdsByRequirementId,
+  };
+}
+
 function collectFanout(
   requirementId: string,
-  results: readonly ExtractionResult[],
+  index: FanoutIndex,
   typesByEntityId: ReadonlyMap<string, string>,
 ): RequirementFanout {
-  const implementingSymbolIds: string[] = [];
   const scenarioIds: string[] = [];
   const testIds: string[] = [];
   const dependentRequirementIds: string[] = [];
 
-  for (const result of results) {
-    for (const relationship of result.relationships) {
-      if (
-        relationship.type === "implements" &&
-        relationship.to === requirementId
-      ) {
-        implementingSymbolIds.push(result.entity.id);
-      }
-      if (
-        result.entity.id === requirementId &&
-        relationship.type === "specified_by" &&
-        targetHasType(relationship.to, "scenario", typesByEntityId)
-      ) {
-        scenarioIds.push(relationship.to);
-      }
-      if (
-        result.entity.id === requirementId &&
-        (relationship.type === "verified_by" ||
-          relationship.type === "covered_by") &&
-        targetHasType(relationship.to, "test", typesByEntityId)
-      ) {
-        testIds.push(relationship.to);
-      }
-      if (relationship.type === "depends_on") {
-        if (
-          result.entity.id === requirementId &&
-          targetHasType(relationship.to, "req", typesByEntityId)
-        ) {
-          dependentRequirementIds.push(relationship.to);
-        }
-        if (relationship.to === requirementId && result.entity.type === "req") {
-          dependentRequirementIds.push(result.entity.id);
-        }
-      }
+  // rationale: every requirement this is called for is in the index, so the
+  // fallback list is never read.
+  // Stryker disable next-line ArrayDeclaration
+  const relationships = index.relationshipsByEntityId.get(requirementId) ?? [];
+  for (const relationship of relationships) {
+    if (
+      relationship.type === "specified_by" &&
+      targetHasType(relationship.to, "scenario", typesByEntityId)
+    ) {
+      scenarioIds.push(relationship.to);
+    }
+    if (
+      (relationship.type === "verified_by" ||
+        relationship.type === "covered_by") &&
+      targetHasType(relationship.to, "test", typesByEntityId)
+    ) {
+      testIds.push(relationship.to);
+    }
+    if (
+      relationship.type === "depends_on" &&
+      targetHasType(relationship.to, "req", typesByEntityId)
+    ) {
+      dependentRequirementIds.push(relationship.to);
     }
   }
+  dependentRequirementIds.push(
+    ...(index.dependentRequirementIdsByRequirementId.get(requirementId) ?? []),
+  );
 
   return {
-    implementingSymbolIds: sortedUnique(implementingSymbolIds),
+    implementingSymbolIds: sortedUnique(
+      index.implementerIdsByRequirementId.get(requirementId) ?? [],
+    ),
     scenarioIds: sortedUnique(scenarioIds),
     testIds: sortedUnique(testIds),
     dependentRequirementIds: sortedUnique(dependentRequirementIds),
@@ -145,9 +201,10 @@ function createBroadRequirementDiagnostics(
   results: readonly ExtractionResult[],
 ): readonly KibiImpactDiagnostic[] {
   const typesByEntityId = entityTypeById(results);
+  const index = fanoutIndex(results);
   return results.flatMap((result) => {
     if (!isCurrentRequirement(result)) return [];
-    const fanout = collectFanout(result.entity.id, results, typesByEntityId);
+    const fanout = collectFanout(result.entity.id, index, typesByEntityId);
     if (!exceedsBroadThreshold(fanout)) return [];
     if (isUmbrellaRequirement(result)) return [];
 

package/src/public/operations/check-executor.ts

@@ -225,6 +225,35 @@ export function uncompiledBranchStoreViolation(
   };
 }
 
+/**
+ * The branch store this check reads, when the engine is known to read it, as
+ * the place to keep parsed source analyses. A read-only detached snapshot
+ * and an unknown store (an explicit --kb-path) get no cache.
+ */
+// implements REQ-cli-check
+export function analysisCacheDir(
+  context: OperationContext,
+  workspaceRoot: string,
+  options: CheckExecutionOptions,
+): string | undefined {
+  if (
+    context.branchAttachment === undefined &&
+    options.branchStoreAttached !== true
+  ) {
+    return undefined;
+  }
+  try {
+    const attachment =
+      context.branchAttachment ?? resolveBranchAttachment(workspaceRoot);
+    if ("storePath" in attachment && attachment.readOnly === undefined) {
+      return attachment.storePath;
+    }
+  } catch {
+    // A branch that cannot be resolved gets no cache.
+  }
+  return undefined;
+}
+
 // implements REQ-kibi-operation-interface-parity, REQ-002
 export async function executeCheck(
   args: CheckInput,
@@ -239,6 +268,10 @@ export async function executeCheck(
       ? snapshotEvidence.snapshot.hash
       : undefined;
     const checkedAt = context.clock().toISOString();
+    const proofTestBindings = async () => {
+      const { perContractTestBindings } = await import("./specs/reporting.js");
+      return perContractTestBindings({ ...context, prolog });
+    };
     // Enforcement policy is Kibi-owned and deterministic from the installed
     // version. `args.rules` is an invocation-time diagnostic selector only.
     const rulesAllowlist = resolveCheckRules(args);
@@ -316,6 +349,7 @@ export async function executeCheck(
                 workspaceRoot,
                 ...(proofSnapshot !== undefined ? { proofSnapshot } : {}),
                 checkedAt,
+                proofTestBindings,
                 now: context.clock(),
                 ...maxDiagnosticsOption,
               });
@@ -378,6 +412,7 @@ export async function executeCheck(
       prolog,
       workspaceRoot,
       rulesAllowlist,
+      analysisCacheDir(context, workspaceRoot, options),
     );
     const originReviewFindings = await collectOriginReviewViolations(
       prolog,
@@ -400,7 +435,11 @@ export async function executeCheck(
     const evidenceFloorFindings = await collectEvidenceFloorViolations(
       context,
       rulesAllowlist,
-      { freshEvidence: args.freshEvidence === true },
+      {
+        freshEvidence: args.freshEvidence === true,
+        checkedAt,
+        snapshotEvidence,
+      },
     );
     const proofContractClaimFindings =
       await collectProofContractClaimViolations(context, rulesAllowlist);
@@ -442,6 +481,7 @@ export async function executeCheck(
             workspaceRoot,
             ...(proofSnapshot !== undefined ? { proofSnapshot } : {}),
             checkedAt,
+            proofTestBindings,
             now: context.clock(),
             ...maxDiagnosticsOption,
           });

package/src/public/operations/discovery-executors.ts

@@ -10,6 +10,7 @@ import {
   type IntentSearchAnalysis,
   type IntentSearchFacets,
   type IntentSearchMatch,
+  type MarkdownBodyCache,
   type SourceLocation,
   executeIntentSearch,
   questionPaths,
@@ -18,6 +19,12 @@ import {
 import { classifyActivation } from "../../operations/bootstrap/activation.js";
 import { SwiplResolutionError } from "../../prolog/swipl-resolver.js";
 import { type SearchAnswer, buildSearchAnswer } from "../../search-answer.js";
+import {
+  type SearchHintsAnalysis,
+  buildSearchHints,
+  searchHintsNote,
+  searchHintsTrigger,
+} from "../../search-hints.js";
 import { rankEntities } from "../../search-ranking.js";
 import type { SearchMatch } from "../../search-ranking.js";
 import { resolveBranchAttachment } from "../../utils/branch-resolver.js";
@@ -51,7 +58,11 @@ import {
   runOperationJsonQuery,
   toPrologAtom,
 } from "./prolog-json.js";
-import type { OperationContext, PrologPort } from "./runtime-types.js";
+import type {
+  CapabilityRegistry,
+  OperationContext,
+  PrologPort,
+} from "./runtime-types.js";
 import type { OperationResult } from "./types.js";
 import { readWorkspaceSnapshot } from "./workspace-snapshot.js";
 
@@ -176,6 +187,7 @@ export type SearchInput = {
   readonly minScore?: number;
   readonly fields?: "summary" | "full";
   readonly answer?: boolean;
+  readonly hints?: boolean;
 };
 
 export type SearchPayload = {
@@ -185,7 +197,9 @@ export type SearchPayload = {
   /** Rows in `results`: the page this call returned. */
   readonly returned: number;
   readonly truncated?: boolean;
-  readonly queryAnalysis?: IntentSearchAnalysis;
+  readonly queryAnalysis?: IntentSearchAnalysis & {
+    readonly hints?: SearchHintsAnalysis;
+  };
   readonly answer?: SearchAnswer;
   /** The Kibi branch whose store was searched, when the runtime attached one. */
   readonly branch?: string | null;
@@ -912,6 +926,51 @@ function questionPathHint(
     : ` The question names ${list}; their words were left out of the topic. Pass them as sourceLocations to also see the requirements linked to those files.`;
 }
 
+/**
+ * Hints from the workspace's kibi.search-hints.v1 provider. A host without a
+ * plugin runtime, or a registry that fails to load, gives no hints rather than
+ * failing the search.
+ */
+// implements REQ-kibi-search-hints-host
+async function searchHintsFor(
+  context: OperationContext,
+  options: Omit<
+    Parameters<typeof buildSearchHints>[0],
+    "resolution" | "workspaceRoot"
+  >,
+): Promise<SearchHintsAnalysis | undefined> {
+  if (!context.ensurePlugins) return undefined;
+  let resolution: Awaited<ReturnType<CapabilityRegistry["resolveSearchHints"]>>;
+  try {
+    resolution = await (await context.ensurePlugins()).resolveSearchHints();
+  } catch (error) {
+    // A configured provider that cannot load is reported, not thrown: the
+    // lexical answer stands on its own.
+    const trigger = searchHintsTrigger(options.analysis);
+    return trigger === null
+      ? undefined
+      : {
+          trigger,
+          provider: null,
+          items: [],
+          diagnostics: [
+            {
+              pluginId: "unresolved",
+              packageName: null,
+              mode: "replace",
+              code: "provider_unavailable",
+              message: error instanceof Error ? error.message : String(error),
+            },
+          ],
+        };
+  }
+  return buildSearchHints({
+    ...options,
+    resolution,
+    workspaceRoot: context.workspaceRoot,
+  });
+}
+
 export async function executeSearch(
   input: SearchInput,
   context: OperationContext,
@@ -928,6 +987,7 @@ export async function executeSearch(
     minScore,
     fields = "summary",
     answer,
+    hints: hintsWanted = true,
   } = input;
   const trimmedQuery = query.trim();
   if (!trimmedQuery) {
@@ -960,10 +1020,19 @@ export async function executeSearch(
         ...(minScore !== undefined ? { minScore } : {}),
       } as const;
       validateIntentSearchInput(intentInput);
+      let corpus:
+        | {
+            entities: readonly Record<string, unknown>[];
+            bodies: MarkdownBodyCache;
+          }
+        | undefined;
       const intentResult = await executeIntentSearch(
         intentInput,
         prolog,
         context.workspaceRoot,
+        (entities, bodies) => {
+          corpus = { entities, bodies };
+        },
       );
       const paginated = paginateResults(intentResult.matches, limit, offset);
       // The answer layer summarizes the whole ranking, so it belongs to the
@@ -982,6 +1051,22 @@ export async function executeSearch(
       const topUngoverned = answerLayer?.ungoverned.find(
         (entry) => entry.rank === 1,
       );
+      // Hints come after the lexical answer and never change it; a strong
+      // answer never reaches a provider.
+      const hints =
+        hintsWanted &&
+        offset === 0 &&
+        corpus !== undefined &&
+        searchHintsTrigger(intentResult.analysis) !== null
+          ? await searchHintsFor(context, {
+              query: trimmedQuery,
+              analysis: intentResult.analysis,
+              entities: corpus.entities,
+              bodies: corpus.bodies,
+              governingIds: (answerLayer?.governing ?? []).map((req) => req.id),
+              prolog,
+            })
+          : undefined;
       const text = `${
         intentResult.matches.length === 0
           ? `No intent search results for '${trimmedQuery}' (abstained). No entity shares enough of the question's words: ask again in the words and language the KB is written in, or pass sourceLocations.`
@@ -991,7 +1076,7 @@ export async function executeSearch(
               .join(
                 ", ",
               )}${answerLayer ? `. Governing: ${answerLayer.governing.map((req) => req.id).join(", ") || "none found"}` : ""}${topUngoverned ? ` (the top match ${topUngoverned.id} is linked to no requirement)` : ""}.`
-      }${questionPathHint(trimmedQuery, sourceLocations)}${CONTRADICTION_QUESTION.test(trimmedQuery) ? CONTRADICTION_HINT : ""}${storeNote}`;
+      }${searchHintsNote(hints)}${questionPathHint(trimmedQuery, sourceLocations)}${CONTRADICTION_QUESTION.test(trimmedQuery) ? CONTRADICTION_HINT : ""}${storeNote}`;
       return {
         content: [{ type: "text", text }],
         structuredContent: {
@@ -999,7 +1084,10 @@ export async function executeSearch(
           count: intentResult.matches.length,
           returned: paginated.length,
           truncated: offset + paginated.length < intentResult.matches.length,
-          queryAnalysis: intentResult.analysis,
+          queryAnalysis:
+            hints !== undefined
+              ? { ...intentResult.analysis, hints }
+              : intentResult.analysis,
           ...(answerLayer ? { answer: answerLayer } : {}),
           ...branchFields,
         },