@codragraph/cli 1.6.2

package/dist/core/group/matching.js

@@ -0,0 +1,198 @@
+function isGrpcWildcard(cid) {
+    return cid.startsWith('grpc::') && cid.endsWith('/*');
+}
+export function normalizeContractId(id) {
+    const colonIdx = id.indexOf('::');
+    if (colonIdx === -1)
+        return id;
+    const type = id.substring(0, colonIdx);
+    const rest = id.substring(colonIdx + 2);
+    switch (type) {
+        case 'http': {
+            const parts = rest.split('::');
+            if (parts.length >= 2) {
+                const method = parts[0].toUpperCase();
+                let pathPart = parts.slice(1).join('::');
+                pathPart = pathPart.replace(/\/+$/, '');
+                return `http::${method}::${pathPart}`;
+            }
+            return id;
+        }
+        case 'grpc': {
+            // Canonical form: `grpc::<lowercased-package-or-service>[/<method>]`.
+            //
+            // The package/service segment is lowercased because gRPC package
+            // names are effectively case-insensitive across language bindings
+            // (`auth.AuthService`, `auth.authservice`, `AUTH.AUTHSERVICE` all
+            // describe the same wire protocol service). The RPC method segment
+            // is preserved as-is because the HTTP/2 path used on the wire is
+            // case-sensitive per the gRPC spec (`/Service/MethodName`), and
+            // method names in generated clients match the proto source exactly.
+            //
+            // A package-only id (no slash) and a package/method id are treated
+            // as DISTINCT canonical forms: `grpc::userservice` does not match
+            // `grpc::userservice/Login`. That's by design — callers that want
+            // service-level manifest matching against method-level providers
+            // should use the gRPC wildcard form `grpc::UserService/*` which is
+            // handled by runWildcardMatch below.
+            const slashIdx = rest.indexOf('/');
+            if (slashIdx > 0) {
+                const pkg = rest.substring(0, slashIdx).toLowerCase();
+                const method = rest.substring(slashIdx);
+                return `grpc::${pkg}${method}`;
+            }
+            if (slashIdx === 0) {
+                // Malformed "/method" with leading slash — keep as-is so two
+                // equally malformed ids can still match each other.
+                return `grpc::${rest}`;
+            }
+            // No slash: package/service only. Lowercase to match the package
+            // segment produced by the pkg/method branch above.
+            return `grpc::${rest.toLowerCase()}`;
+        }
+        case 'topic':
+            return `topic::${rest.trim().toLowerCase()}`;
+        case 'lib':
+            return `lib::${rest.toLowerCase()}`;
+        default:
+            return id;
+    }
+}
+function findMatchingKeys(contractId, index) {
+    const normalized = normalizeContractId(contractId);
+    if (index.has(normalized))
+        return [normalized];
+    if (normalized.startsWith('http::*::')) {
+        const pathPart = normalized.substring('http::*::'.length);
+        const matches = [];
+        for (const key of index.keys()) {
+            if (key.startsWith('http::') && key.endsWith(`::${pathPart}`)) {
+                matches.push(key);
+            }
+        }
+        return matches;
+    }
+    return [];
+}
+export function buildProviderIndex(contracts) {
+    const providers = contracts.filter((c) => c.role === 'provider');
+    const index = new Map();
+    for (const p of providers) {
+        const key = normalizeContractId(p.contractId);
+        const list = index.get(key) || [];
+        list.push(p);
+        index.set(key, list);
+    }
+    return index;
+}
+export function runExactMatch(contracts, providerIndex) {
+    const index = providerIndex ?? buildProviderIndex(contracts);
+    // Skip gRPC wildcard consumers — they go to wildcard pass only
+    const consumers = contracts.filter((c) => c.role === 'consumer' && !isGrpcWildcard(c.contractId));
+    const matched = [];
+    const matchedConsumerIds = new Set();
+    const matchedProviderIds = new Set();
+    for (const consumer of consumers) {
+        const matchingKeys = findMatchingKeys(consumer.contractId, index);
+        if (matchingKeys.length === 0)
+            continue;
+        const allMatchingProviders = matchingKeys.flatMap((k) => index.get(k) || []);
+        for (const provider of allMatchingProviders) {
+            if (provider.repo === consumer.repo) {
+                if (!provider.service || !consumer.service || provider.service === consumer.service) {
+                    continue;
+                }
+            }
+            matched.push({
+                from: {
+                    repo: consumer.repo,
+                    service: consumer.service,
+                    symbolUid: consumer.symbolUid,
+                    symbolRef: consumer.symbolRef,
+                },
+                to: {
+                    repo: provider.repo,
+                    service: provider.service,
+                    symbolUid: provider.symbolUid,
+                    symbolRef: provider.symbolRef,
+                },
+                type: consumer.type,
+                contractId: consumer.contractId,
+                matchType: 'exact',
+                confidence: 1.0,
+            });
+            matchedConsumerIds.add(`${consumer.repo}::${consumer.contractId}`);
+            matchedProviderIds.add(`${provider.repo}::${provider.contractId}`);
+        }
+    }
+    // normalUnmatched: contracts that weren't matched in exact pass
+    const normalUnmatched = contracts.filter((c) => {
+        if (isGrpcWildcard(c.contractId))
+            return false; // excluded from exact, handled separately
+        const id = `${c.repo}::${c.contractId}`;
+        return c.role === 'provider' ? !matchedProviderIds.has(id) : !matchedConsumerIds.has(id);
+    });
+    // Re-add gRPC wildcard contracts — they were never in exact matching
+    const grpcWildcards = contracts.filter((c) => isGrpcWildcard(c.contractId));
+    const unmatched = [...normalUnmatched, ...grpcWildcards];
+    return { matched, unmatched };
+}
+export function runWildcardMatch(unmatched, providerIndex) {
+    const wildcardConsumers = unmatched.filter((c) => c.role === 'consumer' && isGrpcWildcard(c.contractId));
+    const matched = [];
+    const matchedConsumerIds = new Set();
+    for (const consumer of wildcardConsumers) {
+        const normalized = normalizeContractId(consumer.contractId);
+        // "grpc::com.example.userservice/*" → "com.example.userservice"
+        // "grpc::userservice/*" → "userservice"
+        const fqService = normalized.slice(normalized.indexOf('::') + 2, -2); // strip "grpc::" and "/*"
+        for (const [key, providers] of providerIndex) {
+            // Only match against non-wildcard gRPC providers (method-level IDs)
+            if (!key.startsWith('grpc::') || key.endsWith('/*'))
+                continue;
+            const afterPrefix = key.slice(6); // strip "grpc::"
+            const slashIdx = afterPrefix.indexOf('/');
+            if (slashIdx < 0)
+                continue;
+            const providerFqService = afterPrefix.slice(0, slashIdx);
+            // Match: exact FQ service, or bare-name match when consumer has no package
+            const isMatch = providerFqService === fqService ||
+                (!fqService.includes('.') && providerFqService.endsWith('.' + fqService));
+            if (!isMatch)
+                continue;
+            for (const provider of providers) {
+                // Skip same-repo same-service (same logic as runExactMatch)
+                if (provider.repo === consumer.repo) {
+                    if (!provider.service || !consumer.service || provider.service === consumer.service) {
+                        continue;
+                    }
+                }
+                matched.push({
+                    from: {
+                        repo: consumer.repo,
+                        service: consumer.service,
+                        symbolUid: consumer.symbolUid,
+                        symbolRef: consumer.symbolRef,
+                    },
+                    to: {
+                        repo: provider.repo,
+                        service: provider.service,
+                        symbolUid: provider.symbolUid,
+                        symbolRef: provider.symbolRef,
+                    },
+                    type: consumer.type,
+                    contractId: consumer.contractId, // consumer's wildcard ID
+                    matchType: 'wildcard',
+                    confidence: Math.min(provider.confidence, consumer.confidence),
+                });
+                matchedConsumerIds.add(`${consumer.repo}::${consumer.contractId}`);
+            }
+        }
+    }
+    const remaining = unmatched.filter((c) => {
+        if (c.role !== 'consumer' || !isGrpcWildcard(c.contractId))
+            return true;
+        return !matchedConsumerIds.has(`${c.repo}::${c.contractId}`);
+    });
+    return { matched, remaining };
+}

package/dist/core/group/normalization.d.ts

@@ -0,0 +1,3 @@
+import type { CrossLink, StoredContract } from './types.js';
+export declare function dedupeContracts(items: StoredContract[]): StoredContract[];
+export declare function dedupeCrossLinks(items: CrossLink[]): CrossLink[];

package/dist/core/group/normalization.js

@@ -0,0 +1,115 @@
+function contractKey(contract) {
+    return [contract.repo, contract.contractId, contract.role, contract.symbolRef.filePath].join('\0');
+}
+function endpointKey(endpoint) {
+    return [
+        endpoint.repo,
+        endpoint.service ?? '',
+        endpoint.symbolRef.filePath,
+        endpoint.symbolRef.name,
+    ].join('\0');
+}
+/**
+ * Score a contract by how much information it carries, so `dedupeContracts`
+ * can prefer the "richer" record when two contracts collide on the same
+ * `(repo, contractId, role, filePath)` key.
+ *
+ * Weights express a priority ordering, not calibrated probabilities:
+ *   +3 — `symbolUid` resolved (tier 1 of the downstream lookup — highest
+ *        signal because it's the strongest anchor for cross-impact traversal
+ *        and the only one that's robust to renames)
+ *   +2 — any of `filePath`, `symbolRef.name`, or `symbolName` that's more
+ *        specific than the contractId itself (tier 2 signal — resolves
+ *        uniquely in most cases and survives across syncs)
+ *   +1 — `service` tag (monorepo attribution — useful but not sufficient
+ *        on its own) or non-manifest origin (auto-extracted contracts are
+ *        preferred over manifest-declared synthetic ones because the former
+ *        are grounded in real source code)
+ *
+ * The absolute numbers don't matter, only their relative ordering.
+ */
+function contractRichness(contract) {
+    let score = 0;
+    if (contract.symbolUid)
+        score += 3;
+    if (contract.symbolRef.filePath)
+        score += 2;
+    if (contract.symbolRef.name && contract.symbolRef.name !== contract.contractId)
+        score += 2;
+    if (contract.symbolName && contract.symbolName !== contract.contractId)
+        score += 2;
+    if (contract.service)
+        score += 1;
+    if (contract.meta.source !== 'manifest')
+        score += 1;
+    return score;
+}
+function mergeContracts(existing, incoming) {
+    const [primary, secondary] = contractRichness(incoming) > contractRichness(existing)
+        ? [incoming, existing]
+        : [existing, incoming];
+    const symbolRefName = primary.symbolRef.name || secondary.symbolRef.name;
+    return {
+        ...secondary,
+        ...primary,
+        symbolUid: primary.symbolUid || secondary.symbolUid,
+        symbolRef: {
+            filePath: primary.symbolRef.filePath || secondary.symbolRef.filePath,
+            name: symbolRefName,
+        },
+        symbolName: primary.symbolName || secondary.symbolName || symbolRefName,
+        confidence: Math.max(existing.confidence, incoming.confidence),
+        service: primary.service ?? secondary.service,
+        meta: { ...secondary.meta, ...primary.meta },
+    };
+}
+function mergeEndpoints(existing, incoming) {
+    return {
+        repo: existing.repo,
+        service: existing.service ?? incoming.service,
+        symbolUid: existing.symbolUid || incoming.symbolUid,
+        symbolRef: {
+            filePath: existing.symbolRef.filePath || incoming.symbolRef.filePath,
+            name: existing.symbolRef.name || incoming.symbolRef.name,
+        },
+    };
+}
+function crossLinkKey(link) {
+    return [
+        link.type,
+        link.contractId,
+        link.matchType,
+        endpointKey(link.from),
+        endpointKey(link.to),
+    ].join('\0');
+}
+export function dedupeContracts(items) {
+    const deduped = new Map();
+    for (const contract of items) {
+        const key = contractKey(contract);
+        const existing = deduped.get(key);
+        deduped.set(key, existing ? mergeContracts(existing, contract) : contract);
+    }
+    return [...deduped.values()];
+}
+export function dedupeCrossLinks(items) {
+    const deduped = new Map();
+    for (const link of items) {
+        const key = crossLinkKey(link);
+        const existing = deduped.get(key);
+        if (!existing) {
+            deduped.set(key, link);
+            continue;
+        }
+        const keepIncoming = link.confidence > existing.confidence;
+        const primary = keepIncoming ? link : existing;
+        const secondary = keepIncoming ? existing : link;
+        deduped.set(key, {
+            ...primary,
+            confidence: Math.max(existing.confidence, link.confidence),
+            from: mergeEndpoints(primary.from, secondary.from),
+            to: mergeEndpoints(primary.to, secondary.to),
+        });
+    }
+    return [...deduped.values()];
+}

package/dist/core/group/resolve-at-member.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Map MCP/CLI `@groupName` or `@groupName/memberPath` to a concrete member path in group.yaml.
+ */
+export declare function resolveAtGroupMemberRepoPath(groupName: string, explicitMemberPath: string | undefined): Promise<{
+    ok: true;
+    repoPath: string;
+} | {
+    ok: false;
+    error: string;
+}>;

package/dist/core/group/resolve-at-member.js

@@ -0,0 +1,31 @@
+/**
+ * Map MCP/CLI `@groupName` or `@groupName/memberPath` to a concrete member path in group.yaml.
+ */
+import { loadGroupConfig } from './config-parser.js';
+import { getDefaultCodragraphDir, getGroupDir } from './storage.js';
+export async function resolveAtGroupMemberRepoPath(groupName, explicitMemberPath) {
+    const trimmed = groupName.trim();
+    if (!trimmed)
+        return { ok: false, error: 'Group name is empty.' };
+    try {
+        const groupDir = getGroupDir(getDefaultCodragraphDir(), trimmed);
+        const config = await loadGroupConfig(groupDir);
+        const keys = Object.keys(config.repos).sort((a, b) => a.localeCompare(b));
+        if (keys.length === 0) {
+            return { ok: false, error: `Group "${trimmed}" has no repos in group.yaml.` };
+        }
+        if (explicitMemberPath !== undefined && explicitMemberPath !== '') {
+            if (!(explicitMemberPath in config.repos)) {
+                return {
+                    ok: false,
+                    error: `Unknown member path "${explicitMemberPath}" in group "${trimmed}". Known paths: ${keys.join(', ')}`,
+                };
+            }
+            return { ok: true, repoPath: explicitMemberPath };
+        }
+        return { ok: true, repoPath: keys[0] };
+    }
+    catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+    }
+}

package/dist/core/group/service-boundary-detector.d.ts

@@ -0,0 +1,8 @@
+export interface ServiceBoundary {
+    servicePath: string;
+    serviceName: string;
+    markers: string[];
+    confidence: number;
+}
+export declare function detectServiceBoundaries(repoPath: string): Promise<ServiceBoundary[]>;
+export declare function assignService(filePath: string, boundaries: ServiceBoundary[]): string | undefined;

package/dist/core/group/service-boundary-detector.js

@@ -0,0 +1,155 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+const SERVICE_MARKERS = [
+    'package.json',
+    'go.mod',
+    'Dockerfile',
+    'pom.xml',
+    'build.gradle',
+    'build.gradle.kts',
+    'Cargo.toml',
+    'pyproject.toml',
+    'requirements.txt',
+    'mix.exs',
+];
+const SOURCE_EXTENSIONS = new Set([
+    '.ts',
+    '.tsx',
+    '.js',
+    '.jsx',
+    '.mjs',
+    '.cjs',
+    '.go',
+    '.java',
+    '.kt',
+    '.kts',
+    '.py',
+    '.pyi',
+    '.rs',
+    '.c',
+    '.cpp',
+    '.h',
+    '.hpp',
+    '.cs',
+    '.rb',
+    '.php',
+    '.swift',
+    '.dart',
+    '.ex',
+    '.exs',
+    '.erl',
+    '.proto',
+]);
+const EXCLUDED_DIRS = new Set([
+    'node_modules',
+    'vendor',
+    'target',
+    'build',
+    'dist',
+    '__pycache__',
+    '.venv',
+    'venv',
+    '.tox',
+    '.mypy_cache',
+    '.gradle',
+    '.mvn',
+    'out',
+    'bin',
+]);
+export async function detectServiceBoundaries(repoPath) {
+    const boundaries = [];
+    await walkForBoundaries(repoPath, repoPath, boundaries);
+    return boundaries;
+}
+async function walkForBoundaries(dir, repoRoot, results) {
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    const isRoot = path.resolve(dir) === path.resolve(repoRoot);
+    const foundMarkers = [];
+    let hasSourceFiles = false;
+    const subdirs = [];
+    for (const entry of entries) {
+        if (entry.name.startsWith('.') || EXCLUDED_DIRS.has(entry.name))
+            continue;
+        if (entry.isDirectory()) {
+            subdirs.push(path.join(dir, entry.name));
+        }
+        else if (entry.isFile()) {
+            if (SERVICE_MARKERS.includes(entry.name)) {
+                foundMarkers.push(entry.name);
+            }
+            const ext = path.extname(entry.name).toLowerCase();
+            if (SOURCE_EXTENSIONS.has(ext)) {
+                hasSourceFiles = true;
+            }
+        }
+    }
+    // Check subdirectories for source files if not found at this level
+    if (!hasSourceFiles && foundMarkers.length > 0) {
+        hasSourceFiles = await hasSourceFilesInSubdirs(subdirs);
+    }
+    if (!isRoot && foundMarkers.length >= 1 && hasSourceFiles) {
+        const relativePath = path.relative(repoRoot, dir).replace(/\\/g, '/');
+        const serviceName = path.basename(dir);
+        const confidence = computeConfidence(foundMarkers.length);
+        results.push({
+            servicePath: relativePath,
+            serviceName,
+            markers: foundMarkers,
+            confidence,
+        });
+    }
+    // Recurse into subdirectories
+    for (const subdir of subdirs) {
+        await walkForBoundaries(subdir, repoRoot, results);
+    }
+}
+async function hasSourceFilesInSubdirs(subdirs) {
+    for (const subdir of subdirs) {
+        let entries;
+        try {
+            entries = await fs.readdir(subdir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.isFile()) {
+                const ext = path.extname(entry.name).toLowerCase();
+                if (SOURCE_EXTENSIONS.has(ext))
+                    return true;
+            }
+            if (entry.isDirectory() && !entry.name.startsWith('.') && !EXCLUDED_DIRS.has(entry.name)) {
+                const deeper = await hasSourceFilesInSubdirs([path.join(subdir, entry.name)]);
+                if (deeper)
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+function computeConfidence(markerCount) {
+    if (markerCount >= 3)
+        return 1.0;
+    if (markerCount === 2)
+        return 0.9;
+    return 0.75;
+}
+export function assignService(filePath, boundaries) {
+    const normalized = filePath.replace(/\\/g, '/');
+    let bestMatch;
+    let bestLength = 0;
+    for (const boundary of boundaries) {
+        const prefix = boundary.servicePath + '/';
+        if (normalized.startsWith(prefix) && boundary.servicePath.length > bestLength) {
+            bestMatch = boundary;
+            bestLength = boundary.servicePath.length;
+        }
+    }
+    return bestMatch?.servicePath;
+}

package/dist/core/group/service.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Group orchestration shared by MCP (LocalBackend) and CLI.
+ * DB access is injected via GroupToolPort so this module stays free of LocalBackend private API.
+ */
+import type { GroupContextResult } from './types.js';
+export interface GroupRepoHandle {
+    id: string;
+    name: string;
+    repoPath: string;
+    storagePath: string;
+    indexedAt?: string;
+    lastCommit?: string;
+}
+export interface GroupToolPort {
+    resolveRepo(repoParam?: string): Promise<GroupRepoHandle>;
+    impact(repo: GroupRepoHandle, params: {
+        target: string;
+        direction: 'upstream' | 'downstream';
+        maxDepth?: number;
+        relationTypes?: string[];
+        includeTests?: boolean;
+        minConfidence?: number;
+    }): Promise<unknown>;
+    query(repo: GroupRepoHandle, params: {
+        query: string;
+        task_context?: string;
+        goal?: string;
+        limit?: number;
+        max_symbols?: number;
+        include_content?: boolean;
+    }): Promise<unknown>;
+    impactByUid(repoId: string, uid: string, direction: string, opts: {
+        maxDepth: number;
+        relationTypes: string[];
+        minConfidence: number;
+        includeTests: boolean;
+    }): Promise<unknown | null>;
+    context(repo: GroupRepoHandle, params: {
+        name?: string;
+        uid?: string;
+        file_path?: string;
+        include_content?: boolean;
+    }): Promise<unknown>;
+}
+export declare class GroupService {
+    private readonly port;
+    constructor(port: GroupToolPort);
+    groupList(params: Record<string, unknown>): Promise<unknown>;
+    groupSync(params: Record<string, unknown>): Promise<unknown>;
+    groupContracts(params: Record<string, unknown>): Promise<unknown>;
+    groupImpact(params: Record<string, unknown>): Promise<unknown>;
+    groupContext(params: Record<string, unknown>): Promise<GroupContextResult>;
+    groupQuery(params: Record<string, unknown>): Promise<unknown>;
+    groupStatus(params: Record<string, unknown>): Promise<unknown>;
+}