kibi-mcp 0.1.0

package/dist/tools/derive.js

@@ -0,0 +1,311 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+import { parseAtomList, parsePairList } from "./prolog-list.js";
+const RULES = [
+    "transitively_implements",
+    "transitively_depends",
+    "impacted_by_change",
+    "affected_symbols",
+    "coverage_gap",
+    "untested_symbols",
+    "stale",
+    "orphaned",
+    "conflicting",
+    "deprecated_still_used",
+    "current_adr",
+    "adr_chain",
+    "superseded_by",
+    "domain_contradictions",
+];
+export async function handleKbDerive(prolog, args) {
+    const params = args.params ?? {};
+    const { rule } = args;
+    if (!RULES.includes(rule)) {
+        throw new Error(`Unsupported rule '${rule}'`);
+    }
+    let rows = [];
+    switch (rule) {
+        case "transitively_implements":
+            rows = await deriveTransitivelyImplements(prolog, params);
+            break;
+        case "transitively_depends":
+            rows = await deriveTransitivelyDepends(prolog, params);
+            break;
+        case "impacted_by_change":
+            rows = await deriveImpactedByChange(prolog, params);
+            break;
+        case "affected_symbols":
+            rows = await deriveAffectedSymbols(prolog, params);
+            break;
+        case "coverage_gap":
+            rows = await deriveCoverageGap(prolog, params);
+            break;
+        case "untested_symbols":
+            rows = await deriveUntestedSymbols(prolog);
+            break;
+        case "stale":
+            rows = await deriveStale(prolog, params);
+            break;
+        case "orphaned":
+            rows = await deriveOrphaned(prolog, params);
+            break;
+        case "conflicting":
+            rows = await deriveConflicting(prolog, params);
+            break;
+        case "deprecated_still_used":
+            rows = await deriveDeprecatedStillUsed(prolog, params);
+            break;
+        case "current_adr":
+            rows = await deriveCurrentAdr(prolog);
+            break;
+        case "adr_chain":
+            rows = await deriveAdrChain(prolog, params);
+            break;
+        case "superseded_by":
+            rows = await deriveSupersededBy(prolog, params);
+            break;
+        case "domain_contradictions":
+            rows = await deriveDomainContradictions(prolog);
+            break;
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Derived ${rows.length} row(s) for rule '${rule}'.`,
+            },
+        ],
+        structuredContent: {
+            rule,
+            params,
+            count: rows.length,
+            rows,
+            provenance: {
+                predicate: rule,
+                deterministic: true,
+            },
+        },
+    };
+}
+async function deriveTransitivelyImplements(prolog, params) {
+    const symbolFilter = asOptionalString(params.symbol);
+    const reqFilter = asOptionalString(params.req);
+    const cond = makeConjunction([
+        symbolFilter ? `Symbol='${escapeAtom(symbolFilter)}'` : "",
+        reqFilter ? `Req='${escapeAtom(reqFilter)}'` : "",
+    ]);
+    const goal = `setof([Symbol,Req], (transitively_implements(Symbol, Req)${cond}), Rows)`;
+    const pairs = await queryPairRows(prolog, goal, "Rows");
+    return pairs.map(([symbol, req]) => ({ symbol, req }));
+}
+async function deriveTransitivelyDepends(prolog, params) {
+    const req1Filter = asOptionalString(params.req1);
+    const req2Filter = asOptionalString(params.req2);
+    const cond = makeConjunction([
+        req1Filter ? `Req1='${escapeAtom(req1Filter)}'` : "",
+        req2Filter ? `Req2='${escapeAtom(req2Filter)}'` : "",
+    ]);
+    const goal = `setof([Req1,Req2], (transitively_depends(Req1, Req2)${cond}), Rows)`;
+    const pairs = await queryPairRows(prolog, goal, "Rows");
+    return pairs.map(([req1, req2]) => ({ req1, req2 }));
+}
+async function deriveImpactedByChange(prolog, params) {
+    const changed = asRequiredString(params.changed, "params.changed is required");
+    const goal = `setof(Entity, impacted_by_change(Entity, '${escapeAtom(changed)}'), Rows)`;
+    const entities = await queryAtomRows(prolog, goal, "Rows");
+    return entities.map((entity) => ({ changed, entity }));
+}
+async function deriveAffectedSymbols(prolog, params) {
+    const req = asRequiredString(params.req, "params.req is required");
+    const goal = `affected_symbols('${escapeAtom(req)}', Symbols)`;
+    const result = await prolog.query(goal);
+    if (!result.success || !result.bindings.Symbols) {
+        return [];
+    }
+    const symbols = parseAtomList(result.bindings.Symbols);
+    return symbols.map((symbol) => ({ req, symbol }));
+}
+async function deriveCoverageGap(prolog, params) {
+    const reqFilter = asOptionalString(params.req);
+    const cond = reqFilter ? `Req='${escapeAtom(reqFilter)}'` : "";
+    const goal = `setof([Req,Reason], (coverage_gap(Req, Reason)${makeConjunction([cond])}), Rows)`;
+    const pairs = await queryPairRows(prolog, goal, "Rows");
+    return pairs.map(([req, reason]) => ({ req, reason }));
+}
+async function deriveUntestedSymbols(prolog) {
+    const result = await prolog.query("untested_symbols(Symbols)");
+    if (!result.success || !result.bindings.Symbols) {
+        return [];
+    }
+    const symbols = parseAtomList(result.bindings.Symbols);
+    return symbols.map((symbol) => ({ symbol }));
+}
+async function deriveStale(prolog, params) {
+    const maxAgeDays = Number(params.max_age_days ?? params.maxAgeDays);
+    if (!Number.isFinite(maxAgeDays)) {
+        throw new Error("params.max_age_days is required and must be numeric");
+    }
+    const entityFilter = asOptionalString(params.entity);
+    const cond = entityFilter ? `Entity='${escapeAtom(entityFilter)}'` : "";
+    const goal = `setof(Entity, (stale(Entity, ${maxAgeDays})${makeConjunction([cond])}), Rows)`;
+    const entities = await queryAtomRows(prolog, goal, "Rows");
+    return entities.map((entity) => ({ entity, max_age_days: maxAgeDays }));
+}
+async function deriveOrphaned(prolog, params) {
+    const symbolFilter = asOptionalString(params.symbol);
+    const cond = symbolFilter ? `Symbol='${escapeAtom(symbolFilter)}'` : "";
+    const goal = `setof(Symbol, (orphaned(Symbol)${makeConjunction([cond])}), Rows)`;
+    const symbols = await queryAtomRows(prolog, goal, "Rows");
+    return symbols.map((symbol) => ({ symbol }));
+}
+async function deriveConflicting(prolog, params) {
+    const adr1Filter = asOptionalString(params.adr1);
+    const adr2Filter = asOptionalString(params.adr2);
+    const cond = makeConjunction([
+        adr1Filter ? `Adr1='${escapeAtom(adr1Filter)}'` : "",
+        adr2Filter ? `Adr2='${escapeAtom(adr2Filter)}'` : "",
+    ]);
+    const goal = `setof([Adr1,Adr2], (conflicting(Adr1, Adr2)${cond}), Rows)`;
+    const pairs = await queryPairRows(prolog, goal, "Rows");
+    return pairs.map(([adr1, adr2]) => ({ adr1, adr2 }));
+}
+async function deriveDeprecatedStillUsed(prolog, params) {
+    const adrFilter = asOptionalString(params.adr);
+    const goal = adrFilter
+        ? `deprecated_still_used('${escapeAtom(adrFilter)}', Symbols)`
+        : "setof([Adr,Symbols], deprecated_still_used(Adr, Symbols), Rows)";
+    if (adrFilter) {
+        const result = await prolog.query(goal);
+        if (!result.success || !result.bindings.Symbols) {
+            return [];
+        }
+        return [
+            { adr: adrFilter, symbols: parseAtomList(result.bindings.Symbols) },
+        ];
+    }
+    const pairs = await queryPairRows(prolog, goal, "Rows");
+    return pairs.map(([adr, symbolsRaw]) => ({
+        adr,
+        symbols: parseAtomList(symbolsRaw),
+    }));
+}
+async function queryAtomRows(prolog, goal, bindingName) {
+    const result = await prolog.query(goal);
+    if (!result.success || !result.bindings[bindingName]) {
+        return [];
+    }
+    return parseAtomList(result.bindings[bindingName]);
+}
+async function queryPairRows(prolog, goal, bindingName) {
+    const result = await prolog.query(goal);
+    if (!result.success || !result.bindings[bindingName]) {
+        return [];
+    }
+    return parsePairList(result.bindings[bindingName]);
+}
+function asOptionalString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function asRequiredString(value, message) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(message);
+    }
+    return value;
+}
+function makeConjunction(parts) {
+    const filtered = parts.filter((part) => part.length > 0);
+    if (filtered.length === 0) {
+        return "";
+    }
+    return `, ${filtered.join(", ")}`;
+}
+function escapeAtom(value) {
+    return value.replace(/'/g, "\\'");
+}
+async function deriveCurrentAdr(prolog) {
+    // Query for all current ADRs and their titles
+    const result = await prolog.query("setof([Id,TitleAtom], (kb_entity(Id, adr, Props), memberchk(title=Title, Props), normalize_term_atom(Title, TitleAtom), current_adr(Id)), Rows)");
+    if (!result.success || !result.bindings.Rows) {
+        return [];
+    }
+    const pairs = parsePairList(result.bindings.Rows);
+    return pairs.map(([id, title]) => ({ id, title }));
+}
+async function deriveAdrChain(prolog, params) {
+    const adr = asRequiredString(params.adr, "params.adr is required");
+    // Query for the full chain including status
+    const result = await prolog.query(`findall([Id,TitleAtom,StatusAtom], (kb_entity(Id, adr, Props), memberchk(title=Title, Props), normalize_term_atom(Title, TitleAtom), memberchk(status=Status, Props), normalize_term_atom(Status, StatusAtom), adr_chain('${escapeAtom(adr)}', Chain), member(Id, Chain)), Rows)`);
+    if (!result.success || !result.bindings.Rows) {
+        return [];
+    }
+    // Parse triplets and include status
+    const triplets = parseTripleList(result.bindings.Rows);
+    return triplets.map(([id, title, status]) => ({ id, title, status }));
+}
+async function deriveSupersededBy(prolog, params) {
+    const adr = asRequiredString(params.adr, "params.adr is required");
+    // Query for direct supersession
+    const result = await prolog.query(`superseded_by('${escapeAtom(adr)}', NewAdr), kb_entity(NewAdr, adr, Props), memberchk(title=Title, Props), normalize_term_atom(Title, TitleAtom)`);
+    if (!result.success ||
+        !result.bindings.NewAdr ||
+        !result.bindings.TitleAtom) {
+        return [];
+    }
+    const newAdr = String(result.bindings.NewAdr).replace(/^'|'$/g, "");
+    const newAdrTitle = String(result.bindings.TitleAtom).replace(/^'|'$/g, "");
+    return [
+        {
+            adr,
+            successor_id: newAdr,
+            successor_title: newAdrTitle,
+        },
+    ];
+}
+function parseTripleList(raw) {
+    const match = raw.match(/\[(.*)\]/);
+    if (!match) {
+        return [];
+    }
+    const content = match[1].trim();
+    if (!content) {
+        return [];
+    }
+    // Parse triplets: [[a,b,c],[x,y,z],...]
+    const triplets = [];
+    const tripletRegex = /\[([^,]+),([^,]+),([^\]]+)\]/g;
+    let tripletMatch;
+    do {
+        tripletMatch = tripletRegex.exec(content);
+        if (tripletMatch !== null) {
+            triplets.push([
+                tripletMatch[1].trim().replace(/^'|'$/g, ""),
+                tripletMatch[2].trim().replace(/^'|'$/g, ""),
+                tripletMatch[3].trim().replace(/^'|'$/g, ""),
+            ]);
+        }
+    } while (tripletMatch !== null);
+    return triplets;
+}
+async function deriveDomainContradictions(prolog) {
+    const result = await prolog.query("setof([ReqA,ReqB,Reason], contradicting_reqs(ReqA, ReqB, Reason), Rows)");
+    if (!result.success || !result.bindings.Rows) {
+        return [];
+    }
+    const rows = parseTripleList(result.bindings.Rows);
+    return rows.map(([reqA, reqB, reason]) => ({ reqA, reqB, reason }));
+}

package/dist/tools/impact.js

@@ -0,0 +1,70 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+import { parseAtomList } from "./prolog-list.js";
+export async function handleKbImpact(prolog, args) {
+    if (!args.entity || typeof args.entity !== "string") {
+        throw new Error("'entity' is required");
+    }
+    const goal = `setof(Id, (impacted_by_change(Id, '${escapeAtom(args.entity)}'), Id \\= '${escapeAtom(args.entity)}'), Impacted)`;
+    const impactedIds = await queryAtoms(prolog, goal, "Impacted");
+    const impacted = [];
+    for (const id of impactedIds) {
+        const type = await getEntityType(prolog, id);
+        impacted.push({ id, type: type ?? "unknown" });
+    }
+    impacted.sort((a, b) => {
+        if (a.type === b.type) {
+            return a.id.localeCompare(b.id);
+        }
+        return a.type.localeCompare(b.type);
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Impact analysis for '${args.entity}': ${impacted.length} impacted entity(s).`,
+            },
+        ],
+        structuredContent: {
+            entity: args.entity,
+            impacted,
+            count: impacted.length,
+            provenance: {
+                predicate: "impacted_by_change",
+                deterministic: true,
+            },
+        },
+    };
+}
+async function queryAtoms(prolog, goal, bindingName) {
+    const result = await prolog.query(goal);
+    if (!result.success || !result.bindings[bindingName]) {
+        return [];
+    }
+    return parseAtomList(result.bindings[bindingName]);
+}
+async function getEntityType(prolog, id) {
+    const result = await prolog.query(`kb_entity('${escapeAtom(id)}', Type, _)`);
+    if (!result.success || !result.bindings.Type) {
+        return null;
+    }
+    return result.bindings.Type;
+}
+function escapeAtom(value) {
+    return value.replace(/'/g, "\\'");
+}

package/dist/tools/list-types.js

@@ -0,0 +1,75 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+/**
+ * Handle kb_list_entity_types tool calls
+ * Returns the static list of supported KB entity type names (req, scenario, test, adr, flag, event, symbol, fact).
+ */
+export async function handleKbListEntityTypes() {
+    return {
+        content: [
+            {
+                type: "text",
+                text: "Available entity types: req, scenario, test, adr, flag, event, symbol, fact",
+            },
+        ],
+        structuredContent: {
+            types: [
+                "req",
+                "scenario",
+                "test",
+                "adr",
+                "flag",
+                "event",
+                "symbol",
+                "fact",
+            ],
+        },
+    };
+}
+/**
+ * Handle kb_list_relationship_types tool calls
+ * Returns the static list of supported KB relationship type names (depends_on, specified_by, verified_by, etc.).
+ */
+export async function handleKbListRelationshipTypes() {
+    return {
+        content: [
+            {
+                type: "text",
+                text: "Available relationship types: depends_on, specified_by, verified_by, validates, implements, covered_by, constrained_by, constrains, requires_property, guards, publishes, consumes, supersedes, relates_to",
+            },
+        ],
+        structuredContent: {
+            types: [
+                "depends_on",
+                "specified_by",
+                "verified_by",
+                "validates",
+                "implements",
+                "covered_by",
+                "constrained_by",
+                "constrains",
+                "requires_property",
+                "guards",
+                "publishes",
+                "consumes",
+                "supersedes",
+                "relates_to",
+            ],
+        },
+    };
+}

package/dist/tools/prolog-list.js

@@ -0,0 +1,176 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+/*
+ How to apply this header to source files (examples)
+
+ 1) Prepend header to a single file (POSIX shells):
+
+    cat LICENSE_HEADER.txt "$FILE" > "$FILE".with-header && mv "$FILE".with-header "$FILE"
+
+ 2) Apply to multiple files (example: the project's main entry files):
+
+    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp packages/cli/src/*.ts packages/mcp/src/*.ts; do
+      if [ -f "$f" ]; then
+        cp "$f" "$f".bak
+        (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
+      fi
+    done
+
+ 3) Avoid duplicating the header: run a quick guard to only add if missing
+
+    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp; do
+      if [ -f "$f" ]; then
+        if ! head -n 5 "$f" | grep -q "Copyright (C) 2026 Piotr Franczyk"; then
+          cp "$f" "$f".bak
+          (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
+        fi
+      fi
+    done
+*/
+export function parseAtomList(raw) {
+    const trimmed = raw.trim();
+    if (trimmed === "[]" || trimmed.length === 0) {
+        return [];
+    }
+    const content = unwrapList(trimmed);
+    if (content.length === 0) {
+        return [];
+    }
+    return splitTopLevel(content, ",")
+        .map((token) => stripQuotes(token.trim()))
+        .filter((token) => token.length > 0);
+}
+export function parsePairList(raw) {
+    const rows = parseListRows(raw);
+    const pairs = [];
+    for (const row of rows) {
+        const parts = splitTopLevel(row, ",").map((part) => stripQuotes(part.trim()));
+        if (parts.length >= 2) {
+            pairs.push([parts[0], parts[1]]);
+        }
+    }
+    return pairs;
+}
+export function parseTriples(raw) {
+    const rows = parseListRows(raw);
+    const triples = [];
+    for (const row of rows) {
+        const parts = splitTopLevel(row, ",").map((part) => stripQuotes(part.trim()));
+        if (parts.length >= 3) {
+            triples.push([parts[0], parts[1], parts[2]]);
+        }
+    }
+    return triples;
+}
+function parseListRows(raw) {
+    const trimmed = raw.trim();
+    if (trimmed === "[]" || trimmed.length === 0) {
+        return [];
+    }
+    const content = unwrapList(trimmed);
+    if (content.length === 0) {
+        return [];
+    }
+    const rows = [];
+    let depth = 0;
+    let current = "";
+    for (let i = 0; i < content.length; i++) {
+        const ch = content[i];
+        if (ch === "[") {
+            depth++;
+            if (depth > 1) {
+                current += ch;
+            }
+            continue;
+        }
+        if (ch === "]") {
+            depth--;
+            if (depth === 0) {
+                rows.push(current.trim());
+                current = "";
+            }
+            else {
+                current += ch;
+            }
+            continue;
+        }
+        if (ch === "," && depth === 0) {
+            continue;
+        }
+        current += ch;
+    }
+    return rows;
+}
+function unwrapList(value) {
+    if (value.startsWith("[") && value.endsWith("]")) {
+        return value.slice(1, -1).trim();
+    }
+    return value;
+}
+function splitTopLevel(input, delimiter) {
+    const parts = [];
+    let current = "";
+    let depth = 0;
+    let inDoubleQuotes = false;
+    let inSingleQuotes = false;
+    for (let i = 0; i < input.length; i++) {
+        const ch = input[i];
+        const prev = i > 0 ? input[i - 1] : "";
+        if (ch === '"' && !inSingleQuotes && prev !== "\\") {
+            inDoubleQuotes = !inDoubleQuotes;
+            current += ch;
+            continue;
+        }
+        if (ch === "'" && !inDoubleQuotes && prev !== "\\") {
+            inSingleQuotes = !inSingleQuotes;
+            current += ch;
+            continue;
+        }
+        if (!inSingleQuotes && !inDoubleQuotes && (ch === "[" || ch === "(")) {
+            depth++;
+            current += ch;
+            continue;
+        }
+        if (!inSingleQuotes && !inDoubleQuotes && (ch === "]" || ch === ")")) {
+            depth--;
+            current += ch;
+            continue;
+        }
+        if (!inSingleQuotes && !inDoubleQuotes && depth === 0 && ch === delimiter) {
+            if (current.length > 0) {
+                parts.push(current);
+            }
+            current = "";
+            continue;
+        }
+        current += ch;
+    }
+    if (current.length > 0) {
+        parts.push(current);
+    }
+    return parts;
+}
+function stripQuotes(value) {
+    if (value.startsWith("'") && value.endsWith("'")) {
+        return value.slice(1, -1);
+    }
+    if (value.startsWith('"') && value.endsWith('"')) {
+        return value.slice(1, -1);
+    }
+    return value;
+}