@dbt-tools/core 0.3.2

package/dist/analysis/run-results-search.d.ts

@@ -0,0 +1,56 @@
+import type { NodeExecution } from "./execution-analyzer";
+import type { ManifestGraph } from "./manifest-graph";
+/**
+ * Criteria for filtering run results executions
+ */
+export interface RunResultsSearchCriteria {
+    /** Min execution time in seconds */
+    min_execution_time?: number;
+    /** Max execution time in seconds */
+    max_execution_time?: number;
+    /** Filter by status: success, error, skipped, etc. */
+    status?: string | string[];
+    /** Glob or regex pattern for unique_id */
+    unique_id_pattern?: string | RegExp;
+    /** Limit number of results (for top-N queries) */
+    limit?: number;
+    /** Sort by: execution_time_asc | execution_time_desc | unique_id */
+    sort?: "execution_time_asc" | "execution_time_desc" | "unique_id";
+}
+/**
+ * Single bottleneck node in the result
+ */
+export interface BottleneckNode {
+    unique_id: string;
+    name?: string;
+    execution_time: number;
+    rank: number;
+    pct_of_total: number;
+    status: string;
+}
+/**
+ * Result of bottleneck detection
+ */
+export interface BottleneckResult {
+    nodes: BottleneckNode[];
+    total_execution_time: number;
+    criteria_used: "top_n" | "threshold";
+}
+/**
+ * Search and filter NodeExecution array by criteria.
+ * Pure function: returns new array, no side effects.
+ */
+export declare function searchRunResults(executions: NodeExecution[], criteria: RunResultsSearchCriteria): NodeExecution[];
+/**
+ * Detect bottlenecks in execution results.
+ * Uses searchRunResults internally for filtering.
+ */
+export declare function detectBottlenecks(executions: NodeExecution[], options: {
+    mode: "top_n";
+    top: number;
+    graph?: ManifestGraph;
+} | {
+    mode: "threshold";
+    min_seconds: number;
+    graph?: ManifestGraph;
+}): BottleneckResult;

package/dist/analysis/run-results-search.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchRunResults = searchRunResults;
+exports.detectBottlenecks = detectBottlenecks;
+/**
+ * Simple glob match: * matches any chars. Avoids ReDoS from dynamic RegExp.
+ */
+function matchesGlob(text, pattern) {
+    const parts = pattern.split("*");
+    if (parts.length === 1)
+        return text === pattern;
+    let pos = 0;
+    for (let i = 0; i < parts.length; i++) {
+        const part = parts[i];
+        const idx = text.indexOf(part, pos);
+        if (idx === -1)
+            return false;
+        if (i === 0 && idx !== 0)
+            return false;
+        pos = idx + part.length;
+    }
+    return (parts[parts.length - 1] === "" || text.endsWith(parts[parts.length - 1]));
+}
+/**
+ * Filter executions by unique_id pattern (glob or RegExp)
+ */
+function matchesUniqueId(uniqueId, pattern) {
+    if (pattern instanceof RegExp) {
+        return pattern.test(uniqueId);
+    }
+    return matchesGlob(uniqueId, pattern);
+}
+/**
+ * Search and filter NodeExecution array by criteria.
+ * Pure function: returns new array, no side effects.
+ */
+function searchRunResults(executions, criteria) {
+    let result = [...executions];
+    // Filter by status
+    if (criteria.status !== undefined) {
+        const statuses = typeof criteria.status === "string" ? [criteria.status] : criteria.status;
+        const set = new Set(statuses.map((s) => s.toLowerCase()));
+        result = result.filter((e) => set.has((e.status || "unknown").toLowerCase()));
+    }
+    // Filter by execution time range
+    if (criteria.min_execution_time !== undefined) {
+        result = result.filter((e) => { var _a; return ((_a = e.execution_time) !== null && _a !== void 0 ? _a : 0) >= criteria.min_execution_time; });
+    }
+    if (criteria.max_execution_time !== undefined) {
+        result = result.filter((e) => { var _a; return ((_a = e.execution_time) !== null && _a !== void 0 ? _a : 0) <= criteria.max_execution_time; });
+    }
+    // Filter by unique_id pattern
+    if (criteria.unique_id_pattern !== undefined) {
+        result = result.filter((e) => matchesUniqueId(e.unique_id, criteria.unique_id_pattern));
+    }
+    // Sort
+    if (criteria.sort) {
+        result = [...result].sort((a, b) => {
+            var _a, _b, _c, _d;
+            switch (criteria.sort) {
+                case "execution_time_asc":
+                    return ((_a = a.execution_time) !== null && _a !== void 0 ? _a : 0) - ((_b = b.execution_time) !== null && _b !== void 0 ? _b : 0);
+                case "execution_time_desc":
+                    return ((_c = b.execution_time) !== null && _c !== void 0 ? _c : 0) - ((_d = a.execution_time) !== null && _d !== void 0 ? _d : 0);
+                case "unique_id":
+                    return a.unique_id.localeCompare(b.unique_id);
+                default:
+                    return 0;
+            }
+        });
+    }
+    // Limit
+    if (criteria.limit !== undefined && criteria.limit >= 0) {
+        result = result.slice(0, criteria.limit);
+    }
+    return result;
+}
+/**
+ * Get display name for a node from the graph, or fallback to unique_id
+ */
+function getNodeName(uniqueId, graph) {
+    if (!graph)
+        return undefined;
+    const g = graph.getGraph();
+    if (!g.hasNode(uniqueId))
+        return undefined;
+    const attrs = g.getNodeAttributes(uniqueId);
+    return (attrs === null || attrs === void 0 ? void 0 : attrs.name) || undefined;
+}
+/**
+ * Detect bottlenecks in execution results.
+ * Uses searchRunResults internally for filtering.
+ */
+function detectBottlenecks(executions, options) {
+    const totalExecutionTime = executions.reduce((sum, e) => { var _a; return sum + ((_a = e.execution_time) !== null && _a !== void 0 ? _a : 0); }, 0);
+    let filtered;
+    if (options.mode === "top_n") {
+        filtered = searchRunResults(executions, {
+            sort: "execution_time_desc",
+            limit: options.top,
+        });
+    }
+    else {
+        filtered = searchRunResults(executions, {
+            min_execution_time: options.min_seconds,
+            sort: "execution_time_desc",
+        });
+    }
+    const nodes = filtered.map((e, i) => {
+        var _a;
+        const time = (_a = e.execution_time) !== null && _a !== void 0 ? _a : 0;
+        const pct = totalExecutionTime > 0 ? (time / totalExecutionTime) * 100 : 0;
+        return {
+            unique_id: e.unique_id,
+            name: getNodeName(e.unique_id, options.graph),
+            execution_time: time,
+            rank: i + 1,
+            pct_of_total: Math.round(pct * 10) / 10,
+            status: e.status || "unknown",
+        };
+    });
+    return {
+        nodes,
+        total_execution_time: totalExecutionTime,
+        criteria_used: options.mode === "top_n" ? "top_n" : "threshold",
+    };
+}

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

@@ -0,0 +1,30 @@
+export interface ColumnDependency {
+    sourceTable: string;
+    sourceColumn: string;
+}
+export type ColumnDependencyMap = Record<string, ColumnDependency[]>;
+/**
+ * SQLAnalyzer performs AST analysis on SQL to infer column-level lineage.
+ */
+export declare class SQLAnalyzer {
+    private parser;
+    constructor();
+    /**
+     * Analyze SQL to extract column-level dependencies.
+     * @param sql The compiled SQL code.
+     * @param dialect The SQL dialect (e.g., 'mysql', 'postgresql', 'snowflake').
+     * @returns A map of target column names to their source dependencies.
+     */
+    analyze(sql: string, dialect?: string): ColumnDependencyMap;
+    private analyzeSelect;
+    private buildCteMap;
+    private getColumnTargetName;
+    private processSelectColumns;
+    private extractColumnName;
+    private buildTableMap;
+    private resolveExpressionDependencies;
+    private traverseAst;
+    private collectColumnRefDeps;
+    private pushColumnDeps;
+    private uniqueDependencies;
+}

package/dist/analysis/sql-analyzer.js

@@ -0,0 +1,218 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SQLAnalyzer = void 0;
+const node_sql_parser_1 = require("node-sql-parser");
+/**
+ * SQLAnalyzer performs AST analysis on SQL to infer column-level lineage.
+ */
+class SQLAnalyzer {
+    constructor() {
+        this.parser = new node_sql_parser_1.Parser();
+    }
+    /**
+     * Analyze SQL to extract column-level dependencies.
+     * @param sql The compiled SQL code.
+     * @param dialect The SQL dialect (e.g., 'mysql', 'postgresql', 'snowflake').
+     * @returns A map of target column names to their source dependencies.
+     */
+    analyze(sql, dialect = "mysql") {
+        try {
+            let cleanSql = sql.trim();
+            while (cleanSql.endsWith(";")) {
+                cleanSql = cleanSql.slice(0, -1);
+            }
+            const ast = this.parser.astify(cleanSql, { database: dialect });
+            if (Array.isArray(ast)) {
+                const selectAst = ast.find((s) => s.type === "select");
+                return selectAst ? this.analyzeSelect(selectAst, dialect) : {};
+            }
+            return this.analyzeSelect(ast, dialect);
+        }
+        catch (_a) {
+            return {};
+        }
+    }
+    analyzeSelect(select, dialect, parentCteMap = {}) {
+        if (!select || select.type !== "select")
+            return {};
+        const tableMap = this.buildTableMap((Array.isArray(select.from) ? select.from : []));
+        const cteMap = this.buildCteMap(select, dialect, parentCteMap);
+        if (!select.columns || !Array.isArray(select.columns))
+            return {};
+        return this.processSelectColumns(select.columns, tableMap, cteMap);
+    }
+    buildCteMap(select, dialect, parentCteMap) {
+        var _a;
+        const cteMap = Object.assign({}, parentCteMap);
+        if (!select.with || !Array.isArray(select.with))
+            return cteMap;
+        for (const cte of select.with) {
+            if ((_a = cte.stmt) === null || _a === void 0 ? void 0 : _a.ast) {
+                cteMap[cte.name.value] = this.analyzeSelect(cte.stmt.ast, dialect, cteMap);
+            }
+        }
+        return cteMap;
+    }
+    getColumnTargetName(col) {
+        const asVal = col.as;
+        if (asVal !== undefined && asVal !== null) {
+            return typeof asVal === "string"
+                ? asVal
+                : typeof asVal.value === "string"
+                    ? asVal.value
+                    : undefined;
+        }
+        if (col.expr &&
+            typeof col.expr === "object" &&
+            col.expr.type === "column_ref") {
+            return this.extractColumnName(col.expr.column);
+        }
+        return undefined;
+    }
+    processSelectColumns(columns, tableMap, cteMap) {
+        const dependencies = {};
+        for (const col of columns) {
+            const targetName = this.getColumnTargetName(col);
+            if (!targetName || targetName === "*") {
+                const colColumn = col.expr &&
+                    typeof col.expr === "object" &&
+                    col.expr.type === "column_ref"
+                    ? this.extractColumnName(col.expr.column)
+                    : undefined;
+                if (targetName === "*" || colColumn === "*") {
+                    const starDeps = this.resolveExpressionDependencies(col.expr, tableMap, cteMap);
+                    dependencies["*"] = this.uniqueDependencies(starDeps);
+                }
+                continue;
+            }
+            const colDeps = this.resolveExpressionDependencies(col.expr, tableMap, cteMap);
+            const uniqueDeps = this.uniqueDependencies(colDeps);
+            if (uniqueDeps.length > 0) {
+                dependencies[targetName] = uniqueDeps;
+            }
+        }
+        return dependencies;
+    }
+    extractColumnName(column) {
+        if (typeof column === "string")
+            return column;
+        if (column && typeof column === "object") {
+            const c = column;
+            const expr = c.expr;
+            if (expr &&
+                typeof expr === "object" &&
+                expr.type === "default") {
+                return String(expr.value);
+            }
+        }
+        return String(column);
+    }
+    buildTableMap(from) {
+        const map = {};
+        if (!from || !Array.isArray(from))
+            return map;
+        for (const item of from) {
+            const f = item;
+            if (f.table) {
+                const actualTable = f.table;
+                const alias = f.as || actualTable;
+                map[alias] = actualTable;
+            }
+            else if (f.expr && f.expr.ast) {
+                const subqueryAlias = f.as;
+                if (subqueryAlias) {
+                    map[subqueryAlias] = `__subquery_${subqueryAlias}__`;
+                }
+            }
+        }
+        return map;
+    }
+    resolveExpressionDependencies(expr, tableMap, cteMap) {
+        const deps = [];
+        this.traverseAst(expr, tableMap, cteMap, deps);
+        return deps;
+    }
+    traverseAst(node, tableMap, cteMap, deps) {
+        if (!node || typeof node !== "object")
+            return;
+        const n = node;
+        switch (n.type) {
+            case "column_ref":
+                this.collectColumnRefDeps(n, tableMap, cteMap, deps);
+                break;
+            case "binary_expr":
+                this.traverseAst(n.left, tableMap, cteMap, deps);
+                this.traverseAst(n.right, tableMap, cteMap, deps);
+                break;
+            case "function": {
+                const args = n.args;
+                if (args === null || args === void 0 ? void 0 : args.value)
+                    for (const a of args.value)
+                        this.traverseAst(a, tableMap, cteMap, deps);
+                break;
+            }
+            case "aggr_func": {
+                const args = n.args;
+                if (args === null || args === void 0 ? void 0 : args.expr)
+                    this.traverseAst(args.expr, tableMap, cteMap, deps);
+                break;
+            }
+            case "case": {
+                const args = n.args;
+                if (args)
+                    for (const arg of args) {
+                        this.traverseAst(arg.cond, tableMap, cteMap, deps);
+                        this.traverseAst(arg.result, tableMap, cteMap, deps);
+                    }
+                this.traverseAst(n.fallback, tableMap, cteMap, deps);
+                break;
+            }
+            case "cast":
+                this.traverseAst(n.expr, tableMap, cteMap, deps);
+                break;
+        }
+    }
+    collectColumnRefDeps(n, tableMap, cteMap, deps) {
+        var _a;
+        const tableAlias = n.table;
+        const columnName = this.extractColumnName(n.column);
+        if (tableAlias) {
+            const actualTable = tableMap[tableAlias];
+            if (actualTable) {
+                this.pushColumnDeps(actualTable, columnName, cteMap, deps);
+            }
+            return;
+        }
+        const tables = Object.values(tableMap);
+        if (tables.length === 1) {
+            this.pushColumnDeps(tables[0], columnName, cteMap, deps);
+            return;
+        }
+        for (const table of tables) {
+            const cteCols = (_a = cteMap[table]) === null || _a === void 0 ? void 0 : _a[columnName];
+            if (cteCols === null || cteCols === void 0 ? void 0 : cteCols.length)
+                deps.push(...cteCols);
+        }
+    }
+    pushColumnDeps(actualTable, columnName, cteMap, deps) {
+        var _a, _b;
+        const cteDeps = (_b = (_a = cteMap[actualTable]) === null || _a === void 0 ? void 0 : _a[columnName]) !== null && _b !== void 0 ? _b : [];
+        if (cteDeps.length > 0) {
+            deps.push(...cteDeps);
+        }
+        else {
+            deps.push({ sourceTable: actualTable, sourceColumn: columnName });
+        }
+    }
+    uniqueDependencies(deps) {
+        const seen = new Set();
+        return deps.filter((d) => {
+            const key = `${d.sourceTable}.${d.sourceColumn}`;
+            if (seen.has(key))
+                return false;
+            seen.add(key);
+            return true;
+        });
+    }
+}
+exports.SQLAnalyzer = SQLAnalyzer;

package/dist/browser.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Browser-safe entry point for @dbt-tools/core.
+ * Re-exports only APIs that do not depend on Node.js (fs, path).
+ */
+export { ManifestGraph } from "./analysis/manifest-graph";
+export { ExecutionAnalyzer } from "./analysis/execution-analyzer";
+export { searchRunResults, detectBottlenecks, } from "./analysis/run-results-search";
+export { buildAnalysisSnapshotFromArtifacts, buildAnalysisSnapshotFromParsedArtifacts, } from "./analysis/analysis-snapshot";
+export type { NodeExecution, ExecutionSummary, CriticalPath, } from "./analysis/execution-analyzer";
+export type { BottleneckNode, BottleneckResult, RunResultsSearchCriteria, } from "./analysis/run-results-search";
+export type { AnalysisSnapshot, AnalysisSnapshotBuildTimings, DependencyPreview, ExecutionRow, GanttItem, GraphSnapshot, MetricDefinition, ResourceConnectionSummary, ResourceDefinition, ResourceGroup, ResourceNode, SemanticModelDefinition, StatusBreakdownItem, StatusTone, ThreadStat, TimelineAdjacencyEntry, } from "./analysis/analysis-snapshot";

package/dist/browser.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAnalysisSnapshotFromParsedArtifacts = exports.buildAnalysisSnapshotFromArtifacts = exports.detectBottlenecks = exports.searchRunResults = exports.ExecutionAnalyzer = exports.ManifestGraph = void 0;
+/**
+ * Browser-safe entry point for @dbt-tools/core.
+ * Re-exports only APIs that do not depend on Node.js (fs, path).
+ */
+var manifest_graph_1 = require("./analysis/manifest-graph");
+Object.defineProperty(exports, "ManifestGraph", { enumerable: true, get: function () { return manifest_graph_1.ManifestGraph; } });
+var execution_analyzer_1 = require("./analysis/execution-analyzer");
+Object.defineProperty(exports, "ExecutionAnalyzer", { enumerable: true, get: function () { return execution_analyzer_1.ExecutionAnalyzer; } });
+var run_results_search_1 = require("./analysis/run-results-search");
+Object.defineProperty(exports, "searchRunResults", { enumerable: true, get: function () { return run_results_search_1.searchRunResults; } });
+Object.defineProperty(exports, "detectBottlenecks", { enumerable: true, get: function () { return run_results_search_1.detectBottlenecks; } });
+var analysis_snapshot_1 = require("./analysis/analysis-snapshot");
+Object.defineProperty(exports, "buildAnalysisSnapshotFromArtifacts", { enumerable: true, get: function () { return analysis_snapshot_1.buildAnalysisSnapshotFromArtifacts; } });
+Object.defineProperty(exports, "buildAnalysisSnapshotFromParsedArtifacts", { enumerable: true, get: function () { return analysis_snapshot_1.buildAnalysisSnapshotFromParsedArtifacts; } });

package/dist/errors/error-handler.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Structured error format for JSON output
+ */
+export interface StructuredError {
+    error: string;
+    code: string;
+    message: string;
+    details?: unknown;
+}
+/**
+ * ErrorHandler provides structured error formatting for agent consumption
+ */
+export declare class ErrorHandler {
+    /**
+     * Format an error for output (JSON when not TTY, human-readable when TTY)
+     */
+    static formatError(error: Error, isTTY: boolean): string | StructuredError;
+    /**
+     * Create a validation error
+     */
+    static createValidationError(message: string, field?: string): Error;
+    /**
+     * Get error code from error type
+     */
+    private static getErrorCode;
+}

package/dist/errors/error-handler.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorHandler = void 0;
+/**
+ * ErrorHandler provides structured error formatting for agent consumption
+ */
+class ErrorHandler {
+    /**
+     * Format an error for output (JSON when not TTY, human-readable when TTY)
+     */
+    static formatError(error, isTTY) {
+        const structured = {
+            error: error.name || "Error",
+            code: this.getErrorCode(error),
+            message: error.message,
+        };
+        // Add details for validation errors
+        if (error.name === "ValidationError" && "field" in error) {
+            structured.details = { field: error.field };
+        }
+        if (isTTY) {
+            // Human-readable format
+            return `Error [${structured.code}]: ${structured.message}`;
+        }
+        // JSON format for agents
+        return structured;
+    }
+    /**
+     * Create a validation error
+     */
+    static createValidationError(message, field) {
+        const error = new Error(message);
+        error.name = "ValidationError";
+        if (field) {
+            error.field = field;
+        }
+        return error;
+    }
+    /**
+     * Get error code from error type
+     */
+    static getErrorCode(error) {
+        if (error.name === "ValidationError") {
+            return "VALIDATION_ERROR";
+        }
+        if (error.message.includes("not found") ||
+            error.message.includes("File not found")) {
+            return "FILE_NOT_FOUND";
+        }
+        if (error.message.includes("Failed to parse")) {
+            return "PARSE_ERROR";
+        }
+        if (error.message.includes("Unsupported dbt version")) {
+            return "UNSUPPORTED_VERSION";
+        }
+        return "UNKNOWN_ERROR";
+    }
+}
+exports.ErrorHandler = ErrorHandler;

package/dist/formatting/field-filter.d.ts

@@ -0,0 +1,29 @@
+/**
+ * FieldFilter provides field selection to reduce context window usage.
+ * Supports simple and nested field paths.
+ */
+export declare class FieldFilter {
+    /**
+     * Filter fields from an object based on a comma-separated field list
+     */
+    static filterFields<T>(data: T, fields?: string): Partial<T>;
+    /**
+     * Filter fields from an array of objects
+     */
+    static filterArrayFields<T>(data: T[], fields?: string): Partial<T>[];
+    /**
+     * Filter fields from an object using field paths
+     */
+    private static filterObjectFields;
+    /** Rejects prototype-pollution keys (__proto__, constructor, prototype). */
+    private static isUnsafeKey;
+    /**
+     * Get a nested value from an object using dot notation.
+     * Rejects prototype-pollution keys (__proto__, constructor, prototype).
+     */
+    private static getNestedValue;
+    /**
+     * Set a nested value in an object using dot notation
+     */
+    private static setNestedValue;
+}