@dbt-tools/core 0.3.2 → 0.3.4

package/README.md

@@ -1,12 +1,24 @@
 # @dbt-tools/core
 
-Core library for dbt artifact graph management and analysis.
-
-## Features
+Core library for dbt artifact graph management and analysis. Provides the analysis engine used by [`@dbt-tools/cli`](../cli/README.md) and [`@dbt-tools/web`](../web/README.md).
+
+---
+
+## Architecture
+
+```mermaid
+graph TD
+  AF[dbt-artifacts-parser\nparseManifest · parseRunResults]
+  AF --> AL[ArtifactLoader]
+  AL --> MG[ManifestGraph\ngraphology DAG]
+  AL --> EA[ExecutionAnalyzer\ncritical path · Gantt]
+  MG --> DS[DependencyService\nupstream · downstream · build order]
+  MG --> GE[GraphExport\nJSON · DOT · GEXF]
+  EA --> OF[OutputFormatter\nfield filtering · JSON/text]
+  OF --> FF[FieldFilter]
+```
 
-- **ManifestGraph**: Build and manage dependency graphs from dbt manifests
-- **ExecutionAnalyzer**: Analyze execution results and calculate critical paths
-- **High Performance**: Optimized for large manifests with 100k+ nodes
+---
 
 ## Installation
 
@@ -14,38 +26,166 @@ Core library for dbt artifact graph management and analysis.
 pnpm add @dbt-tools/core
 ```
 
+---
+
 ## Usage
 
 ```typescript
 import { parseManifest } from "dbt-artifacts-parser/manifest";
-import { ManifestGraph } from "@dbt-tools/core";
+import { ManifestGraph, ExecutionAnalyzer } from "@dbt-tools/core";
 
+// Build dependency graph
 const manifest = parseManifest(manifestJson);
 const graph = new ManifestGraph(manifest);
 
-// Get summary statistics
+// Summary statistics
 const summary = graph.getSummary();
-console.log(`Total nodes: ${summary.total_nodes}`);
-console.log(`Has cycles: ${summary.has_cycles}`);
+console.log(`Nodes: ${summary.total_nodes}, Cycles: ${summary.has_cycles}`);
 
-// Get upstream dependencies
+// Dependency traversal
 const upstream = graph.getUpstream("model.my_project.my_model");
-
-// Get downstream dependents
 const downstream = graph.getDownstream("model.my_project.my_model");
+
+// Execution analysis
+const analyzer = new ExecutionAnalyzer(runResults, manifest);
+const report = analyzer.getSummary();
+console.log(
+  `Critical path: ${report.critical_path.map((n) => n.name).join(" → ")}`,
+);
+```
+
+---
+
+## Exports
+
+### Node.js (default)
+
+```typescript
+import {
+  // Analysis
+  ManifestGraph,
+  ExecutionAnalyzer,
+  DependencyService,
+  SqlAnalyzer,
+  RunResultsSearch,
+  AnalysisSnapshot,
+  // I/O
+  ArtifactLoader,
+  // Validation
+  InputValidator,
+  // Formatting
+  OutputFormatter,
+  FieldFilter,
+  GraphExport,
+  // Errors
+  ErrorHandler,
+  // Introspection
+  SchemaGenerator,
+} from "@dbt-tools/core";
+```
+
+### Browser (no Node.js dependencies)
+
+For use in browser environments (e.g. web workers in `@dbt-tools/web`):
+
+```typescript
+import {
+  ManifestGraph,
+  ExecutionAnalyzer,
+  RunResultsSearch,
+  AnalysisSnapshot,
+} from "@dbt-tools/core/browser";
 ```
 
+---
+
 ## API
 
 ### ManifestGraph
 
-- `getGraph()`: Get the underlying graphology graph
-- `getSummary()`: Get summary statistics
-- `getUpstream(nodeId)`: Get all upstream dependencies
-- `getDownstream(nodeId)`: Get all downstream dependents
+Builds a directed acyclic graph (DAG) from a parsed dbt manifest using [graphology](https://graphology.github.io/).
+
+| Method                          | Description                                                             |
+| ------------------------------- | ----------------------------------------------------------------------- |
+| `getGraph()`                    | Returns the underlying `graphology` `DirectedGraph`                     |
+| `getSummary()`                  | Returns `{ total_nodes, total_edges, has_cycles, node_counts_by_type }` |
+| `getUpstream(nodeId, depth?)`   | All nodes that `nodeId` depends on (transitive, optional depth limit)   |
+| `getDownstream(nodeId, depth?)` | All nodes that depend on `nodeId` (transitive, optional depth limit)    |
 
 ### ExecutionAnalyzer
 
-- `getSummary()`: Get execution summary with critical path
-- `getNodeExecutions()`: Get execution details for each node
-- `getGanttData()`: Get Gantt chart data for visualization
+Analyzes dbt execution results to compute critical paths and bottlenecks.
+
+| Method                | Description                                                             |
+| --------------------- | ----------------------------------------------------------------------- |
+| `getSummary()`        | Returns execution summary with critical path, total time, slowest nodes |
+| `getNodeExecutions()` | Per-node execution details (status, duration, thread)                   |
+| `getGanttData()`      | Gantt chart data for timeline visualization                             |
+
+### DependencyService
+
+Higher-level dependency queries with build-order support.
+
+| Method                                 | Description                                   |
+| -------------------------------------- | --------------------------------------------- |
+| `getUpstreamBuildOrder(nodeId)`        | Topological ordering of upstream dependencies |
+| `getDependencyTree(nodeId, direction)` | Nested tree structure of dependencies         |
+
+### ArtifactLoader
+
+Loads dbt artifact files from disk.
+
+```typescript
+import { ArtifactLoader } from "@dbt-tools/core";
+
+const loader = new ArtifactLoader({ targetDir: "./target" });
+const manifest = await loader.loadManifest();
+const runResults = await loader.loadRunResults();
+```
+
+### InputValidator
+
+Validates user-supplied strings against common injection patterns (path traversal, control characters, URL encoding tricks).
+
+### OutputFormatter / FieldFilter
+
+Formats analysis output as JSON or human-readable text. `FieldFilter` limits output to a specified set of fields (useful for reducing context window usage in AI agents).
+
+### GraphExport
+
+Exports the dependency graph in multiple formats:
+
+- `json` — nodes and edges as JSON
+- `dot` — Graphviz DOT format
+- `gexf` — GEXF format (for Gephi and other tools)
+
+### ErrorHandler
+
+Standardized error wrapping with typed error codes (`VALIDATION_ERROR`, `FILE_NOT_FOUND`, `PARSE_ERROR`, `UNSUPPORTED_VERSION`, `UNKNOWN_ERROR`).
+
+### SchemaGenerator
+
+Runtime introspection — generates machine-readable schemas for CLI commands. Used by `@dbt-tools/cli schema`.
+
+---
+
+## Performance
+
+`ManifestGraph` uses graphology's adjacency-list representation and is optimized for large manifests with 100k+ nodes.
+
+---
+
+## Development
+
+```bash
+pnpm build
+pnpm test
+```
+
+See [CONTRIBUTING.md](../../../CONTRIBUTING.md) for the full developer guide.
+
+---
+
+## License
+
+Apache License 2.0.

package/dist/analysis/analysis-snapshot.d.ts

@@ -2,6 +2,7 @@ import type { ParsedManifest } from "dbt-artifacts-parser/manifest";
 import type { ParsedRunResults } from "dbt-artifacts-parser/run_results";
 import { type BottleneckResult } from "./run-results-search";
 import { type ExecutionSummary } from "./execution-analyzer";
+import { ManifestGraph } from "./manifest-graph";
 export interface GanttItem {
     unique_id: string;
     name: string;
@@ -106,6 +107,10 @@ export interface DependencyPreview {
     resourceType: string;
     depth: number;
 }
+/**
+ * Direct (1-hop) dependency edges only. `upstream` / `downstream` preview at
+ * most 8 neighbors; counts are total direct neighbors, not transitive closure.
+ */
 export interface ResourceConnectionSummary {
     upstreamCount: number;
     downstreamCount: number;
@@ -141,5 +146,6 @@ export interface AnalysisSnapshotBuildTimings {
 export declare function buildAnalysisSnapshotFromParsedArtifacts(manifestJson: Record<string, unknown>, runResultsJson: Record<string, unknown>, manifest: ParsedManifest, runResults: ParsedRunResults): {
     analysis: AnalysisSnapshot;
     timings: AnalysisSnapshotBuildTimings;
+    graph: ManifestGraph;
 };
 export declare function buildAnalysisSnapshotFromArtifacts(manifestJson: Record<string, unknown>, runResultsJson: Record<string, unknown>): Promise<AnalysisSnapshot>;

package/dist/analysis/analysis-snapshot.js

@@ -183,10 +183,8 @@ function buildResourcesAndDependencyIndex(graph, executionById) {
             description: typeof attributes.description === "string"
                 ? attributes.description
                 : null,
-            compiledCode: typeof attributes.compiled_code === "string"
-                ? attributes.compiled_code
-                : null,
-            rawCode: typeof attributes.raw_code === "string" ? attributes.raw_code : null,
+            compiledCode: null,
+            rawCode: null,
             definition: buildResourceDefinition(String(attributes.resource_type || "unknown"), attributes),
             status: (execution === null || execution === void 0 ? void 0 : execution.status) ? statusLabel(execution.status) : null,
             statusTone: statusTone(execution === null || execution === void 0 ? void 0 : execution.status),
@@ -195,8 +193,8 @@ function buildResourcesAndDependencyIndex(graph, executionById) {
                 : null,
             threadId: typeof (execution === null || execution === void 0 ? void 0 : execution.thread_id) === "string" ? execution.thread_id : null,
         });
-        const upstream = graph.getUpstream(uniqueId);
-        const downstream = graph.getDownstream(uniqueId);
+        const upstream = graph.getUpstream(uniqueId, 1);
+        const downstream = graph.getDownstream(uniqueId, 1);
         dependencyIndex[uniqueId] = {
             upstreamCount: upstream.length,
             downstreamCount: downstream.length,
@@ -602,6 +600,7 @@ function buildAnalysisSnapshotFromParsedArtifacts(manifestJson, runResultsJson,
             graphBuildMs,
             snapshotBuildMs: now() - snapshotStart,
         },
+        graph,
     };
 }
 async function buildAnalysisSnapshotFromArtifacts(manifestJson, runResultsJson) {

package/dist/formatting/field-filter.js

@@ -72,8 +72,7 @@ class FieldFilter {
             if (!Object.prototype.hasOwnProperty.call(current, part)) {
                 return undefined;
             }
-            // nosemgrep: javascript.lang.security.audit.prototype-pollution.prototype-pollution-loop
-            // Part is validated by isUnsafeKey above; hasOwnProperty ensures we don't read proto chain.
+            // nosemgrep: javascript.lang.security.audit.prototype-pollution.prototype-pollution-loop.prototype-pollution-loop — part blocked by isUnsafeKey; hasOwnProperty guards proto chain.
             current = current[part];
         }
         return current;
@@ -96,8 +95,7 @@ class FieldFilter {
                 current[part] === null) {
                 current[part] = Object.create(null);
             }
-            // nosemgrep: javascript.lang.security.audit.prototype-pollution.prototype-pollution-loop
-            // Part is validated by isUnsafeKey check above; assignment creates own property only.
+            // nosemgrep: javascript.lang.security.audit.prototype-pollution.prototype-pollution-loop.prototype-pollution-loop — part blocked by isUnsafeKey; assignment is own property only.
             current = current[part];
         }
         const lastPart = parts[parts.length - 1];

package/dist/io/artifact-loader.js

@@ -52,9 +52,11 @@ function resolveManifestPath(manifestPath, targetDir) {
         if (manifestPath.endsWith(".json")) {
             return (0, input_validator_1.resolveSafePath)(manifestPath);
         }
+        // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal — resolveSafePath validates manifestPath before join.
         return path.join((0, input_validator_1.resolveSafePath)(manifestPath), MANIFEST_FILE);
     }
     const effectiveTargetDir = targetDir || process.env.DBT_TARGET_DIR || DEFAULT_TARGET_DIR;
+    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal — resolveSafePath validates effectiveTargetDir before join.
     return path.join((0, input_validator_1.resolveSafePath)(effectiveTargetDir), MANIFEST_FILE);
 }
 function resolveRunResultsPath(runResultsPath, targetDir) {
@@ -62,9 +64,11 @@ function resolveRunResultsPath(runResultsPath, targetDir) {
         if (runResultsPath.endsWith(".json")) {
             return (0, input_validator_1.resolveSafePath)(runResultsPath);
         }
+        // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal — resolveSafePath validates runResultsPath before join.
         return path.join((0, input_validator_1.resolveSafePath)(runResultsPath), RUN_RESULTS_FILE);
     }
     const effectiveTargetDir = targetDir || process.env.DBT_TARGET_DIR || DEFAULT_TARGET_DIR;
+    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal — resolveSafePath validates effectiveTargetDir before join.
     return path.join((0, input_validator_1.resolveSafePath)(effectiveTargetDir), RUN_RESULTS_FILE);
 }
 function resolveCatalogPath(catalogPath, targetDir) {
@@ -72,9 +76,11 @@ function resolveCatalogPath(catalogPath, targetDir) {
         if (catalogPath.endsWith(".json")) {
             return (0, input_validator_1.resolveSafePath)(catalogPath);
         }
+        // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal — resolveSafePath validates catalogPath before join.
         return path.join((0, input_validator_1.resolveSafePath)(catalogPath), CATALOG_FILE);
     }
     const effectiveTargetDir = targetDir || process.env.DBT_TARGET_DIR || DEFAULT_TARGET_DIR;
+    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal — resolveSafePath validates effectiveTargetDir before join.
     return path.join((0, input_validator_1.resolveSafePath)(effectiveTargetDir), CATALOG_FILE);
 }
 /**

package/dist/validation/input-validator.js

@@ -66,6 +66,7 @@ function validateSafePath(pathInput) {
  */
 function resolveSafePath(pathInput) {
     validateSafePath(pathInput);
+    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal — validateSafePath rejects traversal before resolve.
     return path.resolve(pathInput);
 }
 /**
@@ -74,7 +75,10 @@ function resolveSafePath(pathInput) {
  */
 function assertPathUnderBase(resolvedPath, baseDir) {
     validateSafePath(resolvedPath);
+    validateSafePath(baseDir);
+    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal — validateSafePath on both args before resolve.
     const absPath = path.resolve(resolvedPath);
+    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal — validateSafePath on both args before resolve.
     const baseAbs = path.resolve(baseDir);
     const relative = path.relative(baseAbs, absPath);
     if (relative.startsWith("..") || path.isAbsolute(relative)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dbt-tools/core",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Core library for dbt artifact graph management and analysis",
   "keywords": [
     "dbt",
@@ -29,7 +29,7 @@
     "graphology": "^0.26.0",
     "graphology-dag": "^0.4.1",
     "node-sql-parser": "^5.4.0",
-    "dbt-artifacts-parser": "0.3.2"
+    "dbt-artifacts-parser": "0.3.4"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",