gitnexus 1.6.6-rc.95 → 1.6.6-rc.97

package/README.md

@@ -170,6 +170,13 @@ gitnexus clean --all --force     # Delete all indexes
 gitnexus wiki [path]             # Generate LLM-powered docs from knowledge graph
 gitnexus wiki --model <model>    # Wiki with custom LLM model (default: gpt-4o-mini)
 
+# Direct graph queries — the same tools the MCP server exposes, no MCP daemon needed
+gitnexus query "<concept>"                                    # Process-grouped hybrid search
+gitnexus context <symbol> [--uid <uid> | --file <path>]       # 360° symbol view; flags disambiguate a shared name
+gitnexus impact <symbol> [--uid <uid> | --file <path> | --kind <kind>]  # Blast radius; flags disambiguate a shared name
+gitnexus detect-changes          # Map the working-tree diff to affected symbols and execution flows
+gitnexus cypher "<query>"        # Run a raw Cypher query against the knowledge graph
+
 # Repository groups (multi-repo / monorepo service tracking)
 gitnexus group create <name>                                   # Create a repository group
 gitnexus group add <group> <groupPath> <registryName>          # Add a repo to a group. <groupPath> is a hierarchy path (e.g. hr/hiring/backend); <registryName> is the repo's name from the registry (see `gitnexus list`)

package/dist/cli/help-i18n.js

@@ -97,6 +97,9 @@ const OPTION_DESCRIPTION_KEYS = {
     'context|--content': 'help.option.content',
     'impact|-d, --direction <dir>': 'help.option.impact.direction',
     'impact|-r, --repo <name>': 'help.option.repo.target',
+    'impact|-u, --uid <uid>': 'help.option.context.uid',
+    'impact|-f, --file <path>': 'help.option.context.file',
+    'impact|--kind <kind>': 'help.option.impact.kind',
     'impact|--depth <n>': 'help.option.impact.depth',
     'impact|--include-tests': 'help.option.impact.includeTests',
     'impact|--limit <n>': 'help.option.impact.limit',

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

@@ -41,8 +41,9 @@ export declare const en: {
     readonly 'tool.noIndexed': "GitNexus: No indexed repositories found. Run: gitnexus analyze";
     readonly 'tool.usage.query': "Usage: gitnexus query <search_query>";
     readonly 'tool.usage.context': "Usage: gitnexus context <symbol_name> [--uid <uid>] [--file <path>]";
-    readonly 'tool.usage.impact': "Usage: gitnexus impact <symbol_name> [--direction upstream|downstream]";
+    readonly 'tool.usage.impact': "Usage: gitnexus impact <symbol_name> [--uid <uid>] [--file <path>] [--kind <kind>] [--direction upstream|downstream]";
     readonly 'tool.usage.cypher': "Usage: gitnexus cypher <cypher_query>";
+    readonly 'tool.warn.unknownKind': "--kind '{{kind}}' is not a known symbol kind (e.g. Function, Class, Method); it will not narrow the result.";
     readonly 'tool.detectChanges.noChanges': "No changes detected.";
     readonly 'tool.detectChanges.changesSummary': "Changes: {{files}} files, {{symbols}} symbols";
     readonly 'tool.detectChanges.affectedProcesses': "Affected processes: {{count}}";
@@ -177,6 +178,7 @@ export declare const en: {
     readonly 'help.option.repo.target': "Target repository";
     readonly 'help.option.context.uid': "Direct symbol UID (zero-ambiguity lookup)";
     readonly 'help.option.context.file': "File path to disambiguate common names";
+    readonly 'help.option.impact.kind': "Kind filter to disambiguate common names (e.g. Function, Class, Method)";
     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";

package/dist/cli/i18n/en.js

@@ -41,8 +41,9 @@ export const en = {
     'tool.noIndexed': 'GitNexus: No indexed repositories found. Run: gitnexus analyze',
     'tool.usage.query': 'Usage: gitnexus query <search_query>',
     'tool.usage.context': 'Usage: gitnexus context <symbol_name> [--uid <uid>] [--file <path>]',
-    'tool.usage.impact': 'Usage: gitnexus impact <symbol_name> [--direction upstream|downstream]',
+    'tool.usage.impact': 'Usage: gitnexus impact <symbol_name> [--uid <uid>] [--file <path>] [--kind <kind>] [--direction upstream|downstream]',
     'tool.usage.cypher': 'Usage: gitnexus cypher <cypher_query>',
+    'tool.warn.unknownKind': "--kind '{{kind}}' is not a known symbol kind (e.g. Function, Class, Method); it will not narrow the result.",
     'tool.detectChanges.noChanges': 'No changes detected.',
     'tool.detectChanges.changesSummary': 'Changes: {{files}} files, {{symbols}} symbols',
     'tool.detectChanges.affectedProcesses': 'Affected processes: {{count}}',
@@ -177,6 +178,7 @@ export const en = {
     'help.option.repo.target': 'Target repository',
     'help.option.context.uid': 'Direct symbol UID (zero-ambiguity lookup)',
     'help.option.context.file': 'File path to disambiguate common names',
+    'help.option.impact.kind': 'Kind filter to disambiguate common names (e.g. Function, Class, Method)',
     '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',

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

@@ -42,8 +42,9 @@ export declare const cliResources: {
         readonly 'tool.noIndexed': "GitNexus: No indexed repositories found. Run: gitnexus analyze";
         readonly 'tool.usage.query': "Usage: gitnexus query <search_query>";
         readonly 'tool.usage.context': "Usage: gitnexus context <symbol_name> [--uid <uid>] [--file <path>]";
-        readonly 'tool.usage.impact': "Usage: gitnexus impact <symbol_name> [--direction upstream|downstream]";
+        readonly 'tool.usage.impact': "Usage: gitnexus impact <symbol_name> [--uid <uid>] [--file <path>] [--kind <kind>] [--direction upstream|downstream]";
         readonly 'tool.usage.cypher': "Usage: gitnexus cypher <cypher_query>";
+        readonly 'tool.warn.unknownKind': "--kind '{{kind}}' is not a known symbol kind (e.g. Function, Class, Method); it will not narrow the result.";
         readonly 'tool.detectChanges.noChanges': "No changes detected.";
         readonly 'tool.detectChanges.changesSummary': "Changes: {{files}} files, {{symbols}} symbols";
         readonly 'tool.detectChanges.affectedProcesses': "Affected processes: {{count}}";
@@ -178,6 +179,7 @@ export declare const cliResources: {
         readonly 'help.option.repo.target': "Target repository";
         readonly 'help.option.context.uid': "Direct symbol UID (zero-ambiguity lookup)";
         readonly 'help.option.context.file': "File path to disambiguate common names";
+        readonly 'help.option.impact.kind': "Kind filter to disambiguate common names (e.g. Function, Class, Method)";
         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";
@@ -253,6 +255,7 @@ export declare const cliResources: {
         'tool.usage.context': string;
         'tool.usage.impact': string;
         'tool.usage.cypher': string;
+        'tool.warn.unknownKind': string;
         'tool.detectChanges.noChanges': string;
         'tool.detectChanges.changesSummary': string;
         'tool.detectChanges.affectedProcesses': string;
@@ -387,6 +390,7 @@ export declare const cliResources: {
         'help.option.repo.target': string;
         'help.option.context.uid': string;
         'help.option.context.file': string;
+        'help.option.impact.kind': string;
         'help.option.impact.direction': string;
         'help.option.impact.depth': string;
         'help.option.impact.includeTests': string;

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

@@ -43,6 +43,7 @@ export declare const zhCN: {
     'tool.usage.context': string;
     'tool.usage.impact': string;
     'tool.usage.cypher': string;
+    'tool.warn.unknownKind': string;
     'tool.detectChanges.noChanges': string;
     'tool.detectChanges.changesSummary': string;
     'tool.detectChanges.affectedProcesses': string;
@@ -177,6 +178,7 @@ export declare const zhCN: {
     'help.option.repo.target': string;
     'help.option.context.uid': string;
     'help.option.context.file': string;
+    'help.option.impact.kind': string;
     'help.option.impact.direction': string;
     'help.option.impact.depth': string;
     'help.option.impact.includeTests': string;

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

@@ -41,8 +41,9 @@ export const zhCN = {
     'tool.noIndexed': 'GitNexus：未找到已索引仓库。请运行：gitnexus analyze',
     'tool.usage.query': '用法：gitnexus query <搜索词>',
     'tool.usage.context': '用法：gitnexus context <符号名> [--uid <uid>] [--file <路径>]',
-    'tool.usage.impact': '用法：gitnexus impact <符号名> [--direction upstream|downstream]',
+    'tool.usage.impact': '用法：gitnexus impact <符号名> [--uid <uid>] [--file <路径>] [--kind <类型>] [--direction upstream|downstream]',
     'tool.usage.cypher': '用法：gitnexus cypher <Cypher 查询>',
+    'tool.warn.unknownKind': "--kind '{{kind}}' 不是已知的符号类型（如 Function、Class、Method），不会用于缩小结果范围。",
     'tool.detectChanges.noChanges': '未检测到变更。',
     'tool.detectChanges.changesSummary': '变更：{{files}} 个文件，{{symbols}} 个符号',
     'tool.detectChanges.affectedProcesses': '受影响流程：{{count}}',
@@ -177,6 +178,7 @@ export const zhCN = {
     'help.option.repo.target': '目标仓库',
     'help.option.context.uid': '直接符号 UID（零歧义查找）',
     'help.option.context.file': '用于消除常见名称歧义的文件路径',
+    'help.option.impact.kind': '用于消除常见名称歧义的类型过滤（如 Function、Class、Method）',
     'help.option.impact.direction': 'upstream（依赖它的项）或 downstream（它依赖的项）',
     'help.option.impact.depth': '最大关系遍历深度（默认：3）',
     'help.option.impact.includeTests': '在结果中包含测试文件',

package/dist/cli/index.js

@@ -142,10 +142,13 @@ program
     .option('--content', 'Include full symbol source code')
     .action(createLbugLazyAction(() => import('./tool.js'), 'contextCommand'));
 program
-    .command('impact <target>')
+    .command('impact [target]')
     .description('Blast radius analysis: what breaks if you change a symbol')
     .option('-d, --direction <dir>', 'upstream (dependants) or downstream (dependencies)', 'upstream')
     .option('-r, --repo <name>', 'Target repository')
+    .option('-u, --uid <uid>', 'Direct symbol UID (zero-ambiguity lookup)')
+    .option('-f, --file <path>', 'File path to disambiguate common names')
+    .option('--kind <kind>', 'Kind filter to disambiguate common names (e.g. Function, Class, Method)')
     .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)')

package/dist/cli/tool.d.ts

@@ -27,9 +27,12 @@ export declare function contextCommand(name: string, options?: {
     uid?: string;
     content?: boolean;
 }): Promise<void>;
-export declare function impactCommand(target: string, options?: {
+export declare function impactCommand(target?: string, options?: {
     direction?: string;
     repo?: string;
+    uid?: string;
+    file?: string;
+    kind?: string;
     depth?: string;
     includeTests?: boolean;
     limit?: string;

package/dist/cli/tool.js

@@ -15,8 +15,8 @@
  * See the output() function for details (#324).
  */
 import { writeSync } from 'node:fs';
-import { LocalBackend } from '../mcp/local/local-backend.js';
-import { cliErrorKey } from './cli-message.js';
+import { LocalBackend, VALID_NODE_LABELS } from '../mcp/local/local-backend.js';
+import { cliErrorKey, cliWarnKey } from './cli-message.js';
 import { formatDetectChangesResult } from './detect-changes-format.js';
 let _backend = null;
 async function getBackend() {
@@ -72,6 +72,11 @@ export async function queryCommand(queryText, options) {
     output(result);
 }
 export async function contextCommand(name, options) {
+    // Reject a `--`-prefixed uid swallowed from a following flag (see impactCommand).
+    if (options?.uid?.startsWith('--')) {
+        cliErrorKey('tool.usage.context');
+        process.exit(1);
+    }
     if (!name?.trim() && !options?.uid) {
         cliErrorKey('tool.usage.context');
         process.exit(1);
@@ -87,10 +92,25 @@ export async function contextCommand(name, options) {
     output(result);
 }
 export async function impactCommand(target, options) {
-    if (!target?.trim()) {
+    // A `--`-prefixed uid means Commander swallowed a following flag as the uid
+    // value (e.g. `impact --uid --file x` → uid === '--file'). Reject it rather
+    // than forwarding a garbage uid that would silently resolve to not-found.
+    if (options?.uid?.startsWith('--')) {
         cliErrorKey('tool.usage.impact');
         process.exit(1);
     }
+    // Target is an optional positional: a uid alone is enough to resolve (parity
+    // with `context [name]`). Only error when neither a target nor a uid is given.
+    if (!target?.trim() && !options?.uid) {
+        cliErrorKey('tool.usage.impact');
+        process.exit(1);
+    }
+    // Soft-validate --kind: an unknown kind is a no-op hint (the backend scores
+    // it but it matches nothing), so warn and proceed rather than rejecting —
+    // parity with the lenient MCP surface and forward-compatible with new labels.
+    if (options?.kind && !VALID_NODE_LABELS.has(options.kind)) {
+        cliWarnKey('tool.warn.unknownKind', { kind: options.kind });
+    }
     try {
         const backend = await getBackend();
         const rawLimit = parseInt(options?.limit ?? '', 10);
@@ -98,7 +118,10 @@ export async function impactCommand(target, options) {
         const parsedLimit = Number.isFinite(rawLimit) ? rawLimit : undefined;
         const parsedOffset = Number.isFinite(rawOffset) ? rawOffset : undefined;
         const result = await backend.callTool('impact', {
-            target,
+            target: target || undefined,
+            target_uid: options?.uid,
+            file_path: options?.file,
+            kind: options?.kind,
             direction: options?.direction || 'upstream',
             maxDepth: options?.depth ? parseInt(options.depth, 10) : undefined,
             includeTests: options?.includeTests ?? false,

package/dist/core/ingestion/csharp-namespace-gate.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Pure predicates gating C# `using` suffix-fallback resolution so BCL usings
+ * (e.g. `System.Threading.Tasks`) can't match a coincidentally-named local
+ * file (#1881).
+ *
+ * Lives in the shared `ingestion/` layer — NOT under `languages/csharp/` — so
+ * BOTH the registry-primary scope resolver (`languages/csharp/import-target.ts`)
+ * and the legacy DAG resolver (`import-resolvers/csharp.ts`) can import it
+ * without an `import-resolvers/ -> languages/` dependency inversion (#5).
+ */
+import type { CSharpNamespaceEvidence } from './language-config.js';
+/**
+ * Whether the unanchored suffix fallback may run for `targetRaw`.
+ *
+ * Fails OPEN when the namespace scan was truncated (large repos must not
+ * silently lose legitimate edges, #1881 #11) and when no evidence was
+ * threaded at all (preserves legacy permissive behavior). The truncation
+ * fail-open is carved out for clearly-external roots (BCL / well-known
+ * packages) that the repo does not declare, so one incomplete scan can't
+ * re-open the #1881 hole repo-wide. Otherwise defers to
+ * {@link importAlignsWithDeclaredNamespaces}.
+ */
+export declare function csharpSuffixFallbackAllowed(targetRaw: string, evidence: CSharpNamespaceEvidence | undefined): boolean;
+/** True when `targetRaw` plausibly refers to a namespace declared in-repo. */
+export declare function importAlignsWithDeclaredNamespaces(targetRaw: string, declaredNamespaces: ReadonlySet<string> | undefined, rootNamespaces?: ReadonlySet<string>): boolean;

package/dist/core/ingestion/csharp-namespace-gate.js

@@ -0,0 +1,129 @@
+/**
+ * Pure predicates gating C# `using` suffix-fallback resolution so BCL usings
+ * (e.g. `System.Threading.Tasks`) can't match a coincidentally-named local
+ * file (#1881).
+ *
+ * Lives in the shared `ingestion/` layer — NOT under `languages/csharp/` — so
+ * BOTH the registry-primary scope resolver (`languages/csharp/import-target.ts`)
+ * and the legacy DAG resolver (`import-resolvers/csharp.ts`) can import it
+ * without an `import-resolvers/ -> languages/` dependency inversion (#5).
+ */
+/**
+ * Top-level namespace segments that clearly belong to the BCL / runtime / a
+ * ubiquitous third-party package — i.e. roots a normal repo does NOT declare.
+ * These stay gated even when the namespace scan is truncated, so a single
+ * unreadable file / capped subtree can't silently re-enable BCL→local suffix
+ * matches repo-wide (#1881). A repo that legitimately declares one of these
+ * roots is still allowed via the alignment escape hatch below.
+ */
+const CSHARP_EXTERNAL_ROOTS = new Set([
+    // .NET BCL / runtime
+    'System',
+    'Microsoft',
+    'Windows',
+    'Mono',
+    // ubiquitous third-party NuGet roots
+    'Newtonsoft',
+    'Serilog',
+    'AutoMapper',
+    'MediatR',
+    'Polly',
+    'FluentValidation',
+    'Grpc',
+    'Google',
+    'Azure',
+    'Amazon',
+    'AWSSDK',
+    // common test frameworks
+    'Xunit',
+    'NUnit',
+    'Moq',
+    'FluentAssertions',
+    'NSubstitute',
+    'Shouldly',
+]);
+/** Whether `targetRaw`'s top-level segment is a clearly-external root. */
+function isExternalRoot(targetRaw) {
+    const dot = targetRaw.indexOf('.');
+    const top = dot === -1 ? targetRaw : targetRaw.slice(0, dot);
+    return CSHARP_EXTERNAL_ROOTS.has(top);
+}
+/**
+ * Whether the unanchored suffix fallback may run for `targetRaw`.
+ *
+ * Fails OPEN when the namespace scan was truncated (large repos must not
+ * silently lose legitimate edges, #1881 #11) and when no evidence was
+ * threaded at all (preserves legacy permissive behavior). The truncation
+ * fail-open is carved out for clearly-external roots (BCL / well-known
+ * packages) that the repo does not declare, so one incomplete scan can't
+ * re-open the #1881 hole repo-wide. Otherwise defers to
+ * {@link importAlignsWithDeclaredNamespaces}.
+ */
+export function csharpSuffixFallbackAllowed(targetRaw, evidence) {
+    if (evidence === undefined)
+        return true;
+    if (evidence.truncated) {
+        // Keep clearly-external roots blocked through truncation UNLESS the repo
+        // actually declares an aligning namespace (the alignment check is the
+        // escape hatch — a repo that declares `namespace System;` still resolves).
+        if (isExternalRoot(targetRaw) &&
+            !importAlignsWithDeclaredNamespaces(targetRaw, evidence.declaredNamespaces, evidence.rootNamespaces)) {
+            return false;
+        }
+        return true;
+    }
+    return importAlignsWithDeclaredNamespaces(targetRaw, evidence.declaredNamespaces, evidence.rootNamespaces);
+}
+/** True when `targetRaw` plausibly refers to a namespace declared in-repo. */
+export function importAlignsWithDeclaredNamespaces(targetRaw, declaredNamespaces, rootNamespaces) {
+    if (declaredNamespaces === undefined || declaredNamespaces.size === 0)
+        return false;
+    // Exact: the import IS a declared in-repo namespace.
+    if (declaredNamespaces.has(targetRaw))
+        return true;
+    // Child-of: the import's IMMEDIATE parent namespace is declared in-repo.
+    // Anchoring on the direct parent — not "any declared prefix" — is what stops
+    // a declared BCL prefix from green-lighting an unrelated BCL using: a repo
+    // that declares `namespace System;` must NOT make `using
+    // System.Threading.Tasks;` resolve to a coincidental local `Tasks.cs`,
+    // because the import's parent `System.Threading` is not itself declared
+    // (#1881). The case this still allows is a type / `using static` import under
+    // a declared namespace laid out without its full path on disk, e.g.
+    // `using static MyApp.Utils.Logger;` when `MyApp.Utils` is declared.
+    const lastDot = targetRaw.lastIndexOf('.');
+    if (lastDot > 0 && declaredNamespaces.has(targetRaw.slice(0, lastDot)))
+        return true;
+    // Ancestor-of: the import is a strict prefix of some declared namespace
+    // (e.g. `using MyApp;` when `MyApp.Models` is declared). Only honored when
+    // the import also sits at or above an in-repo root namespace, so a BCL prefix
+    // can't qualify merely because a file declares something deeper under it
+    // (e.g. `System.Threading.Tasks.Extensions`) (#1881).
+    const childPrefix = targetRaw + '.';
+    for (const ns of declaredNamespaces) {
+        if (ns.startsWith(childPrefix)) {
+            return isAtOrAboveInRepoRoot(targetRaw, declaredNamespaces, rootNamespaces);
+        }
+    }
+    return false;
+}
+function isAtOrAboveInRepoRoot(targetRaw, declaredNamespaces, rootNamespaces) {
+    const descendantPrefix = targetRaw + '.';
+    if (rootNamespaces !== undefined && rootNamespaces.size > 0) {
+        for (const root of rootNamespaces) {
+            // targetRaw equals a root, or is an ancestor of one (e.g. `using MyApp;`
+            // for csproj RootNamespace `MyApp.Core`).
+            if (root === targetRaw || root.startsWith(descendantPrefix))
+                return true;
+        }
+        return false;
+    }
+    // No explicit roots (e.g. no csproj): treat the top-level segment of each
+    // declared namespace as the implied root.
+    for (const ns of declaredNamespaces) {
+        const dot = ns.indexOf('.');
+        const top = dot === -1 ? ns : ns.slice(0, dot);
+        if (top === targetRaw)
+            return true;
+    }
+    return false;
+}

package/dist/core/ingestion/import-resolvers/configs/csharp.js

@@ -5,21 +5,36 @@
 import { SupportedLanguages } from '../../../../_shared/index.js';
 import { createStandardStrategy } from '../standard.js';
 import { resolveCSharpImportInternal, resolveCSharpNamespaceDir } from '../csharp.js';
+import { csharpSuffixFallbackAllowed } from '../../csharp-namespace-gate.js';
 /** C# namespace-based resolution strategy via .csproj configs. */
 export const csharpNamespaceStrategy = (rawImportPath, _filePath, ctx) => {
     const csharpConfigs = ctx.configs.csharpConfigs;
-    if (csharpConfigs.length > 0) {
-        const resolvedFiles = resolveCSharpImportInternal(rawImportPath, csharpConfigs, ctx.normalizedFileList, ctx.allFileList, ctx.index);
-        if (resolvedFiles.length > 1) {
-            const dirSuffix = resolveCSharpNamespaceDir(rawImportPath, csharpConfigs);
-            if (dirSuffix) {
-                return { kind: 'package', files: resolvedFiles, dirSuffix };
-            }
+    const evidence = ctx.configs.csharpNamespaces;
+    if (csharpConfigs.length === 0) {
+        // No csproj → there's no namespace→directory mapping to apply, so the
+        // generic strategy would normally take over. But that generic suffix match
+        // is UNGATED: it re-introduces the BCL→local spurious match the #1881 gate
+        // exists to stop. Mirror the registry leg's no-csproj path — defer to the
+        // generic strategy ONLY for imports that align with an in-repo declared
+        // namespace; for everything else (BCL usings) return an authoritative empty
+        // result that STOPS the chain (#2 parity). With no evidence threaded the
+        // gate fails open, so behavior is unchanged when the scan didn't run.
+        if (!csharpSuffixFallbackAllowed(rawImportPath, evidence)) {
+            return { kind: 'files', files: [] };
         }
-        if (resolvedFiles.length > 0)
-            return { kind: 'files', files: resolvedFiles };
+        return null;
     }
-    return null;
+    const resolvedFiles = resolveCSharpImportInternal(rawImportPath, csharpConfigs, ctx.normalizedFileList, ctx.allFileList, ctx.index, evidence);
+    if (resolvedFiles.length > 1) {
+        const dirSuffix = resolveCSharpNamespaceDir(rawImportPath, csharpConfigs);
+        if (dirSuffix) {
+            return { kind: 'package', files: resolvedFiles, dirSuffix };
+        }
+    }
+    // Authoritative once csproj configs exist: return even an empty result to
+    // STOP the chain, so the generic suffix fallback can't re-introduce the
+    // gated BCL→local match this resolver just suppressed (#1881).
+    return { kind: 'files', files: resolvedFiles };
 };
 export const csharpImportConfig = {
     language: SupportedLanguages.CSharp,

package/dist/core/ingestion/import-resolvers/csharp.d.ts

@@ -5,12 +5,16 @@
  * This file contains shared helpers for namespace-based resolution.
  */
 import type { SuffixIndex } from './utils.js';
-import type { CSharpProjectConfig } from '../language-config.js';
+import type { CSharpProjectConfig, CSharpNamespaceEvidence } from '../language-config.js';
 /**
  * Resolve a C# using-directive import path to matching .cs files (low-level helper).
  * Tries single-file match first, then directory match for namespace imports.
+ *
+ * The final unanchored suffix fallback is gated on `evidence` so BCL usings
+ * (e.g. `System.Threading.Tasks`) can't match a coincidentally-named local
+ * file (#1881). When `evidence` is omitted the fallback stays permissive.
  */
-export declare function resolveCSharpImportInternal(importPath: string, csharpConfigs: CSharpProjectConfig[], normalizedFileList: string[], allFileList: string[], index?: SuffixIndex): string[];
+export declare function resolveCSharpImportInternal(importPath: string, csharpConfigs: CSharpProjectConfig[], normalizedFileList: string[], allFileList: string[], index?: SuffixIndex, evidence?: CSharpNamespaceEvidence): string[];
 /**
  * Compute the directory suffix for a C# namespace import (for PackageMap).
  * Returns a suffix like "/ProjectDir/Models/" or null if no config matches.

package/dist/core/ingestion/import-resolvers/csharp.js

@@ -5,11 +5,16 @@
  * This file contains shared helpers for namespace-based resolution.
  */
 import { suffixResolve } from './utils.js';
+import { csharpSuffixFallbackAllowed } from '../csharp-namespace-gate.js';
 /**
  * Resolve a C# using-directive import path to matching .cs files (low-level helper).
  * Tries single-file match first, then directory match for namespace imports.
+ *
+ * The final unanchored suffix fallback is gated on `evidence` so BCL usings
+ * (e.g. `System.Threading.Tasks`) can't match a coincidentally-named local
+ * file (#1881). When `evidence` is omitted the fallback stays permissive.
  */
-export function resolveCSharpImportInternal(importPath, csharpConfigs, normalizedFileList, allFileList, index) {
+export function resolveCSharpImportInternal(importPath, csharpConfigs, normalizedFileList, allFileList, index, evidence) {
     const namespacePath = importPath.replace(/\./g, '/');
     const results = [];
     for (const config of csharpConfigs) {
@@ -79,7 +84,11 @@ export function resolveCSharpImportInternal(importPath, csharpConfigs, normalize
                 return results;
         }
     }
-    // Fallback: suffix matching without namespace stripping (single file)
+    // Fallback: suffix matching without namespace stripping (single file).
+    // Gated on in-repo declared-namespace evidence (#1881).
+    if (!csharpSuffixFallbackAllowed(importPath, evidence)) {
+        return [];
+    }
     const pathParts = namespacePath.split('/').filter(Boolean);
     const fallback = suffixResolve(pathParts, normalizedFileList, allFileList, index);
     return fallback ? [fallback] : [];

package/dist/core/ingestion/import-resolvers/types.d.ts

@@ -3,7 +3,7 @@
  *
  * Extracted from import-resolution.ts to co-locate types with their consumers.
  */
-import type { TsconfigPaths, GoModuleConfig, CSharpProjectConfig, ComposerConfig } from '../language-config.js';
+import type { TsconfigPaths, GoModuleConfig, CSharpProjectConfig, CSharpNamespaceEvidence, ComposerConfig } from '../language-config.js';
 import type { SwiftPackageConfig } from '../language-config.js';
 import type { SuffixIndex } from './utils.js';
 import type { SupportedLanguages } from '../../../_shared/index.js';
@@ -28,6 +28,8 @@ export interface ImportConfigs {
     composerConfig: ComposerConfig | null;
     swiftPackageConfig: SwiftPackageConfig | null;
     csharpConfigs: CSharpProjectConfig[];
+    /** In-repo namespace evidence gating C# suffix-fallback resolution (#1881). */
+    csharpNamespaces?: CSharpNamespaceEvidence;
 }
 /** Pre-built lookup structures for import resolution. Build once, reuse across chunks. */
 export interface ImportResolutionContext {

package/dist/core/ingestion/language-config.d.ts

@@ -26,6 +26,35 @@ export interface CSharpProjectConfig {
     /** Directory containing the .csproj file */
     projectDir: string;
 }
+/**
+ * Declared-namespace evidence used to gate C# suffix-fallback resolution so
+ * BCL usings (e.g. `System.Threading.Tasks`) can't match a coincidentally-
+ * named local file (#1881).
+ */
+export interface CSharpNamespaceEvidence {
+    /** Every `namespace X.Y` declared in-repo (scan may be capped — see `truncated`). */
+    readonly declaredNamespaces?: ReadonlySet<string>;
+    /** csproj RootNamespace values plus the top-level segment of each declared
+     *  namespace — the anchor set for the parent-namespace gate direction. */
+    readonly rootNamespaces?: ReadonlySet<string>;
+    /** True when the BFS hit its dir/depth cap, so the namespace set may be
+     *  incomplete; the gate fails open (allows) in that case. */
+    readonly truncated?: boolean;
+}
+/** Result of a single BFS over a repo collecting both csproj configs and
+ *  declared `.cs` namespaces (one disk traversal — see `scanCSharpProject`). */
+export interface CSharpProjectScan {
+    readonly configs: CSharpProjectConfig[];
+    readonly declaredNamespaces: ReadonlySet<string>;
+    readonly rootNamespaces: ReadonlySet<string>;
+    readonly truncated: boolean;
+}
+/** Project the one-pass {@link CSharpProjectScan} into the
+ *  {@link CSharpNamespaceEvidence} both import-resolution legs thread to the
+ *  #1881 gate — one shape, two carriers (`ImportConfigs.csharpNamespaces` for
+ *  the legacy DAG, `CsharpResolutionConfig.namespaces` for the scope resolver).
+ *  Keeps the field mapping in one place so the two carriers can't drift. */
+export declare function csharpScanToEvidence(scan: CSharpProjectScan): CSharpNamespaceEvidence;
 /** Swift Package Manager module config */
 export interface SwiftPackageConfig {
     /** Map of target name -> source directory path (e.g., "SiuperModel" -> "Package/Sources/SiuperModel") */
@@ -43,10 +72,18 @@ export declare function loadGoModulePath(repoRoot: string): Promise<GoModuleConf
 /** Parse composer.json to extract PSR-4 autoload mappings (including autoload-dev). */
 export declare function loadComposerConfig(repoRoot: string): Promise<ComposerConfig | null>;
 /**
- * Parse .csproj files to extract RootNamespace.
- * Scans the repo root for .csproj files and returns configs for each.
+ * Single BFS over a repo that collects BOTH .csproj configs and the set of
+ * `namespace` declarations from `.cs` files.
+ *
+ * The csproj walk is cheap (a handful of project files); the namespace scan
+ * is NOT — it opens and reads every `.cs` file in the repo to collect its
+ * `namespace` declarations. That `.cs` read cost is the price of the #1881
+ * gate, not a saving: collapsing the csproj and namespace walks into one BFS
+ * avoids a second directory traversal, but the per-file `.cs` reads are new
+ * work this scan introduces. Reads within a directory are issued in bounded
+ * windows (see below); directories are still visited breadth-first.
  */
-export declare function loadCSharpProjectConfig(repoRoot: string): Promise<CSharpProjectConfig[]>;
+export declare function scanCSharpProject(repoRoot: string): Promise<CSharpProjectScan>;
 export declare function loadSwiftPackageConfig(repoRoot: string): Promise<SwiftPackageConfig | null>;
 /** Load all language-specific configs once for an ingestion run. */
 export declare function loadImportConfigs(repoRoot: string): Promise<ImportConfigs>;