jekyll-relationships 0.1.0.alpha → 0.2.0.alpha

data/lib/jekyll-relationships/pruning/tree_provenance.rb

@@ -10,7 +10,7 @@ module Pruning
 #
 # Tree orphan repair needs stable provenance even after many prune rounds. This
 # helper snapshots the first fully built tree graph before any pruning so later
-# orphan handling can reattach surviving grandparents in deterministic order.
+# orphan handling can reattach nearest surviving ancestors in deterministic order.
 class TreeProvenance
 	# Builds one immutable provenance index from one tree graph.
 	def initialize(tree_graph:)

data/lib/jekyll-relationships/references/accumulator.rb

@@ -24,37 +24,60 @@ class Accumulator
 	end
 
 	# Adds one resolved relationship entry.
-	def add(document:, key:, metadata: nil, count: 1)
-		add_result(document: document, key: key, metadata: metadata, count: count) != :ignored
+	def add(document:, key:, scope: nil, metadata: nil, count: 1)
+		add_result(document: document, key: key, scope: scope, metadata: metadata, count: count) != :ignored
 	end
 
 	# Adds one resolved relationship entry and returns how it changed the set.
-	def add_result(document:, key:, metadata: nil, count: 1)
+	def add_result(document:, key:, scope: nil, metadata: nil, count: 1)
+		add_detailed_result(
+			document: document,
+			key: key,
+			scope: scope,
+			metadata: metadata,
+			count: count
+		).fetch(:action)
+	end
+
+	# Adds one resolved relationship entry and returns the stored entry as well.
+	def add_detailed_result(document:, key:, scope: nil, metadata: nil, count: 1)
 		if @multiple_settings.keep?
-			append_entry(document: document, key: key, metadata: metadata, count: 1)
-			return :added
+			return {
+				action: :added,
+				entry: append_entry(document: document, key: key, scope: scope, metadata: metadata, count: 1)
+			}
 		end
 
 		existing_entry = @entries_by_document_id[document.object_id]
 		if existing_entry
-			return :ignored if @multiple_settings.drop?
+			return {
+				action: :ignored,
+				entry: existing_entry
+			} if @multiple_settings.drop?
 
 			existing_entry[:count] += normalise_count(count)
 			existing_entry[:metadata] = merge_metadata_under(
 				existing_metadata: existing_entry[:metadata],
 				incoming_metadata: metadata
 			)
-			return :merged
+			return {
+				action: :merged,
+				entry: existing_entry
+			}
 		end
 
 		entry = append_entry(
 			document: document,
 			key: key,
+			scope: scope,
 			metadata: metadata,
 			count: counted_mode? ? normalise_count(count) : 1
 		)
 		@entries_by_document_id[document.object_id] = entry
-		:added
+		{
+			action: :added,
+			entry: entry
+		}
 	end
 
 	# Removes every stored occurrence of one target document.
@@ -99,6 +122,35 @@ class Accumulator
 		end
 	end
 
+	# Repositions newly reinserted entries by proportional target slot.
+	def reposition_entries!(reinsertions:, base_count:)
+		return if reinsertions.empty?
+
+		reinsertions_by_entry_id = reinsertions.each_with_object({}) do |reinsertion, indexed_reinsertions|
+			indexed_reinsertions[reinsertion.fetch(:entry).object_id] = reinsertion
+		end
+		base_entries = @entries.reject do |entry|
+			reinsertions_by_entry_id.key?(entry.object_id)
+		end
+		slots = Hash.new { |hash, key| hash[key] = [] }
+		reinsertions.sort_by do |reinsertion|
+			[
+				reinsertion.fetch(:position_ratio).nil? ? Float::INFINITY : reinsertion.fetch(:position_ratio),
+				reinsertion.fetch(:order)
+			]
+		end.each do |reinsertion|
+			slots[insertion_index(position_ratio: reinsertion.fetch(:position_ratio), base_count: base_count)] << reinsertion.fetch(:entry)
+		end
+
+		rebuilt_entries = []
+		0.upto(base_entries.length) do |index|
+			rebuilt_entries.concat(slots[index]) if slots.key?(index)
+			rebuilt_entries << base_entries[index] if index < base_entries.length
+		end
+		@entries = rebuilt_entries
+		reindex_entries!
+	end
+
 	private
 
 	# Returns true when the current mode is count.
@@ -107,10 +159,11 @@ class Accumulator
 	end
 
 	# Appends one entry while recording its first-seen order.
-	def append_entry(document:, key:, metadata:, count:)
+	def append_entry(document:, key:, scope:, metadata:, count:)
 		entry = {
 			document: document,
 			key: key,
+			scope: duplicate_scope(scope),
 			metadata: normalise_metadata(metadata),
 			count: count,
 			first_seen_index: @next_position
@@ -134,6 +187,7 @@ class Accumulator
 		{
 			document: entry.fetch(:document),
 			key: entry.fetch(:key),
+			scope: duplicate_scope(entry.fetch(:scope)),
 			metadata: normalise_metadata(entry.fetch(:metadata)),
 			count: entry.fetch(:count),
 			first_seen_index: entry.fetch(:first_seen_index)
@@ -145,11 +199,19 @@ class Accumulator
 		@reference_template.build(
 			document: entry.fetch(:document),
 			key: entry.fetch(:key),
+			scope: entry.fetch(:scope),
 			metadata: entry.fetch(:metadata),
 			count: entry.fetch(:count)
 		)
 	end
 
+	# Returns a shallow copy of one complete scope hash while preserving scalar values exactly.
+	def duplicate_scope(scope)
+		return nil if scope.nil?
+
+		normalise_metadata(scope)
+	end
+
 	# Merges later metadata under the first-seen metadata.
 	def merge_metadata_under(existing_metadata:, incoming_metadata:)
 		Jekyll::Plugins::Relationships::Support.hash_deep_merge(
@@ -176,6 +238,22 @@ class Accumulator
 
 		integer_count
 	end
+
+	# Converts one persisted proportional hint into an insertion slot.
+	def insertion_index(position_ratio:, base_count:)
+		return base_count if position_ratio.nil?
+		return 0 if base_count <= 0
+
+		[[0, (position_ratio * base_count).round].max, base_count].min
+	end
+
+	# Rewrites first-seen indexes after persisted reinsertion changes the order.
+	def reindex_entries!
+		@entries.each_with_index do |entry, index|
+			entry[:first_seen_index] = index
+		end
+		@next_position = @entries.length
+	end
 end
 
 end

data/lib/jekyll-relationships/references/template.rb

@@ -9,7 +9,7 @@ module References
 # Parses loose reference values and builds canonical relationship hashes.
 #
 # The template is configured from `relationships.references` and controls which
-# property names hold the key, collection, page, and optional count values in
+# property names hold the key, collection, scope, page, and optional count values in
 # output hashes.
 class Template
 
@@ -18,12 +18,13 @@ class Template
 	# The `metadata` hash contains any non-reserved properties found on an
 	# existing reference hash.
 	class ParsedReference
-		attr_reader :key, :collection, :page, :count, :metadata, :original_value
+		attr_reader :key, :collection, :scope, :page, :count, :metadata, :original_value
 
 		# Captures the parsed reference fields in one immutable object.
-		def initialize(key:, collection:, page:, count:, metadata:, original_value:)
+		def initialize(key:, collection:, scope: nil, page:, count:, metadata:, original_value:)
 			@key = key
 			@collection = collection
+			@scope = scope
 			@page = page
 			@count = count
 			@metadata = metadata
@@ -36,7 +37,7 @@ class Template
 		end
 	end
 
-	attr_reader :key_property, :collection_property, :page_property, :count_property
+	attr_reader :key_property, :collection_property, :scope_property, :page_property, :count_property
 
 	# Builds the reference template from config and duplicate-handling settings.
 	def initialize(config:, count_enabled:)
@@ -44,6 +45,7 @@ class Template
 		@count_enabled = !!count_enabled
 		@key_property = nil
 		@collection_property = nil
+		@scope_property = nil
 		@page_property = nil
 		@count_property = nil
 
@@ -51,7 +53,7 @@ class Template
 	end
 
 	# Parses one raw reference value from frontmatter or resolver input.
-	def parse(value)
+	def parse(value, context: nil)
 		case value
 		when String
 			key = value.to_s.strip
@@ -60,32 +62,35 @@ class Template
 			ParsedReference.new(
 				key: key,
 				collection: nil,
+				scope: nil,
 				page: nil,
 				count: 1,
 				metadata: {},
 				original_value: value
 			)
 		when Hash
-			parse_hash_reference(value)
+			parse_hash_reference(value, context: context)
 		when Jekyll::Document
 			ParsedReference.new(
 				key: nil,
 				collection: nil,
+				scope: nil,
 				page: value,
 				count: 1,
 				metadata: {},
 				original_value: value
 			)
 		else
-			raise ConfigurationError, "Unsupported reference value `#{value.inspect}`."
+			raise ConfigurationError, "#{context_prefix(context)}unsupported reference value `#{value.inspect}`."
 		end
 	end
 
 	# Builds one output reference hash for a resolved document.
-	def build(document:, key:, metadata: nil, count: 1, include_count: @count_enabled)
+	def build(document:, key:, scope: nil, metadata: nil, count: 1, include_count: @count_enabled)
 		hash = {}
 		hash[@key_property] = key
 		hash[@collection_property] = document.collection.label if @collection_property
+		hash[@scope_property] = stringify_hash(scope) if @scope_property && !scope.nil?
 		hash[@page_property] = document if @page_property
 		hash[@count_property] = normalise_count(count) if include_count && @count_property
 
@@ -98,7 +103,7 @@ class Template
 
 	# Returns the configured property names that are reserved for the engine.
 	def reserved_properties
-		[@key_property, @collection_property, @page_property, @count_property].compact
+		[@key_property, @collection_property, @scope_property, @page_property, @count_property].compact
 	end
 
 	# Returns the input properties that should never survive into free-form metadata.
@@ -121,6 +126,9 @@ class Template
 			when Jekyll::Plugins::Relationships::Support::Placeholders::COLLECTION
 				raise ConfigurationError, 'Reference config can only define one <collection> property.' if @collection_property
 				@collection_property = property
+			when Jekyll::Plugins::Relationships::Support::Placeholders::SCOPE
+				raise ConfigurationError, 'Reference config can only define one <scope> property.' if @scope_property
+				@scope_property = property
 			when Jekyll::Plugins::Relationships::Support::Placeholders::PAGE
 				raise ConfigurationError, 'Reference config can only define one <page> property.' if @page_property
 				@page_property = property
@@ -139,18 +147,20 @@ class Template
 	end
 
 	# Parses one hash reference according to the configured property names.
-	def parse_hash_reference(hash)
+	def parse_hash_reference(hash, context: nil)
 		key = fetch_hash_value(hash, @key_property)
 		collection = @collection_property ? fetch_hash_value(hash, @collection_property) : nil
+		scope = parse_scope(hash, context: context)
 		page = @page_property ? fetch_hash_value(hash, @page_property) : nil
 
 		if key.nil? && !page.is_a?(Jekyll::Document)
-			raise ResolutionError, "Reference hash `#{hash.inspect}` does not include the configured key property `#{@key_property}`."
+			raise ResolutionError, "#{context_prefix(context)}reference hash `#{hash.inspect}` does not include the configured key property `#{@key_property}`."
 		end
 
 		ParsedReference.new(
 			key: key,
 			collection: collection,
+			scope: scope,
 			page: page,
 			count: parsed_count(hash),
 			metadata: filter_metadata(hash),
@@ -158,6 +168,19 @@ class Template
 		)
 	end
 
+	# Parses the reserved scope property without interpreting literal dotted field names as nested paths.
+	def parse_scope(hash, context: nil)
+		return nil unless @scope_property
+		return nil unless hash_property?(hash, @scope_property)
+
+		raw_scope = fetch_hash_value(hash, @scope_property)
+		unless raw_scope.is_a?(Hash)
+			raise ResolutionError, "#{context_prefix(context)}reference scope property `#{@scope_property}` must be a hash, but was `#{raw_scope.inspect}`."
+		end
+
+		stringify_hash(raw_scope)
+	end
+
 	# Returns the parsed count value for one reference hash.
 	def parsed_count(hash)
 		return 1 unless @count_enabled
@@ -191,6 +214,18 @@ class Template
 		Jekyll::Plugins::Relationships::Support::FrontmatterPath.read_hash(hash, property)
 	end
 
+	# Returns true when a string- or symbol-keyed hash contains one literal property.
+	def hash_property?(hash, property)
+		hash.key?(property) || hash.key?(property.to_s) || hash.key?(property.to_s.to_sym)
+	end
+
+	# Adds relationship and document details supplied by the caller to parsing diagnostics.
+	def context_prefix(context)
+		return '' if context.nil? || context.to_s.empty?
+
+		"#{context}: "
+	end
+
 	# Converts one hash to a shallow string-keyed copy.
 	def stringify_hash(hash)
 		return {} unless hash.is_a?(Hash)

data/lib/jekyll-relationships/resolvers/base.rb

@@ -6,6 +6,17 @@ module Plugins
 module Relationships
 module Resolvers
 
+# Declares or reads the global default persistence mode for resolver link calls.
+#
+# Resolver classes can override this locally with their own `persist true/false`
+# declaration. When left unset on the class, `link(...)` falls back to this
+# module-wide default.
+def self.persist(value = :__read__)
+	return Base.global_persist_default if value == :__read__
+
+	Base.global_persist_default = value
+end
+
 # Base class for custom relationship resolvers.
 #
 # Subclass this in `_plugins`, declare `from` and `to`, then implement
@@ -14,6 +25,7 @@ module Resolvers
 class Base
 
 	@registered_subclasses = []
+	@global_persist_default = false
 
 	class << self
 		attr_reader :from_definition, :to_definition
@@ -42,6 +54,35 @@ class Base
 			@to_definition
 		end
 
+		# Declares or reads the default persistence mode for this resolver class.
+		def persist(value = :__read__)
+			unless value == :__read__
+				@persist_default = normalise_persist_default(
+					value,
+					context: "#{name || self}.persist"
+				)
+			end
+			return @persist_default unless @persist_default.nil?
+			return superclass.persist if self != Base && superclass.respond_to?(:persist)
+
+			global_persist_default
+		end
+
+		# Returns the module-wide fallback persistence mode.
+		def global_persist_default
+			return false unless instance_variable_defined?(:@global_persist_default)
+
+			@global_persist_default
+		end
+
+		# Sets the module-wide fallback persistence mode.
+		def global_persist_default=(value)
+			@global_persist_default = normalise_persist_default(
+				value,
+				context: 'Resolvers.persist'
+			)
+		end
+
 		# Returns every resolver subclass whose `from` and `to` selectors are complete.
 		def registered_subclasses
 			@registered_subclasses ||= []
@@ -60,6 +101,15 @@ class Base
 		def remove_registered_subclass(subclass:)
 			registered_subclasses.delete(subclass)
 		end
+
+		private
+
+		# Normalises one resolver persistence default to a strict boolean.
+		def normalise_persist_default(value, context:)
+			return value if value == true || value == false
+
+			raise ConfigurationError, "`#{context}` must be true or false."
+		end
 	end
 
 	# Builds one resolver instance for one resolving relationship state.
@@ -159,11 +209,15 @@ class Base
 	end
 
 	# Adds one relationship from the current document to the target collection.
-	def link(target_reference, reference: nil)
+	#
+	# When `persist` is true, the link may be restored in later rounds if the
+	# resolver does not recreate it and both linked documents still survive.
+	def link(target_reference, reference: nil, persist: nil)
 		@state.link(
 			target_reference,
 			metadata: reference,
-			origin: "resolver #{self.class.name || self.class}"
+			origin: "resolver #{self.class.name || self.class}",
+			persist: persist.nil? ? self.class.persist : persist
 		)
 	end
 
@@ -184,6 +238,9 @@ class Base
 		@engine.resolve_reference_document(
 			reference,
 			primary_path: @state.definition.primary_path,
+			scope_fields: @state.definition.scope_fields,
+			referring_document: @document,
+			relationship: "#{@state.definition.from_collection} -> #{@state.definition.to_collection}",
 			collection_hint: from_collection
 		)
 	end

data/lib/jekyll-relationships/support/frontmatter_matcher.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Jekyll
+module Plugins
+module Relationships
+
+module Support
+
+# Matches exact values at dot-separated paths in document frontmatter.
+#
+# Paths traverse hashes only so arrays and hashes remain matchable terminal
+# values. Lookup distinguishes a missing path from a present nil value and
+# treats string and symbol hash keys as equivalent.
+class FrontmatterMatcher
+	# Builds one matcher from normalised path and expected-value pairs.
+	def initialize(expected_values:)
+		@expected_values = expected_values
+	end
+
+	# Returns true when every configured path is present and matches exactly.
+	def matches?(data)
+		@expected_values.all? do |path, expected_value|
+			match = value_at(data: data, path: path)
+			match.fetch(:present) && type_sensitive_equal?(match.fetch(:value), expected_value)
+		end
+	end
+
+	private
+
+	# Reads one hash-only path without collapsing a present nil into missing.
+	def value_at(data:, path:)
+		current_value = data
+		FrontmatterPath.split_path(path).each do |segment|
+			return missing_value unless current_value.is_a?(Hash)
+
+			resolved_key = resolve_hash_key(hash: current_value, segment: segment)
+			return missing_value if resolved_key.nil?
+
+			current_value = current_value[resolved_key]
+		end
+
+		{
+			present: true,
+			value: current_value
+		}
+	end
+
+	# Resolves string and symbol forms of one path segment.
+	def resolve_hash_key(hash:, segment:)
+		return segment if hash.key?(segment)
+
+		symbol_segment = segment.to_sym
+		return symbol_segment if hash.key?(symbol_segment)
+
+		nil
+	end
+
+	# Returns one fresh missing lookup result.
+	def missing_value
+		{
+			present: false,
+			value: nil
+		}
+	end
+
+	# Requires both the Ruby type and value to match.
+	def type_sensitive_equal?(actual_value, expected_value)
+		actual_value.class == expected_value.class && actual_value == expected_value
+	end
+end
+
+end
+
+end
+end
+end

data/lib/jekyll-relationships/support/placeholders.rb

@@ -10,6 +10,7 @@ module Support
 	module Placeholders
 		KEY = '<key>'.freeze
 		COLLECTION = '<collection>'.freeze
+		SCOPE = '<scope>'.freeze
 		PAGE = '<page>'.freeze
 		COUNT = '<count>'.freeze
 	end

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

@@ -53,8 +53,8 @@ class EdgeBuilder
 
 		@graph.documents_for(child_collection).each do |child_document|
 			path_configuration.parent_input_paths(max_parents: definition.tree_settings.max_parents).each do |path|
-				parse_references(@data_path.read(child_document.data, path)).each do |reference|
-					parent_document = resolve_reference(reference: reference, primary_path: definition.primary_path)
+				parse_references(@data_path.read(child_document.data, path), definition: definition, document: child_document).each do |reference|
+					parent_document = resolve_reference(reference: reference, definition: definition, referring_document: child_document)
 					next unless parent_document
 					next unless parent_document.collection.label == parent_collection
 
@@ -88,8 +88,8 @@ class EdgeBuilder
 
 		@graph.documents_for(parent_collection).each do |parent_document|
 			path_configuration.child_input_paths(max_children: definition.tree_settings.max_children).each do |path|
-				parse_references(@data_path.read(parent_document.data, path)).each do |reference|
-					child_document = resolve_reference(reference: reference, primary_path: definition.primary_path)
+				parse_references(@data_path.read(parent_document.data, path), definition: definition, document: parent_document).each do |reference|
+					child_document = resolve_reference(reference: reference, definition: definition, referring_document: parent_document)
 					next unless child_document
 					next unless child_document.collection.label == child_collection
 
@@ -132,7 +132,7 @@ class EdgeBuilder
 					parents = fetch_nested(url_index, parent_collection, parent_parts)
 					next unless parents
 
-					parents.each do |parent_document|
+					parents.select { |parent_document| same_scope?(first_document: child_document, second_document: parent_document, definition: definition) }.each do |parent_document|
 						@graph.add_edge(
 							parent_document: parent_document,
 							child_document: child_document,
@@ -162,24 +162,56 @@ class EdgeBuilder
 	end
 
 	# Parses one tree frontmatter value into parsed references.
-	def parse_references(value)
+	def parse_references(value, definition:, document:)
 		@string_array.interpret(value, split: -1, flatten: true).map do |entry|
-			@configuration.reference_template.parse(entry)
+			@configuration.reference_template.parse(
+				entry,
+				context: "Relationship `#{definition.from_collection} -> #{definition.to_collection}` reference on document `#{document.relative_path}`"
+			)
 		end.compact
 	end
 
 	# Resolves one parsed reference to a real document.
-	def resolve_reference(reference:, primary_path:)
-		return reference.page if reference.document?
+	def resolve_reference(reference:, definition:, referring_document:)
+		relationship = "#{definition.from_collection} -> #{definition.to_collection}"
+		effective_scope = @registry.effective_scope_for(
+			reference_scope: reference.scope,
+			referring_document: referring_document,
+			scope_fields: definition.scope_fields,
+			relationship: relationship
+		)
+		if reference.document?
+			@registry.validate_scope_match!(
+				document: reference.page,
+				scope: effective_scope,
+				scope_fields: definition.scope_fields,
+				relationship: relationship,
+				referring_document: referring_document
+			)
+			return reference.page
+		end
 
 		collection = reference.collection.to_s unless reference.collection.nil?
 		@registry.lookup(
 			key: reference.key,
-			primary_path: primary_path,
-			collection: collection
+			primary_path: definition.primary_path,
+			collection: collection,
+			scope_fields: definition.scope_fields,
+			scope: effective_scope,
+			relationship: relationship,
+			referring_document: referring_document
 		)
 	end
 
+	# Returns true when two URL-selected documents share the definition's complete scope.
+	def same_scope?(first_document:, second_document:, definition:)
+		return true if definition.scope_fields.empty?
+
+		relationship = "#{definition.from_collection} -> #{definition.to_collection}"
+		@registry.scope_for(first_document, scope_fields: definition.scope_fields, relationship: relationship) ==
+			@registry.scope_for(second_document, scope_fields: definition.scope_fields, relationship: relationship)
+	end
+
 	# Reads one nested hash value without creating a default entry.
 	def fetch_nested(hash, first_key, second_key)
 		first_hash = hash[first_key]