kibi-cli 0.2.7 → 0.3.0

package/dist/cli.js

@@ -19,10 +19,15 @@ 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";
@@ -59,6 +64,63 @@ program
     .action(async (type, options) => {
     await 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 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")
     .description("Check KB consistency and integrity")

package/dist/commands/aggregated-checks.js

@@ -23,8 +23,7 @@ export async function runAggregatedChecks(prolog, rulesAllowlist, requireAdr = f
     try {
         const result = await prolog.query(query);
         if (!result.success) {
-            console.warn("Aggregated checks query failed, falling back to individual checks");
-            return [];
+            throw new Error(`Aggregated checks query failed: ${result.error || "Unknown error"}`);
         }
         let violationsDict;
         try {
@@ -39,8 +38,7 @@ export async function runAggregatedChecks(prolog, rulesAllowlist, requireAdr = f
             violationsDict = parsed;
         }
         catch (parseError) {
-            console.warn("Failed to parse violations JSON:", parseError);
-            return [];
+            throw new Error(`Failed to parse violations JSON: ${parseError instanceof Error ? parseError.message : String(parseError)}`);
         }
         for (const ruleViolations of Object.values(violationsDict)) {
             for (const v of ruleViolations) {
@@ -59,7 +57,7 @@ export async function runAggregatedChecks(prolog, rulesAllowlist, requireAdr = f
         return violations;
     }
     catch (error) {
-        console.warn("Error running aggregated checks:", error);
-        return [];
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Error running aggregated checks: ${message}`);
     }
 }

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

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

package/dist/commands/check.js

@@ -16,24 +16,24 @@
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 import * as path from "node:path";
+import { extractFromManifest } from "../extractors/manifest.js";
 import { PrologProcess } from "../prolog.js";
 import { escapeAtom } 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 { 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 { RULES, getEffectiveRules, } from "../utils/rule-registry.js";
 import { runAggregatedChecks } from "./aggregated-checks.js";
 import { getCurrentBranch } from "./init-helpers.js";
+import { discoverSourceFiles } from "./sync/discovery.js";
 // implements REQ-006
 export async function checkCommand(options) {
     let prolog = null;
     let attached = false;
     try {
-        // Resolve KB path with priority:
-        // --kb-path > git branch --show-current > KIBI_BRANCH env > develop > main
         let resolvedKbPath = "";
         if (options.kbPath) {
             resolvedKbPath = options.kbPath;
@@ -54,13 +54,32 @@ export async function checkCommand(options) {
             // fallback to main if develop isn't present? keep path consistent
             resolvedKbPath = path.join(process.cwd(), ".kb/branches", branch || "main");
         }
-        // If --staged mode requested, run staged-symbol traceability gate.
-        // We skip creating the main prolog session entirely in this path.
         if (options.staged) {
             const minLinks = options.minLinks ? Number(options.minLinks) : 1;
             let tempCtx = null;
             try {
-                // Get staged files
+                const config = loadConfig(process.cwd());
+                const manifestLookup = new Map();
+                const { manifestFiles } = await discoverSourceFiles(process.cwd(), config.paths);
+                for (const manifestPath of manifestFiles) {
+                    try {
+                        const entries = extractFromManifest(manifestPath);
+                        for (const entry of entries) {
+                            // Prefer the per-symbol sourceFile; fall back to entity.source or manifest path
+                            const sourceFile = entry.sourceFile || entry.entity.source || manifestPath;
+                            const key = `${sourceFile}:${entry.entity.title}`;
+                            // Extract requirement links (implements relationships to REQ-*)
+                            const links = entry.relationships
+                                .filter((r) => r.type === "implements" &&
+                                r.to.match(/^[A-Z][A-Z0-9\-_]*$/))
+                                .map((r) => r.to);
+                            manifestLookup.set(key, { id: entry.entity.id, links });
+                        }
+                    }
+                    catch {
+                        // Ignore manifest parsing errors
+                    }
+                }
                 const stagedFiles = getStagedFiles();
                 if (!stagedFiles || stagedFiles.length === 0) {
                     console.log("No staged files found.");
@@ -89,7 +108,7 @@ export async function checkCommand(options) {
                 const allSymbols = [];
                 for (const f of codeFiles) {
                     try {
-                        const symbols = extractSymbolsFromStagedFile(f);
+                        const symbols = extractSymbolsFromStagedFile(f, manifestLookup);
                         if (symbols?.length) {
                             allSymbols.push(...symbols);
                         }
@@ -108,12 +127,10 @@ export async function checkCommand(options) {
                 }
                 // Create temp KB
                 tempCtx = await createTempKb(resolvedKbPath);
-                // Write overlay facts THEN consult so Prolog sees the changed_symbol facts
                 const overlayFacts = createOverlayFacts(allSymbols);
                 const fs = await import("node:fs/promises");
                 await fs.writeFile(tempCtx.overlayPath, overlayFacts, "utf8");
                 await consultOverlay(tempCtx);
-                // Validate staged symbols using the temp KB prolog session
                 const violationsRaw = await validateStagedSymbols({
                     minLinks,
                     prolog: tempCtx.prolog,
@@ -153,13 +170,11 @@ export async function checkCommand(options) {
         }
         attached = true;
         const violations = [];
-        // Load config to get rule enablement settings
         const config = loadConfig(process.cwd());
         const checksConfig = config.checks ?? {
             rules: Object.fromEntries(RULES.map((r) => [r.name, true])),
             symbolTraceability: { requireAdr: false },
         };
-        // Get effective rules based on config and CLI --rules filter
         const effectiveRules = getEffectiveRules(checksConfig.rules, options.rules);
         // Helper to conditionally run a check by name
         async function runCheck(name, fn, ...args) {
@@ -250,7 +265,6 @@ export async function checkCommand(options) {
 }
 async function checkMustPriorityCoverage(prolog) {
     const violations = [];
-    // Find all must-priority requirements
     const mustReqs = await findMustPriorityReqs(prolog);
     for (const reqId of mustReqs) {
         const entityResult = await prolog.query(`kb_entity('${reqId}', req, Props)`);
@@ -324,9 +338,7 @@ async function getAllEntityIds(prolog, type) {
 }
 async function checkNoDanglingRefs(prolog) {
     const violations = [];
-    // Get all entity IDs once
     const allEntityIds = new Set(await getAllEntityIds(prolog));
-    // Get all relationships by querying all known relationship types
     const relTypes = [
         "depends_on",
         "verified_by",
@@ -379,7 +391,6 @@ async function checkNoDanglingRefs(prolog) {
 }
 async function checkNoCycles(prolog) {
     const violations = [];
-    // Get all depends_on relationships
     const depsResult = await prolog.query("findall([From,To], kb_relationship(depends_on, From, To), Deps)");
     if (!depsResult.success || !depsResult.bindings.Deps) {
         return violations;
@@ -393,7 +404,6 @@ async function checkNoCycles(prolog) {
     if (!content) {
         return violations;
     }
-    // Build adjacency map
     const graph = new Map();
     const depMatches = content.matchAll(/\[([^,]+),([^\]]+)\]/g);
     for (const depMatch of depMatches) {
@@ -407,7 +417,6 @@ async function checkNoCycles(prolog) {
             fromList.push(to);
         }
     }
-    // DFS to detect cycles
     const visited = new Set();
     const recStack = new Set();
     function hasCycleDFS(node, path) {
@@ -429,7 +438,6 @@ async function checkNoCycles(prolog) {
         recStack.delete(node);
         return null;
     }
-    // Check each node for cycles
     for (const node of graph.keys()) {
         if (!visited.has(node)) {
             const cyclePath = hasCycleDFS(node, []);
@@ -472,15 +480,12 @@ async function checkRequiredFields(prolog, allEntityIds) {
     for (const entityId of allEntityIds) {
         const result = await prolog.query(`kb_entity('${entityId}', Type, Props)`);
         if (result.success && result.bindings.Props) {
-            // Parse properties list: [key1=value1, key2=value2, ...]
             const propsStr = result.bindings.Props;
             const propKeys = new Set();
-            // Extract keys from Props
             const keyMatches = propsStr.matchAll(/(\w+)\s*=/g);
             for (const match of keyMatches) {
                 propKeys.add(match[1]);
             }
-            // Check for missing required fields
             for (const field of required) {
                 if (!propKeys.has(field)) {
                     violations.push({
@@ -515,7 +520,6 @@ async function checkDeprecatedAdrs(prolog) {
         .split(",")
         .map((id) => id.trim().replace(/^'|'$/g, ""));
     for (const adrId of adrIds) {
-        // Get source for better error message
         const entityResult = await prolog.query(`kb_entity('${adrId}', adr, Props)`);
         let source = "";
         if (entityResult.success && entityResult.bindings.Props) {
@@ -585,10 +589,8 @@ async function checkSymbolTraceability(prolog, requireAdr) {
     if (!result.success || !result.bindings.Violations) {
         return violations;
     }
-    // Parse the violations from Prolog format
     const violationsStr = result.bindings.Violations;
     if (violationsStr && violationsStr !== "[]") {
-        // Parse each violation term
         const violationRegex = /violation\(([^,]+),'?([^',]+)'?,([^,]+),([^,]+),'?([^']*)'?\)/g;
         let match;
         do {

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;AAI9D,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,CAsCZ;AAGD,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,QAAQ,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,GAC9C,OAAO,CAAC,CAAC,CAAC,CAcZ;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,CAsBZ;AAGD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,EACpC,UAAU,EAAE,OAAO,EACnB,YAAY,EAAE,MAAM,GACnB,IAAI,CAQN"}

package/dist/commands/discovery-shared.js

@@ -0,0 +1,280 @@
+import path from "node:path";
+import Table from "cli-table3";
+import { PrologProcess, resolveKbPlPath } from "../prolog.js";
+import { escapeAtom } from "../prolog/codec.js";
+import { getCurrentBranch } from "./init-helpers.js";
+// implements REQ-003
+export async function withAttachedBranchProlog(callback) {
+    let prolog = null;
+    let attached = false;
+    try {
+        prolog = new PrologProcess({ timeout: 120000 });
+        await prolog.start();
+        await prolog.query("set_prolog_flag(answer_write_options, [max_depth(0), spacing(next_argument)])");
+        let branch;
+        try {
+            branch = process.env.KIBI_BRANCH || (await getCurrentBranch(process.cwd()));
+        }
+        catch {
+            branch = process.env.KIBI_BRANCH || "main";
+        }
+        const kbPath = path.join(process.cwd(), ".kb/branches", branch);
+        const attachResult = await prolog.query(`kb_attach('${escapeAtom(kbPath)}')`);
+        if (!attachResult.success) {
+            throw new Error(`Failed to attach KB: ${attachResult.error || "Unknown error"}`);
+        }
+        attached = true;
+        return await callback(prolog);
+    }
+    finally {
+        if (prolog) {
+            if (attached) {
+                try {
+                    await prolog.query("kb_detach");
+                }
+                catch { }
+            }
+            try {
+                await prolog.terminate();
+            }
+            catch { }
+        }
+    }
+}
+// implements REQ-003
+export async function withPrologProcess(callback) {
+    const prolog = new PrologProcess({ timeout: 120000 });
+    try {
+        await prolog.start();
+        ;
+        prolog.useOneShotMode = true;
+        await prolog.query("set_prolog_flag(answer_write_options, [max_depth(0), spacing(next_argument)])");
+        return await callback(prolog);
+    }
+    finally {
+        try {
+            await prolog.terminate();
+        }
+        catch { }
+    }
+}
+// implements REQ-003
+export async function resolveCurrentKbPath() {
+    let branch;
+    try {
+        branch = process.env.KIBI_BRANCH || (await getCurrentBranch(process.cwd()));
+    }
+    catch {
+        branch = process.env.KIBI_BRANCH || "main";
+    }
+    return path.join(process.cwd(), ".kb/branches", branch);
+}
+// implements REQ-003
+export function resolveCoreModulePath(fileName) {
+    return path.join(path.dirname(resolveKbPlPath()), fileName);
+}
+// implements REQ-003
+export async function runJsonModuleQuery(prolog, fileName, goal, errorLabel, kbPath) {
+    const modulePath = escapeAtom(resolveCoreModulePath(fileName).replace(/\\/g, "/"));
+    const wrappedGoal = kbPath
+        ? `(use_module('${modulePath}'), kb_attach('${escapeAtom(kbPath)}'), ${goal}, kb_detach)`
+        : `(use_module('${modulePath}'), ${goal})`;
+    const result = await prolog.query(wrappedGoal);
+    if (!result.success) {
+        throw new Error(`${errorLabel}: ${result.error || "Unknown error"}`);
+    }
+    const rawJson = result.bindings.JsonString;
+    if (!rawJson) {
+        throw new Error(`${errorLabel}: missing JsonString binding`);
+    }
+    let parsed = JSON.parse(rawJson);
+    if (typeof parsed === "string") {
+        parsed = JSON.parse(parsed);
+    }
+    return parsed;
+}
+// implements REQ-003
+export function printDiscoveryResult(format, structured, fallbackText) {
+    if (format === "json") {
+        console.log(JSON.stringify(structured, null, 2));
+        return;
+    }
+    const rendered = renderDiscoveryTable(structured);
+    console.log(rendered || fallbackText);
+}
+function renderDiscoveryTable(structured) {
+    if (!structured || typeof structured !== "object") {
+        return null;
+    }
+    const payload = structured;
+    if (Array.isArray(payload.results)) {
+        return renderSearchTable(payload);
+    }
+    if (typeof payload.branch === "string" && typeof payload.syncState === "string") {
+        return renderStatusTable(payload);
+    }
+    if (Array.isArray(payload.nodes) && Array.isArray(payload.edges)) {
+        return renderGraphTable(payload);
+    }
+    if (Array.isArray(payload.rows) && payload.summary && typeof payload.summary === "object") {
+        return renderCoverageTable(payload);
+    }
+    if (Array.isArray(payload.rows)) {
+        return renderGapsTable(payload);
+    }
+    return null;
+}
+function renderSearchTable(payload) {
+    const rows = Array.isArray(payload.results) ? payload.results : [];
+    const table = new Table({
+        head: ["ID", "Type", "Title", "Score", "Reasons", "Snippet"],
+        wordWrap: true,
+        colWidths: [20, 10, 32, 8, 28, 44],
+    });
+    for (const row of rows) {
+        const match = row;
+        const entity = (match.entity ?? {});
+        const reasons = Array.isArray(match.reasons) ? match.reasons.join(", ") : "";
+        table.push([
+            stringifyCell(entity.id),
+            stringifyCell(entity.type),
+            stringifyCell(entity.title),
+            stringifyCell(match.score),
+            reasons,
+            stringifyCell(match.snippet),
+        ]);
+    }
+    return [
+        `Search results: ${stringifyCell(payload.count)} total`,
+        table.toString(),
+    ].join("\n");
+}
+function renderStatusTable(payload) {
+    const table = new Table({
+        head: ["Field", "Value"],
+        colWidths: [18, 72],
+        wordWrap: true,
+    });
+    table.push(["Branch", stringifyCell(payload.branch)], ["Sync State", stringifyCell(payload.syncState)], ["Dirty", stringifyCell(payload.dirty)], ["Snapshot", stringifyCell(payload.snapshotId)], ["Synced At", stringifyCell(payload.syncedAt)], ["KB Path", stringifyCell(payload.kbPath)]);
+    return table.toString();
+}
+function renderGapsTable(payload) {
+    const rows = Array.isArray(payload.rows) ? payload.rows : [];
+    const table = new Table({
+        head: ["ID", "Type", "Status", "Missing", "Present", "Source"],
+        colWidths: [20, 10, 12, 24, 24, 40],
+        wordWrap: true,
+    });
+    for (const row of rows) {
+        const item = row;
+        table.push([
+            stringifyCell(item.id),
+            stringifyCell(item.type),
+            stringifyCell(item.status),
+            joinCells(item.missingRelationships),
+            joinCells(item.presentRelationships),
+            stringifyCell(item.source),
+        ]);
+    }
+    return [`Gap rows: ${stringifyCell(payload.count)}`, table.toString()].join("\n");
+}
+function renderCoverageTable(payload) {
+    const summary = (payload.summary ?? {});
+    const rows = Array.isArray(payload.rows) ? payload.rows : [];
+    const summaryTable = new Table({
+        head: ["Metric", "Value"],
+        colWidths: [24, 16],
+    });
+    for (const [key, value] of Object.entries(summary)) {
+        summaryTable.push([key, stringifyCell(value)]);
+    }
+    const firstRow = rows[0];
+    const isRequirementCoverage = firstRow && Object.hasOwn(firstRow, "scenarioCount");
+    const table = isRequirementCoverage
+        ? new Table({
+            head: ["ID", "Status", "Priority", "Coverage", "Scen", "Tests", "Symbols", "Gaps"],
+            colWidths: [20, 12, 12, 18, 8, 8, 10, 28],
+            wordWrap: true,
+        })
+        : new Table({
+            head: ["ID", "Type", "Coverage", "Details", "Gaps"],
+            colWidths: [20, 10, 18, 28, 28],
+            wordWrap: true,
+        });
+    for (const row of rows) {
+        const item = row;
+        if (isRequirementCoverage) {
+            table.push([
+                stringifyCell(item.id),
+                stringifyCell(item.status),
+                stringifyCell(item.priority),
+                stringifyCell(item.coverageStatus),
+                stringifyCell(item.scenarioCount),
+                stringifyCell(item.testCount),
+                stringifyCell(item.transitiveSymbolCount),
+                joinCells(item.gaps),
+            ]);
+        }
+        else {
+            table.push([
+                stringifyCell(item.id),
+                stringifyCell(item.type),
+                stringifyCell(item.coverageStatus),
+                `req=${stringifyCell(item.directRequirementCount)} test=${stringifyCell(item.testCount)} count=${stringifyCell(item.count)}`,
+                joinCells(item.gaps),
+            ]);
+        }
+    }
+    return [summaryTable.toString(), table.toString()].join("\n\n");
+}
+function renderGraphTable(payload) {
+    const nodes = Array.isArray(payload.nodes) ? payload.nodes : [];
+    const edges = Array.isArray(payload.edges) ? payload.edges : [];
+    const nodeTable = new Table({
+        head: ["Node ID", "Type", "Title", "Status"],
+        colWidths: [22, 10, 36, 12],
+        wordWrap: true,
+    });
+    for (const row of nodes) {
+        const item = row;
+        nodeTable.push([
+            stringifyCell(item.id),
+            stringifyCell(item.type),
+            stringifyCell(item.title),
+            stringifyCell(item.status),
+        ]);
+    }
+    const edgeTable = new Table({
+        head: ["Relationship", "From", "To"],
+        colWidths: [18, 22, 22],
+        wordWrap: true,
+    });
+    for (const row of edges) {
+        const item = row;
+        edgeTable.push([
+            stringifyCell(item.type),
+            stringifyCell(item.from),
+            stringifyCell(item.to),
+        ]);
+    }
+    return [
+        `Nodes: ${nodes.length}  Edges: ${edges.length}  Truncated: ${stringifyCell(payload.truncated)}`,
+        nodeTable.toString(),
+        edgeTable.toString(),
+    ].join("\n\n");
+}
+function stringifyCell(value) {
+    if (value === null || value === undefined || value === "") {
+        return "-";
+    }
+    if (typeof value === "string") {
+        return value;
+    }
+    return String(value);
+}
+function joinCells(value) {
+    if (!Array.isArray(value) || value.length === 0) {
+        return "-";
+    }
+    return value.map((item) => stringifyCell(item)).join(", ");
+}