kibi-plugin-builtin 0.5.1 → 0.5.3

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # kibi-plugin-builtin
 
+## 0.5.3
+
+### Patch Changes
+
+- 25d537e: Symbol coordinate refresh no longer treats `sourceFile` as an unrestricted filesystem path. Absolute paths and `..` escapes are rejected at upsert and refused at read time, so MCP/CLI coordinate refresh cannot probe files outside the workspace.
+
+  Tighten Prolog `sourceFile` typing to `workspace_relpath` in `kibi-core` (and the CLI schema mirror), add `resolveWorkspaceSourceAbsolute` confinement (with realpath checks), and cover the escape oracle with regression tests in CLI and MCP.
+
+## 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
@@ -16,6 +38,7 @@
 ### Minor Changes
 
 - ee91b85: Projects with a UI can opt into the experimental `kibi-plugin-ui`, which keeps agents on the agreed design: `kb_check` then requires every React or Angular component to implement a design requirement and blocks a component that loses the class names or test ids marking its agreed pattern, such as a timeline rewritten as cards. `/kibi-bootstrap` offers the plugin when it finds component files, and a declined offer is remembered in `package.json` `kibi.declinedPlugins`. Requirements that only name a UI pattern are now proved by fresh isolated component tests, so pattern rules do not need browser tests. Projects without the plugin see no new blocking findings.
+
   - Add the `kibi.check-policy.v1` capability to `kibi-plugin-sdk`: a JSON policy with ownership and pattern-marker rules, validated by `validateCheckPolicyDocument`. `kb_check` reads activated policies as data from the package and never imports plugin code; an unreadable policy blocks. The builtin plugin ships an empty policy.
   - Add the canonical `policy-ownership` and `policy-markers` rules (inert without an activated policy) to the rule registry, the `kb_check` schema and the CLI.
   - Add built-in `ui_pattern`, `same_pattern`, `pattern_marker` and `ui_container` predicate schemas with suggestion keywords.
@@ -64,6 +87,7 @@
 ### Patch Changes
 
 - 8622782: An impact review prepared on one machine now still validates in CI, and the MCP server and the CLI agree on whether it is current. Checks only block on incomplete source analysis the author can act on: the committed side of a change never blocks, and a known analyzer limitation such as a Rust macro or a Python decorator matters only where it overlaps the changed lines. Syntax, parse, timeout and integrity problems in the staged file still block. Long-running hosts no longer grow memory with every analyzed file, and Tree-sitter analysis reuses warm workers instead of starting one per file.
+
   - Identify the impact evaluator by its contract version and the canonical JSON of the schemas it consumes, instead of hashing the installed file tree and `process.version`. Identify the builtin analyzer runtime by its package identity rather than its installed tree.
   - `kibi-runtime` bundles the CLI operations again (`kibi-cli` is a build-time dependency only); it no longer installs `kibi-cli`.
   - Add one shared analysis gate (`analysisObligation`) used by staged checks, impact-review preparation and validation, and impact reports.
@@ -84,6 +108,7 @@
   When you model a new requirement, Kibi now ranks the subjects that already exist and either reuses one or explicitly declares a new one. It also flags claims that look like possible duplicates. An intentional restatement can be recorded with the new `restates` relationship. Skills and docs now recommend naming entities by the behavior they govern (`REQ-cli-gc`) instead of a sequence number (`REQ-042`). Existing numbered IDs stay valid.
 
   Predicate schemas can now declare the allowed values for an argument, plus the old spellings that map onto them. New facts must use those values. `kibi check` reports predicate facts that don't match any schema, and `kibi migrate` can fix the mechanical cases after you approve the plan hash. It moves a fact to the only namespace whose schema matches, and rewrites old spellings to the declared value. Everything that needs judgment stays a review item.
+
   - core: new `semantic_quality.pl` (`entity-id-style`, `domain-redundancy`, `domain-implication`, `subject-key-identity`, `subject-key-shape`, `ontology-quality`) and `units.pl`. Unit canonicalization is used for comparison only, and unknown or ambiguous units such as `KB` are never equated. Adds the `restates` req→req relationship and an optional `diagnosticSeverity` in the rule registry. Adds `:- encoding(utf8)` to modules that contain non-ASCII text.
   - cli/mcp: `restates` is wired through the extractors, schemas, and mutation paths. `entity-id-style` warnings are reported on `kb_upsert` creates and on staged added or renamed entity files. `kb_model_requirement` returns `vocabularyAlignment` (subject decision, candidates, redundancy candidates, stamps, `fallbackUsed`). Ontology-quality thresholds can be set with `KIBI_ONTOLOGY_QUALITY_MAX_SINGLETON_RATIO` / `KIBI_ONTOLOGY_QUALITY_MIN_FACTS`. `kb_compile_intent` create mode now keeps a caller-supplied `requirementId`. `kibi check --staged` now also prints its pass line when metadata-only staged changes have only advisory findings, matching the staged-symbol path.
   - cli/mcp: `predicate_schema` facts accept `argument_constants` and `argument_aliases`, stored like `rule_ir` as JSON. `kb_upsert` / `kb_validate_upsert` reject malformed vocabularies and predicate facts that use undeclared values or aliases. `kb_suggest_predicates` binds aliases to their constant and leaves undeclared values unbound. The new advisory TypeScript rule `predicate-schema-conformance` checks predicate facts against project schemas and the built-in catalog. Its mechanical repairs become automatic `predicate_schema_alignment` migration actions that carry the exact `kb_upsert` input and re-read the fact before writing.
@@ -99,6 +124,7 @@
   this repository, `kibi status` for a fresh KB drops from about 3 seconds to
   about 1.7, and a command that needs neither schema validation nor symbol
   extraction starts about 0.5 seconds sooner.
+
   - `kb_status_json` skips the full-entity stale-reason scan when the KB is
     fresh, because a fresh verdict already rules out every stale reason.
   - `kibi-plugin-builtin` loads ts-morph (the TypeScript compiler) on first
@@ -113,6 +139,7 @@
 ### Minor Changes
 
 - 783cc75: Coordinate enrichment, granularity candidate collection, and private-member helpers now live in `kibi-plugin-builtin`, so the CLI can analyze TypeScript/JavaScript symbols without depending on `ts-morph` directly. Hosts that only install `kibi-cli` still get the same enrichment and staged-symbol behavior through the builtin plugin.
+
   - Export `enrichSymbolCoordinatesWithTsMorph`, `collectGranularityCandidates`, `onlyCandidate`, and `isPrivateClassMember` from `kibi-plugin-builtin`
   - Thin-wrap those helpers from CLI `symbols-ts`, `symbol-granularity`, and `symbol-extract`
   - Drop `ts-morph` from `kibi-cli` runtime dependencies (kept as a test-only devDependency for AST spies)
@@ -125,10 +152,12 @@
 ### Patch Changes
 
 - b375e8f: This maintenance update brings the affected package code and tests into line with Kibi's Biome checks while preserving runtime behavior. It also replaces MCP non-null assertions with receiver-preserving method calls.
+
   - Format affected files, sort imports, and remove unnecessary template literals.
   - Preserve EngineClient `this` when forwarding optional Prolog methods.
 
 - e6571b4: External classifiers stay limited to the two allowlisted operations, ontology matches keep their claim keys through host composition, and CLI predicate rule tables now re-export the builtin pack so advisor and modeling cannot drift. Lane selection from the builtin classifier also accepts host snake_case signal shapes, which unblocks typecheck/build for capability-plugin call sites.
+
   - fix(builtin): chooseLane accepts kind-only LaneSignal (unblocks analysis-receipt typecheck)
   - feat(cli): stamp claimKey on composed ontology match candidates
   - refactor(cli): re-export predicate rule tables from kibi-plugin-builtin

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":"AAqCA,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,8 @@
 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";
+import { resolveWorkspaceSourceAbsolute } from "./workspace-path.js";
 // implements REQ-capability-plugin-builtin-parity-v1
 export async function enrichSymbolCoordinatesWithTsMorph(entries, workspaceRoot) {
     const project = new (tsMorph().Project)({
@@ -62,7 +63,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();
@@ -97,9 +103,9 @@ export async function enrichSymbolCoordinatesWithTsMorph(entries, workspaceRoot)
 async function resolveSourcePath(sourceFile, workspaceRoot) {
     if (!sourceFile)
         return null;
-    const absolute = path.isAbsolute(sourceFile)
-        ? sourceFile
-        : path.resolve(workspaceRoot, sourceFile);
+    const absolute = resolveWorkspaceSourceAbsolute(workspaceRoot, sourceFile);
+    if (absolute === null)
+        return null;
     const ext = path.extname(absolute).toLowerCase();
     if (!SUPPORTED_SOURCE_EXTENSIONS.has(ext))
         return null;
@@ -258,6 +264,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 +282,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 +303,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 +316,8 @@ function findNamedDeclaration(sourceFile, title) {
                 ...cls.getGetAccessors(),
                 ...cls.getSetAccessors(),
             ]) {
+                if (isPrivateClassMember(accessor))
+                    continue;
                 if (accessor.getName() !== title)
                     continue;
                 const nameNode = accessor.getNameNode();
@@ -320,6 +334,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 +350,8 @@ function findNamedDeclaration(sourceFile, title) {
                     ...classExpression.getGetAccessors(),
                     ...classExpression.getSetAccessors(),
                 ]) {
+                    if (isPrivateClassMember(accessor))
+                        continue;
                     if (accessor.getName() !== title)
                         continue;
                     const nameNode = accessor.getNameNode();
@@ -355,16 +373,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 +398,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 +406,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/dist/symbols/workspace-path.d.ts

@@ -0,0 +1,3 @@
+/** Return null when `candidate` escapes `workspaceRoot`. */
+export declare function resolveWorkspaceSourceAbsolute(workspaceRoot: string, sourceFile: string): string | null;
+//# sourceMappingURL=workspace-path.d.ts.map

package/dist/symbols/workspace-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-path.d.ts","sourceRoot":"","sources":["../../src/symbols/workspace-path.ts"],"names":[],"mappings":"AAoBA,4DAA4D;AAE5D,wBAAgB,8BAA8B,CAC5C,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,GACjB,MAAM,GAAG,IAAI,CA+Bf"}

package/dist/symbols/workspace-path.js

@@ -0,0 +1,55 @@
+/*
+ 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 { realpathSync } from "node:fs";
+import path from "node:path";
+/** Return null when `candidate` escapes `workspaceRoot`. */
+// implements REQ-symbol-sourcefile-workspace-confinement
+export function resolveWorkspaceSourceAbsolute(workspaceRoot, sourceFile) {
+    if (sourceFile.trim() === "")
+        return null;
+    let slashed = sourceFile.replaceAll("\\", "/");
+    const foreignAbsolute = /^[A-Za-z]:\//.test(slashed) || slashed.startsWith("//");
+    if (slashed.startsWith("/") || foreignAbsolute) {
+        if (foreignAbsolute && path.sep === "/")
+            return null;
+        const root = path.resolve(workspaceRoot);
+        const relative = path.relative(root, path.resolve(sourceFile));
+        if (relative === "" || path.isAbsolute(relative))
+            return null;
+        slashed = relative.replaceAll("\\", "/");
+    }
+    const normalized = path.posix.normalize(slashed).replace(/\/+$/, "");
+    if (normalized === "" ||
+        normalized === "." ||
+        normalized === ".." ||
+        normalized.startsWith("../")) {
+        return null;
+    }
+    const absolute = path.resolve(workspaceRoot, normalized);
+    try {
+        const realRoot = realpathSync.native(path.resolve(workspaceRoot));
+        const realFile = realpathSync.native(absolute);
+        const confined = path.relative(realRoot, realFile);
+        if (confined.startsWith("..") || path.isAbsolute(confined))
+            return null;
+        return realFile;
+    }
+    catch {
+        return absolute;
+    }
+}

package/package.json

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