gitnexus 1.5.3 → 1.6.0

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

@@ -7,13 +7,15 @@
  */
 import fs from 'fs/promises';
 import path from 'path';
-import { initLbug, executeQuery, executeParameterized, closeLbug, isLbugReady, isWriteQuery, } from '../core/lbug-adapter.js';
+import { initLbug, executeQuery, executeParameterized, closeLbug, isLbugReady, isWriteQuery, } from '../../core/lbug/pool-adapter.js';
 export { isWriteQuery };
 // Embedding imports are lazy (dynamic import) to avoid loading onnxruntime-node
 // at MCP server startup — crashes on unsupported Node ABI versions (#89)
 // git utilities available if needed
 // import { isGitRepo, getCurrentCommit, getGitRoot } from '../../storage/git.js';
+import { parseDiffHunks } from '../../storage/git.js';
 import { listRegisteredRepos, cleanupOldKuzuFiles, } from '../../storage/repo-manager.js';
+import { GroupService } from '../../core/group/service.js';
 // AI context generation is CLI-only (gitnexus analyze)
 // import { generateAIContextFiles } from '../../cli/ai-context.js';
 /**
@@ -78,7 +80,9 @@ export const VALID_RELATION_TYPES = new Set([
     'IMPLEMENTS',
     'HAS_METHOD',
     'HAS_PROPERTY',
-    'OVERRIDES',
+    'METHOD_OVERRIDES',
+    'OVERRIDES', // Legacy alias — dual-read for pre-rename indexes
+    'METHOD_IMPLEMENTS',
     'ACCESSES',
     'HANDLES_ROUTE',
     'FETCHES',
@@ -98,7 +102,8 @@ export const VALID_RELATION_TYPES = new Set([
  *   CALLS / IMPORTS  – direct, strongly-typed references → 0.9
  *   EXTENDS          – class hierarchy, statically verifiable → 0.85
  *   IMPLEMENTS       – interface contract, statically verifiable → 0.85
- *   OVERRIDES        – method override, statically verifiable → 0.85
+ *   METHOD_OVERRIDES  – method override, statically verifiable → 0.85
+ *   METHOD_IMPLEMENTS – interface method implementation, statically verifiable → 0.85
  *   HAS_METHOD       – structural containment → 0.95
  *   HAS_PROPERTY     – structural containment → 0.95
  *   ACCESSES         – field read/write, may be indirect → 0.8
@@ -110,7 +115,8 @@ export const IMPACT_RELATION_CONFIDENCE = {
     IMPORTS: 0.9,
     EXTENDS: 0.85,
     IMPLEMENTS: 0.85,
-    OVERRIDES: 0.85,
+    METHOD_OVERRIDES: 0.85,
+    METHOD_IMPLEMENTS: 0.85,
     HAS_METHOD: 0.95,
     HAS_PROPERTY: 0.95,
     ACCESSES: 0.8,
@@ -132,6 +138,26 @@ export class LocalBackend {
     initializedRepos = new Set();
     reinitPromises = new Map();
     lastStalenessCheck = new Map();
+    groupToolSvc = null;
+    /**
+     * Cross-repo group tools (CLI). Shares logic with MCP `group_*` handlers.
+     */
+    getGroupService() {
+        if (!this.groupToolSvc) {
+            const port = {
+                resolveRepo: (p) => this.resolveRepo(p),
+                impact: (r, p) => this.impact(r, p),
+                query: (r, p) => this.query(r, p),
+                impactByUid: (id, uid, d, o) => this.impactByUid(id, uid, d, o),
+            };
+            this.groupToolSvc = new GroupService(port);
+        }
+        return this.groupToolSvc;
+    }
+    /** Close all pooled LadybugDB connections (CLI one-shot; optional for long-lived MCP). */
+    async dispose() {
+        await closeLbug();
+    }
     // ─── Initialization ──────────────────────────────────────────────
     /**
      * Initialize from the global registry.
@@ -364,6 +390,9 @@ export class LocalBackend {
         if (method === 'list_repos') {
             return this.listRepos();
         }
+        if (method.startsWith('group_')) {
+            return this.handleGroupTool(method, params || {});
+        }
         // Resolve repo from optional param (re-reads registry on miss)
         const repo = await this.resolveRepo(params?.repo);
         switch (method) {
@@ -974,7 +1003,7 @@ export class LocalBackend {
         // Categorized incoming refs
         const incomingRows = await executeParameterized(repo.id, `
       MATCH (caller)-[r:CodeRelation]->(n {id: $symId})
-      WHERE r.type IN ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS', 'HAS_METHOD', 'HAS_PROPERTY', 'OVERRIDES', 'ACCESSES']
+      WHERE r.type IN ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS', 'HAS_METHOD', 'HAS_PROPERTY', 'METHOD_OVERRIDES', 'OVERRIDES', 'METHOD_IMPLEMENTS', 'ACCESSES']
       RETURN r.type AS relType, caller.id AS uid, caller.name AS name, caller.filePath AS filePath, labels(caller)[0] AS kind
       LIMIT 30
     `, { symId });
@@ -1045,7 +1074,7 @@ export class LocalBackend {
         // Categorized outgoing refs
         const outgoingRows = await executeParameterized(repo.id, `
       MATCH (n {id: $symId})-[r:CodeRelation]->(target)
-      WHERE r.type IN ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS', 'HAS_METHOD', 'HAS_PROPERTY', 'OVERRIDES', 'ACCESSES']
+      WHERE r.type IN ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS', 'HAS_METHOD', 'HAS_PROPERTY', 'METHOD_OVERRIDES', 'OVERRIDES', 'METHOD_IMPLEMENTS', 'ACCESSES']
       RETURN r.type AS relType, target.id AS uid, target.name AS name, target.filePath AS filePath, labels(target)[0] AS kind
       LIMIT 30
     `, { symId });
@@ -1077,16 +1106,50 @@ export class LocalBackend {
             }
             return cats;
         };
+        // Method/Function/Constructor enrichment: fetch method-specific properties
+        const symKind = isClassLike ? resolvedLabel || 'Class' : sym.type || sym[2];
+        const isMethodLike = symKind === 'Method' || symKind === 'Function' || symKind === 'Constructor';
+        let methodMetadata;
+        if (isMethodLike) {
+            try {
+                const metaRows = await executeParameterized(repo.id, `
+          MATCH (n {id: $symId})
+          RETURN n.visibility AS visibility, n.isStatic AS isStatic, n.isAbstract AS isAbstract,
+                 n.isFinal AS isFinal, n.isVirtual AS isVirtual, n.isOverride AS isOverride,
+                 n.isAsync AS isAsync, n.isPartial AS isPartial, n.returnType AS returnType,
+                 n.parameterCount AS parameterCount, n.isVariadic AS isVariadic,
+                 n.requiredParameterCount AS requiredParameterCount,
+                 n.parameterTypes AS parameterTypes, n.annotations AS annotations
+          LIMIT 1
+        `, { symId });
+                if (metaRows.length > 0) {
+                    const row = metaRows[0];
+                    const meta = {};
+                    // Only include defined properties to distinguish "not applicable" from "not enriched"
+                    for (const key of Object.keys(row)) {
+                        const val = row[key];
+                        if (val !== null && val !== undefined)
+                            meta[key] = val;
+                    }
+                    if (Object.keys(meta).length > 0)
+                        methodMetadata = meta;
+                }
+            }
+            catch {
+                /* method metadata unavailable — omit silently */
+            }
+        }
         return {
             status: 'found',
             symbol: {
                 uid: sym.id || sym[0],
                 name: sym.name || sym[1],
-                kind: isClassLike ? resolvedLabel || 'Class' : sym.type || sym[2],
+                kind: symKind,
                 filePath: sym.filePath || sym[3],
                 startLine: sym.startLine || sym[4],
                 endLine: sym.endLine || sym[5],
                 ...(include_content && (sym.content || sym[6]) ? { content: sym.content || sym[6] } : {}),
+                ...(methodMetadata ? { methodMetadata } : {}),
             },
             incoming: categorize(incomingRows),
             outgoing: categorize(outgoingRows),
@@ -1197,33 +1260,30 @@ export class LocalBackend {
         let diffArgs;
         switch (scope) {
             case 'staged':
-                diffArgs = ['diff', '--staged', '--name-only'];
+                diffArgs = ['diff', '--staged', '-U0'];
                 break;
             case 'all':
-                diffArgs = ['diff', 'HEAD', '--name-only'];
+                diffArgs = ['diff', 'HEAD', '-U0'];
                 break;
             case 'compare':
                 if (!params.base_ref)
                     return { error: 'base_ref is required for "compare" scope' };
-                diffArgs = ['diff', params.base_ref, '--name-only'];
+                diffArgs = ['diff', params.base_ref, '-U0'];
                 break;
             case 'unstaged':
             default:
-                diffArgs = ['diff', '--name-only'];
+                diffArgs = ['diff', '-U0'];
                 break;
         }
-        let changedFiles;
+        let diffOutput;
         try {
-            const output = execFileSync('git', diffArgs, { cwd: repo.repoPath, encoding: 'utf-8' });
-            changedFiles = output
-                .trim()
-                .split('\n')
-                .filter((f) => f.length > 0);
+            diffOutput = execFileSync('git', diffArgs, { cwd: repo.repoPath, encoding: 'utf-8' });
         }
         catch (err) {
             return { error: `Git diff failed: ${err.message}` };
         }
-        if (changedFiles.length === 0) {
+        const fileDiffs = parseDiffHunks(diffOutput);
+        if (fileDiffs.length === 0) {
             return {
                 summary: {
                     changed_count: 0,
@@ -1235,23 +1295,36 @@ export class LocalBackend {
                 affected_processes: [],
             };
         }
-        // Map changed files to indexed symbols
+        // Map diff hunks to indexed symbols via range overlap
         const changedSymbols = [];
-        for (const file of changedFiles) {
-            const normalizedFile = file.replace(/\\/g, '/');
+        for (const fileDiff of fileDiffs) {
+            if (fileDiff.hunks.length === 0)
+                continue;
+            // Build range overlap conditions for all hunks in this file
+            const overlapConditions = fileDiff.hunks
+                .map((_, i) => `(n.startLine <= $hunkEnd${i} AND n.endLine >= $hunkStart${i})`)
+                .join(' OR ');
+            const queryParams = { filePath: fileDiff.filePath };
+            fileDiff.hunks.forEach((hunk, i) => {
+                queryParams[`hunkStart${i}`] = hunk.startLine;
+                queryParams[`hunkEnd${i}`] = hunk.endLine;
+            });
+            const symbolQuery = `
+        MATCH (n) WHERE n.filePath ENDS WITH $filePath
+          AND n.startLine IS NOT NULL AND n.endLine IS NOT NULL
+          AND (${overlapConditions})
+        RETURN n.id AS id, n.name AS name, labels(n)[0] AS type,
+               n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine
+      `;
             try {
-                const symbols = await executeParameterized(repo.id, `
-          MATCH (n) WHERE n.filePath CONTAINS $filePath
-          RETURN n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath
-          LIMIT 20
-        `, { filePath: normalizedFile });
-                for (const sym of symbols) {
+                const rows = await executeParameterized(repo.id, symbolQuery, queryParams);
+                for (const sym of rows) {
                     changedSymbols.push({
                         id: sym.id || sym[0],
                         name: sym.name || sym[1],
                         type: sym.type || sym[2],
                         filePath: sym.filePath || sym[3],
-                        change_type: 'Modified',
+                        change_type: 'touched',
                     });
                 }
             }
@@ -1259,28 +1332,33 @@ export class LocalBackend {
                 logQueryError('detect-changes:file-symbols', e);
             }
         }
-        // Find affected processes
+        // Find affected processes -- single batched query instead of N+1
         const affectedProcesses = new Map();
-        for (const sym of changedSymbols) {
+        if (changedSymbols.length > 0) {
+            const symIds = changedSymbols.map((s) => s.id);
+            const symNameById = new Map(changedSymbols.map((s) => [s.id, s.name]));
             try {
                 const procs = await executeParameterized(repo.id, `
-          MATCH (n {id: $nodeId})-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
-          RETURN p.id AS pid, p.heuristicLabel AS label, p.processType AS processType, p.stepCount AS stepCount, r.step AS step
-        `, { nodeId: sym.id });
+          MATCH (n)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
+          WHERE n.id IN $ids
+          RETURN n.id AS nodeId, p.id AS pid, p.heuristicLabel AS label,
+                 p.processType AS processType, p.stepCount AS stepCount, r.step AS step
+        `, { ids: symIds });
                 for (const proc of procs) {
-                    const pid = proc.pid || proc[0];
+                    const nodeId = proc.nodeId || proc[0];
+                    const pid = proc.pid || proc[1];
                     if (!affectedProcesses.has(pid)) {
                         affectedProcesses.set(pid, {
                             id: pid,
-                            name: proc.label || proc[1],
-                            process_type: proc.processType || proc[2],
-                            step_count: proc.stepCount || proc[3],
+                            name: proc.label || proc[2],
+                            process_type: proc.processType || proc[3],
+                            step_count: proc.stepCount || proc[4],
                             changed_steps: [],
                         });
                     }
                     affectedProcesses.get(pid).changed_steps.push({
-                        symbol: sym.name,
-                        step: proc.step || proc[4],
+                        symbol: symNameById.get(nodeId) ?? nodeId,
+                        step: proc.step || proc[5],
                     });
                 }
             }
@@ -1300,7 +1378,7 @@ export class LocalBackend {
             summary: {
                 changed_count: changedSymbols.length,
                 affected_count: processCount,
-                changed_files: changedFiles.length,
+                changed_files: fileDiffs.length,
                 risk_level: risk,
             },
             changed_symbols: changedSymbols,
@@ -1494,14 +1572,32 @@ export class LocalBackend {
         await this.ensureInitialized(repo.id);
         const { target, direction } = params;
         const maxDepth = params.maxDepth || 3;
-        const rawRelTypes = params.relationTypes && params.relationTypes.length > 0
-            ? params.relationTypes.filter((t) => VALID_RELATION_TYPES.has(t))
-            : ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS'];
-        const relationTypes = rawRelTypes.length > 0 ? rawRelTypes : ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS'];
+        // Map legacy relation type names before filtering (backward compat for OVERRIDES → METHOD_OVERRIDES)
+        const mappedRelTypes = params.relationTypes?.flatMap((t) => t === 'OVERRIDES' ? ['OVERRIDES', 'METHOD_OVERRIDES'] : [t]);
+        const rawRelTypes = mappedRelTypes && mappedRelTypes.length > 0
+            ? mappedRelTypes.filter((t) => VALID_RELATION_TYPES.has(t))
+            : [
+                'CALLS',
+                'IMPORTS',
+                'EXTENDS',
+                'IMPLEMENTS',
+                'METHOD_OVERRIDES',
+                'OVERRIDES',
+                'METHOD_IMPLEMENTS',
+            ];
+        const relationTypes = rawRelTypes.length > 0
+            ? rawRelTypes
+            : [
+                'CALLS',
+                'IMPORTS',
+                'EXTENDS',
+                'IMPLEMENTS',
+                'METHOD_OVERRIDES',
+                'OVERRIDES',
+                'METHOD_IMPLEMENTS',
+            ];
         const includeTests = params.includeTests ?? false;
         const minConfidence = params.minConfidence ?? 0;
-        const relTypeFilter = relationTypes.map((t) => `'${t}'`).join(', ');
-        const confidenceFilter = minConfidence > 0 ? ` AND r.confidence >= ${minConfidence}` : '';
         // Resolve target by name, preferring Class/Interface over Constructor
         // (fix #480: Java class and constructor share the same name).
         // labels(n)[0] returns empty string in LadybugDB, so we use explicit
@@ -1550,6 +1646,20 @@ export class LocalBackend {
         }
         if (!sym)
             return { error: `Target '${target}' not found` };
+        return this._runImpactBFS(repo, sym, symType, direction, {
+            maxDepth,
+            relationTypes,
+            includeTests,
+            minConfidence,
+        });
+    }
+    /**
+     * Shared BFS traversal for impact analysis (name-resolved or UID-resolved symbol).
+     */
+    async _runImpactBFS(repo, sym, symType, direction, opts) {
+        const { maxDepth, relationTypes, includeTests, minConfidence } = opts;
+        const relTypeFilter = relationTypes.map((t) => `'${t}'`).join(', ');
+        const confidenceFilter = minConfidence > 0 ? ` AND r.confidence >= ${minConfidence}` : '';
         const symId = sym.id || sym[0];
         const impacted = [];
         const visited = new Set([symId]);
@@ -1891,6 +2001,105 @@ export class LocalBackend {
             byDepth: grouped,
         };
     }
+    /**
+     * UID-based impact for cross-repo fan-out. Same result shape as `impact`.
+     * Returns null if the repo is unknown, the UID is missing, or analysis fails.
+     */
+    async impactByUid(repoId, uid, direction, opts) {
+        try {
+            await this.refreshRepos();
+            await this.ensureInitialized(repoId);
+        }
+        catch {
+            return null;
+        }
+        const repo = this.repos.get(repoId);
+        if (!repo)
+            return null;
+        const dir = direction === 'downstream' ? 'downstream' : 'upstream';
+        let rows;
+        try {
+            rows = await executeParameterized(repoId, `MATCH (n) WHERE n.id = $uid
+         RETURN n.id AS id, n.name AS name, n.filePath AS filePath, labels(n)[0] AS type
+         LIMIT 1`, { uid });
+        }
+        catch {
+            return null;
+        }
+        if (!rows?.length)
+            return null;
+        const sym = rows[0];
+        const labelRaw = sym.type ?? sym[3];
+        const symType = typeof labelRaw === 'string' && labelRaw.trim().length > 0 ? labelRaw.trim() : '';
+        // Map legacy relation type names (backward compat for OVERRIDES → METHOD_OVERRIDES)
+        const mappedRelTypes = opts.relationTypes?.flatMap((t) => t === 'OVERRIDES' ? ['OVERRIDES', 'METHOD_OVERRIDES'] : [t]);
+        const rawRelTypes = mappedRelTypes && mappedRelTypes.length > 0
+            ? mappedRelTypes.filter((t) => VALID_RELATION_TYPES.has(t))
+            : [
+                'CALLS',
+                'IMPORTS',
+                'EXTENDS',
+                'IMPLEMENTS',
+                'METHOD_OVERRIDES',
+                'OVERRIDES',
+                'METHOD_IMPLEMENTS',
+            ];
+        const relationTypes = rawRelTypes.length > 0
+            ? rawRelTypes
+            : [
+                'CALLS',
+                'IMPORTS',
+                'EXTENDS',
+                'IMPLEMENTS',
+                'METHOD_OVERRIDES',
+                'OVERRIDES',
+                'METHOD_IMPLEMENTS',
+            ];
+        try {
+            return await this._runImpactBFS(repo, sym, symType, dir, {
+                maxDepth: opts.maxDepth,
+                relationTypes,
+                includeTests: opts.includeTests,
+                minConfidence: opts.minConfidence,
+            });
+        }
+        catch {
+            return null;
+        }
+    }
+    handleGroupTool(method, params) {
+        switch (method) {
+            case 'group_list':
+                return this.groupList(params);
+            case 'group_sync':
+                return this.groupSync(params);
+            case 'group_contracts':
+                return this.groupContracts(params);
+            case 'group_query':
+                return this.groupQuery(params);
+            case 'group_status':
+                return this.groupStatus(params);
+            default:
+                throw new Error(`Unknown group tool: ${method}`);
+        }
+    }
+    async groupList(params) {
+        return this.getGroupService().groupList(params);
+    }
+    async groupSync(params) {
+        return this.getGroupService().groupSync(params);
+    }
+    async groupContracts(params) {
+        return this.getGroupService().groupContracts(params);
+    }
+    async groupQuery(params) {
+        await this.refreshRepos();
+        return this.getGroupService().groupQuery(params);
+    }
+    async groupStatus(params) {
+        await this.refreshRepos();
+        return this.getGroupService().groupStatus(params);
+    }
     /**
      * Fetch Route nodes with their consumers in a single query.
      * Shared by routeMap and shapeCheck to avoid N+1 query patterns.

package/dist/mcp/resources.js

@@ -281,10 +281,10 @@ additional_node_types: "Multi-language: Struct, Enum, Macro, Typedef, Union, Nam
 
 node_properties:
   common: "name (STRING), filePath (STRING), startLine (INT32), endLine (INT32)"
-  Method: "parameterCount (INT32), returnType (STRING), isVariadic (BOOL)"
-  Function: "parameterCount (INT32), returnType (STRING), isVariadic (BOOL)"
+  Method: "parameterCount (INT32), returnType (STRING), isVariadic (BOOL), visibility (STRING), isStatic (BOOL), isAbstract (BOOL), isFinal (BOOL), isVirtual (BOOL), isOverride (BOOL), isAsync (BOOL), isPartial (BOOL), requiredParameterCount (INT32), parameterTypes (STRING[]), annotations (STRING[])"
+  Function: "parameterCount (INT32), returnType (STRING), isVariadic (BOOL), visibility (STRING), isStatic (BOOL), isAbstract (BOOL), isFinal (BOOL), isAsync (BOOL), parameterTypes (STRING[]), annotations (STRING[])"
   Property: "declaredType (STRING) — the field's type annotation (e.g., 'Address', 'City'). Used for field-access chain resolution."
-  Constructor: "parameterCount (INT32)"
+  Constructor: "parameterCount (INT32), visibility (STRING), isStatic (BOOL), parameterTypes (STRING[])"
   Community: "heuristicLabel (STRING), cohesion (DOUBLE), symbolCount (INT32), keywords (STRING[]), description (STRING), enrichedBy (STRING)"
   Process: "heuristicLabel (STRING), processType (STRING — 'intra_community' or 'cross_community'), stepCount (INT32), communities (STRING[]), entryPointId (STRING), terminalId (STRING)"
 
@@ -298,7 +298,8 @@ relationships:
   - HAS_METHOD: Class/Struct/Interface owns a Method
   - HAS_PROPERTY: Class/Struct/Interface owns a Property (field)
   - ACCESSES: Function/Method reads or writes a Property (reason: 'read' or 'write')
-  - OVERRIDES: Method overrides another Method (MRO)
+  - METHOD_OVERRIDES: Method overrides another Method (MRO)
+  - METHOD_IMPLEMENTS: ConcreteMethod implements InterfaceMethod (matched by name + parameterTypes)
   - MEMBER_OF: Symbol belongs to community
   - STEP_IN_PROCESS: Symbol is step N in process
 

package/dist/mcp/staleness.d.ts

@@ -1,15 +1,5 @@
 /**
- * Staleness Check
- *
- * Checks if the GitNexus index is behind the current git HEAD.
- * Returns a hint for the LLM to call analyze if stale.
+ * Staleness Check — re-export from core (see `core/git-staleness.ts`).
  */
-export interface StalenessInfo {
-    isStale: boolean;
-    commitsBehind: number;
-    hint?: string;
-}
-/**
- * Check how many commits the index is behind HEAD
- */
-export declare function checkStaleness(repoPath: string, lastCommit: string): StalenessInfo;
+export type { StalenessInfo } from '../core/git-staleness.js';
+export { checkStaleness } from '../core/git-staleness.js';

package/dist/mcp/staleness.js

@@ -1,33 +1,4 @@
 /**
- * Staleness Check
- *
- * Checks if the GitNexus index is behind the current git HEAD.
- * Returns a hint for the LLM to call analyze if stale.
+ * Staleness Check — re-export from core (see `core/git-staleness.ts`).
  */
-import { execFileSync } from 'child_process';
-/**
- * Check how many commits the index is behind HEAD
- */
-export function checkStaleness(repoPath, lastCommit) {
-    try {
-        // Get count of commits between lastCommit and HEAD
-        const result = execFileSync('git', ['rev-list', '--count', `${lastCommit}..HEAD`], {
-            cwd: repoPath,
-            encoding: 'utf-8',
-            stdio: ['pipe', 'pipe', 'pipe'],
-        }).trim();
-        const commitsBehind = parseInt(result, 10) || 0;
-        if (commitsBehind > 0) {
-            return {
-                isStale: true,
-                commitsBehind,
-                hint: `⚠️ Index is ${commitsBehind} commit${commitsBehind > 1 ? 's' : ''} behind HEAD. Run analyze tool to update.`,
-            };
-        }
-        return { isStale: false, commitsBehind: 0 };
-    }
-    catch {
-        // If git command fails, assume not stale (fail open)
-        return { isStale: false, commitsBehind: 0 };
-    }
-}
+export { checkStaleness } from '../core/git-staleness.js';

package/dist/mcp/tools.js

@@ -78,7 +78,7 @@ SCHEMA:
 - Nodes: File, Folder, Function, Class, Interface, Method, CodeElement, Community, Process, Route, Tool
 - Multi-language nodes (use backticks): \`Struct\`, \`Enum\`, \`Trait\`, \`Impl\`, etc.
 - All edges via single CodeRelation table with 'type' property
-- Edge types: CONTAINS, DEFINES, CALLS, IMPORTS, EXTENDS, IMPLEMENTS, HAS_METHOD, HAS_PROPERTY, ACCESSES, OVERRIDES, MEMBER_OF, STEP_IN_PROCESS, HANDLES_ROUTE, FETCHES, HANDLES_TOOL, ENTRY_POINT_OF
+- Edge types: CONTAINS, DEFINES, CALLS, IMPORTS, EXTENDS, IMPLEMENTS, HAS_METHOD, HAS_PROPERTY, ACCESSES, METHOD_OVERRIDES, METHOD_IMPLEMENTS, MEMBER_OF, STEP_IN_PROCESS, HANDLES_ROUTE, FETCHES, HANDLES_TOOL, ENTRY_POINT_OF
 - Edge properties: type (STRING), confidence (DOUBLE), reason (STRING), step (INT32)
 
 EXAMPLES:
@@ -101,7 +101,7 @@ EXAMPLES:
   MATCH (f:Function)-[r:CodeRelation {type: 'ACCESSES', reason: 'write'}]->(p:Property) WHERE p.name = "address" RETURN f.name, f.filePath
 
 • Find method overrides (MRO resolution):
-  MATCH (winner:Method)-[r:CodeRelation {type: 'OVERRIDES'}]->(loser:Method) RETURN winner.name, winner.filePath, loser.filePath, r.reason
+  MATCH (winner:Method)-[r:CodeRelation {type: 'METHOD_OVERRIDES'}]->(loser:Method) RETURN winner.name, winner.filePath, loser.filePath, r.reason
 
 • Detect diamond inheritance:
   MATCH (d:Class)-[:CodeRelation {type: 'EXTENDS'}]->(b1), (d)-[:CodeRelation {type: 'EXTENDS'}]->(b2), (b1)-[:CodeRelation {type: 'EXTENDS'}]->(a), (b2)-[:CodeRelation {type: 'EXTENDS'}]->(a) WHERE b1 <> b2 RETURN d.name, b1.name, b2.name, a.name
@@ -244,7 +244,7 @@ Depth groups:
 
 TIP: Default traversal uses CALLS/IMPORTS/EXTENDS/IMPLEMENTS. For class members, include HAS_METHOD and HAS_PROPERTY in relationTypes. For field access analysis, include ACCESSES in relationTypes.
 
-EdgeType: CALLS, IMPORTS, EXTENDS, IMPLEMENTS, HAS_METHOD, HAS_PROPERTY, OVERRIDES, ACCESSES
+EdgeType: CALLS, IMPORTS, EXTENDS, IMPLEMENTS, HAS_METHOD, HAS_PROPERTY, METHOD_OVERRIDES, METHOD_IMPLEMENTS, ACCESSES
 Confidence: 1.0 = certain, <0.8 = fuzzy match`,
         inputSchema: {
             type: 'object',
@@ -262,7 +262,7 @@ Confidence: 1.0 = certain, <0.8 = fuzzy match`,
                 relationTypes: {
                     type: 'array',
                     items: { type: 'string' },
-                    description: 'Filter: CALLS, IMPORTS, EXTENDS, IMPLEMENTS, HAS_METHOD, HAS_PROPERTY, OVERRIDES, ACCESSES (default: usage-based, ACCESSES excluded by default)',
+                    description: 'Filter: CALLS, IMPORTS, EXTENDS, IMPLEMENTS, HAS_METHOD, HAS_PROPERTY, METHOD_OVERRIDES, METHOD_IMPLEMENTS, ACCESSES (default: usage-based, ACCESSES excluded by default)',
                 },
                 includeTests: { type: 'boolean', description: 'Include test files (default: false)' },
                 minConfidence: { type: 'number', description: 'Minimum confidence 0-1 (default: 0.7)' },
@@ -355,4 +355,80 @@ Returns: single route object when one match, or { routes: [...], total: N } for
             required: [],
         },
     },
+    {
+        name: 'group_list',
+        description: `List all configured repository groups, or return details for one group (repos, manifest links).
+
+WHEN TO USE: Discover groups before group_sync. Optional "name" returns a single group's config.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Group name. Omit to list all groups.' },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'group_sync',
+        description: `Rebuild the Contract Registry (contracts.json) for a group: extract HTTP contracts, apply manifest links, exact-match cross-links.
+
+WHEN TO USE: After changing group.yaml or re-indexing member repos.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Group name' },
+                skipEmbeddings: {
+                    type: 'boolean',
+                    description: 'Exact + BM25 only (Demo PR: same as default exact path)',
+                },
+                exactOnly: { type: 'boolean', description: 'Exact match only in cascade' },
+            },
+            required: ['name'],
+        },
+    },
+    {
+        name: 'group_contracts',
+        description: `Inspect contracts and cross-links from the group's contracts.json.
+
+WHEN TO USE: Debug cross-repo links after group_sync.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Group name' },
+                type: { type: 'string', description: 'Filter by contract type (http, topic, …)' },
+                repo: { type: 'string', description: 'Filter by group repo path (e.g. app/backend)' },
+                unmatchedOnly: { type: 'boolean', description: 'Only contracts with no cross-link' },
+            },
+            required: ['name'],
+        },
+    },
+    {
+        name: 'group_query',
+        description: `Run the query tool across all repos in a group and merge process results via reciprocal rank fusion.
+
+WHEN TO USE: Semantic / hybrid search across a whole product group.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Group name' },
+                query: { type: 'string', description: 'Search query' },
+                subgroup: { type: 'string', description: 'Limit to repo paths under this prefix' },
+                limit: { type: 'number', description: 'Max merged results (default 5)' },
+            },
+            required: ['name', 'query'],
+        },
+    },
+    {
+        name: 'group_status',
+        description: `Report index staleness (commit vs HEAD) and Contract Registry staleness (indexedAt) for each repo in a group.
+
+WHEN TO USE: Before group_sync or when agents should refresh indexes.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Group name' },
+            },
+            required: ['name'],
+        },
+    },
 ];

package/dist/server/analyze-job.d.ts

@@ -40,6 +40,8 @@ export declare class JobManager {
         repoPath?: string;
     }): AnalyzeJob;
     getJob(id: string): AnalyzeJob | undefined;
+    /** Return a snapshot of all tracked jobs for inspection. */
+    listJobs(): AnalyzeJob[];
     updateJob(id: string, update: Partial<Pick<AnalyzeJob, 'status' | 'progress' | 'error' | 'repoPath' | 'repoName' | 'completedAt'>>): void;
     /** Register a child process for a job — enables cancellation and timeout. */
     registerChild(jobId: string, child: ChildProcess): void;