@veewo/gitnexus 1.3.4

package/dist/benchmark/runner.js

@@ -0,0 +1,302 @@
+import path from 'node:path';
+import { runAnalyze, parseAnalyzeSummary } from './analyze-runner.js';
+import { evaluateGates, computePR, computeF1 } from './scoring.js';
+import { buildFailureTriage } from './evaluators.js';
+import { writeReports } from './report.js';
+import { createToolRunner } from './tool-runner.js';
+export function resolveBenchmarkRepoName(options) {
+    return options.repo || options.repoAlias || (options.targetPath ? path.basename(path.resolve(options.targetPath)) : undefined);
+}
+function normalize(s) {
+    return s.trim().toLowerCase();
+}
+function expectedName(uid) {
+    const last = uid.split(':').pop() || uid;
+    return normalize(last);
+}
+function extractHits(result) {
+    const uids = new Set();
+    const names = new Set();
+    const addUid = (uid) => {
+        if (typeof uid === 'string' && uid.trim()) {
+            uids.add(uid.trim());
+        }
+    };
+    const addName = (name) => {
+        if (typeof name === 'string' && name.trim()) {
+            names.add(name.trim());
+        }
+    };
+    for (const sym of result?.process_symbols || []) {
+        addUid(sym?.id);
+        addName(sym?.name);
+    }
+    for (const def of result?.definitions || []) {
+        addUid(def?.id);
+        addName(def?.name);
+    }
+    addUid(result?.symbol?.uid);
+    addName(result?.symbol?.name);
+    addUid(result?.target?.id);
+    addName(result?.target?.name);
+    for (const depthRows of Object.values(result?.byDepth || {})) {
+        if (!Array.isArray(depthRows))
+            continue;
+        for (const row of depthRows) {
+            addUid(row?.id);
+            addName(row?.name);
+        }
+    }
+    for (const candidate of result?.candidates || []) {
+        addUid(candidate?.uid);
+        addName(candidate?.name);
+    }
+    return { uids: [...uids], names: [...names] };
+}
+export function hasRequiredHitFuzzy(expectedUid, hitUids, hitNames) {
+    const expectedNorm = normalize(expectedUid);
+    const expectedLooksLikeUid = expectedUid.includes(':');
+    if (expectedLooksLikeUid) {
+        for (const uid of hitUids) {
+            const n = normalize(uid);
+            if (n === expectedNorm || n.endsWith(expectedNorm) || expectedNorm.endsWith(n)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    const expectedSym = expectedName(expectedUid);
+    for (const uid of hitUids) {
+        const n = normalize(uid);
+        if (expectedSym && n.includes(expectedSym)) {
+            return true;
+        }
+    }
+    for (const name of hitNames) {
+        const n = normalize(name);
+        if (n === expectedSym || n.includes(expectedSym) || expectedSym.includes(n)) {
+            return true;
+        }
+    }
+    return false;
+}
+export function hasForbiddenUidHitStrict(forbiddenUid, hitUids) {
+    const forbiddenNorm = normalize(forbiddenUid);
+    return hitUids.some((uid) => normalize(uid) === forbiddenNorm);
+}
+function mapToolInput(task, repo) {
+    const input = { ...(task.input || {}) };
+    if (repo) {
+        input.repo = repo;
+    }
+    if (task.tool === 'query') {
+        if (!('query' in input) && typeof input.search_query === 'string') {
+            input.query = input.search_query;
+        }
+    }
+    if (task.tool === 'impact' && !('direction' in input)) {
+        input.direction = 'upstream';
+    }
+    return input;
+}
+function resultCount(tool, result) {
+    if (tool === 'query') {
+        return (result?.process_symbols?.length || 0) + (result?.definitions?.length || 0);
+    }
+    if (tool === 'context') {
+        const incoming = Object.values(result?.incoming || {}).flat().length;
+        const outgoing = Object.values(result?.outgoing || {}).flat().length;
+        return incoming + outgoing + (result?.processes?.length || 0) + (result?.symbol ? 1 : 0);
+    }
+    if (tool === 'impact') {
+        return Number(result?.impactedCount || 0) + (result?.target ? 1 : 0);
+    }
+    return 0;
+}
+async function evaluateTask(index, task, runTool, repo) {
+    const failures = [];
+    try {
+        const params = mapToolInput(task, repo);
+        const result = await runTool(task.tool, params);
+        if (result?.error) {
+            return {
+                smokePass: false,
+                tool: task.tool,
+                hits: [],
+                names: [],
+                truePositive: 0,
+                predicted: 0,
+                gold: task.must_hit_uids.length,
+                failures: [{ kind: 'tool-error', taskIndex: index, detail: String(result.error) }],
+            };
+        }
+        if (result?.status === 'ambiguous') {
+            failures.push({ kind: 'ambiguous-name-wrong-hit', taskIndex: index, detail: result?.message });
+        }
+        const hits = extractHits(result);
+        const predicted = hits.uids.length;
+        const gold = task.must_hit_uids.length;
+        let truePositive = 0;
+        for (const expected of task.must_hit_uids) {
+            if (hasRequiredHitFuzzy(expected, hits.uids, hits.names)) {
+                truePositive += 1;
+            }
+            else {
+                failures.push({ kind: 'missing-required-hit', taskIndex: index, detail: expected });
+            }
+        }
+        for (const forbidden of task.must_not_hit_uids) {
+            if (hasForbiddenUidHitStrict(forbidden, hits.uids)) {
+                failures.push({ kind: 'forbidden-hit-present', taskIndex: index, detail: forbidden });
+            }
+        }
+        const count = resultCount(task.tool, result);
+        if (typeof task.min_result_count === 'number' && count < task.min_result_count) {
+            failures.push({ kind: 'insufficient-result-count', taskIndex: index, detail: `${count} < ${task.min_result_count}` });
+        }
+        if (task.tool === 'context') {
+            const refs = Object.values(result?.incoming || {}).flat().length + Object.values(result?.outgoing || {}).flat().length;
+            if (refs === 0) {
+                failures.push({ kind: 'context-empty-refs', taskIndex: index });
+            }
+        }
+        if (task.tool === 'impact' && Number(result?.impactedCount || 0) === 0) {
+            failures.push({ kind: 'impact-downstream-zero', taskIndex: index });
+        }
+        return {
+            smokePass: !result?.error,
+            tool: task.tool,
+            hits: hits.uids,
+            names: hits.names,
+            truePositive,
+            predicted,
+            gold,
+            failures,
+        };
+    }
+    catch (error) {
+        return {
+            smokePass: false,
+            tool: task.tool,
+            hits: [],
+            names: [],
+            truePositive: 0,
+            predicted: 0,
+            gold: task.must_hit_uids.length,
+            failures: [{ kind: 'tool-execution-error', taskIndex: index, detail: String(error?.message || error) }],
+        };
+    }
+}
+export async function runBenchmark(ds, options) {
+    const reportDir = path.resolve(options.reportDir || '.gitnexus/benchmark');
+    const repo = resolveBenchmarkRepoName(options);
+    let analyzeSummary;
+    if (!options.skipAnalyze) {
+        if (!options.targetPath) {
+            throw new Error('targetPath is required unless skipAnalyze is true');
+        }
+        const analyze = await runAnalyze(path.resolve(options.targetPath), {
+            extensions: options.extensions,
+            repoAlias: options.repoAlias,
+            scopeManifest: options.scopeManifest,
+            scopePrefix: options.scopePrefix,
+        });
+        analyzeSummary = parseAnalyzeSummary(`${analyze.stdout}\n${analyze.stderr}`);
+    }
+    const limitedTasks = ds.tasks.slice(0, options.profile.maxTasks);
+    const limitedSymbols = ds.symbols.slice(0, options.profile.maxSymbols);
+    const toolRunner = await createToolRunner();
+    const failures = [];
+    let queryTP = 0;
+    let queryPred = 0;
+    let queryGold = 0;
+    let ciTP = 0;
+    let ciPred = 0;
+    let ciGold = 0;
+    let smokePassCount = 0;
+    const runTool = async (tool, params) => {
+        if (tool === 'query') {
+            return toolRunner.query(params);
+        }
+        if (tool === 'context') {
+            return toolRunner.context(params);
+        }
+        return toolRunner.impact(params);
+    };
+    try {
+        for (let i = 0; i < limitedTasks.length; i += 1) {
+            const task = limitedTasks[i];
+            const evalResult = await evaluateTask(i, task, runTool, repo);
+            if (evalResult.smokePass) {
+                smokePassCount += 1;
+            }
+            failures.push(...evalResult.failures);
+            if (task.tool === 'query') {
+                queryTP += evalResult.truePositive;
+                queryPred += evalResult.predicted;
+                queryGold += evalResult.gold;
+            }
+            else {
+                ciTP += evalResult.truePositive;
+                ciPred += evalResult.predicted;
+                ciGold += evalResult.gold;
+            }
+        }
+    }
+    finally {
+        await toolRunner.close();
+    }
+    if (limitedSymbols.length === 0) {
+        failures.push({ kind: 'dataset-empty-symbols' });
+    }
+    if (ds.relations.length === 0) {
+        failures.push({ kind: 'dataset-empty-relations' });
+    }
+    const queryPR = queryGold > 0 || queryPred > 0 ? computePR(queryTP, queryPred, queryGold) : { precision: 1, recall: 1 };
+    const ciPR = ciGold > 0 || ciPred > 0 ? computePR(ciTP, ciPred, ciGold) : { precision: 1, recall: 1 };
+    const metrics = {
+        queryPrecision: queryPR.precision,
+        queryRecall: queryPR.recall,
+        contextImpactF1: computeF1(ciPR.precision, ciPR.recall),
+        smokePassRate: limitedTasks.length === 0 ? 1 : smokePassCount / limitedTasks.length,
+        perfRegressionPct: 0,
+    };
+    const gateResult = evaluateGates(metrics, ds.thresholds);
+    const triage = buildFailureTriage(failures);
+    const jsonReport = {
+        generatedAt: new Date().toISOString(),
+        repo,
+        profile: options.profile,
+        metrics,
+        thresholds: ds.thresholds,
+        gate: gateResult,
+        analyze: analyzeSummary,
+        triage,
+        failures,
+        stats: {
+            symbols: limitedSymbols.length,
+            relations: ds.relations.length,
+            tasks: limitedTasks.length,
+        },
+    };
+    const markdown = [
+        '# Unity Benchmark Summary',
+        '',
+        `- Pass: ${gateResult.pass ? 'YES' : 'NO'}`,
+        `- Query Precision: ${metrics.queryPrecision.toFixed(3)}`,
+        `- Query Recall: ${metrics.queryRecall.toFixed(3)}`,
+        `- Context/Impact F1: ${metrics.contextImpactF1.toFixed(3)}`,
+        `- Smoke Pass Rate: ${metrics.smokePassRate.toFixed(3)}`,
+        `- Perf Regression: ${metrics.perfRegressionPct.toFixed(2)}%`,
+        gateResult.failures.length > 0 ? `- Gate Failures: ${gateResult.failures.join(', ')}` : '- Gate Failures: none',
+    ].join('\n');
+    await writeReports(reportDir, jsonReport, markdown);
+    return {
+        pass: gateResult.pass,
+        failures: gateResult.failures,
+        metrics,
+        triage,
+        analyze: analyzeSummary,
+        reportDir,
+    };
+}

package/dist/benchmark/runner.test.d.ts

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

package/dist/benchmark/runner.test.js

@@ -0,0 +1,50 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { hasForbiddenUidHitStrict, hasRequiredHitFuzzy, resolveBenchmarkRepoName } from './runner.js';
+test('resolveBenchmarkRepoName prefers explicit repo', () => {
+    const resolved = resolveBenchmarkRepoName({
+        repo: 'my-repo',
+        repoAlias: 'alias-repo',
+        targetPath: '/tmp/source',
+    });
+    assert.equal(resolved, 'my-repo');
+});
+test('resolveBenchmarkRepoName falls back to repo alias', () => {
+    const resolved = resolveBenchmarkRepoName({
+        repoAlias: 'neonspark-v1-subset',
+        targetPath: '/tmp/source',
+    });
+    assert.equal(resolved, 'neonspark-v1-subset');
+});
+test('resolveBenchmarkRepoName uses target basename when no repo input exists', () => {
+    const resolved = resolveBenchmarkRepoName({
+        targetPath: '/Volumes/Shuttle/unity-projects/neonspark',
+    });
+    assert.equal(resolved, 'neonspark');
+});
+test('hasRequiredHitFuzzy does not treat wrong same-name uid as a required hit for uid expectations', () => {
+    const expected = 'Class:Assets/NEON/Code/Game/LootSystem/LootManager.cs:LootManager';
+    const hitUids = ['Class:Assets/NEON/Code/Game/LootSystem/LootDropRecorder.cs:LootManager'];
+    const matched = hasRequiredHitFuzzy(expected, hitUids, ['LootManager']);
+    assert.equal(matched, false);
+});
+test('hasRequiredHitFuzzy accepts correct uid for required hit', () => {
+    const expected = 'Class:Assets/NEON/Code/Game/LootSystem/LootManager.cs:LootManager';
+    const hitUids = ['class:assets/neon/code/game/lootsystem/lootmanager.cs:lootmanager'];
+    assert.equal(hasRequiredHitFuzzy(expected, hitUids, []), true);
+});
+test('hasRequiredHitFuzzy keeps legacy name fallback for non-uid expectations', () => {
+    const expected = 'LootManager';
+    const matched = hasRequiredHitFuzzy(expected, [], ['LootManager']);
+    assert.equal(matched, true);
+});
+test('hasForbiddenUidHitStrict ignores same-name symbol with different uid', () => {
+    const forbidden = 'Class:Assets/NEON/Code/Game/LootSystem/LootManager.cs:LootManager';
+    const hitUids = ['Class:Assets/NEON/Code/Game/LootSystem/LootDropRecorder.cs:LootManager'];
+    assert.equal(hasForbiddenUidHitStrict(forbidden, hitUids), false);
+});
+test('hasForbiddenUidHitStrict matches only exact normalized uid', () => {
+    const forbidden = 'Class:Assets/NEON/Code/Game/LootSystem/LootManager.cs:LootManager';
+    const hitUids = ['  class:assets/neon/code/game/lootsystem/lootmanager.cs:lootmanager  '];
+    assert.equal(hasForbiddenUidHitStrict(forbidden, hitUids), true);
+});

package/dist/benchmark/scoring.d.ts

@@ -0,0 +1,16 @@
+import type { Thresholds } from './types.js';
+export declare function computePR(truePositive: number, predicted: number, gold: number): {
+    precision: number;
+    recall: number;
+};
+export declare function computeF1(precision: number, recall: number): number;
+export declare function evaluateGates(metrics: {
+    queryPrecision: number;
+    queryRecall: number;
+    contextImpactF1: number;
+    smokePassRate: number;
+    perfRegressionPct: number;
+}, thresholds: Thresholds): {
+    pass: boolean;
+    failures: string[];
+};

package/dist/benchmark/scoring.js

@@ -0,0 +1,27 @@
+export function computePR(truePositive, predicted, gold) {
+    const precision = predicted === 0 ? 0 : truePositive / predicted;
+    const recall = gold === 0 ? 0 : truePositive / gold;
+    return { precision, recall };
+}
+export function computeF1(precision, recall) {
+    return precision + recall === 0 ? 0 : (2 * precision * recall) / (precision + recall);
+}
+export function evaluateGates(metrics, thresholds) {
+    const failures = [];
+    if (metrics.queryPrecision < thresholds.query.precisionMin) {
+        failures.push('query.precision');
+    }
+    if (metrics.queryRecall < thresholds.query.recallMin) {
+        failures.push('query.recall');
+    }
+    if (metrics.contextImpactF1 < thresholds.contextImpact.f1Min) {
+        failures.push('contextImpact.f1');
+    }
+    if (metrics.smokePassRate < thresholds.smoke.passRateMin) {
+        failures.push('smoke.passRate');
+    }
+    if (metrics.perfRegressionPct > thresholds.performance.analyzeTimeRegressionMaxPct) {
+        failures.push('performance.analyzeTimeRegression');
+    }
+    return { pass: failures.length === 0, failures };
+}

package/dist/benchmark/scoring.test.d.ts

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

package/dist/benchmark/scoring.test.js

@@ -0,0 +1,24 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { computePR, evaluateGates } from './scoring.js';
+test('computePR returns precision and recall', () => {
+    const pr = computePR(9, 10, 12);
+    assert.equal(pr.precision.toFixed(2), '0.90');
+    assert.equal(pr.recall.toFixed(2), '0.75');
+});
+test('evaluateGates fails when one hard threshold fails', () => {
+    const result = evaluateGates({
+        queryPrecision: 0.9,
+        queryRecall: 0.84,
+        contextImpactF1: 0.82,
+        smokePassRate: 1,
+        perfRegressionPct: 10,
+    }, {
+        query: { precisionMin: 0.9, recallMin: 0.85 },
+        contextImpact: { f1Min: 0.8 },
+        smoke: { passRateMin: 1 },
+        performance: { analyzeTimeRegressionMaxPct: 15 },
+    });
+    assert.equal(result.pass, false);
+    assert.ok(result.failures.includes('query.recall'));
+});

package/dist/benchmark/tool-runner.d.ts

@@ -0,0 +1,6 @@
+export declare function createToolRunner(): Promise<{
+    query: (params: any) => Promise<any>;
+    context: (params: any) => Promise<any>;
+    impact: (params: any) => Promise<any>;
+    close: () => Promise<void>;
+}>;

package/dist/benchmark/tool-runner.js

@@ -0,0 +1,17 @@
+import { closeKuzu } from '../mcp/core/kuzu-adapter.js';
+import { LocalBackend } from '../mcp/local/local-backend.js';
+export async function createToolRunner() {
+    const backend = new LocalBackend();
+    const ok = await backend.init();
+    if (!ok) {
+        throw new Error('No indexed repositories found. Run analyze first.');
+    }
+    return {
+        query: (params) => backend.callTool('query', params),
+        context: (params) => backend.callTool('context', params),
+        impact: (params) => backend.callTool('impact', params),
+        close: async () => {
+            await closeKuzu();
+        },
+    };
+}

package/dist/benchmark/types.d.ts

@@ -0,0 +1,36 @@
+export interface Thresholds {
+    query: {
+        precisionMin: number;
+        recallMin: number;
+    };
+    contextImpact: {
+        f1Min: number;
+    };
+    smoke: {
+        passRateMin: number;
+    };
+    performance: {
+        analyzeTimeRegressionMaxPct: number;
+    };
+}
+export interface SymbolCase {
+    symbol_uid: string;
+    file_path: string;
+    symbol_name: string;
+    symbol_type: string;
+    start_line: number;
+    end_line: number;
+}
+export interface RelationCase {
+    src_uid: string;
+    edge_type: string;
+    dst_uid: string;
+    must_exist: boolean;
+}
+export interface TaskCase {
+    tool: 'query' | 'context' | 'impact';
+    input: Record<string, unknown>;
+    must_hit_uids: string[];
+    must_not_hit_uids: string[];
+    min_result_count?: number;
+}

package/dist/benchmark/types.js

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

package/dist/cli/ai-context.d.ts

@@ -0,0 +1,22 @@
+/**
+ * AI Context Generator
+ *
+ * Creates AGENTS.md and CLAUDE.md with full inline GitNexus context.
+ * AGENTS.md is the standard read by Cursor, Windsurf, OpenCode, Cline, etc.
+ * CLAUDE.md is for Claude Code which only reads that file.
+ */
+interface RepoStats {
+    files?: number;
+    nodes?: number;
+    edges?: number;
+    communities?: number;
+    clusters?: number;
+    processes?: number;
+}
+/**
+ * Generate AI context files after indexing
+ */
+export declare function generateAIContextFiles(repoPath: string, _storagePath: string, projectName: string, stats: RepoStats): Promise<{
+    files: string[];
+}>;
+export {};