kibi-cli 0.1.5 → 0.1.6

package/dist/traceability/git-staged.js

@@ -0,0 +1,141 @@
+import { execSync } from "node:child_process";
+function runGit(cmd) {
+    try {
+        return execSync(cmd, { encoding: "utf8" });
+    }
+    catch (err) {
+        // wrap common errors
+        const e = err;
+        const message = e && e.message ? String(e.message) : String(err);
+        throw new Error(`git command failed: ${cmd} -> ${message}`);
+    }
+}
+/**
+ * Parse null-separated name-status output from git
+ */
+export function parseNameStatusNull(input) {
+    if (!input)
+        return [];
+    const entries = input.split("\0").filter(Boolean);
+    return entries.map((entry) => {
+        const cols = entry.split("\t");
+        const status = cols[0];
+        const parts = cols.slice(1);
+        return { status, parts };
+    });
+}
+const SUPPORTED_EXT = new Set([
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".mts",
+    ".cts",
+    ".mjs",
+    ".cjs",
+]);
+function hasSupportedExt(p) {
+    for (const ext of SUPPORTED_EXT) {
+        if (p.endsWith(ext))
+            return true;
+    }
+    return false;
+}
+/**
+ * Parse unified diff hunks (new-file coordinates) from git diff output
+ */
+export function parseHunksFromDiff(diffText, isNewFile = false) {
+    const ranges = [];
+    if (!diffText)
+        return ranges;
+    const regex = /^@@\s+-\d+(?:,\d+)?\s+\+(\d+)(?:,(\d+))?\s+@@/gm;
+    let m = null;
+    while (true) {
+        m = regex.exec(diffText);
+        if (!m)
+            break;
+        const c = Number.parseInt(m[1], 10);
+        const d = m[2] ? Number.parseInt(m[2], 10) : 1;
+        if (d > 0) {
+            ranges.push({ start: c, end: c + d - 1 });
+        }
+    }
+    // If no hunks found and isNewFile, treat entire file as changed (we'll use a sentinel later)
+    if (ranges.length === 0 && isNewFile) {
+        // Represent as a single wide range starting at 1, using Number.MAX_SAFE_INTEGER as a sentinel end to indicate unknown (we'll set later)
+        ranges.push({ start: 1, end: Number.MAX_SAFE_INTEGER });
+    }
+    return ranges;
+}
+/**
+ * Get staged files with statuses, hunks and content.
+ */
+export function getStagedFiles() {
+    // 1. get staged name-status -z
+    let nameStatus;
+    try {
+        nameStatus = runGit("git diff --cached --name-status -z --diff-filter=ACMRD");
+    }
+    catch (err) {
+        throw new Error(`failed to list staged files: ${String(err)}`);
+    }
+    const parsed = parseNameStatusNull(nameStatus);
+    const results = [];
+    for (const entry of parsed) {
+        const statusRaw = entry.status;
+        const status = statusRaw[0] || "M";
+        if (status === "D") {
+            // deleted files: skip but log via console.debug
+            console.debug(`Skipping deleted file (staged): ${entry.parts.join(" -> ")}`);
+            continue;
+        }
+        // handle renames: parts = [old, new]
+        let path = entry.parts[0] ?? "";
+        let oldPath;
+        if (status === "R") {
+            if (entry.parts.length >= 2) {
+                oldPath = entry.parts[0];
+                path = entry.parts[1];
+            }
+        }
+        if (!hasSupportedExt(path)) {
+            console.debug(`Skipping unsupported extension: ${path}`);
+            continue;
+        }
+        // 4. compute hunks using git diff --cached -U0 -- <path>
+        let diffText = "";
+        try {
+            // use new path for diff; quote the path to handle spaces
+            diffText = runGit(`git diff --cached -U0 -- "${path.replace(/"/g, '\\"')}"`);
+        }
+        catch (err) {
+            console.debug(`Failed to get diff for ${path}: ${String(err)}`);
+            diffText = "";
+        }
+        // determine if new file: status 'A' or diff contains /dev/null in old file path
+        const isNewFile = status === "A" || /\bdev\/null\b/.test(diffText);
+        const hunkRanges = parseHunksFromDiff(diffText, isNewFile);
+        // 5. read staged content using git show :<path>
+        let content;
+        try {
+            content = runGit(`git show :"${path.replace(/"/g, '\\"')}"`);
+        }
+        catch (err) {
+            // binary or deleted in index
+            const e = err;
+            const em = e && e.message ? String(e.message) : String(err);
+            console.debug(`Skipping binary/deleted or unreadable staged file ${path}: ${em}`);
+            continue;
+        }
+        // If we had a new-file sentinel (end = MAX_SAFE_INTEGER) set a realistic end as content lines
+        const lines = content.split(/\r?\n/);
+        for (const r of hunkRanges) {
+            if (r.end === Number.MAX_SAFE_INTEGER) {
+                r.end = Math.max(1, lines.length);
+            }
+        }
+        results.push({ path, status, oldPath, hunkRanges, content });
+    }
+    return results;
+}
+export default getStagedFiles;

package/dist/traceability/symbol-extract.d.ts

@@ -0,0 +1,15 @@
+import type { HunkRange, StagedFile } from "./git-staged.js";
+export interface ExtractedSymbol {
+    id: string;
+    name: string;
+    kind: "function" | "class" | "variable" | "enum" | "unknown";
+    location: {
+        file: string;
+        startLine: number;
+        endLine: number;
+    };
+    hunkRanges: HunkRange[];
+    reqLinks: string[];
+}
+export declare function extractSymbolsFromStagedFile(stagedFile: StagedFile): ExtractedSymbol[];
+//# sourceMappingURL=symbol-extract.d.ts.map

package/dist/traceability/symbol-extract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-extract.d.ts","sourceRoot":"","sources":["../../src/traceability/symbol-extract.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7D,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,GAAG,OAAO,GAAG,UAAU,GAAG,MAAM,GAAG,SAAS,CAAC;IAC7D,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AA0DD,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,UAAU,GACrB,eAAe,EAAE,CAuLnB"}

package/dist/traceability/symbol-extract.js

@@ -0,0 +1,228 @@
+import { createHash } from "node:crypto";
+import { Project, ScriptKind } from "ts-morph";
+import { extractFromManifest } from "../extractors/manifest.js";
+// Simple in-memory cache keyed by blob sha with 30s TTL
+const sourceFileCache = new Map();
+const CACHE_TTL_MS = 30 * 1000;
+const project = new Project({ skipAddingFilesFromTsConfig: true });
+function computeContentSha(content) {
+    const h = createHash("sha256");
+    h.update(content);
+    return h.digest("hex");
+}
+function chooseScriptKind(path) {
+    const lower = path.toLowerCase();
+    if (lower.endsWith(".tsx"))
+        return ScriptKind.TSX;
+    if (lower.endsWith(".ts") || lower.endsWith(".mts") || lower.endsWith(".cts"))
+        return ScriptKind.TS;
+    if (lower.endsWith(".jsx"))
+        return ScriptKind.JSX;
+    return ScriptKind.JS;
+}
+function parseReqDirectives(text) {
+    // look for lines containing implements REQ-123 or implements: REQ-1, REQ-2
+    // Stop at end-of-line and only accept IDs starting with an uppercase letter
+    // to avoid capturing tokens like `export`, `function`, etc.
+    const REQ_ID = "[A-Z][A-Z0-9\\-_]*";
+    const regex = new RegExp(`implements\\s*:?\\s*(${REQ_ID}(?:\\s*,\\s*${REQ_ID})*)\\s*$`, "gim");
+    const reqs = new Set();
+    let m;
+    while ((m = regex.exec(text))) {
+        const list = m[1];
+        for (const part of list.split(/[,\s]+/)) {
+            const p = part.trim();
+            if (!p)
+                continue;
+            reqs.add(p);
+        }
+    }
+    return Array.from(reqs);
+}
+function rangesIntersect(aStart, aEnd, bStart, bEnd) {
+    return aStart <= bEnd && bStart <= aEnd;
+}
+export function extractSymbolsFromStagedFile(stagedFile) {
+    const content = stagedFile.content ?? "";
+    const sha = computeContentSha(content + "|" + stagedFile.path);
+    // TTL cache lookup
+    const now = Date.now();
+    let cached = sourceFileCache.get(sha);
+    if (!cached || now - cached.ts > CACHE_TTL_MS) {
+        // create or recreate SourceFile in project (in-memory)
+        try {
+            const scriptKind = chooseScriptKind(stagedFile.path);
+            const sf = project.createSourceFile(stagedFile.path + "::staged", content, {
+                overwrite: true,
+                scriptKind,
+            });
+            cached = { tsf: sf, ts: now };
+            sourceFileCache.set(sha, cached);
+        }
+        catch (err) {
+            // on parse error, cache null to avoid retry storms briefly
+            cached = { tsf: null, ts: now };
+            sourceFileCache.set(sha, cached);
+        }
+    }
+    const sf = cached.tsf;
+    if (!sf)
+        return [];
+    const results = [];
+    // helpers to compute line spans
+    const getSpan = (startPos, endPos) => {
+        const start = sf.getLineAndColumnAtPos(startPos);
+        const end = sf.getLineAndColumnAtPos(endPos);
+        return { startLine: start.line, endLine: end.line };
+    };
+    // Functions
+    for (const fn of sf.getFunctions()) {
+        if (!fn.isExported())
+            continue;
+        try {
+            const name = fn.getName() ?? "<anonymous>";
+            const nameNode = fn.getNameNode();
+            const start = nameNode ? nameNode.getStart() : fn.getStart();
+            const end = fn.getEnd();
+            const span = getSpan(start, end);
+            const reqLinks = parseReqDirectives(fn.getFullText() +
+                "\n" +
+                fn
+                    .getJsDocs()
+                    .map((d) => d.getFullText())
+                    .join("\n"));
+            const id = resolveSymbolId(stagedFile.path, name);
+            results.push({
+                id,
+                name,
+                kind: "function",
+                location: {
+                    file: stagedFile.path,
+                    startLine: span.startLine,
+                    endLine: span.endLine,
+                },
+                hunkRanges: intersectingHunks(span.startLine, span.endLine, stagedFile.hunkRanges),
+                reqLinks,
+            });
+        }
+        catch { }
+    }
+    // Classes
+    for (const cls of sf.getClasses()) {
+        if (!cls.isExported())
+            continue;
+        try {
+            const name = cls.getName() ?? "<anonymous>";
+            const start = cls.getNameNode()?.getStart() ?? cls.getStart();
+            const end = cls.getEnd();
+            const span = getSpan(start, end);
+            const reqLinks = parseReqDirectives(cls.getText() +
+                "\n" +
+                cls
+                    .getJsDocs()
+                    .map((d) => d.getFullText())
+                    .join("\n"));
+            const id = resolveSymbolId(stagedFile.path, name);
+            results.push({
+                id,
+                name,
+                kind: "class",
+                location: {
+                    file: stagedFile.path,
+                    startLine: span.startLine,
+                    endLine: span.endLine,
+                },
+                hunkRanges: intersectingHunks(span.startLine, span.endLine, stagedFile.hunkRanges),
+                reqLinks,
+            });
+        }
+        catch { }
+    }
+    // Enums
+    for (const en of sf.getEnums()) {
+        if (!en.isExported())
+            continue;
+        try {
+            const name = en.getName() ?? "<anonymous>";
+            const start = en.getNameNode()?.getStart() ?? en.getStart();
+            const end = en.getEnd();
+            const span = getSpan(start, end);
+            const reqLinks = parseReqDirectives(en.getText());
+            const id = resolveSymbolId(stagedFile.path, name);
+            results.push({
+                id,
+                name,
+                kind: "enum",
+                location: {
+                    file: stagedFile.path,
+                    startLine: span.startLine,
+                    endLine: span.endLine,
+                },
+                hunkRanges: intersectingHunks(span.startLine, span.endLine, stagedFile.hunkRanges),
+                reqLinks,
+            });
+        }
+        catch { }
+    }
+    // Variable statements (exported)
+    for (const vs of sf.getVariableStatements()) {
+        if (!vs.isExported())
+            continue;
+        for (const decl of vs.getDeclarations()) {
+            try {
+                const name = decl.getName();
+                const start = decl.getNameNode()?.getStart() ?? decl.getStart();
+                const end = decl.getEnd();
+                const span = getSpan(start, end);
+                const reqLinks = parseReqDirectives(decl.getText());
+                const id = resolveSymbolId(stagedFile.path, name);
+                results.push({
+                    id,
+                    name,
+                    kind: "variable",
+                    location: {
+                        file: stagedFile.path,
+                        startLine: span.startLine,
+                        endLine: span.endLine,
+                    },
+                    hunkRanges: intersectingHunks(span.startLine, span.endLine, stagedFile.hunkRanges),
+                    reqLinks,
+                });
+            }
+            catch { }
+        }
+    }
+    // Filter to only include symbols that intersect with at least one hunk
+    // (unless it's a new file or rename, in which case we include all)
+    const shouldFilterByHunks = stagedFile.status === "M" && stagedFile.hunkRanges.length > 0;
+    if (shouldFilterByHunks) {
+        return results.filter((r) => r.hunkRanges.length > 0);
+    }
+    return results;
+}
+function intersectingHunks(startLine, endLine, hunks) {
+    const out = [];
+    for (const h of hunks) {
+        if (rangesIntersect(startLine, endLine, h.start, h.end))
+            out.push(h);
+    }
+    return out;
+}
+function resolveSymbolId(filePath, name) {
+    try {
+        // attempt to read manifest entries for explicit id (best-effort)
+        // extractFromManifest expects a file path; if manifest not present it will throw — catch it
+        const ents = extractFromManifest(filePath);
+        for (const e of ents) {
+            if (e.entity.title === name)
+                return e.entity.id;
+        }
+    }
+    catch {
+        // ignore
+    }
+    // deterministic id: sha(file:path:name)
+    const h = createHash("sha256");
+    h.update(`${filePath}:${name}`);
+    return h.digest("hex").slice(0, 16);
+}

package/dist/traceability/temp-kb.d.ts

@@ -0,0 +1,14 @@
+import { PrologProcess } from "../prolog.js";
+import type { ExtractedSymbol } from "./symbol-extract";
+export interface TempKbContext {
+    tempDir: string;
+    kbPath: string;
+    overlayPath: string;
+    prolog: PrologProcess;
+}
+declare function consultOverlay(ctx: TempKbContext): Promise<void>;
+export { consultOverlay };
+export declare function createTempKb(baseKbPath: string): Promise<TempKbContext>;
+export declare function createOverlayFacts(symbols: ExtractedSymbol[]): string;
+export declare function cleanupTempKb(tempDir: string): Promise<void>;
+//# sourceMappingURL=temp-kb.d.ts.map

package/dist/traceability/temp-kb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"temp-kb.d.ts","sourceRoot":"","sources":["../../src/traceability/temp-kb.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,aAAa,CAAC;CACvB;AAmDD,iBAAe,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAe/D;AAED,OAAO,EAAE,cAAc,EAAE,CAAC;AAE1B,wBAAsB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CA2C7E;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,MAAM,CAkBrE;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BlE"}

package/dist/traceability/temp-kb.js

@@ -0,0 +1,121 @@
+import { existsSync } from "node:fs";
+import { cp, mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { PrologProcess } from "../prolog.js";
+const prologByTempDir = new Map();
+const cleanupByTempDir = new Map();
+const cleanedTempDirs = new Set();
+function isTraceEnabled() {
+    return Boolean(process.env.KIBI_TRACE || process.env.KIBI_DEBUG);
+}
+function trace(message) {
+    if (isTraceEnabled()) {
+        // eslint-disable-next-line no-console
+        console.log(`[kibi-trace] ${message}`);
+    }
+}
+function escapePrologAtom(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+function createCleanupHandler(tempDir) {
+    let inProgress = false;
+    return () => {
+        if (inProgress || cleanedTempDirs.has(tempDir)) {
+            return;
+        }
+        inProgress = true;
+        void cleanupTempKb(tempDir).catch((error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            trace(`cleanup on signal/exit failed for ${tempDir}: ${message}`);
+        });
+    };
+}
+function registerCleanupHandlers(tempDir) {
+    const handler = createCleanupHandler(tempDir);
+    process.once("exit", handler);
+    process.once("SIGINT", handler);
+    process.once("SIGTERM", handler);
+    cleanupByTempDir.set(tempDir, () => {
+        process.off("exit", handler);
+        process.off("SIGINT", handler);
+        process.off("SIGTERM", handler);
+    });
+}
+async function consultOverlay(ctx) {
+    const prolog = prologByTempDir.get(ctx.tempDir);
+    if (!prolog) {
+        throw new Error(`No Prolog session found for temp dir: ${ctx.tempDir}`);
+    }
+    const consultResult = await prolog.query([
+        `consult(${escapePrologAtom(ctx.overlayPath)})`,
+    ]);
+    if (!consultResult.success) {
+        throw new Error(`Failed to consult overlay facts ${ctx.overlayPath}: ${consultResult.error || "unknown error"}`);
+    }
+}
+export { consultOverlay };
+export async function createTempKb(baseKbPath) {
+    if (!existsSync(baseKbPath)) {
+        throw new Error(`Base KB path does not exist: ${baseKbPath}`);
+    }
+    const tempDir = path.join(tmpdir(), `kibi-precommit-${process.pid}-${Date.now()}`);
+    const kbPath = path.join(tempDir, "kb");
+    const overlayPath = path.join(tempDir, "changed_symbols.pl");
+    trace(`creating temp KB directory ${tempDir}`);
+    await mkdir(tempDir, { recursive: true });
+    trace(`copying base KB ${baseKbPath} -> ${kbPath}`);
+    await cp(baseKbPath, kbPath, { recursive: true });
+    await writeFile(overlayPath, "", "utf8");
+    const prolog = new PrologProcess({ timeout: 120000 });
+    await prolog.start();
+    prologByTempDir.set(tempDir, prolog);
+    // ctx includes prolog so callers can use it directly
+    const ctx = { tempDir, kbPath, overlayPath, prolog };
+    registerCleanupHandlers(tempDir);
+    const attachResult = await prolog.query(`kb_attach(${escapePrologAtom(kbPath)})`);
+    if (!attachResult.success) {
+        await cleanupTempKb(tempDir);
+        throw new Error(`Failed to attach temporary KB at ${kbPath}: ${attachResult.error || "unknown error"}`);
+    }
+    // Caller is expected to write overlay facts and then call consultOverlay(ctx).
+    trace(`temporary KB ready at ${kbPath}`);
+    return ctx;
+}
+export function createOverlayFacts(symbols) {
+    const lines = [];
+    for (const symbol of symbols) {
+        lines.push(`changed_symbol(${escapePrologAtom(symbol.id)}).`);
+        lines.push(`changed_symbol_loc(${escapePrologAtom(symbol.id)}, ${escapePrologAtom(symbol.location.file)}, ${symbol.location.startLine}, 0, ${escapePrologAtom(symbol.name)}).`);
+        // Emit overlay facts for requirement links from code-comment directives.
+        for (const reqId of symbol.reqLinks) {
+            lines.push(`changed_symbol_req(${escapePrologAtom(symbol.id)}, ${escapePrologAtom(reqId)}).`);
+        }
+    }
+    return lines.join("\n");
+}
+export async function cleanupTempKb(tempDir) {
+    if (cleanedTempDirs.has(tempDir)) {
+        return;
+    }
+    cleanedTempDirs.add(tempDir);
+    const unregister = cleanupByTempDir.get(tempDir);
+    if (unregister) {
+        unregister();
+        cleanupByTempDir.delete(tempDir);
+    }
+    const prolog = prologByTempDir.get(tempDir);
+    if (prolog) {
+        try {
+            await prolog.query("kb_detach");
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            trace(`kb_detach failed during cleanup for ${tempDir}: ${message}`);
+        }
+        await prolog.terminate();
+        prologByTempDir.delete(tempDir);
+    }
+    await rm(tempDir, { recursive: true, force: true });
+    trace(`removed temporary KB directory ${tempDir}`);
+}

package/dist/traceability/validate.d.ts

@@ -0,0 +1,17 @@
+import type { PrologProcess } from "../prolog.js";
+export interface ValidationOptions {
+    minLinks: number;
+    prolog: PrologProcess;
+}
+export interface Violation {
+    symbolId: string;
+    name: string;
+    file: string;
+    line: number;
+    column: number;
+    currentLinks: number;
+    requiredLinks: number;
+}
+export declare function validateStagedSymbols(options: ValidationOptions): Promise<Violation[]>;
+export declare function formatViolations(violations: Violation[]): string;
+//# sourceMappingURL=validate.d.ts.map

package/dist/traceability/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/traceability/validate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;CACvB;AAgHD,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,SAAS,EAAE,CAAC,CAqCtB;AAED,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,MAAM,CAiBhE"}