kibi-mcp 0.15.0 → 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

@@ -337,6 +337,20 @@ 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"],
                 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-mcp",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
     "ajv": "^8.18.0",
@@ -9,7 +9,7 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-cli": "^0.12.0",
+    "kibi-cli": "^0.12.1",
     "kibi-core": "^0.6.0",
     "mcpcat": "^0.1.12",
     "ts-morph": "^23.0.0",
@@ -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"