@codragraph/cli 2.1.0 → 2.1.1

package/dist/cli/index.js

@@ -135,6 +135,43 @@ program
     .description('Execute raw Cypher query against the knowledge graph')
     .option('-r, --repo <name>', 'Target repository')
     .action(createLazyAction(() => import('./tool.js'), 'cypherCommand'));
+program
+    .command('feature-clusters')
+    .description('List human-facing feature clusters for targeted context building')
+    .option('-r, --repo <name>', 'Target repository')
+    .option('-l, --limit <n>', 'Max feature clusters to return (default: 100)')
+    .action(createLazyAction(() => import('./tool.js'), 'featureClustersCommand'));
+program
+    .command('cluster-query [query]')
+    .description('Alias for feature-clusters: list product/domain clusters')
+    .option('-r, --repo <name>', 'Target repository')
+    .option('-l, --limit <n>', 'Max feature clusters to return (default: 100)')
+    .action(createLazyAction(() => import('./tool.js'), 'clusterQueryCommand'));
+program
+    .command('feature-context <name>')
+    .description('Show members, line ranges, and dependencies for a feature cluster')
+    .option('-r, --repo <name>', 'Target repository')
+    .option('-l, --limit <n>', 'Max members to return (default: 100)')
+    .action(createLazyAction(() => import('./tool.js'), 'featureContextCommand'));
+program
+    .command('cluster-context <name>')
+    .description('Alias for feature-context: show a feature cluster context pack')
+    .option('-r, --repo <name>', 'Target repository')
+    .option('-l, --limit <n>', 'Max members to return (default: 100)')
+    .action(createLazyAction(() => import('./tool.js'), 'clusterContextCommand'));
+program
+    .command('context-pack <name>')
+    .description('Generate the compact agent context pack for a feature cluster')
+    .option('-r, --repo <name>', 'Target repository')
+    .option('-l, --limit <n>', 'Max members to return (default: 100)')
+    .action(createLazyAction(() => import('./tool.js'), 'contextPackCommand'));
+program
+    .command('cluster-impact <name>')
+    .description('Feature-level blast radius analysis for a cluster')
+    .option('-d, --direction <dir>', 'upstream, downstream, or both', 'upstream')
+    .option('-r, --repo <name>', 'Target repository')
+    .option('-l, --limit <n>', 'Max context-pack members to include (default: 100)')
+    .action(createLazyAction(() => import('./tool.js'), 'clusterImpactCommand'));
 program
     .command('detect-changes')
     .alias('detect_changes')

package/dist/cli/setup.js

@@ -11,12 +11,16 @@ import os from 'os';
 import { execFile, execFileSync } from 'child_process';
 import { promisify } from 'util';
 import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
 import { glob } from 'glob';
 import { parseTree, modify, applyEdits } from 'jsonc-parser';
 import { getGlobalDir } from '../storage/repo-manager.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const execFileAsync = promisify(execFile);
+const require = createRequire(import.meta.url);
+const pkg = require('../../package.json');
+const CLI_PACKAGE_SPEC = `@codragraph/cli@${pkg.version}`;
 /**
  * Resolve the absolute path to the `codragraph` binary if it's installed
  * globally (or via npm -g / yarn global). Returns null when not found.
@@ -59,7 +63,7 @@ function resolveCodragraphBin() {
  * The MCP server entry for all editors.
  *
  * Prefers the globally-installed `codragraph` binary (starts in ~1 s) over
- * `npx -y @codragraph/cli@latest` (cold-cache install of native deps can take
+ * `npx -y @codragraph/cli@<version>` (cold-cache install of native deps can take
  * >60 s, exceeding Claude Code's 30 s MCP connection timeout).
  *
  * Falls back to npx when the binary isn't on PATH — e.g. first-time
@@ -84,12 +88,12 @@ function getMcpEntry() {
     if (process.platform === 'win32') {
         return {
             command: 'cmd',
-            args: ['/c', 'npx', '-y', '@codragraph/cli@latest', 'mcp'],
+            args: ['/c', 'npx', '-y', CLI_PACKAGE_SPEC, 'mcp'],
         };
     }
     return {
         command: 'npx',
-        args: ['-y', '@codragraph/cli@latest', 'mcp'],
+        args: ['-y', CLI_PACKAGE_SPEC, 'mcp'],
     };
 }
 /**
@@ -107,10 +111,10 @@ function getOpenCodeMcpEntry() {
     if (process.platform === 'win32') {
         return {
             type: 'local',
-            command: ['cmd', '/c', 'npx', '-y', '@codragraph/cli@latest', 'mcp'],
+            command: ['cmd', '/c', 'npx', '-y', CLI_PACKAGE_SPEC, 'mcp'],
         };
     }
-    return { type: 'local', command: ['npx', '-y', '@codragraph/cli@latest', 'mcp'] };
+    return { type: 'local', command: ['npx', '-y', CLI_PACKAGE_SPEC, 'mcp'] };
 }
 /**
  * Merge codragraph entry into an existing MCP config JSON object.

package/dist/cli/tool.d.ts

@@ -36,6 +36,31 @@ export declare function impactCommand(target: string, options?: {
 export declare function cypherCommand(query: string, options?: {
     repo?: string;
 }): Promise<void>;
+export declare function featureClustersCommand(options?: {
+    repo?: string;
+    limit?: string;
+}): Promise<void>;
+export declare function clusterQueryCommand(query?: string, options?: {
+    repo?: string;
+    limit?: string;
+}): Promise<void>;
+export declare function featureContextCommand(name: string, options?: {
+    repo?: string;
+    limit?: string;
+}): Promise<void>;
+export declare function clusterContextCommand(name: string, options?: {
+    repo?: string;
+    limit?: string;
+}): Promise<void>;
+export declare function contextPackCommand(name: string, options?: {
+    repo?: string;
+    limit?: string;
+}): Promise<void>;
+export declare function clusterImpactCommand(name: string, options?: {
+    direction?: string;
+    repo?: string;
+    limit?: string;
+}): Promise<void>;
 export declare function detectChangesCommand(options?: {
     scope?: string;
     baseRef?: string;

package/dist/cli/tool.js

@@ -128,6 +128,80 @@ export async function cypherCommand(query, options) {
     });
     output(result);
 }
+export async function featureClustersCommand(options) {
+    const backend = await getBackend();
+    const result = await backend.callTool('feature_clusters', {
+        repo: options?.repo,
+        limit: options?.limit ? parseInt(options.limit, 10) : undefined,
+    });
+    output(result);
+}
+export async function clusterQueryCommand(query, options) {
+    const backend = await getBackend();
+    const result = await backend.callTool('cluster_query', {
+        query,
+        repo: options?.repo,
+        limit: options?.limit ? parseInt(options.limit, 10) : undefined,
+    });
+    output(result);
+}
+export async function featureContextCommand(name, options) {
+    if (!name?.trim()) {
+        console.error('Usage: codragraph feature-context <name>');
+        process.exit(1);
+    }
+    const backend = await getBackend();
+    const result = await backend.callTool('feature_context', {
+        name,
+        repo: options?.repo,
+        limit: options?.limit ? parseInt(options.limit, 10) : undefined,
+    });
+    output(result);
+    emitTokenStats(result);
+}
+export async function clusterContextCommand(name, options) {
+    if (!name?.trim()) {
+        console.error('Usage: codragraph cluster-context <name>');
+        process.exit(1);
+    }
+    const backend = await getBackend();
+    const result = await backend.callTool('cluster_context', {
+        name,
+        repo: options?.repo,
+        limit: options?.limit ? parseInt(options.limit, 10) : undefined,
+    });
+    output(result);
+    emitTokenStats(result);
+}
+export async function contextPackCommand(name, options) {
+    if (!name?.trim()) {
+        console.error('Usage: codragraph context-pack <name>');
+        process.exit(1);
+    }
+    const backend = await getBackend();
+    const result = await backend.callTool('context_pack', {
+        name,
+        repo: options?.repo,
+        limit: options?.limit ? parseInt(options.limit, 10) : undefined,
+    });
+    output(result);
+    emitTokenStats(result);
+}
+export async function clusterImpactCommand(name, options) {
+    if (!name?.trim()) {
+        console.error('Usage: codragraph cluster-impact <name>');
+        process.exit(1);
+    }
+    const backend = await getBackend();
+    const result = await backend.callTool('cluster_impact', {
+        name,
+        direction: options?.direction,
+        repo: options?.repo,
+        limit: options?.limit ? parseInt(options.limit, 10) : undefined,
+    });
+    output(result);
+    emitTokenStats(result);
+}
 function formatDetectChangesResult(result) {
     if (result?.error)
         return `Error: ${result.error}`;

package/dist/config/supported-languages.d.ts

@@ -1,12 +1,12 @@
 /**
- * Re-export SupportedLanguages from codragraph-shared (single source of truth).
+ * Re-export SupportedLanguages from @codragraph/shared (single source of truth).
  *
  * HOW TO ADD A NEW LANGUAGE:
  *
- * 1. Add the enum member in codragraph-shared/src/languages.ts
+ * 1. Add the enum member in packages/shared/src/languages.ts
  * 2. Run `tsc --noEmit` — compiler errors guide you to every dispatch table
  * 3. Use the checklist in each ingestion file for what to add
- * 4. Add tree-sitter-<lang> to codragraph/package.json dependencies
+ * 4. Add tree-sitter-<lang> to packages/core/package.json dependencies
  * 5. Add file extension mapping in utils.ts getLanguageFromFilename()
  * 6. Run full test suite
  */

package/dist/config/supported-languages.js

@@ -1,12 +1,12 @@
 /**
- * Re-export SupportedLanguages from codragraph-shared (single source of truth).
+ * Re-export SupportedLanguages from @codragraph/shared (single source of truth).
  *
  * HOW TO ADD A NEW LANGUAGE:
  *
- * 1. Add the enum member in codragraph-shared/src/languages.ts
+ * 1. Add the enum member in packages/shared/src/languages.ts
  * 2. Run `tsc --noEmit` — compiler errors guide you to every dispatch table
  * 3. Use the checklist in each ingestion file for what to add
- * 4. Add tree-sitter-<lang> to codragraph/package.json dependencies
+ * 4. Add tree-sitter-<lang> to packages/core/package.json dependencies
  * 5. Add file extension mapping in utils.ts getLanguageFromFilename()
  * 6. Run full test suite
  */

package/dist/core/cgdb/cgdb-adapter.js

@@ -507,7 +507,8 @@ const getCopyQuery = (table, filePath) => {
     // RFC 0001 Phase 2: every content-bearing table also lists
     // `contentEncoding` immediately after `content` to match the schema +
     // CSV layout. Tables without a content column (Folder, Community,
-    // Process, Route, Tool) are unchanged.
+    // Process, Route, Tool) are unchanged. FeatureCluster carries rich metadata
+    // but still has no content/file snippet column.
     if (table === 'File') {
         return `COPY ${t}(id, name, filePath, content, contentEncoding) FROM "${filePath}" ${COPY_CSV_OPTS}`;
     }
@@ -520,6 +521,9 @@ const getCopyQuery = (table, filePath) => {
     if (table === 'Process') {
         return `COPY ${t}(id, label, heuristicLabel, processType, stepCount, communities, entryPointId, terminalId) FROM "${filePath}" ${COPY_CSV_OPTS}`;
     }
+    if (table === 'FeatureCluster') {
+        return `COPY ${t}(id, name, slug, featureKind, summary, description, repo, service, signals, memberCount, entryPointIds, routes, tools, testCoverageHints, lastIndexedCommit, confidence, source) FROM "${filePath}" ${COPY_CSV_OPTS}`;
+    }
     if (table === 'Section') {
         return `COPY ${t}(id, name, filePath, startLine, endLine, level, content, contentEncoding, description) FROM "${filePath}" ${COPY_CSV_OPTS}`;
     }
@@ -557,6 +561,9 @@ export const insertNodeToCgdb = async (label, properties, dbPath) => {
                 return 'NULL';
             if (typeof v === 'number')
                 return String(v);
+            if (Array.isArray(v)) {
+                return `[${v.map((item) => `'${String(item).replace(/\\/g, '\\\\').replace(/'/g, "''")}'`).join(',')}]`;
+            }
             // Escape backslashes first (for Windows paths), then single quotes
             return `'${String(v).replace(/\\/g, '\\\\').replace(/'/g, "''").replace(/\n/g, '\\n').replace(/\r/g, '\\r')}'`;
         };
@@ -575,6 +582,9 @@ export const insertNodeToCgdb = async (label, properties, dbPath) => {
                 : '';
             query = `CREATE (n:Section {id: ${escapeValue(properties.id)}, name: ${escapeValue(properties.name)}, filePath: ${escapeValue(properties.filePath)}, startLine: ${properties.startLine || 0}, endLine: ${properties.endLine || 0}, level: ${properties.level || 1}, content: ${escapeValue(properties.content || '')}${descPart}})`;
         }
+        else if (label === 'FeatureCluster') {
+            query = `CREATE (n:FeatureCluster {id: ${escapeValue(properties.id)}, name: ${escapeValue(properties.name)}, slug: ${escapeValue(properties.slug)}, featureKind: ${escapeValue(properties.featureKind || 'feature')}, summary: ${escapeValue(properties.summary || '')}, description: ${escapeValue(properties.description || '')}, repo: ${escapeValue(properties.repo || '')}, service: ${escapeValue(properties.service || '')}, signals: ${escapeValue(properties.signals || [])}, memberCount: ${properties.memberCount || 0}, entryPointIds: ${escapeValue(properties.entryPointIds || [])}, routes: ${escapeValue(properties.routes || [])}, tools: ${escapeValue(properties.tools || [])}, testCoverageHints: ${escapeValue(properties.testCoverageHints || [])}, lastIndexedCommit: ${escapeValue(properties.lastIndexedCommit || '')}, confidence: ${properties.confidence || 0}, source: ${escapeValue(properties.source || 'heuristic')}})`;
+        }
         else if (TABLES_WITH_EXPORTED.has(label)) {
             const descPart = properties.description
                 ? `, description: ${escapeValue(properties.description)}`
@@ -635,6 +645,9 @@ export const batchInsertNodesToCgdb = async (nodes, dbPath) => {
             return 'NULL';
         if (typeof v === 'number')
             return String(v);
+        if (Array.isArray(v)) {
+            return `[${v.map((item) => `'${String(item).replace(/\\/g, '\\\\').replace(/'/g, "''")}'`).join(',')}]`;
+        }
         // Escape backslashes first (for Windows paths), then single quotes, then newlines
         return `'${String(v).replace(/\\/g, '\\\\').replace(/'/g, "''").replace(/\n/g, '\\n').replace(/\r/g, '\\r')}'`;
     };
@@ -661,6 +674,9 @@ export const batchInsertNodesToCgdb = async (nodes, dbPath) => {
                         : '';
                     query = `MERGE (n:Section {id: ${escapeValue(properties.id)}}) SET n.name = ${escapeValue(properties.name)}, n.filePath = ${escapeValue(properties.filePath)}, n.startLine = ${properties.startLine || 0}, n.endLine = ${properties.endLine || 0}, n.level = ${properties.level || 1}, n.content = ${escapeValue(properties.content || '')}${descPart}`;
                 }
+                else if (label === 'FeatureCluster') {
+                    query = `MERGE (n:FeatureCluster {id: ${escapeValue(properties.id)}}) SET n.name = ${escapeValue(properties.name)}, n.slug = ${escapeValue(properties.slug)}, n.featureKind = ${escapeValue(properties.featureKind || 'feature')}, n.summary = ${escapeValue(properties.summary || '')}, n.description = ${escapeValue(properties.description || '')}, n.repo = ${escapeValue(properties.repo || '')}, n.service = ${escapeValue(properties.service || '')}, n.signals = ${escapeValue(properties.signals || [])}, n.memberCount = ${properties.memberCount || 0}, n.entryPointIds = ${escapeValue(properties.entryPointIds || [])}, n.routes = ${escapeValue(properties.routes || [])}, n.tools = ${escapeValue(properties.tools || [])}, n.testCoverageHints = ${escapeValue(properties.testCoverageHints || [])}, n.lastIndexedCommit = ${escapeValue(properties.lastIndexedCommit || '')}, n.confidence = ${properties.confidence || 0}, n.source = ${escapeValue(properties.source || 'heuristic')}`;
+                }
                 else if (TABLES_WITH_EXPORTED.has(label)) {
                     const descPart = properties.description
                         ? `, n.description = ${escapeValue(properties.description)}`
@@ -1103,8 +1119,8 @@ export const deleteNodesForFile = async (filePath, dbPath) => {
         // Delete nodes from each table that has filePath
         // DETACH DELETE removes the node and all its relationships
         for (const tableName of NODE_TABLES) {
-            // Skip tables that don't have filePath (Community, Process)
-            if (tableName === 'Community' || tableName === 'Process')
+            // Skip tables that don't have filePath (Community, Process, FeatureCluster)
+            if (tableName === 'Community' || tableName === 'Process' || tableName === 'FeatureCluster')
                 continue;
             try {
                 // First count how many we'll delete

package/dist/core/cgdb/csv-generator.js

@@ -40,6 +40,13 @@ export const escapeCSVNumber = (value, defaultValue = -1) => {
         return String(defaultValue);
     return String(value);
 };
+const toCgdbStringArray = (value) => {
+    const values = Array.isArray(value) ? value : [];
+    return `[${values
+        .map((item) => String(item).replace(/\\/g, '\\\\').replace(/'/g, "''").replace(/,/g, '\\,'))
+        .map((item) => `'${item}'`)
+        .join(',')}]`;
+};
 // ============================================================================
 // CONTENT EXTRACTION (lazy — reads from disk on demand)
 // ============================================================================
@@ -231,6 +238,7 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir, compress) =>
     const codeElemWriter = new BufferedCSVWriter(path.join(csvDir, 'codeelement.csv'), codeElementHeader);
     const communityWriter = new BufferedCSVWriter(path.join(csvDir, 'community.csv'), 'id,label,heuristicLabel,keywords,description,enrichedBy,cohesion,symbolCount');
     const processWriter = new BufferedCSVWriter(path.join(csvDir, 'process.csv'), 'id,label,heuristicLabel,processType,stepCount,communities,entryPointId,terminalId');
+    const featureClusterWriter = new BufferedCSVWriter(path.join(csvDir, 'featurecluster.csv'), 'id,name,slug,featureKind,summary,description,repo,service,signals,memberCount,entryPointIds,routes,tools,testCoverageHints,lastIndexedCommit,confidence,source');
     // Section nodes have an extra 'level' column
     const sectionWriter = new BufferedCSVWriter(path.join(csvDir, 'section.csv'), 'id,name,filePath,startLine,endLine,level,content,contentEncoding,description');
     // Route nodes for API endpoint mapping
@@ -315,8 +323,7 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir, compress) =>
                 break;
             }
             case 'Process': {
-                const communities = node.properties.communities || [];
-                const communitiesStr = `[${communities.map((c) => `'${c.replace(/'/g, "''")}'`).join(',')}]`;
+                const communitiesStr = toCgdbStringArray(node.properties.communities);
                 await processWriter.addRow([
                     escapeCSVField(node.id),
                     escapeCSVField(node.properties.name || ''),
@@ -329,6 +336,28 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir, compress) =>
                 ].join(','));
                 break;
             }
+            case 'FeatureCluster': {
+                await featureClusterWriter.addRow([
+                    escapeCSVField(node.id),
+                    escapeCSVField(node.properties.name || ''),
+                    escapeCSVField(node.properties.slug || ''),
+                    escapeCSVField(node.properties.featureKind || 'feature'),
+                    escapeCSVField(node.properties.summary || ''),
+                    escapeCSVField(node.properties.description || ''),
+                    escapeCSVField(node.properties.repo || ''),
+                    escapeCSVField(node.properties.service || ''),
+                    escapeCSVField(toCgdbStringArray(node.properties.signals)),
+                    escapeCSVNumber(node.properties.memberCount, 0),
+                    escapeCSVField(toCgdbStringArray(node.properties.entryPointIds)),
+                    escapeCSVField(toCgdbStringArray(node.properties.routes)),
+                    escapeCSVField(toCgdbStringArray(node.properties.tools)),
+                    escapeCSVField(toCgdbStringArray(node.properties.testCoverageHints)),
+                    escapeCSVField(node.properties.lastIndexedCommit || ''),
+                    escapeCSVNumber(node.properties.confidence, 0),
+                    escapeCSVField(node.properties.source || 'heuristic'),
+                ].join(','));
+                break;
+            }
             case 'Method': {
                 const content = await extractContent(node, contentCache);
                 const { wireContent, tag } = applyEncoding(content, compress);
@@ -441,6 +470,7 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir, compress) =>
         codeElemWriter,
         communityWriter,
         processWriter,
+        featureClusterWriter,
         sectionWriter,
         routeWriter,
         toolWriter,
@@ -473,6 +503,7 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir, compress) =>
         ['CodeElement', codeElemWriter],
         ['Community', communityWriter],
         ['Process', processWriter],
+        ['FeatureCluster', featureClusterWriter],
         ['Section', sectionWriter],
         ['Route', routeWriter],
         ['Tool', toolWriter],

package/dist/core/cgdb/schema.d.ts

@@ -20,6 +20,7 @@ export declare const METHOD_SCHEMA = "\nCREATE NODE TABLE Method (\n  id STRING,
 export declare const CODE_ELEMENT_SCHEMA = "\nCREATE NODE TABLE CodeElement (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  isExported BOOLEAN,\n  content STRING,\n  contentEncoding STRING DEFAULT 'none',\n  description STRING,\n  PRIMARY KEY (id)\n)";
 export declare const COMMUNITY_SCHEMA = "\nCREATE NODE TABLE Community (\n  id STRING,\n  label STRING,\n  heuristicLabel STRING,\n  keywords STRING[],\n  description STRING,\n  enrichedBy STRING,\n  cohesion DOUBLE,\n  symbolCount INT32,\n  PRIMARY KEY (id)\n)";
 export declare const PROCESS_SCHEMA = "\nCREATE NODE TABLE Process (\n  id STRING,\n  label STRING,\n  heuristicLabel STRING,\n  processType STRING,\n  stepCount INT32,\n  communities STRING[],\n  entryPointId STRING,\n  terminalId STRING,\n  PRIMARY KEY (id)\n)";
+export declare const FEATURE_CLUSTER_SCHEMA = "\nCREATE NODE TABLE FeatureCluster (\n  id STRING,\n  name STRING,\n  slug STRING,\n  featureKind STRING,\n  summary STRING,\n  description STRING,\n  repo STRING,\n  service STRING,\n  signals STRING[],\n  memberCount INT32,\n  entryPointIds STRING[],\n  routes STRING[],\n  tools STRING[],\n  testCoverageHints STRING[],\n  lastIndexedCommit STRING,\n  confidence DOUBLE,\n  source STRING,\n  PRIMARY KEY (id)\n)";
 export declare const STRUCT_SCHEMA: string;
 export declare const ENUM_SCHEMA: string;
 export declare const MACRO_SCHEMA: string;
@@ -42,7 +43,7 @@ export declare const MODULE_SCHEMA: string;
 export declare const ROUTE_SCHEMA = "\nCREATE NODE TABLE Route (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  responseKeys STRING[],\n  errorKeys STRING[],\n  middleware STRING[],\n  PRIMARY KEY (id)\n)";
 export declare const TOOL_SCHEMA = "\nCREATE NODE TABLE Tool (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  description STRING,\n  PRIMARY KEY (id)\n)";
 export declare const SECTION_SCHEMA = "\nCREATE NODE TABLE Section (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  level INT64,\n  content STRING,\n  contentEncoding STRING DEFAULT 'none',\n  description STRING,\n  PRIMARY KEY (id)\n)";
-export declare const RELATION_SCHEMA = "\nCREATE REL TABLE CodeRelation (\n  FROM File TO File,\n  FROM File TO Folder,\n  FROM File TO Function,\n  FROM File TO Class,\n  FROM File TO Interface,\n  FROM File TO Method,\n  FROM File TO CodeElement,\n  FROM File TO `Struct`,\n  FROM File TO `Enum`,\n  FROM File TO `Macro`,\n  FROM File TO `Typedef`,\n  FROM File TO `Union`,\n  FROM File TO `Namespace`,\n  FROM File TO `Trait`,\n  FROM File TO `Impl`,\n  FROM File TO `TypeAlias`,\n  FROM File TO `Const`,\n  FROM File TO `Static`,\n  FROM File TO `Variable`,\n  FROM File TO `Property`,\n  FROM File TO `Record`,\n  FROM File TO `Delegate`,\n  FROM File TO `Annotation`,\n  FROM File TO `Constructor`,\n  FROM File TO `Template`,\n  FROM File TO `Module`,\n  FROM File TO Section,\n  FROM Folder TO Folder,\n  FROM Folder TO File,\n  FROM Function TO Function,\n  FROM Function TO Method,\n  FROM Function TO Class,\n  FROM Function TO Community,\n  FROM Function TO `Macro`,\n  FROM Function TO `Struct`,\n  FROM Function TO `Template`,\n  FROM Function TO `Enum`,\n  FROM Function TO `Namespace`,\n  FROM Function TO `TypeAlias`,\n  FROM Function TO `Module`,\n  FROM Function TO `Impl`,\n  FROM Function TO Interface,\n  FROM Function TO `Constructor`,\n  FROM Function TO `Const`,\n  FROM Function TO `Typedef`,\n  FROM Function TO `Union`,\n  FROM Function TO `Property`,\n  FROM Function TO CodeElement,\n  FROM Class TO Method,\n  FROM Class TO Function,\n  FROM Class TO Class,\n  FROM Class TO Interface,\n  FROM Class TO Community,\n  FROM Class TO `Template`,\n  FROM Class TO `TypeAlias`,\n  FROM Class TO `Struct`,\n  FROM Class TO `Enum`,\n  FROM Class TO `Annotation`,\n  FROM Class TO `Constructor`,\n  FROM Class TO `Trait`,\n  FROM Class TO `Macro`,\n  FROM Class TO `Impl`,\n  FROM Class TO `Union`,\n  FROM Class TO `Namespace`,\n  FROM Class TO `Typedef`,\n  FROM Class TO `Property`,\n  FROM Method TO Function,\n  FROM Method TO Method,\n  FROM Method TO Class,\n  FROM Method TO Community,\n  FROM Method TO `Template`,\n  FROM Method TO `Struct`,\n  FROM Method TO `TypeAlias`,\n  FROM Method TO `Enum`,\n  FROM Method TO `Macro`,\n  FROM Method TO `Namespace`,\n  FROM Method TO `Module`,\n  FROM Method TO `Impl`,\n  FROM Method TO Interface,\n  FROM Method TO `Constructor`,\n  FROM Method TO `Property`,\n  FROM Method TO CodeElement,\n  FROM `Template` TO `Template`,\n  FROM `Template` TO Function,\n  FROM `Template` TO Method,\n  FROM `Template` TO Class,\n  FROM `Template` TO `Struct`,\n  FROM `Template` TO `TypeAlias`,\n  FROM `Template` TO `Enum`,\n  FROM `Template` TO `Macro`,\n  FROM `Template` TO Interface,\n  FROM `Template` TO `Constructor`,\n  FROM `Module` TO `Module`,\n  FROM Section TO Section,\n  FROM Section TO File,\n  FROM File TO Route,\n  FROM Function TO Route,\n  FROM Method TO Route,\n  FROM File TO Tool,\n  FROM Function TO Tool,\n  FROM Method TO Tool,\n  FROM CodeElement TO Community,\n  FROM Interface TO Community,\n  FROM Interface TO Function,\n  FROM Interface TO Method,\n  FROM Interface TO Class,\n  FROM Interface TO Interface,\n  FROM Interface TO `TypeAlias`,\n  FROM Interface TO `Struct`,\n  FROM Interface TO `Constructor`,\n  FROM Interface TO `Property`,\n  FROM `Struct` TO Community,\n  FROM `Struct` TO `Trait`,\n  FROM `Struct` TO `Struct`,\n  FROM `Struct` TO Class,\n  FROM `Struct` TO `Enum`,\n  FROM `Struct` TO Function,\n  FROM `Struct` TO Method,\n  FROM `Struct` TO Interface,\n  FROM `Struct` TO `Constructor`,\n  FROM `Struct` TO `Property`,\n  FROM `Enum` TO `Enum`,\n  FROM `Enum` TO Community,\n  FROM `Enum` TO Class,\n  FROM `Enum` TO Interface,\n  FROM `Macro` TO Community,\n  FROM `Macro` TO Function,\n  FROM `Macro` TO Method,\n  FROM `Module` TO Function,\n  FROM `Module` TO Method,\n  FROM `Typedef` TO Community,\n  FROM `Union` TO Community,\n  FROM `Namespace` TO Community,\n  FROM `Namespace` TO `Struct`,\n  FROM `Trait` TO Method,\n  FROM `Trait` TO `Constructor`,\n  FROM `Trait` TO `Property`,\n  FROM `Trait` TO Community,\n  FROM `Impl` TO Method,\n  FROM `Impl` TO `Constructor`,\n  FROM `Impl` TO `Property`,\n  FROM `Impl` TO Community,\n  FROM `Impl` TO `Trait`,\n  FROM `Impl` TO `Struct`,\n  FROM `Impl` TO `Impl`,\n  FROM `TypeAlias` TO Community,\n  FROM `TypeAlias` TO `Trait`,\n  FROM `TypeAlias` TO Class,\n  FROM `Const` TO Community,\n  FROM `Static` TO Community,\n  FROM `Variable` TO Community,\n  FROM `Property` TO Community,\n  FROM `Record` TO Method,\n  FROM `Record` TO `Constructor`,\n  FROM `Record` TO `Property`,\n  FROM `Record` TO Community,\n  FROM `Delegate` TO Community,\n  FROM `Annotation` TO Community,\n  FROM `Constructor` TO Community,\n  FROM `Constructor` TO Interface,\n  FROM `Constructor` TO Class,\n  FROM `Constructor` TO Method,\n  FROM `Constructor` TO Function,\n  FROM `Constructor` TO `Constructor`,\n  FROM `Constructor` TO `Struct`,\n  FROM `Constructor` TO `Macro`,\n  FROM `Constructor` TO `Template`,\n  FROM `Constructor` TO `TypeAlias`,\n  FROM `Constructor` TO `Enum`,\n  FROM `Constructor` TO `Annotation`,\n  FROM `Constructor` TO `Impl`,\n  FROM `Constructor` TO `Namespace`,\n  FROM `Constructor` TO `Module`,\n  FROM `Constructor` TO `Property`,\n  FROM `Constructor` TO `Typedef`,\n  FROM `Template` TO Community,\n  FROM `Module` TO Community,\n  FROM Function TO Process,\n  FROM Method TO Process,\n  FROM Class TO Process,\n  FROM Interface TO Process,\n  FROM `Struct` TO Process,\n  FROM `Constructor` TO Process,\n  FROM `Module` TO Process,\n  FROM `Macro` TO Process,\n  FROM `Impl` TO Process,\n  FROM `Typedef` TO Process,\n  FROM `TypeAlias` TO Process,\n  FROM `Enum` TO Process,\n  FROM `Union` TO Process,\n  FROM `Namespace` TO Process,\n  FROM `Trait` TO Process,\n  FROM `Const` TO Process,\n  FROM `Static` TO Process,\n  FROM `Variable` TO Process,\n  FROM `Property` TO Process,\n  FROM `Record` TO Process,\n  FROM `Delegate` TO Process,\n  FROM `Annotation` TO Process,\n  FROM `Template` TO Process,\n  FROM CodeElement TO Process,\n  FROM Route TO Process,\n  FROM Tool TO Process,\n  type STRING,\n  confidence DOUBLE,\n  reason STRING,\n  step INT32\n)";
+export declare const RELATION_SCHEMA = "\nCREATE REL TABLE CodeRelation (\n  FROM File TO File,\n  FROM File TO Folder,\n  FROM File TO Function,\n  FROM File TO Class,\n  FROM File TO Interface,\n  FROM File TO Method,\n  FROM File TO CodeElement,\n  FROM File TO `Struct`,\n  FROM File TO `Enum`,\n  FROM File TO `Macro`,\n  FROM File TO `Typedef`,\n  FROM File TO `Union`,\n  FROM File TO `Namespace`,\n  FROM File TO `Trait`,\n  FROM File TO `Impl`,\n  FROM File TO `TypeAlias`,\n  FROM File TO `Const`,\n  FROM File TO `Static`,\n  FROM File TO `Variable`,\n  FROM File TO `Property`,\n  FROM File TO `Record`,\n  FROM File TO `Delegate`,\n  FROM File TO `Annotation`,\n  FROM File TO `Constructor`,\n  FROM File TO `Template`,\n  FROM File TO `Module`,\n  FROM File TO Section,\n  FROM Folder TO Folder,\n  FROM Folder TO File,\n  FROM Function TO Function,\n  FROM Function TO Method,\n  FROM Function TO Class,\n  FROM Function TO Community,\n  FROM Function TO `Macro`,\n  FROM Function TO `Struct`,\n  FROM Function TO `Template`,\n  FROM Function TO `Enum`,\n  FROM Function TO `Namespace`,\n  FROM Function TO `TypeAlias`,\n  FROM Function TO `Module`,\n  FROM Function TO `Impl`,\n  FROM Function TO Interface,\n  FROM Function TO `Constructor`,\n  FROM Function TO `Const`,\n  FROM Function TO `Typedef`,\n  FROM Function TO `Union`,\n  FROM Function TO `Property`,\n  FROM Function TO CodeElement,\n  FROM Class TO Method,\n  FROM Class TO Function,\n  FROM Class TO Class,\n  FROM Class TO Interface,\n  FROM Class TO Community,\n  FROM Class TO `Template`,\n  FROM Class TO `TypeAlias`,\n  FROM Class TO `Struct`,\n  FROM Class TO `Enum`,\n  FROM Class TO `Annotation`,\n  FROM Class TO `Constructor`,\n  FROM Class TO `Trait`,\n  FROM Class TO `Macro`,\n  FROM Class TO `Impl`,\n  FROM Class TO `Union`,\n  FROM Class TO `Namespace`,\n  FROM Class TO `Typedef`,\n  FROM Class TO `Property`,\n  FROM Method TO Function,\n  FROM Method TO Method,\n  FROM Method TO Class,\n  FROM Method TO Community,\n  FROM Method TO `Template`,\n  FROM Method TO `Struct`,\n  FROM Method TO `TypeAlias`,\n  FROM Method TO `Enum`,\n  FROM Method TO `Macro`,\n  FROM Method TO `Namespace`,\n  FROM Method TO `Module`,\n  FROM Method TO `Impl`,\n  FROM Method TO Interface,\n  FROM Method TO `Constructor`,\n  FROM Method TO `Property`,\n  FROM Method TO CodeElement,\n  FROM `Template` TO `Template`,\n  FROM `Template` TO Function,\n  FROM `Template` TO Method,\n  FROM `Template` TO Class,\n  FROM `Template` TO `Struct`,\n  FROM `Template` TO `TypeAlias`,\n  FROM `Template` TO `Enum`,\n  FROM `Template` TO `Macro`,\n  FROM `Template` TO Interface,\n  FROM `Template` TO `Constructor`,\n  FROM `Module` TO `Module`,\n  FROM Section TO Section,\n  FROM Section TO File,\n  FROM File TO Route,\n  FROM Function TO Route,\n  FROM Method TO Route,\n  FROM File TO Tool,\n  FROM Function TO Tool,\n  FROM Method TO Tool,\n  FROM CodeElement TO Community,\n  FROM Interface TO Community,\n  FROM Interface TO Function,\n  FROM Interface TO Method,\n  FROM Interface TO Class,\n  FROM Interface TO Interface,\n  FROM Interface TO `TypeAlias`,\n  FROM Interface TO `Struct`,\n  FROM Interface TO `Constructor`,\n  FROM Interface TO `Property`,\n  FROM `Struct` TO Community,\n  FROM `Struct` TO `Trait`,\n  FROM `Struct` TO `Struct`,\n  FROM `Struct` TO Class,\n  FROM `Struct` TO `Enum`,\n  FROM `Struct` TO Function,\n  FROM `Struct` TO Method,\n  FROM `Struct` TO Interface,\n  FROM `Struct` TO `Constructor`,\n  FROM `Struct` TO `Property`,\n  FROM `Enum` TO `Enum`,\n  FROM `Enum` TO Community,\n  FROM `Enum` TO Class,\n  FROM `Enum` TO Interface,\n  FROM `Macro` TO Community,\n  FROM `Macro` TO Function,\n  FROM `Macro` TO Method,\n  FROM `Module` TO Function,\n  FROM `Module` TO Method,\n  FROM `Typedef` TO Community,\n  FROM `Union` TO Community,\n  FROM `Namespace` TO Community,\n  FROM `Namespace` TO `Struct`,\n  FROM `Trait` TO Method,\n  FROM `Trait` TO `Constructor`,\n  FROM `Trait` TO `Property`,\n  FROM `Trait` TO Community,\n  FROM `Impl` TO Method,\n  FROM `Impl` TO `Constructor`,\n  FROM `Impl` TO `Property`,\n  FROM `Impl` TO Community,\n  FROM `Impl` TO `Trait`,\n  FROM `Impl` TO `Struct`,\n  FROM `Impl` TO `Impl`,\n  FROM `TypeAlias` TO Community,\n  FROM `TypeAlias` TO `Trait`,\n  FROM `TypeAlias` TO Class,\n  FROM `Const` TO Community,\n  FROM `Static` TO Community,\n  FROM `Variable` TO Community,\n  FROM `Property` TO Community,\n  FROM `Record` TO Method,\n  FROM `Record` TO `Constructor`,\n  FROM `Record` TO `Property`,\n  FROM `Record` TO Community,\n  FROM `Delegate` TO Community,\n  FROM `Annotation` TO Community,\n  FROM `Constructor` TO Community,\n  FROM `Constructor` TO Interface,\n  FROM `Constructor` TO Class,\n  FROM `Constructor` TO Method,\n  FROM `Constructor` TO Function,\n  FROM `Constructor` TO `Constructor`,\n  FROM `Constructor` TO `Struct`,\n  FROM `Constructor` TO `Macro`,\n  FROM `Constructor` TO `Template`,\n  FROM `Constructor` TO `TypeAlias`,\n  FROM `Constructor` TO `Enum`,\n  FROM `Constructor` TO `Annotation`,\n  FROM `Constructor` TO `Impl`,\n  FROM `Constructor` TO `Namespace`,\n  FROM `Constructor` TO `Module`,\n  FROM `Constructor` TO `Property`,\n  FROM `Constructor` TO `Typedef`,\n  FROM `Template` TO Community,\n  FROM `Module` TO Community,\n  FROM Function TO Process,\n  FROM Method TO Process,\n  FROM Class TO Process,\n  FROM Interface TO Process,\n  FROM `Struct` TO Process,\n  FROM `Constructor` TO Process,\n  FROM `Module` TO Process,\n  FROM `Macro` TO Process,\n  FROM `Impl` TO Process,\n  FROM `Typedef` TO Process,\n  FROM `TypeAlias` TO Process,\n  FROM `Enum` TO Process,\n  FROM `Union` TO Process,\n  FROM `Namespace` TO Process,\n  FROM `Trait` TO Process,\n  FROM `Const` TO Process,\n  FROM `Static` TO Process,\n  FROM `Variable` TO Process,\n  FROM `Property` TO Process,\n  FROM `Record` TO Process,\n  FROM `Delegate` TO Process,\n  FROM `Annotation` TO Process,\n  FROM `Template` TO Process,\n  FROM CodeElement TO Process,\n  FROM Route TO Process,\n  FROM Tool TO Process,\n  FROM File TO FeatureCluster,\n  FROM Function TO FeatureCluster,\n  FROM Method TO FeatureCluster,\n  FROM Class TO FeatureCluster,\n  FROM Interface TO FeatureCluster,\n  FROM CodeElement TO FeatureCluster,\n  FROM Section TO FeatureCluster,\n  FROM Route TO FeatureCluster,\n  FROM Tool TO FeatureCluster,\n  FROM Process TO FeatureCluster,\n  FROM `Struct` TO FeatureCluster,\n  FROM `Enum` TO FeatureCluster,\n  FROM `Macro` TO FeatureCluster,\n  FROM `Typedef` TO FeatureCluster,\n  FROM `Union` TO FeatureCluster,\n  FROM `Namespace` TO FeatureCluster,\n  FROM `Trait` TO FeatureCluster,\n  FROM `Impl` TO FeatureCluster,\n  FROM `TypeAlias` TO FeatureCluster,\n  FROM `Const` TO FeatureCluster,\n  FROM `Static` TO FeatureCluster,\n  FROM `Variable` TO FeatureCluster,\n  FROM `Property` TO FeatureCluster,\n  FROM `Record` TO FeatureCluster,\n  FROM `Delegate` TO FeatureCluster,\n  FROM `Annotation` TO FeatureCluster,\n  FROM `Constructor` TO FeatureCluster,\n  FROM `Template` TO FeatureCluster,\n  FROM `Module` TO FeatureCluster,\n  FROM FeatureCluster TO FeatureCluster,\n  type STRING,\n  confidence DOUBLE,\n  reason STRING,\n  step INT32\n)";
 export declare const EMBEDDING_DIMS: number;
 /** HNSW vector index name for the CodeEmbedding table. */
 export declare const EMBEDDING_INDEX_NAME = "code_embedding_idx";

package/dist/core/cgdb/schema.js

@@ -139,6 +139,30 @@ CREATE NODE TABLE Process (
   PRIMARY KEY (id)
 )`;
 // ============================================================================
+// FEATURE CLUSTER NODE TABLE (human-facing feature/domain clusters)
+// ============================================================================
+export const FEATURE_CLUSTER_SCHEMA = `
+CREATE NODE TABLE FeatureCluster (
+  id STRING,
+  name STRING,
+  slug STRING,
+  featureKind STRING,
+  summary STRING,
+  description STRING,
+  repo STRING,
+  service STRING,
+  signals STRING[],
+  memberCount INT32,
+  entryPointIds STRING[],
+  routes STRING[],
+  tools STRING[],
+  testCoverageHints STRING[],
+  lastIndexedCommit STRING,
+  confidence DOUBLE,
+  source STRING,
+  PRIMARY KEY (id)
+)`;
+// ============================================================================
 // MULTI-LANGUAGE NODE TABLE SCHEMAS
 // ============================================================================
 // Generic code element with startLine/endLine for C, C++, Rust, Go, Java, C#
@@ -417,6 +441,36 @@ CREATE REL TABLE ${REL_TABLE_NAME} (
   FROM CodeElement TO Process,
   FROM Route TO Process,
   FROM Tool TO Process,
+  FROM File TO FeatureCluster,
+  FROM Function TO FeatureCluster,
+  FROM Method TO FeatureCluster,
+  FROM Class TO FeatureCluster,
+  FROM Interface TO FeatureCluster,
+  FROM CodeElement TO FeatureCluster,
+  FROM Section TO FeatureCluster,
+  FROM Route TO FeatureCluster,
+  FROM Tool TO FeatureCluster,
+  FROM Process TO FeatureCluster,
+  FROM \`Struct\` TO FeatureCluster,
+  FROM \`Enum\` TO FeatureCluster,
+  FROM \`Macro\` TO FeatureCluster,
+  FROM \`Typedef\` TO FeatureCluster,
+  FROM \`Union\` TO FeatureCluster,
+  FROM \`Namespace\` TO FeatureCluster,
+  FROM \`Trait\` TO FeatureCluster,
+  FROM \`Impl\` TO FeatureCluster,
+  FROM \`TypeAlias\` TO FeatureCluster,
+  FROM \`Const\` TO FeatureCluster,
+  FROM \`Static\` TO FeatureCluster,
+  FROM \`Variable\` TO FeatureCluster,
+  FROM \`Property\` TO FeatureCluster,
+  FROM \`Record\` TO FeatureCluster,
+  FROM \`Delegate\` TO FeatureCluster,
+  FROM \`Annotation\` TO FeatureCluster,
+  FROM \`Constructor\` TO FeatureCluster,
+  FROM \`Template\` TO FeatureCluster,
+  FROM \`Module\` TO FeatureCluster,
+  FROM FeatureCluster TO FeatureCluster,
   type STRING,
   confidence DOUBLE,
   reason STRING,
@@ -471,6 +525,7 @@ export const NODE_SCHEMA_QUERIES = [
     CODE_ELEMENT_SCHEMA,
     COMMUNITY_SCHEMA,
     PROCESS_SCHEMA,
+    FEATURE_CLUSTER_SCHEMA,
     // Multi-language support
     STRUCT_SCHEMA,
     ENUM_SCHEMA,

package/dist/core/embeddings/embedder.js

@@ -16,6 +16,7 @@ import { pipeline, env } from '@huggingface/transformers';
 import { existsSync } from 'fs';
 import { execFileSync } from 'child_process';
 import { join, dirname } from 'path';
+import { homedir } from 'os';
 import { createRequire } from 'module';
 import { DEFAULT_EMBEDDING_CONFIG } from './types.js';
 import { isHttpMode, getHttpDimensions, httpEmbed } from './http-client.js';
@@ -134,8 +135,9 @@ export const initEmbedder = async (onProgress, config = {}, forceDevice) => {
             // 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');
             const isDev = process.env.NODE_ENV === 'development';
             if (isDev) {
                 console.log(`🧠 Loading embedding model: ${finalConfig.modelId}`);

package/dist/core/graphstore/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Codragraph-side glue for the Phase 4 versioned graph store.
+ * CodraGraph-side glue for the Phase 4 versioned graph store.
  *
  * The graphstore package itself is engine-agnostic; everything that
  * touches LadybugDB lives here, in codragraph/. Best-effort by design:

package/dist/core/graphstore/index.js

@@ -1,5 +1,5 @@
 /**
- * Codragraph-side glue for the Phase 4 versioned graph store.
+ * CodraGraph-side glue for the Phase 4 versioned graph store.
  *
  * The graphstore package itself is engine-agnostic; everything that
  * touches LadybugDB lives here, in codragraph/. Best-effort by design:

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

@@ -41,6 +41,19 @@ export interface GroupToolPort {
         file_path?: string;
         include_content?: boolean;
     }): Promise<unknown>;
+    featureClusters?(repo: GroupRepoHandle, params: {
+        query?: string;
+        limit?: number;
+    }): Promise<unknown>;
+    featureContext?(repo: GroupRepoHandle, params: {
+        name: string;
+        limit?: number;
+    }): Promise<unknown>;
+    featureImpact?(repo: GroupRepoHandle, params: {
+        name: string;
+        direction?: 'upstream' | 'downstream' | 'both';
+        limit?: number;
+    }): Promise<unknown>;
 }
 export declare class GroupService {
     private readonly port;
@@ -51,5 +64,8 @@ export declare class GroupService {
     groupImpact(params: Record<string, unknown>): Promise<unknown>;
     groupContext(params: Record<string, unknown>): Promise<GroupContextResult>;
     groupQuery(params: Record<string, unknown>): Promise<unknown>;
+    groupFeatureClusters(params: Record<string, unknown>): Promise<unknown>;
+    groupFeatureContext(params: Record<string, unknown>): Promise<unknown>;
+    groupFeatureImpact(params: Record<string, unknown>): Promise<unknown>;
     groupStatus(params: Record<string, unknown>): Promise<unknown>;
 }