@codragraph/cli 2.0.0 → 2.1.1

package/dist/core/graphstore/cgdb-row-source.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Adapter exposing a live LadybugDB instance as a `@codragraph/graphstore`
+ * `RowSource`. Used by the analyze pipeline (Phase 4) to snapshot the
+ * loaded graph into the content-addressed store.
+ *
+ * Best-effort by design: any table that errors at query time is skipped
+ * (with the failure surfaced through the optional `onSkip` callback) so
+ * the surrounding analyze flow never breaks because the versioning hook
+ * misbehaves.
+ */
+import type { RowSource } from '@codragraph/graphstore';
+import { type NodeTableName } from '../../_shared/index.js';
+export interface CgdbRowSourceOptions {
+    /** Filter the node tables enumerated by `listNodeTables` — defaults to every NODE_TABLE. */
+    readonly nodeTables?: readonly NodeTableName[];
+    /** Called with `(table, error)` when a table query fails — defaults to a no-op. */
+    readonly onSkip?: (tableName: string, error: unknown) => void;
+}
+export declare const createCgdbRowSource: (opts?: CgdbRowSourceOptions) => RowSource;

package/dist/core/graphstore/cgdb-row-source.js

@@ -0,0 +1,141 @@
+/**
+ * Adapter exposing a live LadybugDB instance as a `@codragraph/graphstore`
+ * `RowSource`. Used by the analyze pipeline (Phase 4) to snapshot the
+ * loaded graph into the content-addressed store.
+ *
+ * Best-effort by design: any table that errors at query time is skipped
+ * (with the failure surfaced through the optional `onSkip` callback) so
+ * the surrounding analyze flow never breaks because the versioning hook
+ * misbehaves.
+ */
+import { NODE_TABLES, REL_TABLE_NAME } from '../../_shared/index.js';
+import { executeQuery } from '../cgdb/cgdb-adapter.js';
+export const createCgdbRowSource = (opts = {}) => {
+    const onSkip = opts.onSkip ?? (() => { });
+    const tables = opts.nodeTables ?? NODE_TABLES;
+    const listNodeTables = async () => {
+        return [...tables];
+    };
+    const streamNodeTable = async function* (tableName) {
+        let rows;
+        try {
+            // `MATCH (n:T) RETURN n` returns one row per node. The node value
+            // is reachable as either `row.n` (named-column form) or `row[0]`
+            // (positional form) depending on the LadybugDB result-shape mode;
+            // we accept both, mirroring the resilient pattern used by
+            // `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`);
+        }
+        catch (err) {
+            onSkip(tableName, err);
+            return;
+        }
+        let yielded = 0;
+        for (const raw of rows) {
+            const node = unwrapNode(raw);
+            if (!node)
+                continue;
+            yield normalizeNodeRow(node);
+            yielded++;
+        }
+        // If the query reported rows but none unwrapped, surface that as a
+        // skip so the analyze log makes the silent-empty failure mode
+        // visible instead of producing a 0-row snapshot for the table.
+        if (rows.length > 0 && yielded === 0) {
+            onSkip(tableName, new Error(`cgdb-row-source: query returned ${rows.length} row(s) for "${tableName}" but none had an unwrappable node — ` +
+                `result shape changed? expected row.n or row[0] to be the node`));
+        }
+    };
+    const streamEdges = async function* () {
+        let rows;
+        try {
+            // Project `from`/`to`/`type` as scalar columns and the full rel as
+            // `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`);
+        }
+        catch (err) {
+            onSkip(REL_TABLE_NAME, err);
+            return;
+        }
+        let yielded = 0;
+        for (const raw of rows) {
+            const r = raw;
+            const from = pickField(r, 'from', 0);
+            const to = pickField(r, 'to', 1);
+            const type = pickField(r, 'type', 2);
+            const rel = pickField(r, 'rel', 3);
+            if (typeof from !== 'string' || typeof to !== 'string')
+                continue;
+            yield normalizeEdgeRow({ from, to, type, rel: isPlainObject(rel) ? rel : null });
+            yielded++;
+        }
+        if (rows.length > 0 && yielded === 0) {
+            onSkip(REL_TABLE_NAME, new Error(`cgdb-row-source: edges query returned ${rows.length} row(s) but none had a string from/to — ` +
+                `result shape changed?`));
+        }
+    };
+    return { listNodeTables, streamNodeTable, streamEdges };
+};
+/**
+ * Pull the node out of an executeQuery result row, accepting either the
+ * named-column form (`row.n`) or the positional form (`row[0]`). Returns
+ * null when the row is missing or the node value isn't an object — the
+ * caller treats that as "skip and surface".
+ */
+const unwrapNode = (raw) => {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const r = raw;
+    const candidate = r['n'] ?? r[0];
+    return isPlainObject(candidate) ? candidate : null;
+};
+/** Read a field from an executeQuery row, falling back to the positional index. */
+const pickField = (row, named, positional) => {
+    if (!row)
+        return undefined;
+    return row[named] ?? row[positional];
+};
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/**
+ * Sanitize a node row for canonical hashing:
+ *   - Drop LadybugDB-specific internal fields (`_id`, `_label`) that are
+ *     not content-bearing — including them would make the hash sensitive
+ *     to internal storage offsets and break dedup across snapshots.
+ *   - Sort keys deterministically (canonical JSON in the serializer
+ *     already does this, but doing it once here keeps the row payload
+ *     stable when we ever swap engines).
+ */
+const normalizeNodeRow = (node) => {
+    const out = {};
+    for (const key of Object.keys(node).sort()) {
+        if (key === '_id' || key === '_label')
+            continue;
+        out[key] = node[key];
+    }
+    return out;
+};
+const normalizeEdgeRow = (r) => {
+    const props = {};
+    if (r.rel && typeof r.rel === 'object') {
+        for (const key of Object.keys(r.rel).sort()) {
+            // Skip the synthetic from/to/type that show up under `rel` too —
+            // we already project them as top-level columns and don't want
+            // duplication in the canonical row.
+            if (key === 'from' || key === 'to' || key === 'type')
+                continue;
+            if (key.startsWith('_'))
+                continue;
+            props[key] = r.rel[key];
+        }
+    }
+    return {
+        from: String(r.from),
+        to: String(r.to),
+        type: typeof r.type === 'string' ? r.type : String(r.type ?? ''),
+        ...props,
+    };
+};

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:
@@ -38,7 +38,7 @@ export interface RecordAnalysisSnapshotResult {
 /**
  * Snapshot the currently-loaded LadybugDB into the content-addressed
  * store and advance the active branch's HEAD to the new commit. Caller
- * is expected to have already initialized lbug with `initLbug(...)`.
+ * is expected to have already initialized cgdb with `initCgdb(...)`.
  *
  * Returns null if anything goes sideways (logged via `onSkipTable`); the
  * analyze pipeline treats that as "no snapshot for this run".

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:
@@ -9,13 +9,13 @@
  */
 import path from 'node:path';
 import { FsCAS, serializeSnapshot, createCommit, setHead, writeHeadBranch, resolveHeadCommit, DEFAULT_BRANCH, } from '@codragraph/graphstore';
-import { createLbugRowSource } from './lbug-row-source.js';
+import { createCgdbRowSource } from './cgdb-row-source.js';
 /** Subdirectory of `<repo>/.codragraph` that holds versioning artifacts. */
 export const GRAPHSTORE_SUBDIR = 'graphstore';
 /**
  * Snapshot the currently-loaded LadybugDB into the content-addressed
  * store and advance the active branch's HEAD to the new commit. Caller
- * is expected to have already initialized lbug with `initLbug(...)`.
+ * is expected to have already initialized cgdb with `initCgdb(...)`.
  *
  * Returns null if anything goes sideways (logged via `onSkipTable`); the
  * analyze pipeline treats that as "no snapshot for this run".
@@ -26,7 +26,7 @@ export const recordAnalysisSnapshot = async (opts) => {
     let serialized;
     try {
         serialized = await serializeSnapshot({
-            source: createLbugRowSource({ onSkip: opts.onSkipTable }),
+            source: createCgdbRowSource({ onSkip: opts.onSkipTable }),
             cas,
             indexedRepoCommit: opts.indexedRepoCommit,
         });

package/dist/core/group/bridge-db.d.ts

@@ -1,4 +1,4 @@
-import type { LbugValue } from '@ladybugdb/core';
+import type { LbugValue as CgdbValue } from '@ladybugdb/core';
 import type { BridgeHandle, BridgeMeta, StoredContract, CrossLink, RepoSnapshot } from './types.js';
 export declare function contractNodeId(repo: string, contractId: string, role: string, filePath: string): string;
 /**
@@ -46,7 +46,7 @@ export declare function indexContract(index: ContractLookupIndex, contract: Stor
 export declare function findContractNode(index: ContractLookupIndex, repo: string, role: 'consumer' | 'provider', symbolUid: string, filePath: string, symbolName: string): string | null;
 export declare function openBridgeDb(dbPath: string): Promise<BridgeHandle>;
 export declare function ensureBridgeSchema(handle: BridgeHandle): Promise<void>;
-export declare function queryBridge<T>(handle: BridgeHandle, cypher: string, params?: Record<string, LbugValue>): Promise<T[]>;
+export declare function queryBridge<T>(handle: BridgeHandle, cypher: string, params?: Record<string, CgdbValue>): Promise<T[]>;
 export declare function closeBridgeDb(handle: BridgeHandle): Promise<void>;
 export declare function retryRename(src: string, dst: string, attempts?: number): Promise<void>;
 export declare function writeBridgeMeta(groupDir: string, meta: BridgeMeta): Promise<void>;

package/dist/core/group/bridge-db.js

@@ -1,7 +1,7 @@
 import fsp from 'node:fs/promises';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
-import lbug from '@ladybugdb/core';
+import cgdb from '@ladybugdb/core';
 import { BRIDGE_SCHEMA_QUERIES, BRIDGE_SCHEMA_VERSION } from './bridge-schema.js';
 import { dedupeContracts, dedupeCrossLinks } from './normalization.js';
 export function contractNodeId(repo, contractId, role, filePath) {
@@ -74,8 +74,8 @@ 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 lbug.Database(dbPath, 0, false, false); // writable
-    const conn = new lbug.Connection(db);
+    const db = new cgdb.Database(dbPath, 0, false, false); // writable
+    const conn = new cgdb.Connection(db);
     return { _db: db, _conn: conn, groupDir: parentDir };
 }
 /**
@@ -83,10 +83,10 @@ export async function openBridgeDb(dbPath) {
  * CREATE NODE TABLE or CREATE REL TABLE statement hits an already-existing
  * table. LadybugDB DDL doesn't support IF NOT EXISTS, and its JS driver
  * doesn't expose typed error codes, so we match on the message substring —
- * the same pattern used by `core/lbug/lbug-adapter.ts`. If a future
+ * the same pattern used by `core/cgdb/cgdb-adapter.ts`. If a future
  * LadybugDB release changes the wording, update this constant.
  */
-const LBUG_ALREADY_EXISTS_MSG = 'already exists';
+const CGDB_ALREADY_EXISTS_MSG = 'already exists';
 export async function ensureBridgeSchema(handle) {
     const conn = handle._conn;
     for (const q of BRIDGE_SCHEMA_QUERIES) {
@@ -95,14 +95,14 @@ export async function ensureBridgeSchema(handle) {
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            if (!msg.includes(LBUG_ALREADY_EXISTS_MSG))
+            if (!msg.includes(CGDB_ALREADY_EXISTS_MSG))
                 throw err;
         }
     }
 }
 /**
  * Close every QueryResult / PreparedStatement before letting V8 GC them.
- * Same close-order discipline as `core/lbug/lbug-adapter.ts:closeQueryResult`
+ * Same close-order discipline as `core/cgdb/cgdb-adapter.ts:closeQueryResult`
  * — leaking these handles past `conn.close()` corrupts LadybugDB's native
  * file lock on Windows ("Error 33: The process cannot access the file
  * because it is being used by another process") and segfaults on
@@ -132,7 +132,7 @@ async function closeBridgeHandle(h) {
  * fully released the exclusive lock yet. Retrying with backoff is the
  * documented workaround for this class of Windows-fs interactions.
  */
-function isTransientLbugLockError(err) {
+function isTransientCgdbLockError(err) {
     const msg = err?.message ?? '';
     return (msg.includes('Error 33') ||
         msg.includes('locked a portion of the file') ||
@@ -180,7 +180,7 @@ export async function queryBridge(handle, cypher, params) {
             return await queryBridgeOnce(handle, cypher, params);
         }
         catch (err) {
-            if (!isTransientLbugLockError(err) || attempt === ATTEMPTS - 1)
+            if (!isTransientCgdbLockError(err) || attempt === ATTEMPTS - 1)
                 throw err;
             await new Promise((r) => setTimeout(r, 50 * Math.pow(2, attempt)));
         }
@@ -248,7 +248,7 @@ export async function writeBridgeMeta(groupDir, meta) {
     // Use retryRename for consistency with writeBridge's atomic swap — on
     // Windows a concurrent reader can cause EBUSY/EPERM even on a tiny
     // meta.json, and we don't want meta write to be less robust than the
-    // bridge.lbug swap it accompanies.
+    // bridge.cgdb swap it accompanies.
     await retryRename(tmp, target);
 }
 export async function readBridgeMeta(groupDir) {
@@ -275,9 +275,9 @@ export async function writeBridge(groupDir, input) {
     await fsp.mkdir(groupDir, { recursive: true });
     const contracts = dedupeContracts(input.contracts);
     const crossLinks = dedupeCrossLinks(input.crossLinks);
-    const finalPath = path.join(groupDir, 'bridge.lbug');
-    const tmpPath = path.join(groupDir, 'bridge.lbug.tmp');
-    const bakPath = path.join(groupDir, 'bridge.lbug.bak');
+    const finalPath = path.join(groupDir, 'bridge.cgdb');
+    const tmpPath = path.join(groupDir, 'bridge.cgdb.tmp');
+    const bakPath = path.join(groupDir, 'bridge.cgdb.bak');
     const report = {
         contractsInserted: 0,
         contractsFailed: 0,
@@ -466,7 +466,7 @@ export async function writeBridge(groupDir, input) {
 /*  openBridgeDbReadOnly                                               */
 /* ------------------------------------------------------------------ */
 export async function openBridgeDbReadOnly(groupDir) {
-    const dbPath = path.join(groupDir, 'bridge.lbug');
+    const dbPath = path.join(groupDir, 'bridge.cgdb');
     try {
         await fsp.access(dbPath);
     }
@@ -476,7 +476,7 @@ export async function openBridgeDbReadOnly(groupDir) {
         // triggers bak recovery is an interrupted writer, which on Windows may
         // still be holding an open handle on `.bak` for a few milliseconds when
         // a reader races in. EBUSY/EPERM retries recover that case silently.
-        const bakPath = path.join(groupDir, 'bridge.lbug.bak');
+        const bakPath = path.join(groupDir, 'bridge.cgdb.bak');
         try {
             await fsp.access(bakPath);
             await retryRename(bakPath, dbPath);
@@ -506,8 +506,8 @@ export async function openBridgeDbReadOnly(groupDir) {
         let db;
         let conn;
         try {
-            db = new lbug.Database(dbPath, 0, false, true); // readOnly
-            conn = new lbug.Connection(db);
+            db = new cgdb.Database(dbPath, 0, false, true); // readOnly
+            conn = new cgdb.Connection(db);
             return { _db: db, _conn: conn, groupDir };
         }
         catch (err) {
@@ -527,7 +527,7 @@ export async function openBridgeDbReadOnly(groupDir) {
                     /* ignore */
                 }
             }
-            if (!isTransientLbugLockError(err) || attempt === ATTEMPTS - 1)
+            if (!isTransientCgdbLockError(err) || attempt === ATTEMPTS - 1)
                 return null;
             await new Promise((r) => setTimeout(r, 50 * Math.pow(2, attempt)));
             continue;

package/dist/core/group/bridge-schema.d.ts

@@ -1,19 +1,19 @@
 /**
  * Bridge LadybugDB schema for cross-repo Contract Registry.
- * Separate from per-repo schema in lbug/schema.ts.
+ * Separate from per-repo schema in cgdb/schema.ts.
  */
 /**
- * Version of the bridge.lbug schema below. `openBridgeDbReadOnly` compares
+ * Version of the bridge.cgdb schema below. `openBridgeDbReadOnly` compares
  * this against `meta.json`'s version field and returns `null` on mismatch,
  * which trips the caller into either the JSON fallback path or a fresh
- * `group sync` that rebuilds `bridge.lbug` from scratch.
+ * `group sync` that rebuilds `bridge.cgdb` from scratch.
  *
  * Migration contract for contributors bumping this constant:
  *   1. Bump the number (e.g. `1` → `2`).
  *   2. Update the DDL below to match the new schema.
  *   3. DO NOT attempt an online migration in this file — the version gate
  *      is intentionally a "discard and re-sync" strategy for V1. An old
- *      bridge.lbug whose version doesn't match is treated as opaque and
+ *      bridge.cgdb whose version doesn't match is treated as opaque and
  *      rebuilt by the next `group sync`.
  *   4. If online migration becomes necessary (e.g. when groups accumulate
  *      large amounts of embedding data), add a migration path as a

package/dist/core/group/bridge-schema.js

@@ -1,19 +1,19 @@
 /**
  * Bridge LadybugDB schema for cross-repo Contract Registry.
- * Separate from per-repo schema in lbug/schema.ts.
+ * Separate from per-repo schema in cgdb/schema.ts.
  */
 /**
- * Version of the bridge.lbug schema below. `openBridgeDbReadOnly` compares
+ * Version of the bridge.cgdb schema below. `openBridgeDbReadOnly` compares
  * this against `meta.json`'s version field and returns `null` on mismatch,
  * which trips the caller into either the JSON fallback path or a fresh
- * `group sync` that rebuilds `bridge.lbug` from scratch.
+ * `group sync` that rebuilds `bridge.cgdb` from scratch.
  *
  * Migration contract for contributors bumping this constant:
  *   1. Bump the number (e.g. `1` → `2`).
  *   2. Update the DDL below to match the new schema.
  *   3. DO NOT attempt an online migration in this file — the version gate
  *      is intentionally a "discard and re-sync" strategy for V1. An old
- *      bridge.lbug whose version doesn't match is treated as opaque and
+ *      bridge.cgdb whose version doesn't match is treated as opaque and
  *      rebuilt by the next `group sync`.
  *   4. If online migration becomes necessary (e.g. when groups accumulate
  *      large amounts of embedding data), add a migration path as a

package/dist/core/group/cross-impact.js

@@ -199,19 +199,19 @@ async function ensureBridgeReady(groupDir) {
             error: `Bridge schema version mismatch (meta.json has ${meta.version}, expected ${BRIDGE_SCHEMA_VERSION}). Run codragraph group sync for this group.`,
         };
     }
-    const dbPath = path.join(groupDir, 'bridge.lbug');
+    const dbPath = path.join(groupDir, 'bridge.cgdb');
     try {
         await fsp.access(dbPath);
     }
     catch {
         return {
-            error: `No bridge.lbug in this group directory. Run codragraph group sync (schema ${BRIDGE_SCHEMA_VERSION}).`,
+            error: `No bridge.cgdb in this group directory. Run codragraph group sync (schema ${BRIDGE_SCHEMA_VERSION}).`,
         };
     }
     const handle = await openBridgeDbReadOnly(groupDir);
     if (!handle) {
         return {
-            error: `Could not open bridge.lbug read-only (schema ${BRIDGE_SCHEMA_VERSION}). Run codragraph group sync.`,
+            error: `Could not open bridge.cgdb read-only (schema ${BRIDGE_SCHEMA_VERSION}). Run codragraph group sync.`,
         };
     }
     return { handle };

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