gitnexus 1.6.8-rc.18 → 1.6.8-rc.19

package/dist/cli/help-i18n.js

@@ -27,6 +27,7 @@ const COMMAND_DESCRIPTION_KEYS = {
     impact: 'help.command.impact.description',
     cypher: 'help.command.cypher.description',
     'detect-changes': 'help.command.detectChanges.description',
+    check: 'help.command.check.description',
     'eval-server': 'help.command.evalServer.description',
     group: 'help.command.group.description',
     'group create': 'help.command.group.create.description',
@@ -117,6 +118,10 @@ const OPTION_DESCRIPTION_KEYS = {
     'detect-changes|-b, --base-ref <ref>': 'help.option.detectChanges.baseRef',
     'detect-changes|-r, --repo <name>': 'help.option.repo.target',
     'detect-changes|--branch <name>': 'help.option.branch',
+    'check|--cycles': 'help.option.check.cycles',
+    'check|--json': 'help.option.json',
+    'check|-r, --repo <name>': 'help.option.repo.target',
+    'check|--branch <name>': 'help.option.branch',
     'eval-server|-p, --port <port>': 'help.option.port',
     'eval-server|--host <host>': 'help.option.evalServer.host',
     'eval-server|--idle-timeout <seconds>': 'help.option.evalServer.idleTimeout',

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

@@ -126,6 +126,7 @@ export declare const en: {
     readonly 'help.command.impact.description': "Blast radius analysis: what breaks if you change a symbol";
     readonly 'help.command.cypher.description': "Execute raw Cypher query against the knowledge graph";
     readonly 'help.command.detectChanges.description': "Map git diff hunks to indexed symbols and affected execution flows";
+    readonly 'help.command.check.description': "Run structural checks against the indexed graph";
     readonly 'help.command.evalServer.description': "Start lightweight HTTP server for fast tool calls during evaluation";
     readonly 'help.command.group.description': "Manage repository groups for cross-index impact analysis";
     readonly 'help.command.group.create.description': "Create a new group with template group.yaml";
@@ -200,6 +201,7 @@ export declare const en: {
     readonly 'help.option.impact.summaryOnly': "Return counts and risk only, omit symbol list";
     readonly 'help.option.detectChanges.scope': "What to analyze: unstaged, staged, all, or compare";
     readonly 'help.option.detectChanges.baseRef': "Branch/commit for compare scope (e.g. main)";
+    readonly 'help.option.check.cycles': "Detect circular imports and fail when any are found";
     readonly 'help.option.evalServer.host': "Bind address (default: 127.0.0.1, use 0.0.0.0 to expose to all interfaces)";
     readonly 'help.option.evalServer.idleTimeout': "Auto-shutdown after N seconds idle (0 = disabled)";
     readonly 'help.option.group.create.force': "Overwrite existing group";

package/dist/cli/i18n/en.js

@@ -126,6 +126,7 @@ export const en = {
     'help.command.impact.description': 'Blast radius analysis: what breaks if you change a symbol',
     'help.command.cypher.description': 'Execute raw Cypher query against the knowledge graph',
     'help.command.detectChanges.description': 'Map git diff hunks to indexed symbols and affected execution flows',
+    'help.command.check.description': 'Run structural checks against the indexed graph',
     'help.command.evalServer.description': 'Start lightweight HTTP server for fast tool calls during evaluation',
     'help.command.group.description': 'Manage repository groups for cross-index impact analysis',
     'help.command.group.create.description': 'Create a new group with template group.yaml',
@@ -200,6 +201,7 @@ export const en = {
     'help.option.impact.summaryOnly': 'Return counts and risk only, omit symbol list',
     'help.option.detectChanges.scope': 'What to analyze: unstaged, staged, all, or compare',
     'help.option.detectChanges.baseRef': 'Branch/commit for compare scope (e.g. main)',
+    'help.option.check.cycles': 'Detect circular imports and fail when any are found',
     'help.option.evalServer.host': 'Bind address (default: 127.0.0.1, use 0.0.0.0 to expose to all interfaces)',
     'help.option.evalServer.idleTimeout': 'Auto-shutdown after N seconds idle (0 = disabled)',
     'help.option.group.create.force': 'Overwrite existing group',

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

@@ -127,6 +127,7 @@ export declare const cliResources: {
         readonly 'help.command.impact.description': "Blast radius analysis: what breaks if you change a symbol";
         readonly 'help.command.cypher.description': "Execute raw Cypher query against the knowledge graph";
         readonly 'help.command.detectChanges.description': "Map git diff hunks to indexed symbols and affected execution flows";
+        readonly 'help.command.check.description': "Run structural checks against the indexed graph";
         readonly 'help.command.evalServer.description': "Start lightweight HTTP server for fast tool calls during evaluation";
         readonly 'help.command.group.description': "Manage repository groups for cross-index impact analysis";
         readonly 'help.command.group.create.description': "Create a new group with template group.yaml";
@@ -201,6 +202,7 @@ export declare const cliResources: {
         readonly 'help.option.impact.summaryOnly': "Return counts and risk only, omit symbol list";
         readonly 'help.option.detectChanges.scope': "What to analyze: unstaged, staged, all, or compare";
         readonly 'help.option.detectChanges.baseRef': "Branch/commit for compare scope (e.g. main)";
+        readonly 'help.option.check.cycles': "Detect circular imports and fail when any are found";
         readonly 'help.option.evalServer.host': "Bind address (default: 127.0.0.1, use 0.0.0.0 to expose to all interfaces)";
         readonly 'help.option.evalServer.idleTimeout': "Auto-shutdown after N seconds idle (0 = disabled)";
         readonly 'help.option.group.create.force': "Overwrite existing group";
@@ -351,6 +353,7 @@ export declare const cliResources: {
         'help.command.impact.description': string;
         'help.command.cypher.description': string;
         'help.command.detectChanges.description': string;
+        'help.command.check.description': string;
         'help.command.evalServer.description': string;
         'help.command.group.description': string;
         'help.command.group.create.description': string;
@@ -425,6 +428,7 @@ export declare const cliResources: {
         'help.option.impact.summaryOnly': string;
         'help.option.detectChanges.scope': string;
         'help.option.detectChanges.baseRef': string;
+        'help.option.check.cycles': string;
         'help.option.evalServer.host': string;
         'help.option.evalServer.idleTimeout': string;
         'help.option.group.create.force': string;

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

@@ -126,6 +126,7 @@ export declare const zhCN: {
     'help.command.impact.description': string;
     'help.command.cypher.description': string;
     'help.command.detectChanges.description': string;
+    'help.command.check.description': string;
     'help.command.evalServer.description': string;
     'help.command.group.description': string;
     'help.command.group.create.description': string;
@@ -200,6 +201,7 @@ export declare const zhCN: {
     'help.option.impact.summaryOnly': string;
     'help.option.detectChanges.scope': string;
     'help.option.detectChanges.baseRef': string;
+    'help.option.check.cycles': string;
     'help.option.evalServer.host': string;
     'help.option.evalServer.idleTimeout': string;
     'help.option.group.create.force': string;

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

@@ -126,6 +126,7 @@ export const zhCN = {
     'help.command.impact.description': '影响面分析：修改符号会影响什么',
     'help.command.cypher.description': '对知识图谱执行原始 Cypher 查询',
     'help.command.detectChanges.description': '将 git diff hunk 映射到已索引符号和受影响执行流程',
+    'help.command.check.description': '对已索引图谱运行结构检查',
     'help.command.evalServer.description': '启动轻量 HTTP 服务器，用于评测期间的快速工具调用',
     'help.command.group.description': '管理仓库组，用于跨索引影响分析',
     'help.command.group.create.description': '使用模板 group.yaml 创建新仓库组',
@@ -200,6 +201,7 @@ export const zhCN = {
     'help.option.impact.summaryOnly': '仅返回计数和风险等级，省略符号列表',
     'help.option.detectChanges.scope': '分析范围：unstaged、staged、all 或 compare',
     'help.option.detectChanges.baseRef': 'compare 范围的分支/提交（例如 main）',
+    'help.option.check.cycles': '检测循环导入，并在发现循环时失败',
     'help.option.evalServer.host': '绑定地址（默认：127.0.0.1；用 0.0.0.0 暴露到所有网卡）',
     'help.option.evalServer.idleTimeout': '空闲 N 秒后自动关闭（0 = 禁用）',
     'help.option.group.create.force': '覆盖现有仓库组',

package/dist/cli/index.js

@@ -186,6 +186,14 @@ program
     .option('-r, --repo <name>', 'Target repository')
     .option('--branch <name>', 'Scope to a specific branch index (multi-branch repos)')
     .action(createLbugLazyAction(() => import('./tool.js'), 'detectChangesCommand'));
+program
+    .command('check')
+    .description('Run structural checks against the indexed graph')
+    .option('--cycles', 'Detect circular imports and fail when any are found')
+    .option('--json', 'Emit machine-readable JSON')
+    .option('-r, --repo <name>', 'Target repository')
+    .option('--branch <name>', 'Scope to a specific branch index (multi-branch repos)')
+    .action(createLbugLazyAction(() => import('./tool.js'), 'checkCommand'));
 // ─── Eval Server (persistent daemon for SWE-bench) ─────────────────
 program
     .command('eval-server')

package/dist/cli/tool.d.ts

@@ -1,7 +1,7 @@
 /**
  * Direct CLI Tool Commands
  *
- * Exposes GitNexus tools (query, context, impact, cypher) as direct CLI commands.
+ * Exposes GitNexus tools (query, context, impact, cypher, check) as direct CLI commands.
  * Bypasses MCP entirely — invokes LocalBackend directly for minimal overhead.
  *
  * Usage:
@@ -52,3 +52,9 @@ export declare function detectChangesCommand(options?: {
     repo?: string;
     branch?: string;
 }): Promise<void>;
+export declare function checkCommand(options?: {
+    cycles?: boolean;
+    json?: boolean;
+    repo?: string;
+    branch?: string;
+}): Promise<void>;

package/dist/cli/tool.js

@@ -1,7 +1,7 @@
 /**
  * Direct CLI Tool Commands
  *
- * Exposes GitNexus tools (query, context, impact, cypher) as direct CLI commands.
+ * Exposes GitNexus tools (query, context, impact, cypher, check) as direct CLI commands.
  * Bypasses MCP entirely — invokes LocalBackend directly for minimal overhead.
  *
  * Usage:
@@ -170,3 +170,38 @@ export async function detectChangesCommand(options) {
     });
     output(formatDetectChangesResult(result));
 }
+export async function checkCommand(options) {
+    if (!options?.cycles) {
+        process.stderr.write('Usage: gitnexus check --cycles [--json]\n');
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        const backend = await getBackend();
+        const result = await backend.callTool('check', {
+            cycles: true,
+            repo: options.repo,
+            branch: options.branch,
+        });
+        if (result?.error) {
+            output(result);
+            process.exitCode = 1;
+            return;
+        }
+        if (options.json) {
+            output(result);
+        }
+        else if (result.cycleCount === 0) {
+            output('No circular imports found.');
+        }
+        else {
+            output(result.cycles.map((cycle) => cycle.files.join(' -> ')).join('\n'));
+        }
+        if (result.cycleCount > 0)
+            process.exitCode = 1;
+    }
+    catch (error) {
+        output({ error: error instanceof Error ? error.message : String(error) });
+        process.exitCode = 1;
+    }
+}

package/dist/core/graph/import-cycles.d.ts

@@ -0,0 +1,10 @@
+interface ImportEdge {
+    source: string;
+    target: string;
+}
+/**
+ * Return one deterministic concrete cycle for every cyclic strongly connected
+ * component in the file import graph.
+ */
+export declare function findImportCycles(edges: ImportEdge[]): string[][];
+export {};

package/dist/core/graph/import-cycles.js

@@ -0,0 +1,103 @@
+function findCyclePath(component, adjacency) {
+    const allowed = new Set(component);
+    const start = component[0];
+    const parents = new Map([[start, null]]);
+    const queue = [start];
+    for (let index = 0; index < queue.length; index += 1) {
+        const node = queue[index];
+        for (const next of adjacency.get(node) ?? []) {
+            if (!allowed.has(next))
+                continue;
+            if (next === start) {
+                const path = [];
+                let cursor = node;
+                while (cursor !== null) {
+                    path.push(cursor);
+                    cursor = parents.get(cursor) ?? null;
+                }
+                path.reverse();
+                return [...path, start];
+            }
+            if (parents.has(next))
+                continue;
+            parents.set(next, node);
+            queue.push(next);
+        }
+    }
+    throw new Error('Invariant violation: no cycle found through SCC root.');
+}
+/**
+ * Return one deterministic concrete cycle for every cyclic strongly connected
+ * component in the file import graph.
+ */
+export function findImportCycles(edges) {
+    const adjacency = new Map();
+    for (const { source, target } of edges) {
+        if (!source || !target)
+            continue;
+        const targets = adjacency.get(source) ?? new Set();
+        targets.add(target);
+        adjacency.set(source, targets);
+        if (!adjacency.has(target))
+            adjacency.set(target, new Set());
+    }
+    const sortedAdjacency = new Map([...adjacency].map(([node, targets]) => [node, [...targets].sort()]));
+    const reverseAdjacency = new Map();
+    for (const node of sortedAdjacency.keys())
+        reverseAdjacency.set(node, []);
+    for (const [source, targets] of sortedAdjacency) {
+        for (const target of targets)
+            reverseAdjacency.get(target).push(source);
+    }
+    for (const sources of reverseAdjacency.values())
+        sources.sort();
+    const visited = new Set();
+    const finishOrder = [];
+    const components = [];
+    for (const start of [...sortedAdjacency.keys()].sort()) {
+        if (visited.has(start))
+            continue;
+        visited.add(start);
+        const stack = [{ node: start, nextIndex: 0 }];
+        while (stack.length > 0) {
+            const frame = stack[stack.length - 1];
+            const neighbors = sortedAdjacency.get(frame.node) ?? [];
+            if (frame.nextIndex < neighbors.length) {
+                const next = neighbors[frame.nextIndex++];
+                if (!visited.has(next)) {
+                    visited.add(next);
+                    stack.push({ node: next, nextIndex: 0 });
+                }
+            }
+            else {
+                finishOrder.push(frame.node);
+                stack.pop();
+            }
+        }
+    }
+    visited.clear();
+    for (let index = finishOrder.length - 1; index >= 0; index -= 1) {
+        const start = finishOrder[index];
+        if (visited.has(start))
+            continue;
+        const component = [];
+        const stack = [start];
+        visited.add(start);
+        while (stack.length > 0) {
+            const node = stack.pop();
+            component.push(node);
+            for (const next of reverseAdjacency.get(node) ?? []) {
+                if (visited.has(next))
+                    continue;
+                visited.add(next);
+                stack.push(next);
+            }
+        }
+        component.sort();
+        components.push(component);
+    }
+    return components
+        .filter((component) => component.length > 1 || (sortedAdjacency.get(component[0]) ?? []).includes(component[0]))
+        .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+        .map((component) => findCyclePath(component, sortedAdjacency));
+}

package/dist/mcp/local/local-backend.d.ts

@@ -337,6 +337,8 @@ export declare class LocalBackend {
      */
     private maybeWarnSiblingDrift;
     callTool(method: string, params: any): Promise<any>;
+    /** Check repository graph invariants that are suitable for CI gating. */
+    private check;
     /**
      * Query tool — process-grouped search.
      *

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

@@ -28,6 +28,7 @@ import { PhaseTimer } from '../../core/search/phase-timer.js';
 import { checkStalenessAsync, checkCwdMatch } from '../../core/git-staleness.js';
 import { logger } from '../../core/logger.js';
 import { LIST_REPOS_DEFAULT_LIMIT, LIST_REPOS_MAX_LIMIT } from '../tools.js';
+import { findImportCycles } from '../../core/graph/import-cycles.js';
 // AI context generation is CLI-only (gitnexus analyze)
 // import { generateAIContextFiles } from '../../cli/ai-context.js';
 /**
@@ -1037,6 +1038,8 @@ export class LocalBackend {
                 return this.impact(repo, params);
             case 'detect_changes':
                 return this.detectChanges(repo, params);
+            case 'check':
+                return this.check(repo, params);
             case 'rename':
                 return this.rename(repo, params);
             // Legacy aliases for backwards compatibility
@@ -1059,6 +1062,37 @@ export class LocalBackend {
         }
     }
     // ─── Tool Implementations ────────────────────────────────────────
+    /** Check repository graph invariants that are suitable for CI gating. */
+    async check(repo, params) {
+        if (params?.cycles === false) {
+            return { error: 'No checks selected. Set "cycles" to true.' };
+        }
+        await this.ensureInitialized(repo);
+        const rowLimit = 100_001;
+        const rows = await executeParameterized(repo.lbugPath, `MATCH (source:File)-[r:CodeRelation]->(target:File)
+       WHERE r.type = 'IMPORTS'
+         AND (r.reason IS NULL OR (
+           r.reason <> 'swift-scope: implicit module visibility'
+           AND r.reason <> 'markdown-link'
+         ))
+       RETURN source.filePath AS source, target.filePath AS target
+       LIMIT ${rowLimit}`, {});
+        if (rows.length === rowLimit) {
+            return {
+                error: `Import graph exceeds the ${rowLimit - 1} edge safety limit.`,
+                truncated: true,
+            };
+        }
+        const cycles = findImportCycles(rows.map((row) => ({
+            source: String(row.source ?? row[0] ?? ''),
+            target: String(row.target ?? row[1] ?? ''),
+        })));
+        return {
+            status: cycles.length === 0 ? 'clean' : 'cycles_found',
+            cycleCount: cycles.length,
+            cycles: cycles.map((files) => ({ files })),
+        };
+    }
     /**
      * Query tool — process-grouped search.
      *

package/dist/mcp/tools.js

@@ -277,6 +277,29 @@ Returns: changed symbols, affected processes, and a risk summary.`,
             required: [],
         },
     },
+    {
+        name: 'check',
+        description: `Run read-only structural checks against the indexed graph.
+
+Currently detects directed cycles between File nodes connected by IMPORTS edges.
+Returns deterministic cycle paths and a cycle count suitable for CI automation.`,
+        annotations: READ_ONLY_TOOL_ANNOTATIONS,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                cycles: {
+                    type: 'boolean',
+                    description: 'Detect circular file imports (default: true).',
+                    default: true,
+                },
+                repo: {
+                    type: 'string',
+                    description: 'Repository name or path. Omit if only one repo is indexed.',
+                },
+            },
+            required: [],
+        },
+    },
     {
         name: 'rename',
         description: `Multi-file coordinated rename using the knowledge graph + text search.
@@ -572,6 +595,7 @@ const BRANCH_SCOPED_TOOLS = new Set([
     'cypher',
     'context',
     'detect_changes',
+    'check',
     'impact',
     'rename',
     'route_map',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.8-rc.18",
+  "version": "1.6.8-rc.19",
   "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",