kibi-cli 0.2.8 → 0.4.0

package/dist/cli.d.ts

@@ -1,2 +1,5 @@
-export {};
+/** All command handlers return this instead of calling process.exit(). */
+export interface CommandResult {
+    exitCode?: number;
+}
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAsCA,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/dist/cli.js

@@ -19,13 +19,28 @@ import { readFileSync } from "node:fs";
 import { Command } from "commander";
 import { branchEnsureCommand } from "./commands/branch.js";
 import { checkCommand } from "./commands/check.js";
+import { coverageCommand } from "./commands/coverage.js";
 import { doctorCommand } from "./commands/doctor.js";
+import { gapsCommand } from "./commands/gaps.js";
 import { gcCommand } from "./commands/gc.js";
+import { graphCommand } from "./commands/graph.js";
 import { initCommand } from "./commands/init.js";
 import { queryCommand } from "./commands/query.js";
+import { searchCommand } from "./commands/search.js";
+import { statusCommand } from "./commands/status.js";
 import { syncCommand } from "./commands/sync.js";
 const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 const VERSION = packageJson.version ?? "0.1.0";
+// implements REQ-003
+/** Wraps an async command handler to apply its returned exitCode to process.exitCode. */
+function withExitCode(fn) {
+    return async (...args) => {
+        const result = await fn(...args);
+        if (result && typeof result.exitCode === "number") {
+            process.exitCode = result.exitCode;
+        }
+    };
+}
 const program = new Command();
 program
     .name("kibi")
@@ -35,17 +50,17 @@ program
     .command("init")
     .description("Initialize .kb/ directory")
     .option("--no-hooks", "Do not install git hooks (hooks installed by default)")
-    .action(async (options) => {
-    await initCommand(options);
-});
+    .action(withExitCode(async (options) => {
+    return initCommand(options);
+}));
 program
     .command("sync")
     .description("Sync entities from documents")
     .option("--validate-only", "Perform validation without mutations")
     .option("--rebuild", "Rebuild branch snapshot from scratch (discards current KB)")
-    .action(async (options) => {
-    await syncCommand(options);
-});
+    .action(withExitCode(async (options) => {
+    return syncCommand(options);
+}));
 program
     .command("query [type]")
     .description("Query knowledge base")
@@ -56,8 +71,65 @@ program
     .option("--format <format>", "Output format: json|table", "json")
     .option("--limit <n>", "Limit results", "100")
     .option("--offset <n>", "Skip results", "0")
+    .action(withExitCode(async (type, options) => {
+    return queryCommand(type, options);
+}));
+program
+    .command("search [query]")
+    .description("Search knowledge base metadata and markdown content")
+    .option("--type <type>", "Filter by entity type")
+    .option("--format <format>", "Output format: json|table", "table")
+    .option("--limit <n>", "Limit results", "20")
+    .option("--offset <n>", "Skip results", "0")
+    .action(async (query, options) => {
+    await searchCommand(query, options);
+});
+program
+    .command("status")
+    .description("Show KB snapshot and freshness metadata")
+    .option("--format <format>", "Output format: json|table", "table")
+    .action(async (options) => {
+    await statusCommand(options);
+});
+program
+    .command("gaps [type]")
+    .description("Find entities missing or present on selected relationships")
+    .option("--missing-rel <rels>", "Comma-separated missing relationship filters")
+    .option("--present-rel <rels>", "Comma-separated present relationship filters")
+    .option("--tag <tags>", "Comma-separated tag filter")
+    .option("--source <path>", "Source file substring filter")
+    .option("--limit <n>", "Limit results", "100")
+    .option("--offset <n>", "Skip results", "0")
+    .option("--format <format>", "Output format: json|table", "table")
     .action(async (type, options) => {
-    await queryCommand(type, options);
+    await gapsCommand(type, options);
+});
+program
+    .command("coverage")
+    .description("Generate curated coverage reports")
+    .option("--by <group>", "Coverage mode: req|symbol|type", "req")
+    .option("--tag <tags>", "Comma-separated tag filter")
+    .option("--include-passing", "Include passing rows", false)
+    .option("--no-include-transitive", "Disable transitive symbol coverage")
+    .option("--limit <n>", "Limit results", "100")
+    .option("--offset <n>", "Skip results", "0")
+    .option("--format <format>", "Output format: json|table", "table")
+    .action(async (options) => {
+    await coverageCommand(options);
+});
+program
+    .command("graph")
+    .description("Traverse the KB graph from one or more seed IDs")
+    .option("--from <ids>", "Comma-separated seed IDs")
+    .option("--relationships <rels>", "Comma-separated relationship filter")
+    .option("--direction <direction>", "Direction: outgoing|incoming|both", "outgoing")
+    .option("--depth <n>", "Traversal depth", "1")
+    .option("--entity-types <types>", "Comma-separated entity type filter")
+    .option("--max-nodes <n>", "Maximum node count", "200")
+    .option("--max-edges <n>", "Maximum edge count", "500")
+    .option("--format <format>", "Output format: json|table", "table")
+    .action(async (options) => {
+    await graphCommand(options);
 });
 program
     .command("check")
@@ -68,9 +140,9 @@ program
     .option("--staged", "Run check only against staged changes (experimental)")
     .option("--min-links <n>", "Minimum number of links required for symbol coverage", "1")
     .option("--dry-run", "Do not modify files; only print what would happen")
-    .action(async (options) => {
-    await checkCommand(options);
-});
+    .action(withExitCode(async (options) => {
+    return checkCommand(options);
+}));
 program
     .command("gc")
     .description("Garbage collect stale branch KBs")
@@ -83,9 +155,7 @@ program
 program
     .command("doctor")
     .description("Diagnose KB setup and configuration")
-    .action(async () => {
-    await doctorCommand();
-});
+    .action(withExitCode(async () => doctorCommand()));
 program
     .command("branch")
     .description("Manage branch KBs")
@@ -96,4 +166,11 @@ program
         await branchEnsureCommand(options);
     }
 });
-program.parse(process.argv);
+program
+    .parseAsync(process.argv)
+    .then(() => process.exit(process.exitCode ?? 0))
+    .catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    process.exit(1);
+});

package/dist/commands/check.d.ts

@@ -1,3 +1,5 @@
+import { type Violation } from "../utils/rule-registry.js";
+export type { Violation };
 export interface CheckOptions {
     fix?: boolean;
     kbPath?: string;
@@ -6,12 +8,7 @@ export interface CheckOptions {
     minLinks?: string | number;
     dryRun?: boolean;
 }
-export interface Violation {
-    rule: string;
-    entityId: string;
-    description: string;
-    suggestion?: string;
-    source?: string;
-}
-export declare function checkCommand(options: CheckOptions): Promise<void>;
+export declare function checkCommand(options: CheckOptions): Promise<{
+    exitCode: number;
+}>;
 //# sourceMappingURL=check.d.ts.map

package/dist/commands/check.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AAgDA,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAGD,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA+RvE"}
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AA4CA,OAAO,EAGL,KAAK,SAAS,EAEf,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EAAE,SAAS,EAAE,CAAC;AAK1B,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAGD,wBAAsB,YAAY,CAChC,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA0R/B"}

package/dist/commands/check.js

@@ -18,13 +18,14 @@
 import * as path from "node:path";
 import { extractFromManifest } from "../extractors/manifest.js";
 import { PrologProcess } from "../prolog.js";
-import { escapeAtom } from "../prolog/codec.js";
+import { escapeAtom, parseTriples, parseViolationRows, } from "../prolog/codec.js";
 import { getStagedFiles } from "../traceability/git-staged.js";
 import { validateStagedMarkdown } from "../traceability/markdown-validate.js";
 import { extractSymbolsFromStagedFile, } from "../traceability/symbol-extract.js";
 import { cleanupTempKb, consultOverlay, createOverlayFacts, createTempKb, } from "../traceability/temp-kb.js";
 import { formatViolations as formatStagedViolations, validateStagedSymbols, } from "../traceability/validate.js";
 import { loadConfig } from "../utils/config.js";
+import { safeCleanupProlog } from "../utils/prolog-cleanup.js";
 import { RULES, getEffectiveRules, } from "../utils/rule-registry.js";
 import { runAggregatedChecks } from "./aggregated-checks.js";
 import { getCurrentBranch } from "./init-helpers.js";
@@ -83,7 +84,7 @@ export async function checkCommand(options) {
                 const stagedFiles = getStagedFiles();
                 if (!stagedFiles || stagedFiles.length === 0) {
                     console.log("No staged files found.");
-                    process.exit(0);
+                    return { exitCode: 0 };
                 }
                 const codeFiles = stagedFiles.filter((f) => !f.path.endsWith(".md"));
                 const markdownFiles = stagedFiles.filter((f) => f.path.endsWith(".md"));
@@ -101,9 +102,9 @@ export async function checkCommand(options) {
                         console.log();
                     }
                     if (options.dryRun) {
-                        process.exit(0);
+                        return { exitCode: 0 };
                     }
-                    process.exit(1);
+                    return { exitCode: 1 };
                 }
                 const allSymbols = [];
                 for (const f of codeFiles) {
@@ -119,11 +120,11 @@ export async function checkCommand(options) {
                 }
                 if (allSymbols.length === 0 && markdownFiles.length === 0) {
                     console.log("No exported symbols or markdown entities found in staged files.");
-                    process.exit(0);
+                    return { exitCode: 0 };
                 }
                 if (allSymbols.length === 0) {
                     console.log("✓ No violations found in staged files.");
-                    process.exit(0);
+                    return { exitCode: 0 };
                 }
                 // Create temp KB
                 tempCtx = await createTempKb(resolvedKbPath);
@@ -140,13 +141,13 @@ export async function checkCommand(options) {
                     console.log(violationsFormatted);
                     await cleanupTempKb(tempCtx.tempDir);
                     if (options.dryRun) {
-                        process.exit(0);
+                        return { exitCode: 0 };
                     }
-                    process.exit(1);
+                    return { exitCode: 1 };
                 }
                 console.log("✓ No violations found in staged symbols.");
                 await cleanupTempKb(tempCtx.tempDir);
-                process.exit(0);
+                return { exitCode: 0 };
             }
             catch (err) {
                 console.error(`Error running staged validation: ${err instanceof Error ? err.message : String(err)}`);
@@ -154,9 +155,11 @@ export async function checkCommand(options) {
                     try {
                         await cleanupTempKb(tempCtx.tempDir);
                     }
-                    catch { }
+                    catch {
+                        // best-effort: temp directory may already be cleaned up
+                    }
                 }
-                process.exit(1);
+                return { exitCode: 1 };
             }
         }
         prolog = new PrologProcess({ timeout: 120000 });
@@ -166,7 +169,7 @@ export async function checkCommand(options) {
         if (!attachResult.success) {
             await prolog.terminate();
             console.error(`Error: Failed to attach KB: ${attachResult.error}`);
-            process.exit(1);
+            return { exitCode: 1 };
         }
         attached = true;
         const violations = [];
@@ -203,6 +206,7 @@ export async function checkCommand(options) {
             "required-fields",
             "deprecated-adr-no-successor",
             "domain-contradictions",
+            "strict-fact-shape",
         ];
         const canUseAggregated = Array.from(effectiveRules).every((r) => supportedRules.includes(r));
         if (canUseAggregated) {
@@ -225,10 +229,11 @@ export async function checkCommand(options) {
             }
             await runCheck("deprecated-adr-no-successor", checkDeprecatedAdrs);
             await runCheck("domain-contradictions", checkDomainContradictions);
+            await runCheck("strict-fact-shape", checkStrictFactShape);
         }
         if (violations.length === 0) {
             console.log("✓ No violations found. KB is valid.");
-            process.exit(0);
+            return { exitCode: 0 };
         }
         console.log(`Found ${violations.length} violation(s):`);
         console.log();
@@ -241,26 +246,15 @@ export async function checkCommand(options) {
             }
             console.log();
         }
-        process.exit(1);
+        return { exitCode: 1 };
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         console.error(`Error: ${message}`);
-        process.exit(1);
+        return { exitCode: 1 };
     }
     finally {
-        if (prolog) {
-            if (attached) {
-                try {
-                    await prolog.query("kb_detach");
-                }
-                catch { }
-            }
-            try {
-                await prolog.terminate();
-            }
-            catch { }
-        }
+        await safeCleanupProlog(prolog);
     }
 }
 async function checkMustPriorityCoverage(prolog) {
@@ -545,7 +539,7 @@ async function checkDomainContradictions(prolog) {
     if (!result.success || !result.bindings.Rows) {
         return violations;
     }
-    const rows = parseTripleRows(result.bindings.Rows);
+    const rows = parseTriples(result.bindings.Rows);
     for (const [reqA, reqB, reason] of rows) {
         violations.push({
             rule: "domain-contradictions",
@@ -556,6 +550,22 @@ async function checkDomainContradictions(prolog) {
     }
     return violations;
 }
+async function checkStrictFactShape(prolog) {
+    const violations = [];
+    const result = await prolog.query(`findall(violation(Rule, EntityId, Desc, Sugg, Src),
+      checks:strict_fact_shape_violation(violation(Rule, EntityId, Desc, Sugg, Src)),
+      Violations)`);
+    if (!result.success || !result.bindings.Violations) {
+        return violations;
+    }
+    const violationsStr = result.bindings.Violations;
+    if (violationsStr && violationsStr !== "[]") {
+        for (const v of parseViolationRows(violationsStr)) {
+            violations.push(v);
+        }
+    }
+    return violations;
+}
 async function checkSymbolCoverage(prolog) {
     const violations = [];
     const uncoveredResult = await prolog.query("setof(Symbol, symbol_no_req_coverage(Symbol, _), Symbols)");
@@ -591,40 +601,9 @@ async function checkSymbolTraceability(prolog, requireAdr) {
     }
     const violationsStr = result.bindings.Violations;
     if (violationsStr && violationsStr !== "[]") {
-        const violationRegex = /violation\(([^,]+),'?([^',]+)'?,([^,]+),([^,]+),'?([^']*)'?\)/g;
-        let match;
-        do {
-            match = violationRegex.exec(violationsStr);
-            if (match) {
-                violations.push({
-                    rule: match[1].trim().replace(/^'|'$/g, ""),
-                    entityId: match[2].trim(),
-                    description: match[3].trim().replace(/^"|"$/g, ""),
-                    suggestion: match[4].trim().replace(/^"|"$/g, ""),
-                    source: match[5].trim() || undefined,
-                });
-            }
-        } while (match);
+        for (const v of parseViolationRows(violationsStr)) {
+            violations.push(v);
+        }
     }
     return violations;
 }
-function parseTripleRows(raw) {
-    const cleaned = raw.trim();
-    if (cleaned === "[]" || cleaned.length === 0) {
-        return [];
-    }
-    const rows = [];
-    const rowRegex = /\[([^,]+),([^,]+),([^\]]+)\]/g;
-    let match;
-    do {
-        match = rowRegex.exec(cleaned);
-        if (match) {
-            rows.push([
-                match[1].trim().replace(/^'|'$/g, ""),
-                match[2].trim().replace(/^'|'$/g, ""),
-                match[3].trim().replace(/^'|'$/g, ""),
-            ]);
-        }
-    } while (match);
-    return rows;
-}

package/dist/commands/coverage.d.ts

@@ -0,0 +1,12 @@
+interface CoverageOptions {
+    by?: "req" | "symbol" | "type";
+    tag?: string;
+    includePassing?: boolean;
+    includeTransitive?: boolean;
+    limit?: string;
+    offset?: string;
+    format?: "json" | "table";
+}
+export declare function coverageCommand(options: CoverageOptions): Promise<void>;
+export {};
+//# sourceMappingURL=coverage.d.ts.map

package/dist/commands/coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.d.ts","sourceRoot":"","sources":["../../src/commands/coverage.ts"],"names":[],"mappings":"AAQA,UAAU,eAAe;IACvB,EAAE,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAGD,wBAAsB,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAgC7E"}

package/dist/commands/coverage.js

@@ -0,0 +1,24 @@
+import { escapeAtom } from "../prolog/codec.js";
+import { printDiscoveryResult, resolveCurrentKbPath, runJsonModuleQuery, withPrologProcess, } from "./discovery-shared.js";
+// implements REQ-002, REQ-003
+export async function coverageCommand(options) {
+    await withPrologProcess(async (prolog) => {
+        const kbPath = await resolveCurrentKbPath();
+        const by = options.by || "req";
+        const tags = options.tag
+            ? `[${options.tag
+                .split(",")
+                .map((item) => item.trim())
+                .filter(Boolean)
+                .map((item) => `'${escapeAtom(item)}'`)
+                .join(",")}]`
+            : "[]";
+        const includePassing = options.includePassing ?? false;
+        const includeTransitive = options.includeTransitive ?? true;
+        const limit = Number.parseInt(options.limit || "100", 10);
+        const offset = Number.parseInt(options.offset || "0", 10);
+        const result = await runJsonModuleQuery(prolog, "discovery.pl", `discovery:coverage_report_json('${by}', ${tags}, ${includePassing}, ${includeTransitive}, ${limit}, ${offset}, JsonString)`, "coverage query failed", kbPath);
+        const summary = (result.summary ?? {});
+        printDiscoveryResult(options.format, result, `Coverage summary: ${summary.fullyCovered ?? 0} fully covered out of ${summary.total ?? 0}.`);
+    });
+}

package/dist/commands/discovery-shared.d.ts

@@ -0,0 +1,11 @@
+import { PrologProcess } from "../prolog.js";
+export interface DiscoveryCommandOptions {
+    format?: "json" | "table";
+}
+export declare function withAttachedBranchProlog<T>(callback: (prolog: PrologProcess) => Promise<T>): Promise<T>;
+export declare function withPrologProcess<T>(callback: (prolog: PrologProcess) => Promise<T>): Promise<T>;
+export declare function resolveCurrentKbPath(): Promise<string>;
+export declare function resolveCoreModulePath(fileName: string): string;
+export declare function runJsonModuleQuery<T>(prolog: PrologProcess, fileName: string, goal: string, errorLabel: string, kbPath?: string): Promise<T>;
+export declare function printDiscoveryResult(format: "json" | "table" | undefined, structured: unknown, fallbackText: string): void;
+//# sourceMappingURL=discovery-shared.d.ts.map

package/dist/commands/discovery-shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery-shared.d.ts","sourceRoot":"","sources":["../../src/commands/discovery-shared.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAmB,MAAM,cAAc,CAAC;AAK9D,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAGD,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,QAAQ,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,GAC9C,OAAO,CAAC,CAAC,CAAC,CAkCZ;AAGD,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,QAAQ,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,GAC9C,OAAO,CAAC,CAAC,CAAC,CAYZ;AAGD,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,MAAM,CAAC,CAS5D;AAGD,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE9D;AAGD,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,CAAC,CAAC,CAwBZ;AAGD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,EACpC,UAAU,EAAE,OAAO,EACnB,YAAY,EAAE,MAAM,GACnB,IAAI,CAQN"}