jekyll-relationships 0.1.1.alpha → 0.2.0.alpha

data/lib/jekyll-relationships/engine/normal_seed.rb

@@ -79,7 +79,7 @@ class Engine
 		# Reads and stores one concrete direct relationship definition from frontmatter.
 		def seed_definition_from_frontmatter(accumulators:, document:, definition:)
 			definition.foreign_paths.each do |path|
-				raw_state = raw_path_state(document, path)
+				raw_state = raw_path_state(document, path, definition)
 				debug_relationship_event(
 					document: document,
 					definition: definition,
@@ -94,7 +94,9 @@ class Engine
 
 				resolved_entries = raw_state.resolved_entries_for(
 					primary_path: definition.primary_path,
+					scope_fields: definition.scope_fields,
 					registry: @registry,
+					relationship: "#{definition.from_collection} -> #{definition.to_collection}",
 					active_document_checker: proc { |resolved_document| active_document?(resolved_document) }
 				)
 				debug_relationship_event(
@@ -144,6 +146,7 @@ class Engine
 			).add(
 				document: entry.fetch(:document),
 				key: entry.fetch(:key),
+				scope: entry.fetch(:scope),
 				metadata: entry.fetch(:metadata),
 				count: entry.fetch(:count)
 			)
@@ -157,6 +160,7 @@ class Engine
 			).add(
 				document: document,
 				key: @registry.key_for(document, primary_path: definition.primary_path),
+				scope: @registry.scope_for(document, scope_fields: definition.scope_fields, relationship: "#{definition.from_collection} -> #{definition.to_collection}"),
 				metadata: entry.fetch(:metadata),
 				count: entry.fetch(:count)
 			)
@@ -183,13 +187,14 @@ class Engine
 		end
 
 		# Returns the cached raw-path parser for one document/path pair.
-		def raw_path_state(document, path)
-			@raw_path_states[[document.object_id, path]] ||= RawPathState.new(
+		def raw_path_state(document, path, definition)
+			@raw_path_states[[document.object_id, path, definition.object_id]] ||= RawPathState.new(
 				document: document,
 				path: path,
 				data_path: @data_path,
 				string_array: @string_array,
-				reference_template: @configuration.reference_template
+				reference_template: @configuration.reference_template,
+				reference_context: "Relationship `#{definition.from_collection} -> #{definition.to_collection}` reference on document `#{document.relative_path}`"
 			)
 		end
 

data/lib/jekyll-relationships/engine/raw_path_state.rb

@@ -18,16 +18,17 @@ class Engine
 		# reuse them without reparsing frontmatter.
 		class LocationState
 			# Builds one concrete-location cache.
-			def initialize(match:, string_array:, reference_template:)
+			def initialize(match:, string_array:, reference_template:, reference_context: nil)
 				@string_array = string_array
 				@reference_template = reference_template
+				@reference_context = reference_context
 				@entries = parse_entries(match.value)
 				@resolution_cache = {}
 			end
 
-			# Resolves every parsed entry for one primary-key scheme.
-			def resolved_entries_for(primary_path:, &resolver)
-				signature = primary_signature(primary_path)
+			# Resolves every parsed entry for one complete identity scheme.
+			def resolved_entries_for(primary_path:, scope_fields:, &resolver)
+				signature = identity_signature(primary_path: primary_path, scope_fields: scope_fields)
 				@resolution_cache[signature] ||= @entries.map do |entry|
 					resolver.call(entry)
 				end
@@ -38,20 +39,20 @@ class Engine
 			# Parses one concrete raw value into individual reference entries.
 			def parse_entries(raw_value)
 				@string_array.interpret(raw_value, split: -1, flatten: true).map do |entry|
-					@reference_template.parse(entry)
+					@reference_template.parse(entry, context: @reference_context)
 				end.compact
 			end
 
-			# Normalises the cache key for one primary-key scheme.
-			def primary_signature(primary_path)
-				primary_path.nil? ? '__relative_path__' : primary_path
+			# Normalises the cache key for one primary-key and scope scheme.
+			def identity_signature(primary_path:, scope_fields:)
+				[primary_path.nil? ? '__relative_path__' : primary_path, scope_fields.map(&:signature)]
 			end
 		end
 
 		attr_reader :document, :path, :raw_value
 
 		# Builds one raw-path cache for one document and path.
-		def initialize(document:, path:, data_path:, string_array:, reference_template:)
+		def initialize(document:, path:, data_path:, string_array:, reference_template:, reference_context: nil)
 			@document = document
 			@path = path
 			@data_path = data_path
@@ -64,7 +65,8 @@ class Engine
 				LocationState.new(
 					match: match,
 					string_array: @string_array,
-					reference_template: @reference_template
+					reference_template: @reference_template,
+					reference_context: reference_context
 				)
 			end
 		end
@@ -79,14 +81,16 @@ class Engine
 			@read_result.array_traversed?
 		end
 
-		# Resolves every parsed entry for one primary-key scheme.
-		def resolved_entries_for(primary_path:, registry:, active_document_checker: nil)
+		# Resolves every parsed entry for one complete identity scheme.
+		def resolved_entries_for(primary_path:, scope_fields: [], registry:, relationship: nil, active_document_checker: nil)
 			@location_states.flat_map do |location_state|
-				location_state.resolved_entries_for(primary_path: primary_path) do |entry|
+				location_state.resolved_entries_for(primary_path: primary_path, scope_fields: scope_fields) do |entry|
 					resolve_entry(
 						entry: entry,
 						primary_path: primary_path,
+						scope_fields: scope_fields,
 						registry: registry,
+						relationship: relationship,
 						active_document_checker: active_document_checker
 					)
 				end
@@ -96,21 +100,39 @@ class Engine
 		private
 
 		# Resolves one parsed entry to a document and canonical key.
-		def resolve_entry(entry:, primary_path:, registry:, active_document_checker:)
+		def resolve_entry(entry:, primary_path:, scope_fields:, registry:, relationship:, active_document_checker:)
+			effective_scope = registry.effective_scope_for(
+				reference_scope: entry.scope,
+				referring_document: @document,
+				scope_fields: scope_fields,
+				relationship: relationship
+			)
 			document = if entry.document?
-									 entry.page
-								 else
-									 registry.lookup(
-										 key: entry.key,
-										 primary_path: primary_path,
-										 collection: entry.collection.nil? ? nil : entry.collection.to_s
-										 )
-									 end
+				registry.validate_scope_match!(
+					document: entry.page,
+					scope: effective_scope,
+					scope_fields: scope_fields,
+					relationship: relationship,
+					referring_document: @document
+				)
+				entry.page
+			else
+				registry.lookup(
+					key: entry.key,
+					primary_path: primary_path,
+					collection: entry.collection.nil? ? nil : entry.collection.to_s,
+					scope_fields: scope_fields,
+					scope: effective_scope,
+					relationship: relationship,
+					referring_document: @document
+				)
+			end
 			return nil if active_document_checker && !active_document_checker.call(document)
 
 			{
 				document: document,
 				key: registry.key_for(document, primary_path: primary_path),
+				scope: effective_scope,
 				metadata: entry.metadata,
 				count: entry.count
 			}

data/lib/jekyll-relationships/engine/relationship_state.rb

@@ -75,6 +75,9 @@ class Engine
 			target_document = @engine.resolve_reference_document(
 				reference,
 				primary_path: @definition.primary_path,
+				scope_fields: @definition.scope_fields,
+				referring_document: @document,
+				relationship: relationship_description,
 				collection_hint: @definition.to_collection
 			)
 			unless @engine.active_document?(target_document)
@@ -99,6 +102,7 @@ class Engine
 			result = @links.add_detailed_result(
 				document: target_document,
 				key: @engine.registry.key_for(target_document, primary_path: @definition.primary_path),
+				scope: @engine.registry.scope_for(target_document, scope_fields: @definition.scope_fields, relationship: relationship_description),
 				metadata: sanitised_metadata(metadata),
 				count: count
 			)
@@ -145,6 +149,9 @@ class Engine
 			target_document = @engine.resolve_reference_document(
 				reference,
 				primary_path: @definition.primary_path,
+				scope_fields: @definition.scope_fields,
+				referring_document: @document,
+				relationship: relationship_description,
 				collection_hint: @definition.to_collection
 			)
 			@engine.clear_persisted_link(source_state: self, target_document: target_document) if clear_persisted
@@ -231,6 +238,11 @@ class Engine
 			"`#{@document.relative_path}` (#{@definition.from_collection} -> #{@definition.to_collection})"
 		end
 
+		# Returns the concrete relationship label used in validation diagnostics.
+		def relationship_description
+			"#{@definition.from_collection} -> #{@definition.to_collection}"
+		end
+
 		# Emits one debug event for this state when the definition enables it.
 		def debug(area, event, details)
 			@engine.debug_logger.relationship_event(

data/lib/jekyll-relationships/engine/session.rb

@@ -36,6 +36,7 @@ class Engine
 			@relationship_states = {}
 			@document_resolution_states = {}
 			@initial_links_seeded = false
+			@defer_bidirectional_mirror_resolvers = false
 		end
 
 		# Returns true when the document is active in this session.
@@ -71,6 +72,8 @@ class Engine
 			end
 
 			ensure_initial_links_seeded!
+			return state.current_references if defer_bidirectional_mirror_resolver_for?(state)
+
 			resolve_state(state)
 			state.current_references
 		end
@@ -94,16 +97,41 @@ class Engine
 		end
 
 		# Resolves one helper or resolver reference to a document, even if inactive.
-		def resolve_reference_document(reference, primary_path:, collection_hint: nil)
-			return reference if reference.is_a?(Jekyll::Document)
+		def resolve_reference_document(reference, primary_path:, scope_fields: [], referring_document: nil, relationship: nil, collection_hint: nil)
+			if reference.is_a?(Jekyll::Document)
+				@registry.scope_for(reference, scope_fields: scope_fields, relationship: relationship)
+				return reference
+			end
 
-			parsed_reference = @configuration.reference_template.parse(reference)
-			return parsed_reference.page if parsed_reference.document?
+			parsed_reference = @configuration.reference_template.parse(
+				reference,
+				context: reference_context(relationship: relationship, document: referring_document)
+			)
+			effective_scope = @registry.effective_scope_for(
+				reference_scope: parsed_reference.scope,
+				referring_document: referring_document,
+				scope_fields: scope_fields,
+				relationship: relationship
+			)
+			if parsed_reference.document?
+				@registry.validate_scope_match!(
+					document: parsed_reference.page,
+					scope: effective_scope,
+					scope_fields: scope_fields,
+					relationship: relationship,
+					referring_document: referring_document
+				)
+				return parsed_reference.page
+			end
 
 			@registry.lookup(
 				key: parsed_reference.key,
 				primary_path: primary_path,
-				collection: collection_hint || (parsed_reference.collection.nil? ? nil : parsed_reference.collection.to_s)
+				collection: collection_hint || (parsed_reference.collection.nil? ? nil : parsed_reference.collection.to_s),
+				scope_fields: scope_fields,
+				scope: effective_scope,
+				relationship: relationship,
+				referring_document: referring_document
 			)
 		end
 
@@ -198,16 +226,12 @@ class Engine
 
 		# Resolves every configured normal relationship state once.
 		def resolve_all_relationships!
-			@configuration.collections.each do |collection|
-				definitions = @configuration.normal_relationships_for(collection)
-				next if definitions.empty?
-
-				documents_for(collection).each do |document|
-					definitions.each do |definition|
-						resolve_relationships(document, definition.to_collection)
-					end
-				end
-			end
+			@defer_bidirectional_mirror_resolvers = true
+			resolve_all_relationships_pass!
+			@defer_bidirectional_mirror_resolvers = false
+			resolve_deferred_bidirectional_mirror_resolvers!
+		ensure
+			@defer_bidirectional_mirror_resolvers = false
 		end
 
 		# Writes the current session's resolved relationships back to frontmatter.
@@ -217,6 +241,14 @@ class Engine
 
 		private
 
+		# Builds consistent relationship and source-document details for reference parsing errors.
+		def reference_context(relationship:, document:)
+			parts = []
+			parts << "Relationship `#{relationship}`" unless relationship.nil? || relationship.to_s.empty?
+			parts << "reference on document `#{document.relative_path}`" if document
+			parts.join(' ')
+		end
+
 		# Seeds every normal relationship state before any resolver mutates the graph.
 		#
 		# Bidirectional removals can target reverse states that have not been
@@ -244,6 +276,48 @@ class Engine
 			state.resolve!
 			state
 		end
+
+		# Resolves every configured normal relationship state in collection and sequence order.
+		def resolve_all_relationships_pass!
+			@configuration.collections.each do |collection|
+				definitions = @configuration.normal_relationships_for(collection)
+				next if definitions.empty?
+
+				documents_for(collection).each do |document|
+					definitions.each do |definition|
+						resolve_relationships(document, definition.to_collection)
+					end
+				end
+			end
+		end
+
+		# Runs deferred resolvers for inverse bidirectional mirrors after forward resolution settles.
+		def resolve_deferred_bidirectional_mirror_resolvers!
+			@configuration.collections.each do |collection|
+				definitions = @configuration.normal_relationships_for(collection).select do |definition|
+					deferred_bidirectional_mirror_definition?(definition)
+				end
+				next if definitions.empty?
+
+				documents_for(collection).each do |document|
+					definitions.each do |definition|
+						resolve_relationships(document, definition.to_collection)
+					end
+				end
+			end
+		end
+
+		# Returns true when one definition should run in the deferred mirror-resolver pass.
+		def deferred_bidirectional_mirror_definition?(definition)
+			definition.bidirectional_mirror? && !definition.resolver_classes.empty?
+		end
+
+		# Returns true when this state should expose current links now but defer running its resolver.
+		def defer_bidirectional_mirror_resolver_for?(state)
+			return false unless @defer_bidirectional_mirror_resolvers
+
+			deferred_bidirectional_mirror_definition?(state.definition)
+		end
 	end
 end
 

data/lib/jekyll-relationships/engine/write_back.rb

@@ -90,6 +90,7 @@ class Engine
 					accumulator.add(
 						document: entry.fetch(:document),
 						key: entry.fetch(:key),
+						scope: entry.fetch(:scope),
 						metadata: entry.fetch(:metadata),
 						count: entry.fetch(:count)
 					)

data/lib/jekyll-relationships/engine.rb

@@ -43,7 +43,7 @@ class Engine
 		return if @configuration.collections.empty?
 
 		@registry.validate_collections!
-		@registry.validate_primary_paths!(primary_paths: @configuration.primary_paths)
+		@registry.validate_identity_schemes!(identity_schemes: @configuration.identity_schemes)
 		initial_active_document_ids = all_active_document_ids
 		initial_tree_seed_graph = build_tree_graph(active_document_ids: initial_active_document_ids)
 		normal_seed = NormalSeed.new(engine: self, active_document_ids: initial_active_document_ids)

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

@@ -6,12 +6,11 @@ module Plugins
 module Relationships
 module Pruning
 
-# Applies minimum-count prune rules to a mutable graph view.
+# Applies configured prune-rule predicates to a mutable graph view.
 #
 # The graph view may represent either resolved normal relationships or the
-# current tree adjacency. Pruning is recursive within the supplied graph:
-# removing one document can reduce the neighbour counts of others, so the pruner
-# keeps deleting documents until every rule is satisfied.
+# current tree adjacency. Pruning is recursive within the supplied graph because
+# removing one document can make relationship predicates select others.
 class RulePruner
 	# Builds one pruner over one mutable graph view and one ordered rule list.
 	def initialize(graph:, rules:, subject_documents_resolver: nil)
@@ -20,7 +19,7 @@ class RulePruner
 		@subject_documents_resolver = subject_documents_resolver
 	end
 
-	# Removes documents until all configured minimums are satisfied.
+	# Removes documents until no configured rule selects another candidate.
 	def prune!
 		removed_documents = []
 
@@ -40,12 +39,13 @@ class RulePruner
 
 	private
 
-	# Finds every document that currently violates at least one prune rule.
+	# Finds every document selected by at least one prune rule.
 	def prune_candidates
 		@rules.each_with_object({}) do |rule, candidates|
 			subject_documents_for(rule).each do |document|
 				next if candidates.key?(document.object_id)
-				next unless rule.neighbour_documents(graph: @graph, document: document).length < rule.min
+				next unless rule.frontmatter_selected?(document)
+				next unless rule.relationship_selected?(graph: @graph, document: document)
 
 				candidates[document.object_id] = document
 			end

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

@@ -291,30 +291,31 @@ class TreePhase
 		end.sort_by(&:relative_path)
 	end
 
-	# Attempts to reconnect one orphan to its surviving original grandparents.
+	# Attempts to reconnect one orphan to its nearest surviving original ancestors.
 	def reattach_orphan!(graph:, document:)
-		grandparent_candidates_for(graph: graph, document: document).each do |candidate|
+		nearest_surviving_ancestor_candidates_for(graph: graph, document: document).each do |candidate|
 			graph.add_edge(
 				parent_document: candidate.fetch(:document),
 				child_document: document,
 				tree_settings: candidate.fetch(:tree_settings),
 				definition: candidate.fetch(:definition),
-				source_description: 'pruning grandparents'
+				source_description: 'pruning ancestors'
 			)
 		end
 
 		graph.parent_documents_for(document).any?
 	end
 
-	# Returns every surviving grandparent candidate for one orphan.
-	def grandparent_candidates_for(graph:, document:)
+	# Returns the first surviving ancestor on every original parent lineage.
+	def nearest_surviving_ancestor_candidates_for(graph:, document:)
 		@provenance.original_parent_entries_for(document).each_with_object({}) do |parent_entry, candidates|
-			@provenance.original_parent_entries_for(parent_entry.fetch(:document)).each do |grandparent_entry|
-				grandparent_document = grandparent_entry.fetch(:document)
-				next unless graph.active_document?(grandparent_document)
-
-				candidates[grandparent_document.object_id] ||= {
-					document: grandparent_document,
+			nearest_surviving_ancestors_for(
+				graph: graph,
+				document: parent_entry.fetch(:document),
+				visited_document_ids: {}
+			).each do |ancestor_document|
+				candidates[ancestor_document.object_id] ||= {
+					document: ancestor_document,
 					definition: parent_entry.fetch(:definition),
 					tree_settings: parent_entry.fetch(:tree_settings)
 				}
@@ -322,6 +323,23 @@ class TreePhase
 		end.values
 	end
 
+	# Walks removed provenance nodes until each lineage reaches an active document.
+	def nearest_surviving_ancestors_for(graph:, document:, visited_document_ids:)
+		return [] if visited_document_ids.key?(document.object_id)
+		return [document] if graph.active_document?(document)
+
+		lineage_visited_document_ids = visited_document_ids.merge(document.object_id => true)
+		@provenance.original_parent_entries_for(document).each_with_object({}) do |parent_entry, ancestors|
+			nearest_surviving_ancestors_for(
+				graph: graph,
+				document: parent_entry.fetch(:document),
+				visited_document_ids: lineage_visited_document_ids
+			).each do |ancestor_document|
+				ancestors[ancestor_document.object_id] ||= ancestor_document
+			end
+		end.values
+	end
+
 	# Returns one document array with later duplicates removed by object id.
 	def unique_documents(documents)
 		Array(documents).each_with_object({}) do |document, unique_documents|

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,26 +24,27 @@ 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:, metadata: nil, count: 1)
+	def add_detailed_result(document:, key:, scope: nil, metadata: nil, count: 1)
 		if @multiple_settings.keep?
 			return {
 				action: :added,
-				entry: append_entry(document: document, key: key, metadata: metadata, count: 1)
+				entry: append_entry(document: document, key: key, scope: scope, metadata: metadata, count: 1)
 			}
 		end
 
@@ -68,6 +69,7 @@ class Accumulator
 		entry = append_entry(
 			document: document,
 			key: key,
+			scope: scope,
 			metadata: metadata,
 			count: counted_mode? ? normalise_count(count) : 1
 		)
@@ -157,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
@@ -184,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)
@@ -195,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(