@codragraph/cli 1.6.2

package/dist/mcp/local/graphstore-handler.js

@@ -0,0 +1,272 @@
+/**
+ * MCP dispatch for the Phase 4 versioned-graph tools.
+ *
+ * Each handler takes the repo's `storagePath` (already resolved by the
+ * caller from the optional `repo` MCP param) and returns plain JSON
+ * structures. Output is shaped for direct rendering by the agent — short
+ * strings, sorted lists, no internal CAS handles in the response.
+ */
+import path from 'node:path';
+import { FsCAS, createCommit, diffSemantic, diffSnapshots, gc as runGc, getJson, listBranches, parseObjectId, readCommit, readHead, resolveHeadCommit, setHead, threeWayMerge, walkCommits, } from '@codragraph/graphstore';
+import { GRAPHSTORE_SUBDIR } from '../../core/graphstore/index.js';
+const buildCtx = (storagePath) => {
+    const root = path.join(storagePath, GRAPHSTORE_SUBDIR);
+    return { root, cas: new FsCAS({ root }) };
+};
+const resolveTarget = async (ctx, target) => {
+    const branches = await listBranches({ root: ctx.root });
+    const hit = branches.find((b) => b.name === target);
+    if (hit)
+        return hit.head;
+    return parseObjectId(target);
+};
+export const handleGraphstoreLog = async (params) => {
+    const ctx = buildCtx(params.storagePath);
+    const start = params.from !== undefined
+        ? await resolveTarget(ctx, params.from)
+        : await resolveHeadCommit({ root: ctx.root });
+    if (start === null) {
+        return { branch: null, head: null, commits: [] };
+    }
+    const headState = await readHead({ root: ctx.root });
+    const commits = [];
+    for await (const entry of walkCommits({
+        cas: ctx.cas,
+        from: start,
+        limit: params.limit ?? 50,
+    })) {
+        commits.push({
+            id: entry.id,
+            short: entry.id.slice(7, 7 + 12),
+            snapshot: entry.commit.snapshot,
+            parents: [...entry.commit.parents],
+            author: `${entry.commit.author.name} <${entry.commit.author.email}>`,
+            ts: entry.commit.ts,
+            message: entry.commit.message,
+        });
+    }
+    return {
+        branch: headState.kind === 'branch' ? headState.branch : null,
+        head: start,
+        commits,
+    };
+};
+export const handleGraphstoreBranches = async (params) => {
+    const ctx = buildCtx(params.storagePath);
+    const branches = await listBranches({ root: ctx.root });
+    const headState = await readHead({ root: ctx.root });
+    const current = headState.kind === 'branch' ? headState.branch : null;
+    return {
+        current,
+        branches: branches.map((b) => ({
+            name: b.name,
+            head: b.head,
+            short: b.head.slice(7, 7 + 12),
+            createdAt: b.createdAt,
+            isCurrent: b.name === current,
+        })),
+    };
+};
+export const handleGraphstoreDiff = async (params) => {
+    const ctx = buildCtx(params.storagePath);
+    const [fromCommitId, toCommitId] = await Promise.all([
+        resolveTarget(ctx, params.from),
+        resolveTarget(ctx, params.to),
+    ]);
+    const [fromCommit, toCommit] = await Promise.all([
+        readCommit(ctx.cas, fromCommitId),
+        readCommit(ctx.cas, toCommitId),
+    ]);
+    const diff = await diffSnapshots({
+        cas: ctx.cas,
+        from: fromCommit.snapshot,
+        to: toCommit.snapshot,
+    });
+    return formatDiff(fromCommitId, toCommitId, fromCommit.message, toCommit.message, diff);
+};
+const formatDiff = (fromId, toId, fromMsg, toMsg, diff) => {
+    const summary = {
+        addedNodes: countByTable(diff.addedNodes),
+        removedNodes: countByTable(diff.removedNodes),
+        addedEdges: diff.addedEdges.length,
+        removedEdges: diff.removedEdges.length,
+        modifiedSymbols: diff.modifiedSymbols.length,
+    };
+    return {
+        from: { id: fromId, short: fromId.slice(7, 7 + 12), message: fromMsg },
+        to: { id: toId, short: toId.slice(7, 7 + 12), message: toMsg },
+        summary,
+        modifiedSymbols: diff.modifiedSymbols.slice(0, 50),
+    };
+};
+const countByTable = (byTable) => {
+    const out = {};
+    for (const [t, ids] of Object.entries(byTable)) {
+        if (ids.length > 0)
+            out[t] = ids.length;
+    }
+    return out;
+};
+export const handleGraphstoreBlameSymbol = async (params) => {
+    const ctx = buildCtx(params.storagePath);
+    const head = await resolveHeadCommit({ root: ctx.root });
+    if (head === null) {
+        return { symbolId: params.symbolId, history: [] };
+    }
+    const limit = params.limit ?? 20;
+    // Collect history newest → oldest, with each commit's symbol hash.
+    const history = [];
+    for await (const entry of walkCommits({ cas: ctx.cas, from: head })) {
+        const snapshot = await getJson(ctx.cas, entry.commit.snapshot);
+        const manifest = await getJson(ctx.cas, parseObjectId(snapshot.manifestId));
+        const found = locateSymbol(manifest, params.symbolId, params.table);
+        history.push({
+            commitId: entry.id,
+            short: entry.id.slice(7, 7 + 12),
+            ts: entry.commit.ts,
+            message: entry.commit.message,
+            table: found?.table ?? null,
+            rowHash: found?.hash ?? null,
+        });
+    }
+    // Compress: keep only commits where the row hash transitioned.
+    const transitions = compressBlameTransitions(history).slice(0, limit);
+    return { symbolId: params.symbolId, history: transitions };
+};
+export const handleGraphstoreSemanticDiff = async (params) => {
+    const ctx = buildCtx(params.storagePath);
+    const [fromCommitId, toCommitId] = await Promise.all([
+        resolveTarget(ctx, params.from),
+        resolveTarget(ctx, params.to),
+    ]);
+    const [fromCommit, toCommit] = await Promise.all([
+        readCommit(ctx.cas, fromCommitId),
+        readCommit(ctx.cas, toCommitId),
+    ]);
+    const d = await diffSemantic({
+        cas: ctx.cas,
+        from: fromCommit.snapshot,
+        to: toCommit.snapshot,
+    });
+    return {
+        from: { id: fromCommitId, short: fromCommitId.slice(7, 7 + 12), message: fromCommit.message },
+        to: { id: toCommitId, short: toCommitId.slice(7, 7 + 12), message: toCommit.message },
+        summary: {
+            addedAPIs: d.addedAPIs.length,
+            removedAPIs: d.removedAPIs.length,
+            addedProcesses: d.addedProcesses.length,
+            removedProcesses: d.removedProcesses.length,
+            classifiedModifications: d.classifiedModifications.length,
+        },
+        addedAPIs: d.addedAPIs,
+        removedAPIs: d.removedAPIs,
+        addedProcesses: d.addedProcesses,
+        removedProcesses: d.removedProcesses,
+        classifiedModifications: d.classifiedModifications.slice(0, 50),
+    };
+};
+export const handleGraphstoreMerge = async (params) => {
+    const ctx = buildCtx(params.storagePath);
+    const headState = await readHead({ root: ctx.root });
+    const branch = params.into ?? (headState.kind === 'branch' ? headState.branch : null);
+    if (!branch) {
+        return {
+            kind: 'error',
+            message: 'merge requires either --into <branch> or a non-detached HEAD on the target repo',
+        };
+    }
+    const ours = (await listBranches({ root: ctx.root })).find((b) => b.name === branch)?.head;
+    if (!ours) {
+        return { kind: 'error', message: `target branch "${branch}" not found` };
+    }
+    const theirs = await resolveTarget(ctx, params.source);
+    const result = await threeWayMerge({ cas: ctx.cas, ours, theirs });
+    switch (result.kind) {
+        case 'already-up-to-date':
+            return { kind: 'already-up-to-date', branch };
+        case 'fast-forward':
+            if (!params.dryRun) {
+                await setHead({ root: ctx.root, branch, commit: result.to });
+            }
+            return { kind: 'fast-forward', branch, to: result.to, dryRun: params.dryRun ?? false };
+        case 'conflicts':
+            return {
+                kind: 'conflicts',
+                branch,
+                base: result.base,
+                conflicts: result.conflicts.slice(0, 100),
+                totalConflicts: result.conflicts.length,
+            };
+        case 'merged': {
+            if (params.dryRun) {
+                return {
+                    kind: 'merged',
+                    dryRun: true,
+                    branch,
+                    base: result.base,
+                    snapshotId: result.snapshotId,
+                    stats: result.stats,
+                };
+            }
+            const message = params.message ?? `Merge ${params.source} into ${branch}`;
+            const commit = await createCommit({
+                cas: ctx.cas,
+                snapshot: result.snapshotId,
+                parents: [ours, theirs],
+                author: { name: '@codragraph/cli', email: 'noreply@codragraph.local' },
+                message,
+            });
+            await setHead({ root: ctx.root, branch, commit: commit.commitId });
+            return {
+                kind: 'merged',
+                dryRun: false,
+                branch,
+                base: result.base,
+                commitId: commit.commitId,
+                snapshotId: result.snapshotId,
+                stats: result.stats,
+            };
+        }
+    }
+};
+export const handleGraphstoreGc = async (params) => {
+    const ctx = buildCtx(params.storagePath);
+    const result = await runGc({
+        cas: ctx.cas,
+        graphstoreRoot: ctx.root,
+        dryRun: params.dryRun,
+    });
+    return {
+        dryRun: result.dryRun,
+        reachable: result.reachable,
+        swept: result.swept.length,
+        bytesFreed: result.bytesFreed,
+        sample: result.swept.slice(0, 25),
+    };
+};
+const locateSymbol = (manifest, symbolId, tableHint) => {
+    if (tableHint !== undefined) {
+        const t = manifest.nodeTables[tableHint];
+        const h = t?.rows[symbolId];
+        return h ? { table: tableHint, hash: h } : null;
+    }
+    for (const [table, t] of Object.entries(manifest.nodeTables)) {
+        const h = t.rows[symbolId];
+        if (h)
+            return { table, hash: h };
+    }
+    return null;
+};
+const compressBlameTransitions = (history) => {
+    const out = [];
+    let lastHash = null;
+    for (let i = 0; i < history.length; i++) {
+        const e = history[i];
+        if (e === undefined)
+            continue;
+        if (i === 0 || e.rowHash !== lastHash)
+            out.push(e);
+        lastHash = e.rowHash;
+    }
+    return out;
+};

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

@@ -0,0 +1,347 @@
+/**
+ * Local Backend (Multi-Repo)
+ *
+ * Provides tool implementations using local .codragraph/ indexes.
+ * Supports multiple indexed repositories via a global registry.
+ * LadybugDB connections are opened lazily per repo on first query.
+ */
+import { isWriteQuery } from '../../core/lbug/pool-adapter.js';
+export { isWriteQuery };
+import { type RegistryEntry } from '../../storage/repo-manager.js';
+import { GroupService } from '../../core/group/service.js';
+/**
+ * Quick test-file detection for filtering impact results.
+ * Matches common test file patterns across all supported languages.
+ */
+export declare function isTestFilePath(filePath: string): boolean;
+/** Valid LadybugDB node labels for safe Cypher query construction */
+export declare const VALID_NODE_LABELS: Set<string>;
+/** Valid relation types for impact analysis filtering */
+export declare const VALID_RELATION_TYPES: Set<string>;
+/**
+ * Per-relation-type confidence floor for impact analysis.
+ *
+ * When the graph stores a relation with a confidence value, that stored
+ * value is used as-is (it reflects resolution-tier accuracy from analysis
+ * time).  This map provides the floor for each edge type when no stored
+ * confidence is available, and is also used for display / tooltip hints.
+ *
+ * Rationale:
+ *   CALLS / IMPORTS  – direct, strongly-typed references → 0.9
+ *   EXTENDS          – class hierarchy, statically verifiable → 0.85
+ *   IMPLEMENTS       – interface contract, 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
+ *   CONTAINS         – folder/file containment → 0.95
+ *   (unknown type)   – conservative fallback → 0.5
+ */
+export declare const IMPACT_RELATION_CONFIDENCE: Readonly<Record<string, number>>;
+export interface CodebaseContext {
+    projectName: string;
+    stats: {
+        fileCount: number;
+        functionCount: number;
+        communityCount: number;
+        processCount: number;
+    };
+}
+interface RepoHandle {
+    id: string;
+    name: string;
+    repoPath: string;
+    storagePath: string;
+    lbugPath: string;
+    indexedAt: string;
+    lastCommit: string;
+    remoteUrl?: string;
+    stats?: RegistryEntry['stats'];
+}
+export declare class LocalBackend {
+    private repos;
+    private contextCache;
+    private initializedRepos;
+    private reinitPromises;
+    private lastStalenessCheck;
+    private groupToolSvc;
+    /**
+     * One-shot stderr warnings for sibling-clone drift, keyed by
+     * `${repoId}|${cwdGitRoot}`. Without this guard every tool call
+     * from inside a sibling clone would print the same warning,
+     * making MCP stderr unreadable.
+     */
+    private warnedSiblingDrift;
+    /**
+     * Cross-repo group tools (CLI). Shares logic with MCP `group_*` handlers.
+     */
+    getGroupService(): GroupService;
+    /** Close all pooled LadybugDB connections (CLI one-shot; optional for long-lived MCP). */
+    dispose(): Promise<void>;
+    /**
+     * Initialize from the global registry.
+     * Returns true if at least one repo is available.
+     */
+    init(): Promise<boolean>;
+    /**
+     * Re-read the global registry and update the in-memory repo map.
+     * New repos are added, existing repos are updated, removed repos are pruned.
+     * LadybugDB connections for removed repos are NOT closed (they idle-timeout naturally).
+     */
+    private refreshRepos;
+    /**
+     * Generate a stable repo ID from name + path.
+     * If names collide, append a hash of the path.
+     */
+    private repoId;
+    /**
+     * Resolve which repo to use.
+     * - If repoParam is given, match by name or path
+     * - If only 1 repo, use it
+     * - If 0 or multiple without param, throw with helpful message
+     *
+     * On a miss, re-reads the registry once in case a new repo was indexed
+     * while the MCP server was running.
+     */
+    resolveRepo(repoParam?: string): Promise<RepoHandle>;
+    /**
+     * Try to resolve a repo from the in-memory cache. Returns null on miss.
+     */
+    private resolveRepoFromCache;
+    private ensureInitialized;
+    /**
+     * Get context for a specific repo (or the single repo if only one).
+     */
+    getContext(repoId?: string): CodebaseContext | null;
+    /**
+     * List all registered repos with their metadata.
+     * Re-reads the global registry so newly indexed repos are discovered
+     * without restarting the MCP server.
+     *
+     * Each entry includes:
+     *   - `staleness`: if the indexed clone's own HEAD has moved past
+     *     the recorded `lastCommit` (option D in the issue's fix list).
+     *   - `siblings`: other registered entries sharing the same
+     *     `remoteUrl` (option B's payoff: callers can see at a glance
+     *     that another clone of the same logical repo is registered).
+     *   - `remoteUrl`: the canonical origin URL recorded at index time.
+     */
+    listRepos(): Promise<Array<{
+        name: string;
+        path: string;
+        indexedAt: string;
+        lastCommit: string;
+        remoteUrl?: string;
+        stats?: any;
+        staleness?: {
+            commitsBehind: number;
+            hint?: string;
+        };
+        siblings?: Array<{
+            name: string;
+            path: string;
+            lastCommit: string;
+        }>;
+    }>>;
+    /**
+     * Best-effort sibling-clone drift warning.
+     *
+     * When the resolved index has a `remoteUrl` recorded and the caller's
+     * `process.cwd()` is inside a *different* clone of the same repo, emit
+     * one stderr line per (repo, cwd) pair so the operator knows the
+     * graph may be stale relative to what's actually on disk under their
+     * cwd. Silent on path matches and on repos without a remote URL.
+     *
+     * Limitation: in MCP stdio server mode `process.cwd()` is the
+     * server's CWD at start time, *not* the agent client's CWD. The
+     * warning therefore only fires when the MCP server itself was
+     * launched from inside a sibling clone (typical for `npx codragraph
+     * serve` from a polecat workspace). Surfacing the client's CWD
+     * would require a per-tool-call `cwd` parameter — out of scope for
+     * the current MCP contract.
+     *
+     * Pure side-effect (stderr); never affects the returned handle.
+     * After the first computation for a given (repo, cwd) pair the
+     * result is cached so subsequent `resolveRepo()` calls don't
+     * re-shell-out to git.
+     */
+    private maybeWarnSiblingDrift;
+    callTool(method: string, params: any): Promise<any>;
+    /**
+     * Query tool — process-grouped search.
+     *
+     * 1. Hybrid search (BM25 + semantic) to find matching symbols
+     * 2. Trace each match to its process(es) via STEP_IN_PROCESS
+     * 3. Group by process, rank by aggregate relevance + internal cluster cohesion
+     * 4. Return: { processes, process_symbols, definitions }
+     */
+    private query;
+    /**
+     * BM25 keyword search helper - uses LadybugDB FTS for always-fresh results
+     */
+    private bm25Search;
+    /**
+     * Semantic vector search helper
+     */
+    private semanticSearch;
+    executeCypher(repoName: string, query: string): Promise<any>;
+    private cypher;
+    /**
+     * Format raw Cypher result rows as a markdown table for LLM readability.
+     * Falls back to raw result if rows aren't tabular objects.
+     */
+    private formatCypherAsMarkdown;
+    /**
+     * Aggregate same-named clusters: group by heuristicLabel, sum symbols,
+     * weighted-average cohesion, filter out tiny clusters (<5 symbols).
+     * Raw communities stay intact in LadybugDB for Cypher queries.
+     */
+    private aggregateClusters;
+    private overview;
+    /**
+     * Patch the `type` field on candidates whose `labels(n)[0]` projection
+     * came back empty — a known LadybugDB behaviour for several node types.
+     *
+     * Uses one scoped UNION query across the five priority labels rather
+     * than per-candidate round-trips, so cost is a single DB call regardless
+     * of how many candidates need enrichment. No-op when every candidate
+     * already has a non-empty type.
+     *
+     * Failures are swallowed: label enrichment is an optimisation for
+     * downstream scoring and #480 Class/Interface BFS seeding; if it fails
+     * the symbol still resolves, just without the kind-priority bonus.
+     */
+    private enrichCandidateLabels;
+    /**
+     * Score a symbol candidate for disambiguation ranking.
+     *
+     * Deterministic, no DB round-trip:
+     *   - base 0.50
+     *   - +0.40 when file_path hint matches (substring, case-insensitive)
+     *   - +0.20 when kind hint exactly matches the candidate's kind
+     *   - when no kind hint, a small priority bonus (Class > Interface >
+     *     Function > Method > Constructor) to preserve the intuition that
+     *     class-level names are usually what the user wanted.
+     *
+     * Capped at 1.0. Intentionally simple and inspectable — a future v2 can
+     * plug in BM25/embedding signals here without changing the surrounding
+     * resolver shape.
+     */
+    private scoreCandidate;
+    /**
+     * Shared symbol resolver used by `context` and `impact`.
+     *
+     * Returns one of:
+     *   - `{ kind: 'ok', symbol, resolvedLabel }` — single confident match
+     *     (either direct UID, only one candidate after filtering, Class/
+     *     Constructor collapse, or a top-scoring candidate with a clear gap
+     *     to the runner-up).
+     *   - `{ kind: 'ambiguous', candidates }` — multiple viable matches,
+     *     sorted by score desc. Each candidate carries a relevance score.
+     *   - `{ kind: 'not_found' }` — no matches at all.
+     *
+     * Preserves the #480 Class/Constructor preference: when the only
+     * ambiguity is between a Class and its own Constructor (same name,
+     * same filePath), the Class wins silently.
+     */
+    private resolveSymbolCandidates;
+    /**
+     * Context tool — 360-degree symbol view with categorized refs.
+     * Disambiguation (ranked) when multiple symbols share a name.
+     * UID-based direct lookup. No cluster in output.
+     */
+    private context;
+    /**
+     * Legacy explore — kept for backwards compatibility with resources.ts.
+     * Routes cluster/process types to direct graph queries.
+     */
+    private explore;
+    /**
+     * Detect changes — git-diff based impact analysis.
+     * Maps changed lines to indexed symbols, then finds affected processes.
+     */
+    private detectChanges;
+    /**
+     * Rename tool — multi-file coordinated rename using graph + text search.
+     * Graph refs are tagged "graph" (high confidence).
+     * Additional refs found via text search are tagged "text_search" (lower confidence).
+     */
+    private rename;
+    private impact;
+    private _impactImpl;
+    /**
+     * Shared BFS traversal for impact analysis (name-resolved or UID-resolved symbol).
+     */
+    private _runImpactBFS;
+    /**
+     * 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.
+     */
+    impactByUid(repoId: string, uid: string, direction: string, opts: {
+        maxDepth: number;
+        relationTypes: string[];
+        minConfidence: number;
+        includeTests: boolean;
+    }): Promise<any | null>;
+    private handleGroupTool;
+    /**
+     * Dispatch impact/query/context when `repo` is `@groupName` or `@groupName/memberPath`
+     * (group mode — not the global indexed-repo `repo` parameter).
+     */
+    private callToolAtGroupRepo;
+    private groupList;
+    private groupSync;
+    /**
+     * MCP resource body for `codragraph://group/{name}/contracts` (Issue #794).
+     */
+    readGroupContractsResource(groupName: string, filter: {
+        type?: string;
+        repo?: string;
+        unmatchedOnly?: boolean;
+    }): Promise<string>;
+    /**
+     * MCP resource body for `codragraph://group/{name}/status` (Issue #794).
+     */
+    readGroupStatusResource(groupName: string): Promise<string>;
+    private static formatGroupResourcePayload;
+    /**
+     * Fetch Route nodes with their consumers in a single query.
+     * Shared by routeMap and shapeCheck to avoid N+1 query patterns.
+     */
+    private fetchRoutesWithConsumers;
+    /**
+     * Batch-fetch execution flows linked to a set of Route or Tool nodes.
+     * Single query instead of N+1.
+     */
+    private fetchLinkedFlowsBatch;
+    private routeMap;
+    private shapeCheck;
+    private toolMap;
+    private apiImpact;
+    /**
+     * Query clusters (communities) directly from graph.
+     * Used by getClustersResource — avoids legacy overview() dispatch.
+     */
+    queryClusters(repoName?: string, limit?: number): Promise<{
+        clusters: any[];
+    }>;
+    /**
+     * Query processes directly from graph.
+     * Used by getProcessesResource — avoids legacy overview() dispatch.
+     */
+    queryProcesses(repoName?: string, limit?: number): Promise<{
+        processes: any[];
+    }>;
+    /**
+     * Query cluster detail (members) directly from graph.
+     * Used by getClusterDetailResource.
+     */
+    queryClusterDetail(name: string, repoName?: string): Promise<any>;
+    /**
+     * Query process detail (steps) directly from graph.
+     * Used by getProcessDetailResource.
+     */
+    queryProcessDetail(name: string, repoName?: string): Promise<any>;
+    disconnect(): Promise<void>;
+}