@zuvia-software-solutions/code-mapper 1.4.0 → 2.0.1

package/dist/core/db/queries.d.ts

@@ -0,0 +1,160 @@
+/**
+ * @file Typed SQL boundary for joined queries, traversals, and aggregation.
+ *
+ * All multi-table SQL lives here. `local-backend.ts` never touches SQL
+ * directly for joined or traversal queries -- it calls typed functions
+ * from this module or from adapter.ts for simple CRUD.
+ *
+ * Design invariants:
+ *   - schema.ts is the ONLY source of truth for types
+ *   - Every ID is branded (NodeId, EdgeId)
+ *   - Every edge type is a literal union (EdgeType)
+ *   - Synchronous API (better-sqlite3 is sync)
+ *   - Fail-fast: log and throw, never swallow
+ */
+import type Database from 'better-sqlite3';
+import type { NodeLabel, EdgeType, NodeRow, EdgeRow } from './schema.js';
+import { type NodeId } from './schema.js';
+export { getStats } from './adapter.js';
+/**
+ * Find incoming edges to a target node, joined with their source nodes.
+ * Use case: "who calls this function?" (callers / upstream deps).
+ */
+export declare function findIncomingEdges(db: Database.Database, targetId: NodeId, type?: EdgeType, opts?: {
+    minConfidence?: number;
+    limit?: number;
+}): Array<{
+    edge: EdgeRow;
+    node: NodeRow;
+}>;
+/**
+ * Find outgoing edges from a source node, joined with their target nodes.
+ * Use case: "what does this function call?" (callees / downstream deps).
+ */
+export declare function findOutgoingEdges(db: Database.Database, sourceId: NodeId, type?: EdgeType, opts?: {
+    minConfidence?: number;
+    limit?: number;
+}): Array<{
+    edge: EdgeRow;
+    node: NodeRow;
+}>;
+/**
+ * Find all processes that a given node participates in.
+ * Looks for STEP_IN_PROCESS edges from nodeId to Process nodes.
+ */
+export declare function findProcessesForNode(db: Database.Database, nodeId: NodeId): Array<{
+    processId: NodeId;
+    label: string;
+    heuristicLabel: string;
+    processType: string;
+    stepCount: number;
+    step: number;
+}>;
+/**
+ * Find the community a node belongs to (via MEMBER_OF edge).
+ * Returns null if the node has no community membership.
+ */
+export declare function findCommunityForNode(db: Database.Database, nodeId: NodeId): {
+    communityId: NodeId;
+    label: string;
+    cohesion: number;
+} | null;
+/**
+ * Batch: find process participation for multiple nodes at once.
+ * More efficient than calling findProcessesForNode in a loop.
+ */
+export declare function batchFindProcesses(db: Database.Database, nodeIds: readonly NodeId[]): Array<{
+    nodeId: NodeId;
+    processId: NodeId;
+    label: string;
+    heuristicLabel: string;
+    processType: string;
+    stepCount: number;
+    step: number;
+}>;
+/**
+ * Batch: find community membership for multiple nodes at once.
+ */
+export declare function batchFindCommunities(db: Database.Database, nodeIds: readonly NodeId[]): Array<{
+    nodeId: NodeId;
+    communityId: NodeId;
+    module: string;
+    cohesion: number;
+}>;
+export interface ImpactNode {
+    readonly depth: number;
+    readonly id: NodeId;
+    readonly name: string;
+    readonly label: NodeLabel;
+    readonly filePath: string;
+    readonly relationType: EdgeType;
+    readonly confidence: number;
+}
+export interface ImpactResult {
+    readonly nodes: readonly ImpactNode[];
+    readonly truncated: boolean;
+}
+/**
+ * Multi-hop BFS traversal for impact analysis.
+ *
+ * `upstream` = follow edges backward (find callers, importers -- who depends on this)
+ * `downstream` = follow edges forward (find callees -- what does this depend on)
+ *
+ * Algorithm: iterative frontier expansion per depth level.
+ * Terminates when maxDepth is reached, frontier is empty, or maxImpacted nodes collected.
+ */
+export declare function traverseImpact(db: Database.Database, startId: NodeId, direction: 'upstream' | 'downstream', opts: {
+    maxDepth: number;
+    edgeTypes: readonly EdgeType[];
+    minConfidence: number;
+    includeTests: boolean;
+    maxImpacted?: number;
+    maxFrontierPerDepth?: number;
+}): ImpactResult;
+/**
+ * List all Community nodes, ordered by symbolCount descending.
+ */
+export declare function listCommunities(db: Database.Database, limit?: number): NodeRow[];
+/**
+ * List all Process nodes, ordered by stepCount descending.
+ */
+export declare function listProcesses(db: Database.Database, limit?: number): NodeRow[];
+/**
+ * Get members of a community (nodes with MEMBER_OF edges to the community).
+ * Matches by community name or heuristicLabel.
+ */
+export declare function getCommunityMembers(db: Database.Database, communityName: string, limit?: number): NodeRow[];
+/**
+ * Get ordered steps of a process.
+ * Returns nodes participating in the process, sorted by step number.
+ */
+export declare function getProcessSteps(db: Database.Database, processId: NodeId): Array<{
+    node: NodeRow;
+    step: number;
+}>;
+/**
+ * Find communities by name (matches against name or heuristicLabel).
+ */
+export declare function findCommunitiesByName(db: Database.Database, name: string): NodeRow[];
+/**
+ * Find processes by name (matches against name or heuristicLabel).
+ */
+export declare function findProcessesByName(db: Database.Database, name: string): NodeRow[];
+/**
+ * Fetch multiple nodes by their IDs. Useful for batch content retrieval
+ * (e.g., reranker signature extraction).
+ */
+export declare function findNodesByIds(db: Database.Database, ids: readonly NodeId[]): NodeRow[];
+/**
+ * Get ALL steps for multiple processes at once.
+ * Returns flattened list of steps across all requested processes.
+ */
+export declare function batchGetProcessSteps(db: Database.Database, processIds: readonly NodeId[]): Array<{
+    processId: NodeId;
+    nodeId: NodeId;
+    name: string;
+    label: string;
+    filePath: string;
+    startLine: number | null;
+    step: number;
+}>;

package/dist/core/db/queries.js

@@ -0,0 +1,441 @@
+// code-mapper/src/core/db/queries.ts
+/**
+ * @file Typed SQL boundary for joined queries, traversals, and aggregation.
+ *
+ * All multi-table SQL lives here. `local-backend.ts` never touches SQL
+ * directly for joined or traversal queries -- it calls typed functions
+ * from this module or from adapter.ts for simple CRUD.
+ *
+ * Design invariants:
+ *   - schema.ts is the ONLY source of truth for types
+ *   - Every ID is branded (NodeId, EdgeId)
+ *   - Every edge type is a literal union (EdgeType)
+ *   - Synchronous API (better-sqlite3 is sync)
+ *   - Fail-fast: log and throw, never swallow
+ */
+import { toNodeId, assertNodeLabel, assertEdgeType } from './schema.js';
+export { getStats } from './adapter.js';
+// ---------------------------------------------------------------------------
+// Test-file detection (inlined -- small, pure, no external deps)
+// ---------------------------------------------------------------------------
+const TEST_PATH_PATTERN = /(?:^|[/\\])(?:__tests?__|tests?|spec|__mocks__)[/\\]|\.(?:test|spec|e2e|integration)\.[^/\\]+$/i;
+function isTestFilePath(filePath) {
+    return TEST_PATH_PATTERN.test(filePath);
+}
+/** Convert a prefixed join row to typed { edge, node } pair. */
+function parseEdgeNodeJoin(raw) {
+    // Validate string-union fields at the DB boundary — fail fast on invalid data
+    assertEdgeType(raw.e_type);
+    assertNodeLabel(raw.n_label);
+    return {
+        edge: {
+            id: raw.e_id,
+            sourceId: toNodeId(raw.e_sourceId),
+            targetId: toNodeId(raw.e_targetId),
+            type: raw.e_type,
+            confidence: raw.e_confidence,
+            reason: raw.e_reason,
+            step: raw.e_step,
+            callLine: raw.e_callLine,
+        },
+        node: {
+            id: toNodeId(raw.n_id),
+            label: raw.n_label,
+            name: raw.n_name,
+            filePath: raw.n_filePath,
+            startLine: raw.n_startLine,
+            endLine: raw.n_endLine,
+            isExported: raw.n_isExported,
+            content: raw.n_content,
+            description: raw.n_description,
+            heuristicLabel: raw.n_heuristicLabel,
+            cohesion: raw.n_cohesion,
+            symbolCount: raw.n_symbolCount,
+            keywords: raw.n_keywords,
+            enrichedBy: raw.n_enrichedBy,
+            processType: raw.n_processType,
+            stepCount: raw.n_stepCount,
+            communities: raw.n_communities,
+            entryPointId: raw.n_entryPointId,
+            terminalId: raw.n_terminalId,
+            parameterCount: raw.n_parameterCount,
+            returnType: raw.n_returnType,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Shared SQL fragments
+// ---------------------------------------------------------------------------
+const NODE_COLUMNS_PREFIXED = `
+  n.id AS n_id, n.label AS n_label, n.name AS n_name, n.filePath AS n_filePath,
+  n.startLine AS n_startLine, n.endLine AS n_endLine, n.isExported AS n_isExported,
+  n.content AS n_content, n.description AS n_description,
+  n.heuristicLabel AS n_heuristicLabel, n.cohesion AS n_cohesion,
+  n.symbolCount AS n_symbolCount, n.keywords AS n_keywords, n.enrichedBy AS n_enrichedBy,
+  n.processType AS n_processType, n.stepCount AS n_stepCount,
+  n.communities AS n_communities, n.entryPointId AS n_entryPointId,
+  n.terminalId AS n_terminalId, n.parameterCount AS n_parameterCount,
+  n.returnType AS n_returnType`;
+const EDGE_COLUMNS_PREFIXED = `
+  e.id AS e_id, e.sourceId AS e_sourceId, e.targetId AS e_targetId,
+  e.type AS e_type, e.confidence AS e_confidence, e.reason AS e_reason,
+  e.step AS e_step, e.callLine AS e_callLine`;
+// ---------------------------------------------------------------------------
+// 1. Edge traversals with joined nodes
+// ---------------------------------------------------------------------------
+/**
+ * Find incoming edges to a target node, joined with their source nodes.
+ * Use case: "who calls this function?" (callers / upstream deps).
+ */
+export function findIncomingEdges(db, targetId, type, opts) {
+    const minConf = opts?.minConfidence ?? 0;
+    const limit = opts?.limit ?? 500;
+    const sql = type
+        ? `SELECT ${EDGE_COLUMNS_PREFIXED}, ${NODE_COLUMNS_PREFIXED}
+       FROM edges e JOIN nodes n ON n.id = e.sourceId
+       WHERE e.targetId = ? AND e.type = ? AND e.confidence >= ?
+       LIMIT ?`
+        : `SELECT ${EDGE_COLUMNS_PREFIXED}, ${NODE_COLUMNS_PREFIXED}
+       FROM edges e JOIN nodes n ON n.id = e.sourceId
+       WHERE e.targetId = ? AND e.confidence >= ?
+       LIMIT ?`;
+    const rows = type
+        ? db.prepare(sql).all(targetId, type, minConf, limit)
+        : db.prepare(sql).all(targetId, minConf, limit);
+    return rows.map(parseEdgeNodeJoin);
+}
+/**
+ * Find outgoing edges from a source node, joined with their target nodes.
+ * Use case: "what does this function call?" (callees / downstream deps).
+ */
+export function findOutgoingEdges(db, sourceId, type, opts) {
+    const minConf = opts?.minConfidence ?? 0;
+    const limit = opts?.limit ?? 500;
+    const sql = type
+        ? `SELECT ${EDGE_COLUMNS_PREFIXED}, ${NODE_COLUMNS_PREFIXED}
+       FROM edges e JOIN nodes n ON n.id = e.targetId
+       WHERE e.sourceId = ? AND e.type = ? AND e.confidence >= ?
+       LIMIT ?`
+        : `SELECT ${EDGE_COLUMNS_PREFIXED}, ${NODE_COLUMNS_PREFIXED}
+       FROM edges e JOIN nodes n ON n.id = e.targetId
+       WHERE e.sourceId = ? AND e.confidence >= ?
+       LIMIT ?`;
+    const rows = type
+        ? db.prepare(sql).all(sourceId, type, minConf, limit)
+        : db.prepare(sql).all(sourceId, minConf, limit);
+    return rows.map(parseEdgeNodeJoin);
+}
+/**
+ * Find all processes that a given node participates in.
+ * Looks for STEP_IN_PROCESS edges from nodeId to Process nodes.
+ */
+export function findProcessesForNode(db, nodeId) {
+    const rows = db.prepare(`
+    SELECT p.id AS processId, p.name AS label, p.heuristicLabel, p.processType, p.stepCount, e.step
+    FROM edges e
+    JOIN nodes p ON p.id = e.targetId
+    WHERE e.sourceId = ? AND e.type = 'STEP_IN_PROCESS' AND p.label = 'Process'
+  `).all(nodeId);
+    return rows.map(r => ({
+        processId: toNodeId(r.processId),
+        label: r.label,
+        heuristicLabel: r.heuristicLabel,
+        processType: r.processType,
+        stepCount: r.stepCount,
+        step: r.step,
+    }));
+}
+/**
+ * Find the community a node belongs to (via MEMBER_OF edge).
+ * Returns null if the node has no community membership.
+ */
+export function findCommunityForNode(db, nodeId) {
+    const row = db.prepare(`
+    SELECT c.id AS communityId, c.heuristicLabel AS label, c.cohesion
+    FROM edges e
+    JOIN nodes c ON c.id = e.targetId
+    WHERE e.sourceId = ? AND e.type = 'MEMBER_OF' AND c.label = 'Community'
+    LIMIT 1
+  `).get(nodeId);
+    if (!row)
+        return null;
+    return {
+        communityId: toNodeId(row.communityId),
+        label: row.label,
+        cohesion: row.cohesion,
+    };
+}
+/**
+ * Batch: find process participation for multiple nodes at once.
+ * More efficient than calling findProcessesForNode in a loop.
+ */
+export function batchFindProcesses(db, nodeIds) {
+    if (nodeIds.length === 0)
+        return [];
+    const ph = nodeIds.map(() => '?').join(',');
+    const rows = db.prepare(`
+    SELECT e.sourceId AS nodeId, p.id AS processId, p.name AS label,
+           p.heuristicLabel, p.processType, p.stepCount, e.step
+    FROM edges e
+    JOIN nodes p ON p.id = e.targetId
+    WHERE e.sourceId IN (${ph}) AND e.type = 'STEP_IN_PROCESS' AND p.label = 'Process'
+  `).all(...nodeIds);
+    return rows.map(r => ({
+        nodeId: toNodeId(r.nodeId),
+        processId: toNodeId(r.processId),
+        label: r.label,
+        heuristicLabel: r.heuristicLabel,
+        processType: r.processType,
+        stepCount: r.stepCount,
+        step: r.step,
+    }));
+}
+/**
+ * Batch: find community membership for multiple nodes at once.
+ */
+export function batchFindCommunities(db, nodeIds) {
+    if (nodeIds.length === 0)
+        return [];
+    const ph = nodeIds.map(() => '?').join(',');
+    const rows = db.prepare(`
+    SELECT e.sourceId AS nodeId, c.id AS communityId, c.heuristicLabel AS module, c.cohesion
+    FROM edges e
+    JOIN nodes c ON c.id = e.targetId
+    WHERE e.sourceId IN (${ph}) AND e.type = 'MEMBER_OF' AND c.label = 'Community'
+  `).all(...nodeIds);
+    return rows.map(r => ({
+        nodeId: toNodeId(r.nodeId),
+        communityId: toNodeId(r.communityId),
+        module: r.module,
+        cohesion: r.cohesion,
+    }));
+}
+/**
+ * Multi-hop BFS traversal for impact analysis.
+ *
+ * `upstream` = follow edges backward (find callers, importers -- who depends on this)
+ * `downstream` = follow edges forward (find callees -- what does this depend on)
+ *
+ * Algorithm: iterative frontier expansion per depth level.
+ * Terminates when maxDepth is reached, frontier is empty, or maxImpacted nodes collected.
+ */
+export function traverseImpact(db, startId, direction, opts) {
+    const maxImpacted = opts.maxImpacted ?? 500;
+    const maxFrontierPerDepth = opts.maxFrontierPerDepth ?? 200;
+    const visited = new Set([startId]);
+    const result = [];
+    let frontier = [startId];
+    let truncated = false;
+    // Build the type filter clause: e.type IN ('CALLS', 'IMPORTS', ...)
+    // Use parameterized OR chain since SQLite IN with params can be awkward for mixed params
+    const typeFilter = opts.edgeTypes.map(() => 'e.type = ?').join(' OR ');
+    // Direction determines join orientation:
+    //   upstream:   edges pointing TO current frontier nodes, join SOURCE node
+    //   downstream: edges pointing FROM current frontier nodes, join TARGET node
+    const buildSql = (placeholderCount) => {
+        const idPh = Array.from({ length: placeholderCount }, () => '?').join(',');
+        if (direction === 'upstream') {
+            return `
+        SELECT n.id, n.name, n.label, n.filePath, e.type AS edgeType, e.confidence
+        FROM edges e
+        JOIN nodes n ON n.id = e.sourceId
+        WHERE e.targetId IN (${idPh})
+          AND (${typeFilter})
+          AND e.confidence >= ?`;
+        }
+        return `
+      SELECT n.id, n.name, n.label, n.filePath, e.type AS edgeType, e.confidence
+      FROM edges e
+      JOIN nodes n ON n.id = e.targetId
+      WHERE e.sourceId IN (${idPh})
+        AND (${typeFilter})
+        AND e.confidence >= ?`;
+    };
+    for (let depth = 1; depth <= opts.maxDepth; depth++) {
+        if (frontier.length === 0)
+            break;
+        // Truncate frontier to cap per-depth expansion
+        if (frontier.length > maxFrontierPerDepth) {
+            frontier = frontier.slice(0, maxFrontierPerDepth);
+            truncated = true;
+        }
+        const sql = buildSql(frontier.length);
+        const params = [
+            ...frontier,
+            ...opts.edgeTypes,
+            opts.minConfidence,
+        ];
+        const rows = db.prepare(sql).all(...params);
+        const nextFrontier = [];
+        for (const row of rows) {
+            if (visited.has(row.id))
+                continue;
+            visited.add(row.id);
+            // Skip test files unless includeTests is true
+            if (!opts.includeTests && isTestFilePath(row.filePath))
+                continue;
+            // Validate string-union fields at the DB boundary — fail fast on invalid data
+            assertNodeLabel(row.label);
+            assertEdgeType(row.edgeType);
+            const node = {
+                depth,
+                id: toNodeId(row.id),
+                name: row.name,
+                label: row.label,
+                filePath: row.filePath,
+                relationType: row.edgeType,
+                confidence: row.confidence,
+            };
+            result.push(node);
+            nextFrontier.push(toNodeId(row.id));
+            if (result.length >= maxImpacted) {
+                truncated = true;
+                break;
+            }
+        }
+        if (result.length >= maxImpacted)
+            break;
+        frontier = nextFrontier;
+    }
+    return { nodes: result, truncated };
+}
+// ---------------------------------------------------------------------------
+// 7. Community / Process listing
+// ---------------------------------------------------------------------------
+/**
+ * List all Community nodes, ordered by symbolCount descending.
+ */
+export function listCommunities(db, limit = 100) {
+    return db.prepare(`
+    SELECT * FROM nodes
+    WHERE label = 'Community'
+    ORDER BY symbolCount DESC
+    LIMIT ?
+  `).all(limit);
+}
+/**
+ * List all Process nodes, ordered by stepCount descending.
+ */
+export function listProcesses(db, limit = 100) {
+    return db.prepare(`
+    SELECT * FROM nodes
+    WHERE label = 'Process'
+    ORDER BY stepCount DESC
+    LIMIT ?
+  `).all(limit);
+}
+/**
+ * Get members of a community (nodes with MEMBER_OF edges to the community).
+ * Matches by community name or heuristicLabel.
+ */
+export function getCommunityMembers(db, communityName, limit = 200) {
+    return db.prepare(`
+    SELECT DISTINCT n.* FROM edges e
+    JOIN nodes n ON n.id = e.sourceId
+    JOIN nodes c ON c.id = e.targetId
+    WHERE e.type = 'MEMBER_OF' AND c.label = 'Community'
+      AND (c.name = ? OR c.heuristicLabel = ?)
+    LIMIT ?
+  `).all(communityName, communityName, limit);
+}
+/**
+ * Get ordered steps of a process.
+ * Returns nodes participating in the process, sorted by step number.
+ */
+export function getProcessSteps(db, processId) {
+    const rows = db.prepare(`
+    SELECT e.step,
+      ${NODE_COLUMNS_PREFIXED}
+    FROM edges e
+    JOIN nodes n ON n.id = e.sourceId
+    WHERE e.targetId = ? AND e.type = 'STEP_IN_PROCESS'
+    ORDER BY e.step ASC
+  `).all(processId);
+    return rows.map(r => {
+        // Validate string-union field at the DB boundary — fail fast on invalid data
+        assertNodeLabel(r.n_label);
+        return {
+            step: r.step,
+            node: {
+                id: toNodeId(r.n_id),
+                label: r.n_label,
+                name: r.n_name,
+                filePath: r.n_filePath,
+                startLine: r.n_startLine,
+                endLine: r.n_endLine,
+                isExported: r.n_isExported,
+                content: r.n_content,
+                description: r.n_description,
+                heuristicLabel: r.n_heuristicLabel,
+                cohesion: r.n_cohesion,
+                symbolCount: r.n_symbolCount,
+                keywords: r.n_keywords,
+                enrichedBy: r.n_enrichedBy,
+                processType: r.n_processType,
+                stepCount: r.n_stepCount,
+                communities: r.n_communities,
+                entryPointId: r.n_entryPointId,
+                terminalId: r.n_terminalId,
+                parameterCount: r.n_parameterCount,
+                returnType: r.n_returnType,
+            },
+        };
+    });
+}
+/**
+ * Find communities by name (matches against name or heuristicLabel).
+ */
+export function findCommunitiesByName(db, name) {
+    return db.prepare(`
+    SELECT * FROM nodes
+    WHERE label = 'Community' AND (name = ? OR heuristicLabel = ?)
+  `).all(name, name);
+}
+/**
+ * Find processes by name (matches against name or heuristicLabel).
+ */
+export function findProcessesByName(db, name) {
+    return db.prepare(`
+    SELECT * FROM nodes
+    WHERE label = 'Process' AND (name = ? OR heuristicLabel = ?)
+  `).all(name, name);
+}
+// ---------------------------------------------------------------------------
+// 8. Batch content fetch
+// ---------------------------------------------------------------------------
+/**
+ * Fetch multiple nodes by their IDs. Useful for batch content retrieval
+ * (e.g., reranker signature extraction).
+ */
+export function findNodesByIds(db, ids) {
+    if (ids.length === 0)
+        return [];
+    const ph = ids.map(() => '?').join(',');
+    return db.prepare(`SELECT * FROM nodes WHERE id IN (${ph})`).all(...ids);
+}
+/**
+ * Get ALL steps for multiple processes at once.
+ * Returns flattened list of steps across all requested processes.
+ */
+export function batchGetProcessSteps(db, processIds) {
+    if (processIds.length === 0)
+        return [];
+    const ph = processIds.map(() => '?').join(',');
+    const rows = db.prepare(`
+    SELECT e.targetId AS processId, n.id AS nodeId, n.name, n.label,
+           n.filePath, n.startLine, e.step
+    FROM edges e
+    JOIN nodes n ON n.id = e.sourceId
+    WHERE e.targetId IN (${ph}) AND e.type = 'STEP_IN_PROCESS'
+    ORDER BY e.targetId, e.step ASC
+  `).all(...processIds);
+    return rows.map(r => ({
+        processId: toNodeId(r.processId),
+        nodeId: toNodeId(r.nodeId),
+        name: r.name,
+        label: r.label,
+        filePath: r.filePath,
+        startLine: r.startLine,
+        step: r.step,
+    }));
+}