kibi-mcp 0.14.3 → 0.15.1

package/dist/tools/upsert.js

@@ -16,6 +16,9 @@
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 import Ajv from "ajv";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { Project, ScriptKind } from "ts-morph";
 import { escapeAtom, toPrologAtom, toPrologString, } from "kibi-cli/prolog/codec";
 import entitySchema from "kibi-cli/schemas/entity";
 import relationshipSchema from "kibi-cli/schemas/relationship";
@@ -23,8 +26,40 @@ import { isMcpDebugEnabled } from "../env.js";
 import { refreshCoordinatesForSymbolId } from "./symbols.js";
 let refreshCoordinatesForSymbolIdImpl = refreshCoordinatesForSymbolId;
 const ajv = new Ajv({ strict: false });
-const validateEntity = ajv.compile(entitySchema);
+const entitySchemaRecord = entitySchema;
+const entitySchemaProperties = entitySchemaRecord.properties;
+const normalizedEntitySchemaProperties = entitySchemaProperties !== null &&
+    typeof entitySchemaProperties === "object" &&
+    !Array.isArray(entitySchemaProperties)
+    ? entitySchemaProperties
+    : {};
+const validateEntity = ajv.compile({
+    ...entitySchemaRecord,
+    properties: {
+        ...normalizedEntitySchemaProperties,
+        granularity_reason: {
+            type: "string",
+            enum: [
+                "config-artifact",
+                "module-level-behavior",
+                "extractor-miss",
+                "legacy-link",
+            ],
+        },
+    },
+});
 const validateRelationship = ajv.compile(relationshipSchema);
+const TRACEABILITY_RELATIONSHIP_TYPES = new Set([
+    "implements",
+    "covered_by",
+    "executable_for",
+]);
+const ALLOWED_GRANULARITY_REASONS = new Set([
+    "config-artifact",
+    "module-level-behavior",
+    "extractor-miss",
+    "legacy-link",
+]);
 /**
  * Handle kb.upsert tool calls
  * Accepts { type, id, properties } — the flat format matching the tool schema.
@@ -76,6 +111,7 @@ export async function handleKbUpsert(prolog, args) {
         }
     }
     validateRelationshipSources(id, relationships);
+    validateSymbolGranularity(entity, relationships);
     // Validate strict-lane fact_kind pairing for constrains/requires_property
     // implements REQ-011
     await validateStrictLanePairing(prolog, relationships);
@@ -185,6 +221,83 @@ export async function handleKbUpsert(prolog, args) {
         throw new Error(`Upsert execution failed: ${message}`);
     }
 }
+function chooseScriptKind(filePath) {
+    const lower = filePath.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 hasTraceabilityRelationship(relationships) {
+    return relationships.some((relationship) => typeof relationship.type === "string" &&
+        TRACEABILITY_RELATIONSHIP_TYPES.has(relationship.type));
+}
+function hasAllowedGranularityReason(entity) {
+    const reason = entity.granularity_reason;
+    return (typeof reason === "string" && ALLOWED_GRANULARITY_REASONS.has(reason));
+}
+function collectNarrowExportNames(filePath, content) {
+    const project = new Project({ skipAddingFilesFromTsConfig: true });
+    const sourceFile = project.createSourceFile(`${filePath}::granularity`, content, {
+        overwrite: true,
+        scriptKind: chooseScriptKind(filePath),
+    });
+    const names = new Set();
+    for (const fn of sourceFile.getFunctions()) {
+        if (fn.isExported()) {
+            const name = fn.getName();
+            if (name)
+                names.add(name);
+        }
+    }
+    for (const cls of sourceFile.getClasses()) {
+        if (cls.isExported()) {
+            const name = cls.getName();
+            if (name)
+                names.add(name);
+        }
+    }
+    for (const iface of sourceFile.getInterfaces()) {
+        if (iface.isExported())
+            names.add(iface.getName());
+    }
+    for (const alias of sourceFile.getTypeAliases()) {
+        if (alias.isExported())
+            names.add(alias.getName());
+    }
+    for (const en of sourceFile.getEnums()) {
+        if (en.isExported())
+            names.add(en.getName());
+    }
+    return [...names].sort();
+}
+function validateSymbolGranularity(entity, relationships) {
+    if (entity.type !== "symbol")
+        return;
+    if (!hasTraceabilityRelationship(relationships))
+        return;
+    if (hasAllowedGranularityReason(entity))
+        return;
+    if (typeof entity.sourceFile !== "string")
+        return;
+    if (typeof entity.title !== "string")
+        return;
+    const sourcePath = path.isAbsolute(entity.sourceFile)
+        ? entity.sourceFile
+        : path.resolve(process.cwd(), entity.sourceFile);
+    if (!existsSync(sourcePath))
+        return;
+    const narrowNames = collectNarrowExportNames(entity.sourceFile, readFileSync(sourcePath, "utf8"));
+    if (narrowNames.length === 0)
+        return;
+    if (narrowNames.includes(entity.title))
+        return;
+    throw new Error(`Symbol ${String(entity.id)} links ${entity.sourceFile} coarsely while granular symbols are available: ${narrowNames.join(", ")}. Move relationships to the narrow symbol or set granularity_reason to config-artifact, module-level-behavior, extractor-miss, or legacy-link.`);
+}
 export const __test__ = {
     // implements REQ-vscode-traceability
     setRefreshCoordinatesForSymbolIdForTests(fn) {

package/dist/tools-config.js

@@ -272,7 +272,7 @@ const BASE_TOOLS = [
     },
     {
         name: "kb_upsert",
-        description: "Create or update one entity and optional relationships. Use for KB mutations after validating intent. Use the `relationships` array for batch creation of multiple links in a single call (e.g., linking a requirement to multiple tests or facts). Prefer modeling requirements as reusable fact links (`constrains`, `requires_property`) so consistency and contradiction checks remain queryable. Relationship endpoints must already exist in KB. For requirements, the write will be rejected if it contradicts existing current requirements that constrain the same subject with incompatible properties. To replace a conflicting requirement, include a `supersedes` relationship from the new requirement to the old one in the same request. Do not use for read-only inspection. Side effects: writes KB, may refresh symbol coordinates.",
+        description: "Create or update one entity and optional relationships. Use for KB mutations after validating intent. Use the `relationships` array for batch creation of multiple links in a single call (e.g., linking a requirement to multiple tests or facts). Prefer modeling requirements as reusable fact links (`constrains`, `requires_property`, or `requires_predicate`) so consistency and contradiction checks remain queryable. Relationship endpoints must already exist in KB. For requirements, the write will be rejected if it contradicts existing current requirements that constrain the same subject with incompatible properties. To replace a conflicting requirement, include a `supersedes` relationship from the new requirement to the old one in the same request. Do not use for read-only inspection. Side effects: writes KB, may refresh symbol coordinates.",
         inputSchema: {
             type: "object",
             required: ["type", "id", "properties"],
@@ -337,12 +337,26 @@ const BASE_TOOLS = [
                             type: "string",
                             description: "Optional text anchor/reference. Example: 'requirements.md#L40'.",
                         },
+                        sourceFile: {
+                            type: "string",
+                            description: "Optional code source file for symbol entities. Example: 'src/auth/login.ts'.",
+                        },
+                        granularity_reason: {
+                            type: "string",
+                            enum: [
+                                "config-artifact",
+                                "module-level-behavior",
+                                "extractor-miss",
+                                "legacy-link",
+                            ],
+                            description: "Optional justification for a coarse file/module-level symbol traceability relationship when narrower function/class/type symbols exist.",
+                        },
                     },
                     required: ["title", "status"],
                 },
                 relationships: {
                     type: "array",
-                    description: "Optional relationship rows to create in the same call. For requirement encoding, prefer `constrains` + `requires_property` edges from req IDs to shared fact IDs to maximize reuse and detect conflicts. Side effect: asserts edges in KB.",
+                    description: "Optional relationship rows to create in the same call. For requirement encoding, prefer `constrains` + `requires_property` for strict property facts or `requires_predicate` for ontology predicate facts. Side effect: asserts edges in KB.",
                     items: {
                         type: "object",
                         required: ["type", "from", "to"],
@@ -360,6 +374,7 @@ const BASE_TOOLS = [
                                     "constrained_by",
                                     "constrains",
                                     "requires_property",
+                                    "requires_predicate",
                                     "guards",
                                     "publishes",
                                     "consumes",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-mcp",
-  "version": "0.14.3",
+  "version": "0.15.1",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
     "ajv": "^8.18.0",
@@ -9,8 +9,8 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-cli": "^0.11.3",
-    "kibi-core": "^0.5.3",
+    "kibi-cli": "^0.12.1",
+    "kibi-core": "^0.6.0",
     "mcpcat": "^0.1.12",
     "ts-morph": "^23.0.0",
     "zod": "^4.3.6"
@@ -27,7 +27,10 @@
     "build": "tsc -p tsconfig.json",
     "prepack": "npm run build"
   },
-  "files": ["dist", "bin"],
+  "files": [
+    "dist",
+    "bin"
+  ],
   "engines": {
     "node": ">=18",
     "bun": ">=1.0"