@dbt-tools/core 0.3.2

package/dist/analysis/dependency-service.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DependencyService = void 0;
+const field_filter_1 = require("../formatting/field-filter");
+/**
+ * DependencyService wraps ManifestGraph dependency methods with formatting
+ * and field filtering capabilities.
+ */
+class DependencyService {
+    /**
+     * Get dependencies for a resource with optional field filtering, depth limit, output format, and build order.
+     * @param depth - Optional max traversal depth; 1 = immediate neighbors, undefined = all levels
+     * @param format - Output structure: flat list or nested tree
+     * @param buildOrder - When true and direction is upstream, return dependencies in topological build order
+     */
+    static getDependencies(graph, resourceId, direction, fields, depth, format, buildOrder) {
+        if (format === "tree" && !(direction === "upstream" && buildOrder)) {
+            return this.getDependenciesTree(graph, resourceId, direction, fields, depth);
+        }
+        // Flat format (or tree with buildOrder: use flat + build order)
+        const dependencyEntries = direction === "upstream" && buildOrder
+            ? graph.getUpstreamBuildOrder(resourceId, depth)
+            : direction === "upstream"
+                ? graph.getUpstream(resourceId, depth)
+                : graph.getDownstream(resourceId, depth);
+        const graphologyGraph = graph.getGraph();
+        const dependencies = dependencyEntries.map(({ nodeId, depth: depDepth }) => {
+            const attributes = graphologyGraph.getNodeAttributes(nodeId);
+            return Object.assign(Object.assign({}, attributes), { unique_id: nodeId, resource_type: attributes.resource_type || "unknown", name: attributes.name || nodeId, package_name: attributes.package_name || "", depth: depDepth });
+        });
+        let filteredDependencies = dependencies;
+        if (fields) {
+            filteredDependencies = field_filter_1.FieldFilter.filterArrayFields(dependencies, fields);
+        }
+        return Object.assign(Object.assign({ resource_id: resourceId, direction }, (buildOrder && direction === "upstream" && { build_order: true })), { dependencies: filteredDependencies, count: filteredDependencies.length });
+    }
+    /**
+     * Build nested tree from BFS entries with parent tracking
+     */
+    static getDependenciesTree(graph, resourceId, direction, fields, depth) {
+        var _a, _b;
+        const entries = direction === "upstream"
+            ? graph.getUpstreamWithParents(resourceId, depth)
+            : graph.getDownstreamWithParents(resourceId, depth);
+        const graphologyGraph = graph.getGraph();
+        // Build parent -> children map (parentId is the BFS predecessor)
+        const childrenByParent = new Map();
+        for (const { nodeId, depth: depDepth, parentId } of entries) {
+            const existing = (_a = childrenByParent.get(parentId)) !== null && _a !== void 0 ? _a : [];
+            existing.push({ nodeId, depth: depDepth });
+            childrenByParent.set(parentId, existing);
+        }
+        const buildNode = (nodeId, depDepth) => {
+            var _a;
+            const attributes = graphologyGraph.getNodeAttributes(nodeId);
+            const childEntries = (_a = childrenByParent.get(nodeId)) !== null && _a !== void 0 ? _a : [];
+            const childNodes = childEntries.map(({ nodeId: cId, depth: cDepth }) => buildNode(cId, cDepth));
+            const node = Object.assign(Object.assign({}, attributes), { unique_id: nodeId, resource_type: attributes.resource_type || "unknown", name: attributes.name || nodeId, package_name: attributes.package_name || "", depth: depDepth, dependencies: childNodes });
+            if (fields) {
+                const filtered = field_filter_1.FieldFilter.filterFields(node, fields);
+                return Object.assign(Object.assign({}, filtered), { dependencies: node.dependencies });
+            }
+            return node;
+        };
+        const rootChildren = (_b = childrenByParent.get(resourceId)) !== null && _b !== void 0 ? _b : [];
+        const dependencyTrees = rootChildren.map(({ nodeId, depth: d }) => buildNode(nodeId, d));
+        return {
+            resource_id: resourceId,
+            direction,
+            dependencies: dependencyTrees,
+            count: entries.length,
+        };
+    }
+}
+exports.DependencyService = DependencyService;

package/dist/analysis/execution-analyzer.d.ts

@@ -0,0 +1,85 @@
+import type { ParsedRunResults } from "dbt-artifacts-parser/run_results";
+import type { ManifestGraph } from "./manifest-graph";
+/**
+ * Execution timing information for a single node
+ */
+export interface NodeExecution {
+    unique_id: string;
+    status: string;
+    execution_time: number;
+    started_at?: string;
+    completed_at?: string;
+    thread_id?: string;
+}
+/**
+ * Critical path analysis result
+ */
+export interface CriticalPath {
+    path: string[];
+    total_time: number;
+}
+/**
+ * Execution summary statistics
+ */
+export interface ExecutionSummary {
+    total_execution_time: number;
+    total_nodes: number;
+    nodes_by_status: Record<string, number>;
+    critical_path?: CriticalPath;
+    node_executions: NodeExecution[];
+}
+/**
+ * ExecutionAnalyzer processes run_results.json to extract timing information
+ * and correlate it with the dependency graph.
+ */
+export declare class ExecutionAnalyzer {
+    private runResults;
+    private graph;
+    constructor(runResults: ParsedRunResults, graph: ManifestGraph);
+    /**
+     * Get execution summary with statistics
+     */
+    getSummary(): ExecutionSummary;
+    /**
+     * Extract execution information for each node
+     */
+    getNodeExecutions(): NodeExecution[];
+    /**
+     * Calculate the critical path (longest path through the dependency graph)
+     */
+    calculateCriticalPath(nodeExecutions: NodeExecution[]): CriticalPath | undefined;
+    /**
+     * Find the longest path from a node to root (nodes with no dependencies)
+     */
+    private findLongestPathToRoot;
+    /**
+     * Calculate total execution time for a path
+     */
+    private calculatePathTime;
+    /**
+     * Returns the absolute epoch-ms timestamp of the earliest executed node,
+     * or null if no timing data is available. Useful for converting relative
+     * Gantt offsets to wall-clock timestamps.
+     */
+    getRunStartedAt(): number | null;
+    private parseTimingInterval;
+    /**
+     * Wall-clock span and optional compile/execute intervals (epoch ms).
+     */
+    private wallClockFromResult;
+    /**
+     * Get Gantt chart data for visualization
+     */
+    getGanttData(): Array<{
+        unique_id: string;
+        name: string;
+        start: number;
+        end: number;
+        duration: number;
+        status: string;
+        compileStart: number | null;
+        compileEnd: number | null;
+        executeStart: number | null;
+        executeEnd: number | null;
+    }>;
+}

package/dist/analysis/execution-analyzer.js

@@ -0,0 +1,245 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExecutionAnalyzer = void 0;
+/**
+ * ExecutionAnalyzer processes run_results.json to extract timing information
+ * and correlate it with the dependency graph.
+ */
+class ExecutionAnalyzer {
+    constructor(runResults, graph) {
+        this.runResults = runResults;
+        this.graph = graph;
+    }
+    /**
+     * Get execution summary with statistics
+     */
+    getSummary() {
+        const nodeExecutions = this.getNodeExecutions();
+        const nodesByStatus = {};
+        let totalExecutionTime = 0;
+        for (const execution of nodeExecutions) {
+            // Count by status
+            const status = execution.status || "unknown";
+            nodesByStatus[status] = (nodesByStatus[status] || 0) + 1;
+            // Sum execution time
+            totalExecutionTime += execution.execution_time || 0;
+        }
+        // Calculate critical path
+        const criticalPath = this.calculateCriticalPath(nodeExecutions);
+        return {
+            total_execution_time: totalExecutionTime,
+            total_nodes: nodeExecutions.length,
+            nodes_by_status: nodesByStatus,
+            critical_path: criticalPath,
+            node_executions: nodeExecutions,
+        };
+    }
+    /**
+     * Extract execution information for each node
+     */
+    getNodeExecutions() {
+        if (!this.runResults.results || !Array.isArray(this.runResults.results)) {
+            return [];
+        }
+        const results = this.runResults.results;
+        return results.map((result) => {
+            var _a, _b, _c;
+            // Find execute timing (most relevant for execution time)
+            const timingArray = result.timing || [];
+            const executeTiming = timingArray.find((t) => t.name === "execute");
+            const compileTiming = timingArray.find((t) => t.name === "compile");
+            // Use execute timing if available, otherwise fall back to compile
+            const timing = executeTiming || compileTiming || timingArray[0];
+            return {
+                unique_id: result.unique_id || "",
+                status: result.status || "unknown",
+                execution_time: result.execution_time || 0,
+                started_at: (_a = timing === null || timing === void 0 ? void 0 : timing.started_at) !== null && _a !== void 0 ? _a : undefined,
+                completed_at: (_b = timing === null || timing === void 0 ? void 0 : timing.completed_at) !== null && _b !== void 0 ? _b : undefined,
+                thread_id: (_c = result.thread_id) !== null && _c !== void 0 ? _c : undefined,
+            };
+        });
+    }
+    /**
+     * Calculate the critical path (longest path through the dependency graph)
+     */
+    calculateCriticalPath(nodeExecutions) {
+        // Create a map of node executions by unique_id
+        const executionMap = new Map();
+        for (const exec of nodeExecutions) {
+            executionMap.set(exec.unique_id, exec);
+        }
+        // Find all leaf nodes (nodes with no downstream dependents)
+        const leafNodes = [];
+        const graph = this.graph.getGraph();
+        graph.forEachNode((nodeId) => {
+            const outboundNeighbors = graph.outboundNeighbors(nodeId);
+            if (outboundNeighbors.length === 0 && executionMap.has(nodeId)) {
+                leafNodes.push(nodeId);
+            }
+        });
+        if (leafNodes.length === 0) {
+            return undefined;
+        }
+        // For each leaf node, find the longest path from root
+        let maxPath = [];
+        let maxTime = 0;
+        for (const leafNode of leafNodes) {
+            const path = this.findLongestPathToRoot(leafNode, executionMap);
+            const pathTime = this.calculatePathTime(path, executionMap);
+            if (pathTime > maxTime) {
+                maxTime = pathTime;
+                maxPath = path;
+            }
+        }
+        if (maxPath.length === 0) {
+            return undefined;
+        }
+        return {
+            path: maxPath,
+            total_time: maxTime,
+        };
+    }
+    /**
+     * Find the longest path from a node to root (nodes with no dependencies)
+     */
+    findLongestPathToRoot(startNode, executionMap) {
+        const graph = this.graph.getGraph();
+        const visited = new Set();
+        let longestPath = [];
+        const dfs = (currentNode, currentPath) => {
+            if (visited.has(currentNode)) {
+                return;
+            }
+            visited.add(currentNode);
+            const newPath = [...currentPath, currentNode];
+            // Update longest path if this is longer
+            if (newPath.length > longestPath.length) {
+                longestPath = newPath;
+            }
+            // Traverse upstream (inbound neighbors)
+            const inboundNeighbors = graph.inboundNeighbors(currentNode);
+            for (const neighbor of inboundNeighbors) {
+                if (executionMap.has(neighbor)) {
+                    dfs(neighbor, newPath);
+                }
+            }
+            visited.delete(currentNode);
+        };
+        dfs(startNode, []);
+        return longestPath.reverse(); // Reverse to get root-to-leaf order
+    }
+    /**
+     * Calculate total execution time for a path
+     */
+    calculatePathTime(path, executionMap) {
+        let totalTime = 0;
+        for (const nodeId of path) {
+            const exec = executionMap.get(nodeId);
+            if (exec) {
+                totalTime += exec.execution_time || 0;
+            }
+        }
+        return totalTime;
+    }
+    /**
+     * Returns the absolute epoch-ms timestamp of the earliest executed node,
+     * or null if no timing data is available. Useful for converting relative
+     * Gantt offsets to wall-clock timestamps.
+     */
+    getRunStartedAt() {
+        const executions = this.getNodeExecutions();
+        const timestamps = executions
+            .map((exec) => exec.started_at ? new Date(exec.started_at).getTime() : null)
+            .filter((t) => t !== null);
+        if (timestamps.length === 0)
+            return null;
+        return Math.min(...timestamps);
+    }
+    parseTimingInterval(timing) {
+        if (!timing)
+            return null;
+        const started = timing.started_at;
+        const completed = timing.completed_at;
+        if (!started || !completed)
+            return null;
+        const startMs = new Date(started).getTime();
+        const endMs = new Date(completed).getTime();
+        if (Number.isNaN(startMs) || Number.isNaN(endMs))
+            return null;
+        return { start: startMs, end: endMs };
+    }
+    /**
+     * Wall-clock span and optional compile/execute intervals (epoch ms).
+     */
+    wallClockFromResult(result) {
+        const timingArray = result.timing || [];
+        const executeTiming = timingArray.find((t) => t.name === "execute");
+        const compileTiming = timingArray.find((t) => t.name === "compile");
+        const compile = this.parseTimingInterval(compileTiming);
+        const execute = this.parseTimingInterval(executeTiming);
+        const starts = [];
+        const ends = [];
+        if (compile) {
+            starts.push(compile.start);
+            ends.push(compile.end);
+        }
+        if (execute) {
+            starts.push(execute.start);
+            ends.push(execute.end);
+        }
+        if (starts.length === 0)
+            return null;
+        return {
+            wallStart: Math.min(...starts),
+            wallEnd: Math.max(...ends),
+            compile,
+            execute,
+        };
+    }
+    /**
+     * Get Gantt chart data for visualization
+     */
+    getGanttData() {
+        if (!this.runResults.results || !Array.isArray(this.runResults.results)) {
+            return [];
+        }
+        const graphologyGraph = this.graph.getGraph();
+        const rows = [];
+        for (const result of this.runResults
+            .results) {
+            const uniqueId = result.unique_id || "";
+            if (!uniqueId)
+                continue;
+            const wall = this.wallClockFromResult(result);
+            if (!wall)
+                continue;
+            const nodeAttributes = graphologyGraph.hasNode(uniqueId)
+                ? graphologyGraph.getNodeAttributes(uniqueId)
+                : undefined;
+            const name = (nodeAttributes === null || nodeAttributes === void 0 ? void 0 : nodeAttributes.name) || uniqueId;
+            const status = result.status || "unknown";
+            rows.push({ unique_id: uniqueId, name, status, wall });
+        }
+        if (rows.length === 0)
+            return [];
+        const minStart = Math.min(...rows.map((r) => r.wall.wallStart));
+        return rows.map((row) => {
+            const { wall } = row;
+            const rel = (t) => t - minStart;
+            return {
+                unique_id: row.unique_id,
+                name: row.name,
+                start: rel(wall.wallStart),
+                end: rel(wall.wallEnd),
+                duration: wall.wallEnd - wall.wallStart,
+                status: row.status,
+                compileStart: wall.compile ? rel(wall.compile.start) : null,
+                compileEnd: wall.compile ? rel(wall.compile.end) : null,
+                executeStart: wall.execute ? rel(wall.execute.start) : null,
+                executeEnd: wall.execute ? rel(wall.execute.end) : null,
+            };
+        });
+    }
+}
+exports.ExecutionAnalyzer = ExecutionAnalyzer;

package/dist/analysis/manifest-graph.d.ts

@@ -0,0 +1,118 @@
+import { DirectedGraph } from "graphology";
+import type { ParsedManifest } from "dbt-artifacts-parser/manifest";
+import type { ParsedCatalog } from "dbt-artifacts-parser/catalog";
+import type { GraphNodeAttributes, GraphEdgeAttributes, GraphSummary } from "../types";
+import type { ColumnDependencyMap } from "./sql-analyzer";
+/**
+ * ManifestGraph builds and manages a directed graph from a dbt manifest.
+ *
+ * This class transforms dbt artifacts into a graphology graph, enabling
+ * efficient graph operations like cycle detection, path finding, and traversal.
+ */
+export declare class ManifestGraph {
+    private graph;
+    private relationMap;
+    constructor(manifest: ParsedManifest);
+    /**
+     * Build the graph from manifest data
+     */
+    private buildGraph;
+    /**
+     * Add nodes from manifest to the graph
+     */
+    /** Map relation_name (lowercase) to unique_id when present on manifest entries. */
+    private registerRelationName;
+    private addNodes;
+    private addNodeEntries;
+    private addSourceEntries;
+    private addMacroEntries;
+    private addExposureEntries;
+    private addMetricEntries;
+    private addSemanticModelEntries;
+    private addUnitTestEntries;
+    /**
+     * Add edges based on dependencies
+     */
+    private addEdges;
+    private addEdgesFromParentMap;
+    private addEdgesFromDependsOn;
+    private addEdgesFromNodeDependsOn;
+    private addEdgesFromExposureDependsOn;
+    private addEdgesFromMetricDependsOn;
+    /**
+     * Extract resource type from manifest node
+     */
+    private extractResourceType;
+    /**
+     * Infer dependency type from node ID
+     */
+    private inferDependencyType;
+    /**
+     * Get the underlying graphology graph
+     */
+    getGraph(): DirectedGraph<GraphNodeAttributes, GraphEdgeAttributes>;
+    /**
+     * Get summary statistics about the graph
+     */
+    getSummary(): GraphSummary;
+    /**
+     * Get all upstream dependencies of a node using BFS.
+     * @param nodeId - The node to find upstream dependencies for
+     * @param maxDepth - Optional limit; 1 = immediate neighbors only, undefined = all levels
+     * @returns Array of { nodeId, depth } where depth is the shortest distance from the node
+     */
+    getUpstream(nodeId: string, maxDepth?: number): Array<{
+        nodeId: string;
+        depth: number;
+    }>;
+    /**
+     * Get all downstream dependents of a node using BFS.
+     * @param nodeId - The node to find downstream dependents for
+     * @param maxDepth - Optional limit; 1 = immediate neighbors only, undefined = all levels
+     * @returns Array of { nodeId, depth } where depth is the shortest distance from the node
+     */
+    getDownstream(nodeId: string, maxDepth?: number): Array<{
+        nodeId: string;
+        depth: number;
+    }>;
+    /**
+     * Get upstream dependencies with parent info for tree construction.
+     * @returns Array of { nodeId, depth, parentId } where parentId is the BFS predecessor
+     */
+    getUpstreamWithParents(nodeId: string, maxDepth?: number): Array<{
+        nodeId: string;
+        depth: number;
+        parentId: string;
+    }>;
+    /**
+     * Get upstream dependencies in build order (topological sort).
+     * Sources and root models first, then models that depend on them.
+     * @param nodeId - The node to find upstream dependencies for
+     * @param maxDepth - Optional limit; 1 = immediate neighbors only, undefined = all levels
+     * @returns Array of { nodeId, depth } in build order
+     */
+    getUpstreamBuildOrder(nodeId: string, maxDepth?: number): Array<{
+        nodeId: string;
+        depth: number;
+    }>;
+    /**
+     * Get downstream dependents with parent info for tree construction.
+     * @returns Array of { nodeId, depth, parentId } where parentId is the BFS predecessor
+     */
+    getDownstreamWithParents(nodeId: string, maxDepth?: number): Array<{
+        nodeId: string;
+        depth: number;
+        parentId: string;
+    }>;
+    /**
+     * Add field nodes from catalog metadata
+     */
+    addFieldNodes(catalog: ParsedCatalog): void;
+    private processCatalogColumns;
+    /**
+     * Add field-to-field edges based on SQL analysis
+     */
+    addFieldEdges(childNodeId: string, dependencies: ColumnDependencyMap): void;
+    private ensureFieldNode;
+    private resolveRelationToUniqueId;
+}