jekyll-relationships 0.1.0.alpha → 0.2.0.alpha

data/lib/jekyll-relationships/trees/graph.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'jekyll-relationships/trees/edge_builder'
+require 'jekyll-relationships/trees/root_distances'
 
 module Jekyll
 module Plugins
@@ -27,12 +28,16 @@ class Graph
 		@child_edge_entries = Hash.new { |hash, key| hash[key] = [] }
 		@ancestor_cache = {}
 		@descendant_cache = {}
+		@root_distance_cache = nil
 		@primary_path_by_collection = {}
+		@scope_fields_by_collection = {}
 		@tree_collections = @configuration.tree_relationships.each_with_object(Set.new) do |definition, collections|
 			collections << definition.from_collection
 			collections << definition.to_collection
 			@primary_path_by_collection[definition.from_collection] ||= definition.primary_path
 			@primary_path_by_collection[definition.to_collection] ||= definition.primary_path
+			@scope_fields_by_collection[definition.from_collection] ||= definition.scope_fields
+			@scope_fields_by_collection[definition.to_collection] ||= definition.scope_fields
 		end
 		@edge_builder = EdgeBuilder.new(
 			graph: self,
@@ -48,6 +53,35 @@ class Graph
 		@edge_builder.build!
 	end
 
+	# Returns one deep copy of the current tree graph state.
+	def deep_dup
+		duplicated_graph = self.class.new(
+			site: @site,
+			configuration: @configuration,
+			registry: @registry,
+			data_path: @data_path,
+			debug_logger: @debug_logger,
+			active_document_ids: @active_document_ids.nil? ? nil : @active_document_ids.keys
+		)
+		duplicated_graph.instance_variable_set(
+			:@parents,
+			duplicate_document_adjacency(@parents)
+		)
+		duplicated_graph.instance_variable_set(
+			:@children,
+			duplicate_document_adjacency(@children)
+		)
+		duplicated_graph.instance_variable_set(
+			:@parent_edge_entries,
+			duplicate_edge_entries(@parent_edge_entries)
+		)
+		duplicated_graph.instance_variable_set(
+			:@child_edge_entries,
+			duplicate_edge_entries(@child_edge_entries)
+		)
+		duplicated_graph
+	end
+
 	# Returns true when one document is part of any tree relationship.
 	def participating?(document)
 		@tree_collections.include?(document.collection.label)
@@ -68,19 +102,21 @@ class Graph
 	end
 
 	# Returns immediate parents as canonical reference hashes.
-	def parents_for(document, primary_path: nil)
+	def parents_for(document, primary_path: nil, scope_fields: nil)
 		return [] unless active_document?(document)
 
 		resolved_primary_path = resolve_primary_path(document: document, primary_path: primary_path)
-		@parents[document].map { |parent| build_reference(parent, primary_path: resolved_primary_path) }
+		resolved_scope_fields = resolve_scope_fields(document: document, scope_fields: scope_fields)
+		@parents[document].map { |parent| build_reference(parent, primary_path: resolved_primary_path, scope_fields: resolved_scope_fields) }
 	end
 
 	# Returns immediate children as canonical reference hashes.
-	def children_for(document, primary_path: nil)
+	def children_for(document, primary_path: nil, scope_fields: nil)
 		return [] unless active_document?(document)
 
 		resolved_primary_path = resolve_primary_path(document: document, primary_path: primary_path)
-		@children[document].map { |child| build_reference(child, primary_path: resolved_primary_path) }
+		resolved_scope_fields = resolve_scope_fields(document: document, scope_fields: scope_fields)
+		@children[document].map { |child| build_reference(child, primary_path: resolved_primary_path, scope_fields: resolved_scope_fields) }
 	end
 
 	# Returns the immediate parent documents in deterministic insertion order.
@@ -112,31 +148,42 @@ class Graph
 	end
 
 	# Returns ancestor references filtered by minimum and maximum distance.
-	def ancestors_for(document, primary_path: nil, min: 0, max: -1)
+	def ancestors_for(document, primary_path: nil, scope_fields: nil, min: 0, max: -1)
 		return [] unless active_document?(document)
 
 		resolved_primary_path = resolve_primary_path(document: document, primary_path: primary_path)
+		resolved_scope_fields = resolve_scope_fields(document: document, scope_fields: scope_fields)
 		filter_distances(
 			distance_map_for(document: document, direction: :up),
 			primary_path: resolved_primary_path,
+			scope_fields: resolved_scope_fields,
 			min: min,
 			max: max
 		)
 	end
 
 	# Returns descendant references filtered by minimum and maximum distance.
-	def descendants_for(document, primary_path: nil, min: 0, max: -1)
+	def descendants_for(document, primary_path: nil, scope_fields: nil, min: 0, max: -1)
 		return [] unless active_document?(document)
 
 		resolved_primary_path = resolve_primary_path(document: document, primary_path: primary_path)
+		resolved_scope_fields = resolve_scope_fields(document: document, scope_fields: scope_fields)
 		filter_distances(
 			distance_map_for(document: document, direction: :down),
 			primary_path: resolved_primary_path,
+			scope_fields: resolved_scope_fields,
 			min: min,
 			max: max
 		)
 	end
 
+	# Returns the shortest number of edges from the document to any root.
+	def root_distance_for(document)
+		return nil unless active_document?(document)
+
+		root_distances_for_graph[document.object_id]
+	end
+
 	# Adds one parent-child edge unless it would break tree guarantees.
 	def add_edge(parent_document:, child_document:, tree_settings:, definition:, source_description:)
 		return unless active_document?(parent_document) && active_document?(child_document)
@@ -220,7 +267,7 @@ class Graph
 			tree_settings: tree_settings,
 			source_description: source_description
 		)
-		clear_distance_cache
+		clear_traversal_cache
 		debug_tree_event(
 			document: child_document,
 			definition: definition,
@@ -240,6 +287,32 @@ class Graph
 		end
 	end
 
+	# Removes one document from the graph along with every adjacent edge.
+	def remove_document!(document)
+		return false unless active_document?(document)
+
+		@active_document_ids.delete(document.object_id) unless @active_document_ids.nil?
+		@children[document].dup.each do |child_document|
+			remove_parent_edge(parent_document: document, child_document: child_document)
+		end
+		@parents[document].dup.each do |parent_document|
+			remove_parent_edge(parent_document: parent_document, child_document: document)
+		end
+		@children.delete(document)
+		@parents.delete(document)
+		@child_edge_entries.delete(document)
+		@parent_edge_entries.delete(document)
+		clear_traversal_cache
+		true
+	end
+
+	# Removes many documents from the graph.
+	def remove_documents!(documents)
+		Array(documents).each do |document|
+			remove_document!(document)
+		end
+	end
+
 	# Returns every document participating in tree relationships.
 	def tree_documents
 		@tree_collections.to_a.flat_map { |collection| documents_for(collection) }.uniq
@@ -252,10 +325,11 @@ class Graph
 		frontmatter = definition.tree_settings.frontmatter
 
 		definition_documents(definition).each do |document|
-			parent_values = parents_for(document, primary_path: definition.primary_path)
-			child_values = children_for(document, primary_path: definition.primary_path)
-			ancestor_values = ancestors_for(document, primary_path: definition.primary_path, min: 0)
-			descendant_values = descendants_for(document, primary_path: definition.primary_path, min: 0)
+			parent_values = parents_for(document, primary_path: definition.primary_path, scope_fields: definition.scope_fields)
+			child_values = children_for(document, primary_path: definition.primary_path, scope_fields: definition.scope_fields)
+			ancestor_values = ancestors_for(document, primary_path: definition.primary_path, scope_fields: definition.scope_fields, min: 0)
+			descendant_values = descendants_for(document, primary_path: definition.primary_path, scope_fields: definition.scope_fields, min: 0)
+			depth_value = root_distance_for(document)
 
 			if frontmatter.output_path
 				@data_path.write(
@@ -268,6 +342,7 @@ class Graph
 						children_value: child_values,
 						ancestors_value: ancestor_values,
 						descendants_value: descendant_values,
+						depth_value: depth_value,
 						max_parents: definition.tree_settings.max_parents,
 						max_children: definition.tree_settings.max_children
 					)
@@ -300,6 +375,7 @@ class Graph
 			)
 			@data_path.write(document.data, frontmatter.ancestors_output_path, ancestor_values)
 			@data_path.write(document.data, frontmatter.descendants_output_path, descendant_values)
+			@data_path.write(document.data, frontmatter.depth_output_path, depth_value)
 			debug_tree_event(
 				document: document,
 				definition: definition,
@@ -312,7 +388,9 @@ class Graph
 					ancestors_path: frontmatter.ancestors_output_path,
 					ancestors_value: ancestor_values,
 					descendants_path: frontmatter.descendants_output_path,
-					descendants_value: descendant_values
+					descendants_value: descendant_values,
+					depth_path: frontmatter.depth_output_path,
+					depth_value: depth_value
 				}
 			)
 		end
@@ -333,11 +411,30 @@ class Graph
 		@primary_path_by_collection[document.collection.label]
 	end
 
+	# Chooses explicit scope fields, or the collection's first tree scope scheme for public helper calls.
+	def resolve_scope_fields(document:, scope_fields:)
+		return scope_fields unless scope_fields.nil?
+
+		@scope_fields_by_collection[document.collection.label] || []
+	end
+
 	# Returns true when one edge already exists.
 	def edge_exists?(parent_document:, child_document:)
 		@parents[child_document].include?(parent_document)
 	end
 
+	# Removes one stored parent-child edge and its metadata in both directions.
+	def remove_parent_edge(parent_document:, child_document:)
+		@parents[child_document].delete(parent_document)
+		@children[parent_document].delete(child_document)
+		@parent_edge_entries[child_document].reject! do |entry|
+			entry.fetch(:document) == parent_document
+		end
+		@child_edge_entries[parent_document].reject! do |entry|
+			entry.fetch(:document) == child_document
+		end
+	end
+
 	# Returns true when one collection has already reached its configured cap.
 	def maximum_reached?(maximum:, items:)
 		maximum != -1 && items.length >= maximum
@@ -384,21 +481,27 @@ class Graph
 		cache[document] = ordered
 	end
 
+	# Computes one shortest-root-distance map for the current graph.
+	def root_distances_for_graph
+		@root_distance_cache ||= Trees::RootDistances.for(graph: self)
+	end
+
 	# Filters one distance map to the requested range and builds references.
-	def filter_distances(distance_map, primary_path:, min:, max:)
+	def filter_distances(distance_map, primary_path:, scope_fields:, min:, max:)
 		distance_map.each_with_object([]) do |(document, distance), references|
 			next if distance < min
 			next if max != -1 && distance > max
 
-			references << build_reference(document, primary_path: primary_path, distance: distance)
+			references << build_reference(document, primary_path: primary_path, scope_fields: scope_fields, distance: distance)
 		end
 	end
 
 	# Builds one canonical reference hash, optionally including distance.
-	def build_reference(document, primary_path:, distance: nil)
+	def build_reference(document, primary_path:, scope_fields:, distance: nil)
 		reference = @configuration.reference_template.build(
 			document: document,
 			key: @registry.key_for(document, primary_path: primary_path),
+			scope: @registry.scope_for(document, scope_fields: scope_fields),
 			include_count: false
 		)
 		reference['distance'] = distance unless distance.nil?
@@ -414,10 +517,11 @@ class Graph
 		end
 	end
 
-	# Clears cached breadth-first-search results after a new edge is added.
-	def clear_distance_cache
+	# Clears cached graph traversals after the tree changes.
+	def clear_traversal_cache
 		@ancestor_cache.clear
 		@descendant_cache.clear
+		@root_distance_cache = nil
 	end
 
 	# Captures the metadata needed to understand one stored edge later on.
@@ -445,6 +549,20 @@ class Graph
 			details: details
 		)
 	end
+
+	# Duplicates one adjacency hash keyed by document.
+	def duplicate_document_adjacency(adjacency)
+		adjacency.each_with_object(Hash.new { |hash, key| hash[key] = [] }) do |(document, neighbours), duplicated_adjacency|
+			duplicated_adjacency[document] = neighbours.dup
+		end
+	end
+
+	# Duplicates one edge-entry hash keyed by document.
+	def duplicate_edge_entries(edge_entries)
+		edge_entries.each_with_object(Hash.new { |hash, key| hash[key] = [] }) do |(document, entries), duplicated_edge_entries|
+			duplicated_edge_entries[document] = entries.map(&:dup)
+		end
+	end
 end
 
 end

data/lib/jekyll-relationships/trees/root_distances.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Jekyll
+module Plugins
+
+module Relationships
+module Trees
+
+# Calculates the shortest distance from every tree node to any current root.
+#
+# The supplied graph-like object must expose `tree_documents`,
+# `parent_documents_for`, and `child_documents_for`. Keeping this traversal in
+# one helper ensures tree write-back and tree pruning interpret depth the same
+# way even though they operate on different graph wrappers.
+class RootDistances
+	# Returns one map of document object id to shortest root distance.
+	def self.for(graph:)
+		root_distances = {}
+		queue = graph.tree_documents.select do |document|
+			graph.parent_documents_for(document).empty?
+		end.sort_by(&:relative_path).map do |root_document|
+			[root_document, 0]
+		end
+
+		until queue.empty?
+			document, distance = queue.shift
+			existing_distance = root_distances[document.object_id]
+			next if !existing_distance.nil? && existing_distance <= distance
+
+			root_distances[document.object_id] = distance
+			graph.child_documents_for(document).each do |child_document|
+				queue << [child_document, distance + 1]
+			end
+		end
+
+		root_distances
+	end
+end
+
+end
+end
+
+end
+end

data/lib/jekyll-relationships/version.rb

@@ -4,7 +4,7 @@ module Jekyll
 module Plugins
 
 module Relationships
-	VERSION = '0.1.0.alpha'
+	VERSION = '0.2.0.alpha'
 end
 
 end

data/lib/jekyll-relationships.rb

@@ -7,6 +7,7 @@ require 'jekyll-relationships/version'
 require 'jekyll-relationships/errors'
 require 'jekyll-relationships/support/string_array'
 require 'jekyll-relationships/support/frontmatter_path'
+require 'jekyll-relationships/support/frontmatter_matcher'
 require 'jekyll-relationships/support/data_path'
 require 'jekyll-relationships/support/hash_deep_merge'
 require 'jekyll-relationships/support/placeholders'