@codragraph/cli 2.1.0 → 2.1.4

package/dist/core/group/service.js

@@ -36,6 +36,116 @@ function filterQueryByServicePrefix(queryResult, servicePrefix) {
     const processes = (queryResult.processes || []).filter((p) => allowed.has(String(p.id)));
     return { processes, process_symbols: symbols };
 }
+function normalizeClusterToken(value) {
+    return String(value ?? '')
+        .trim()
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+function featureClusterKey(cluster) {
+    return normalizeClusterToken(cluster.slug || cluster.name || cluster.id || 'unknown');
+}
+function normalizeStringList(value) {
+    if (Array.isArray(value)) {
+        return value
+            .filter((item) => item !== null && item !== undefined)
+            .map((item) => String(item).trim())
+            .filter(Boolean);
+    }
+    if (typeof value !== 'string' || value.trim() === '')
+        return [];
+    return value
+        .replace(/^\[|\]$/g, '')
+        .split(/,(?=(?:[^']*'[^']*')*[^']*$)/)
+        .map((item) => item
+        .trim()
+        .replace(/^['"]|['"]$/g, '')
+        .replace(/\\,/g, ','))
+        .filter(Boolean);
+}
+function clusterOwnsEndpoint(cluster, endpoint) {
+    const entryPointIds = normalizeStringList(cluster.entryPointIds);
+    if (entryPointIds.includes(endpoint.symbolUid))
+        return true;
+    const key = featureClusterKey(cluster);
+    if (!key || key === 'unknown')
+        return false;
+    const filePath = normalizeClusterToken(endpoint.symbolRef.filePath);
+    const symbolName = normalizeClusterToken(endpoint.symbolRef.name);
+    return filePath.includes(key) || symbolName.includes(key);
+}
+function resolveEndpointCluster(endpoint, clusters) {
+    const sameRepo = clusters.filter((cluster) => cluster.repoPath === endpoint.repo);
+    return sameRepo.find((cluster) => clusterOwnsEndpoint(cluster, endpoint));
+}
+function buildCrossRepoClusterLinks(registry, clusters) {
+    if (!registry)
+        return [];
+    const links = [];
+    for (const link of registry.crossLinks) {
+        const sourceCluster = resolveEndpointCluster(link.from, clusters);
+        const targetCluster = resolveEndpointCluster(link.to, clusters);
+        if (!sourceCluster || !targetCluster)
+            continue;
+        links.push({
+            sourceRepo: link.from.repo,
+            sourceService: link.from.service,
+            sourceClusterId: sourceCluster.id,
+            sourceClusterName: String(sourceCluster.name || sourceCluster.slug || sourceCluster.id || ''),
+            targetRepo: link.to.repo,
+            targetService: link.to.service,
+            targetClusterId: targetCluster.id,
+            targetClusterName: String(targetCluster.name || targetCluster.slug || targetCluster.id || ''),
+            contractName: link.contractId,
+            relationship: 'shared-contract',
+            confidence: link.confidence,
+            evidence: [
+                `${link.type}:${link.contractId}`,
+                `${link.from.symbolRef.filePath} -> ${link.to.symbolRef.filePath}`,
+                `match:${link.matchType}`,
+            ],
+        });
+    }
+    return links;
+}
+function aggregateCrossRepoFeatureClusters(clusters, links) {
+    const byKey = new Map();
+    for (const cluster of clusters) {
+        const key = featureClusterKey(cluster);
+        const list = byKey.get(key) ?? [];
+        list.push(cluster);
+        byKey.set(key, list);
+    }
+    return [...byKey.entries()]
+        .map(([key, group]) => {
+        const clusterIds = new Set(group.map((cluster) => String(cluster.id || '')).filter(Boolean));
+        const crossRepoLinks = links.filter((link) => (link.sourceClusterId && clusterIds.has(link.sourceClusterId)) ||
+            (link.targetClusterId && clusterIds.has(link.targetClusterId)));
+        const routes = new Set();
+        const tools = new Set();
+        for (const cluster of group) {
+            normalizeStringList(cluster.routes).forEach((route) => routes.add(route));
+            normalizeStringList(cluster.tools).forEach((tool) => tools.add(tool));
+        }
+        return {
+            key,
+            name: String(group[0]?.name || group[0]?.slug || key),
+            repos: group.map((cluster) => ({
+                repoPath: cluster.repoPath,
+                registryName: cluster.registryName,
+                cluster,
+            })),
+            repoCount: new Set(group.map((cluster) => cluster.repoPath)).size,
+            memberCount: group.reduce((sum, cluster) => sum + Number(cluster.memberCount ?? 0), 0),
+            routes: [...routes].sort(),
+            tools: [...tools].sort(),
+            crossRepoLinks,
+        };
+    })
+        .sort((a, b) => Number(b.memberCount) - Number(a.memberCount));
+}
 function isCrossLink(raw) {
     if (!raw || typeof raw !== 'object')
         return false;
@@ -346,6 +456,256 @@ export class GroupService {
             per_repo: perRepo.map((r) => ({ repo: r.repo, count: r.processes.length })),
         };
     }
+    async groupFeatureClusters(params) {
+        const name = String(params.name ?? '').trim();
+        if (!name)
+            return { error: 'name is required' };
+        const featureClusters = this.port.featureClusters;
+        if (!featureClusters)
+            return { error: 'feature cluster query is unavailable' };
+        const query = typeof params.query === 'string' ? params.query.trim() : '';
+        const limit = typeof params.limit === 'number' && params.limit > 0 ? params.limit : 100;
+        const subgroup = typeof params.subgroup === 'string' ? params.subgroup : undefined;
+        const subgroupExact = params.subgroupExact === true;
+        const groupDir = getGroupDir(getDefaultCodragraphDir(), name);
+        let config;
+        try {
+            config = await loadGroupConfig(groupDir);
+        }
+        catch (err) {
+            if (err instanceof GroupNotFoundError)
+                return { error: `Group "${name}" not found. Run group_list to see configured groups.` };
+            throw err;
+        }
+        const memberEntries = Object.entries(config.repos).filter(([repoPath]) => repoInSubgroup(repoPath, subgroup, subgroupExact));
+        const registryResult = await loadContractRegistryResilient(groupDir);
+        const registry = registryResult.ok ? registryResult.registry : null;
+        const perRepo = await Promise.all(memberEntries.map(async ([repoPath, registryName]) => {
+            try {
+                const repoObj = await this.port.resolveRepo(registryName);
+                const payload = (await featureClusters(repoObj, {
+                    query,
+                    limit,
+                }));
+                const clusters = (payload.clusters ?? []).map((cluster) => ({
+                    ...cluster,
+                    repoPath,
+                    registryName,
+                }));
+                return { repo: repoPath, registryName, clusters };
+            }
+            catch (e) {
+                return {
+                    repo: repoPath,
+                    registryName,
+                    clusters: [],
+                    error: e instanceof Error ? e.message : String(e),
+                };
+            }
+        }));
+        const clusters = perRepo
+            .flatMap((entry) => entry.clusters)
+            .sort((a, b) => Number(b.memberCount ?? 0) - Number(a.memberCount ?? 0))
+            .slice(0, limit);
+        const allClusters = perRepo.flatMap((entry) => entry.clusters);
+        const crossRepoLinks = buildCrossRepoClusterLinks(registry, allClusters);
+        const crossRepoClusters = aggregateCrossRepoFeatureClusters(allClusters, crossRepoLinks);
+        return {
+            group: name,
+            query,
+            clusters,
+            cross_repo_clusters: crossRepoClusters,
+            cross_repo_links: crossRepoLinks,
+            ...(registryResult.ok === true && registryResult.skippedCorrupt > 0
+                ? { skippedCorruptContracts: registryResult.skippedCorrupt }
+                : {}),
+            per_repo: perRepo.map((entry) => ({
+                repo: entry.repo,
+                registryName: entry.registryName,
+                count: entry.clusters.length,
+                ...(entry.error ? { error: entry.error } : {}),
+            })),
+        };
+    }
+    async groupFeatureContext(params) {
+        const name = String(params.name ?? '').trim();
+        const clusterName = String(params.cluster ?? params.target ?? params.feature ?? '').trim();
+        if (!name || !clusterName)
+            return { error: 'name and cluster are required' };
+        const featureContext = this.port.featureContext;
+        if (!featureContext)
+            return { error: 'feature cluster context is unavailable' };
+        const limit = typeof params.limit === 'number' && params.limit > 0 ? params.limit : 100;
+        const subgroup = typeof params.subgroup === 'string' ? params.subgroup : undefined;
+        const subgroupExact = params.subgroupExact === true;
+        const groupDir = getGroupDir(getDefaultCodragraphDir(), name);
+        let config;
+        try {
+            config = await loadGroupConfig(groupDir);
+        }
+        catch (err) {
+            if (err instanceof GroupNotFoundError)
+                return { error: `Group "${name}" not found. Run group_list to see configured groups.` };
+            throw err;
+        }
+        const memberEntries = Object.entries(config.repos).filter(([repoPath]) => repoInSubgroup(repoPath, subgroup, subgroupExact));
+        const registryResult = await loadContractRegistryResilient(groupDir);
+        const registry = registryResult.ok ? registryResult.registry : null;
+        const results = await Promise.all(memberEntries.map(async ([repoPath, registryName]) => {
+            try {
+                const repoObj = await this.port.resolveRepo(registryName);
+                const payload = await featureContext(repoObj, {
+                    name: clusterName,
+                    limit,
+                });
+                return { repoPath, registryName, payload };
+            }
+            catch (e) {
+                return {
+                    repoPath,
+                    registryName,
+                    payload: { error: e instanceof Error ? e.message : String(e) },
+                };
+            }
+        }));
+        const contexts = results.filter((result) => !result.payload?.error);
+        const memberIdsByRepo = new Map();
+        for (const result of contexts) {
+            const payload = result.payload;
+            memberIdsByRepo.set(result.repoPath, new Set((payload.members ?? []).map((member) => String(member.id || '')).filter(Boolean)));
+        }
+        const crossRepoLinks = (registry?.crossLinks ?? [])
+            .filter((link) => {
+            const fromIds = memberIdsByRepo.get(link.from.repo);
+            const toIds = memberIdsByRepo.get(link.to.repo);
+            return fromIds?.has(link.from.symbolUid) || toIds?.has(link.to.symbolUid);
+        })
+            .map((link) => ({
+            sourceRepo: link.from.repo,
+            sourceService: link.from.service,
+            targetRepo: link.to.repo,
+            targetService: link.to.service,
+            contractName: link.contractId,
+            relationship: 'shared-contract',
+            confidence: link.confidence,
+            evidence: [
+                `${link.type}:${link.contractId}`,
+                `${link.from.symbolRef.filePath} -> ${link.to.symbolRef.filePath}`,
+                `match:${link.matchType}`,
+            ],
+        }));
+        return {
+            group: name,
+            cluster: clusterName,
+            results: contexts,
+            cross_repo_links: crossRepoLinks,
+            ...(registryResult.ok === true && registryResult.skippedCorrupt > 0
+                ? { skippedCorruptContracts: registryResult.skippedCorrupt }
+                : {}),
+            errors: results
+                .filter((result) => result.payload?.error)
+                .map((result) => ({
+                repoPath: result.repoPath,
+                registryName: result.registryName,
+                error: result.payload.error,
+            })),
+        };
+    }
+    async groupFeatureImpact(params) {
+        const name = String(params.name ?? '').trim();
+        const clusterName = String(params.cluster ?? params.target ?? params.feature ?? '').trim();
+        if (!name || !clusterName)
+            return { error: 'name and cluster are required' };
+        const featureImpact = this.port.featureImpact;
+        if (!featureImpact)
+            return { error: 'feature cluster impact is unavailable' };
+        const direction = params.direction === 'downstream' || params.direction === 'both'
+            ? params.direction
+            : 'upstream';
+        const limit = typeof params.limit === 'number' && params.limit > 0 ? params.limit : 100;
+        const subgroup = typeof params.subgroup === 'string' ? params.subgroup : undefined;
+        const subgroupExact = params.subgroupExact === true;
+        const groupDir = getGroupDir(getDefaultCodragraphDir(), name);
+        let config;
+        try {
+            config = await loadGroupConfig(groupDir);
+        }
+        catch (err) {
+            if (err instanceof GroupNotFoundError)
+                return { error: `Group "${name}" not found. Run group_list to see configured groups.` };
+            throw err;
+        }
+        const memberEntries = Object.entries(config.repos).filter(([repoPath]) => repoInSubgroup(repoPath, subgroup, subgroupExact));
+        const registryResult = await loadContractRegistryResilient(groupDir);
+        const registry = registryResult.ok ? registryResult.registry : null;
+        const results = await Promise.all(memberEntries.map(async ([repoPath, registryName]) => {
+            try {
+                const repoObj = await this.port.resolveRepo(registryName);
+                const payload = await featureImpact(repoObj, {
+                    name: clusterName,
+                    direction,
+                    limit,
+                });
+                return { repoPath, registryName, payload };
+            }
+            catch (e) {
+                return {
+                    repoPath,
+                    registryName,
+                    payload: { error: e instanceof Error ? e.message : String(e) },
+                };
+            }
+        }));
+        const successfulResults = results.filter((result) => !result.payload?.error);
+        const memberIdsByRepo = new Map();
+        for (const result of successfulResults) {
+            const payload = result.payload;
+            memberIdsByRepo.set(result.repoPath, new Set((payload.contextPack?.members ?? [])
+                .map((member) => String(member.id || ''))
+                .filter(Boolean)));
+        }
+        const crossRepoLinks = (registry?.crossLinks ?? [])
+            .filter((link) => {
+            const fromIds = memberIdsByRepo.get(link.from.repo);
+            const toIds = memberIdsByRepo.get(link.to.repo);
+            return fromIds?.has(link.from.symbolUid) || toIds?.has(link.to.symbolUid);
+        })
+            .map((link) => ({
+            sourceRepo: link.from.repo,
+            sourceService: link.from.service,
+            targetRepo: link.to.repo,
+            targetService: link.to.service,
+            contractName: link.contractId,
+            relationship: 'shared-contract',
+            confidence: link.confidence,
+            evidence: [
+                `${link.type}:${link.contractId}`,
+                `${link.from.symbolRef.filePath} -> ${link.to.symbolRef.filePath}`,
+                `match:${link.matchType}`,
+            ],
+        }));
+        return {
+            group: name,
+            cluster: clusterName,
+            direction,
+            results: successfulResults,
+            cross_repo_links: crossRepoLinks,
+            summary: {
+                repos: successfulResults.length,
+                crossRepoLinks: crossRepoLinks.length,
+            },
+            ...(registryResult.ok === true && registryResult.skippedCorrupt > 0
+                ? { skippedCorruptContracts: registryResult.skippedCorrupt }
+                : {}),
+            errors: results
+                .filter((result) => result.payload?.error)
+                .map((result) => ({
+                repoPath: result.repoPath,
+                registryName: result.registryName,
+                error: result.payload.error,
+            })),
+        };
+    }
     async groupStatus(params) {
         const name = String(params.name ?? '').trim();
         if (!name)

package/dist/core/ingestion/emit-references.d.ts

@@ -15,7 +15,7 @@
  *   - `confidence`: the pre-computed confidence from the Reference record.
  *   - `reason`: human-readable summary (`"scope-resolution: call | confidence 0.75"`).
  *   - `evidence`: the full `ResolutionEvidence[]` trace — additive graph
- *     property (see `GraphRelationship.evidence` in codragraph-shared),
+ *     property (see `GraphRelationship.evidence` in @codragraph/shared),
  *     so queries that don't know about it are unaffected.
  *   - `step`: carries the reference's access-kind discriminant when
  *     available (`1` for read, `2` for write) so `ACCESSES` edges retain

package/dist/core/ingestion/emit-references.js

@@ -15,7 +15,7 @@
  *   - `confidence`: the pre-computed confidence from the Reference record.
  *   - `reason`: human-readable summary (`"scope-resolution: call | confidence 0.75"`).
  *   - `evidence`: the full `ResolutionEvidence[]` trace — additive graph
- *     property (see `GraphRelationship.evidence` in codragraph-shared),
+ *     property (see `GraphRelationship.evidence` in @codragraph/shared),
  *     so queries that don't know about it are unaffected.
  *   - `step`: carries the reference's access-kind discriminant when
  *     available (`1` for read, `2` for write) so `ACCESSES` edges retain

package/dist/core/ingestion/feature-cluster-processor.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Feature Cluster Processor
+ *
+ * Builds a stable, human-facing feature layer over the raw code graph.
+ * Communities are graph-algorithm clusters; FeatureCluster nodes are
+ * product/domain clusters such as Settings, AI, Auth, Billing, MCP, or
+ * Ingestion. Agents can query this layer first to land directly on the
+ * files, symbols, and line ranges that matter for a task.
+ */
+import type { FeatureClusterKind } from '../../_shared/index.js';
+import { KnowledgeGraph } from '../graph/types.js';
+export interface FeatureClusterNode {
+    id: string;
+    name: string;
+    slug: string;
+    featureKind: FeatureClusterKind;
+    summary: string;
+    description: string;
+    repo?: string;
+    service?: string;
+    signals: string[];
+    memberCount: number;
+    entryPointIds: string[];
+    routes: string[];
+    tools: string[];
+    testCoverageHints: string[];
+    lastIndexedCommit?: string;
+    confidence: number;
+    memberIds: string[];
+}
+export interface FeatureClusterMembership {
+    nodeId: string;
+    clusterId: string;
+    confidence: number;
+    signals: string[];
+}
+export interface FeatureClusterDependency {
+    sourceClusterId: string;
+    targetClusterId: string;
+    edgeCount: number;
+    relationshipTypes: string[];
+    confidence: number;
+}
+export interface FeatureClusterDetectionResult {
+    clusters: FeatureClusterNode[];
+    memberships: FeatureClusterMembership[];
+    dependencies: FeatureClusterDependency[];
+    stats: {
+        totalClusters: number;
+        totalMemberships: number;
+        totalDependencies: number;
+        nodesProcessed: number;
+    };
+}
+export interface FeatureClusterConfig {
+    minMembers: number;
+    maxClusters: number;
+    repo?: string;
+    service?: string;
+    lastIndexedCommit?: string;
+}
+export declare const processFeatureClusters: (knowledgeGraph: KnowledgeGraph, onProgress?: (message: string, progress: number) => void, config?: Partial<FeatureClusterConfig>) => Promise<FeatureClusterDetectionResult>;