kibi-cli 2.17.0 → 2.19.0

package/dist/utils/content-freshness.js

@@ -0,0 +1,171 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+*/
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import * as path from "node:path";
+import { load as parseYAML } from "js-yaml";
+import { hashManifestWithCoordinates } from "../commands/sync/cache.js";
+import { KB_PATHS, isSymbolsManifestPath } from "./kb-paths.js";
+/** Stale-reason codes that compare file times only. */
+export const MTIME_SOURCE_REASON_CODES = new Set([
+    "indexed_source_newer",
+    "knowledge_source_newer",
+    "documentation_source_newer",
+]);
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function readJson(file) {
+    try {
+        return JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+/**
+ * Content evidence recorded by the last compilation: the store's sync-cache
+ * source hashes, and the per-symbol `sourceHash` of the generated coordinate
+ * artifact. A file whose bytes match that evidence has not changed since it
+ * was compiled, however new its mtime (a fresh clone, a checkout, a touch).
+ * Without either kind of evidence a reason is kept.
+ */
+class CompiledContentEvidence {
+    workspaceRoot;
+    hashes;
+    coordinateHashes = null;
+    manifestState = new Map();
+    constructor(workspaceRoot, storePath) {
+        this.workspaceRoot = workspaceRoot;
+        const cache = record(readJson(path.join(storePath, "sync-cache.json")));
+        const hashes = record(cache?.hashes) ?? {};
+        this.hashes = Object.fromEntries(Object.entries(hashes).filter((entry) => typeof entry[1] === "string"));
+    }
+    fileHash(relative) {
+        try {
+            return sha256(readFileSync(path.resolve(this.workspaceRoot, relative)));
+        }
+        catch {
+            return null;
+        }
+    }
+    manifest(key) {
+        const cached = this.manifestState.get(key);
+        if (cached)
+            return cached;
+        const absolute = path.resolve(this.workspaceRoot, key);
+        let state = { matches: false, sources: new Set() };
+        try {
+            const matches = hashManifestWithCoordinates(this.workspaceRoot, absolute, path.join(path.dirname(absolute), "symbol-coordinates.yaml")) === this.hashes[key];
+            const parsed = record(parseYAML(readFileSync(absolute, "utf8")));
+            const sources = new Set();
+            for (const symbol of Array.isArray(parsed?.symbols)
+                ? parsed.symbols
+                : []) {
+                const row = record(symbol);
+                const source = row?.sourceFile ?? row?.source;
+                if (typeof source === "string" && source.length > 0)
+                    sources.add(source.replaceAll("\\", "/"));
+            }
+            state = { matches, sources };
+        }
+        catch {
+            // An unreadable manifest proves nothing; keep the reason.
+        }
+        this.manifestState.set(key, state);
+        return state;
+    }
+    coordinates() {
+        if (this.coordinateHashes)
+            return this.coordinateHashes;
+        const byFile = new Map();
+        // The coordinate artifact is content evidence in its own right: kb_upsert
+        // and sync record each symbol's source hash there. Consult the canonical
+        // artifact even when its manifest was never hashed (an untracked,
+        // upsert-only `.kb/symbols.yaml` that sync could not see).
+        const artifacts = new Set([
+            path.resolve(this.workspaceRoot, KB_PATHS.symbolCoordinates),
+        ]);
+        for (const key of Object.keys(this.hashes)) {
+            if (!isSymbolsManifestPath(key) || !key.endsWith("symbols.yaml"))
+                continue;
+            artifacts.add(path.resolve(this.workspaceRoot, path.dirname(key), "symbol-coordinates.yaml"));
+        }
+        for (const artifact of artifacts) {
+            if (!existsSync(artifact))
+                continue;
+            try {
+                const parsed = record(parseYAML(readFileSync(artifact, "utf8")));
+                for (const value of Object.values(record(parsed?.coordinates) ?? {})) {
+                    const row = record(value);
+                    if (typeof row?.sourceFile !== "string" ||
+                        typeof row.sourceHash !== "string")
+                        continue;
+                    const hashes = byFile.get(row.sourceFile) ?? new Set();
+                    hashes.add(row.sourceHash);
+                    byFile.set(row.sourceFile, hashes);
+                }
+            }
+            catch {
+                // A malformed artifact proves nothing.
+            }
+        }
+        this.coordinateHashes = byFile;
+        return byFile;
+    }
+    /** True only when recorded evidence proves the file's bytes are unchanged. */
+    unchanged(relative) {
+        const key = relative.replaceAll("\\", "/");
+        if (isSymbolsManifestPath(key) && this.hashes[key] !== undefined)
+            return this.manifest(key).matches;
+        const current = this.fileHash(key);
+        if (current === null)
+            return false;
+        const cached = this.hashes[key];
+        if (cached !== undefined)
+            return cached === current;
+        const coordinate = this.coordinates().get(key);
+        if (coordinate !== undefined && coordinate.size > 0)
+            return [...coordinate].every((hash) => hash === current);
+        // A code file that is only referenced from a symbol manifest is covered
+        // by that manifest's composite hash, which includes every referenced
+        // source's bytes.
+        return Object.keys(this.hashes).some((manifestKey) => {
+            if (!isSymbolsManifestPath(manifestKey))
+                return false;
+            const manifest = this.manifest(manifestKey);
+            return manifest.sources.has(key) && manifest.matches;
+        });
+    }
+}
+/**
+ * Drop mtime-only stale reasons whose file content provably matches what the
+ * store compiled. Reasons without such evidence are kept.
+ */
+// implements REQ-cli-status-pre-first-sync
+export function confirmSourceNewerReasons(workspaceRoot, storePath, reasons) {
+    const kept = [];
+    const dropped = [];
+    let evidence = null;
+    for (const reason of reasons) {
+        if (typeof reason.code !== "string" ||
+            !MTIME_SOURCE_REASON_CODES.has(reason.code) ||
+            typeof reason.path !== "string") {
+            kept.push(reason);
+            continue;
+        }
+        evidence ??= new CompiledContentEvidence(workspaceRoot, storePath);
+        if (evidence.unchanged(reason.path))
+            dropped.push(reason);
+        else
+            kept.push(reason);
+    }
+    return { kept, dropped };
+}

package/dist/utils/symbol-manifest-layout.d.ts

@@ -0,0 +1,9 @@
+import { type Document } from "yaml";
+/**
+ * Render the `symbols` sequence of a parsed manifest, and every collection
+ * inside it, as block YAML. `kibi init` writes `symbols: []`, a flow
+ * sequence, and kibi-cli before 2.18.0 appended to it, so older manifests
+ * keep every symbol on that one line. Returns true when the layout changed.
+ */
+export declare function blockifySymbolManifest(doc: Document): boolean;
+//# sourceMappingURL=symbol-manifest-layout.d.ts.map

package/dist/utils/symbol-manifest-layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-manifest-layout.d.ts","sourceRoot":"","sources":["../../src/utils/symbol-manifest-layout.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAA8B,MAAM,MAAM,CAAC;AAEjE;;;;;GAKG;AAEH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAO7D"}

package/dist/utils/symbol-manifest-layout.js

@@ -0,0 +1,18 @@
+import { isCollection, isSeq, visit } from "yaml";
+/**
+ * Render the `symbols` sequence of a parsed manifest, and every collection
+ * inside it, as block YAML. `kibi init` writes `symbols: []`, a flow
+ * sequence, and kibi-cli before 2.18.0 appended to it, so older manifests
+ * keep every symbol on that one line. Returns true when the layout changed.
+ */
+// implements REQ-kibi-hooks-flow-manifest, REQ-core-persistence
+export function blockifySymbolManifest(doc) {
+    const symbols = doc.get("symbols", true);
+    if (!isSeq(symbols) || symbols.flow !== true)
+        return false;
+    visit(symbols, (_key, node) => {
+        if (isCollection(node))
+            node.flow = false;
+    });
+    return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cli",
-  "version": "2.17.0",
+  "version": "2.19.0",
   "type": "module",
   "description": "Kibi CLI for knowledge base management",
   "engines": {
@@ -235,7 +235,7 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-core": "^0.18.2",
+    "kibi-core": "^0.20.0",
     "kibi-plugin-builtin": "^0.5.0",
     "kibi-plugin-sdk": "^0.5.0",
     "kibi-swipl": "^1.0.1",

package/src/public/operations/contracts.ts

@@ -441,10 +441,10 @@ const BASE_DATA_SCHEMAS: Readonly<
     sourceType: stringValue,
   }),
   kb_skills_read: objectData({ content: stringValue }, ["content"]),
-  kb_query: objectData({ entities: recordArray, count: integerValue }, [
-    "entities",
-    "count",
-  ]),
+  kb_query: objectData(
+    { entities: recordArray, count: integerValue, factQuery: recordValue },
+    ["entities", "count"],
+  ),
   kb_search: objectData(
     {
       results: valueArray,
@@ -452,6 +452,8 @@ const BASE_DATA_SCHEMAS: Readonly<
       truncated: booleanValue,
       queryAnalysis: recordValue,
       answer: recordValue,
+      branch: { type: ["string", "null"] },
+      branchStore: recordValue,
     },
     ["results", "count"],
   ),
@@ -476,6 +478,7 @@ const BASE_DATA_SCHEMAS: Readonly<
     staleReasons: recordArray,
     staleReasonCount: integerValue,
     staleReasonsTruncated: booleanValue,
+    notices: recordArray,
     branchAttachment: recordValue,
     proofSnapshotChanges: recordArray,
     proofSnapshotChangeCount: integerValue,