@veewo/gitnexus 1.3.6 → 1.3.8

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.6",
+  "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",