jekyll-relationships 0.1.0.alpha → 0.2.0.alpha

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

@@ -20,7 +20,7 @@ class Engine
 			@document = document
 			@definition = definition
 			@status = :unseen
-			@raw_seeded = false
+			@seeded = false
 			@links = Jekyll::Plugins::Relationships::References::Accumulator.new(
 				reference_template: @engine.configuration.reference_template,
 				multiple_settings: @engine.configuration.multiple_settings
@@ -37,6 +37,16 @@ class Engine
 			@status == :resolved
 		end
 
+		# Seeds the state from the normal seed graph once, without running resolvers.
+		def ensure_seeded!
+			seed_initial_links!
+		end
+
+		# Returns true when one document is active in this session.
+		def active_document?(document = @document)
+			@engine.active_document?(document)
+		end
+
 		# Resolves the state unless it has already been handled.
 		def resolve!
 			return if resolved?
@@ -50,8 +60,10 @@ class Engine
 				bidirectional: @definition.bidirectional,
 				resolvers: @definition.resolver_classes.map { |resolver_class| @engine.debug_logger.resolver_name(resolver_class) }
 			})
-			seed_raw_links!
+			ensure_seeded!
 			run_resolvers!
+			@engine.reapply_persisted_links(state: self)
+			@engine.refresh_persisted_positions(state: self)
 			@status = :resolved
 			debug('resolution', 'resolve_finish', {
 				references: current_references
@@ -59,10 +71,13 @@ class Engine
 		end
 
 		# Adds one link to the state and mirrors it when required.
-		def link(reference, metadata: nil, count: 1, reflect: true, origin: 'resolver')
+		def link(reference, metadata: nil, count: 1, reflect: true, origin: 'resolver', persist: false)
 			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)
@@ -74,35 +89,50 @@ class Engine
 					count: count,
 					metadata: sanitised_metadata(metadata)
 				})
-				return
+				return {
+					action: :inactive,
+					entry: nil,
+					target_document: target_document
+				}
 			end
 			unless target_document.collection.label == @definition.to_collection
 				raise ResolutionError, "Resolver attempted to link `#{target_document.relative_path}` outside the allowed target collection `#{@definition.to_collection}`."
 			end
 
-			action = @links.add_result(
+			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
 			)
 			debug('mutations', 'link', {
-				action: action,
+				action: result.fetch(:action),
 				origin: origin,
 				target: target_document,
 				target_key: @engine.registry.key_for(target_document, primary_path: @definition.primary_path),
 				count: count,
 				metadata: sanitised_metadata(metadata)
 			})
-			return if action == :ignored
-			return unless reflect && @definition.bidirectional
+			if persist && result.fetch(:action) != :ignored
+				@engine.persist_link(
+					source_state: self,
+					target_document: target_document,
+					metadata: metadata,
+					count: count
+				)
+			end
+			if reflect && @definition.bidirectional && result.fetch(:action) != :ignored
+				@engine.mirror_add(source_state: self, target_document: target_document, metadata: metadata, count: count)
+			end
 
-			@engine.mirror_add(source_state: self, target_document: target_document, metadata: metadata, count: count)
+			result.merge(target_document: target_document)
 		end
 
 		# Removes one link, or every link when no reference is given.
-		def unlink(reference = nil, reflect: true, origin: 'resolver')
+		def unlink(reference = nil, reflect: true, origin: 'resolver', clear_persisted: true)
 			if reference.nil?
+				@engine.clear_all_persisted_links(source_state: self) if clear_persisted
 				if current_link_entries.empty?
 					debug('mutations', 'unlink_all', {
 						action: :missing,
@@ -119,8 +149,12 @@ 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
 			remove_document(document: target_document, reflect: reflect, origin: origin)
 		end
 
@@ -134,56 +168,28 @@ class Engine
 			@links.encounter_entries
 		end
 
-		private
+		# Repositions reinserted persisted entries after they have been added.
+		def reposition_entries!(reinsertions:, base_count:)
+			@links.reposition_entries!(reinsertions: reinsertions, base_count: base_count)
+		end
 
-		# Seeds the state from raw frontmatter once.
-		def seed_raw_links!
-			return unless @definition.reads_frontmatter
-			return if @raw_seeded
-
-			@definition.foreign_paths.each do |path|
-				raw_state = @engine.raw_path_state(@document, path)
-				debug('upgrading', 'raw_path', {
-					path: path,
-					present: raw_state.present?,
-					value: raw_state.raw_value
-				})
-				next unless raw_state.present?
+		private
 
-				resolved_entries = raw_state.resolved_entries_for(
-					primary_path: @definition.primary_path,
-					registry: @engine.registry,
-					active_document_checker: proc { |resolved_document| @engine.active_document?(resolved_document) }
+		# Seeds the state from the source-derived normal seed graph.
+		def seed_initial_links!
+			return if @seeded
+
+			@engine.seed_entries_for(@document, @definition.to_collection).each do |entry|
+				link(
+					entry.fetch(:document),
+					metadata: entry.fetch(:metadata),
+					count: entry.fetch(:count),
+					reflect: false,
+					origin: 'seed graph',
+					persist: false
 				)
-				debug('upgrading', 'raw_path_resolved', {
-					path: path,
-					entries: resolved_entries.compact
-				})
-
-				resolved_entries.each do |entry|
-					next unless entry
-					if entry.fetch(:document).collection.label != @definition.to_collection
-						debug('upgrading', 'raw_path_skipped', {
-							path: path,
-							target: entry.fetch(:document),
-							target_key: entry.fetch(:key),
-							actual_collection: entry.fetch(:document).collection.label,
-							expected_collection: @definition.to_collection
-						})
-						next
-					end
-
-					link(
-						entry.fetch(:document),
-						metadata: entry.fetch(:metadata),
-						count: entry.fetch(:count),
-						reflect: @definition.bidirectional,
-						origin: "frontmatter #{path}"
-					)
-				end
 			end
-
-			@raw_seeded = true
+			@seeded = true
 		end
 
 		# Instantiates and runs every configured resolver class.
@@ -232,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

@@ -11,12 +11,13 @@ class Engine
 	#
 	# The main engine creates a fresh session for each rebuild round so raw-path
 	# caches, resolver state, and relationship accumulators never outlive the
-	# graph they were built against.
+	# graph they were built against. Every round reseeds from the current source
+	# graph plus any explicit persisted-link overlay.
 	class Session
 		attr_reader :site, :configuration, :registry, :tree_graph, :data_path, :debug_logger
 
 		# Builds one new resolution session.
-		def initialize(engine:, active_document_ids:, tree_graph:)
+		def initialize(engine:, active_document_ids:, tree_graph:, normal_seed:, persisted_links:)
 			@engine = engine
 			@site = engine.site
 			@configuration = engine.configuration
@@ -24,6 +25,9 @@ class Engine
 			@tree_graph = tree_graph
 			@data_path = engine.data_path
 			@debug_logger = engine.debug_logger
+			@normal_seed = normal_seed
+			@persisted_links = persisted_links
+			@persisted_links.start_round!
 			@active_document_ids = active_document_ids.each_with_object({}) do |document_id, active_ids|
 				active_ids[document_id] = true
 			end
@@ -31,6 +35,8 @@ class Engine
 			@raw_path_states = {}
 			@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.
@@ -52,8 +58,7 @@ class Engine
 				path: path,
 				data_path: @data_path,
 				string_array: @string_array,
-				reference_template: @configuration.reference_template,
-				multiple_settings: @configuration.multiple_settings
+				reference_template: @configuration.reference_template
 			)
 		end
 
@@ -66,6 +71,9 @@ class Engine
 				raise ResolutionError, "No relationship is defined from collection `#{document.collection.label}` to `#{to_collection}`."
 			end
 
+			ensure_initial_links_seeded!
+			return state.current_references if defer_bidirectional_mirror_resolver_for?(state)
+
 			resolve_state(state)
 			state.current_references
 		end
@@ -89,19 +97,86 @@ 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
+
+		# Returns the source-derived seed entries for one concrete pair.
+		def seed_entries_for(document, to_collection)
+			return [] unless active_document?(document)
+
+			@normal_seed.entries_for(document, to_collection).select do |entry|
+				active_document?(entry.fetch(:document))
+			end
+		end
+
+		# Records one persisted resolver link so it can survive later rounds.
+		def persist_link(source_state:, target_document:, metadata:, count:)
+			@persisted_links.persist_link(
+				source_state: source_state,
+				target_document: target_document,
+				metadata: metadata,
+				count: count
 			)
 		end
 
+		# Removes one persisted resolver link.
+		def clear_persisted_link(source_state:, target_document:)
+			@persisted_links.clear_link(
+				source_state: source_state,
+				target_document: target_document
+			)
+		end
+
+		# Removes every persisted resolver link on one state.
+		def clear_all_persisted_links(source_state:)
+			@persisted_links.clear_all(source_state: source_state)
+		end
+
+		# Reapplies persisted links only when resolvers did not recreate them.
+		def reapply_persisted_links(state:)
+			@persisted_links.reapply_missing_links(state: state)
+		end
+
+		# Refreshes remembered persisted-link positions from the final current ordering.
+		def refresh_persisted_positions(state:)
+			@persisted_links.refresh_positions(state: state)
+		end
+
 		# Mirrors one bidirectional add into the reverse state.
 		def mirror_add(source_state:, target_document:, metadata:, count:)
 			return unless active_document?(target_document)
@@ -151,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.
@@ -170,6 +241,33 @@ 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
+		# resolved yet. Seeding the whole current graph up front ensures those
+		# reverse states already contain their direct seed links before any resolver
+		# adds or removes mirrored relationships.
+		def ensure_initial_links_seeded!
+			return if @initial_links_seeded
+
+			@configuration.collections.each do |collection|
+				@configuration.normal_relationships_for(collection).each do |definition|
+					documents_for(collection).each do |document|
+						relationship_state(document, definition.to_collection)&.ensure_seeded!
+					end
+				end
+			end
+			@initial_links_seeded = true
+		end
+
 		# Resolves one relationship state with cycle detection.
 		def resolve_state(state)
 			return state if state.resolved?
@@ -178,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

@@ -9,8 +9,8 @@ class Engine
 
 	# Writes resolved normal relationships back into document frontmatter.
 	#
-	# Input paths are upgraded in place while final resolved link sets are
-	# written to the configured output path for each relationship pair.
+	# Each relationship writes one final resolved link set to its configured
+	# output path. Any separate ingestion paths are left untouched.
 	class WriteBack
 		# Builds one write-back helper for the current engine instance.
 		def initialize(engine:)
@@ -37,7 +37,6 @@ class Engine
 		# Writes every normal relationship path for one document.
 		def write_document_relationships(document:, definitions:)
 			output_paths = {}
-			input_paths = {}
 
 			definitions.each do |definition|
 				state = @engine.relationship_state(document, definition.to_collection)
@@ -46,13 +45,6 @@ class Engine
 				output_path = definition.final_output_path
 				output_paths[output_path] ||= []
 				output_paths[output_path] << state
-				definition.foreign_paths.each do |path|
-					input_paths[path] ||= {
-						raw_state: @engine.raw_path_state(document, path),
-						definitions: []
-					}
-					input_paths[path][:definitions] << definition
-				end
 			end
 
 			output_paths.each do |path, states|
@@ -74,31 +66,6 @@ class Engine
 					}
 				)
 			end
-
-			input_paths.each do |path, input_path_state|
-				raw_state = input_path_state.fetch(:raw_state)
-				next if output_paths.key?(path)
-				next unless raw_state.present?
-
-				raw_state.write_upgraded_input!(
-					registry: @registry,
-					active_document_checker: proc { |resolved_document| active_document?(resolved_document) }
-				)
-				value = raw_state.upgraded_raw_value(
-					registry: @registry,
-					active_document_checker: proc { |resolved_document| active_document?(resolved_document) }
-				)
-				@engine.debug_logger.document_event(
-					document: document,
-					definitions: input_path_state.fetch(:definitions),
-					area: 'upgrading',
-					event: 'upgrade_input',
-					details: {
-						path: path,
-						value: value
-					}
-				)
-			end
 		end
 
 		# Rejects any consolidated output path that expands through arrays.
@@ -123,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)
 					)
@@ -138,13 +106,6 @@ class Engine
 
 			@registry.documents_for(collection)
 		end
-
-		# Returns true when one document is active in the current engine or session.
-		def active_document?(document)
-			return @engine.active_document?(document) if @engine.respond_to?(:active_document?)
-
-			true
-		end
 	end
 end