kibi-cli 0.10.1 → 0.11.0

package/dist/cli.d.ts.map

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

package/dist/cli.js

@@ -30,6 +30,7 @@ import { queryCommand } from "./commands/query.js";
 import { searchCommand } from "./commands/search.js";
 import { statusCommand } from "./commands/status.js";
 import { syncCommand } from "./commands/sync.js";
+import { usageMetricsCommand } from "./commands/usage-metrics.js";
 const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 const VERSION = packageJson.version ?? "0.1.0";
 // implements REQ-003
@@ -167,6 +168,14 @@ program
     .command("doctor")
     .description("Diagnose KB setup and configuration")
     .action(withExitCode(async () => doctorCommand()));
+program
+    .command("usage-metrics")
+    .description("Report usage and quality metrics from .kb/usage.log")
+    .option("--format <format>", "Output format: json|table", "table")
+    .option("--limit <n>", "Limit top zero-result source files", "10")
+    .action(withExitCode(async (options) => {
+    return usageMetricsCommand(options);
+}));
 program
     .command("branch")
     .description("Manage branch KBs")

package/dist/commands/usage-metrics.d.ts

@@ -0,0 +1,8 @@
+import type { CommandResult } from "../cli.js";
+interface UsageMetricsOptions {
+    format?: "json" | "table";
+    limit?: string;
+}
+export declare function usageMetricsCommand(options: UsageMetricsOptions): Promise<CommandResult | undefined>;
+export {};
+//# sourceMappingURL=usage-metrics.d.ts.map

package/dist/commands/usage-metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-metrics.d.ts","sourceRoot":"","sources":["../../src/commands/usage-metrics.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/C,UAAU,mBAAmB;IAC3B,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAkED,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAuBpC"}

package/dist/commands/usage-metrics.js

@@ -0,0 +1,323 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import Table from "cli-table3";
+// implements REQ-003
+export async function usageMetricsCommand(options) {
+    const limit = Number.parseInt(options.limit || "10", 10);
+    if (!Number.isFinite(limit) || limit < 1) {
+        console.error("Error: --limit must be a positive integer");
+        return { exitCode: 1 };
+    }
+    const usageLogPath = path.join(process.cwd(), ".kb", "usage.log");
+    if (!existsSync(usageLogPath)) {
+        console.error(`Error: usage log not found at ${usageLogPath}`);
+        return { exitCode: 1 };
+    }
+    const rows = parseUsageLog(readFileSync(usageLogPath, "utf8"));
+    const report = buildUsageMetricsReport(rows, limit);
+    if (options.format === "json") {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    console.log(renderUsageMetricsReport(report));
+    return;
+}
+function parseUsageLog(contents) {
+    const rows = [];
+    for (const [index, line] of contents.split(/\r?\n/).entries()) {
+        const trimmed = line.trim();
+        if (!trimmed) {
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to parse .kb/usage.log line ${index + 1}: ${message}`);
+        }
+        if (!parsed || typeof parsed !== "object") {
+            throw new Error(`Failed to parse .kb/usage.log line ${index + 1}: expected object`);
+        }
+        rows.push(parsed);
+    }
+    return rows;
+}
+function buildUsageMetricsReport(rows, limit) {
+    const timestamps = rows
+        .map((row) => row.timestamp)
+        .filter((value) => typeof value === "string")
+        .sort((left, right) => left.localeCompare(right));
+    const toolCounts = new Map();
+    const branchCounts = new Map();
+    const zeroResultToolCounts = new Map();
+    const zeroResultSourceFileCounts = new Map();
+    const upsertErrorCategories = new Map();
+    const violationTrend = [];
+    let successCount = 0;
+    let errorCount = 0;
+    let telemetryCompleteCount = 0;
+    let telemetryMissingCount = 0;
+    let zeroResultCount = 0;
+    for (const row of rows) {
+        increment(toolCounts, normalizeKey(row.tool, "unknown"));
+        increment(branchCounts, normalizeKey(row.active_branch || row.branch, "unknown"));
+        const outcome = getOutcome(row);
+        if (outcome === "success") {
+            successCount += 1;
+        }
+        if (outcome === "error") {
+            errorCount += 1;
+        }
+        if (hasCompleteTelemetry(row)) {
+            telemetryCompleteCount += 1;
+        }
+        else {
+            telemetryMissingCount += 1;
+        }
+        if (isZeroResult(row)) {
+            zeroResultCount += 1;
+            increment(zeroResultToolCounts, normalizeKey(row.tool, "unknown"));
+            const sourceFile = getSourceFile(row);
+            if (sourceFile) {
+                increment(zeroResultSourceFileCounts, sourceFile);
+            }
+        }
+        if (row.tool === "kb_check" &&
+            typeof row.violation_count === "number" &&
+            typeof row.timestamp === "string") {
+            violationTrend.push({
+                timestamp: row.timestamp,
+                violationCount: row.violation_count,
+            });
+        }
+        if (row.tool === "kb_upsert" && outcome === "error") {
+            increment(upsertErrorCategories, categorizeUpsertError(row.error_message ?? row.error));
+        }
+    }
+    violationTrend.sort((left, right) => left.timestamp.localeCompare(right.timestamp));
+    return {
+        rowCount: rows.length,
+        dateRange: {
+            first: timestamps[0] ?? null,
+            last: timestamps.at(-1) ?? null,
+        },
+        toolCounts: mapToSortedObject(toolCounts),
+        branchCounts: mapToSortedObject(branchCounts),
+        outcomeCounts: {
+            success: successCount,
+            error: errorCount,
+        },
+        telemetry: {
+            completeCount: telemetryCompleteCount,
+            missingCount: telemetryMissingCount,
+            completenessRate: rows.length === 0 ? 0 : telemetryCompleteCount / rows.length,
+        },
+        zeroResults: {
+            count: zeroResultCount,
+            rate: rows.length === 0 ? 0 : zeroResultCount / rows.length,
+            byTool: mapToSortedObject(zeroResultToolCounts),
+            topSourceFiles: sortCountEntries(zeroResultSourceFileCounts)
+                .slice(0, limit)
+                .map(([sourceFile, count]) => ({ sourceFile, count })),
+        },
+        kbCheck: {
+            violationTrend,
+        },
+        upsertErrors: {
+            categories: mapToSortedObject(upsertErrorCategories),
+        },
+    };
+}
+function hasCompleteTelemetry(row) {
+    if (row.telemetry_status === "provided") {
+        return true;
+    }
+    if (row.telemetry_status === "missing") {
+        return false;
+    }
+    return row.telemetry !== null && row.telemetry !== undefined;
+}
+function getOutcome(row) {
+    if (row.status === "success" || row.status === "error") {
+        return row.status;
+    }
+    if (row.success === true) {
+        return "success";
+    }
+    if (row.success === false) {
+        return "error";
+    }
+    return null;
+}
+function isZeroResult(row) {
+    if (row.zero_results === true) {
+        return true;
+    }
+    if (row.zero_results === false) {
+        return false;
+    }
+    if (row.result_count === 0) {
+        return true;
+    }
+    return row.result_summary === "0 results";
+}
+function getSourceFile(row) {
+    if (typeof row.sourceFile === "string" && row.sourceFile.trim()) {
+        return row.sourceFile;
+    }
+    if (row.args &&
+        typeof row.args.sourceFile === "string" &&
+        row.args.sourceFile.trim()) {
+        return row.args.sourceFile;
+    }
+    if (row.business_args &&
+        typeof row.business_args.sourceFile === "string" &&
+        row.business_args.sourceFile.trim()) {
+        return row.business_args.sourceFile;
+    }
+    return null;
+}
+function categorizeUpsertError(errorMessage) {
+    if (!errorMessage) {
+        return "Unknown error";
+    }
+    if (errorMessage.startsWith("Entity validation failed:")) {
+        return "Entity validation failed";
+    }
+    if (errorMessage.startsWith("Relationship source must match the upserted entity")) {
+        return "Relationship source must match the upserted entity";
+    }
+    const semicolonIndex = errorMessage.indexOf(";");
+    if (semicolonIndex > 0) {
+        return errorMessage.slice(0, semicolonIndex).trim();
+    }
+    const colonIndex = errorMessage.indexOf(":");
+    if (colonIndex > 0) {
+        return errorMessage.slice(0, colonIndex).trim();
+    }
+    return errorMessage.trim() || "Unknown error";
+}
+function increment(counts, key) {
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+}
+function normalizeKey(value, fallback) {
+    return typeof value === "string" && value.trim() ? value : fallback;
+}
+function sortCountEntries(counts) {
+    return [...counts.entries()].sort(([leftKey, leftCount], [rightKey, rightCount]) => rightCount - leftCount || leftKey.localeCompare(rightKey));
+}
+function mapToSortedObject(counts) {
+    return Object.fromEntries(sortCountEntries(counts));
+}
+function renderUsageMetricsReport(report) {
+    const sections = [
+        renderSummaryTable(report),
+        renderCountsTable("Tool Counts", "Tool", report.toolCounts),
+        renderCountsTable("Branch Counts", "Branch", report.branchCounts),
+        renderCountsTable("Outcome Counts", "Outcome", report.outcomeCounts),
+        renderTelemetryTable(report),
+        renderZeroResultsTable(report),
+        renderViolationTrendTable(report),
+        renderCountsTable("Upsert Error Categories", "Category", report.upsertErrors.categories),
+    ].filter(Boolean);
+    return sections.join("\n\n");
+}
+function renderSummaryTable(report) {
+    const table = new Table({
+        head: ["Field", "Value"],
+        colWidths: [24, 56],
+        wordWrap: true,
+    });
+    table.push(["Row Count", String(report.rowCount)], ["First Timestamp", report.dateRange.first ?? "-"], ["Last Timestamp", report.dateRange.last ?? "-"]);
+    return table.toString();
+}
+function renderCountsTable(title, label, counts) {
+    const entries = Object.entries(counts);
+    const table = new Table({
+        head: [label, "Count"],
+        colWidths: [48, 12],
+        wordWrap: true,
+    });
+    if (entries.length === 0) {
+        table.push(["-", "0"]);
+    }
+    else {
+        for (const [key, count] of entries) {
+            table.push([key, String(count)]);
+        }
+    }
+    return `${title}\n${table.toString()}`;
+}
+function renderTelemetryTable(report) {
+    const table = new Table({
+        head: ["Metric", "Value"],
+        colWidths: [32, 28],
+        wordWrap: true,
+    });
+    table.push(["Complete", String(report.telemetry.completeCount)], ["Missing", String(report.telemetry.missingCount)], ["Completeness Rate", formatRate(report.telemetry.completenessRate)]);
+    return `Telemetry\n${table.toString()}`;
+}
+function renderZeroResultsTable(report) {
+    const summary = new Table({
+        head: ["Metric", "Value"],
+        colWidths: [32, 28],
+        wordWrap: true,
+    });
+    summary.push(["Count", String(report.zeroResults.count)], ["Rate", formatRate(report.zeroResults.rate)]);
+    const byTool = new Table({
+        head: ["Tool", "Count"],
+        colWidths: [48, 12],
+        wordWrap: true,
+    });
+    const byToolEntries = Object.entries(report.zeroResults.byTool);
+    if (byToolEntries.length === 0) {
+        byTool.push(["-", "0"]);
+    }
+    else {
+        for (const [tool, count] of byToolEntries) {
+            byTool.push([tool, String(count)]);
+        }
+    }
+    const sourceFiles = new Table({
+        head: ["Source File", "Zero Results"],
+        colWidths: [48, 14],
+        wordWrap: true,
+    });
+    if (report.zeroResults.topSourceFiles.length === 0) {
+        sourceFiles.push(["-", "0"]);
+    }
+    else {
+        for (const entry of report.zeroResults.topSourceFiles) {
+            sourceFiles.push([entry.sourceFile, String(entry.count)]);
+        }
+    }
+    return [
+        "Zero Results",
+        summary.toString(),
+        "Zero-Result Counts By Tool",
+        byTool.toString(),
+        "Zero-Result Source Files",
+        sourceFiles.toString(),
+    ].join("\n");
+}
+function renderViolationTrendTable(report) {
+    const table = new Table({
+        head: ["Timestamp", "Violations"],
+        colWidths: [32, 12],
+        wordWrap: true,
+    });
+    if (report.kbCheck.violationTrend.length === 0) {
+        table.push(["-", "0"]);
+    }
+    else {
+        for (const entry of report.kbCheck.violationTrend) {
+            table.push([entry.timestamp, String(entry.violationCount)]);
+        }
+    }
+    return `KB Check Violation Trend\n${table.toString()}`;
+}
+function formatRate(value) {
+    return `${(value * 100).toFixed(1)}%`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cli",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "type": "module",
   "description": "Kibi CLI for knowledge base management",
   "engines": {