gitnexus 1.6.6-rc.154 → 1.6.6-rc.155

package/README.md

@@ -423,6 +423,16 @@ Three env vars expose the pool's resilience layers (respawn budget, cumulative-t
 | `GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS`     | `5 × subBatchTimeoutMs` | Total retry wall-time budget per job before quarantining. Bounds exponentially-growing retry waits.                   |
 | `GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD` | `max(3, poolSize)`      | Per-slot consecutive deaths before the pool's circuit breaker trips. After tripping, dispatches require a fresh pool. |
 
+### Graph cleanup tuning
+
+After scope resolution, analyze prunes inert block-local value symbols (a function-local `const`/`let`/`var` that ends up with only its structural `File→DEFINES` edge) to keep the graph focused on cross-symbol relationships. Module/file-scope symbols, class members, and any local with a real edge are always kept.
+
+| Variable                             | Default | Effect                                                                                                  |
+| ------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------- |
+| `GITNEXUS_KEEP_LOCAL_VALUE_SYMBOLS`  | unset   | Set to `1`/`true` to keep inert block-local value symbols instead of pruning them.                      |
+
+Programmatic callers can pass `keepLocalValueSymbols: true` in `PipelineOptions` instead of setting the env var.
+
 ## Privacy
 
 - All processing happens locally on your machine

package/dist/core/ingestion/local-symbol-pruner.d.ts

@@ -0,0 +1,11 @@
+import type { KnowledgeGraph } from '../graph/types.js';
+export interface LocalSymbolPruneStats {
+    candidateNodes: number;
+    prunedNodes: number;
+    keptWithSemanticEdges: number;
+    skippedByEnv: boolean;
+}
+export declare const shouldKeepLocalValueSymbols: () => boolean;
+export declare const pruneLocalValueSymbols: (graph: KnowledgeGraph, options?: {
+    keepLocalValueSymbols?: boolean;
+}) => LocalSymbolPruneStats;

package/dist/core/ingestion/local-symbol-pruner.js

@@ -0,0 +1,63 @@
+import { parseTruthyEnv } from './utils/env.js';
+const LOCAL_VALUE_LABELS = new Set(['Const', 'Variable', 'Static']);
+const KEEP_LOCAL_VALUE_SYMBOLS_ENV = 'GITNEXUS_KEEP_LOCAL_VALUE_SYMBOLS';
+export const shouldKeepLocalValueSymbols = () => parseTruthyEnv(process.env[KEEP_LOCAL_VALUE_SYMBOLS_ENV]);
+const emptyStats = (skippedByEnv) => ({
+    candidateNodes: 0,
+    prunedNodes: 0,
+    keptWithSemanticEdges: 0,
+    skippedByEnv,
+});
+const isLocalValueCandidate = (node) => {
+    if (!LOCAL_VALUE_LABELS.has(node.label))
+        return false;
+    return node.properties.scope === 'block';
+};
+// True when `rel` is the structural `File -> DEFINES -> candidate` edge. Callers
+// guard on the candidate already being the edge target, so only the source label
+// needs checking here.
+const isFileDefinesEdge = (graph, rel) => {
+    if (rel.type !== 'DEFINES')
+        return false;
+    return graph.getNode(rel.sourceId)?.label === 'File';
+};
+export const pruneLocalValueSymbols = (graph, options = {}) => {
+    if (options.keepLocalValueSymbols ?? shouldKeepLocalValueSymbols()) {
+        return emptyStats(true);
+    }
+    const candidateIds = new Set();
+    for (const node of graph.iterNodes()) {
+        if (isLocalValueCandidate(node))
+            candidateIds.add(node.id);
+    }
+    if (candidateIds.size === 0)
+        return emptyStats(false);
+    const candidatesWithSemanticEdges = new Set();
+    for (const rel of graph.iterRelationships()) {
+        // Any outgoing edge from a candidate is a semantic edge: the only structural
+        // edge a block-local value symbol carries is the incoming File -> DEFINES, on
+        // which the candidate is the target, never the source.
+        if (candidateIds.has(rel.sourceId)) {
+            candidatesWithSemanticEdges.add(rel.sourceId);
+        }
+        // An incoming edge is semantic unless it is the structural File -> DEFINES.
+        if (candidateIds.has(rel.targetId)) {
+            if (!isFileDefinesEdge(graph, rel)) {
+                candidatesWithSemanticEdges.add(rel.targetId);
+            }
+        }
+    }
+    let prunedNodes = 0;
+    for (const candidateId of candidateIds) {
+        if (candidatesWithSemanticEdges.has(candidateId))
+            continue;
+        if (graph.removeNode(candidateId))
+            prunedNodes++;
+    }
+    return {
+        candidateNodes: candidateIds.size,
+        prunedNodes,
+        keptWithSemanticEdges: candidatesWithSemanticEdges.size,
+        skippedByEnv: false,
+    };
+};

package/dist/core/ingestion/pipeline-phases/communities.d.ts

@@ -4,7 +4,7 @@
  * Detects code communities via Leiden algorithm and creates
  * Community nodes + MEMBER_OF edges.
  *
- * @deps    mro
+ * @deps    mro, pruneLocalSymbols
  * @reads   graph (all nodes and relationships)
  * @writes  graph (Community nodes, MEMBER_OF edges)
  */

package/dist/core/ingestion/pipeline-phases/communities.js

@@ -4,7 +4,7 @@
  * Detects code communities via Leiden algorithm and creates
  * Community nodes + MEMBER_OF edges.
  *
- * @deps    mro
+ * @deps    mro, pruneLocalSymbols
  * @reads   graph (all nodes and relationships)
  * @writes  graph (Community nodes, MEMBER_OF edges)
  */
@@ -14,7 +14,10 @@ import { isDev } from '../utils/env.js';
 import { logger } from '../../logger.js';
 export const communitiesPhase = {
     name: 'communities',
-    deps: ['mro', 'structure'],
+    // `pruneLocalSymbols` is declared explicitly (not just transitively via `mro`)
+    // so community detection always reads the trimmed graph even if a future option
+    // drops `mro` from the phase list.
+    deps: ['mro', 'pruneLocalSymbols', 'structure'],
     async execute(ctx, deps) {
         const { totalFiles } = getPhaseOutput(deps, 'structure');
         ctx.onProgress({

package/dist/core/ingestion/pipeline-phases/index.d.ts

@@ -14,6 +14,7 @@ export { toolsPhase, type ToolsOutput, type ToolDef } from './tools.js';
 export { ormPhase, type ORMOutput } from './orm.js';
 export { crossFilePhase, type CrossFileOutput } from './cross-file.js';
 export { scopeResolutionPhase, type ScopeResolutionOutput, } from '../scope-resolution/pipeline/phase.js';
+export { pruneLocalSymbolsPhase, type PruneLocalSymbolsOutput } from './prune-local-symbols.js';
 export { mroPhase, type MROOutput } from './mro.js';
 export { communitiesPhase, type CommunitiesOutput } from './communities.js';
 export { processesPhase, type ProcessesOutput } from './processes.js';

package/dist/core/ingestion/pipeline-phases/index.js

@@ -15,6 +15,7 @@ export { toolsPhase } from './tools.js';
 export { ormPhase } from './orm.js';
 export { crossFilePhase } from './cross-file.js';
 export { scopeResolutionPhase, } from '../scope-resolution/pipeline/phase.js';
+export { pruneLocalSymbolsPhase } from './prune-local-symbols.js';
 export { mroPhase } from './mro.js';
 export { communitiesPhase } from './communities.js';
 export { processesPhase } from './processes.js';

package/dist/core/ingestion/pipeline-phases/mro.d.ts

@@ -4,7 +4,7 @@
  * Computes Method Resolution Order (MRO) and creates METHOD_OVERRIDES
  * and METHOD_IMPLEMENTS edges.
  *
- * @deps    crossFile, scopeResolution
+ * @deps    crossFile, scopeResolution, pruneLocalSymbols
  * @reads   graph (all nodes and relationships)
  * @writes  graph (METHOD_OVERRIDES, METHOD_IMPLEMENTS edges)
  */

package/dist/core/ingestion/pipeline-phases/mro.js

@@ -4,7 +4,7 @@
  * Computes Method Resolution Order (MRO) and creates METHOD_OVERRIDES
  * and METHOD_IMPLEMENTS edges.
  *
- * @deps    crossFile, scopeResolution
+ * @deps    crossFile, scopeResolution, pruneLocalSymbols
  * @reads   graph (all nodes and relationships)
  * @writes  graph (METHOD_OVERRIDES, METHOD_IMPLEMENTS edges)
  */
@@ -14,7 +14,7 @@ import { isDev } from '../utils/env.js';
 import { logger } from '../../logger.js';
 export const mroPhase = {
     name: 'mro',
-    deps: ['crossFile', 'scopeResolution', 'structure'],
+    deps: ['crossFile', 'scopeResolution', 'pruneLocalSymbols', 'structure'],
     async execute(ctx, deps) {
         const { totalFiles } = getPhaseOutput(deps, 'structure');
         ctx.onProgress({

package/dist/core/ingestion/pipeline-phases/processes.d.ts

@@ -4,7 +4,7 @@
  * Detects execution flows (processes) and creates Process nodes +
  * STEP_IN_PROCESS edges. Also links Route/Tool nodes to processes.
  *
- * @deps    communities, routes, tools
+ * @deps    communities, routes, tools, pruneLocalSymbols
  * @reads   graph (all nodes and relationships), communityResult, routeRegistry, toolDefs
  * @writes  graph (Process nodes, STEP_IN_PROCESS edges, ENTRY_POINT_OF edges)
  */

package/dist/core/ingestion/pipeline-phases/processes.js

@@ -4,7 +4,7 @@
  * Detects execution flows (processes) and creates Process nodes +
  * STEP_IN_PROCESS edges. Also links Route/Tool nodes to processes.
  *
- * @deps    communities, routes, tools
+ * @deps    communities, routes, tools, pruneLocalSymbols
  * @reads   graph (all nodes and relationships), communityResult, routeRegistry, toolDefs
  * @writes  graph (Process nodes, STEP_IN_PROCESS edges, ENTRY_POINT_OF edges)
  */
@@ -16,8 +16,10 @@ import { logger } from '../../logger.js';
 export const processesPhase = {
     name: 'processes',
     // `structure` supplies `totalFiles` (progress counter) without the spurious
-    // structural data dependency on `parse`.
-    deps: ['communities', 'routes', 'tools', 'structure'],
+    // structural data dependency on `parse`. `pruneLocalSymbols` is declared
+    // explicitly so process extraction always reads the trimmed graph even if a
+    // future option drops the intervening `mro`/`communities` phases.
+    deps: ['communities', 'routes', 'tools', 'pruneLocalSymbols', 'structure'],
     async execute(ctx, deps) {
         const { totalFiles } = getPhaseOutput(deps, 'structure');
         const { communityResult } = getPhaseOutput(deps, 'communities');

package/dist/core/ingestion/pipeline-phases/prune-local-symbols.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Phase: pruneLocalSymbols
+ *
+ * Drops inert function/block-local value symbols after scope resolution has
+ * already used them for binding and call resolution.
+ *
+ * @deps    scopeResolution
+ * @reads   graph (nodes and relationships)
+ * @writes  graph (removes unreferenced local Const/Variable/Static nodes)
+ */
+import type { PipelinePhase } from './types.js';
+import { type LocalSymbolPruneStats } from '../local-symbol-pruner.js';
+export type PruneLocalSymbolsOutput = LocalSymbolPruneStats;
+export declare const pruneLocalSymbolsPhase: PipelinePhase<PruneLocalSymbolsOutput>;

package/dist/core/ingestion/pipeline-phases/prune-local-symbols.js

@@ -0,0 +1,26 @@
+/**
+ * Phase: pruneLocalSymbols
+ *
+ * Drops inert function/block-local value symbols after scope resolution has
+ * already used them for binding and call resolution.
+ *
+ * @deps    scopeResolution
+ * @reads   graph (nodes and relationships)
+ * @writes  graph (removes unreferenced local Const/Variable/Static nodes)
+ */
+import { pruneLocalValueSymbols } from '../local-symbol-pruner.js';
+import { isDev } from '../utils/env.js';
+import { logger } from '../../logger.js';
+export const pruneLocalSymbolsPhase = {
+    name: 'pruneLocalSymbols',
+    deps: ['scopeResolution'],
+    async execute(ctx) {
+        const stats = pruneLocalValueSymbols(ctx.graph, {
+            keepLocalValueSymbols: ctx.options?.keepLocalValueSymbols,
+        });
+        if (isDev && !stats.skippedByEnv && stats.prunedNodes > 0) {
+            logger.info(`Pruned ${stats.prunedNodes}/${stats.candidateNodes} inert local value symbols`);
+        }
+        return stats;
+    },
+};

package/dist/core/ingestion/pipeline.d.ts

@@ -17,7 +17,12 @@
 import { type PipelineProgress } from '../../_shared/index.js';
 import { PipelineResult } from '../../types/pipeline.js';
 export interface PipelineOptions {
-    /** Skip MRO, community detection, and process extraction for faster test runs. */
+    /**
+     * Skip MRO, community detection, and process extraction for faster test runs.
+     * The `pruneLocalSymbols` phase still runs — it is graph construction (it cleans
+     * up inert local symbols), not graph analysis — so set `keepLocalValueSymbols`
+     * to retain those nodes under `skipGraphPhases`.
+     */
     skipGraphPhases?: boolean;
     /**
      * Request parsing with the worker pool disabled. The sequential parser was
@@ -90,5 +95,13 @@ export interface PipelineOptions {
      * without leaking `process.env` state across invocations.
      */
     chunkByteBudget?: number;
+    /**
+     * Keep inert block-local value symbols (Const/Variable/Static) that the
+     * `pruneLocalSymbols` phase would otherwise drop. Mirrors the
+     * `GITNEXUS_KEEP_LOCAL_VALUE_SYMBOLS` env var, but threaded per-call so
+     * long-running hosts (eval-server, MCP daemon) can opt out without leaking
+     * `process.env` state across invocations. When undefined, the env var decides.
+     */
+    keepLocalValueSymbols?: boolean;
 }
 export declare const runPipelineFromRepo: (repoPath: string, onProgress: (progress: PipelineProgress) => void, options?: PipelineOptions) => Promise<PipelineResult>;

package/dist/core/ingestion/pipeline.js

@@ -15,7 +15,7 @@
  * See ARCHITECTURE.md for the full phase dependency diagram.
  */
 import { createKnowledgeGraph } from '../graph/graph.js';
-import { runPipeline, getPhaseOutput, scanPhase, structurePhase, markdownPhase, cobolPhase, parsePhase, routesPhase, toolsPhase, ormPhase, crossFilePhase, scopeResolutionPhase, mroPhase, communitiesPhase, processesPhase, } from './pipeline-phases/index.js';
+import { runPipeline, getPhaseOutput, scanPhase, structurePhase, markdownPhase, cobolPhase, parsePhase, routesPhase, toolsPhase, ormPhase, crossFilePhase, scopeResolutionPhase, pruneLocalSymbolsPhase, mroPhase, communitiesPhase, processesPhase, } from './pipeline-phases/index.js';
 // ── Phase registry ─────────────────────────────────────────────────────────
 /**
  * All pipeline phases with their dependency relationships.
@@ -23,7 +23,8 @@ import { runPipeline, getPhaseOutput, scanPhase, structurePhase, markdownPhase,
  * Phase dependency graph:
  *
  *   scan → structure → [markdown, cobol] → parse → [routes, tools, orm]
- *     → crossFile → mro → communities → processes
+ *     → crossFile → scopeResolution → pruneLocalSymbols
+ *     → mro → communities → processes
  *
  * To add a new phase: create a file in pipeline-phases/, export the phase
  * object, and add it to the appropriate position in this array.
@@ -40,6 +41,7 @@ function buildPhaseList(options) {
         ormPhase,
         crossFilePhase,
         scopeResolutionPhase,
+        pruneLocalSymbolsPhase,
     ];
     if (!options?.skipGraphPhases) {
         phases.push(mroPhase, communitiesPhase, processesPhase);

package/dist/core/ingestion/variable-extractors/generic.js

@@ -1,4 +1,23 @@
 // gitnexus/src/core/ingestion/variable-extractors/generic.ts
+/**
+ * Type-declaration node types whose body can be a bare `block`. tree-sitter-python
+ * models a class body as a `block` node — the same node type used for function and
+ * control-flow bodies — so a class attribute would otherwise look block-scoped. Most
+ * other grammars give class bodies dedicated node types (`class_body`,
+ * `declaration_list`, `body_statement`), which are not in the block-scope list below,
+ * so this guard is a no-op for them but keeps the rule language-agnostic.
+ */
+const CLASS_LIKE_CONTAINERS = new Set([
+    'class_definition',
+    'class_declaration',
+    'class_specifier',
+    'struct_item',
+    'impl_item',
+    'trait_item',
+    'interface_declaration',
+    'enum_declaration',
+    'object_declaration',
+]);
 /**
  * Create a VariableExtractor from a declarative config.
  */
@@ -26,7 +45,7 @@ export function createVariableExtractor(config) {
                 t === 'compilation_unit') {
                 return 'module';
             }
-            // Function/method/block boundaries indicate block scope
+            // Function/method boundaries indicate block scope
             if (t === 'function_declaration' ||
                 t === 'function_definition' ||
                 t === 'function_item' ||
@@ -35,11 +54,17 @@ export function createVariableExtractor(config) {
                 t === 'arrow_function' ||
                 t === 'function_expression' ||
                 t === 'lambda' ||
-                t === 'block' ||
                 t === 'function_body' ||
                 t === 'compound_statement') {
                 return 'block';
             }
+            // A bare `block` is block scope UNLESS it is a class body. A class member
+            // (e.g. Python `class C: MAX = 100`) is not an inert function-local — keep
+            // walking so it resolves to its true enclosing scope ('module' for a
+            // top-level class) instead of being misclassified and pruned.
+            if (t === 'block' && !(current.parent && CLASS_LIKE_CONTAINERS.has(current.parent.type))) {
+                return 'block';
+            }
             current = current.parent;
         }
         return 'file';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.6-rc.154",
+  "version": "1.6.6-rc.155",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",