@codragraph/cli 2.1.0 → 2.1.1

package/dist/core/ingestion/model/semantic-model.js

@@ -9,7 +9,7 @@
  *
  * ## Dependency direction
  *
- *     codragraph-shared (NodeLabel)             — leaf
+ *     @codragraph/shared (NodeLabel)            — leaf
  *          ↑
  *     symbol-table.ts                         — pure file/callable index
  *          ↑

package/dist/core/ingestion/model/symbol-table.d.ts

@@ -17,7 +17,7 @@
  *
  * Dependency direction (strictly enforced):
  *
- *     codragraph-shared (NodeLabel)       — leaf type
+ *     @codragraph/shared (NodeLabel)      — leaf type
  *          ↑
  *     symbol-table.ts                   — THIS FILE (pure storage)
  *          ↑

package/dist/core/ingestion/model/symbol-table.js

@@ -17,7 +17,7 @@
  *
  * Dependency direction (strictly enforced):
  *
- *     codragraph-shared (NodeLabel)       — leaf type
+ *     @codragraph/shared (NodeLabel)      — leaf type
  *          ↑
  *     symbol-table.ts                   — THIS FILE (pure storage)
  *          ↑

package/dist/core/ingestion/pipeline-phases/feature-clusters.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Phase: featureClusters
+ *
+ * Creates human-facing FeatureCluster nodes above algorithmic Community nodes.
+ * This is the layer agents query for product/domain areas such as Settings,
+ * AI, Auth, MCP, or Ingestion before drilling into exact symbols.
+ *
+ * @deps    processes, structure
+ * @reads   graph (all nodes and relationships)
+ * @writes  graph (FeatureCluster nodes, FEATURE_MEMBER_OF, FEATURE_DEPENDS_ON)
+ */
+import type { PipelinePhase } from './types.js';
+import { type FeatureClusterDetectionResult } from '../feature-cluster-processor.js';
+export interface FeatureClustersOutput {
+    featureClusterResult: FeatureClusterDetectionResult;
+}
+export declare const featureClustersPhase: PipelinePhase<FeatureClustersOutput>;

package/dist/core/ingestion/pipeline-phases/feature-clusters.js

@@ -0,0 +1,88 @@
+/**
+ * Phase: featureClusters
+ *
+ * Creates human-facing FeatureCluster nodes above algorithmic Community nodes.
+ * This is the layer agents query for product/domain areas such as Settings,
+ * AI, Auth, MCP, or Ingestion before drilling into exact symbols.
+ *
+ * @deps    processes, structure
+ * @reads   graph (all nodes and relationships)
+ * @writes  graph (FeatureCluster nodes, FEATURE_MEMBER_OF, FEATURE_DEPENDS_ON)
+ */
+import { getPhaseOutput } from './types.js';
+import { processFeatureClusters, } from '../feature-cluster-processor.js';
+import { generateId } from '../../../lib/utils.js';
+import { isDev } from '../utils/env.js';
+export const featureClustersPhase = {
+    name: 'featureClusters',
+    deps: ['processes', 'structure'],
+    async execute(ctx, deps) {
+        const { totalFiles } = getPhaseOutput(deps, 'structure');
+        ctx.onProgress({
+            phase: 'feature_clusters',
+            percent: 99,
+            message: 'Building feature clusters...',
+            stats: { filesProcessed: totalFiles, totalFiles, nodesCreated: ctx.graph.nodeCount },
+        });
+        const featureClusterResult = await processFeatureClusters(ctx.graph, (message, progress) => {
+            ctx.onProgress({
+                phase: 'feature_clusters',
+                percent: Math.round(99 + progress * 0.009),
+                message,
+                stats: { filesProcessed: totalFiles, totalFiles, nodesCreated: ctx.graph.nodeCount },
+            });
+        }, {
+            repo: ctx.options?.featureClusterRepo,
+            lastIndexedCommit: ctx.options?.lastIndexedCommit,
+        });
+        if (isDev) {
+            console.log(`Feature clustering: ${featureClusterResult.stats.totalClusters} clusters, ${featureClusterResult.stats.totalMemberships} memberships`);
+        }
+        featureClusterResult.clusters.forEach((cluster) => {
+            ctx.graph.addNode({
+                id: cluster.id,
+                label: 'FeatureCluster',
+                properties: {
+                    name: cluster.name,
+                    filePath: '',
+                    slug: cluster.slug,
+                    featureKind: cluster.featureKind,
+                    summary: cluster.summary,
+                    description: cluster.description,
+                    repo: cluster.repo,
+                    service: cluster.service,
+                    signals: cluster.signals,
+                    memberCount: cluster.memberCount,
+                    entryPointIds: cluster.entryPointIds,
+                    routes: cluster.routes,
+                    tools: cluster.tools,
+                    testCoverageHints: cluster.testCoverageHints,
+                    lastIndexedCommit: cluster.lastIndexedCommit,
+                    confidence: cluster.confidence,
+                    source: 'heuristic',
+                },
+            });
+        });
+        featureClusterResult.memberships.forEach((membership) => {
+            ctx.graph.addRelationship({
+                id: generateId('FEATURE_MEMBER_OF', `${membership.nodeId}->${membership.clusterId}`),
+                sourceId: membership.nodeId,
+                targetId: membership.clusterId,
+                type: 'FEATURE_MEMBER_OF',
+                confidence: membership.confidence,
+                reason: membership.signals.join('|'),
+            });
+        });
+        featureClusterResult.dependencies.forEach((dependency) => {
+            ctx.graph.addRelationship({
+                id: generateId('FEATURE_DEPENDS_ON', `${dependency.sourceClusterId}->${dependency.targetClusterId}`),
+                sourceId: dependency.sourceClusterId,
+                targetId: dependency.targetClusterId,
+                type: 'FEATURE_DEPENDS_ON',
+                confidence: dependency.confidence,
+                reason: `member-dependency|edges:${dependency.edgeCount}|types:${dependency.relationshipTypes.join(',')}`,
+            });
+        });
+        return { featureClusterResult };
+    },
+};

package/dist/core/ingestion/pipeline-phases/index.d.ts

@@ -17,6 +17,7 @@ export { scopeResolutionPhase, type ScopeResolutionOutput, } from '../scope-reso
 export { mroPhase, type MROOutput } from './mro.js';
 export { communitiesPhase, type CommunitiesOutput } from './communities.js';
 export { processesPhase, type ProcessesOutput } from './processes.js';
+export { featureClustersPhase, type FeatureClustersOutput } from './feature-clusters.js';
 export { runPipeline } from './runner.js';
 export type { PipelinePhase, PipelineContext, PhaseResult } from './types.js';
 export { getPhaseOutput } from './types.js';

package/dist/core/ingestion/pipeline-phases/index.js

@@ -18,6 +18,7 @@ export { scopeResolutionPhase, } from '../scope-resolution/pipeline/phase.js';
 export { mroPhase } from './mro.js';
 export { communitiesPhase } from './communities.js';
 export { processesPhase } from './processes.js';
+export { featureClustersPhase } from './feature-clusters.js';
 // ── Infrastructure ─────────────────────────────────────────────────────────
 export { runPipeline } from './runner.js';
 export { getPhaseOutput } from './types.js';

package/dist/core/ingestion/pipeline.d.ts

@@ -21,6 +21,10 @@ export interface PipelineOptions {
     skipGraphPhases?: boolean;
     /** Force sequential parsing (no worker pool). Useful for testing the sequential path. */
     skipWorkers?: boolean;
+    /** Repo label written onto FeatureCluster metadata. */
+    featureClusterRepo?: string;
+    /** Indexed source commit written onto FeatureCluster metadata. */
+    lastIndexedCommit?: string;
     /**
      * @internal Test-only override for worker-pool gating thresholds.
      * When unset, production defaults apply (15 files OR 512 KB total bytes).

package/dist/core/ingestion/pipeline.js

@@ -15,15 +15,16 @@
  * See ARCHITECTURE.md for the full phase dependency diagram.
  */
 import { createKnowledgeGraph } from '../graph/graph.js';
-import { runPipeline, getPhaseOutput, scanPhase, structurePhase, markdownPhase, cobolPhase, parsePhase, routesPhase, toolsPhase, ormPhase, crossFilePhase, scopeResolutionPhase, mroPhase, communitiesPhase, processesPhase, } from './pipeline-phases/index.js';
+import { runPipeline, getPhaseOutput, scanPhase, structurePhase, markdownPhase, cobolPhase, parsePhase, routesPhase, toolsPhase, ormPhase, crossFilePhase, scopeResolutionPhase, mroPhase, communitiesPhase, processesPhase, featureClustersPhase, } from './pipeline-phases/index.js';
 // ── Phase registry ─────────────────────────────────────────────────────────
 /**
  * All pipeline phases with their dependency relationships.
  *
  * Phase dependency graph:
  *
- *   scan → structure → [markdown, cobol] → parse → [routes, tools, orm]
- *     → crossFile → mro → communities → processes
+ *   scan -> structure -> [markdown, cobol] -> parse -> [routes, tools, orm]
+ *     -> crossFile -> scopeResolution -> mro -> communities -> processes
+ *     -> featureClusters
  *
  * To add a new phase: create a file in pipeline-phases/, export the phase
  * object, and add it to the appropriate position in this array.
@@ -42,7 +43,7 @@ function buildPhaseList(options) {
         scopeResolutionPhase,
     ];
     if (!options?.skipGraphPhases) {
-        phases.push(mroPhase, communitiesPhase, processesPhase);
+        phases.push(mroPhase, communitiesPhase, processesPhase, featureClustersPhase);
     }
     return phases;
 }
@@ -62,15 +63,17 @@ export const runPipelineFromRepo = async (repoPath, onProgress, options) => {
     const { totalFiles, usedWorkerPool } = getPhaseOutput(results, 'parse');
     let communityResult;
     let processResult;
+    let featureClusterResult;
     if (!options?.skipGraphPhases) {
         communityResult = getPhaseOutput(results, 'communities').communityResult;
         processResult = getPhaseOutput(results, 'processes').processResult;
+        featureClusterResult = getPhaseOutput(results, 'featureClusters').featureClusterResult;
     }
     onProgress({
         phase: 'complete',
         percent: 100,
         message: communityResult && processResult
-            ? `Graph complete! ${communityResult.stats.totalCommunities} communities, ${processResult.stats.totalProcesses} processes detected.`
+            ? `Graph complete! ${communityResult.stats.totalCommunities} communities, ${processResult.stats.totalProcesses} processes, ${featureClusterResult?.stats.totalClusters ?? 0} feature clusters detected.`
             : 'Graph complete! (graph phases skipped)',
         stats: {
             filesProcessed: totalFiles,
@@ -84,6 +87,7 @@ export const runPipelineFromRepo = async (repoPath, onProgress, options) => {
         totalFileCount: totalFiles,
         communityResult,
         processResult,
+        featureClusterResult,
         usedWorkerPool,
     };
 };

package/dist/core/run-analyze.d.ts

@@ -63,6 +63,7 @@ export interface AnalyzeResult {
         nodes?: number;
         edges?: number;
         communities?: number;
+        featureClusters?: number;
         processes?: number;
         embeddings?: number;
     };

package/dist/core/run-analyze.js

@@ -31,6 +31,7 @@ export const PHASE_LABELS = {
     heritage: 'Extracting inheritance',
     communities: 'Detecting communities',
     processes: 'Detecting processes',
+    feature_clusters: 'Building feature clusters',
     complete: 'Pipeline complete',
     cgdb: 'Loading into LadybugDB',
     fts: 'Creating search indexes',
@@ -129,10 +130,10 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
     // ── Early-return: already up to date ──────────────────────────────
     // Schema-version mismatch forces a full re-analyze regardless of commit
     // equality: existing 1.7.x indexes have no `schemaVersion` field at all,
-    // and 1.8+ readers expect every node table to carry a `contentEncoding`
-    // column (RFC 0001 Phase 2). LadybugDB ALTER on existing tables is not
-    // validated end-to-end yet, so the supported migration path is
-    // re-analyze → fresh CREATE NODE TABLE.
+    // and current readers expect contentEncoding plus rich FeatureCluster
+    // context-pack columns. LadybugDB ALTER on existing tables is not validated
+    // end-to-end yet, so the supported migration path is re-analyze via a fresh
+    // CREATE NODE TABLE.
     const schemaUpToDate = !!existingMeta && (existingMeta.schemaVersion ?? 0) >= INDEX_SCHEMA_VERSION;
     if (existingMeta &&
         schemaUpToDate &&
@@ -150,7 +151,7 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
     }
     if (existingMeta && !schemaUpToDate) {
         log(`Index schema version ${existingMeta.schemaVersion ?? '<missing>'} is older than ` +
-            `${INDEX_SCHEMA_VERSION} (RFC 0001 Phase 2 — adds contentEncoding column). ` +
+            `${INDEX_SCHEMA_VERSION} (FeatureCluster context-pack schema). ` +
             `Re-analyzing.`);
     }
     // ── Cache embeddings from existing index before rebuild ────────────
@@ -175,10 +176,14 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         }
     }
     // ── Phase 1: Full Pipeline (0–60%) ────────────────────────────────
+    const repoNameForFeatureClusters = options.registryName ?? getInferredRepoName(repoPath) ?? path.basename(repoPath);
     const pipelineResult = await runPipelineFromRepo(repoPath, (p) => {
         const phaseLabel = PHASE_LABELS[p.phase] || p.phase;
         const scaled = Math.round(p.percent * 0.6);
         progress(p.phase, scaled, phaseLabel);
+    }, {
+        featureClusterRepo: repoNameForFeatureClusters,
+        lastIndexedCommit: currentCommit || undefined,
     });
     // ── Phase 2: LadybugDB (60–85%) ──────────────────────────────────
     progress('cgdb', 60, 'Loading into LadybugDB...');
@@ -334,6 +339,7 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
                 nodes: stats.nodes,
                 edges: stats.edges,
                 communities: pipelineResult.communityResult?.stats.totalCommunities,
+                featureClusters: pipelineResult.featureClusterResult?.stats.totalClusters,
                 processes: pipelineResult.processResult?.stats.totalProcesses,
                 embeddings: embeddingCount,
             },
@@ -372,7 +378,7 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
                 nodes: stats.nodes,
                 edges: stats.edges,
                 communities: pipelineResult.communityResult?.stats.totalCommunities,
-                clusters: aggregatedClusterCount,
+                clusters: pipelineResult.featureClusterResult?.stats.totalClusters ?? aggregatedClusterCount,
                 processes: pipelineResult.processResult?.stats.totalProcesses,
             }, undefined, { skipAgentsMd: options.skipAgentsMd, noStats: options.noStats });
         }

package/dist/mcp/core/embedder.js

@@ -6,6 +6,8 @@
  */
 import { pipeline, env } from '@huggingface/transformers';
 import { isHttpMode, getHttpDimensions, httpEmbedQuery, } from '../../core/embeddings/http-client.js';
+import { homedir } from 'os';
+import { join } from 'path';
 import { silenceStdout, restoreStdout, realStderrWrite } from '../../core/cgdb/pool-adapter.js';
 // Model config
 const MODEL_ID = 'Snowflake/snowflake-arctic-embed-xs';
@@ -33,8 +35,9 @@ export const initEmbedder = async () => {
             // Default cache to user-writable location. transformers.js defaults to
             // ./node_modules/.cache inside its own install dir, which is unwritable
             // when codragraph is installed globally (e.g. /usr/lib/node_modules/).
-            // Respect HF_HOME if set, otherwise fall back to ~/.cache/huggingface.
-            env.cacheDir = process.env.HF_HOME ?? `${process.env.HOME}/.cache/huggingface`;
+            // Respect HF_HOME if set, otherwise fall back to a user-writable cache
+            // path using Node's OS-aware home directory resolution.
+            env.cacheDir = process.env.HF_HOME ?? join(homedir(), '.cache', 'huggingface');
             console.error('CodraGraph: Loading embedding model (first search may take a moment)...');
             // Try GPU first (DirectML on Windows, CUDA on Linux), fall back to CPU
             const isWindows = process.platform === 'win32';

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

@@ -323,6 +323,18 @@ export declare class LocalBackend {
      * Query clusters (communities) directly from graph.
      * Used by getClustersResource — avoids legacy overview() dispatch.
      */
+    /**
+     * Query feature clusters directly from graph.
+     * FeatureCluster is the human-facing project area layer above Communities.
+     */
+    queryFeatureClusters(repoName?: string, limit?: number, query?: string): Promise<{
+        clusters: any[];
+    }>;
+    /**
+     * Query one feature cluster with members, dependencies, and process links.
+     */
+    queryFeatureContext(name: string, repoName?: string, limit?: number): Promise<any>;
+    queryFeatureImpact(name: string, repoName?: string, direction?: 'upstream' | 'downstream' | 'both', limit?: number): Promise<any>;
     queryClusters(repoName?: string, limit?: number): Promise<{
         clusters: any[];
     }>;