@codragraph/cli 2.1.0 → 2.1.4

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/cgdb-row-source.js

@@ -26,7 +26,7 @@ export const createCgdbRowSource = (opts = {}) => {
             // `core/search/bm25-index.ts` for FTS results. Tables that do not
             // exist on disk for a given repo throw here — we treat that as
             // "no rows" via the onSkip callback rather than a hard failure.
-            rows = await executeQuery(`MATCH (n:${tableName}) RETURN n`);
+            rows = await executeQuery(`MATCH (n:${quoteCypherIdentifier(tableName)}) RETURN n`);
         }
         catch (err) {
             onSkip(tableName, err);
@@ -55,7 +55,7 @@ export const createCgdbRowSource = (opts = {}) => {
             // `rel`. Scalars give us a deterministic edge id even if the rel
             // payload's shape changes; `rel` carries any extra properties for
             // hashing.
-            rows = await executeQuery(`MATCH (a)-[r:${REL_TABLE_NAME}]->(b) RETURN a.id AS \`from\`, b.id AS \`to\`, r.type AS type, r AS rel`);
+            rows = await executeQuery(`MATCH (a)-[r:${quoteCypherIdentifier(REL_TABLE_NAME)}]->(b) RETURN a.id AS \`from\`, b.id AS \`to\`, r.type AS type, r AS rel`);
         }
         catch (err) {
             onSkip(REL_TABLE_NAME, err);
@@ -100,6 +100,7 @@ const pickField = (row, named, positional) => {
     return row[named] ?? row[positional];
 };
 const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const quoteCypherIdentifier = (identifier) => `\`${identifier.replace(/`/g, '``')}\``;
 /**
  * Sanitize a node row for canonical hashing:
  *   - Drop LadybugDB-specific internal fields (`_id`, `_label`) that are

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/bridge-db.js

@@ -74,7 +74,7 @@ export function findContractNode(index, repo, role, symbolUid, filePath, symbolN
 export async function openBridgeDb(dbPath) {
     const parentDir = path.dirname(dbPath);
     await fsp.mkdir(parentDir, { recursive: true });
-    const db = new cgdb.Database(dbPath, 0, false, false); // writable
+    const db = new cgdb.Database(dbPath, 0, false, false, BRIDGE_MAX_DB_SIZE_BYTES); // writable
     const conn = new cgdb.Connection(db);
     return { _db: db, _conn: conn, groupDir: parentDir };
 }
@@ -238,6 +238,25 @@ export async function retryRename(src, dst, attempts = 3) {
         }
     }
 }
+async function removeBridgeArtifacts(basePath) {
+    for (const candidate of [basePath, `${basePath}.wal`, `${basePath}.lock`]) {
+        try {
+            await fsp.rm(candidate, { recursive: true, force: true });
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+async function renameBridgeArtifactIfExists(src, dst) {
+    try {
+        await fsp.access(src);
+    }
+    catch {
+        return;
+    }
+    await retryRename(src, dst);
+}
 /* ------------------------------------------------------------------ */
 /*  writeBridgeMeta / readBridgeMeta                                  */
 /* ------------------------------------------------------------------ */
@@ -261,6 +280,10 @@ export async function readBridgeMeta(groupDir) {
     }
 }
 const MAX_SAMPLE_ERRORS = 10;
+// LadybugDB defaults maxDBSize to an 8 TiB mmap window on some platforms.
+// Bridge databases are small contract registries, so cap the mapping to keep
+// CI and low-resource user machines from failing before the first query.
+const BRIDGE_MAX_DB_SIZE_BYTES = 512 * 1024 * 1024;
 function errMessage(err) {
     if (err instanceof Error)
         return err.message;
@@ -293,13 +316,9 @@ export async function writeBridge(groupDir, input) {
             report.sampleErrors.push({ kind, id, message: errMessage(err) });
         }
     };
-    // Clean up any leftover tmp
-    try {
-        await fsp.rm(tmpPath, { recursive: true, force: true });
-    }
-    catch {
-        /* ignore */
-    }
+    // Clean up any leftover tmp plus native sidecars. LadybugDB stores WAL/lock
+    // files next to the database path, not inside it.
+    await removeBridgeArtifacts(tmpPath);
     // 1. Create temp DB, insert all data.
     //
     // Everything after `openBridgeDb` must run inside a try/finally so that
@@ -440,16 +459,27 @@ export async function writeBridge(groupDir, input) {
         }
     }
     // 3. Atomic swap: old→.bak, tmp→final, rm .bak
+    // Keep LadybugDB sidecars paired with the path rename. WAL files live next
+    // to the DB path, so renaming only the base path can hide fresh schema/data.
+    await removeBridgeArtifacts(bakPath);
     try {
         await fsp.access(finalPath);
         await retryRename(finalPath, bakPath);
+        await renameBridgeArtifactIfExists(`${finalPath}.wal`, `${bakPath}.wal`);
     }
     catch {
         /* no existing db */
     }
     await retryRename(tmpPath, finalPath);
+    await renameBridgeArtifactIfExists(`${tmpPath}.wal`, `${finalPath}.wal`);
+    try {
+        await fsp.rm(`${tmpPath}.lock`, { force: true });
+    }
+    catch {
+        /* ignore */
+    }
     try {
-        await fsp.rm(bakPath, { recursive: true, force: true });
+        await removeBridgeArtifacts(bakPath);
     }
     catch {
         /* ignore */
@@ -480,6 +510,8 @@ export async function openBridgeDbReadOnly(groupDir) {
         try {
             await fsp.access(bakPath);
             await retryRename(bakPath, dbPath);
+            await renameBridgeArtifactIfExists(`${bakPath}.wal`, `${dbPath}.wal`);
+            await fsp.rm(`${bakPath}.lock`, { force: true });
         }
         catch {
             return null;
@@ -506,7 +538,7 @@ export async function openBridgeDbReadOnly(groupDir) {
         let db;
         let conn;
         try {
-            db = new cgdb.Database(dbPath, 0, false, true); // readOnly
+            db = new cgdb.Database(dbPath, 0, false, true, BRIDGE_MAX_DB_SIZE_BYTES); // readOnly
             conn = new cgdb.Connection(db);
             return { _db: db, _conn: conn, groupDir };
         }

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>;
 }