jekyll-relationships 0.1.0.alpha → 0.2.0.alpha

data/lib/jekyll-relationships/definitions/tree_relationship.rb

@@ -12,13 +12,14 @@ module Definitions
 # and which frontmatter, maximum, URL, and primary-key rules should be used to
 # resolve references for this concrete relationship definition.
 class TreeRelationship
-	attr_reader :from_collection, :to_collection, :primary_path, :tree_settings, :sequence
+	attr_reader :from_collection, :to_collection, :primary_path, :scope_fields, :tree_settings, :sequence
 
 	# Captures the allowed parent-child directions for one tree definition.
-	def initialize(from_collection:, to_collection:, primary_path:, parent_child_pairs:, tree_settings:, debug:, sequence:)
+	def initialize(from_collection:, to_collection:, primary_path:, scope_fields: [], parent_child_pairs:, tree_settings:, debug:, sequence:)
 		@from_collection = from_collection
 		@to_collection = to_collection
 		@primary_path = primary_path
+		@scope_fields = scope_fields.freeze
 		@parent_child_pairs = parent_child_pairs
 		@tree_settings = tree_settings
 		@debug = debug
@@ -35,6 +36,11 @@ class TreeRelationship
 		@debug.enabled?(area)
 	end
 
+	# Returns true when one event's related IDs satisfy this definition's debug filter.
+	def debug_ids_match?(ids)
+		@debug.matches_ids?(ids)
+	end
+
 	# Returns true when one parent-child direction is permitted.
 	def allows_parent_child?(parent_collection:, child_collection:)
 		@parent_child_pairs.include?([parent_collection, child_collection])

data/lib/jekyll-relationships/documents/registry.rb

@@ -6,17 +6,18 @@ module Plugins
 module Relationships
 module Documents
 
-# Indexes participating documents by collection and primary key.
+# Indexes participating documents by collection, primary key, and optional complete scope.
 #
-# Indices are built lazily per primary-key path so relationship definitions can
-# use different key schemes without rebuilding unrelated lookups.
+# Indices are built lazily per complete identity scheme so relationship definitions can
+# use different primary and scope paths without rebuilding unrelated lookups.
 class Registry
 
 	# Builds the registry over the collections used by the configuration.
 	def initialize(site:, collections:)
 		@site = site
 		@collections = collections
-		@indices_by_primary_path = {}
+		@indices_by_identity = {}
+		@data_path = Jekyll::Plugins::Relationships::Support::DataPath.new
 	end
 
 	# Returns true when the document belongs to one of the tracked collections.
@@ -48,7 +49,19 @@ class Registry
 	# Builds every requested primary-key index so duplicates fail eagerly.
 	def validate_primary_paths!(primary_paths:)
 		Array(primary_paths).uniq.each do |primary_path|
-			index_for(primary_path)
+			index_for(primary_path: primary_path, scope_fields: [])
+		end
+	end
+
+	# Builds every requested identity index so missing scope values and duplicate identities fail eagerly.
+	def validate_identity_schemes!(identity_schemes:)
+		Array(identity_schemes).each do |scheme|
+			index_for(
+				primary_path: scheme.fetch(:primary_path),
+				scope_fields: scheme.fetch(:scope_fields),
+				collections: scheme.fetch(:collections),
+				relationship: scheme.fetch(:relationships).join(', ')
+			)
 		end
 	end
 
@@ -57,61 +70,157 @@ class Registry
 		if primary_path.nil?
 			default_relative_key(document)
 		else
-			value = Jekyll::Plugins::Relationships::Support::DataPath.new.read(document.data, primary_path)
+			value = @data_path.read(document.data, primary_path)
 			raise ResolutionError, "Document `#{document.relative_path}` is missing primary key path `#{primary_path}`." if value.nil?
 
 			value.to_s
 		end
 	end
 
-	# Resolves one key to a document, optionally constrained to a collection.
-	def lookup(key:, primary_path:, collection: nil)
-		index = index_for(primary_path)
-		if collection
-			document = fetch_nested(index.fetch(:by_collection), collection, key.to_s)
-			raise ResolutionError, "Could not resolve key `#{key}` in collection `#{collection}`." unless document
+	# Reads and validates a document's complete scope for one configured identity scheme.
+	def scope_for(document, scope_fields:, relationship: nil)
+		return nil if scope_fields.empty?
+
+		scope_fields.each_with_object({}) do |field, scope|
+			value = @data_path.read(document.data, field.path)
+			if value.nil?
+				raise ResolutionError, "#{relationship_prefix(relationship)}document `#{document.relative_path}` is missing required scope field `#{field.name}` at frontmatter path `#{field.path}`."
+			end
+
+			scope[field.name] = value
+		end
+	end
+
+	# Resolves reference overrides over the referring document's scope and validates every configured field.
+	def effective_scope_for(reference_scope:, referring_document:, scope_fields:, relationship: nil)
+		return nil if scope_fields.empty? && (reference_scope.nil? || reference_scope.empty?)
+
+		reference_scope ||= {}
+		unless reference_scope.is_a?(Hash)
+			raise ResolutionError, "#{relationship_prefix(relationship)}reference on document `#{referring_document.relative_path}` must provide scope as a hash."
+		end
+
+		configured_names = scope_fields.map(&:name)
+		unknown_names = reference_scope.keys.map(&:to_s) - configured_names
+		unless unknown_names.empty?
+			raise ResolutionError, "#{relationship_prefix(relationship)}reference on document `#{referring_document.relative_path}` uses unconfigured scope field `#{unknown_names.first}`."
+		end
+
+		scope_fields.each_with_object({}) do |field, effective_scope|
+			value = if hash_property?(reference_scope, field.name)
+						 Jekyll::Plugins::Relationships::Support::FrontmatterPath.read_hash(reference_scope, field.name)
+					 else
+						 @data_path.read(referring_document.data, field.path)
+					 end
+			if value.nil?
+				raise ResolutionError, "#{relationship_prefix(relationship)}reference on document `#{referring_document.relative_path}` has no effective value for scope field `#{field.name}`."
+			end
 
-			return document
+			effective_scope[field.name] = value
 		end
+	end
+
+	# Ensures one already-selected target contains and exactly matches an effective scope.
+	def validate_scope_match!(document:, scope:, scope_fields:, relationship: nil, referring_document: nil)
+		return nil if scope_fields.empty?
 
-		matches = index.fetch(:by_key).fetch(key.to_s, [])
-		raise ResolutionError, "Could not resolve key-only reference `#{key}`." if matches.empty?
-		return matches.first if index.fetch(:site_wide_unique)
-		return matches.first if matches.length == 1
+		target_scope = scope_for(document, scope_fields: scope_fields, relationship: relationship)
+		scope_fields.each do |field|
+			next if target_scope.fetch(field.name) == scope.fetch(field.name)
 
-		collections = matches.map { |document| collection_label(document) }.uniq.sort.join(', ')
-		raise ResolutionError, "Key-only reference `#{key}` is ambiguous across collections: #{collections}."
+			raise ResolutionError, scope_mismatch_message(
+				document: document,
+				field: field,
+				expected_value: scope.fetch(field.name),
+				actual_value: target_scope.fetch(field.name),
+				relationship: relationship,
+				referring_document: referring_document
+			)
+		end
+
+		target_scope
+	end
+
+	# Resolves one key and complete scope to a document, optionally constrained to a collection.
+	def lookup(key:, primary_path:, collection: nil, scope_fields: [], scope: nil, relationship: nil, referring_document: nil)
+		index = index_for(primary_path: primary_path, scope_fields: scope_fields, relationship: relationship)
+		candidates = if collection
+						 fetch_nested(index.fetch(:by_collection), collection, key.to_s) || []
+					 else
+						 index.fetch(:by_key).fetch(key.to_s, [])
+					 end
+		if candidates.empty?
+			if collection
+				raise ResolutionError, "#{relationship_prefix(relationship)}could not resolve key `#{key}` in collection `#{collection}`#{source_suffix(referring_document)}."
+			end
+
+			raise ResolutionError, "#{relationship_prefix(relationship)}could not resolve key-only reference `#{key}`#{source_suffix(referring_document)}."
+		end
+
+		matches = if scope_fields.empty?
+					 candidates
+				 else
+					 candidates.select { |entry| entry.fetch(:scope) == scope }
+				 end
+		if matches.empty?
+			raise_scope_mismatch!(
+				candidates: candidates,
+				scope: scope,
+				scope_fields: scope_fields,
+				relationship: relationship,
+				referring_document: referring_document
+			)
+		end
+
+		matched_documents = matches.map { |entry| entry.fetch(:document) }
+		return matched_documents.first if collection
+
+		return matched_documents.first if matched_documents.length == 1
+
+		collections = matched_documents.map { |document| collection_label(document) }.uniq.sort.join(', ')
+		raise ResolutionError, "#{relationship_prefix(relationship)}key-only reference `#{key}` is ambiguous across collections: #{collections}#{source_suffix(referring_document)}."
 	end
 
 	private
 
-	# Returns or builds the index for one primary-key scheme.
-	def index_for(primary_path)
-		signature = primary_path.nil? ? '__relative_path__' : primary_path
-		@indices_by_primary_path[signature] ||= build_index(primary_path)
+	# Returns or builds the index for one complete identity scheme.
+	def index_for(primary_path:, scope_fields:, collections: nil, relationship: nil)
+		signature = [primary_path.nil? ? '__relative_path__' : primary_path, scope_fields.map(&:signature)]
+		@indices_by_identity[signature] ||= build_index(
+			primary_path: primary_path,
+			scope_fields: scope_fields,
+			collections: collections || @collections,
+			relationship: relationship
+		)
 	end
 
-	# Builds the collection and global indices for one scheme.
-	def build_index(primary_path)
-		by_collection = Hash.new { |hash, key| hash[key] = {} }
+	# Builds the collection and global indices for one complete identity scheme.
+	def build_index(primary_path:, scope_fields:, collections:, relationship: nil)
+		by_collection = Hash.new { |hash, key| hash[key] = Hash.new { |nested_hash, nested_key| nested_hash[nested_key] = [] } }
 		by_key = Hash.new { |hash, key| hash[key] = [] }
 
-		@collections.each do |collection|
+		collections.each do |collection|
 			documents_for(collection).each do |document|
 				key = key_for(document, primary_path: primary_path)
-				if by_collection[collection].key?(key)
-					raise ResolutionError, "Primary key `#{key}` is duplicated within collection `#{collection}`."
+				scope = scope_for(document, scope_fields: scope_fields, relationship: relationship)
+				existing_entry = by_collection[collection][key].find { |entry| entry.fetch(:scope) == scope }
+				if existing_entry
+					if scope_fields.empty?
+						raise ResolutionError, "Primary key `#{key}` is duplicated within collection `#{collection}`."
+					end
+
+					raise ResolutionError, "#{relationship_prefix(relationship)}primary key `#{key}` is duplicated within collection `#{collection}` and scope #{scope.inspect} by documents `#{existing_entry.fetch(:document).relative_path}` and `#{document.relative_path}`."
 				end
 
-				by_collection[collection][key] = document
-				by_key[key] << document
+				entry = { document: document, scope: scope }
+				by_collection[collection][key] << entry
+				by_key[key] << entry
 			end
 		end
 
 		{
 			by_collection: by_collection,
-			by_key: by_key,
-			site_wide_unique: by_key.values.all? { |documents| documents.length <= 1 }
+			by_key: by_key
 		}
 	end
 
@@ -123,6 +232,46 @@ class Registry
 		first_hash[second_key]
 	end
 
+	# Raises a field-specific error when key candidates exist but none match the requested complete scope.
+	def raise_scope_mismatch!(candidates:, scope:, scope_fields:, relationship:, referring_document:)
+		candidate = candidates.first
+		field = scope_fields.find do |configured_field|
+			candidate.fetch(:scope).fetch(configured_field.name) != scope.fetch(configured_field.name)
+		end
+		raise ResolutionError, scope_mismatch_message(
+			document: candidate.fetch(:document),
+			field: field,
+			expected_value: scope.fetch(field.name),
+			actual_value: candidate.fetch(:scope).fetch(field.name),
+			relationship: relationship,
+			referring_document: referring_document
+		)
+	end
+
+	# Builds one detailed exact-match failure for a configured scope field.
+	def scope_mismatch_message(document:, field:, expected_value:, actual_value:, relationship:, referring_document:)
+		"#{relationship_prefix(relationship)}target document `#{document.relative_path}` has scope field `#{field.name}` value `#{actual_value.inspect}`, not the required `#{expected_value.inspect}`#{source_suffix(referring_document)}."
+	end
+
+	# Returns true when one literal scope key exists in string or symbol form.
+	def hash_property?(hash, property)
+		hash.key?(property) || hash.key?(property.to_s) || hash.key?(property.to_s.to_sym)
+	end
+
+	# Prefixes an error with its concrete relationship where available.
+	def relationship_prefix(relationship)
+		return '' if relationship.nil? || relationship.to_s.empty?
+
+		"Relationship `#{relationship}`: "
+	end
+
+	# Adds the referring document to lookup diagnostics where available.
+	def source_suffix(document)
+		return '' unless document
+
+		" from document `#{document.relative_path}`"
+	end
+
 	# Implements the README's default relative-path key rule.
 	def default_relative_key(document)
 		document.relative_path.sub(/\A_/, '').sub(/#{Regexp.escape(document.extname)}\z/, '')

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

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+module Jekyll
+module Plugins
+
+module Relationships
+
+class Engine
+
+	# Stores the source-derived normal relationship graph used to seed each round.
+	#
+	# The seed graph is built once from frontmatter, including deterministic
+	# bidirectional mirrors, and is later reduced only by document removals.
+	# Resolver output never flows back into this structure.
+	class NormalSeed
+		# Builds one normal seed graph for the current active document set.
+		def initialize(engine:, active_document_ids:)
+			@engine = engine
+			@configuration = engine.configuration
+			@registry = engine.registry
+			@data_path = engine.data_path
+			@debug_logger = engine.debug_logger
+			@active_document_ids = active_document_ids.each_with_object({}) do |document_id, active_ids|
+				active_ids[document_id] = true
+			end
+			@string_array = Jekyll::Plugins::Relationships::Support::StringArray.new
+			@raw_path_states = {}
+			@entries_by_state = {}
+			build!
+		end
+
+		# Returns the seed entries for one concrete document-to-collection pair.
+		def entries_for(document, to_collection)
+			duplicate_entries(@entries_by_state[[document.object_id, to_collection]])
+		end
+
+		# Permanently removes documents from the seed graph in both source and target positions.
+		def remove_documents!(documents)
+			removed_document_ids = Array(documents).each_with_object({}) do |document, lookup|
+				lookup[document.object_id] = true
+			end
+			return if removed_document_ids.empty?
+
+			@entries_by_state.delete_if do |(source_document_id, _to_collection), _entries|
+				removed_document_ids.key?(source_document_id)
+			end
+			@entries_by_state.each_value do |entries|
+				entries.reject! do |entry|
+					removed_document_ids.key?(entry.fetch(:document).object_id)
+				end
+			end
+		end
+
+		private
+
+		# Builds the full source-derived seed graph once.
+		def build!
+			accumulators = {}
+
+			@configuration.collections.each do |collection|
+				@configuration.normal_relationships_for(collection).each do |definition|
+					next unless definition.reads_frontmatter
+
+					documents_for(collection).each do |document|
+						seed_definition_from_frontmatter(
+							accumulators: accumulators,
+							document: document,
+							definition: definition
+						)
+					end
+				end
+			end
+
+			@entries_by_state = accumulators.each_with_object({}) do |(state_key, accumulator), entries_by_state|
+				entries_by_state[state_key] = accumulator.encounter_entries
+			end
+		end
+
+		# 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, definition)
+				debug_relationship_event(
+					document: document,
+					definition: definition,
+					event: 'raw_path',
+					details: {
+						path: path,
+						present: raw_state.present?,
+						value: raw_state.raw_value
+					}
+				)
+				next unless raw_state.present?
+
+				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(
+					document: document,
+					definition: definition,
+					event: 'raw_path_resolved',
+					details: {
+						path: path,
+						entries: resolved_entries.compact
+					}
+				)
+
+				resolved_entries.each do |entry|
+					next unless entry
+					if entry.fetch(:document).collection.label != definition.to_collection
+						debug_relationship_event(
+							document: document,
+							definition: definition,
+							event: 'raw_path_skipped',
+							details: {
+								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
+
+					add_direct_entry(
+						accumulators: accumulators,
+						document: document,
+						definition: definition,
+						entry: entry
+					)
+				end
+			end
+		end
+
+		# Adds one direct link and its deterministic bidirectional mirror when configured.
+		def add_direct_entry(accumulators:, document:, definition:, entry:)
+			accumulator_for(
+				accumulators: accumulators,
+				document: document,
+				to_collection: definition.to_collection
+			).add(
+				document: entry.fetch(:document),
+				key: entry.fetch(:key),
+				scope: entry.fetch(:scope),
+				metadata: entry.fetch(:metadata),
+				count: entry.fetch(:count)
+			)
+
+			return unless definition.bidirectional
+
+			accumulator_for(
+				accumulators: accumulators,
+				document: entry.fetch(:document),
+				to_collection: definition.from_collection
+			).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)
+			)
+		end
+
+		# Returns one reusable accumulator for one concrete source pair.
+		def accumulator_for(accumulators:, document:, to_collection:)
+			accumulators[[document.object_id, to_collection]] ||= Jekyll::Plugins::Relationships::References::Accumulator.new(
+				reference_template: @configuration.reference_template,
+				multiple_settings: @configuration.multiple_settings
+			)
+		end
+
+		# Returns every active document for one collection.
+		def documents_for(collection)
+			@registry.documents_for(collection).select do |document|
+				active_document?(document)
+			end
+		end
+
+		# Returns true when one document is still active in the seed graph.
+		def active_document?(document)
+			@active_document_ids.key?(document.object_id)
+		end
+
+		# Returns the cached raw-path parser for one document/path pair.
+		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_context: "Relationship `#{definition.from_collection} -> #{definition.to_collection}` reference on document `#{document.relative_path}`"
+			)
+		end
+
+		# Duplicates one stored seed-entry array defensively.
+		def duplicate_entries(entries)
+			Array(entries).map(&:dup)
+		end
+
+		# Emits one debug event while the seed graph is being built.
+		def debug_relationship_event(document:, definition:, event:, details:)
+			@debug_logger.relationship_event(
+				document: document,
+				definition: definition,
+				area: 'upgrading',
+				event: event,
+				details: details
+			)
+		end
+	end
+end
+
+end
+
+end
+end