jekyll-relationships 0.1.1.alpha → 0.2.0.alpha

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

@@ -238,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]

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

@@ -30,11 +30,14 @@ class Graph
 		@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,
@@ -99,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.
@@ -143,26 +148,30 @@ 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
 		)
@@ -316,10 +325,10 @@ 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
@@ -402,6 +411,13 @@ 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)
@@ -471,20 +487,21 @@ class Graph
 	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?

data/lib/jekyll-relationships/version.rb

@@ -4,7 +4,7 @@ module Jekyll
 module Plugins
 
 module Relationships
-	VERSION = '0.1.1.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'