kibi-plugin-builtin 0.5.1 → 0.5.2

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # kibi-plugin-builtin
 
+## 0.5.2
+
+### Patch Changes
+
+- e9b50db: A clean `kibi check` now means the next commit passes `kibi check --staged`, and the staged gate no longer passes symbol coverage that the full check rejects. `kibi check --staged` runs the full-check `symbol-coverage` rule on the staged knowledge for every changed symbol, so a test that verifies a requirement directly no longer counts once that requirement has a scenario. Full `kibi check` adds the blocking rule `symbol-granularity`, which judges every linked symbol against its source file the way the staged gate does, so coarse links, including symbols whose title the extractor never produces, surface before a later commit trips over them; existing knowledge bases can see new violations (see Migration below). Source analysis for symbol checks no longer builds a TypeScript program over the default library files for every file, so the rule adds a few seconds to a full check, and the staged gate and coordinate refresh get faster too. `kibi sync --refresh-symbol-coordinates` no longer binds coordinates to a private class member that the staged extractor never produces; it lists the symbol as failed and says to re-point it to the public owner or remove it.
+
+  Technical summary: `kb.pl` adds `changed_symbol_no_req_coverage/2`, which restricts `symbol_no_req_coverage/2` to the `changed_symbol/1` overlay facts plus symbols whose staged manifest entry changed, and `checks.pl` adds `check_changed_symbol_coverage/2`, which renders those as `symbol-coverage` violations; the staged flow in `check.ts` calls it through `validateStagedSymbolCoverage` next to `validateStagedSymbols` and creates the temp KB whenever a symbol changed, including manifest-only edits. The rule registry adds the TypeScript rule `symbol-granularity`, evaluated in `executeCheck` by `collectSymbolGranularityViolations`, which reuses `createSymbolGranularityDiagnostics` with every working-tree declaration as a candidate, analyzes only the source files of symbols the rule judges, honours allowed `granularity_reason` values and skips files the analyzers cannot fully analyze; the `kb_check` `rules` enum gains the name. Granularity diagnostics now carry `entityId`, `source` and evidence, and name titles the extractor does not produce. The built-in ts-morph v2 extractor creates its project with `noLib`, `noResolve` and no `types`: it reads only syntactic diagnostics, which are unchanged, and per-file analysis drops from roughly 75 ms to a few milliseconds. The ts-morph coordinate enricher skips private class members and records a transient `coordinateRefreshFailure` that sync prints as the failure reason and never writes to the manifest. The unused `checkSymbolCoverage` helper and its stale "not traceable to any functional requirement" message are removed. kibi-runtime is bumped because it bundles the CLI operations that kibi-mcp serves.
+
+  Migration: `symbol-granularity` is canonical and blocking, so `kibi check`, `kb_check` and CI fail until its violations are fixed. A symbol violates it when it has `implements`, `covered_by` or `executable_for` links, no allowed `granularity_reason`, and its source file has a narrower behavioral declaration: a member of the symbol's title (a class symbol while its methods exist), or any declaration when the title names nothing the extractor produces (a non-exported helper, a private class member, a removed or renamed declaration). Run `kibi check --rules symbol-granularity` to list them, fix them with `kb_upsert`/`kb_delete` (never by editing `.kb/` files), then run `kibi sync --refresh-symbol-coordinates`:
+  - Title the extractor does not produce: re-point the symbol to its public owner, the exported function or class that owns the behavior. Change its `title` to the owner, or, when a symbol for the owner already exists, add the links to that symbol and delete the helper symbol.
+  - Class symbol while its members exist: move the links to the narrow member symbols, or delete the class symbol when its members already carry the same links.
+  - Coarse ownership that is intended: add an allowed `granularity_reason` (`module-level-behavior`, `config-artifact`, `extractor-miss`, `test-suite` or `legacy-link`).
+
 ## 0.5.1
 
 ### Patch Changes

package/dist/symbols/ts-morph-enrichment.d.ts

@@ -15,6 +15,13 @@ export interface ManifestSymbolEntry {
     sourceEndColumn?: number;
     coordinatesGeneratedAt?: string;
     links?: string[];
+    /**
+     * Transient refresh outcome, never authored: why no coordinates were
+     * published for this entry. Set when the title names a declaration the
+     * symbol extractor does not produce (a private class member), so a refresh
+     * reports it instead of binding a span no other Kibi path recognizes.
+     */
+    coordinateRefreshFailure?: string;
     [key: string]: unknown;
 }
 export declare function enrichSymbolCoordinatesWithTsMorph(entries: ManifestSymbolEntry[], workspaceRoot: string): Promise<ManifestSymbolEntry[]>;

package/dist/symbols/ts-morph-enrichment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ts-morph-enrichment.d.ts","sourceRoot":"","sources":["../../src/symbols/ts-morph-enrichment.ts"],"names":[],"mappings":"AAmCA,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,sBAAsB,EAAE,MAAM,CAAC;CAChC;AAGD,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAKD,wBAAsB,kCAAkC,CACtD,OAAO,EAAE,mBAAmB,EAAE,EAC9B,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,mBAAmB,EAAE,CAAC,CA8FhC"}
+{"version":3,"file":"ts-morph-enrichment.d.ts","sourceRoot":"","sources":["../../src/symbols/ts-morph-enrichment.ts"],"names":[],"mappings":"AAoCA,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,sBAAsB,EAAE,MAAM,CAAC;CAChC;AAGD,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;;;;OAKG;IACH,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAKD,wBAAsB,kCAAkC,CACtD,OAAO,EAAE,mBAAmB,EAAE,EAC9B,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAuGhC"}

package/dist/symbols/ts-morph-enrichment.js

@@ -18,7 +18,7 @@
 import { access, readFile } from "node:fs/promises";
 import * as path from "node:path";
 import { tsMorph } from "./ts-morph-runtime.js";
-import { SUPPORTED_SOURCE_EXTENSIONS, onlyCandidate, } from "./ts-morph-shared.js";
+import { SUPPORTED_SOURCE_EXTENSIONS, isPrivateClassMember, onlyCandidate, } from "./ts-morph-shared.js";
 // implements REQ-capability-plugin-builtin-parity-v1
 export async function enrichSymbolCoordinatesWithTsMorph(entries, workspaceRoot) {
     const project = new (tsMorph().Project)({
@@ -62,7 +62,12 @@ export async function enrichSymbolCoordinatesWithTsMorph(entries, workspaceRoot)
             }
             const match = findNamedDeclaration(sourceFile, entry.title);
             if (!match) {
-                enriched.push(entry);
+                enriched.push(namesPrivateClassMember(sourceFile, entry.title)
+                    ? {
+                        ...entry,
+                        coordinateRefreshFailure: privateMemberRefreshFailure(entry.title),
+                    }
+                    : entry);
                 continue;
             }
             const nameStart = match.getNameNode().getStart();
@@ -258,6 +263,8 @@ function findNamedDeclaration(sourceFile, title) {
         const methodCandidates = [];
         for (const cls of sourceFile.getClasses()) {
             for (const method of cls.getMethods()) {
+                if (isPrivateClassMember(method))
+                    continue;
                 if (method.getName() !== title)
                     continue;
                 const nameNode = method.getNameNode();
@@ -274,6 +281,8 @@ function findNamedDeclaration(sourceFile, title) {
                 if (!classExpression)
                     continue;
                 for (const method of classExpression.getMethods()) {
+                    if (isPrivateClassMember(method))
+                        continue;
                     if (method.getName() !== title)
                         continue;
                     const nameNode = method.getNameNode();
@@ -293,6 +302,8 @@ function findNamedDeclaration(sourceFile, title) {
         const memberCandidates = [];
         for (const cls of sourceFile.getClasses()) {
             for (const property of cls.getProperties()) {
+                if (isPrivateClassMember(property))
+                    continue;
                 if (property.getName() !== title)
                     continue;
                 const nameNode = property.getNameNode();
@@ -304,6 +315,8 @@ function findNamedDeclaration(sourceFile, title) {
                 ...cls.getGetAccessors(),
                 ...cls.getSetAccessors(),
             ]) {
+                if (isPrivateClassMember(accessor))
+                    continue;
                 if (accessor.getName() !== title)
                     continue;
                 const nameNode = accessor.getNameNode();
@@ -320,6 +333,8 @@ function findNamedDeclaration(sourceFile, title) {
                 if (!classExpression)
                     continue;
                 for (const property of classExpression.getProperties()) {
+                    if (isPrivateClassMember(property))
+                        continue;
                     if (property.getName() !== title)
                         continue;
                     const nameNode = property.getNameNode();
@@ -334,6 +349,8 @@ function findNamedDeclaration(sourceFile, title) {
                     ...classExpression.getGetAccessors(),
                     ...classExpression.getSetAccessors(),
                 ]) {
+                    if (isPrivateClassMember(accessor))
+                        continue;
                     if (accessor.getName() !== title)
                         continue;
                     const nameNode = accessor.getNameNode();
@@ -355,16 +372,22 @@ function findNamedDeclaration(sourceFile, title) {
     candidates.sort((a, b) => a.getNameNode().getStart() - b.getNameNode().getStart());
     return candidates[0] ?? null;
 }
+/**
+ * Public members only: the symbol extractor skips private class members, so
+ * a coordinate refresh must not bind a span to one either.
+ */
+// implements REQ-capability-plugin-builtin-parity-v1
 function findClassMember(declaration, name) {
+    const visible = (member) => !isPrivateClassMember(member);
     for (const method of declaration.getMethods()) {
-        if (method.getName() !== name)
+        if (method.getName() !== name || !visible(method))
             continue;
         const nameNode = method.getNameNode();
         if (nameNode)
             return { node: method, getNameNode: () => nameNode };
     }
     for (const property of declaration.getProperties()) {
-        if (property.getName() !== name)
+        if (property.getName() !== name || !visible(property))
             continue;
         const nameNode = property.getNameNode();
         if (nameNode)
@@ -374,7 +397,7 @@ function findClassMember(declaration, name) {
         ...declaration.getGetAccessors(),
         ...declaration.getSetAccessors(),
     ]) {
-        if (accessor.getName() !== name)
+        if (accessor.getName() !== name || !visible(accessor))
             continue;
         const nameNode = accessor.getNameNode();
         if (nameNode)
@@ -382,6 +405,42 @@ function findClassMember(declaration, name) {
     }
     return null;
 }
+/**
+ * True when the title names a private member of a class in this file (as
+ * `Class.member` or as a bare member name), which the extractor never emits.
+ */
+// implements REQ-capability-plugin-builtin-parity-v1
+function namesPrivateClassMember(sourceFile, title) {
+    const qualified = parseQualifiedMethodTitle(title);
+    const classes = [
+        ...sourceFile.getClasses(),
+    ];
+    for (const statement of sourceFile.getVariableStatements()) {
+        for (const declaration of statement.getDeclarations()) {
+            const classExpression = declaration.getInitializerIfKind(tsMorph().SyntaxKind.ClassExpression);
+            if (classExpression)
+                classes.push(classExpression);
+        }
+    }
+    return classes.some((declaration) => {
+        const className = declaration.getName() ??
+            declaration
+                .getParentIfKind(tsMorph().SyntaxKind.VariableDeclaration)
+                ?.getName();
+        if (qualified && qualified.className !== className)
+            return false;
+        const memberName = qualified ? qualified.methodName : title;
+        return [
+            ...declaration.getMethods(),
+            ...declaration.getProperties(),
+            ...declaration.getGetAccessors(),
+            ...declaration.getSetAccessors(),
+        ].some((member) => member.getName() === memberName && isPrivateClassMember(member));
+    });
+}
+function privateMemberRefreshFailure(title) {
+    return `'${title}' is a private class member; the symbol extractor tracks only public declarations, so no coordinates are published. Re-point the symbol to the public member or class that owns the behavior, or remove it`;
+}
 function parseQualifiedMethodTitle(title) {
     const separatorIndex = title.lastIndexOf(".");
     if (separatorIndex <= 0 || separatorIndex === title.length - 1)

package/dist/symbols/ts-morph-extractor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ts-morph-extractor.d.ts","sourceRoot":"","sources":["../../src/symbols/ts-morph-extractor.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EACV,sBAAsB,EAMtB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,iBAAiB,CAAC;AAsDzB;;;GAGG;AAEH,wBAAgB,mCAAmC,IAAI,iBAAiB,CA4CvE;AAED,iFAAiF;AAEjF,wBAAgB,qCAAqC,IAAI,iBAAiB,CAqHzE;AA+BD,wBAAgB,0CAA0C,IAAI,sBAAsB,CAEnF"}
+{"version":3,"file":"ts-morph-extractor.d.ts","sourceRoot":"","sources":["../../src/symbols/ts-morph-extractor.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EACV,sBAAsB,EAMtB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,iBAAiB,CAAC;AAsDzB;;;GAGG;AAEH,wBAAgB,mCAAmC,IAAI,iBAAiB,CA4CvE;AAED,iFAAiF;AAEjF,wBAAgB,qCAAqC,IAAI,iBAAiB,CA2HzE;AA+BD,wBAAgB,0CAA0C,IAAI,sBAAsB,CAEnF"}

package/dist/symbols/ts-morph-extractor.js

@@ -96,9 +96,15 @@ export function createBuiltinTsMorphSymbolExtractor() {
 export function createBuiltinTsMorphSymbolExtractorV2() {
     // Like the v1 extractor, build the project (and load the TypeScript
     // compiler) on the first analysis rather than at plugin registration.
+    // Only syntactic diagnostics are read, so the program needs neither the
+    // default library files nor the file's imports; loading them made every
+    // analysis rebuild a program over the whole lib closure.
     let project;
     const getProject = () => {
-        project ??= new (tsMorph().Project)({ skipAddingFilesFromTsConfig: true });
+        project ??= new (tsMorph().Project)({
+            skipAddingFilesFromTsConfig: true,
+            compilerOptions: { noLib: true, noResolve: true, types: [] },
+        });
         return project;
     };
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-plugin-builtin",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Default Kibi capability plugins: TS symbol extraction, ontology pack, and semantic classifier",
   "type": "module",
   "main": "./dist/index.js",