gitnexus 1.6.5-rc.8 → 1.6.5

package/dist/cli/analyze.js

@@ -86,6 +86,20 @@ function ensureHeap() {
     }
     return true;
 }
+/**
+ * Whether the post-index skill step should run.
+ *
+ * The gated block does two things in sequence: (1) generates the community
+ * skill files from `--skills`, and (2) re-runs `generateAIContextFiles` so
+ * AGENTS.md/CLAUDE.md can reference the freshly written skills. Both are
+ * suppressed together — `--index-only` drops the entire step, not just the
+ * community-skill write. Name retained for the test contract; see call site
+ * in `analyzeCommand` for the AGENTS.md/CLAUDE.md re-generation it also gates.
+ *
+ * Kept as a pure helper so the `--index-only --skills` contract is unit-tested
+ * without booting the full analyze pipeline (#742 review).
+ */
+export const shouldGenerateCommunitySkillFiles = (options, pipelineResult) => Boolean(options?.skills && pipelineResult && !options?.indexOnly);
 export const analyzeCommand = async (inputPath, options) => {
     if (ensureHeap())
         return;
@@ -151,6 +165,15 @@ export const analyzeCommand = async (inputPath, options) => {
         process.env.GITNEXUS_EMBEDDING_DEVICE = options.embeddingDevice;
     }
     console.log('\n  GitNexus Analyzer\n');
+    // `--index-only` is the stronger contract — it suppresses every form of file
+    // injection, including community skill writes that `--skills` would normally
+    // produce. Surface the override explicitly so users don't wonder why a
+    // pipeline re-index ran but no skill files appeared. The pipeline still
+    // re-runs (see `force: options?.force || options?.skills` below); the warning
+    // is purely about the dropped post-index write step.
+    if (options?.indexOnly && options?.skills) {
+        console.log('  Note: --index-only overrides --skills; community skill files will not be written.\n');
+    }
     let repoPath;
     if (inputPath) {
         repoPath = path.resolve(inputPath);
@@ -285,6 +308,9 @@ export const analyzeCommand = async (inputPath, options) => {
     const t0 = Date.now();
     // ── Run shared analysis orchestrator ───────────────────────────────
     try {
+        const skipAll = options?.indexOnly;
+        const skipAgentsMd = skipAll || options?.skipAgentsMd;
+        const skipSkills = skipAll || options?.skipSkills;
         const result = await runFullAnalysis(repoPath, {
             // Pipeline re-index — OR'd with --skills because skill generation
             // needs a fresh pipelineResult. Has no bearing on the registry
@@ -294,8 +320,14 @@ export const analyzeCommand = async (inputPath, options) => {
             embeddingsNodeLimit,
             dropEmbeddings: options?.dropEmbeddings,
             skipGit: options?.skipGit,
-            skipAgentsMd: options?.skipAgentsMd,
-            noStats: options?.noStats,
+            skipAgentsMd,
+            skipSkills,
+            // commander.js `.option('--no-stats', …)` registers the flag as
+            // `options.stats` (boolean, default true; `false` when the user
+            // passed --no-stats). Reading `options?.noStats` here returns
+            // undefined every time, so the flag was a no-op on the markdown
+            // rewrite path before this fix. See #1477.
+            noStats: options?.stats === false,
             registryName: options?.name,
             // Registry-collision bypass — its own CLI flag, intentionally NOT
             // overloading --force. A user who hits the collision guard should
@@ -335,8 +367,10 @@ export const analyzeCommand = async (inputPath, options) => {
         // exit code and an actionable error instead of being mistaken for
         // a healthy index.
         await assertAnalysisFinalized(repoPath);
-        // Skill generation (CLI-only, uses pipeline result from analysis)
-        if (options?.skills && result.pipelineResult) {
+        // Skill generation (CLI-only, uses pipeline result from analysis).
+        // Gated so `--index-only --skills` skips community skill writes too
+        // (`shouldGenerateCommunitySkillFiles` — see unit test).
+        if (shouldGenerateCommunitySkillFiles(options, result.pipelineResult)) {
             updateBar(99, 'Generating skill files...');
             try {
                 const { generateSkillFiles } = await import('./skill-gen.js');
@@ -364,7 +398,13 @@ export const analyzeCommand = async (inputPath, options) => {
                         communities: s.communities,
                         clusters: aggregatedClusterCount,
                         processes: s.processes,
-                    }, skillResult.skills, { skipAgentsMd: options?.skipAgentsMd, noStats: options?.noStats });
+                    }, skillResult.skills, {
+                        skipAgentsMd,
+                        skipSkills,
+                        // Mirror runFullAnalysis `noStats` bridge (#1477) — same expression;
+                        // exercised on the `--skills` path by analyze-no-stats-bridge.test.ts.
+                        noStats: options?.stats === false,
+                    });
                 }
             }
             catch {

package/dist/cli/index.js

@@ -21,9 +21,14 @@ program
     'Optional [limit] overrides the 50,000-node safety cap; pass 0 to disable the cap entirely.')
     .option('--drop-embeddings', 'Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` ' +
     'preserves any embeddings already present in the index.')
-    .option('--skills', 'Generate repo-specific skill files from detected communities')
+    .option('--skills', 'Generate repo-specific skill files from detected communities ' +
+    '(no-op when --index-only is also set).')
     .option('--skip-agents-md', 'Skip updating the gitnexus section in AGENTS.md and CLAUDE.md')
     .option('--no-stats', 'Omit volatile file/symbol counts from AGENTS.md and CLAUDE.md')
+    .option('--skip-skills', 'Skip installing standard GitNexus skill files under .claude/skills/gitnexus/. ' +
+    'Does not suppress community skills from --skills (those use .claude/skills/generated/). ' +
+    'Use --index-only to skip all AI-context file injection.')
+    .option('--index-only', 'Pure index mode: skip all file injection (AGENTS.md, CLAUDE.md, skills)')
     .option('--skip-git', 'Treat the provided path/cwd as the index root and skip parent git-root discovery')
     .option('--name <alias>', 'Register this repo under a custom name in ~/.gitnexus/registry.json ' +
     '(disambiguates repos whose paths share a basename, e.g. two different .../app folders)')
@@ -98,6 +103,8 @@ program
     .option('--reasoning-model', 'Mark deployment as reasoning model (o1/o3/o4-mini) — strips temperature, uses max_completion_tokens')
     .option('--no-reasoning-model', 'Disable reasoning model mode (overrides saved config)')
     .option('--concurrency <n>', 'Parallel LLM calls (default: 3)', '3')
+    .option('--timeout <seconds>', 'Per-attempt LLM request timeout in seconds (default: 60)')
+    .option('--retries <n>', 'Max LLM retry attempts per request (default: 3)')
     .option('--gist', 'Publish wiki as a public GitHub Gist after generation')
     .option('-v, --verbose', 'Enable verbose output (show LLM commands and responses)')
     .option('--review', 'Stop after grouping to review module structure before generating pages')

package/dist/cli/setup.js

@@ -308,6 +308,24 @@ async function installClaudeCodeHooks(result) {
         catch {
             // Script not found in source — skip
         }
+        try {
+            await fs.copyFile(path.join(pluginHooksPath, 'hook-lock.cjs'), path.join(destHooksDir, 'hook-lock.cjs'));
+        }
+        catch {
+            // Helper not found in source — skip
+        }
+        try {
+            await fs.copyFile(path.join(pluginHooksPath, 'hook-db-lock-probe.cjs'), path.join(destHooksDir, 'hook-db-lock-probe.cjs'));
+        }
+        catch {
+            // Helper not found in source — skip
+        }
+        try {
+            await fs.copyFile(path.join(pluginHooksPath, 'win-rm-list-json.ps1'), path.join(destHooksDir, 'win-rm-list-json.ps1'));
+        }
+        catch {
+            // Helper not found in source — skip
+        }
         const hookPath = path.join(destHooksDir, 'gitnexus-hook.cjs').replace(/\\/g, '/');
         // Escape backslashes FIRST, then quotes (CodeQL js/incomplete-sanitization).
         // The previous shape `replace(/"/g, '\\"')` alone would let `path\with"quote`

package/dist/cli/wiki.d.ts

@@ -17,5 +17,7 @@ export interface WikiCommandOptions {
     provider?: LLMProvider;
     verbose?: boolean;
     review?: boolean;
+    timeout?: string;
+    retries?: string;
 }
 export declare const wikiCommand: (inputPath?: string, options?: WikiCommandOptions) => Promise<void>;

package/dist/cli/wiki.js

@@ -304,6 +304,17 @@ export const wikiCommand = async (inputPath, options) => {
             }
         }
     }
+    // ── Apply per-run overrides not saved to config ────────────────────
+    if (options?.timeout) {
+        const secs = parseInt(options.timeout, 10);
+        if (!isNaN(secs) && secs > 0)
+            llmConfig.requestTimeoutMs = secs * 1000;
+    }
+    if (options?.retries) {
+        const n = parseInt(options.retries, 10);
+        if (!isNaN(n) && n > 0)
+            llmConfig.maxAttempts = n;
+    }
     // ── Setup progress bar with elapsed timer ──────────────────────────
     const bar = new cliProgress.SingleBar({
         format: '  {bar} {percentage}% | {phase}',

package/dist/core/augmentation/engine.js

@@ -76,6 +76,9 @@ async function findRepoForCwd(cwd) {
 export async function augment(pattern, cwd) {
     if (!pattern || pattern.length < 3)
         return '';
+    const patternFirstWord = pattern.trim().replace(/'/g, "''").split(/\s+/)[0];
+    if (!patternFirstWord || patternFirstWord.length < 2)
+        return '';
     const workDir = cwd || process.cwd();
     try {
         const repo = await findRepoForCwd(workDir);
@@ -90,9 +93,7 @@ export async function augment(pattern, cwd) {
             await initLbug(repoId, repo.lbugPath);
         }
         // Step 1: BM25 search (fast, no embeddings)
-        const { results: bm25Results } = await searchFTSFromLbug(pattern, 10, repoId);
-        if (bm25Results.length === 0)
-            return '';
+        const { results: bm25Results, ftsAvailable } = await searchFTSFromLbug(pattern, 10, repoId);
         // Step 2: Map BM25 file results to symbols
         const symbolMatches = [];
         for (const result of bm25Results.slice(0, 5)) {
@@ -100,7 +101,7 @@ export async function augment(pattern, cwd) {
             try {
                 const symbols = await executeQuery(repoId, `
           MATCH (n) WHERE n.filePath = '${escaped}'
-          AND n.name CONTAINS '${pattern.replace(/'/g, "''").split(/\s+/)[0]}'
+          AND n.name CONTAINS '${patternFirstWord}'
           RETURN n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath
           LIMIT 3
         `);
@@ -118,6 +119,25 @@ export async function augment(pattern, cwd) {
                 /* skip */
             }
         }
+        // When FTS indexes are unavailable (read-only DB, first run before indexes are built),
+        // fall back to a direct name CONTAINS query so enrichment still works.
+        if (symbolMatches.length === 0 && !ftsAvailable) {
+            const fallbackRows = await executeQuery(repoId, `
+        MATCH (n)
+        WHERE n.name CONTAINS '${patternFirstWord}'
+        RETURN n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath
+        LIMIT 5
+      `).catch(() => []);
+            for (const sym of fallbackRows) {
+                symbolMatches.push({
+                    nodeId: sym.id || sym[0],
+                    name: sym.name || sym[1],
+                    type: sym.type || sym[2],
+                    filePath: sym.filePath || sym[3],
+                    score: 1.0,
+                });
+            }
+        }
         if (symbolMatches.length === 0)
             return '';
         // Step 3: Batch-fetch callers/callees/processes/cohesion for top matches

package/dist/core/embeddings/http-client.js

@@ -30,8 +30,11 @@ const readConfig = () => {
     const rawDims = process.env.GITNEXUS_EMBEDDING_DIMS;
     let dimensions;
     if (rawDims !== undefined) {
+        if (!/^\d+$/.test(rawDims)) {
+            throw new Error(`GITNEXUS_EMBEDDING_DIMS must be a positive integer, got "${rawDims}"`);
+        }
         const parsed = parseInt(rawDims, 10);
-        if (Number.isNaN(parsed) || parsed <= 0) {
+        if (parsed <= 0) {
             throw new Error(`GITNEXUS_EMBEDDING_DIMS must be a positive integer, got "${rawDims}"`);
         }
         dimensions = parsed;
@@ -73,9 +76,22 @@ const safeUrl = (url) => {
  * @param model - Model name for the request body
  * @param apiKey - Bearer token (only used in Authorization header)
  * @param batchIndex - Logical batch number (for error context)
- * @param attempt - Current retry attempt (internal)
+ * @param dimensions - Optional output-vector size. When provided, sent as
+ *   the `dimensions` field in the request body. Endpoints that implement
+ *   Matryoshka truncation (OpenAI text-embedding-3-*, Cohere embed-v3,
+ *   Voyage) return a truncated vector at that size; endpoints that do not
+ *   recognise the field may ignore it or return 400. Leave
+ *   `GITNEXUS_EMBEDDING_DIMS` unset for strict backends that reject
+ *   unknown fields.
  */
-const httpEmbedBatch = async (url, batch, model, apiKey, batchIndex = 0) => {
+const httpEmbedBatch = async (url, batch, model, apiKey, batchIndex = 0, dimensions) => {
+    const requestBody = {
+        input: batch,
+        model,
+    };
+    if (dimensions !== undefined) {
+        requestBody.dimensions = dimensions;
+    }
     let resp;
     try {
         resp = await resilientFetch(url, {
@@ -85,7 +101,7 @@ const httpEmbedBatch = async (url, batch, model, apiKey, batchIndex = 0) => {
                 'Content-Type': 'application/json',
                 Authorization: `Bearer ${apiKey}`,
             },
-            body: JSON.stringify({ input: batch, model }),
+            body: JSON.stringify(requestBody),
         }, {
             breakerKey: HTTP_BREAKER_KEY,
             retry: { maxAttempts: HTTP_MAX_RETRIES + 1, baseDelayMs: HTTP_RETRY_BACKOFF_MS },
@@ -130,7 +146,7 @@ export const httpEmbed = async (texts) => {
     for (let i = 0; i < texts.length; i += HTTP_BATCH_SIZE) {
         const batch = texts.slice(i, i + HTTP_BATCH_SIZE);
         const batchIndex = Math.floor(i / HTTP_BATCH_SIZE);
-        const items = await httpEmbedBatch(url, batch, config.model, config.apiKey, batchIndex);
+        const items = await httpEmbedBatch(url, batch, config.model, config.apiKey, batchIndex, config.dimensions);
         if (items.length !== batch.length) {
             throw new Error(`Embedding endpoint returned ${items.length} vectors for ${batch.length} texts ` +
                 `(${safeUrl(url)}, batch ${batchIndex})`);
@@ -164,7 +180,7 @@ export const httpEmbedQuery = async (text) => {
     if (!config)
         throw new Error('HTTP embedding not configured');
     const url = `${config.baseUrl}/embeddings`;
-    const items = await httpEmbedBatch(url, [text], config.model, config.apiKey);
+    const items = await httpEmbedBatch(url, [text], config.model, config.apiKey, 0, config.dimensions);
     if (!items.length) {
         throw new Error(`Embedding endpoint returned empty response (${safeUrl(url)})`);
     }

package/dist/core/incremental/shadow-candidates.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Shadow-candidate path derivation for incremental indexing.
+ *
+ * Background — Bugbot review on PR #1479:
+ *   queryImporters() on a NEWLY ADDED file returns 0 importers in the
+ *   pre-pipeline DB, because the new file's IMPORTS rows haven't been
+ *   written yet. But pre-existing files may have IMPORTS edges that
+ *   *resolved to a sibling path*, and the newcomer can now steal that
+ *   resolution under standard JS/TS module-resolution rules. Without
+ *   pulling those pre-existing files into the writable set, their
+ *   stale CALLS edges remain pointing at the OLD resolution target.
+ *
+ * Given an added file path, this helper enumerates the pre-existing
+ * file paths whose import-resolution claim the newcomer can steal.
+ * Caller filters the candidates against the prior-run `fileHashes`
+ * map so we only query importers of paths that actually existed.
+ *
+ * Shadow patterns covered (resolution-priority-aware):
+ *
+ *   (a) Same basename, different extension —
+ *       added `foo/bar.ts` shadows `foo/bar.{tsx,js,jsx,mjs,cjs,d.ts}`.
+ *   (b) Bare-file beats directory-style index —
+ *       added `foo/bar.ts` shadows `foo/bar/index.{ts,tsx,...}`.
+ *   (c) Directory-index beats bare-file —
+ *       added `foo/index.ts` shadows `foo.{ts,tsx,...}` (rare but real,
+ *       e.g. converting a single-file module into a directory module).
+ *
+ * Resolution-order priority is conservatively wide: we enumerate ALL
+ * common extensions because we don't know which the importer actually
+ * specified, and over-seeding is harmless (extra BFS work, but the
+ * subgraph extract still gates write-back by file membership).
+ *
+ * Cross-platform path separators: candidates are emitted with both `/`
+ * and `\` for shadow pattern (b), since the caller's prior fileHashes
+ * map may use either depending on the OS that wrote it.
+ */
+/**
+ * Enumerate pre-existing paths whose import-resolution `added` can steal.
+ *
+ * @param added — repo-relative path of a newly-added file
+ * @returns deduplicated list of candidate paths (NOT filtered against
+ *          any known-files set — caller does that)
+ */
+export declare const shadowCandidatesFor: (added: string) => string[];

package/dist/core/incremental/shadow-candidates.js

@@ -0,0 +1,74 @@
+/**
+ * Shadow-candidate path derivation for incremental indexing.
+ *
+ * Background — Bugbot review on PR #1479:
+ *   queryImporters() on a NEWLY ADDED file returns 0 importers in the
+ *   pre-pipeline DB, because the new file's IMPORTS rows haven't been
+ *   written yet. But pre-existing files may have IMPORTS edges that
+ *   *resolved to a sibling path*, and the newcomer can now steal that
+ *   resolution under standard JS/TS module-resolution rules. Without
+ *   pulling those pre-existing files into the writable set, their
+ *   stale CALLS edges remain pointing at the OLD resolution target.
+ *
+ * Given an added file path, this helper enumerates the pre-existing
+ * file paths whose import-resolution claim the newcomer can steal.
+ * Caller filters the candidates against the prior-run `fileHashes`
+ * map so we only query importers of paths that actually existed.
+ *
+ * Shadow patterns covered (resolution-priority-aware):
+ *
+ *   (a) Same basename, different extension —
+ *       added `foo/bar.ts` shadows `foo/bar.{tsx,js,jsx,mjs,cjs,d.ts}`.
+ *   (b) Bare-file beats directory-style index —
+ *       added `foo/bar.ts` shadows `foo/bar/index.{ts,tsx,...}`.
+ *   (c) Directory-index beats bare-file —
+ *       added `foo/index.ts` shadows `foo.{ts,tsx,...}` (rare but real,
+ *       e.g. converting a single-file module into a directory module).
+ *
+ * Resolution-order priority is conservatively wide: we enumerate ALL
+ * common extensions because we don't know which the importer actually
+ * specified, and over-seeding is harmless (extra BFS work, but the
+ * subgraph extract still gates write-back by file membership).
+ *
+ * Cross-platform path separators: candidates are emitted with both `/`
+ * and `\` for shadow pattern (b), since the caller's prior fileHashes
+ * map may use either depending on the OS that wrote it.
+ */
+const SHADOW_EXTS = ['.d.ts', '.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs'];
+/**
+ * Enumerate pre-existing paths whose import-resolution `added` can steal.
+ *
+ * @param added — repo-relative path of a newly-added file
+ * @returns deduplicated list of candidate paths (NOT filtered against
+ *          any known-files set — caller does that)
+ */
+export const shadowCandidatesFor = (added) => {
+    const ext = SHADOW_EXTS.find((e) => added.endsWith(e));
+    if (!ext)
+        return [];
+    const noExt = added.slice(0, -ext.length);
+    const out = new Set();
+    // (a) Same basename, different extension.
+    for (const alt of SHADOW_EXTS) {
+        if (alt !== ext)
+            out.add(noExt + alt);
+    }
+    // (b) Bare file beats sibling directory-style index.
+    for (const idx of SHADOW_EXTS) {
+        out.add(`${noExt}/index${idx}`);
+        out.add(`${noExt}\\index${idx}`);
+    }
+    // (c) New `foo/index.ext` shadows old `foo.ext`.
+    const idxSuffixSlash = '/index';
+    const idxSuffixBack = '\\index';
+    let dir = null;
+    if (noExt.endsWith(idxSuffixSlash))
+        dir = noExt.slice(0, -idxSuffixSlash.length);
+    else if (noExt.endsWith(idxSuffixBack))
+        dir = noExt.slice(0, -idxSuffixBack.length);
+    if (dir !== null) {
+        for (const alt of SHADOW_EXTS)
+            out.add(dir + alt);
+    }
+    return [...out];
+};

package/dist/core/incremental/subgraph-extract.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Subgraph extraction for incremental DB writeback.
+ *
+ * Given the FULL ctx.graph produced by the pipeline (all files parsed,
+ * all phases run) and the set of file paths whose DB rows must be
+ * replaced, produce a smaller KnowledgeGraph that contains:
+ *
+ *   - Every node whose `properties.filePath` is in `toWriteSet`.
+ *   - Every graph-wide node (Community, Process) — these are regenerated
+ *     each run by the communities/processes phases and must be fully
+ *     rewritten.
+ *   - Every relationship where AT LEAST ONE endpoint is in the writable
+ *     set above. Relationships entirely between unchanged-file nodes
+ *     are skipped — their rows are still in the DB and re-inserting
+ *     them would PK-conflict at COPY time.
+ *
+ * The resulting subgraph is what gets passed to `loadGraphToLbug` after
+ * the orchestrator has deleted the corresponding DB rows. Hydrated
+ * unchanged-file rows are never touched in the DB.
+ *
+ * # Cross-file edge consistency (Finding 1)
+ *
+ * `extractChangedSubgraph` intentionally does NOT expand the set it is
+ * given — expansion is the orchestrator's job, so the SAME expanded set
+ * can be fed to both `deleteNodesForFile` and this function (asymmetry
+ * between the delete set and the write set silently corrupts the DB).
+ * `computeEffectiveWriteSet` below performs the boundary-crossing 1-hop
+ * walk; the orchestrator composes it with its importer-BFS expansion and
+ * passes the result here.
+ *
+ * Why the 1-hop walk is needed: consider a barrel re-export change —
+ * file C (a barrel) shifts `export { foo } from './b'` to
+ * `export { foo } from './d'`. After scope resolution, file A's CALLS
+ * edge to `foo` resolves to D instead of B, even though A's content is
+ * byte-for-byte identical:
+ *
+ *   - Old A→B edge survives in DB (neither A nor B is changed → not deleted)
+ *   - New A→D edge is missing (neither A nor D in writable set → skipped)
+ *
+ * Pulling the unchanged-side file of every writable-boundary-crossing
+ * edge into the write set fixes both halves: the orchestrator's
+ * `DETACH DELETE` cleans up the stale unchanged-side rows, and the new
+ * cross-file edges land because at least one endpoint is now writable.
+ *
+ * Limitation (documented): if a file X *stopped* importing from a
+ * changed file C, X has no edge to C in the new graph, so this 1-hop
+ * walk doesn't catch it. The orchestrator's importer-BFS (which reads
+ * IMPORTS from the pre-pipeline DB) covers that case instead.
+ */
+import type { KnowledgeGraph } from '../graph/types.js';
+export declare const extractChangedSubgraph: (fullGraph: KnowledgeGraph, toWriteSet: ReadonlySet<string>) => KnowledgeGraph;
+/**
+ * Public — derive the EFFECTIVE write-set: `toWriteSet` expanded by one
+ * hop along every edge in the new graph that crosses the writable
+ * boundary (one endpoint in a writable file, the other in an unchanged
+ * file). The unchanged-side file is pulled in so its stale rows are
+ * deleted + rewritten in lockstep with the changed side.
+ *
+ * Single pass over the edge list. Does NOT mutate `toWriteSet`. The
+ * orchestrator MUST feed the returned set to both `deleteNodesForFile`
+ * and `extractChangedSubgraph` — feeding the unexpanded set to either
+ * one leaves stale rows or PK-conflicts at COPY time.
+ */
+export declare const computeEffectiveWriteSet: (fullGraph: KnowledgeGraph, toWriteSet: ReadonlySet<string>) => Set<string>;

package/dist/core/incremental/subgraph-extract.js

@@ -0,0 +1,111 @@
+/**
+ * Subgraph extraction for incremental DB writeback.
+ *
+ * Given the FULL ctx.graph produced by the pipeline (all files parsed,
+ * all phases run) and the set of file paths whose DB rows must be
+ * replaced, produce a smaller KnowledgeGraph that contains:
+ *
+ *   - Every node whose `properties.filePath` is in `toWriteSet`.
+ *   - Every graph-wide node (Community, Process) — these are regenerated
+ *     each run by the communities/processes phases and must be fully
+ *     rewritten.
+ *   - Every relationship where AT LEAST ONE endpoint is in the writable
+ *     set above. Relationships entirely between unchanged-file nodes
+ *     are skipped — their rows are still in the DB and re-inserting
+ *     them would PK-conflict at COPY time.
+ *
+ * The resulting subgraph is what gets passed to `loadGraphToLbug` after
+ * the orchestrator has deleted the corresponding DB rows. Hydrated
+ * unchanged-file rows are never touched in the DB.
+ *
+ * # Cross-file edge consistency (Finding 1)
+ *
+ * `extractChangedSubgraph` intentionally does NOT expand the set it is
+ * given — expansion is the orchestrator's job, so the SAME expanded set
+ * can be fed to both `deleteNodesForFile` and this function (asymmetry
+ * between the delete set and the write set silently corrupts the DB).
+ * `computeEffectiveWriteSet` below performs the boundary-crossing 1-hop
+ * walk; the orchestrator composes it with its importer-BFS expansion and
+ * passes the result here.
+ *
+ * Why the 1-hop walk is needed: consider a barrel re-export change —
+ * file C (a barrel) shifts `export { foo } from './b'` to
+ * `export { foo } from './d'`. After scope resolution, file A's CALLS
+ * edge to `foo` resolves to D instead of B, even though A's content is
+ * byte-for-byte identical:
+ *
+ *   - Old A→B edge survives in DB (neither A nor B is changed → not deleted)
+ *   - New A→D edge is missing (neither A nor D in writable set → skipped)
+ *
+ * Pulling the unchanged-side file of every writable-boundary-crossing
+ * edge into the write set fixes both halves: the orchestrator's
+ * `DETACH DELETE` cleans up the stale unchanged-side rows, and the new
+ * cross-file edges land because at least one endpoint is now writable.
+ *
+ * Limitation (documented): if a file X *stopped* importing from a
+ * changed file C, X has no edge to C in the new graph, so this 1-hop
+ * walk doesn't catch it. The orchestrator's importer-BFS (which reads
+ * IMPORTS from the pre-pipeline DB) covers that case instead.
+ */
+import { createKnowledgeGraph } from '../graph/graph.js';
+const isGraphWide = (label) => label === 'Community' || label === 'Process';
+/**
+ * Build a Map<nodeId, filePath> for every File-bound node in the graph.
+ * Graph-wide nodes (Community/Process) have no filePath and are filtered.
+ */
+const indexNodeFilePaths = (fullGraph) => {
+    const idx = new Map();
+    fullGraph.forEachNode((n) => {
+        const fp = n.properties?.filePath;
+        if (fp)
+            idx.set(n.id, fp);
+    });
+    return idx;
+};
+export const extractChangedSubgraph = (fullGraph, toWriteSet) => {
+    const sub = createKnowledgeGraph();
+    const writableNodeIds = new Set();
+    fullGraph.forEachNode((n) => {
+        const filePath = n.properties?.filePath;
+        const include = (filePath && toWriteSet.has(filePath)) || isGraphWide(n.label);
+        if (include) {
+            sub.addNode(n);
+            writableNodeIds.add(n.id);
+        }
+    });
+    fullGraph.forEachRelationship((r) => {
+        if (writableNodeIds.has(r.sourceId) || writableNodeIds.has(r.targetId)) {
+            sub.addRelationship(r);
+        }
+    });
+    return sub;
+};
+/**
+ * Public — derive the EFFECTIVE write-set: `toWriteSet` expanded by one
+ * hop along every edge in the new graph that crosses the writable
+ * boundary (one endpoint in a writable file, the other in an unchanged
+ * file). The unchanged-side file is pulled in so its stale rows are
+ * deleted + rewritten in lockstep with the changed side.
+ *
+ * Single pass over the edge list. Does NOT mutate `toWriteSet`. The
+ * orchestrator MUST feed the returned set to both `deleteNodesForFile`
+ * and `extractChangedSubgraph` — feeding the unexpanded set to either
+ * one leaves stale rows or PK-conflicts at COPY time.
+ */
+export const computeEffectiveWriteSet = (fullGraph, toWriteSet) => {
+    const nodeFilePaths = indexNodeFilePaths(fullGraph);
+    const expanded = new Set(toWriteSet);
+    fullGraph.forEachRelationship((r) => {
+        const sourcePath = nodeFilePaths.get(r.sourceId);
+        const targetPath = nodeFilePaths.get(r.targetId);
+        if (!sourcePath || !targetPath)
+            return; // skip edges to graph-wide nodes
+        const sourceWritable = toWriteSet.has(sourcePath);
+        const targetWritable = toWriteSet.has(targetPath);
+        if (sourceWritable && !targetWritable)
+            expanded.add(targetPath);
+        else if (targetWritable && !sourceWritable)
+            expanded.add(sourcePath);
+    });
+    return expanded;
+};

package/dist/core/ingestion/call-processor.d.ts

@@ -2,8 +2,10 @@ import { KnowledgeGraph } from '../graph/types.js';
 import { ASTCache } from './ast-cache.js';
 import type { SymbolDefinition } from '../../_shared/index.js';
 import type { SymbolTableReader, HeritageMap, ExtractedHeritage } from './model/index.js';
+import Parser from 'tree-sitter';
 import type { ResolutionContext } from './model/resolution-context.js';
 import type { TieredCandidates } from './model/resolution-context.js';
+import { SupportedLanguages } from '../../_shared/index.js';
 import type { TypeEnvironment } from './type-env.js';
 import type { BindingAccumulator } from './binding-accumulator.js';
 import type { ExtractedCall, ExtractedAssignment, ExtractedRoute, ExtractedFetchCall, FileConstructorBindings } from './workers/parse-worker.js';
@@ -73,7 +75,16 @@ importedBindingsMap?: ReadonlyMap<string, ReadonlyMap<string, string>>,
  *  Consulted ONLY when SymbolTable has no unambiguous match (local-first principle). */
 importedReturnTypesMap?: ReadonlyMap<string, ReadonlyMap<string, string>>, 
 /** Phase 14 E3: cross-file RAW return types for for-loop element extraction. Keyed by filePath → Map<calleeName, rawReturnType>. */
-importedRawReturnTypesMap?: ReadonlyMap<string, ReadonlyMap<string, string>>, heritageMap?: HeritageMap, bindingAccumulator?: BindingAccumulator) => Promise<ExtractedHeritage[]>;
+importedRawReturnTypesMap?: ReadonlyMap<string, ReadonlyMap<string, string>>, heritageMap?: HeritageMap, bindingAccumulator?: BindingAccumulator, 
+/**
+ * Optional cache for compiled `Parser.Query` objects keyed by language name.
+ * When provided, compiled queries are reused across calls instead of being
+ * re-compiled from the query string for every file. Callers that invoke
+ * `processCalls` many times with single-file batches (e.g. the cross-file
+ * propagation phase) should pass a long-lived map here to avoid O(N)
+ * query recompilation overhead.
+ */
+compiledQueryCache?: Map<SupportedLanguages, Parser.Query>) => Promise<ExtractedHeritage[]>;
 /** Per-file cache for module-alias widening. Cleared between files. */
 type WidenCache = Map<string, readonly SymbolDefinition[]>;
 /**