gitnexus 1.6.6-rc.65 → 1.6.6-rc.67

package/dist/cli/eval-server.js

@@ -170,20 +170,41 @@ export function formatImpactResult(result) {
         2: 'LIKELY AFFECTED (indirect)',
         3: 'MAY NEED TESTING (transitive)',
     };
-    for (const depth of [1, 2, 3]) {
-        const items = byDepth[depth];
-        if (!items || items.length === 0)
-            continue;
-        lines.push(`d=${depth}: ${depthLabels[depth] || ''} (${items.length})`);
-        for (const item of items.slice(0, 12)) {
-            const conf = item.confidence < 1 ? ` (conf: ${item.confidence})` : '';
-            lines.push(`  ${item.type} ${item.name} → ${item.filePath} [${item.relationType}]${conf}`);
-        }
-        if (items.length > 12) {
-            lines.push(`  ... and ${items.length - 12} more`);
+    if (!result.byDepth && result.byDepthCounts) {
+        lines.push('(summary only — use summaryOnly: false to see symbol lists)');
+        const depthCounts = result.byDepthCounts;
+        for (const depth of [1, 2, 3]) {
+            const count = depthCounts[depth] ?? 0;
+            if (count === 0)
+                continue;
+            lines.push(`d=${depth}: ${depthLabels[depth] || ''} (${count})`);
         }
         lines.push('');
     }
+    else {
+        const depthCounts = result.byDepthCounts || {};
+        for (const depth of [1, 2, 3]) {
+            const items = byDepth[depth] || [];
+            const trueCount = depthCounts[depth] ?? items.length;
+            if (trueCount === 0)
+                continue;
+            lines.push(`d=${depth}: ${depthLabels[depth] || ''} (${trueCount})`);
+            if (items.length === 0) {
+                lines.push(`  (0 items on this page — adjust offset)`);
+            }
+            else {
+                const shown = Math.min(items.length, 12);
+                for (const item of items.slice(0, shown)) {
+                    const conf = item.confidence < 1 ? ` (conf: ${item.confidence})` : '';
+                    lines.push(`  ${item.type} ${item.name} → ${item.filePath} [${item.relationType}]${conf}`);
+                }
+                if (trueCount > shown) {
+                    lines.push(`  ... and ${trueCount - shown} more`);
+                }
+            }
+            lines.push('');
+        }
+    }
     return lines.join('\n').trim();
 }
 export function formatCypherResult(result) {

package/dist/cli/help-i18n.js

@@ -99,6 +99,9 @@ const OPTION_DESCRIPTION_KEYS = {
     'impact|-r, --repo <name>': 'help.option.repo.target',
     'impact|--depth <n>': 'help.option.impact.depth',
     'impact|--include-tests': 'help.option.impact.includeTests',
+    'impact|--limit <n>': 'help.option.impact.limit',
+    'impact|--offset <n>': 'help.option.impact.offset',
+    'impact|--summary-only': 'help.option.impact.summaryOnly',
     'cypher|-r, --repo <name>': 'help.option.repo.target',
     'detect-changes|-s, --scope <scope>': 'help.option.detectChanges.scope',
     'detect-changes|-b, --base-ref <ref>': 'help.option.detectChanges.baseRef',

package/dist/cli/i18n/en.d.ts

@@ -180,6 +180,9 @@ export declare const en: {
     readonly 'help.option.impact.direction': "upstream (dependants) or downstream (dependencies)";
     readonly 'help.option.impact.depth': "Max relationship depth (default: 3)";
     readonly 'help.option.impact.includeTests': "Include test files in results";
+    readonly 'help.option.impact.limit': "Max symbols per depth level (default: 100)";
+    readonly 'help.option.impact.offset': "Skip N symbols per depth level for pagination";
+    readonly 'help.option.impact.summaryOnly': "Return counts and risk only, omit symbol list";
     readonly 'help.option.detectChanges.scope': "What to analyze: unstaged, staged, all, or compare";
     readonly 'help.option.detectChanges.baseRef': "Branch/commit for compare scope (e.g. main)";
     readonly 'help.option.evalServer.host': "Bind address (default: 127.0.0.1, use 0.0.0.0 to expose to all interfaces)";

package/dist/cli/i18n/en.js

@@ -180,6 +180,9 @@ export const en = {
     'help.option.impact.direction': 'upstream (dependants) or downstream (dependencies)',
     'help.option.impact.depth': 'Max relationship depth (default: 3)',
     'help.option.impact.includeTests': 'Include test files in results',
+    'help.option.impact.limit': 'Max symbols per depth level (default: 100)',
+    'help.option.impact.offset': 'Skip N symbols per depth level for pagination',
+    'help.option.impact.summaryOnly': 'Return counts and risk only, omit symbol list',
     'help.option.detectChanges.scope': 'What to analyze: unstaged, staged, all, or compare',
     'help.option.detectChanges.baseRef': 'Branch/commit for compare scope (e.g. main)',
     'help.option.evalServer.host': 'Bind address (default: 127.0.0.1, use 0.0.0.0 to expose to all interfaces)',

package/dist/cli/i18n/resources.d.ts

@@ -181,6 +181,9 @@ export declare const cliResources: {
         readonly 'help.option.impact.direction': "upstream (dependants) or downstream (dependencies)";
         readonly 'help.option.impact.depth': "Max relationship depth (default: 3)";
         readonly 'help.option.impact.includeTests': "Include test files in results";
+        readonly 'help.option.impact.limit': "Max symbols per depth level (default: 100)";
+        readonly 'help.option.impact.offset': "Skip N symbols per depth level for pagination";
+        readonly 'help.option.impact.summaryOnly': "Return counts and risk only, omit symbol list";
         readonly 'help.option.detectChanges.scope': "What to analyze: unstaged, staged, all, or compare";
         readonly 'help.option.detectChanges.baseRef': "Branch/commit for compare scope (e.g. main)";
         readonly 'help.option.evalServer.host': "Bind address (default: 127.0.0.1, use 0.0.0.0 to expose to all interfaces)";
@@ -387,6 +390,9 @@ export declare const cliResources: {
         'help.option.impact.direction': string;
         'help.option.impact.depth': string;
         'help.option.impact.includeTests': string;
+        'help.option.impact.limit': string;
+        'help.option.impact.offset': string;
+        'help.option.impact.summaryOnly': string;
         'help.option.detectChanges.scope': string;
         'help.option.detectChanges.baseRef': string;
         'help.option.evalServer.host': string;

package/dist/cli/i18n/zh-CN.d.ts

@@ -180,6 +180,9 @@ export declare const zhCN: {
     'help.option.impact.direction': string;
     'help.option.impact.depth': string;
     'help.option.impact.includeTests': string;
+    'help.option.impact.limit': string;
+    'help.option.impact.offset': string;
+    'help.option.impact.summaryOnly': string;
     'help.option.detectChanges.scope': string;
     'help.option.detectChanges.baseRef': string;
     'help.option.evalServer.host': string;

package/dist/cli/i18n/zh-CN.js

@@ -180,6 +180,9 @@ export const zhCN = {
     'help.option.impact.direction': 'upstream（依赖它的项）或 downstream（它依赖的项）',
     'help.option.impact.depth': '最大关系遍历深度（默认：3）',
     'help.option.impact.includeTests': '在结果中包含测试文件',
+    'help.option.impact.limit': '每层深度最大符号数（默认：100）',
+    'help.option.impact.offset': '每层深度跳过 N 个符号（分页用）',
+    'help.option.impact.summaryOnly': '仅返回计数和风险等级，省略符号列表',
     'help.option.detectChanges.scope': '分析范围：unstaged、staged、all 或 compare',
     'help.option.detectChanges.baseRef': 'compare 范围的分支/提交（例如 main）',
     'help.option.evalServer.host': '绑定地址（默认：127.0.0.1；用 0.0.0.0 暴露到所有网卡）',

package/dist/cli/index.js

@@ -148,6 +148,9 @@ program
     .option('-r, --repo <name>', 'Target repository')
     .option('--depth <n>', 'Max relationship depth (default: 3)')
     .option('--include-tests', 'Include test files in results')
+    .option('--limit <n>', 'Max symbols per depth level (default: 100)')
+    .option('--offset <n>', 'Skip N symbols per depth level for pagination')
+    .option('--summary-only', 'Return counts and risk only, omit symbol list')
     .action(createLazyAction(() => import('./tool.js'), 'impactCommand'));
 program
     .command('cypher <query>')

package/dist/cli/tool.d.ts

@@ -32,6 +32,9 @@ export declare function impactCommand(target: string, options?: {
     repo?: string;
     depth?: string;
     includeTests?: boolean;
+    limit?: string;
+    offset?: string;
+    summaryOnly?: boolean;
 }): Promise<void>;
 export declare function cypherCommand(query: string, options?: {
     repo?: string;

package/dist/cli/tool.js

@@ -93,12 +93,19 @@ export async function impactCommand(target, options) {
     }
     try {
         const backend = await getBackend();
+        const rawLimit = parseInt(options?.limit ?? '', 10);
+        const rawOffset = parseInt(options?.offset ?? '', 10);
+        const parsedLimit = Number.isFinite(rawLimit) ? rawLimit : undefined;
+        const parsedOffset = Number.isFinite(rawOffset) ? rawOffset : undefined;
         const result = await backend.callTool('impact', {
             target,
             direction: options?.direction || 'upstream',
             maxDepth: options?.depth ? parseInt(options.depth, 10) : undefined,
             includeTests: options?.includeTests ?? false,
             repo: options?.repo,
+            limit: parsedLimit,
+            offset: parsedOffset,
+            summaryOnly: options?.summaryOnly ?? undefined,
         });
         output(result);
     }

package/dist/core/group/cross-impact.js

@@ -9,6 +9,9 @@ import { fileMatchesServicePrefix, normalizeServicePrefix, repoInSubgroup, } fro
 import { getGroupDir } from './storage.js';
 import { closeBridgeDb, openBridgeDbReadOnly, queryBridge, readBridgeMeta } from './bridge-db.js';
 import { BRIDGE_SCHEMA_VERSION } from './bridge-schema.js';
+// High limit for the local phase of group impact so collectImpactSymbolUids
+// sees (nearly) all symbols. Bypasses the MCP-facing default of 100.
+const GROUP_LOCAL_PHASE_LIMIT = 10000;
 /** Cross-boundary hops beyond this value are clamped (multi-hop reserved for future work). */
 export const MAX_SUPPORTED_CROSS_DEPTH = 1;
 /** Default wall-clock budget for the Phase 1 `impact` leg when callers omit `timeoutMs`. */
@@ -324,6 +327,7 @@ export async function runGroupImpact(deps, params) {
         relationTypes: relationTypes && relationTypes.length > 0 ? relationTypes : undefined,
         includeTests,
         minConfidence,
+        limit: GROUP_LOCAL_PHASE_LIMIT,
     };
     const deadline = Date.now() + Math.max(0, timeoutMs);
     const { value: local, timedOut: localTimedOut } = await safeLocalImpact(deps.port, resolved, impactParams, timeoutMs);

package/dist/core/group/service.d.ts

@@ -20,6 +20,7 @@ export interface GroupToolPort {
         relationTypes?: string[];
         includeTests?: boolean;
         minConfidence?: number;
+        limit?: number;
     }): Promise<unknown>;
     query(repo: GroupRepoHandle, params: {
         query: string;

package/dist/core/ingestion/languages/cpp/captures.js

@@ -373,8 +373,9 @@ function detectCppDependentBases(root, filePath) {
                         for (const base of iterBaseClasses(baseClause)) {
                             if (isBaseDependent(base, params)) {
                                 const baseName = extractBaseLookupName(base);
+                                const baseQualifier = extractBaseLookupQualifier(base);
                                 if (baseName !== '') {
-                                    markCppDependentBase(filePath, className, baseName);
+                                    markCppDependentBase(filePath, className, baseName, baseQualifier);
                                 }
                             }
                         }
@@ -451,10 +452,15 @@ function* iterBaseClasses(baseClause) {
  */
 function isBaseDependent(baseNode, templateParams) {
     if (baseNode.type !== 'template_type') {
-        // Bare `type_identifier` or `qualified_identifier` bases — not
-        // dependent (the base name itself doesn't reference a template
-        // parameter at this level).
-        return false;
+        if (baseNode.type === 'qualified_identifier') {
+            // Qualified identifier bases (e.g. `detail::Inner<T>`) may contain
+            // template_type children — descend into them for template param check.
+            // Fall through to the stack walk below.
+        }
+        else {
+            // Bare `type_identifier` bases — not dependent.
+            return false;
+        }
     }
     // Walk all descendants of the template_argument_list looking for any
     // type_identifier matching a template parameter, or any conservative-
@@ -525,6 +531,28 @@ function extractBaseLookupName(baseNode) {
     }
     return '';
 }
+/** Extract the syntactic namespace qualifier from a base class node.
+ *  For `detail::Inner<T>`, returns `'detail'`.
+ *  For unqualified bases (`Inner<T>`, `Base<int>`), returns `''`.
+ *  Nested qualifiers (`a::b::Inner<T>`) return the full scope text.
+ */
+function extractBaseLookupQualifier(baseNode) {
+    if (baseNode.type === 'qualified_identifier') {
+        const scopeNode = baseNode.childForFieldName('scope');
+        if (scopeNode !== null)
+            return scopeNode.text;
+    }
+    // template_type nodes may have a qualified_identifier as their name child
+    if (baseNode.type === 'template_type') {
+        const nameNode = baseNode.childForFieldName('name');
+        if (nameNode !== null && nameNode.type === 'qualified_identifier') {
+            const scopeNode = nameNode.childForFieldName('scope');
+            if (scopeNode !== null)
+                return scopeNode.text;
+        }
+    }
+    return '';
+}
 /**
  * Walk parent chain from a function_definition / declaration / field_declaration
  * to find the enclosing `template_declaration`. Returns null when the function

package/dist/core/ingestion/languages/cpp/two-phase-lookup.d.ts

@@ -36,12 +36,14 @@ import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexe
  * Record a dependent-base relationship discovered during scope-capture
  * emission. `className` is the simple name of the template class;
  * `baseName` is the simple name of the dependent base class.
+ * `qualifier` is the syntactic namespace qualifier (e.g. `detail` for
+ * `detail::Inner<T>`), or '' for unqualified bases.
  *
  * The capture-time recorder uses simple names because the registry
  * resolution that maps names → nodeIds runs later (in
  * `populateCppDependentBases`).
  */
-export declare function markCppDependentBase(filePath: string, className: string, baseName: string): void;
+export declare function markCppDependentBase(filePath: string, className: string, baseName: string, qualifier?: string): void;
 /** Clear two-phase-lookup state. Called from `clearFileLocalNames`. */
 export declare function clearCppDependentBases(): void;
 /**
@@ -53,8 +55,10 @@ export declare function clearCppDependentBases(): void;
  * Disambiguation strategy (multiple classes sharing a simple name):
  *  1. Prefer the candidate whose qualified-name namespace prefix matches
  *     the deriving class's namespace prefix (same-namespace bias).
- *  2. Fall back to accepting a unique simple-name match.
- *  3. Skip when multiple candidates exist and no namespace match is
+ *  2. When a syntactic qualifier is available (`detail` in
+ *     `detail::Inner<T>`), target the exact namespace derived from it.
+ *  3. Fall back to accepting a unique simple-name match.
+ *  4. Skip when multiple candidates exist and no namespace match is
  *     found (conservative: avoids false associations).
  */
 export declare function populateCppDependentBases(parsedFiles: readonly ParsedFile[]): void;

package/dist/core/ingestion/languages/cpp/two-phase-lookup.js

@@ -33,10 +33,12 @@
 import { findEnclosingClassDef } from '../../scope-resolution/scope/walkers.js';
 /**
  * Capture-time record: for each template class declaration in a file,
- * the simple names of its dependent base classes.
+ * the simple names of its dependent base classes and their syntactic
+ * qualifiers (e.g., `detail` for `detail::Inner<T>`).
  *
  * Key: filePath
- * Value: Map<className, Set<dependentBaseSimpleName>>
+ * Value: Map<className, Map<baseName, qualifier>>
+ *   qualifier is '' when the base was unqualified.
  */
 const dependentBasesByFile = new Map();
 /**
@@ -49,12 +51,14 @@ const dependentBaseNodeIds = new Map();
  * Record a dependent-base relationship discovered during scope-capture
  * emission. `className` is the simple name of the template class;
  * `baseName` is the simple name of the dependent base class.
+ * `qualifier` is the syntactic namespace qualifier (e.g. `detail` for
+ * `detail::Inner<T>`), or '' for unqualified bases.
  *
  * The capture-time recorder uses simple names because the registry
  * resolution that maps names → nodeIds runs later (in
  * `populateCppDependentBases`).
  */
-export function markCppDependentBase(filePath, className, baseName) {
+export function markCppDependentBase(filePath, className, baseName, qualifier = '') {
     let perFile = dependentBasesByFile.get(filePath);
     if (perFile === undefined) {
         perFile = new Map();
@@ -62,10 +66,15 @@ export function markCppDependentBase(filePath, className, baseName) {
     }
     let bases = perFile.get(className);
     if (bases === undefined) {
-        bases = new Set();
+        bases = new Map();
         perFile.set(className, bases);
     }
-    bases.add(baseName);
+    let quals = bases.get(baseName);
+    if (quals === undefined) {
+        quals = new Set();
+        bases.set(baseName, quals);
+    }
+    quals.add(qualifier);
 }
 /** Clear two-phase-lookup state. Called from `clearFileLocalNames`. */
 export function clearCppDependentBases() {
@@ -81,8 +90,10 @@ export function clearCppDependentBases() {
  * Disambiguation strategy (multiple classes sharing a simple name):
  *  1. Prefer the candidate whose qualified-name namespace prefix matches
  *     the deriving class's namespace prefix (same-namespace bias).
- *  2. Fall back to accepting a unique simple-name match.
- *  3. Skip when multiple candidates exist and no namespace match is
+ *  2. When a syntactic qualifier is available (`detail` in
+ *     `detail::Inner<T>`), target the exact namespace derived from it.
+ *  3. Fall back to accepting a unique simple-name match.
+ *  4. Skip when multiple candidates exist and no namespace match is
  *     found (conservative: avoids false associations).
  */
 export function populateCppDependentBases(parsedFiles) {
@@ -91,7 +102,13 @@ export function populateCppDependentBases(parsedFiles) {
     // Build workspace-wide index: simpleName → {nodeId, nsPrefix}[]
     // nsPrefix is the dot-joined namespace path (qualifiedName without the
     // last segment). Classes at global scope have nsPrefix = ''.
+    // Dedup by nodeId, keeping the LAST occurrence: parsed.localDefs may
+    // list the same class def multiple times — the scope-extractor creates
+    // a def with simple-name qualifiedName first, then the class extractor
+    // replaces it with the correct fully-qualified qualifiedName. Keeping
+    // the later entry ensures we capture the full namespace path.
     const classesBySimpleName = new Map();
+    const entryByNodeId = new Map();
     for (const parsed of parsedFiles) {
         for (const def of parsed.localDefs) {
             if (def.type !== 'Class' && def.type !== 'Struct' && def.type !== 'Interface')
@@ -102,13 +119,16 @@ export function populateCppDependentBases(parsedFiles) {
             if (simple === '')
                 continue;
             const nsPrefix = lastDot >= 0 ? qn.slice(0, lastDot) : '';
-            let entries = classesBySimpleName.get(simple);
-            if (entries === undefined) {
-                entries = [];
-                classesBySimpleName.set(simple, entries);
-            }
-            entries.push({ nodeId: def.nodeId, nsPrefix });
+            entryByNodeId.set(def.nodeId, { nodeId: def.nodeId, nsPrefix, simple });
+        }
+    }
+    for (const entry of entryByNodeId.values()) {
+        let entries = classesBySimpleName.get(entry.simple);
+        if (entries === undefined) {
+            entries = [];
+            classesBySimpleName.set(entry.simple, entries);
         }
+        entries.push({ nodeId: entry.nodeId, nsPrefix: entry.nsPrefix });
     }
     // Build a filePath → ParsedFile lookup for fast per-file access.
     const parsedByFile = new Map();
@@ -133,7 +153,12 @@ export function populateCppDependentBases(parsedFiles) {
             const nsPrefix = lastDot >= 0 ? qn.slice(0, lastDot) : '';
             localClassByName.set(simple, { nodeId: def.nodeId, nsPrefix });
         }
-        for (const [className, baseNames] of perFile) {
+        // V3: qualifier-based exact targeting. When the base specifier carries
+        // a syntactic qualifier (e.g., `detail` in `detail::Inner<T>`), compute
+        // the expected namespace prefix and use exact (===) match. Falls back to
+        // the V2 prefix-contains heuristic when the qualifier isn't available or
+        // the exact match fails (absolute qualifier edge cases like `::std`).
+        for (const [className, baseEntries] of perFile) {
             const classEntry = localClassByName.get(className);
             if (classEntry === undefined)
                 continue;
@@ -142,49 +167,66 @@ export function populateCppDependentBases(parsedFiles) {
                 bases = new Set();
                 dependentBaseNodeIds.set(classEntry.nodeId, bases);
             }
-            for (const baseName of baseNames) {
-                const candidates = classesBySimpleName.get(baseName);
-                if (candidates === undefined || candidates.length === 0)
-                    continue;
-                if (candidates.length === 1) {
-                    // Unique simple-name match — accept regardless of namespace.
-                    bases.add(candidates[0].nodeId);
-                    continue;
-                }
-                // Multiple classes share the same simple name — prefer the one
-                // whose namespace matches the deriving class's namespace.
-                // V2: filter by prefix-match capped at one level deeper, then
-                // accept only if exactly one candidate survives. This lets
-                // Derived<T> in ns::outer find Inner<T> in ns::outer::inner
-                // (or ns::v1 for inline-namespace variants) while rejecting
-                // sibling collisions (e.g. detail::Inner vs public_api::Inner).
-                //
-                // The one-segment cap limits walk depth: ns → ns.a ✓, ns → ns.a.b ✗.
-                // Global-scope deriving classes match any single-segment namespace.
-                //
-                // LIMITATION: True ISO behavior would use the base specifier's
-                // syntactic qualifier (available at captures.ts:611 as
-                // qualified_identifier scope) to navigate from the current scope,
-                // which would resolve `detail::Inner` vs `public_api::Inner`
-                // unambiguously. Threading the qualifier is tracked in #1815.
-                // Until then, sibling collisions correctly suppress.
-                const nsMatches = candidates.filter((c) => {
-                    if (c.nsPrefix === classEntry.nsPrefix)
-                        return true;
-                    if (classEntry.nsPrefix === '') {
-                        return c.nsPrefix !== '' && !c.nsPrefix.includes('.');
+            for (const [baseName, qualsSet] of baseEntries) {
+                for (const baseQualifier of qualsSet) {
+                    const candidates = classesBySimpleName.get(baseName);
+                    if (candidates === undefined || candidates.length === 0)
+                        continue;
+                    // Compute the expected namespace prefix from the qualifier.
+                    // Relative qualifier (e.g. `inner`): prepend deriving class's prefix.
+                    // Absolute qualifiers (`::std`, `ns::other`) will fail the relative
+                    // lookup and fall through to the prefix-heuristic below.
+                    const normalizedQualifier = baseQualifier.replace(/::/g, '.');
+                    const expectedNs = baseQualifier && classEntry.nsPrefix
+                        ? classEntry.nsPrefix + '.' + normalizedQualifier
+                        : normalizedQualifier;
+                    if (candidates.length === 1) {
+                        // Unqualified base: accept unique match (pre-existing behavior).
+                        if (!baseQualifier) {
+                            bases.add(candidates[0].nodeId);
+                            continue;
+                        }
+                        // Qualified base: verify namespace before accepting.
+                        if (candidates[0].nsPrefix === expectedNs ||
+                            candidates[0].nsPrefix === normalizedQualifier) {
+                            bases.add(candidates[0].nodeId);
+                        }
+                        // else: suppress — qualifier doesn't match. #1564 policy.
+                        continue;
+                    }
+                    // V3: qualifier-based exact targeting. When the base specifier
+                    // carries a syntactic qualifier, compute the expected namespace
+                    // prefix and attempt an exact (===) match using the deduplicated
+                    // nsPrefix. Dedup by nodeId removes broken entries from the
+                    // classesBySimpleName index, making the surviving nsPrefix reliable.
+                    if (baseQualifier) {
+                        const qualifierMatch = candidates.find((c) => c.nsPrefix === expectedNs || c.nsPrefix === normalizedQualifier);
+                        if (qualifierMatch !== undefined) {
+                            bases.add(qualifierMatch.nodeId);
+                            continue;
+                        }
+                        continue; // qualifier was explicit but no match — suppress, don't fall through to V2
                     }
-                    if (c.nsPrefix.startsWith(classEntry.nsPrefix + '.')) {
-                        const suffix = c.nsPrefix.slice(classEntry.nsPrefix.length + 1);
-                        return !suffix.includes('.');
+                    // V2 fallback: filter by prefix-match capped at one level deeper,
+                    // then accept only if exactly one candidate survives.
+                    const nsMatches = candidates.filter((c) => {
+                        if (c.nsPrefix === classEntry.nsPrefix)
+                            return true;
+                        if (classEntry.nsPrefix === '') {
+                            return c.nsPrefix !== '' && !c.nsPrefix.includes('.');
+                        }
+                        if (c.nsPrefix.startsWith(classEntry.nsPrefix + '.')) {
+                            const suffix = c.nsPrefix.slice(classEntry.nsPrefix.length + 1);
+                            return !suffix.includes('.');
+                        }
+                        return false;
+                    });
+                    const nsMatch = nsMatches.length === 1 ? nsMatches[0] : undefined;
+                    if (nsMatch !== undefined) {
+                        bases.add(nsMatch.nodeId);
                     }
-                    return false;
-                });
-                const nsMatch = nsMatches.length === 1 ? nsMatches[0] : undefined;
-                if (nsMatch !== undefined) {
-                    bases.add(nsMatch.nodeId);
+                    // else: ambiguous (multiple candidates, no namespace match) → skip.
                 }
-                // else: ambiguous (multiple candidates, no namespace match) → skip.
             }
         }
     }

package/dist/mcp/local/local-backend.js

@@ -2361,6 +2361,9 @@ export class LocalBackend {
             relationTypes: effectiveRelationTypes,
             includeTests,
             minConfidence,
+            limit: Number.isFinite(params.limit) ? params.limit : 100,
+            offset: Number.isFinite(params.offset) ? params.offset : 0,
+            summaryOnly: params.summaryOnly,
         });
     }
     /**
@@ -2368,6 +2371,13 @@ export class LocalBackend {
      */
     async _runImpactBFS(repo, sym, symType, direction, opts) {
         const { maxDepth, relationTypes, includeTests, minConfidence } = opts;
+        const hasExplicitLimit = typeof opts.limit === 'number' && Number.isFinite(opts.limit);
+        const paginationLimit = hasExplicitLimit
+            ? Math.max(1, Math.min(Math.trunc(opts.limit), 10000))
+            : Infinity;
+        const rawOffset = typeof opts.offset === 'number' && Number.isFinite(opts.offset) ? opts.offset : 0;
+        const paginationOffset = Math.max(0, Math.trunc(rawOffset));
+        const summaryOnly = opts.summaryOnly ?? false;
         const relTypeFilter = relationTypes.map((t) => `'${t}'`).join(', ');
         const confidenceFilter = minConfidence > 0 ? ` AND r.confidence >= ${minConfidence}` : '';
         const symId = sym.id || sym[0];
@@ -2708,7 +2718,12 @@ export class LocalBackend {
         else if (directCount >= 5 || impacted.length >= 30) {
             risk = 'MEDIUM';
         }
-        return {
+        // Build per-depth counts (always included, even in summaryOnly mode)
+        const byDepthCounts = {};
+        for (const [depth, items] of Object.entries(grouped)) {
+            byDepthCounts[Number(depth)] = items.length;
+        }
+        const base = {
             target: {
                 id: symId,
                 name: sym.name || sym[1],
@@ -2724,9 +2739,34 @@ export class LocalBackend {
                 processes_affected: processCount,
                 modules_affected: moduleCount,
             },
+            byDepthCounts,
             affected_processes: affectedProcesses,
             affected_modules: affectedModules,
-            byDepth: grouped,
+        };
+        if (summaryOnly) {
+            return base;
+        }
+        // Apply limit/offset pagination per depth level
+        const paginatedGrouped = {};
+        let anyTruncated = false;
+        for (const [depth, items] of Object.entries(grouped)) {
+            const total = items.length;
+            const sliced = items.slice(paginationOffset, paginationOffset + paginationLimit);
+            paginatedGrouped[Number(depth)] = sliced;
+            if (paginationOffset > 0 || paginationOffset + paginationLimit < total) {
+                anyTruncated = true;
+            }
+        }
+        return {
+            ...base,
+            ...(anyTruncated && {
+                pagination: {
+                    ...(Number.isFinite(paginationLimit) && { limit: paginationLimit }),
+                    offset: paginationOffset,
+                    truncated: true,
+                },
+            }),
+            byDepth: paginatedGrouped,
         };
     }
     /**
@@ -2855,6 +2895,9 @@ export class LocalBackend {
                 impactArgs.timeoutMs = params.timeoutMs;
             if (params.timeout !== undefined)
                 impactArgs.timeout = params.timeout;
+            // limit/offset/summaryOnly are not forwarded to group-mode impact:
+            // runGroupImpact uses GROUP_LOCAL_PHASE_LIMIT internally for UID
+            // collection and does not re-paginate the local result yet.
             return svc.groupImpact(impactArgs);
         }
         if (method === 'query') {

package/dist/mcp/tools.js

@@ -299,13 +299,15 @@ Output includes:
 - summary: direct callers, processes affected, modules affected
 - affected_processes: which execution flows break and at which step
 - affected_modules: which functional areas are hit (direct vs indirect)
-- byDepth: all affected symbols grouped by traversal depth
+- byDepth: affected symbols grouped by traversal depth (paginated by limit/offset; omitted when summaryOnly:true — use byDepthCounts for totals per depth, pagination object when truncated)
 
 Depth groups:
 - d=1: WILL BREAK (direct callers/importers)
 - d=2: LIKELY AFFECTED (indirect)
 - d=3: MAY NEED TESTING (transitive)
 
+TIP: For hub symbols (base error classes, shared utilities) with many direct callers, use summaryOnly: true first to see counts and risk, then drill into specific depths with limit/offset. maxDepth alone does not bound output size when most dependents are at depth 1. limit and offset apply independently to each depth level, not to the total result set — use byDepthCounts to see totals per depth.
+
 TIP: Default traversal uses CALLS/IMPORTS/EXTENDS/IMPLEMENTS. For class members, include HAS_METHOD and HAS_PROPERTY in relationTypes. For field access analysis, include ACCESSES in relationTypes.
 
 Handles disambiguation: when multiple symbols share the target name, returns ranked candidates (each with a relevance score) instead of silently picking one. Use target_uid for zero-ambiguity lookup, or narrow with file_path and/or kind hints.
@@ -377,6 +379,24 @@ SERVICE: optional monorepo path prefix (case-sensitive path segments). When "rep
                     type: 'string',
                     description: 'Optional group subgroup prefix (member repo paths) limiting which repos participate in cross fan-out.',
                 },
+                limit: {
+                    type: 'integer',
+                    description: 'Max symbols returned in byDepth per depth level (default: 100). Single-repo only; ignored in group mode (@groupName). Use small values for hub symbols to avoid output truncation.',
+                    default: 100,
+                    minimum: 1,
+                    maximum: 10000,
+                },
+                offset: {
+                    type: 'integer',
+                    description: 'Skip this many symbols per depth level before applying limit. Single-repo only; ignored in group mode (@groupName). Use with limit for pagination.',
+                    default: 0,
+                    minimum: 0,
+                },
+                summaryOnly: {
+                    type: 'boolean',
+                    description: 'When true, returns target, summary, risk, byDepthCounts, affected_processes, and affected_modules — omits byDepth. Single-repo only; ignored in group mode (@groupName). Use for hub symbols to get actionable signal without output explosion.',
+                    default: false,
+                },
                 timeoutMs: {
                     type: 'number',
                     description: 'Wall-clock budget in milliseconds for the Phase-1 local impact leg (default 30000)',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.6-rc.65",
+  "version": "1.6.6-rc.67",
   "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",