@optave/codegraph 3.2.0 → 3.3.0

package/dist/features/export.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Export the dependency graph in DOT (Graphviz) format.
+ */
+export function exportDOT(db: any, opts?: {}): string;
+/**
+ * Export the dependency graph in Mermaid format.
+ */
+export function exportMermaid(db: any, opts?: {}): string;
+/**
+ * Export as JSON adjacency list.
+ */
+export function exportJSON(db: any, opts?: {}): object;
+/**
+ * Export the dependency graph in GraphML (XML) format.
+ */
+export function exportGraphML(db: any, opts?: {}): string;
+/**
+ * Export the dependency graph in TinkerPop GraphSON v3 format.
+ */
+export function exportGraphSON(db: any, opts?: {}): object;
+/**
+ * Export the dependency graph as Neo4j bulk-import CSV files.
+ * Returns { nodes: string, relationships: string }.
+ */
+export function exportNeo4jCSV(db: any, opts?: {}): {
+    nodes: string;
+    relationships: string;
+};
+//# sourceMappingURL=export.d.ts.map

package/dist/features/export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../../src/features/export.js"],"names":[],"mappings":"AAsMA;;GAEG;AACH,sDAmBC;AAED;;GAEG;AACH,0DA0BC;AAED;;GAEG;AACH,uDAwBC;AAED;;GAEG;AACH,0DAaC;AAED;;GAEG;AACH,2DAiDC;AAED;;;GAGG;AACH;;;EAmBC"}

package/dist/features/export.js

@@ -0,0 +1,336 @@
+import path from 'node:path';
+import { isTestFile } from '../infrastructure/test-filter.js';
+import { renderFileLevelDOT, renderFileLevelGraphML, renderFileLevelMermaid, renderFileLevelNeo4jCSV, renderFunctionLevelDOT, renderFunctionLevelGraphML, renderFunctionLevelMermaid, renderFunctionLevelNeo4jCSV, } from '../presentation/export.js';
+import { paginateResult } from '../shared/paginate.js';
+const DEFAULT_MIN_CONFIDENCE = 0.5;
+// ─── Shared data loaders ─────────────────────────────────────────────
+/**
+ * Load file-level edges from DB with filtering.
+ * @param {object} db
+ * @param {object} opts
+ * @param {boolean} [opts.includeKind] - Include edge_kind in SELECT DISTINCT
+ * @param {boolean} [opts.includeConfidence] - Include confidence (adds a column to DISTINCT — use only when needed)
+ * @returns {{ edges: Array, totalEdges: number }}
+ */
+function loadFileLevelEdges(db, { noTests, minConfidence, limit, includeKind = false, includeConfidence = false }) {
+    const minConf = minConfidence ?? DEFAULT_MIN_CONFIDENCE;
+    const kindClause = includeKind ? ', e.kind AS edge_kind' : '';
+    const confidenceClause = includeConfidence ? ', e.confidence' : '';
+    let edges = db
+        .prepare(`
+      SELECT DISTINCT n1.file AS source, n2.file AS target${kindClause}${confidenceClause}
+      FROM edges e
+      JOIN nodes n1 ON e.source_id = n1.id
+      JOIN nodes n2 ON e.target_id = n2.id
+      WHERE n1.file != n2.file AND e.kind IN ('imports', 'imports-type', 'calls')
+        AND e.confidence >= ?
+    `)
+        .all(minConf);
+    if (noTests)
+        edges = edges.filter((e) => !isTestFile(e.source) && !isTestFile(e.target));
+    const totalEdges = edges.length;
+    if (limit && edges.length > limit)
+        edges = edges.slice(0, limit);
+    return { edges, totalEdges };
+}
+/**
+ * Load function-level edges from DB with filtering.
+ * Returns the maximal field set needed by any serializer.
+ * @returns {{ edges: Array, totalEdges: number }}
+ */
+function loadFunctionLevelEdges(db, { noTests, minConfidence, limit }) {
+    const minConf = minConfidence ?? DEFAULT_MIN_CONFIDENCE;
+    let edges = db
+        .prepare(`
+      SELECT n1.id AS source_id, n1.name AS source_name, n1.kind AS source_kind,
+             n1.file AS source_file, n1.line AS source_line, n1.role AS source_role,
+             n2.id AS target_id, n2.name AS target_name, n2.kind AS target_kind,
+             n2.file AS target_file, n2.line AS target_line, n2.role AS target_role,
+             e.kind AS edge_kind, e.confidence
+      FROM edges e
+      JOIN nodes n1 ON e.source_id = n1.id
+      JOIN nodes n2 ON e.target_id = n2.id
+      WHERE n1.kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module', 'constant')
+        AND n2.kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module', 'constant')
+        AND e.kind = 'calls'
+        AND e.confidence >= ?
+    `)
+        .all(minConf);
+    if (noTests)
+        edges = edges.filter((e) => !isTestFile(e.source_file) && !isTestFile(e.target_file));
+    const totalEdges = edges.length;
+    if (limit && edges.length > limit)
+        edges = edges.slice(0, limit);
+    return { edges, totalEdges };
+}
+/**
+ * Load directory groupings for file-level graphs.
+ * Uses DB directory nodes if available, falls back to path.dirname().
+ * @returns {Array<{ name: string, files: Array<{ path: string, basename: string }>, cohesion: number|null }>}
+ */
+function loadDirectoryGroups(db, allFiles) {
+    const hasDirectoryNodes = db.prepare("SELECT COUNT(*) as c FROM nodes WHERE kind = 'directory'").get().c > 0;
+    const dirs = new Map();
+    if (hasDirectoryNodes) {
+        const dbDirs = db
+            .prepare(`
+        SELECT n.id, n.name, nm.cohesion
+        FROM nodes n
+        LEFT JOIN node_metrics nm ON n.id = nm.node_id
+        WHERE n.kind = 'directory'
+      `)
+            .all();
+        for (const d of dbDirs) {
+            const containedFiles = db
+                .prepare(`
+          SELECT n.name FROM edges e
+          JOIN nodes n ON e.target_id = n.id
+          WHERE e.source_id = ? AND e.kind = 'contains' AND n.kind = 'file'
+        `)
+                .all(d.id)
+                .map((r) => r.name)
+                .filter((f) => allFiles.has(f));
+            if (containedFiles.length > 0) {
+                dirs.set(d.name, { files: containedFiles, cohesion: d.cohesion ?? null });
+            }
+        }
+    }
+    else {
+        for (const file of allFiles) {
+            const dir = path.dirname(file) || '.';
+            if (!dirs.has(dir))
+                dirs.set(dir, { files: [], cohesion: null });
+            dirs.get(dir).files.push(file);
+        }
+    }
+    return [...dirs]
+        .sort((a, b) => a[0].localeCompare(b[0]))
+        .map(([name, info]) => ({
+        name,
+        files: info.files.map((f) => ({ path: f, basename: path.basename(f) })),
+        cohesion: info.cohesion,
+    }));
+}
+/**
+ * Load directory groupings for Mermaid file-level graphs (simplified — no cohesion, string arrays).
+ */
+function loadMermaidDirectoryGroups(db, allFiles) {
+    const hasDirectoryNodes = db.prepare("SELECT COUNT(*) as c FROM nodes WHERE kind = 'directory'").get().c > 0;
+    const dirs = new Map();
+    if (hasDirectoryNodes) {
+        const dbDirs = db.prepare("SELECT id, name FROM nodes WHERE kind = 'directory'").all();
+        for (const d of dbDirs) {
+            const containedFiles = db
+                .prepare(`
+          SELECT n.name FROM edges e
+          JOIN nodes n ON e.target_id = n.id
+          WHERE e.source_id = ? AND e.kind = 'contains' AND n.kind = 'file'
+        `)
+                .all(d.id)
+                .map((r) => r.name)
+                .filter((f) => allFiles.has(f));
+            if (containedFiles.length > 0)
+                dirs.set(d.name, containedFiles);
+        }
+    }
+    else {
+        for (const file of allFiles) {
+            const dir = path.dirname(file) || '.';
+            if (!dirs.has(dir))
+                dirs.set(dir, []);
+            dirs.get(dir).push(file);
+        }
+    }
+    return [...dirs]
+        .sort((a, b) => a[0].localeCompare(b[0]))
+        .map(([name, files]) => ({ name, files }));
+}
+/**
+ * Load node roles for Mermaid function-level styling.
+ * @returns {Map<string, string>} "file::name" → role
+ */
+function loadNodeRoles(db, edges) {
+    const roles = new Map();
+    const seen = new Set();
+    for (const e of edges) {
+        for (const [file, name] of [
+            [e.source_file, e.source_name],
+            [e.target_file, e.target_name],
+        ]) {
+            const key = `${file}::${name}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const row = db
+                .prepare('SELECT role FROM nodes WHERE file = ? AND name = ? AND role IS NOT NULL LIMIT 1')
+                .get(file, name);
+            if (row?.role)
+                roles.set(key, row.role);
+        }
+    }
+    return roles;
+}
+// ─── Public API ──────────────────────────────────────────────────────
+/**
+ * Export the dependency graph in DOT (Graphviz) format.
+ */
+export function exportDOT(db, opts = {}) {
+    const fileLevel = opts.fileLevel !== false;
+    const noTests = opts.noTests || false;
+    const minConfidence = opts.minConfidence;
+    const limit = opts.limit;
+    if (fileLevel) {
+        const { edges, totalEdges } = loadFileLevelEdges(db, { noTests, minConfidence, limit });
+        const allFiles = new Set();
+        for (const { source, target } of edges) {
+            allFiles.add(source);
+            allFiles.add(target);
+        }
+        const dirs = loadDirectoryGroups(db, allFiles);
+        return renderFileLevelDOT({ dirs, edges, totalEdges, limit });
+    }
+    const { edges, totalEdges } = loadFunctionLevelEdges(db, { noTests, minConfidence, limit });
+    return renderFunctionLevelDOT({ edges, totalEdges, limit });
+}
+/**
+ * Export the dependency graph in Mermaid format.
+ */
+export function exportMermaid(db, opts = {}) {
+    const fileLevel = opts.fileLevel !== false;
+    const noTests = opts.noTests || false;
+    const minConfidence = opts.minConfidence;
+    const direction = opts.direction || 'LR';
+    const limit = opts.limit;
+    if (fileLevel) {
+        const { edges, totalEdges } = loadFileLevelEdges(db, {
+            noTests,
+            minConfidence,
+            limit,
+            includeKind: true,
+        });
+        const allFiles = new Set();
+        for (const { source, target } of edges) {
+            allFiles.add(source);
+            allFiles.add(target);
+        }
+        const dirs = loadMermaidDirectoryGroups(db, allFiles);
+        return renderFileLevelMermaid({ direction, dirs, edges, totalEdges, limit });
+    }
+    const { edges, totalEdges } = loadFunctionLevelEdges(db, { noTests, minConfidence, limit });
+    const roles = loadNodeRoles(db, edges);
+    return renderFunctionLevelMermaid({ direction, edges, roles, totalEdges, limit });
+}
+/**
+ * Export as JSON adjacency list.
+ */
+export function exportJSON(db, opts = {}) {
+    const noTests = opts.noTests || false;
+    const minConf = opts.minConfidence ?? DEFAULT_MIN_CONFIDENCE;
+    let nodes = db
+        .prepare(`
+    SELECT id, name, kind, file, line FROM nodes WHERE kind = 'file'
+  `)
+        .all();
+    if (noTests)
+        nodes = nodes.filter((n) => !isTestFile(n.file));
+    let edges = db
+        .prepare(`
+    SELECT DISTINCT n1.file AS source, n2.file AS target, e.kind, e.confidence
+    FROM edges e
+    JOIN nodes n1 ON e.source_id = n1.id
+    JOIN nodes n2 ON e.target_id = n2.id
+    WHERE n1.file != n2.file AND e.confidence >= ?
+  `)
+        .all(minConf);
+    if (noTests)
+        edges = edges.filter((e) => !isTestFile(e.source) && !isTestFile(e.target));
+    const base = { nodes, edges };
+    return paginateResult(base, 'edges', { limit: opts.limit, offset: opts.offset });
+}
+/**
+ * Export the dependency graph in GraphML (XML) format.
+ */
+export function exportGraphML(db, opts = {}) {
+    const fileLevel = opts.fileLevel !== false;
+    const noTests = opts.noTests || false;
+    const minConfidence = opts.minConfidence;
+    const limit = opts.limit;
+    if (fileLevel) {
+        const { edges } = loadFileLevelEdges(db, { noTests, minConfidence, limit });
+        return renderFileLevelGraphML({ edges });
+    }
+    const { edges } = loadFunctionLevelEdges(db, { noTests, minConfidence, limit });
+    return renderFunctionLevelGraphML({ edges });
+}
+/**
+ * Export the dependency graph in TinkerPop GraphSON v3 format.
+ */
+export function exportGraphSON(db, opts = {}) {
+    const noTests = opts.noTests || false;
+    const minConf = opts.minConfidence ?? DEFAULT_MIN_CONFIDENCE;
+    let nodes = db
+        .prepare(`
+    SELECT id, name, kind, file, line, role FROM nodes
+    WHERE kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module', 'constant', 'file')
+  `)
+        .all();
+    if (noTests)
+        nodes = nodes.filter((n) => !isTestFile(n.file));
+    let edges = db
+        .prepare(`
+    SELECT e.rowid AS id, n1.id AS outV, n2.id AS inV, e.kind, e.confidence
+    FROM edges e
+    JOIN nodes n1 ON e.source_id = n1.id
+    JOIN nodes n2 ON e.target_id = n2.id
+    WHERE e.confidence >= ?
+  `)
+        .all(minConf);
+    if (noTests) {
+        const nodeIds = new Set(nodes.map((n) => n.id));
+        edges = edges.filter((e) => nodeIds.has(e.outV) && nodeIds.has(e.inV));
+    }
+    const vertices = nodes.map((n) => ({
+        id: n.id,
+        label: n.kind,
+        properties: {
+            name: [{ id: 0, value: n.name }],
+            file: [{ id: 0, value: n.file }],
+            ...(n.line != null ? { line: [{ id: 0, value: n.line }] } : {}),
+            ...(n.role ? { role: [{ id: 0, value: n.role }] } : {}),
+        },
+    }));
+    const gEdges = edges.map((e) => ({
+        id: e.id,
+        label: e.kind,
+        inV: e.inV,
+        outV: e.outV,
+        properties: {
+            confidence: e.confidence,
+        },
+    }));
+    const base = { vertices, edges: gEdges };
+    return paginateResult(base, 'edges', { limit: opts.limit, offset: opts.offset });
+}
+/**
+ * Export the dependency graph as Neo4j bulk-import CSV files.
+ * Returns { nodes: string, relationships: string }.
+ */
+export function exportNeo4jCSV(db, opts = {}) {
+    const fileLevel = opts.fileLevel !== false;
+    const noTests = opts.noTests || false;
+    const minConfidence = opts.minConfidence;
+    const limit = opts.limit;
+    if (fileLevel) {
+        const { edges } = loadFileLevelEdges(db, {
+            noTests,
+            minConfidence,
+            limit,
+            includeKind: true,
+            includeConfidence: true,
+        });
+        return renderFileLevelNeo4jCSV({ edges });
+    }
+    const { edges } = loadFunctionLevelEdges(db, { noTests, minConfidence, limit });
+    return renderFunctionLevelNeo4jCSV({ edges });
+}
+//# sourceMappingURL=export.js.map

package/dist/features/export.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.js","sourceRoot":"","sources":["../../src/features/export.js"],"names":[],"mappings":"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"}

package/dist/features/flow.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Determine the entry point type from a node name based on framework prefixes.
+ * @param {string} name
+ * @returns {'route'|'event'|'command'|'exported'|null}
+ */
+export function entryPointType(name: string): "route" | "event" | "command" | "exported" | null;
+/**
+ * Query all entry points from the graph, grouped by type.
+ * Entry points are nodes with framework prefixes or role = 'entry'.
+ *
+ * @param {string} [dbPath]
+ * @param {object} [opts]
+ * @param {boolean} [opts.noTests]
+ * @returns {{ entries: object[], byType: object, count: number }}
+ */
+export function listEntryPointsData(dbPath?: string, opts?: {
+    noTests?: boolean | undefined;
+}): {
+    entries: object[];
+    byType: object;
+    count: number;
+};
+/**
+ * Forward BFS from a matched node through callees to leaves.
+ *
+ * @param {string} name - Node name to trace from (supports partial/prefix-stripped matching)
+ * @param {string} [dbPath]
+ * @param {object} [opts]
+ * @param {number} [opts.depth=10]
+ * @param {boolean} [opts.noTests]
+ * @param {string} [opts.file]
+ * @param {string} [opts.kind]
+ * @returns {{ entry: object|null, depth: number, steps: object[], leaves: object[], cycles: object[], totalReached: number, truncated: boolean }}
+ */
+export function flowData(name: string, dbPath?: string, opts?: {
+    depth?: number | undefined;
+    noTests?: boolean | undefined;
+    file?: string | undefined;
+    kind?: string | undefined;
+}): {
+    entry: object | null;
+    depth: number;
+    steps: object[];
+    leaves: object[];
+    cycles: object[];
+    totalReached: number;
+    truncated: boolean;
+};
+//# sourceMappingURL=flow.d.ts.map

package/dist/features/flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow.d.ts","sourceRoot":"","sources":["../../src/features/flow.js"],"names":[],"mappings":"AAaA;;;;GAIG;AACH,qCAHW,MAAM,GACJ,OAAO,GAAC,OAAO,GAAC,SAAS,GAAC,UAAU,GAAC,IAAI,CASrD;AAED;;;;;;;;GAQG;AACH,6CALW,MAAM,SAEd;IAAuB,OAAO;CAC9B,GAAU;IAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CA+ChE;AAED;;;;;;;;;;;GAWG;AACH,+BATW,MAAM,WACN,MAAM,SAEd;IAAsB,KAAK;IACJ,OAAO;IACR,IAAI;IACJ,IAAI;CAC1B,GAAU;IAAE,KAAK,EAAE,MAAM,GAAC,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAsIhJ"}

package/dist/features/flow.js

@@ -0,0 +1,203 @@
+/**
+ * Execution flow tracing — forward BFS from entry points through callees to leaves.
+ *
+ * Answers "what happens when a user hits POST /login?" by tracing from
+ * framework entry points (routes, commands, events) through their call chains.
+ */
+import { openReadonlyOrFail } from '../db/index.js';
+import { CORE_SYMBOL_KINDS, findMatchingNodes } from '../domain/queries.js';
+import { isTestFile } from '../infrastructure/test-filter.js';
+import { paginateResult } from '../shared/paginate.js';
+import { FRAMEWORK_ENTRY_PREFIXES } from './structure.js';
+/**
+ * Determine the entry point type from a node name based on framework prefixes.
+ * @param {string} name
+ * @returns {'route'|'event'|'command'|'exported'|null}
+ */
+export function entryPointType(name) {
+    for (const prefix of FRAMEWORK_ENTRY_PREFIXES) {
+        if (name.startsWith(prefix)) {
+            return prefix.slice(0, -1); // 'route:', 'event:', 'command:' → 'route', 'event', 'command'
+        }
+    }
+    return null;
+}
+/**
+ * Query all entry points from the graph, grouped by type.
+ * Entry points are nodes with framework prefixes or role = 'entry'.
+ *
+ * @param {string} [dbPath]
+ * @param {object} [opts]
+ * @param {boolean} [opts.noTests]
+ * @returns {{ entries: object[], byType: object, count: number }}
+ */
+export function listEntryPointsData(dbPath, opts = {}) {
+    const db = openReadonlyOrFail(dbPath);
+    try {
+        const noTests = opts.noTests || false;
+        // Find all framework-prefixed nodes
+        const prefixConditions = FRAMEWORK_ENTRY_PREFIXES.map(() => 'n.name LIKE ?').join(' OR ');
+        const prefixParams = FRAMEWORK_ENTRY_PREFIXES.map((p) => `${p}%`);
+        let rows = db
+            .prepare(`SELECT n.name, n.kind, n.file, n.line, n.role
+         FROM nodes n
+         WHERE (
+           (${prefixConditions})
+           OR n.role = 'entry'
+         )
+           AND n.kind NOT IN ('file', 'directory')
+         ORDER BY n.name`)
+            .all(...prefixParams);
+        if (noTests)
+            rows = rows.filter((r) => !isTestFile(r.file));
+        const entries = rows.map((r) => ({
+            name: r.name,
+            kind: r.kind,
+            file: r.file,
+            line: r.line,
+            role: r.role,
+            type: entryPointType(r.name) || (r.role === 'entry' ? 'exported' : null),
+        }));
+        const byType = {};
+        for (const e of entries) {
+            const t = e.type || 'other';
+            if (!byType[t])
+                byType[t] = [];
+            byType[t].push(e);
+        }
+        const base = { entries, byType, count: entries.length };
+        return paginateResult(base, 'entries', { limit: opts.limit, offset: opts.offset });
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Forward BFS from a matched node through callees to leaves.
+ *
+ * @param {string} name - Node name to trace from (supports partial/prefix-stripped matching)
+ * @param {string} [dbPath]
+ * @param {object} [opts]
+ * @param {number} [opts.depth=10]
+ * @param {boolean} [opts.noTests]
+ * @param {string} [opts.file]
+ * @param {string} [opts.kind]
+ * @returns {{ entry: object|null, depth: number, steps: object[], leaves: object[], cycles: object[], totalReached: number, truncated: boolean }}
+ */
+export function flowData(name, dbPath, opts = {}) {
+    const db = openReadonlyOrFail(dbPath);
+    try {
+        const maxDepth = opts.depth || 10;
+        const noTests = opts.noTests || false;
+        const flowOpts = { ...opts, kinds: opts.kind ? [opts.kind] : CORE_SYMBOL_KINDS };
+        // Phase 1: Direct LIKE match on full name (use all 10 core symbol kinds,
+        // not just FUNCTION_KINDS, so flow can trace from interfaces/types/structs/etc.)
+        let matchNode = findMatchingNodes(db, name, flowOpts)[0] ?? null;
+        // Phase 2: Prefix-stripped matching — try adding framework prefixes
+        if (!matchNode) {
+            for (const prefix of FRAMEWORK_ENTRY_PREFIXES) {
+                matchNode = findMatchingNodes(db, `${prefix}${name}`, flowOpts)[0] ?? null;
+                if (matchNode)
+                    break;
+            }
+        }
+        if (!matchNode) {
+            return {
+                entry: null,
+                depth: maxDepth,
+                steps: [],
+                leaves: [],
+                cycles: [],
+                totalReached: 0,
+                truncated: false,
+            };
+        }
+        const epType = entryPointType(matchNode.name);
+        const entry = {
+            name: matchNode.name,
+            kind: matchNode.kind,
+            file: matchNode.file,
+            line: matchNode.line,
+            type: epType || 'exported',
+            role: matchNode.role,
+        };
+        // Forward BFS through callees
+        const visited = new Set([matchNode.id]);
+        let frontier = [matchNode.id];
+        const steps = [];
+        const cycles = [];
+        let truncated = false;
+        // Track which nodes are at each depth and their depth for leaf detection
+        const nodeDepths = new Map();
+        const idToNode = new Map();
+        idToNode.set(matchNode.id, entry);
+        for (let d = 1; d <= maxDepth; d++) {
+            const nextFrontier = [];
+            const levelNodes = [];
+            for (const fid of frontier) {
+                const callees = db
+                    .prepare(`SELECT DISTINCT n.id, n.name, n.kind, n.file, n.line, n.role
+             FROM edges e JOIN nodes n ON e.target_id = n.id
+             WHERE e.source_id = ? AND e.kind = 'calls'`)
+                    .all(fid);
+                for (const c of callees) {
+                    if (noTests && isTestFile(c.file))
+                        continue;
+                    if (visited.has(c.id)) {
+                        // Cycle detected
+                        const fromNode = idToNode.get(fid);
+                        if (fromNode) {
+                            cycles.push({ from: fromNode.name, to: c.name, depth: d });
+                        }
+                        continue;
+                    }
+                    visited.add(c.id);
+                    nextFrontier.push(c.id);
+                    const nodeInfo = { name: c.name, kind: c.kind, file: c.file, line: c.line };
+                    levelNodes.push(nodeInfo);
+                    nodeDepths.set(c.id, d);
+                    idToNode.set(c.id, nodeInfo);
+                }
+            }
+            if (levelNodes.length > 0) {
+                steps.push({ depth: d, nodes: levelNodes });
+            }
+            frontier = nextFrontier;
+            if (frontier.length === 0)
+                break;
+            if (d === maxDepth && frontier.length > 0) {
+                truncated = true;
+            }
+        }
+        // Identify leaves: visited nodes that have no outgoing 'calls' edges to other visited nodes
+        // (or no outgoing calls at all)
+        const leaves = [];
+        for (const [id, depth] of nodeDepths) {
+            const outgoing = db
+                .prepare(`SELECT DISTINCT n.id
+           FROM edges e JOIN nodes n ON e.target_id = n.id
+           WHERE e.source_id = ? AND e.kind = 'calls'`)
+                .all(id);
+            if (outgoing.length === 0) {
+                const node = idToNode.get(id);
+                if (node) {
+                    leaves.push({ ...node, depth });
+                }
+            }
+        }
+        const base = {
+            entry,
+            depth: maxDepth,
+            steps,
+            leaves,
+            cycles,
+            totalReached: visited.size - 1, // exclude the entry node itself
+            truncated,
+        };
+        return paginateResult(base, 'steps', { limit: opts.limit, offset: opts.offset });
+    }
+    finally {
+        db.close();
+    }
+}
+//# sourceMappingURL=flow.js.map

package/dist/features/flow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow.js","sourceRoot":"","sources":["../../src/features/flow.js"],"names":[],"mappings":"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"}