build-graph 2.1.1 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aec6fa0f0986fcf74ca7e3c3debb16f96d7001acbb6f2db9ffb6266973520d39
-  data.tar.gz: 13568cfcc7dc26b1d2a1a4dbbcbe26b3b127756caaff3eb92873ce139d094c53
+  metadata.gz: 732e8eb3e448d4b4d2e29b99cfa776dd3fee02bcac14bf93c87112e907bca776
+  data.tar.gz: 030b9b4aa3f3aadddd4f29569c8ff43151ec10d5a921bc7dd58300cc9808b78b
 SHA512:
-  metadata.gz: 368c3f2a8b146ff538ef5381f1d394965a4d7fde720fcd0757b36c578614da8b4ad81a968611a32ca05372278554a08fd4484ea1dd7ab5f59bbcce9564189bdd
-  data.tar.gz: 92233e7a0535b6b89a0e40716c527357c345bf441387e500d86690d690f0bea21e7b1c86c58e335933efe0535f6599f6e0d0125823136484c60e87c0d908710a
+  metadata.gz: 6cd9d0b4486e3617da1496598baf89a16508fac212ad0c92023948098eab6e1d53ad7fc0c75e9de3f5b0bba5b8f5acebab9cd833d2fb72a6d9220df6babb6183
+  data.tar.gz: b71e886594c0b7aba83db98e4c7da0d5ed97d4f3341006edaa723246a531631457d224ec2a46b5caa25326f938c19861058bb6c28f6b06e1eee207f51a591d7d

data/context/getting-started.md

@@ -0,0 +1,65 @@
+# Getting Started
+
+This guide explains how to use `build-graph` to build a dependency graph for file-based build systems.
+
+## Installation
+
+Add the gem to your project:
+
+~~~ bash
+$ bundle add build-graph
+~~~
+
+Or install it directly:
+
+~~~ bash
+$ gem install build-graph
+~~~
+
+## Usage
+
+A build graph is an abstract set of `[input, process, output]` nodes. A node executes its process within the context of a `Task` which represents a specific set of inputs and outputs and is managed within a `Walker` that walks over graph nodes, regenerating tasks where required. If inputs or outputs change (i.e. become dirty), the old task is nullified.
+
+A `Walker` is used to traverse the build graph once. As it walks over the graph it builds a set of `Edge` relationships between nodes and only traverses relationships which are complete (`Walker#wait_on_paths`). Parent nodes also wait until all their children are complete (`Walker#wait_on_nodes`). It also keeps track of failures (`Walker#failed?`) and fails all dependencies of a node.
+
+A `Task` is instantiated once per node when traversing the graph. The task represents a specific process being applied to the graph, e.g. build, clean, etc. It is responsible for actually performing any real actions and providing the methods to do so. A `Task` contains all details about the specific graph state at that point in time, e.g. `Task#children` and updating the node state in `Task#exit`. Statistics on the build graph are also captured through `Task` and `Walker`, e.g. number of nodes visited, etc.
+
+### Inputs and Outputs
+
+Inputs to a node should be all on-disk state and any additional parameters which cause its behaviour to produce different results.
+
+Outputs from a node should be all files that are generated directly by the processes within the node and sometimes its children.
+
+### Dirty Propagation
+
+A `Node` has a set of `#inputs` and `#outputs` but these are abstract. For example, `#outputs` could be `:inherit` which means that the node symbolically has all the outputs of all its direct children. A `Task`, at the time of execution, captures its inputs and outputs and these may be monitored for changes in real time.
+
+File changes are currently detected using `File::mtime` as this is generally a good trade off between efficiency and accuracy.
+
+When a task is marked as dirty, it also marks all its outputs as being dirty, which in turn could mark other tasks as dirty. This is the mechanism by which dirtiness propagates through the graph. The walker should only have to traverse the graph once to build it completely. If multiple updates are required (i.e. building one part of the graph implicitly dirties another part of the graph), the specification of the graph is incomplete and this may lead to problems within the build graph.
+
+### Example Graph
+
+~~~ ruby
+target("Library/UnitTest", [] => :inherit) do
+	library([UnitTest.cpp] => "UnitTest.a") do
+		compile([UnitTest.cpp] => "UnitTest.o")
+		link([UnitTest.o] => "libUnitTest.a")
+	end
+	
+	copy headers: ["UnitTest.hpp"]
+	
+	# Outputs become libUnitTest.a and UnitTest.hpp
+end
+
+target("Executable/UnitTest", [] => :inherit) do
+	depends("Library/UnitTest")
+	
+	executable("main.cpp" => "UnitTest") do
+		compile("main.cpp" => "main.o")
+		link(["main.o", "libUnitTest.a"] => "UnitTest")
+	end
+	
+	# Outputs become UnitTest
+end
+~~~

data/context/index.yaml

@@ -0,0 +1,18 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: Build::Graph is a framework for build systems, with specific functionality
+  for dealing with file based processes.
+metadata:
+  documentation_uri: https://ioquatix.github.io/build-graph
+  funding_uri: https://github.com/sponsors/ioquatix
+  source_code_uri: https://github.com/ioquatix/build-graph.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to use `build-graph` to build a dependency
+    graph for file-based build systems.
+- path: visualization.md
+  title: Visualization
+  description: This guide explains how to use <code class="language-ruby">Build::Graph::Visualization</code>
+    to generate Mermaid flowchart diagrams from a build graph.

data/context/visualization.md

@@ -0,0 +1,79 @@
+# Visualization
+
+This guide explains how to use {ruby Build::Graph::Visualization} to generate Mermaid flowchart diagrams from a build graph.
+
+## Overview
+
+When debugging or documenting a build graph, it is useful to see the relationships between inputs and outputs visually. `Build::Graph::Visualization` produces a [Mermaid](https://mermaid.js.org) `flowchart LR` diagram from a completed {ruby Build::Graph::Walker}, showing each file as a node and each build step as a directed edge.
+
+## Usage
+
+After running a walker, pass it to {ruby Build::Graph::Visualization#generate}:
+
+~~~ ruby
+require "build/graph/visualization"
+
+walker = Build::Graph::Walker.new do |walker, node|
+  task = Build::Graph::Task.new(walker, node)
+  task.visit do
+    # perform the actual build step here
+  end
+end
+
+walker.update(root_node)
+
+visualization = Build::Graph::Visualization.new
+diagram = visualization.generate(walker)
+
+puts diagram
+~~~
+
+The output is a Mermaid diagram string that can be embedded in documentation, printed to the terminal, or written to a file:
+
+~~~
+flowchart LR
+    _src_main_c[main.c]
+    _obj_main_o[main.o]
+    _src_main_c --> _obj_main_o
+    _obj_main_o[main.o]
+    _bin_program[program]
+    _obj_main_o --> _bin_program
+~~~
+
+## Traversal Without Building
+
+To generate a diagram without actually executing any build steps (e.g. for documentation or dry-run inspection), use {ruby Build::Graph::Task#traverse} instead of `visit` in the walker block:
+
+~~~ ruby
+walker = Build::Graph::Walker.new do |walker, node|
+  task = Build::Graph::Task.new(walker, node)
+  task.traverse
+end
+
+walker.update(root_node)
+
+diagram = Build::Graph::Visualization.new.generate(walker)
+~~~
+
+Unlike `visit`, `traverse` skips input validation and does not require any files to exist on disk. It registers all node outputs with the walker so that dependent nodes can still be resolved correctly.
+
+However, `traverse` only follows **declared** edges — the inputs and outputs as written in the build definition. Some build systems discover additional dependencies at build time (for example, a C compiler producing a `.d` file that lists every header it included). Those discovered edges will not appear in the diagram.
+
+## Complete Graph Visualization
+
+To get a complete and accurate picture of the graph, including any dependencies discovered during execution, use {ruby Build::Graph::Task#visit} with an empty block instead of `traverse`:
+
+~~~ ruby
+walker = Build::Graph::Walker.new do |walker, node|
+  task = Build::Graph::Task.new(walker, node)
+  task.visit do
+    # perform the actual build step here, e.g. compile, link, etc.
+  end
+end
+
+walker.update(root_node)
+
+diagram = Build::Graph::Visualization.new.generate(walker)
+~~~
+
+This executes the build steps and captures the full set of inputs and outputs — including any that are only known after running the task — giving a diagram that accurately reflects what was built and why.

data/lib/build/graph/edge.rb

@@ -1,29 +1,16 @@
-# Copyright, 2014, by Samuel G. D. Williams. <http://www.codeotaku.com>
-# 
-# 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.
+# frozen_string_literal: true
 
-require 'fiber'
+# Released under the MIT License.
+# Copyright, 2014-2026, by Samuel Williams.
+
+require "fiber"
 
 module Build
 	module Graph
 		# Represents a set of inputs to a graph node.
 		class Edge
+			# Create a new edge, optionally pre-populated with a number of pending traversals.
+			# @parameter count [Integer] the initial number of pending traversals.
 			def initialize(count = 0)
 				@fiber = Fiber.current
 				
@@ -48,10 +35,12 @@ module Build
 				succeeded?
 			end
 			
+			# @returns [Boolean] whether any traversing task failed.
 			def failed?
 				@failed.size != 0
 			end
 			
+			# @returns [Boolean] whether all traversing tasks succeeded.
 			def succeeded?
 				@failed.size == 0
 			end

data/lib/build/graph/node.rb

@@ -1,25 +1,10 @@
-# Copyright, 2014, by Samuel G. D. Williams. <http://www.codeotaku.com>
-# 
-# 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.
+# frozen_string_literal: true
 
-require 'build/files/state'
-require 'build/files'
+# Released under the MIT License.
+# Copyright, 2014-2026, by Samuel Williams.
+
+require "build/files/state"
+require "build/files"
 
 module Build
 	module Graph
@@ -44,6 +29,7 @@ module Build
 				@inputs.map{|path| path.modified_time}.max
 			end
 			
+			# @returns [Boolean] whether any input or output file is missing from the filesystem.
 			def missing?
 				@outputs.any?{|path| !path.exist?} || @inputs.any?{|path| !path.exist?}
 			end
@@ -74,6 +60,7 @@ module Build
 				return false
 			end
 			
+			# @returns [Boolean] whether this node is equal to another by comparing inputs and outputs.
 			def == other
 				self.equal?(other) or
 					self.class == other.class and
@@ -81,18 +68,25 @@ module Build
 					@outputs == other.outputs
 			end
 			
+			# @returns [Boolean] whether this node is equal to another, for use in Hash and Set.
 			def eql?(other)
 				self.equal?(other) or self == other
 			end
 			
+			# @returns [Integer] a hash value derived from inputs and outputs.
 			def hash
 				@inputs.hash ^ @outputs.hash
 			end
 			
+			# @returns [String] a human-readable representation of the node.
 			def inspect
 				"#<#{self.class} #{@inputs.inspect} => #{@outputs.inspect}>"
 			end
 			
+			# Create a top-level node that inherits its outputs from its children.
+			# @parameter inputs [Build::Files::List] the input files for this node.
+			# @parameter outputs [Symbol] the output strategy, defaults to `:inherit`.
+			# @returns [Node] the constructed top-level node.
 			def self.top(inputs = Files::Paths::NONE, outputs = :inherit, **options, &block)
 				self.new(inputs, outputs, block, **options)
 			end

data/lib/build/graph/task.rb

@@ -1,41 +1,35 @@
-# Copyright, 2014, by Samuel G. D. Williams. <http://www.codeotaku.com>
-# 
-# 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.
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2015-2026, by Samuel Williams.
 
 module Build
 	module Graph
+		# An error that represents a transient build failure which can be retried.
 		class TransientError < StandardError
 		end
 		
+		# Mixed in to errors raised when child tasks have failed.
 		module ChildrenFailed
+			# @returns [String] a human-readable error message.
 			def self.to_s
 				"Children tasks failed!"
 			end
 		end
 		
+		# Mixed in to errors raised when tasks generating inputs have failed.
 		module InputsFailed
+			# @returns [String] a human-readable error message.
 			def self.to_s
 				"Tasks generating inputs failed!"
 			end
 		end
 		
+		# Represents a single unit of work within a build graph walk.
 		class Task
+			# Create a new task associated with the given walker and node.
+			# @parameter walker [Walker] the walker driving the graph traversal.
+			# @parameter node [Node] the node this task is responsible for updating.
 			def initialize(walker, node)
 				@walker = walker
 				
@@ -72,6 +66,23 @@ module Build
 			# A list of any inputs whose relevant tasks failed:
 			attr :inputs_failed
 			
+			# Traverse the graph without performing any real work. Unlike {visit}, this does not
+			# wait for inputs to be generated, making it suitable for graph analysis tasks such
+			# as visualization where actual files do not need to exist.
+			def traverse
+				update_inputs_and_outputs
+				
+				@walker.enter(self)
+				
+				update_outputs!
+				
+				@state = :complete
+				
+				@walker.exit(self)
+				
+				return self
+			end
+			
 			# Derived task can override this function to provide appropriate behaviour.
 			def visit
 				update_inputs_and_outputs
@@ -124,10 +135,12 @@ module Build
 				return child_task
 			end
 			
+			# @returns [Boolean] whether the task has failed.
 			def failed?
 				@state == :failed
 			end
 			
+			# @returns [Boolean] whether the task has completed successfully.
 			def complete?
 				@state == :complete
 			end
@@ -142,18 +155,22 @@ module Build
 				end
 			end
 			
+			# Resets the node in the walker if inputs or outputs have changed since the last run.
 			def changed!
 				@walker.delete(@node) if (@inputs.update! or @outputs.update!)
 			end
 			
+			# @returns [Array(String)] the list of root directories for all input and output paths.
 			def directories
 				(@inputs.roots + @outputs.roots).collect{|path| path.to_s}
 			end
 			
+			# @returns [String] a short human-readable summary of the task.
 			def to_s
 				"#<#{self.class} #{node_string} #{state_string}>"
 			end
 			
+			# @returns [String] a detailed human-readable representation including object identity.
 			def inspect
 				"\#<#{self.class}:0x#{self.object_id.to_s(16)} #{node_string} #{state_string}>"
 			end
@@ -210,7 +227,7 @@ module Build
 			
 			# Fail the task with the given error. Any task which is waiting on this task will also fail (eventually).
 			def fail!(error)
-				@walker.logger&.error(self) {error}
+				Console.error(self, "Task failed!", exception: error)
 				
 				@error = error
 				@state = :failed

data/lib/build/graph/version.rb

@@ -1,25 +1,12 @@
-# Copyright, 2014, by Samuel G. D. Williams. <http://www.codeotaku.com>
-# 
-# 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.
+# frozen_string_literal: true
 
+# Released under the MIT License.
+# Copyright, 2014-2026, by Samuel Williams.
+
+# @namespace
 module Build
+	# @namespace
 	module Graph
-		VERSION = "2.1.1"
+		VERSION = "2.3.0"
 	end
 end

data/lib/build/graph/visualization.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Build
+	module Graph
+		# Generates Mermaid flowchart visualizations of build graphs.
+		class Visualization
+			# Convert a path to a valid Mermaid node ID.
+			# @parameter path [String] The path to sanitize.
+			# @returns [String] A sanitized identifier safe for use in Mermaid diagrams.
+			def sanitize_id(path)
+				path.to_s.gsub(/[^a-zA-Z0-9_]/, "_")
+			end
+			
+			# Generate a Mermaid flowchart diagram for a completed walker.
+			# @parameter walker [Walker] The completed walker containing tasks.
+			# @returns [String] A Mermaid flowchart diagram in text format.
+			def generate(walker)
+				lines = ["flowchart LR"]
+				
+				walker.tasks.each do |node, task|
+					next unless task.inputs && task.outputs
+					next if task.outputs.equal?(:inherit)
+					
+					input_ids = task.inputs.to_a.map{|path| sanitize_id(path)}
+					output_ids = task.outputs.to_a.map{|path| sanitize_id(path)}
+					
+					task.inputs.each do |path|
+						lines << "    #{sanitize_id(path)}[#{path.basename}]"
+					end
+					
+					task.outputs.each do |path|
+						lines << "    #{sanitize_id(path)}[#{path.basename}]"
+					end
+					
+					label = node.respond_to?(:title) ? node.title.to_s : nil
+					
+					input_ids.each do |input_id|
+						output_ids.each do |output_id|
+							if label && !label.empty?
+								lines << "    #{input_id} -->|#{label}| #{output_id}"
+							else
+								lines << "    #{input_id} --> #{output_id}"
+							end
+						end
+					end
+				end
+				
+				return lines.join("\n")
+			end
+		end
+	end
+end