@veewo/gitnexus 1.3.7 → 1.3.8

package/README.md

@@ -70,7 +70,7 @@ If you prefer to configure manually instead of using `gitnexus setup`:
 ### Claude Code (full support — MCP + skills + hooks)
 
 ```bash
-claude mcp add gitnexus -- npx -y gitnexus@latest mcp
+claude mcp add gitnexus -- npx -y @veewo/gitnexus@latest mcp
 ```
 
 ### Cursor / Windsurf
@@ -82,7 +82,7 @@ Add to `~/.cursor/mcp.json` (global — works for all projects):
   "mcpServers": {
     "gitnexus": {
       "command": "npx",
-      "args": ["-y", "gitnexus@latest", "mcp"]
+      "args": ["-y", "@veewo/gitnexus@latest", "mcp"]
     }
   }
 }
@@ -97,7 +97,7 @@ Add to `~/.config/opencode/opencode.json`:
   "mcp": {
     "gitnexus": {
       "type": "local",
-      "command": ["npx", "-y", "gitnexus@latest", "mcp"]
+      "command": ["npx", "-y", "@veewo/gitnexus@latest", "mcp"]
     }
   }
 }
@@ -106,7 +106,7 @@ Add to `~/.config/opencode/opencode.json`:
 ### Codex
 
 ```bash
-codex mcp add gitnexus -- npx -y gitnexus@latest mcp
+codex mcp add gitnexus -- npx -y @veewo/gitnexus@latest mcp
 ```
 
 ## How It Works

package/dist/cli/analyze-custom-modules-regression.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/analyze-custom-modules-regression.test.js

@@ -0,0 +1,75 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { runPipelineFromRepo } from '../core/ingestion/pipeline.js';
+const FIXTURE_REPO = path.resolve(path.dirname(new URL(import.meta.url).pathname), '../../../benchmarks/fixtures/unity-mini');
+async function copyFixtureRepo() {
+    const tmpRepo = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-custom-modules-'));
+    await fs.cp(FIXTURE_REPO, tmpRepo, { recursive: true });
+    await fs.mkdir(path.join(tmpRepo, '.gitnexus'), { recursive: true });
+    return tmpRepo;
+}
+test('pipeline mixed mode writes config module + auto fallback memberships', { timeout: 120_000 }, async () => {
+    const repoPath = await copyFixtureRepo();
+    const configPath = path.join(repoPath, '.gitnexus', 'modules.json');
+    await fs.writeFile(configPath, JSON.stringify({
+        version: 1,
+        mode: 'mixed',
+        modules: [
+            {
+                name: 'Factory',
+                defaultPriority: 100,
+                rules: [
+                    {
+                        id: 'factory-file-rule',
+                        when: {
+                            all: [{ field: 'file.path', op: 'contains', value: 'MinionFactory.cs' }],
+                        },
+                    },
+                ],
+            },
+            {
+                name: 'Battle',
+                defaultPriority: 100,
+                rules: [],
+            },
+        ],
+    }), 'utf-8');
+    const result = await runPipelineFromRepo(repoPath, () => { }, { includeExtensions: ['.cs'] });
+    const communities = [...result.graph.iterNodes()].filter((n) => n.label === 'Community');
+    const memberships = [...result.graph.iterRelationships()].filter((r) => r.type === 'MEMBER_OF');
+    const commById = new Map(communities.map((c) => [c.id, c]));
+    const labels = communities.map((c) => String(c.properties.heuristicLabel || c.properties.name || c.id));
+    assert.ok(labels.includes('Factory'));
+    assert.ok(labels.includes('Battle'));
+    const createMembership = memberships.find((m) => m.sourceId.includes('MinionFactory.cs:Create'));
+    assert.ok(createMembership);
+    const targetCommunity = commById.get(createMembership.targetId);
+    assert.ok(targetCommunity);
+    assert.equal(String(targetCommunity.properties.heuristicLabel), 'Factory');
+    const uniquePerSymbol = new Set(memberships.map((m) => m.sourceId));
+    assert.equal(uniquePerSymbol.size, memberships.length);
+    const battleCommunity = communities.find((c) => String(c.properties.heuristicLabel) === 'Battle');
+    assert.ok(battleCommunity);
+    assert.ok(!memberships.some((m) => m.targetId === battleCommunity.id));
+    const membershipCommunities = new Set(memberships.map((m) => m.targetId));
+    const processCommunities = new Set((result.processResult?.processes || []).flatMap((p) => p.communities || []));
+    for (const processCommunity of processCommunities) {
+        assert.ok(membershipCommunities.has(processCommunity));
+    }
+});
+test('pipeline mixed + invalid modules.json fails fast', { timeout: 120_000 }, async () => {
+    const repoPath = await copyFixtureRepo();
+    const configPath = path.join(repoPath, '.gitnexus', 'modules.json');
+    await fs.writeFile(configPath, JSON.stringify({
+        version: 1,
+        mode: 'mixed',
+        modules: [
+            { name: 'Dup', defaultPriority: 100, rules: [] },
+            { name: 'Dup', defaultPriority: 100, rules: [] },
+        ],
+    }), 'utf-8');
+    await assert.rejects(runPipelineFromRepo(repoPath, () => { }, { includeExtensions: ['.cs'] }), /duplicate module name/i);
+});

package/dist/cli/analyze-modules-diagnostics.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/analyze-modules-diagnostics.test.js

@@ -0,0 +1,36 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { formatModuleDiagnostics } from './analyze.js';
+test('prints one-time fallback warning for mixed + missing modules.json', () => {
+    const lines = formatModuleDiagnostics({
+        mode: 'mixed',
+        usedFallbackAuto: true,
+        warnings: ['modules.json missing in mixed mode, fallback to auto'],
+        emptyModules: [],
+        configuredModuleCount: 0,
+        finalModuleCount: 3,
+    });
+    assert.ok(lines.some((line) => /fallback to auto/i.test(line)));
+});
+test('prints warning for empty modules', () => {
+    const lines = formatModuleDiagnostics({
+        mode: 'mixed',
+        usedFallbackAuto: false,
+        warnings: [],
+        emptyModules: ['Battle'],
+        configuredModuleCount: 1,
+        finalModuleCount: 2,
+    });
+    assert.ok(lines.some((line) => /empty module/i.test(line)));
+    assert.ok(lines.some((line) => /Battle/.test(line)));
+});
+test('README mentions modules.json mode semantics and fallback behavior', async () => {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const readmePath = path.resolve(here, '../../README.md');
+    const readme = await fs.readFile(readmePath, 'utf-8');
+    assert.match(readme, /\.gitnexus\/modules\.json/);
+    assert.match(readme, /mixed.*fallback.*auto/i);
+});

package/dist/cli/setup.js

@@ -6,6 +6,7 @@
  * in either global or project scope.
  */
 import fs from 'fs/promises';
+import { readFileSync } from 'node:fs';
 import path from 'path';
 import os from 'os';
 import { execFile } from 'node:child_process';
@@ -16,6 +17,7 @@ import { getGitRoot } from '../storage/git.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const execFileAsync = promisify(execFile);
+const FALLBACK_MCP_PACKAGE = 'gitnexus@latest';
 function resolveSetupScope(rawScope) {
     if (!rawScope || rawScope.trim() === '')
         return 'global';
@@ -32,6 +34,25 @@ function resolveSetupAgent(rawAgent) {
     }
     throw new Error(`Invalid --agent value "${rawAgent}". Use "claude", "opencode", or "codex".`);
 }
+/**
+ * Resolve the package spec used by MCP commands.
+ * Defaults to gitnexus@latest when package metadata is unavailable.
+ */
+function resolveMcpPackageSpec() {
+    try {
+        const packageJsonPath = path.join(__dirname, '..', '..', 'package.json');
+        const raw = readFileSync(packageJsonPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.name === 'string' && parsed.name.trim().length > 0) {
+            return `${parsed.name}@latest`;
+        }
+    }
+    catch {
+        // Fallback keeps behavior for unusual runtimes.
+    }
+    return FALLBACK_MCP_PACKAGE;
+}
+const MCP_PACKAGE_SPEC = resolveMcpPackageSpec();
 /**
  * The MCP server entry for all editors.
  * On Windows, npx must be invoked via cmd /c since it's a .cmd script.
@@ -40,12 +61,12 @@ function getMcpEntry() {
     if (process.platform === 'win32') {
         return {
             command: 'cmd',
-            args: ['/c', 'npx', '-y', 'gitnexus@latest', 'mcp'],
+            args: ['/c', 'npx', '-y', MCP_PACKAGE_SPEC, 'mcp'],
         };
     }
     return {
         command: 'npx',
-        args: ['-y', 'gitnexus@latest', 'mcp'],
+        args: ['-y', MCP_PACKAGE_SPEC, 'mcp'],
     };
 }
 function getOpenCodeMcpEntry() {
@@ -190,7 +211,7 @@ async function setupClaudeCode(result) {
     console.log('');
     console.log('  Claude Code detected. Run this command to add GitNexus MCP:');
     console.log('');
-    console.log('    claude mcp add gitnexus -- npx -y gitnexus mcp');
+    console.log(`    claude mcp add gitnexus -- npx -y ${MCP_PACKAGE_SPEC} mcp`);
     console.log('');
     result.configured.push('Claude Code (MCP manual step printed)');
 }

package/dist/cli/setup.test.js

@@ -10,6 +10,8 @@ const execFileAsync = promisify(execFile);
 const here = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(here, '..', '..');
 const cliPath = path.join(packageRoot, 'dist', 'cli', 'index.js');
+const packageName = JSON.parse(await fs.readFile(path.join(packageRoot, 'package.json'), 'utf-8'));
+const expectedMcpPackage = `${packageName.name || 'gitnexus'}@latest`;
 async function runSetup(args, env, cwd = packageRoot) {
     return execFileAsync(process.execPath, [cliPath, 'setup', ...args], { cwd, env });
 }
@@ -112,7 +114,7 @@ process.exit(0);
         const raw = await fs.readFile(outputPath, 'utf-8');
         const parsed = JSON.parse(raw);
         assert.deepEqual(parsed.args.slice(0, 4), ['mcp', 'add', 'gitnexus', '--']);
-        assert.ok(parsed.args.includes('gitnexus@latest'));
+        assert.ok(parsed.args.includes(expectedMcpPackage));
         assert.ok(parsed.args.includes('mcp'));
     }
     finally {
@@ -134,7 +136,7 @@ test('setup configures OpenCode MCP in ~/.config/opencode/opencode.json', async
         const opencodeRaw = await fs.readFile(opencodeConfigPath, 'utf-8');
         const opencodeConfig = JSON.parse(opencodeRaw);
         assert.equal(opencodeConfig.mcp?.gitnexus?.type, 'local');
-        assert.deepEqual(opencodeConfig.mcp?.gitnexus?.command, ['npx', '-y', 'gitnexus@latest', 'mcp']);
+        assert.deepEqual(opencodeConfig.mcp?.gitnexus?.command, ['npx', '-y', expectedMcpPackage, 'mcp']);
     }
     finally {
         await fs.rm(fakeHome, { recursive: true, force: true });
@@ -157,7 +159,7 @@ test('setup keeps using legacy ~/.config/opencode/config.json when it already ex
         const legacyConfig = JSON.parse(legacyRaw);
         assert.equal(legacyConfig.existing, true);
         assert.equal(legacyConfig.mcp?.gitnexus?.type, 'local');
-        assert.deepEqual(legacyConfig.mcp?.gitnexus?.command, ['npx', '-y', 'gitnexus@latest', 'mcp']);
+        assert.deepEqual(legacyConfig.mcp?.gitnexus?.command, ['npx', '-y', expectedMcpPackage, 'mcp']);
         await assert.rejects(fs.access(preferredConfigPath));
     }
     finally {
@@ -254,7 +256,7 @@ test('setup --scope project --agent opencode writes only opencode.json', async (
         const configRaw = await fs.readFile(configPath, 'utf-8');
         const config = JSON.parse(configRaw);
         assert.equal(opencodeConfig.mcp?.gitnexus?.type, 'local');
-        assert.deepEqual(opencodeConfig.mcp?.gitnexus?.command, ['npx', '-y', 'gitnexus@latest', 'mcp']);
+        assert.deepEqual(opencodeConfig.mcp?.gitnexus?.command, ['npx', '-y', expectedMcpPackage, 'mcp']);
         await assert.rejects(fs.access(projectMcpPath));
         await assert.rejects(fs.access(codexConfigPath));
         await fs.access(localSkillPath);

package/dist/core/ingestion/modules/assignment-engine.d.ts

@@ -0,0 +1,33 @@
+import type { CommunityMembership, CommunityNode } from '../community-processor.js';
+import type { ModuleConfig, ModuleMode } from './types.js';
+import { type MatchableSymbol } from './rule-matcher.js';
+export type AssignmentSource = 'config-rule' | 'auto-fallback';
+export type AssignmentResolvedBy = 'priority' | 'specificity' | 'rule-order' | 'module-lexicographic' | 'fallback-auto';
+export interface AssignmentInput {
+    mode: ModuleMode;
+    symbols: MatchableSymbol[];
+    autoCommunities: CommunityNode[];
+    autoMemberships: CommunityMembership[];
+    config: ModuleConfig | null;
+}
+export interface SymbolAssignment {
+    symbolId: string;
+    moduleName: string;
+    communityId: string;
+    assignmentSource: AssignmentSource;
+    matchedRuleId?: string;
+    resolvedBy: AssignmentResolvedBy;
+}
+export interface AssignmentDiagnostics {
+    mode: ModuleMode;
+    configuredModuleCount: number;
+    finalModuleCount: number;
+    emptyModules: string[];
+}
+export interface AssignmentOutput {
+    finalModules: CommunityNode[];
+    finalMemberships: CommunityMembership[];
+    membershipsBySymbol: Map<string, SymbolAssignment>;
+    diagnostics: AssignmentDiagnostics;
+}
+export declare function assignModules(input: AssignmentInput): AssignmentOutput;

package/dist/core/ingestion/modules/assignment-engine.js

@@ -0,0 +1,179 @@
+import { matchRule, ruleSpecificityScore } from './rule-matcher.js';
+function sanitizeModuleId(name) {
+    const base = name.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+    return base || 'module';
+}
+function resolveBy(top, second) {
+    if (!second)
+        return 'priority';
+    if (top.effectivePriority !== second.effectivePriority)
+        return 'priority';
+    if (top.specificity !== second.specificity)
+        return 'specificity';
+    if (top.ruleOrder !== second.ruleOrder)
+        return 'rule-order';
+    return 'module-lexicographic';
+}
+function pickWinner(candidates) {
+    const sorted = [...candidates].sort((a, b) => {
+        if (a.effectivePriority !== b.effectivePriority)
+            return b.effectivePriority - a.effectivePriority;
+        if (a.specificity !== b.specificity)
+            return b.specificity - a.specificity;
+        if (a.ruleOrder !== b.ruleOrder)
+            return a.ruleOrder - b.ruleOrder;
+        return a.moduleName.localeCompare(b.moduleName);
+    });
+    return { winner: sorted[0], resolvedBy: resolveBy(sorted[0], sorted[1]) };
+}
+function buildAutoFallbackMap(autoCommunities) {
+    const m = new Map();
+    for (const comm of autoCommunities)
+        m.set(comm.id, comm);
+    return m;
+}
+function toConfiguredCommunities(config) {
+    const seen = new Set();
+    return config.modules.map((mod) => {
+        let idBase = `comm_cfg_${sanitizeModuleId(mod.name)}`;
+        let suffix = 1;
+        while (seen.has(idBase)) {
+            idBase = `comm_cfg_${sanitizeModuleId(mod.name)}_${suffix++}`;
+        }
+        seen.add(idBase);
+        return {
+            id: idBase,
+            moduleName: mod.name,
+            label: mod.name,
+            heuristicLabel: mod.name,
+            cohesion: 0,
+            symbolCount: 0,
+        };
+    });
+}
+export function assignModules(input) {
+    const membershipsBySymbol = new Map();
+    if (input.mode === 'auto' || !input.config) {
+        const autoCommunityById = buildAutoFallbackMap(input.autoCommunities);
+        for (const membership of input.autoMemberships) {
+            const autoComm = autoCommunityById.get(membership.communityId);
+            const moduleName = autoComm?.heuristicLabel || autoComm?.label || membership.communityId;
+            membershipsBySymbol.set(membership.nodeId, {
+                symbolId: membership.nodeId,
+                moduleName,
+                communityId: membership.communityId,
+                assignmentSource: 'auto-fallback',
+                resolvedBy: 'fallback-auto',
+            });
+        }
+        return {
+            finalModules: input.autoCommunities,
+            finalMemberships: input.autoMemberships,
+            membershipsBySymbol,
+            diagnostics: {
+                mode: input.mode,
+                configuredModuleCount: 0,
+                finalModuleCount: input.autoCommunities.length,
+                emptyModules: [],
+            },
+        };
+    }
+    const configuredCommunities = toConfiguredCommunities(input.config);
+    const configuredCommByName = new Map();
+    for (const comm of configuredCommunities) {
+        configuredCommByName.set(comm.moduleName, comm);
+    }
+    const autoCommunityById = buildAutoFallbackMap(input.autoCommunities);
+    const symbolById = new Map(input.symbols.map((s) => [s.id, s]));
+    const autoMembershipBySymbol = new Map(input.autoMemberships.map((m) => [m.nodeId, m.communityId]));
+    const configModuleCounts = new Map();
+    const fallbackCommunityCounts = new Map();
+    const finalMemberships = [];
+    for (const [symbolId, autoCommunityId] of autoMembershipBySymbol.entries()) {
+        const symbol = symbolById.get(symbolId);
+        if (!symbol)
+            continue;
+        const candidates = [];
+        let ruleOrder = 0;
+        for (const moduleDef of input.config.modules) {
+            const comm = configuredCommByName.get(moduleDef.name);
+            if (!comm)
+                continue;
+            for (const rule of moduleDef.rules) {
+                if (!matchRule(symbol, rule)) {
+                    ruleOrder += 1;
+                    continue;
+                }
+                candidates.push({
+                    moduleName: moduleDef.name,
+                    communityId: comm.id,
+                    ruleId: rule.id,
+                    effectivePriority: rule.priority ?? moduleDef.defaultPriority,
+                    specificity: ruleSpecificityScore(rule),
+                    ruleOrder,
+                });
+                ruleOrder += 1;
+            }
+        }
+        if (candidates.length === 0) {
+            finalMemberships.push({ nodeId: symbolId, communityId: autoCommunityId });
+            fallbackCommunityCounts.set(autoCommunityId, (fallbackCommunityCounts.get(autoCommunityId) || 0) + 1);
+            const autoCommunity = autoCommunityById.get(autoCommunityId);
+            membershipsBySymbol.set(symbolId, {
+                symbolId,
+                moduleName: autoCommunity?.heuristicLabel || autoCommunity?.label || autoCommunityId,
+                communityId: autoCommunityId,
+                assignmentSource: 'auto-fallback',
+                resolvedBy: 'fallback-auto',
+            });
+            continue;
+        }
+        const { winner, resolvedBy } = pickWinner(candidates);
+        finalMemberships.push({ nodeId: symbolId, communityId: winner.communityId });
+        configModuleCounts.set(winner.moduleName, (configModuleCounts.get(winner.moduleName) || 0) + 1);
+        membershipsBySymbol.set(symbolId, {
+            symbolId,
+            moduleName: winner.moduleName,
+            communityId: winner.communityId,
+            assignmentSource: 'config-rule',
+            matchedRuleId: winner.ruleId,
+            resolvedBy,
+        });
+    }
+    const emptyModules = [];
+    const finalModules = configuredCommunities.map((comm) => {
+        const count = configModuleCounts.get(comm.moduleName) || 0;
+        if (count === 0)
+            emptyModules.push(comm.moduleName);
+        return {
+            id: comm.id,
+            label: comm.label,
+            heuristicLabel: comm.heuristicLabel,
+            cohesion: 0,
+            symbolCount: count,
+        };
+    });
+    for (const autoComm of input.autoCommunities) {
+        const fallbackCount = fallbackCommunityCounts.get(autoComm.id) || 0;
+        if (fallbackCount <= 0)
+            continue;
+        finalModules.push({
+            id: autoComm.id,
+            label: autoComm.label,
+            heuristicLabel: autoComm.heuristicLabel,
+            cohesion: autoComm.cohesion,
+            symbolCount: fallbackCount,
+        });
+    }
+    return {
+        finalModules,
+        finalMemberships,
+        membershipsBySymbol,
+        diagnostics: {
+            mode: input.mode,
+            configuredModuleCount: input.config.modules.length,
+            finalModuleCount: finalModules.length,
+            emptyModules,
+        },
+    };
+}

package/dist/core/ingestion/modules/assignment-engine.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/ingestion/modules/assignment-engine.test.js

@@ -0,0 +1,111 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { assignModules } from './assignment-engine.js';
+function baseInput() {
+    return {
+        mode: 'mixed',
+        symbols: [
+            {
+                id: 'Class:MinionFactory',
+                name: 'MinionFactory',
+                kind: 'Class',
+                filePath: 'Assets/Scripts/MinionFactory.cs',
+            },
+            {
+                id: 'Class:Minion',
+                name: 'Minion',
+                kind: 'Class',
+                filePath: 'Assets/Scripts/Minion.cs',
+            },
+        ],
+        autoCommunities: [
+            {
+                id: 'comm_0',
+                label: 'AutoGroup',
+                heuristicLabel: 'AutoGroup',
+                cohesion: 0.7,
+                symbolCount: 2,
+            },
+        ],
+        autoMemberships: [
+            { nodeId: 'Class:MinionFactory', communityId: 'comm_0' },
+            { nodeId: 'Class:Minion', communityId: 'comm_0' },
+        ],
+        config: {
+            version: 1,
+            mode: 'mixed',
+            modules: [
+                {
+                    name: 'Factory',
+                    defaultPriority: 100,
+                    rules: [
+                        {
+                            id: 'factory-rule',
+                            when: {
+                                all: [{ field: 'symbol.name', op: 'contains', value: 'Factory' }],
+                            },
+                        },
+                    ],
+                },
+            ],
+        },
+    };
+}
+test('mixed mode applies config override and auto fallback with single membership', () => {
+    const out = assignModules(baseInput());
+    assert.equal(out.finalMemberships.length, 2);
+    assert.equal(new Set(out.finalMemberships.map((m) => m.nodeId)).size, 2);
+    assert.equal(out.membershipsBySymbol.get('Class:MinionFactory')?.moduleName, 'Factory');
+    assert.equal(out.membershipsBySymbol.get('Class:MinionFactory')?.assignmentSource, 'config-rule');
+    assert.equal(out.membershipsBySymbol.get('Class:Minion')?.assignmentSource, 'auto-fallback');
+});
+test('conflict resolution order: priority > specificity > rule-order > module-name', () => {
+    const input = baseInput();
+    input.symbols = [{ id: 'Class:X', name: 'X', kind: 'Class', filePath: 'x.ts' }];
+    input.autoMemberships = [{ nodeId: 'Class:X', communityId: 'comm_0' }];
+    input.autoCommunities = [{ id: 'comm_0', label: 'Auto', heuristicLabel: 'Auto', cohesion: 0.4, symbolCount: 1 }];
+    input.config = {
+        version: 1,
+        mode: 'mixed',
+        modules: [
+            {
+                name: 'ContainsWinsByOrder',
+                defaultPriority: 100,
+                rules: [{ id: 'contains-a', when: { all: [{ field: 'symbol.name', op: 'contains', value: 'X' }] } }],
+            },
+            {
+                name: 'EqWinsBySpecificity',
+                defaultPriority: 100,
+                rules: [{ id: 'eq-b', when: { all: [{ field: 'symbol.name', op: 'eq', value: 'X' }] } }],
+            },
+        ],
+    };
+    const out = assignModules(input);
+    assert.equal(out.membershipsBySymbol.get('Class:X')?.moduleName, 'EqWinsBySpecificity');
+    assert.equal(out.membershipsBySymbol.get('Class:X')?.resolvedBy, 'specificity');
+});
+test('higher effective priority wins even with lower specificity', () => {
+    const input = baseInput();
+    input.symbols = [{ id: 'Class:X', name: 'X', kind: 'Class', filePath: 'x.ts' }];
+    input.autoMemberships = [{ nodeId: 'Class:X', communityId: 'comm_0' }];
+    input.autoCommunities = [{ id: 'comm_0', label: 'Auto', heuristicLabel: 'Auto', cohesion: 0.4, symbolCount: 1 }];
+    input.config = {
+        version: 1,
+        mode: 'mixed',
+        modules: [
+            {
+                name: 'HighPriorityContains',
+                defaultPriority: 120,
+                rules: [{ id: 'contains-a', when: { all: [{ field: 'symbol.name', op: 'contains', value: 'X' }] } }],
+            },
+            {
+                name: 'LowPriorityEq',
+                defaultPriority: 100,
+                rules: [{ id: 'eq-b', when: { all: [{ field: 'symbol.name', op: 'eq', value: 'X' }] } }],
+            },
+        ],
+    };
+    const out = assignModules(input);
+    assert.equal(out.membershipsBySymbol.get('Class:X')?.moduleName, 'HighPriorityContains');
+    assert.equal(out.membershipsBySymbol.get('Class:X')?.resolvedBy, 'priority');
+});

package/dist/core/ingestion/modules/config-loader.d.ts

@@ -0,0 +1,2 @@
+import { type LoadModuleConfigInput, type ModuleConfigLoadResult } from './types.js';
+export declare function loadModuleConfig(input: LoadModuleConfigInput): Promise<ModuleConfigLoadResult>;

package/dist/core/ingestion/modules/config-loader.js

@@ -0,0 +1,186 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { MODULE_FIELDS, MODULE_OPERATORS, } from './types.js';
+const MODULE_CONFIG_RELATIVE_PATH = path.join('.gitnexus', 'modules.json');
+function assertObject(input, fieldPath) {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) {
+        throw new Error(`${fieldPath} must be an object`);
+    }
+    return input;
+}
+function assertString(input, fieldPath) {
+    if (typeof input !== 'string' || input.trim().length === 0) {
+        throw new Error(`${fieldPath} must be a non-empty string`);
+    }
+    return input.trim();
+}
+function assertNumber(input, fieldPath) {
+    if (typeof input !== 'number' || !Number.isFinite(input)) {
+        throw new Error(`${fieldPath} must be a finite number`);
+    }
+    return input;
+}
+function toMode(input, defaultMode) {
+    if (input === undefined || input === null || input === '')
+        return defaultMode;
+    if (input === 'auto' || input === 'mixed')
+        return input;
+    throw new Error(`mode must be one of: auto, mixed`);
+}
+function validateCondition(input, fieldPath) {
+    const obj = assertObject(input, fieldPath);
+    const field = assertString(obj.field, `${fieldPath}.field`);
+    const op = assertString(obj.op, `${fieldPath}.op`);
+    if (!MODULE_FIELDS.includes(field)) {
+        throw new Error(`${fieldPath}.field must be one of: ${MODULE_FIELDS.join(', ')}`);
+    }
+    if (!MODULE_OPERATORS.includes(op)) {
+        throw new Error(`${fieldPath}.op must be one of: ${MODULE_OPERATORS.join(', ')}`);
+    }
+    const value = obj.value;
+    if (op === 'in') {
+        if (!Array.isArray(value) || value.length === 0 || value.some((v) => typeof v !== 'string' || v.length === 0)) {
+            throw new Error(`${fieldPath}.value must be a non-empty string array when op=in`);
+        }
+        return { field: field, op: 'in', value: value };
+    }
+    if (typeof value !== 'string') {
+        throw new Error(`${fieldPath}.value must be a string when op=${op}`);
+    }
+    if (op === 'regex') {
+        try {
+            new RegExp(value);
+        }
+        catch (error) {
+            throw new Error(`${fieldPath}.value regex compile failed: ${error?.message || String(error)}`);
+        }
+    }
+    return {
+        field: field,
+        op: op,
+        value,
+    };
+}
+function validateRule(input, fieldPath, seenRuleIds) {
+    const obj = assertObject(input, fieldPath);
+    const id = assertString(obj.id, `${fieldPath}.id`);
+    const existingPath = seenRuleIds.get(id);
+    if (existingPath) {
+        throw new Error(`${fieldPath}.id duplicate rule id "${id}" (already declared at ${existingPath})`);
+    }
+    seenRuleIds.set(id, `${fieldPath}.id`);
+    const priority = obj.priority === undefined ? undefined : assertNumber(obj.priority, `${fieldPath}.priority`);
+    const whenObj = assertObject(obj.when, `${fieldPath}.when`);
+    const hasAll = Array.isArray(whenObj.all);
+    const hasAny = Array.isArray(whenObj.any);
+    if (!hasAll && !hasAny) {
+        throw new Error(`${fieldPath}.when must include "all" or "any"`);
+    }
+    const all = hasAll ? whenObj.all.map((c, idx) => validateCondition(c, `${fieldPath}.when.all[${idx}]`)) : undefined;
+    const any = hasAny ? whenObj.any.map((c, idx) => validateCondition(c, `${fieldPath}.when.any[${idx}]`)) : undefined;
+    if ((all && all.length === 0) && (!any || any.length === 0)) {
+        throw new Error(`${fieldPath}.when must include at least one condition`);
+    }
+    return {
+        id,
+        priority,
+        when: { all, any },
+    };
+}
+function validateModule(input, fieldPath, seenRuleIds) {
+    const obj = assertObject(input, fieldPath);
+    const name = assertString(obj.name, `${fieldPath}.name`);
+    const defaultPriority = assertNumber(obj.defaultPriority, `${fieldPath}.defaultPriority`);
+    const rawRules = obj.rules;
+    if (rawRules !== undefined && !Array.isArray(rawRules)) {
+        throw new Error(`${fieldPath}.rules must be an array`);
+    }
+    const rules = rawRules?.map((rule, idx) => validateRule(rule, `${fieldPath}.rules[${idx}]`, seenRuleIds)) || [];
+    return { name, defaultPriority, rules };
+}
+function validateMixedConfig(input, defaultMode) {
+    const obj = assertObject(input, 'modules.json');
+    if (obj.version !== 1) {
+        throw new Error(`version must be 1`);
+    }
+    const mode = toMode(obj.mode, defaultMode);
+    if (mode !== 'mixed') {
+        // auto mode intentionally ignores module schema to keep behavior non-blocking.
+        return { version: 1, mode: 'auto', modules: [] };
+    }
+    if (!Array.isArray(obj.modules) || obj.modules.length === 0) {
+        throw new Error(`modules must be a non-empty array`);
+    }
+    const seenModuleNames = new Set();
+    const seenRuleIds = new Map();
+    const modules = obj.modules.map((mod, idx) => {
+        const normalized = validateModule(mod, `modules[${idx}]`, seenRuleIds);
+        if (seenModuleNames.has(normalized.name)) {
+            throw new Error(`modules[${idx}].name duplicate module name "${normalized.name}"`);
+        }
+        seenModuleNames.add(normalized.name);
+        return normalized;
+    });
+    return {
+        version: 1,
+        mode: 'mixed',
+        modules,
+    };
+}
+export async function loadModuleConfig(input) {
+    const defaultMode = input.defaultMode ?? 'mixed';
+    const configPath = path.join(input.repoPath, MODULE_CONFIG_RELATIVE_PATH);
+    const diagnostics = {
+        configPath,
+        usedFallbackAuto: false,
+        warnings: [],
+    };
+    if (defaultMode === 'auto') {
+        return {
+            mode: 'auto',
+            config: null,
+            diagnostics,
+            usedFallbackAuto: false,
+        };
+    }
+    let rawText;
+    try {
+        rawText = await fs.readFile(configPath, 'utf-8');
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT') {
+            diagnostics.usedFallbackAuto = true;
+            diagnostics.warnings.push('modules.json missing in mixed mode, fallback to auto');
+            return {
+                mode: 'mixed',
+                config: null,
+                diagnostics,
+                usedFallbackAuto: true,
+            };
+        }
+        throw error;
+    }
+    let rawConfig;
+    try {
+        rawConfig = JSON.parse(rawText);
+    }
+    catch (error) {
+        throw new Error(`modules.json invalid JSON: ${error?.message || String(error)}`);
+    }
+    const parsedMode = toMode(assertObject(rawConfig, 'modules.json').mode, defaultMode);
+    if (parsedMode === 'auto') {
+        return {
+            mode: 'auto',
+            config: null,
+            diagnostics,
+            usedFallbackAuto: false,
+        };
+    }
+    const config = validateMixedConfig(rawConfig, defaultMode);
+    return {
+        mode: config.mode,
+        config,
+        diagnostics,
+        usedFallbackAuto: false,
+    };
+}

package/dist/core/ingestion/modules/config-loader.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/ingestion/modules/config-loader.test.js

@@ -0,0 +1,57 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { loadModuleConfig } from './config-loader.js';
+async function makeTempRepo() {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-modules-loader-'));
+    await fs.mkdir(path.join(dir, '.gitnexus'), { recursive: true });
+    return dir;
+}
+test('mixed + missing modules.json returns fallback diagnostic (no throw)', async () => {
+    const repoPath = await makeTempRepo();
+    const result = await loadModuleConfig({ repoPath, defaultMode: 'mixed' });
+    assert.equal(result.mode, 'mixed');
+    assert.equal(result.usedFallbackAuto, true);
+    assert.equal(result.config, null);
+});
+test('mixed + invalid duplicate rule id throws with location', async () => {
+    const repoPath = await makeTempRepo();
+    const cfgPath = path.join(repoPath, '.gitnexus', 'modules.json');
+    await fs.writeFile(cfgPath, JSON.stringify({
+        version: 1,
+        mode: 'mixed',
+        modules: [
+            {
+                name: 'A',
+                defaultPriority: 10,
+                rules: [{ id: 'dup', when: { all: [{ field: 'symbol.name', op: 'contains', value: 'X' }] } }],
+            },
+            {
+                name: 'B',
+                defaultPriority: 10,
+                rules: [{ id: 'dup', when: { all: [{ field: 'symbol.name', op: 'contains', value: 'Y' }] } }],
+            },
+        ],
+    }), 'utf-8');
+    await assert.rejects(loadModuleConfig({ repoPath, defaultMode: 'mixed' }), /rules\[0\]\.id.*duplicate/i);
+});
+test('valid config defaults mode to mixed when omitted', async () => {
+    const repoPath = await makeTempRepo();
+    const cfgPath = path.join(repoPath, '.gitnexus', 'modules.json');
+    await fs.writeFile(cfgPath, JSON.stringify({
+        version: 1,
+        modules: [
+            {
+                name: 'Battle',
+                defaultPriority: 100,
+                rules: [{ id: 'battle-rule', when: { all: [{ field: 'symbol.name', op: 'contains', value: 'Battle' }] } }],
+            },
+        ],
+    }), 'utf-8');
+    const result = await loadModuleConfig({ repoPath, defaultMode: 'mixed' });
+    assert.equal(result.mode, 'mixed');
+    assert.equal(result.usedFallbackAuto, false);
+    assert.equal(result.config?.modules.length, 1);
+});

package/dist/core/ingestion/modules/rule-matcher.d.ts

@@ -0,0 +1,12 @@
+import type { ModuleCondition, ModuleRule } from './types.js';
+export interface MatchableSymbol {
+    id: string;
+    name: string;
+    kind: string;
+    fqn?: string;
+    filePath: string;
+}
+export declare function matchCondition(symbol: MatchableSymbol, condition: ModuleCondition): boolean;
+export declare function matchRule(symbol: MatchableSymbol, rule: ModuleRule): boolean;
+export declare function specificityScore(condition: ModuleCondition): number;
+export declare function ruleSpecificityScore(rule: ModuleRule): number;

package/dist/core/ingestion/modules/rule-matcher.js

@@ -0,0 +1,63 @@
+function readFieldValue(symbol, field) {
+    switch (field) {
+        case 'symbol.name':
+            return symbol.name;
+        case 'symbol.kind':
+            return symbol.kind;
+        case 'symbol.fqn':
+            return symbol.fqn && symbol.fqn.length > 0 ? symbol.fqn : symbol.name;
+        case 'file.path':
+            return symbol.filePath;
+        default:
+            return '';
+    }
+}
+export function matchCondition(symbol, condition) {
+    const actual = readFieldValue(symbol, condition.field);
+    if (condition.op === 'eq') {
+        return actual === condition.value;
+    }
+    if (condition.op === 'contains') {
+        return actual.includes(String(condition.value));
+    }
+    if (condition.op === 'regex') {
+        try {
+            return new RegExp(String(condition.value)).test(actual);
+        }
+        catch {
+            return false;
+        }
+    }
+    if (condition.op === 'in') {
+        return Array.isArray(condition.value) && condition.value.includes(actual);
+    }
+    return false;
+}
+export function matchRule(symbol, rule) {
+    const hasAll = Array.isArray(rule.when.all);
+    const hasAny = Array.isArray(rule.when.any);
+    if (!hasAll && !hasAny)
+        return false;
+    const allPass = !hasAll || rule.when.all.every((cond) => matchCondition(symbol, cond));
+    const anyPass = !hasAny || rule.when.any.some((cond) => matchCondition(symbol, cond));
+    return allPass && anyPass;
+}
+export function specificityScore(condition) {
+    switch (condition.op) {
+        case 'eq':
+            return 4;
+        case 'in':
+            return 3;
+        case 'regex':
+            return 2;
+        case 'contains':
+            return 1;
+        default:
+            return 0;
+    }
+}
+export function ruleSpecificityScore(rule) {
+    const all = rule.when.all || [];
+    const any = rule.when.any || [];
+    return [...all, ...any].reduce((sum, cond) => sum + specificityScore(cond), 0);
+}

package/dist/core/ingestion/modules/rule-matcher.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/ingestion/modules/rule-matcher.test.js

@@ -0,0 +1,58 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { matchRule, specificityScore } from './rule-matcher.js';
+const sample = {
+    id: 'Class:BattleManager',
+    name: 'BattleManager',
+    kind: 'Class',
+    filePath: 'Assets/Scripts/Battle/BattleManager.cs',
+};
+test('supports eq/contains/regex/in on symbol fields', () => {
+    assert.equal(matchRule(sample, {
+        id: 'r1',
+        when: { all: [{ field: 'symbol.kind', op: 'eq', value: 'Class' }] },
+    }), true);
+    assert.equal(matchRule(sample, {
+        id: 'r2',
+        when: { all: [{ field: 'symbol.name', op: 'contains', value: 'Battle' }] },
+    }), true);
+    assert.equal(matchRule(sample, {
+        id: 'r3',
+        when: { all: [{ field: 'symbol.name', op: 'regex', value: '^Battle.*' }] },
+    }), true);
+    assert.equal(matchRule(sample, {
+        id: 'r4',
+        when: { all: [{ field: 'file.path', op: 'in', value: ['Assets/Scripts/Battle/BattleManager.cs'] }] },
+    }), true);
+});
+test('all + any must both pass when both provided', () => {
+    const pass = matchRule(sample, {
+        id: 'all-any-pass',
+        when: {
+            all: [{ field: 'symbol.name', op: 'contains', value: 'Battle' }],
+            any: [{ field: 'symbol.kind', op: 'eq', value: 'Class' }],
+        },
+    });
+    assert.equal(pass, true);
+    const fail = matchRule(sample, {
+        id: 'all-any-fail',
+        when: {
+            all: [{ field: 'symbol.name', op: 'contains', value: 'Battle' }],
+            any: [{ field: 'symbol.kind', op: 'eq', value: 'Function' }],
+        },
+    });
+    assert.equal(fail, false);
+});
+test('symbol.fqn falls back to symbol.name when fqn missing', () => {
+    const hit = matchRule(sample, {
+        id: 'fqn-fallback',
+        when: { all: [{ field: 'symbol.fqn', op: 'contains', value: 'BattleManager' }] },
+    });
+    assert.equal(hit, true);
+});
+test('specificity score weights operators deterministically', () => {
+    assert.equal(specificityScore({ field: 'symbol.name', op: 'eq', value: 'A' }), 4);
+    assert.equal(specificityScore({ field: 'symbol.name', op: 'in', value: ['A'] }), 3);
+    assert.equal(specificityScore({ field: 'symbol.name', op: 'regex', value: '^A$' }), 2);
+    assert.equal(specificityScore({ field: 'symbol.name', op: 'contains', value: 'A' }), 1);
+});

package/dist/core/ingestion/modules/types.d.ts

@@ -0,0 +1,44 @@
+export type ModuleMode = 'auto' | 'mixed';
+export type ModuleField = 'symbol.name' | 'symbol.kind' | 'symbol.fqn' | 'file.path';
+export type ModuleOperator = 'eq' | 'contains' | 'regex' | 'in';
+export interface ModuleCondition {
+    field: ModuleField;
+    op: ModuleOperator;
+    value: string | string[];
+}
+export interface ModuleRuleWhen {
+    all?: ModuleCondition[];
+    any?: ModuleCondition[];
+}
+export interface ModuleRule {
+    id: string;
+    priority?: number;
+    when: ModuleRuleWhen;
+}
+export interface ModuleDefinition {
+    name: string;
+    defaultPriority: number;
+    rules: ModuleRule[];
+}
+export interface ModuleConfig {
+    version: 1;
+    mode: ModuleMode;
+    modules: ModuleDefinition[];
+}
+export interface ModuleConfigLoadDiagnostics {
+    configPath: string;
+    usedFallbackAuto: boolean;
+    warnings: string[];
+}
+export interface LoadModuleConfigInput {
+    repoPath: string;
+    defaultMode?: ModuleMode;
+}
+export interface ModuleConfigLoadResult {
+    mode: ModuleMode;
+    config: ModuleConfig | null;
+    diagnostics: ModuleConfigLoadDiagnostics;
+    usedFallbackAuto: boolean;
+}
+export declare const MODULE_FIELDS: readonly ModuleField[];
+export declare const MODULE_OPERATORS: readonly ModuleOperator[];

package/dist/core/ingestion/modules/types.js

@@ -0,0 +1,2 @@
+export const MODULE_FIELDS = ['symbol.name', 'symbol.kind', 'symbol.fqn', 'file.path'];
+export const MODULE_OPERATORS = ['eq', 'contains', 'regex', 'in'];

package/dist/mcp/local/cluster-aggregation.d.ts

@@ -0,0 +1,20 @@
+export interface RawCluster {
+    id: string;
+    label?: string;
+    heuristicLabel?: string;
+    cohesion?: number;
+    symbolCount?: number;
+}
+export interface AggregatedCluster {
+    id: string;
+    label: string;
+    heuristicLabel: string;
+    symbolCount: number;
+    cohesion: number;
+    subCommunities: number;
+}
+export interface ClusterAggregationOptions {
+    minSymbolCount?: number;
+    configuredIdPrefix?: string;
+}
+export declare function aggregateClusters(clusters: RawCluster[], options?: ClusterAggregationOptions): AggregatedCluster[];

package/dist/mcp/local/cluster-aggregation.js

@@ -0,0 +1,48 @@
+const DEFAULT_MIN_SYMBOL_COUNT = 5;
+const DEFAULT_CONFIGURED_ID_PREFIX = 'comm_cfg_';
+export function aggregateClusters(clusters, options = {}) {
+    const minSymbolCount = options.minSymbolCount ?? DEFAULT_MIN_SYMBOL_COUNT;
+    const configuredIdPrefix = options.configuredIdPrefix ?? DEFAULT_CONFIGURED_ID_PREFIX;
+    const groups = new Map();
+    for (const cluster of clusters) {
+        const label = cluster.heuristicLabel || cluster.label || 'Unknown';
+        const symbols = cluster.symbolCount || 0;
+        const cohesion = cluster.cohesion || 0;
+        const isConfigured = cluster.id.startsWith(configuredIdPrefix);
+        const existing = groups.get(label);
+        if (!existing) {
+            groups.set(label, {
+                ids: [cluster.id],
+                totalSymbols: symbols,
+                weightedCohesion: cohesion * symbols,
+                largest: cluster,
+                hasConfigured: isConfigured,
+            });
+            continue;
+        }
+        existing.ids.push(cluster.id);
+        existing.totalSymbols += symbols;
+        existing.weightedCohesion += cohesion * symbols;
+        existing.hasConfigured = existing.hasConfigured || isConfigured;
+        if (symbols > (existing.largest.symbolCount || 0)) {
+            existing.largest = cluster;
+        }
+    }
+    return Array.from(groups.entries())
+        .map(([label, g]) => ({
+        id: g.largest.id,
+        label,
+        heuristicLabel: label,
+        symbolCount: g.totalSymbols,
+        cohesion: g.totalSymbols > 0 ? g.weightedCohesion / g.totalSymbols : 0,
+        subCommunities: g.ids.length,
+        hasConfigured: g.hasConfigured,
+    }))
+        .filter((c) => c.symbolCount >= minSymbolCount || c.hasConfigured)
+        .sort((a, b) => {
+        if (a.symbolCount !== b.symbolCount)
+            return b.symbolCount - a.symbolCount;
+        return a.heuristicLabel.localeCompare(b.heuristicLabel);
+    })
+        .map(({ hasConfigured: _hasConfigured, ...rest }) => rest);
+}

package/dist/mcp/local/cluster-aggregation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mcp/local/cluster-aggregation.test.js

@@ -0,0 +1,22 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { aggregateClusters } from './cluster-aggregation.js';
+test('keeps auto tiny clusters filtered but includes empty configured modules', () => {
+    const out = aggregateClusters([
+        { id: 'comm_1', label: 'AutoTiny', heuristicLabel: 'AutoTiny', cohesion: 0.2, symbolCount: 1 },
+        { id: 'comm_cfg_battle', label: 'Battle', heuristicLabel: 'Battle', cohesion: 0, symbolCount: 0 },
+        { id: 'comm_2', label: 'Gameplay', heuristicLabel: 'Gameplay', cohesion: 0.8, symbolCount: 9 },
+    ], { minSymbolCount: 5, configuredIdPrefix: 'comm_cfg_' });
+    assert.ok(out.some((c) => c.heuristicLabel === 'Battle' && c.symbolCount === 0));
+    assert.ok(!out.some((c) => c.heuristicLabel === 'AutoTiny'));
+    assert.ok(out.some((c) => c.heuristicLabel === 'Gameplay' && c.symbolCount === 9));
+});
+test('aggregates same-name clusters with weighted cohesion', () => {
+    const out = aggregateClusters([
+        { id: 'comm_1', label: 'Gameplay', heuristicLabel: 'Gameplay', cohesion: 0.5, symbolCount: 4 },
+        { id: 'comm_2', label: 'Gameplay', heuristicLabel: 'Gameplay', cohesion: 1.0, symbolCount: 6 },
+    ], { minSymbolCount: 5, configuredIdPrefix: 'comm_cfg_' });
+    assert.equal(out.length, 1);
+    assert.equal(out[0].symbolCount, 10);
+    assert.equal(Math.round(out[0].cohesion * 100), 80);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veewo/gitnexus",
-  "version": "1.3.7",
+  "version": "1.3.8",
   "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",