@ucdjs/pipelines-graph 0.0.1-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-PRESENT Lucas Nørgård
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,27 @@
+# @ucdjs/pipelines-graph
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![codecov][codecov-src]][codecov-href]
+
+> [!IMPORTANT]
+> This is an internal package. It may change without warning and is not subject to semantic versioning. Use at your own risk.
+
+A collection of core pipeline functionalities for the UCD project.
+
+## Installation
+
+```bash
+npm install @ucdjs/pipelines-graph
+```
+
+## 📄 License
+
+Published under [MIT License](./LICENSE).
+
+[npm-version-src]: https://img.shields.io/npm/v/@ucdjs/pipelines-graph?style=flat&colorA=18181B&colorB=4169E1
+[npm-version-href]: https://npmjs.com/package/@ucdjs/pipelines-graph
+[npm-downloads-src]: https://img.shields.io/npm/dm/@ucdjs/pipelines-graph?style=flat&colorA=18181B&colorB=4169E1
+[npm-downloads-href]: https://npmjs.com/package/@ucdjs/pipelines-graph
+[codecov-src]: https://img.shields.io/codecov/c/gh/ucdjs/ucd?style=flat&colorA=18181B&colorB=4169E1
+[codecov-href]: https://codecov.io/gh/ucdjs/ucd

package/dist/index.d.mts

@@ -0,0 +1,50 @@
+import { DAG, FileContext, PipelineDefinition, PipelineGraph, PipelineGraphEdge } from "@ucdjs/pipelines-core";
+
+//#region src/builder.d.ts
+interface GraphBuilderOptions {
+  includeArtifacts?: boolean;
+}
+declare class PipelineGraphBuilder {
+  #private;
+  addSourceNode(version: string): string;
+  addFileNode(file: FileContext): string;
+  addRouteNode(routeId: string, version: string): string;
+  addArtifactNode(artifactId: string, version: string): string;
+  addOutputNode(outputIndex: number, version: string, property?: string): string;
+  addEdge(from: string, to: string, type: PipelineGraphEdge["type"]): void;
+  build(): PipelineGraph;
+  clear(): void;
+}
+declare function createPipelineGraphBuilder(): PipelineGraphBuilder;
+//#endregion
+//#region src/graph-utils.d.ts
+/**
+ * Build a pipeline graph from a pipeline definition and its DAG.
+ * @param {PipelineDefinition} pipeline The pipeline definition to build the graph from.
+ * @param {DAG} dag The DAG representing the dependencies between routes and artifacts in the pipeline.
+ * @returns {PipelineGraph} The constructed pipeline graph.
+ */
+declare function buildRouteGraph(pipeline: PipelineDefinition, dag: DAG): PipelineGraph;
+/**
+ * Convert a pipeline graph into a visual tree representation.
+ * @param {PipelineGraph} graph The pipeline graph to convert.
+ * @returns {string} A visual tree representation of the graph.
+ */
+declare function toVisualTree(graph: PipelineGraph): string;
+/**
+ * Find a node in the graph by its ID.
+ * @param {PipelineGraph} graph The pipeline graph to search within.
+ * @param {string} nodeId The ID of the node to find.
+ * @returns {PipelineGraph["nodes"][number] | undefined} The node with the specified ID, or undefined if not found.
+ */
+declare function find(graph: PipelineGraph, nodeId: string): PipelineGraph["nodes"][number] | undefined;
+/**
+ * Find edges between two nodes in the graph.
+ * @param {PipelineGraph} graph The pipeline graph to search within.
+ * @param {string} from The ID of the source node.
+ * @param {string} to The ID of the target node.
+ * @returns {PipelineGraph["edges"]} An array of edges from the source node to the target node.
+ */
+declare function findEdges(graph: PipelineGraph, from: string, to: string): PipelineGraph["edges"];
+//#endregion
+export { type GraphBuilderOptions, PipelineGraphBuilder, buildRouteGraph, createPipelineGraphBuilder, find, findEdges, toVisualTree };

package/dist/index.mjs

@@ -0,0 +1,169 @@
+//#region src/builder.ts
+var PipelineGraphBuilder = class {
+	#nodes = /* @__PURE__ */ new Map();
+	#edges = [];
+	#edgeIndex = /* @__PURE__ */ new Set();
+	addSourceNode(version) {
+		const id = `source:${version}`;
+		if (!this.#nodes.has(id)) this.#nodes.set(id, {
+			id,
+			type: "source",
+			version
+		});
+		return id;
+	}
+	addFileNode(file) {
+		const id = `file:${file.version}:${file.path}`;
+		if (!this.#nodes.has(id)) this.#nodes.set(id, {
+			id,
+			type: "file",
+			file
+		});
+		return id;
+	}
+	addRouteNode(routeId, version) {
+		const id = `route:${version}:${routeId}`;
+		if (!this.#nodes.has(id)) this.#nodes.set(id, {
+			id,
+			type: "route",
+			routeId
+		});
+		return id;
+	}
+	addArtifactNode(artifactId, version) {
+		const id = `artifact:${version}:${artifactId}`;
+		if (!this.#nodes.has(id)) this.#nodes.set(id, {
+			id,
+			type: "artifact",
+			artifactId
+		});
+		return id;
+	}
+	addOutputNode(outputIndex, version, property) {
+		const id = `output:${version}:${outputIndex}`;
+		if (!this.#nodes.has(id)) this.#nodes.set(id, {
+			id,
+			type: "output",
+			outputIndex,
+			property
+		});
+		return id;
+	}
+	addEdge(from, to, type) {
+		const key = `${from}|${to}|${type}`;
+		if (this.#edgeIndex.has(key)) return;
+		this.#edgeIndex.add(key);
+		this.#edges.push({
+			from,
+			to,
+			type
+		});
+	}
+	build() {
+		return {
+			nodes: Array.from(this.#nodes.values()),
+			edges: [...this.#edges]
+		};
+	}
+	clear() {
+		this.#nodes.clear();
+		this.#edges.length = 0;
+		this.#edgeIndex.clear();
+	}
+};
+function createPipelineGraphBuilder() {
+	return new PipelineGraphBuilder();
+}
+
+//#endregion
+//#region src/graph-utils.ts
+/**
+* Build a pipeline graph from a pipeline definition and its DAG.
+* @param {PipelineDefinition} pipeline The pipeline definition to build the graph from.
+* @param {DAG} dag The DAG representing the dependencies between routes and artifacts in the pipeline.
+* @returns {PipelineGraph} The constructed pipeline graph.
+*/
+function buildRouteGraph(pipeline, dag) {
+	const builder = new PipelineGraphBuilder();
+	for (const route of pipeline.routes) {
+		const routeNode = dag.nodes.get(route.id);
+		if (!routeNode) continue;
+		const currentRouteId = builder.addRouteNode(route.id, "static");
+		for (const depId of routeNode.dependencies) {
+			const depNodeId = builder.addRouteNode(depId, "static");
+			builder.addEdge(depNodeId, currentRouteId, "provides");
+		}
+		for (const artifactId of routeNode.emittedArtifacts) {
+			const artifactNodeId = builder.addArtifactNode(artifactId, "static");
+			builder.addEdge(currentRouteId, artifactNodeId, "resolved");
+		}
+	}
+	return builder.build();
+}
+const END_LINE = "└─ ";
+const MID_LINE = "├─ ";
+const VERTICAL_LINE = "│  ";
+const EMPTY_SPACE = "   ";
+/**
+* Convert a pipeline graph into a visual tree representation.
+* @param {PipelineGraph} graph The pipeline graph to convert.
+* @returns {string} A visual tree representation of the graph.
+*/
+function toVisualTree(graph) {
+	const adjacencyList = /* @__PURE__ */ new Map();
+	const incomingCount = /* @__PURE__ */ new Map();
+	graph.nodes.forEach((node) => {
+		incomingCount.set(node.id, 0);
+	});
+	for (const edge of graph.edges) {
+		if (!adjacencyList.has(edge.from)) adjacencyList.set(edge.from, []);
+		adjacencyList.get(edge.from).push(edge.to);
+		incomingCount.set(edge.to, (incomingCount.get(edge.to) ?? 0) + 1);
+		if (!incomingCount.has(edge.from)) incomingCount.set(edge.from, 0);
+	}
+	const nodeIds = graph.nodes.map((node) => node.id);
+	const rootIds = nodeIds.filter((id) => (incomingCount.get(id) ?? 0) === 0);
+	const orderedRoots = rootIds.length > 0 ? rootIds : nodeIds;
+	const lines = [];
+	const visited = /* @__PURE__ */ new Set();
+	function buildTree(nodeId, prefix, isLast) {
+		if (visited.has(nodeId)) return;
+		visited.add(nodeId);
+		lines.push(`${prefix}${isLast ? END_LINE : MID_LINE}${nodeId}`);
+		const children = adjacencyList.get(nodeId) ?? [];
+		const nextPrefix = prefix + (isLast ? EMPTY_SPACE : VERTICAL_LINE);
+		children.forEach((childId, index) => {
+			buildTree(childId, nextPrefix, index === children.length - 1);
+		});
+	}
+	orderedRoots.forEach((rootId, index) => {
+		buildTree(rootId, "", index === orderedRoots.length - 1);
+	});
+	const remaining = nodeIds.filter((id) => !visited.has(id));
+	remaining.forEach((nodeId, index) => {
+		buildTree(nodeId, "", index === remaining.length - 1);
+	});
+	return lines.join("\n");
+}
+/**
+* Find a node in the graph by its ID.
+* @param {PipelineGraph} graph The pipeline graph to search within.
+* @param {string} nodeId The ID of the node to find.
+* @returns {PipelineGraph["nodes"][number] | undefined} The node with the specified ID, or undefined if not found.
+*/
+function find(graph, nodeId) {
+	return graph.nodes.find((node) => node.id === nodeId);
+}
+/**
+* Find edges between two nodes in the graph.
+* @param {PipelineGraph} graph The pipeline graph to search within.
+* @param {string} from The ID of the source node.
+* @param {string} to The ID of the target node.
+* @returns {PipelineGraph["edges"]} An array of edges from the source node to the target node.
+*/
+function findEdges(graph, from, to) {
+	return graph.edges.filter((edge) => edge.from === from && edge.to === to);
+}
+
+//#endregion
+export { PipelineGraphBuilder, buildRouteGraph, createPipelineGraphBuilder, find, findEdges, toVisualTree };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@ucdjs/pipelines-graph",
+  "version": "0.0.1-beta.1",
+  "type": "module",
+  "author": {
+    "name": "Lucas Nørgård",
+    "email": "lucasnrgaard@gmail.com",
+    "url": "https://luxass.dev"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/ucdjs/ucd",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ucdjs/ucd.git",
+    "directory": "packages/pipelines/pipeline-graph"
+  },
+  "bugs": {
+    "url": "https://github.com/ucdjs/ucd/issues"
+  },
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.18"
+  },
+  "dependencies": {
+    "@ucdjs/pipelines-core": "0.0.1-beta.1"
+  },
+  "devDependencies": {
+    "@luxass/eslint-config": "7.2.0",
+    "eslint": "10.0.0",
+    "publint": "0.3.17",
+    "tsdown": "0.20.3",
+    "typescript": "5.9.3",
+    "@ucdjs-tooling/tsdown-config": "1.0.0",
+    "@ucdjs-tooling/tsconfig": "1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown --tsconfig=./tsconfig.build.json",
+    "dev": "tsdown --watch",
+    "clean": "git clean -xdf dist node_modules",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit -p tsconfig.build.json"
+  }
+}