gitnexus 1.6.6-rc.153 → 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/cli/ai-context.js

@@ -131,18 +131,18 @@ This project is indexed by GitNexus as **${projectName}**${noStats ? '' : ` (${s
 
 ## Always Do
 
-- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run \`gitnexus_impact({target: "symbolName", direction: "upstream"})\` and report the blast radius (direct callers, affected processes, risk level) to the user.
-- **MUST run \`gitnexus_detect_changes()\` before committing** to verify your changes only affect expected symbols and execution flows. For regression review, compare against the default branch: \`gitnexus_detect_changes({scope: "compare", base_ref: ${JSON.stringify(markdownSafeBranch(defaultBranch))}})\`.
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run \`impact({target: "symbolName", direction: "upstream"})\` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST run \`detect_changes()\` before committing** to verify your changes only affect expected symbols and execution flows. For regression review, compare against the default branch: \`detect_changes({scope: "compare", base_ref: ${JSON.stringify(markdownSafeBranch(defaultBranch))}})\`.
 - **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
-- When exploring unfamiliar code, use \`gitnexus_query({query: "concept"})\` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
-- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use \`gitnexus_context({name: "symbolName"})\`.
+- When exploring unfamiliar code, use \`query({query: "concept"})\` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use \`context({name: "symbolName"})\`.
 
 ## Never Do
 
-- NEVER edit a function, class, or method without first running \`gitnexus_impact\` on it.
+- NEVER edit a function, class, or method without first running \`impact\` on it.
 - NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
-- NEVER rename symbols with find-and-replace — use \`gitnexus_rename\` which understands the call graph.
-- NEVER commit changes without running \`gitnexus_detect_changes()\` to check affected scope.
+- NEVER rename symbols with find-and-replace — use \`rename\` which understands the call graph.
+- NEVER commit changes without running \`detect_changes()\` to check affected scope.
 
 ## Resources
 

package/dist/cli/skill-gen.js

@@ -482,8 +482,8 @@ const renderSkillMarkdown = (community, projectName, members, files, entryPoints
             : community.label;
     lines.push('## How to Explore');
     lines.push('');
-    lines.push(`1. \`gitnexus_context({name: "${firstEntry}"})\` \u2014 see callers and callees`);
-    lines.push(`2. \`gitnexus_query({query: "${community.label.toLowerCase()}"})\` \u2014 find related execution flows`);
+    lines.push(`1. \`context({name: "${firstEntry}"})\` \u2014 see callers and callees`);
+    lines.push(`2. \`query({query: "${community.label.toLowerCase()}"})\` \u2014 find related execution flows`);
     lines.push('3. Read key files listed above for implementation details');
     lines.push('');
     return lines.join('\n');

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/dist/mcp/local/local-backend.d.ts

@@ -74,9 +74,16 @@ interface RepoHandle {
  */
 export declare function resolveWorktreeCwd(repoPath: string, launchCwd: string): string;
 /**
- * Length of the base64url path hash appended to a colliding repo id.
+ * Length of the path-derived suffix appended to a colliding repo id.
  * Exported so tests can pin the suffix shape without re-deriving the
- * literal; see `repoId()` and the hashed-id resolution tier (#1658).
+ * literal; see `assignRepoId()` and the hashed-id resolution tier (#1658).
+ *
+ * Note: base64url is an *encoding*, not a hash — it preserves byte order, so
+ * two paths that share a long common prefix (sibling clones under one parent)
+ * collapse to the same sliced suffix. `assignRepoId()` keeps the legacy
+ * base64url suffix only for the first colliding duplicate (id compatibility)
+ * and falls back to a content hash of the resolved path on a real collision
+ * (#2054).
  */
 export declare const REPO_ID_HASH_LENGTH = 6;
 export declare class LocalBackend {
@@ -118,10 +125,25 @@ export declare class LocalBackend {
      */
     private refreshRepos;
     /**
-     * Generate a stable repo ID from name + path.
-     * If names collide, append a hash of the path.
+     * Assign a collision-free in-memory id for a registered repo.
+     *
+     * - Unique name → the bare lowercased name.
+     * - Duplicate name → a path-derived suffix. The *first* colliding clone keeps
+     *   the legacy `base64url(path)` suffix so ids generated before #2054 still
+     *   resolve (the #1658 hashed-id tier). base64url is an encoding, not a hash:
+     *   it preserves byte order, so sibling clones under one parent (e.g.
+     *   `.../REPO_2` and `.../REPO_3`) yield identical leading characters and thus
+     *   the same sliced suffix. Any further collision therefore falls back to a
+     *   content hash of the *resolved* path (order-insensitive), extended
+     *   deterministically until unique.
+     *
+     * `assigned` maps every id handed out in this refresh to its resolved path,
+     * so a candidate is "free" when it is unused or already owned by this exact
+     * path. This method records its own assignment into `assigned` before
+     * returning, so the map-update is the function's invariant, not a caller
+     * obligation. A returned id never overwrites a different path's handle (#2054).
      */
-    private repoId;
+    private assignRepoId;
     /**
      * Resolve which repo to use.
      * - If repoParam is given, match by name or path
@@ -148,6 +170,16 @@ export declare class LocalBackend {
      */
     private pickRepoHandleForCwd;
     private handleToRegistryEntry;
+    /**
+     * Ensure the LadybugDB pool is open for the *resolved* repo.
+     *
+     * Takes the `RepoHandle` the caller resolved — NOT a bare id — and keys the
+     * pool (and the init/staleness/reinit maps) by the immutable `lbugPath`. Two
+     * things matter for multi-clone correctness: (1) the handle is the one the
+     * caller resolved, so a concurrent `refreshRepos` can't substitute a different
+     * clone; (2) the pool key is the database path, so distinct clones never share
+     * a pool entry even when their name-derived id transiently collides (#2067).
+     */
     private ensureInitialized;
     /**
      * Get context for a specific repo (or the single repo if only one).