kibi-cli 0.6.2 → 0.8.0

package/dist/commands/check.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AAuDA,OAAO,EAGL,KAAK,SAAS,EAEf,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EAAE,SAAS,EAAE,CAAC;AAI1B,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AA+GD,wBAAsB,YAAY,CAChC,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAgR/B"}
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AAuDA,OAAO,EAGL,KAAK,SAAS,EAEf,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EAAE,SAAS,EAAE,CAAC;AAI1B,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AA+GD,wBAAsB,YAAY,CAChC,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAkR/B"}

package/dist/commands/check.js

@@ -277,6 +277,7 @@ export async function checkCommand(options) {
             "deprecated-adr-no-successor",
             "domain-contradictions",
             "strict-fact-shape",
+            "strict-req-fact-pairing",
         ];
         const canUseAggregated = Array.from(effectiveRules).every((r) => supportedRules.includes(r));
         if (canUseAggregated) {
@@ -300,6 +301,7 @@ export async function checkCommand(options) {
             await runCheck("deprecated-adr-no-successor", checkDeprecatedAdrs);
             await runCheck("domain-contradictions", checkDomainContradictions);
             await runCheck("strict-fact-shape", checkStrictFactShape);
+            await runCheck("strict-req-fact-pairing", checkStrictReqFactPairing);
         }
         if (violations.length === 0) {
             console.log("✓ No violations found. KB is valid.");
@@ -640,6 +642,22 @@ async function checkStrictFactShape(prolog) {
     }
     return violations;
 }
+async function checkStrictReqFactPairing(prolog) {
+    const violations = [];
+    const result = await prolog.query(`findall(violation(Rule, EntityId, Desc, Sugg, Src),
+      checks:strict_req_fact_pairing_violation(violation(Rule, EntityId, Desc, Sugg, Src)),
+      Violations)`);
+    if (!result.success || !result.bindings.Violations) {
+        return violations;
+    }
+    const violationsStr = result.bindings.Violations;
+    if (violationsStr && violationsStr !== "[]") {
+        for (const v of parseViolationRows(violationsStr)) {
+            violations.push(v);
+        }
+    }
+    return violations;
+}
 async function checkSymbolCoverage(prolog) {
     const violations = [];
     const uncoveredResult = await prolog.query("setof(Symbol, symbol_no_req_coverage(Symbol, _), Symbols)");

package/dist/commands/init-helpers.d.ts

@@ -2,6 +2,7 @@ export declare function getCurrentBranch(cwd?: string): Promise<string>;
 export declare function createKbDirectoryStructure(kbDir: string, currentBranch: string): void;
 export declare function createConfigFile(kbDir: string): void;
 export declare function updateGitIgnore(cwd: string): void;
+export declare function ensureSymbolsManifestFile(cwd: string): void;
 export declare function copySchemaFiles(kbDir: string, schemaSourceDir: string): Promise<void>;
 export declare function installHook(hookPath: string, content: string): void;
 export declare function installGitHooks(gitDir: string): void;

package/dist/commands/init-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init-helpers.d.ts","sourceRoot":"","sources":["../../src/commands/init-helpers.ts"],"names":[],"mappings":"AAuFA,wBAAsB,gBAAgB,CACpC,GAAG,GAAE,MAAsB,GAC1B,OAAO,CAAC,MAAM,CAAC,CASjB;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,GACpB,IAAI,CAQN;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAMpD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAajD;AAED,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,EACb,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC,CAYf;AASD,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAkCnE;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAiBpD"}
+{"version":3,"file":"init-helpers.d.ts","sourceRoot":"","sources":["../../src/commands/init-helpers.ts"],"names":[],"mappings":"AAuGA,wBAAsB,gBAAgB,CACpC,GAAG,GAAE,MAAsB,GAC1B,OAAO,CAAC,MAAM,CAAC,CASjB;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,GACpB,IAAI,CAQN;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAMpD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAsBjD;AAGD,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAU3D;AAED,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,EACb,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC,CAYf;AASD,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAkCnE;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAiBpD"}

package/dist/commands/init-helpers.js

@@ -20,6 +20,7 @@ import * as path from "node:path";
 import fg from "fast-glob";
 import { getBranchDiagnostic, resolveActiveBranch, } from "../utils/branch-resolver.js";
 import { DEFAULT_CONFIG } from "../utils/config.js";
+import { SYMBOLS_MANIFEST_COMMENT_BLOCK } from "./sync/manifest.js";
 const POST_CHECKOUT_HOOK = `#!/bin/sh
 # post-checkout hook for kibi
 # Parameters: old_ref new_ref branch_flag
@@ -67,6 +68,21 @@ const PRE_COMMIT_HOOK = `#!/bin/sh
 # The OpenCode plugin remains advisory and must not replace this gate.
 
 set -e
+
+symbols_manifest="documentation/symbols.yaml"
+
+if [ ! -f "$symbols_manifest" ]; then
+  echo "Kibi symbols manifest is missing: $symbols_manifest" >&2
+  echo "Run 'kibi init' to create it, then stage and commit it." >&2
+  exit 1
+fi
+
+if ! git diff --quiet -- "$symbols_manifest"; then
+  echo "Kibi symbols manifest has unstaged changes: $symbols_manifest" >&2
+  echo "Stage and commit documentation/symbols.yaml with the code changes that refreshed it." >&2
+  exit 1
+fi
+
 kibi check --staged
 `;
 export async function getCurrentBranch(cwd = process.cwd()) {
@@ -91,17 +107,34 @@ export function createConfigFile(kbDir) {
     console.log("✓ Created config.json with default paths");
 }
 export function updateGitIgnore(cwd) {
+    // implements REQ-001
     const gitignorePath = path.join(cwd, ".gitignore");
     const gitignoreContent = existsSync(gitignorePath)
         ? readFileSync(gitignorePath, "utf8")
         : "";
-    if (!gitignoreContent.includes(".kb/")) {
-        const newContent = gitignoreContent
-            ? `${gitignoreContent.trimEnd()}\n.kb/\n`
-            : ".kb/\n";
-        writeFileSync(gitignorePath, newContent);
-        console.log("✓ Added .kb/ to .gitignore");
+    const ensureEntry = (current, entry) => {
+        if (current.includes(entry)) {
+            return current;
+        }
+        return current ? `${current.trimEnd()}\n${entry}\n` : `${entry}\n`;
+    };
+    const updatedWithKb = ensureEntry(gitignoreContent, ".kb/");
+    const updatedContent = ensureEntry(updatedWithKb, ".kb/briefs/");
+    if (updatedContent !== gitignoreContent) {
+        writeFileSync(gitignorePath, updatedContent);
+        console.log("✓ Added .kb/ and .kb/briefs/ to .gitignore");
+    }
+}
+// implements REQ-003
+export function ensureSymbolsManifestFile(cwd) {
+    const symbolsRelPath = DEFAULT_CONFIG.paths.symbols ?? "documentation/symbols.yaml";
+    const symbolsPath = path.join(cwd, symbolsRelPath);
+    if (existsSync(symbolsPath)) {
+        return;
     }
+    mkdirSync(path.dirname(symbolsPath), { recursive: true });
+    writeFileSync(symbolsPath, `${SYMBOLS_MANIFEST_COMMENT_BLOCK}symbols: []\n`);
+    console.log(`✓ Created ${symbolsRelPath}`);
 }
 export async function copySchemaFiles(kbDir, schemaSourceDir) {
     const schemaFiles = await fg("*.pl", {

package/dist/commands/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAiCA,UAAU,WAAW;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAGD,wBAAsB,WAAW,CAC/B,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA6D/B"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAkCA,UAAU,WAAW;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAGD,wBAAsB,WAAW,CAC/B,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA+D/B"}

package/dist/commands/init.js

@@ -19,7 +19,7 @@ import { existsSync } from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { resolveActiveBranch } from "../utils/branch-resolver.js";
-import { copySchemaFiles, createConfigFile, createKbDirectoryStructure, installGitHooks, updateGitIgnore, } from "./init-helpers.js";
+import { copySchemaFiles, createConfigFile, createKbDirectoryStructure, ensureSymbolsManifestFile, installGitHooks, updateGitIgnore, } from "./init-helpers.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 // implements REQ-003
@@ -58,6 +58,7 @@ export async function initCommand(options) {
         else {
             console.log("✓ .kb/ directory already exists, skipping creation");
         }
+        ensureSymbolsManifestFile(process.cwd());
         if (options.hooks) {
             const gitDir = path.join(process.cwd(), ".git");
             if (!existsSync(gitDir)) {

package/dist/commands/sync/manifest.d.ts

@@ -9,6 +9,7 @@ interface ManifestDeps {
     readFileSync: typeof readFileSync;
     writeFileSync: typeof writeFileSync;
 }
+export declare const SYMBOLS_MANIFEST_COMMENT_BLOCK = "# symbols.yaml\n# AUTHORED fields (edit freely):\n#   id, title, sourceFile, links, status, tags, owner, priority\n# GENERATED fields (never edit manually \u2014 overwritten by kibi sync and kb.symbols.refresh):\n#   sourceLine, sourceColumn, sourceEndLine, sourceEndColumn, coordinatesGeneratedAt\n# Run `kibi sync` or call the `kb.symbols.refresh` MCP tool to refresh coordinates.\n";
 export declare function refreshManifestCoordinates(manifestPath: string, workspaceRoot: string, deps?: Partial<ManifestDeps>): Promise<void>;
 export declare function hasAllGeneratedCoordinates(entry: ManifestSymbolEntry): boolean;
 export declare function isEligibleForCoordinateRefresh(sourceFile: string | undefined, workspaceRoot: string, deps?: Partial<ManifestDeps>): boolean;

package/dist/commands/sync/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/manifest.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAElE,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EACL,KAAK,mBAAmB,EACxB,uBAAuB,EACxB,MAAM,yCAAyC,CAAC;AAEjD,UAAU,YAAY;IACpB,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,aAAa,EAAE,OAAO,aAAa,CAAC;CACrC;AAyCD,wBAAsB,0BAA0B,CAE9C,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC3B,OAAO,CAAC,IAAI,CAAC,CA8Ef;AAED,wBAAgB,0BAA0B,CAExC,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAST;AAED,wBAAgB,8BAA8B,CAE5C,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC3B,OAAO,CAUT"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/manifest.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAElE,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EACL,KAAK,mBAAmB,EACxB,uBAAuB,EACxB,MAAM,yCAAyC,CAAC;AAEjD,UAAU,YAAY;IACpB,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,aAAa,EAAE,OAAO,aAAa,CAAC;CACrC;AAcD,eAAO,MAAM,8BAA8B,qYAM1C,CAAC;AAqBF,wBAAsB,0BAA0B,CAE9C,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC3B,OAAO,CAAC,IAAI,CAAC,CA8Ef;AAED,wBAAgB,0BAA0B,CAExC,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAST;AAED,wBAAgB,8BAA8B,CAE5C,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC3B,OAAO,CAUT"}

package/dist/commands/sync/manifest.js

@@ -30,7 +30,7 @@ function resolveDeps(overrides) {
         ...overrides,
     };
 }
-const SYMBOLS_MANIFEST_COMMENT_BLOCK = `# symbols.yaml
+export const SYMBOLS_MANIFEST_COMMENT_BLOCK = `# symbols.yaml
 # AUTHORED fields (edit freely):
 #   id, title, sourceFile, links, status, tags, owner, priority
 # GENERATED fields (never edit manually — overwritten by kibi sync and kb.symbols.refresh):

package/dist/commands/sync/persistence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/persistence.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAEV,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AA0ErD,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,wBAAsB,eAAe,CAEnC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,GACrB,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CAoEvD;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,kBAAkB,EAAE,qBAAqB,EAAE,GAC1C,OAAO,CAAC;IAAE,iBAAiB,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CAiI7D"}
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/persistence.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAEV,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AA0ErD,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,wBAAsB,eAAe,CAEnC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,GACrB,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CAqEvD;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,kBAAkB,EAAE,qBAAqB,EAAE,GAC1C,OAAO,CAAC;IAAE,iBAAiB,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CAiI7D"}

package/dist/commands/sync/persistence.js

@@ -98,10 +98,10 @@ prolog, results, entityIds) {
             }
         }
     }
-    for (const { entity } of results) {
+    for (const { entity, sourceFile } of results) {
         entityIds.add(entity.id);
     }
-    for (const { entity } of results) {
+    for (const { entity, sourceFile } of results) {
         try {
             const props = [
                 `id=${toPrologAtom(entity.id)}`,
@@ -123,6 +123,8 @@ prolog, results, entityIds) {
                 props.push(`severity=${toPrologAtom(entity.severity)}`);
             if (entity.text_ref)
                 props.push(`text_ref=${toPrologString(entity.text_ref)}`);
+            if (sourceFile)
+                props.push(`sourceFile=${toPrologString(sourceFile)}`);
             // Add typed fact fields for fact entities
             if (entity.type === "fact") {
                 const factFields = serializeTypedFactFields(entity);

package/dist/commands/sync/staging.d.ts

@@ -8,11 +8,14 @@ interface StagingDeps {
     cwd: () => string;
     existsSync: typeof existsSync;
     fg: typeof fg;
+    isProcessAlive: (pid: number) => boolean;
     mkdirSync: typeof mkdirSync;
     moduleDir: string;
     renameSync: typeof renameSync;
     rmSync: typeof rmSync;
 }
+export declare function createUniqueStagingPath(currentBranch: string, rootDir: string, pid?: number, now?: number): string;
+export declare function cleanupAbandonedStagingDirectories(stagingPath: string, deps?: Partial<StagingDeps>): Promise<void>;
 export declare function prepareStagingEnvironment(stagingPath: string, livePath: string, rebuild: boolean, deps?: Partial<StagingDeps>): Promise<void>;
 export declare function atomicPublish(stagingPath: string, livePath: string, deps?: Partial<StagingDeps>): void;
 export declare function cleanupStaging(stagingPath: string, deps?: Partial<StagingDeps>): void;

package/dist/commands/sync/staging.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"staging.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/staging.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAE,MAAM,WAAW,CAAC;AAC3B,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAEnE,UAAU,WAAW;IACnB,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,EAAE,EAAE,OAAO,EAAE,CAAC;IACd,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,MAAM,EAAE,OAAO,MAAM,CAAC;CACvB;AAiBD,wBAAsB,yBAAyB,CAE7C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,OAAO,CAAC,IAAI,CAAC,CAaf;AA0CD,wBAAgB,aAAa,CAE3B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,IAAI,CAeN;AAED,wBAAgB,cAAc,CAE5B,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,IAAI,CAKN"}
+{"version":3,"file":"staging.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/staging.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAE,MAAM,WAAW,CAAC;AAC3B,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAEnE,UAAU,WAAW;IACnB,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,EAAE,EAAE,OAAO,EAAE,CAAC;IACd,cAAc,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACzC,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,MAAM,EAAE,OAAO,MAAM,CAAC;CACvB;AA8BD,wBAAgB,uBAAuB,CACrC,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,GAAG,SAAc,EACjB,GAAG,SAAa,GACf,MAAM,CAOR;AAGD,wBAAsB,kCAAkC,CACtD,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,OAAO,CAAC,IAAI,CAAC,CAkDf;AAED,wBAAsB,yBAAyB,CAE7C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,OAAO,CAAC,IAAI,CAAC,CAaf;AA0CD,wBAAgB,aAAa,CAE3B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,IAAI,CAeN;AAED,wBAAgB,cAAc,CAE5B,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,IAAI,CAKN"}

package/dist/commands/sync/staging.js

@@ -27,6 +27,17 @@ function resolveDeps(overrides) {
         cwd: () => process.cwd(),
         existsSync,
         fg,
+        isProcessAlive: (pid) => {
+            try {
+                process.kill(pid, 0);
+                return true;
+            }
+            catch (error) {
+                return !(error instanceof Error &&
+                    "code" in error &&
+                    error.code === "ESRCH");
+            }
+        },
         mkdirSync,
         moduleDir: import.meta.dirname,
         renameSync,
@@ -34,11 +45,54 @@ function resolveDeps(overrides) {
         ...overrides,
     };
 }
+// implements REQ-003
+export function createUniqueStagingPath(currentBranch, rootDir, pid = process.pid, now = Date.now()) {
+    return path.join(rootDir, ".kb", "branches", `${currentBranch}.staging.${pid}.${now}`);
+}
+// implements REQ-003
+export async function cleanupAbandonedStagingDirectories(stagingPath, deps) {
+    const resolved = resolveDeps(deps);
+    const stagingDir = path.dirname(stagingPath);
+    const stagingBase = path.basename(stagingPath);
+    const match = /^(?<branch>.+)\.staging\.(?<pid>\d+)\.(?<timestamp>\d+)$/.exec(stagingBase);
+    if (!match?.groups) {
+        return;
+    }
+    const branch = match.groups.branch;
+    if (!branch) {
+        return;
+    }
+    const candidates = await resolved.fg(`${branch}.staging.*`, {
+        cwd: stagingDir,
+        absolute: true,
+        onlyDirectories: true,
+        suppressErrors: true,
+    });
+    for (const candidate of candidates) {
+        if (candidate === stagingPath) {
+            continue;
+        }
+        const candidateBase = path.basename(candidate);
+        const candidateMatch = new RegExp(`^${escapeRegex(branch)}\\.staging\\.(\\d+)\\.(\\d+)$`).exec(candidateBase);
+        if (!candidateMatch) {
+            continue;
+        }
+        const candidatePidText = candidateMatch[1];
+        if (!candidatePidText) {
+            continue;
+        }
+        const candidatePid = Number.parseInt(candidatePidText, 10);
+        if (!Number.isFinite(candidatePid) || resolved.isProcessAlive(candidatePid)) {
+            continue;
+        }
+        cleanupStaging(candidate, resolved);
+    }
+}
 export async function prepareStagingEnvironment(
 // implements REQ-003
 stagingPath, livePath, rebuild, deps) {
     const resolved = resolveDeps(deps);
-    // Cleanup any existing staging directory
+    await cleanupAbandonedStagingDirectories(stagingPath, resolved);
     cleanupStaging(stagingPath, resolved);
     resolved.mkdirSync(stagingPath, { recursive: true });
     if (!rebuild && resolved.existsSync(livePath)) {
@@ -107,3 +161,6 @@ stagingPath, deps) {
         resolved.rmSync(stagingPath, { recursive: true, force: true });
     }
 }
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/commands/sync.d.ts

@@ -1,13 +1,30 @@
 import type { SyncSummary } from "../diagnostics.js";
+import { PrologProcess } from "../prolog.js";
 export declare class SyncError extends Error {
     constructor(message: string);
 }
 export interface SyncResult extends SyncSummary {
     exitCode?: number;
 }
+interface SyncCommandRuntimeContext {
+    currentBranch: string;
+    livePath: string;
+    rebuild: boolean;
+    stagingPath: string;
+    validateOnly: boolean;
+}
+interface SyncCommandRuntime {
+    afterAttach?: (context: SyncCommandRuntimeContext) => Promise<void> | void;
+    beforeSave?: (context: SyncCommandRuntimeContext & {
+        kbModified: boolean;
+    }) => Promise<void> | void;
+    createProlog?: (options: {
+        timeout: number;
+    }) => PrologProcess;
+}
 export declare function syncCommand(options?: {
     validateOnly?: boolean;
     rebuild?: boolean;
-}): Promise<SyncResult>;
+}, runtime?: SyncCommandRuntime): Promise<SyncResult>;
 export { normalizeMarkdownPath } from "./sync/discovery.js";
 //# sourceMappingURL=sync.d.ts.map

package/dist/commands/sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/commands/sync.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,mBAAmB,CAAC;AA0CjE,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B;AAGD,MAAM,WAAW,UAAW,SAAQ,WAAW;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAGD,wBAAsB,WAAW,CAC/B,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAC1D,OAAO,CAAC,UAAU,CAAC,CAqarB;AAED,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/commands/sync.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAejE,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AA4B7C,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B;AAGD,MAAM,WAAW,UAAW,SAAQ,WAAW;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,yBAAyB;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,UAAU,kBAAkB;IAC1B,WAAW,CAAC,EAAE,CACZ,OAAO,EAAE,yBAAyB,KAC/B,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,UAAU,CAAC,EAAE,CACX,OAAO,EAAE,yBAAyB,GAAG;QAAE,UAAU,EAAE,OAAO,CAAA;KAAE,KACzD,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,aAAa,CAAC;CAChE;AAGD,wBAAsB,WAAW,CAC/B,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,EAC3D,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,UAAU,CAAC,CAmbrB;AAED,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/commands/sync.js

@@ -29,7 +29,7 @@ import { discoverSourceFiles, } from "./sync/discovery.js";
 import { processExtractions } from "./sync/extraction.js";
 import { refreshManifestCoordinates } from "./sync/manifest.js";
 import { persistEntities, persistRelationships } from "./sync/persistence.js";
-import { atomicPublish, cleanupStaging, prepareStagingEnvironment, } from "./sync/staging.js";
+import { atomicPublish, cleanupStaging, createUniqueStagingPath, prepareStagingEnvironment, } from "./sync/staging.js";
 export class SyncError extends Error {
     constructor(message) {
         super(message);
@@ -37,7 +37,7 @@ export class SyncError extends Error {
     }
 }
 // implements REQ-003, REQ-007
-export async function syncCommand(options = {}) {
+export async function syncCommand(options = {}, runtime = {}) {
     const validateOnly = options.validateOnly ?? false;
     const rebuild = options.rebuild ?? false;
     const startTime = Date.now();
@@ -45,6 +45,7 @@ export async function syncCommand(options = {}) {
     const entityCounts = {};
     let published = false;
     let currentBranch;
+    let stagingPath;
     const getCurrentCommit = () => {
         try {
             return execSync("git rev-parse HEAD", {
@@ -199,16 +200,25 @@ export async function syncCommand(options = {}) {
         if (!kbExists && !rebuild) {
             diagnostics.push(createKbMissingDiagnostic(currentBranch, livePath));
         }
-        const stagingPath = path.join(process.cwd(), `.kb/branches/${currentBranch}.staging`);
+        stagingPath = createUniqueStagingPath(currentBranch, process.cwd());
+        const runtimeContext = {
+            currentBranch,
+            livePath,
+            rebuild,
+            stagingPath,
+            validateOnly,
+        };
         await prepareStagingEnvironment(stagingPath, livePath, rebuild);
         try {
-            const prolog = new PrologProcess({ timeout: 120000 });
+            const prolog = runtime.createProlog?.({ timeout: 120000 }) ??
+                new PrologProcess({ timeout: 120000 });
             await prolog.start();
             const attachResult = await prolog.query(`kb_attach('${stagingPath}')`);
             if (!attachResult.success) {
                 await prolog.terminate();
                 throw new SyncError(`Failed to attach to staging KB: ${attachResult.error || "Unknown error"}`);
             }
+            await runtime.afterAttach?.(runtimeContext);
             const entityIds = new Set();
             for (const { entity } of results) {
                 entityCounts[entity.type] = (entityCounts[entity.type] || 0) + 1;
@@ -263,6 +273,7 @@ export async function syncCommand(options = {}) {
             if (kbModified) {
                 prolog.invalidateCache();
             }
+            await runtime.beforeSave?.({ ...runtimeContext, kbModified });
             const saveResult = await prolog.query("kb_save");
             if (!saveResult.success) {
                 throw new SyncError(`Failed to save staging KB: ${saveResult.error || "Unknown error"}`);
@@ -270,6 +281,7 @@ export async function syncCommand(options = {}) {
             await prolog.query("kb_detach");
             await prolog.terminate();
             atomicPublish(stagingPath, livePath);
+            cleanupStaging(stagingPath);
             const evictedHashes = {};
             const evictedSeenAt = {};
             for (const [key, hash] of Object.entries(nextHashes)) {
@@ -312,6 +324,9 @@ export async function syncCommand(options = {}) {
         }
     }
     catch (error) {
+        if (stagingPath) {
+            cleanupStaging(stagingPath);
+        }
         const errorMessage = error instanceof Error ? error.message : String(error);
         console.error(`Error: ${errorMessage}`);
         const commit = getCurrentCommit();

package/dist/extractors/markdown.d.ts

@@ -38,6 +38,8 @@ export interface ExtractedRelationship {
 export interface ExtractionResult {
     entity: ExtractedEntity;
     relationships: ExtractedRelationship[];
+    /** The per-symbol source code file, distinct from the manifest file path. */
+    sourceFile?: string;
 }
 export declare class FrontmatterError extends Error {
     filePath: string;

package/dist/extractors/markdown.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/extractors/markdown.ts"],"names":[],"mappings":"AAwDA,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kBAAkB,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,YAAY,CAAC;IAC3D,wBAAwB,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IAEnD,SAAS,CAAC,EAAE,SAAS,GAAG,gBAAgB,GAAG,aAAa,GAAG,MAAM,CAAC;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,CAAC;IACtD,UAAU,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAClD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAChC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,eAAe,CAAC;IACxB,aAAa,EAAE,qBAAqB,EAAE,CAAC;CACxC;AA2BD,qBAAa,gBAAiB,SAAQ,KAAK;IAOhC,QAAQ,EAAE,MAAM;IANlB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;gBAG5B,OAAO,EAAE,MAAM,EACR,QAAQ,EAAE,MAAM,EACvB,OAAO,CAAC,EAAE;QACR,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB;IAYM,QAAQ;CAUlB;AA8DD,wBAAgB,sBAAsB,CAEpC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,UAAU,EAAE,MAAM,GACjB,MAAM,EAAE,CAkDV;AAmRD,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,gBAAgB,CAElB;AAGD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAatE;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASjE;AASD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAQpE"}
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/extractors/markdown.ts"],"names":[],"mappings":"AAwDA,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kBAAkB,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,YAAY,CAAC;IAC3D,wBAAwB,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IAEnD,SAAS,CAAC,EAAE,SAAS,GAAG,gBAAgB,GAAG,aAAa,GAAG,MAAM,CAAC;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,CAAC;IACtD,UAAU,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAClD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAChC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,eAAe,CAAC;IACxB,aAAa,EAAE,qBAAqB,EAAE,CAAC;IACvC,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA2BD,qBAAa,gBAAiB,SAAQ,KAAK;IAOhC,QAAQ,EAAE,MAAM;IANlB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;gBAG5B,OAAO,EAAE,MAAM,EACR,QAAQ,EAAE,MAAM,EACvB,OAAO,CAAC,EAAE;QACR,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB;IAYM,QAAQ;CAUlB;AA8DD,wBAAgB,sBAAsB,CAEpC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,UAAU,EAAE,MAAM,GACjB,MAAM,EAAE,CAkDV;AAmRD,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,gBAAgB,CAElB;AAGD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAatE;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASjE;AASD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAQpE"}

package/dist/extractors/symbols-coordinator.d.ts

@@ -1,7 +1,41 @@
 import { type ManifestSymbolEntry, enrichSymbolCoordinatesWithTsMorph } from "./symbols-ts.js";
 export type { ManifestSymbolEntry };
+export type SourceAnalysisMode = "parser" | "fallback";
+export type SourceSymbolKind = "function" | "class" | "interface" | "type" | "enum" | "variable" | "unknown";
+export interface SourceSymbolAnalysis {
+    name: string;
+    kind: SourceSymbolKind;
+    startLine: number;
+    startColumn: number;
+    endLine: number;
+    endColumn: number;
+    directiveText?: string;
+}
+export interface SourceModuleAnalysis {
+    title: string;
+    language: string;
+    analysisMode: SourceAnalysisMode;
+    fallbackReason?: string;
+}
+export interface SourceAnalysisResult {
+    sourceFile: string;
+    language: string;
+    providerId: string | null;
+    module: SourceModuleAnalysis;
+    symbols: SourceSymbolAnalysis[];
+}
+export interface SourceAnalysisProvider {
+    id: string;
+    supportsFile(filePath: string): boolean;
+    analyzeText(filePath: string, content: string): SourceAnalysisResult;
+}
+export interface AnalyzeSourceTextOptions {
+    providers?: SourceAnalysisProvider[];
+}
 interface EnrichSymbolCoordinatesDeps {
     enrichTsCoordinates: typeof enrichSymbolCoordinatesWithTsMorph;
 }
+export declare function analyzeSourceText(entries: ManifestSymbolEntry[], workspaceRoot: string, deps?: Partial<EnrichSymbolCoordinatesDeps>): Promise<ManifestSymbolEntry[]>;
+export declare function analyzeSourceText(filePath: string, content: string, options?: AnalyzeSourceTextOptions): SourceAnalysisResult;
 export declare function enrichSymbolCoordinates(entries: ManifestSymbolEntry[], workspaceRoot: string, deps?: Partial<EnrichSymbolCoordinatesDeps>): Promise<ManifestSymbolEntry[]>;
 //# sourceMappingURL=symbols-coordinator.d.ts.map

package/dist/extractors/symbols-coordinator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"symbols-coordinator.d.ts","sourceRoot":"","sources":["../../src/extractors/symbols-coordinator.ts"],"names":[],"mappings":"AAoBA,OAAO,EACL,KAAK,mBAAmB,EACxB,kCAAkC,EACnC,MAAM,iBAAiB,CAAC;AAazB,YAAY,EAAE,mBAAmB,EAAE,CAAC;AAEpC,UAAU,2BAA2B;IACnC,mBAAmB,EAAE,OAAO,kCAAkC,CAAC;CAChE;AAED,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,mBAAmB,EAAE,EAC9B,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,2BAA2B,CAAC,GAC1C,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAqChC"}
+{"version":3,"file":"symbols-coordinator.d.ts","sourceRoot":"","sources":["../../src/extractors/symbols-coordinator.ts"],"names":[],"mappings":"AAoBA,OAAO,EAEL,KAAK,mBAAmB,EACxB,kCAAkC,EACnC,MAAM,iBAAiB,CAAC;AAazB,YAAY,EAAE,mBAAmB,EAAE,CAAC;AAEpC,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEvD,MAAM,MAAM,gBAAgB,GACxB,UAAU,GACV,OAAO,GACP,WAAW,GACX,MAAM,GACN,MAAM,GACN,UAAU,GACV,SAAS,CAAC;AAEd,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,gBAAgB,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,kBAAkB,CAAC;IACjC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,oBAAoB,CAAC;IAC7B,OAAO,EAAE,oBAAoB,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACxC,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,oBAAoB,CAAC;CACtE;AAED,MAAM,WAAW,wBAAwB;IACvC,SAAS,CAAC,EAAE,sBAAsB,EAAE,CAAC;CACtC;AAED,UAAU,2BAA2B;IACnC,mBAAmB,EAAE,OAAO,kCAAkC,CAAC;CAChE;AA+BD,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,mBAAmB,EAAE,EAC9B,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,2BAA2B,CAAC,GAC1C,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAAC;AAClC,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,wBAAwB,GACjC,oBAAoB,CAAC;AAgCxB,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,mBAAmB,EAAE,EAC9B,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,2BAA2B,CAAC,GAC1C,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAqChC"}

package/dist/extractors/symbols-coordinator.js

@@ -17,7 +17,7 @@
 */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { enrichSymbolCoordinatesWithTsMorph, } from "./symbols-ts.js";
+import { createTsMorphSourceAnalysisProvider, enrichSymbolCoordinatesWithTsMorph, } from "./symbols-ts.js";
 const TS_JS_EXTENSIONS = new Set([
     ".ts",
     ".tsx",
@@ -28,6 +28,52 @@ const TS_JS_EXTENSIONS = new Set([
     ".mjs",
     ".cjs",
 ]);
+const SOURCE_LANGUAGE_EXTENSIONS = {
+    ".c": "c",
+    ".cc": "cpp",
+    ".cjs": "javascript",
+    ".cpp": "cpp",
+    ".cs": "csharp",
+    ".cts": "typescript",
+    ".go": "go",
+    ".h": "c",
+    ".hpp": "cpp",
+    ".java": "java",
+    ".js": "javascript",
+    ".jsx": "javascript",
+    ".kt": "kotlin",
+    ".mjs": "javascript",
+    ".mts": "typescript",
+    ".php": "php",
+    ".py": "python",
+    ".rb": "ruby",
+    ".rs": "rust",
+    ".swift": "swift",
+    ".ts": "typescript",
+    ".tsx": "typescript",
+};
+const DEFAULT_SOURCE_ANALYSIS_PROVIDERS = [
+    createTsMorphSourceAnalysisProvider(),
+];
+// implements REQ-001
+export function analyzeSourceText(filePathOrEntries, contentOrWorkspaceRoot, optionsOrDeps) {
+    if (Array.isArray(filePathOrEntries)) {
+        return enrichSymbolCoordinates(filePathOrEntries, contentOrWorkspaceRoot, optionsOrDeps);
+    }
+    const providers = optionsOrDeps?.providers ??
+        DEFAULT_SOURCE_ANALYSIS_PROVIDERS;
+    for (const provider of providers) {
+        if (!provider.supportsFile(filePathOrEntries))
+            continue;
+        try {
+            return provider.analyzeText(filePathOrEntries, contentOrWorkspaceRoot);
+        }
+        catch {
+            return createFallbackAnalysis(filePathOrEntries, "provider_error");
+        }
+    }
+    return createFallbackAnalysis(filePathOrEntries, "unsupported_language");
+}
 export async function enrichSymbolCoordinates(entries, workspaceRoot, deps) {
     // implements REQ-vscode-traceability
     const enrichTsCoordinates = deps?.enrichTsCoordinates ?? enrichSymbolCoordinatesWithTsMorph;
@@ -106,3 +152,26 @@ function resolveSourcePath(sourceFile, workspaceRoot) {
 function escapeRegex(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+function createFallbackAnalysis(filePath, fallbackReason) {
+    const language = detectSourceLanguage(filePath);
+    return {
+        sourceFile: filePath,
+        language,
+        providerId: null,
+        module: {
+            title: inferModuleTitle(filePath),
+            language,
+            analysisMode: "fallback",
+            fallbackReason,
+        },
+        symbols: [],
+    };
+}
+function detectSourceLanguage(filePath) {
+    return SOURCE_LANGUAGE_EXTENSIONS[path.extname(filePath).toLowerCase()] ?? "unknown";
+}
+function inferModuleTitle(filePath) {
+    const extension = path.extname(filePath);
+    const basename = path.basename(filePath, extension);
+    return basename.length > 0 ? basename : path.basename(filePath);
+}

package/dist/extractors/symbols-ts.d.ts

@@ -1,3 +1,4 @@
+import type { SourceAnalysisProvider } from "./symbols-coordinator.js";
 export interface SymbolCoordinates {
     sourceLine: number;
     sourceColumn: number;
@@ -17,5 +18,6 @@ export interface ManifestSymbolEntry {
     links?: string[];
     [key: string]: unknown;
 }
+export declare function createTsMorphSourceAnalysisProvider(): SourceAnalysisProvider;
 export declare function enrichSymbolCoordinatesWithTsMorph(entries: ManifestSymbolEntry[], workspaceRoot: string): Promise<ManifestSymbolEntry[]>;
 //# sourceMappingURL=symbols-ts.d.ts.map

package/dist/extractors/symbols-ts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"symbols-ts.d.ts","sourceRoot":"","sources":["../../src/extractors/symbols-ts.ts"],"names":[],"mappings":"AA2BA,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;AAED,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;AAaD,wBAAsB,kCAAkC,CACtD,OAAO,EAAE,mBAAmB,EAAE,EAC9B,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAuEhC"}
+{"version":3,"file":"symbols-ts.d.ts","sourceRoot":"","sources":["../../src/extractors/symbols-ts.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EACV,sBAAsB,EAIvB,MAAM,0BAA0B,CAAC;AAElC,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;AAED,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;AAcD,wBAAgB,mCAAmC,IAAI,sBAAsB,CA6B5E;AAED,wBAAsB,kCAAkC,CACtD,OAAO,EAAE,mBAAmB,EAAE,EAC9B,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAuEhC"}