jekyll-relationships 0.1.0.alpha → 0.2.0.alpha

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9656850968f173e997fe9e9a0b5500f12682c94d613f84444827bc5e52aa955a
-  data.tar.gz: e56a5ec1a9a44b58d2aa03e2066e99f7a4b39df1335c449e5325f6a5599b6871
+  metadata.gz: 583920383adff1b25fb21db2130a379a76c6070780bb6fceddeb04c8eb0c5340
+  data.tar.gz: 528d4185f7ee05eced524a732096f19eea13750cb2ca85efa0d9cf325ad532dd
 SHA512:
-  metadata.gz: 010f090f1083c9f8ede2f8a99bd23e05a68b474f6c90b1519a4002c2446bf97eee6256b8cb7858cbd9a7e9aa9def901885fed07290e8a83c995656f71e47afd4
-  data.tar.gz: 1f0c0c85af8fd938f7d6d66a15e4dfb2941615057656867702a01b146e10426901969a2498e10d9fe08427d2226fe9d0f3968e50e262560223fff439ebfcda0f
+  metadata.gz: ede20ebf3d937fa6deda8da76f087d4040f7de50204b70675646cfcc3b860014d69929afde3de3c1f243cf8810f31a723ab914373ca8120a68308d6852501b9e
+  data.tar.gz: 3a5a9f5b7d9ed651af6bd9485749d6b0cf37d366f4da3a238d05c4f533440374bbc27dcfd3b43643d62c91a2a80646037130a296ecf86b3c59f3c8d38303e958

data/lib/jekyll-relationships/configuration/debug_setting.rb

@@ -23,12 +23,32 @@ class Configuration
 			'resolvers' => 'resolver execution and helper calls',
 			'trees' => 'tree discovery, edge handling, and tree write-back'
 		}.freeze
+		HASH_KEYS = %w[ids log].freeze
 
 		ALL_AREAS = AREAS.keys.freeze
 
 		class << self
 			# Builds one explicit debug setting from a loose config value.
 			def build(value:, string_array:, context:)
+				return build_hash_value(value: value, string_array: string_array, context: context) if value.is_a?(Hash)
+
+				build_scalar_value(value: value, string_array: string_array, context: context)
+			end
+
+			# Returns one disabled debug setting.
+			def disabled
+				new([])
+			end
+
+			# Returns one debug setting that enables every area.
+			def all
+				new(ALL_AREAS)
+			end
+
+			private
+
+			# Builds one debug setting from the legacy scalar forms.
+			def build_scalar_value(value:, string_array:, context:)
 				return disabled if value.nil? || false_value?(value)
 				return all if true_value?(value)
 
@@ -45,18 +65,30 @@ class Configuration
 				new(areas.uniq)
 			end
 
-			# Returns one disabled debug setting.
-			def disabled
-				new([])
-			end
+			# Builds one debug setting from the new hash form with optional ID filtering.
+			def build_hash_value(value:, string_array:, context:)
+				hash_value = stringify_hash(value)
+				unknown_keys = hash_value.keys - HASH_KEYS
+				unless unknown_keys.empty?
+					raise ConfigurationError, "`#{context}` contains unsupported keys #{unknown_keys.sort.join(', ')}. Supported keys: #{HASH_KEYS.join(', ')}."
+				end
 
-			# Returns one debug setting that enables every area.
-			def all
-				new(ALL_AREAS)
+				log_context = hash_value.key?('log') ? "#{context}.log" : context
+				scalar_setting = build_scalar_value(
+					value: hash_value.key?('log') ? hash_value.fetch('log') : true,
+					string_array: string_array,
+					context: log_context
+				)
+				new(
+					scalar_setting.areas,
+					parse_ids(
+						value: hash_value['ids'],
+						string_array: string_array,
+						context: "#{context}.ids"
+					)
+				)
 			end
 
-			private
-
 			# Returns true when a loose value means "debug everything".
 			def true_value?(value)
 				value == true || value.to_s.strip.casecmp('true').zero?
@@ -83,13 +115,34 @@ class Configuration
 				raise ConfigurationError,
 					"`#{context}` must be true, false, `all`, or a comma-delimited string/array of debug areas: #{ALL_AREAS.join(', ')}."
 			end
+
+			# Parses one optional string-or-array ID filter.
+			def parse_ids(value:, string_array:, context:)
+				return [] if value.nil?
+
+				raw_ids = string_array.interpret(value, split: true, flatten: true)
+				raise ConfigurationError, "`#{context}` must be a string or array of strings." if raw_ids.empty?
+
+				ids = raw_ids.map { |raw_id| raw_id.to_s.strip }.reject(&:empty?).uniq
+				raise ConfigurationError, "`#{context}` must contain at least one non-blank ID." if ids.empty?
+
+				ids
+			end
+
+			# Converts one config hash to a shallow string-keyed copy.
+			def stringify_hash(hash)
+				hash.each_with_object({}) do |(key, value), stringified|
+					stringified[key.to_s] = value
+				end
+			end
 		end
 
-		attr_reader :areas
+		attr_reader :areas, :ids
 
-		# Captures one immutable set of enabled debug areas.
-		def initialize(areas)
+		# Captures one immutable set of enabled debug areas and optional ID filters.
+		def initialize(areas, ids = [])
 			@areas = areas.freeze
+			@ids = Array(ids).map(&:to_s).uniq.freeze
 		end
 
 		# Returns true when any debug area is enabled, or when one named area is enabled.
@@ -99,6 +152,13 @@ class Configuration
 			@areas.include?(normalise_runtime_area(area))
 		end
 
+		# Returns true when this setting either has no ID filter or overlaps one.
+		def matches_ids?(related_ids)
+			return true if @ids.empty?
+
+			Array(related_ids).map(&:to_s).any? { |related_id| @ids.include?(related_id) }
+		end
+
 		private
 
 		# Normalises one runtime area name and raises on internal typos.

data/lib/jekyll-relationships/configuration/defaults.rb

@@ -15,6 +15,7 @@ class Configuration
 		FRONTMATTER = {
 			'base' => 'relationships',
 			'primary' => nil,
+			'scope' => nil,
 			'foreign' => '<collection>',
 			'output' => nil
 		}.freeze
@@ -26,7 +27,8 @@ class Configuration
 				'parents' => 'parents',
 				'children' => 'children',
 				'ancestors' => 'ancestors',
-				'descendants' => 'descendants'
+				'descendants' => 'descendants',
+				'depth' => 'depth'
 			}.freeze,
 			'max' => {
 				'parents' => -1,

data/lib/jekyll-relationships/configuration/frontmatter.rb

@@ -9,9 +9,17 @@ class Configuration
 
 	# Encapsulates one merged frontmatter configuration block.
 	#
-	# Instances resolve `base`, `primary`, `foreign`, and `output` paths so the
+	# Instances resolve `base`, `primary`, `scope`, `foreign`, and `output` paths so the
 	# rest of the engine can work with explicit values only.
 	class Frontmatter
+		# Describes one configured scope field while preserving both its public name and its base-resolved document path.
+		ScopeField = Struct.new(:name, :path) do
+			# Returns a stable value signature suitable for registry cache keys.
+			def signature
+				[name, path]
+			end
+		end
+
 		# Builds one frontmatter configuration helper.
 		def initialize(raw_config:, string_array:)
 			@raw_config = raw_config.is_a?(Hash) ? raw_config : {}
@@ -34,6 +42,25 @@ class Configuration
 			apply_base(raw_primary.to_s)
 		end
 
+		# Returns the configured scope fields with their literal reference keys and resolved document paths.
+		def scope_fields
+			raw_scope = fetch_value('scope')
+			return [] if raw_scope.nil?
+			unless raw_scope.is_a?(String) || raw_scope.is_a?(Array)
+				raise ConfigurationError, '`frontmatter.scope` must be a string, comma-delimited string, or array of non-empty path strings.'
+			end
+
+			raw_paths = raw_scope.is_a?(String) ? @string_array.interpret(raw_scope, split: true, flatten: true) : raw_scope
+			if raw_paths.empty? || raw_paths.any? { |path| !path.is_a?(String) || path.strip.empty? }
+				raise ConfigurationError, '`frontmatter.scope` must contain one or more non-empty path strings.'
+			end
+
+			raw_paths.map do |path|
+				name = path.strip
+				ScopeField.new(name, apply_base(name)).freeze
+			end.uniq { |field| field.name }
+		end
+
 		# Returns the resolved foreign input paths for one target collection.
 		def foreign_paths_for(to_collection:)
 			raw_foreign = fetch_value('foreign')

data/lib/jekyll-relationships/configuration/parser.rb

@@ -241,6 +241,7 @@ class Configuration
 				from_collection: from_collection,
 				to_collection: to_collection,
 				primary_path: frontmatter.primary_path,
+				scope_fields: frontmatter.scope_fields,
 				parent_child_pairs: parent_child_pairs(from_collection: from_collection, to_collection: to_collection, mode: mode),
 				tree_settings: tree_settings,
 				debug: debug,
@@ -259,6 +260,7 @@ class Configuration
 				from_collection: from_collection,
 				to_collection: to_collection,
 				primary_path: frontmatter.primary_path,
+				scope_fields: frontmatter.scope_fields,
 				foreign_paths: frontmatter.foreign_paths_for(to_collection: to_collection),
 				output_path: frontmatter.output_path_for(to_collection: to_collection),
 				debug: debug,
@@ -291,11 +293,25 @@ class Configuration
 				if prune_configuration.shortcut?
 					raise ConfigurationError, "Relationship entry #{entry_index + 1} cannot use `prune: <int>` on a tree relationship."
 				end
-				if prune_configuration.depth.nil?
+				if prune_configuration.min && prune_configuration.depth.nil?
 					raise ConfigurationError, "Relationship entry #{entry_index + 1} must define `prune.depth` when pruning a tree relationship."
 				end
-			elsif !prune_configuration.depth.nil?
-				raise ConfigurationError, "Relationship entry #{entry_index + 1} cannot define `prune.depth` on a normal relationship."
+				if prune_configuration.min.nil? && prune_configuration.depth
+					raise ConfigurationError, "Relationship entry #{entry_index + 1} must define `prune.min` when defining `prune.depth` on a tree relationship."
+				end
+				if prune_configuration.min.nil? && prune_configuration.where.nil?
+					raise ConfigurationError, "Relationship entry #{entry_index + 1} must define either `prune.where` or both `prune.min` and `prune.depth` when pruning a tree relationship."
+				end
+			else
+				if prune_configuration.where
+					raise ConfigurationError, "Relationship entry #{entry_index + 1} cannot define `prune.where` on a normal relationship."
+				end
+				if !prune_configuration.depth.nil?
+					raise ConfigurationError, "Relationship entry #{entry_index + 1} cannot define `prune.depth` on a normal relationship."
+				end
+				if prune_configuration.min.nil?
+					raise ConfigurationError, "Relationship entry #{entry_index + 1} must define `prune.min` when pruning a normal relationship."
+				end
 			end
 
 			prune_rules_for_entry(
@@ -358,6 +374,7 @@ class Configuration
 				members: members,
 				min: prune_configuration.min,
 				depth: prune_configuration.depth,
+				where: prune_configuration.where,
 				inverse: prune_configuration.inverse?,
 				entry_index: entry_index
 			)

data/lib/jekyll-relationships/configuration/prune_rule_settings.rb

@@ -11,10 +11,10 @@ class Configuration
 	#
 	# Relationship entries and hash-form targets may opt into pruning by defining
 	# a minimum neighbour count and, optionally, switching the subject of the rule
-	# to the inverse side of the relationship. Tree prune rules may also
-	# constrain which depths are eligible for pruning.
+	# to the inverse side of the relationship. Tree prune rules may constrain
+	# eligible depths, select frontmatter values, or combine both modes.
 	class PruneRuleSettings
-		attr_reader :mode, :min, :depth
+		attr_reader :mode, :min, :depth, :where
 
 		# Interprets one loose prune config value.
 		def self.build(raw_config:, context:)
@@ -31,6 +31,7 @@ class Configuration
 				@mode = 'direct'
 				@min = normalise_min(raw_config, context: context)
 				@depth = nil
+				@where = nil
 				return
 			end
 
@@ -43,11 +44,15 @@ class Configuration
 			@min = normalise_min(
 				Configuration::HashUtilities.fetch_hash_value(raw_config, 'min'),
 				context: context
-			)
+			) if Configuration::HashUtilities.hash_key?(raw_config, 'min')
 			@depth = normalise_depth(
 				Configuration::HashUtilities.hash_key?(raw_config, 'depth') ? Configuration::HashUtilities.fetch_hash_value(raw_config, 'depth') : nil,
 				context: context
 			)
+			@where = normalise_where(
+				Configuration::HashUtilities.fetch_hash_value(raw_config, 'where'),
+				context: context
+			) if Configuration::HashUtilities.hash_key?(raw_config, 'where')
 		end
 
 		# Returns true when the rule prunes the inverse side of the relationship.
@@ -73,7 +78,7 @@ class Configuration
 			raise ConfigurationError, "Unsupported `#{context}.mode` value `#{raw_mode}`."
 		end
 
-		# Resolves the configured minimum count and rejects non-positive values.
+		# Resolves the configured minimum count and rejects missing or non-positive values.
 		def normalise_min(raw_min, context:)
 			raise ConfigurationError, "`#{context}` must define `min`." if raw_min.nil?
 
@@ -92,6 +97,29 @@ class Configuration
 
 			interpreted_depth
 		end
+
+		# Resolves a non-empty hash of valid dot paths to exact expected values.
+		def normalise_where(raw_where, context:)
+			raise ConfigurationError, "`#{context}.where` must be a non-empty hash." unless raw_where.is_a?(Hash) && !raw_where.empty?
+
+			raw_where.each_with_object({}) do |(raw_path, expected_value), where|
+				path = normalise_where_path(raw_path, context: context)
+				raise ConfigurationError, "`#{context}.where` defines path `#{path}` more than once." if where.key?(path)
+
+				where[path] = expected_value
+			end.freeze
+		end
+
+		# Resolves one dot path and rejects blank segments.
+		def normalise_where_path(raw_path, context:)
+			path = raw_path.to_s.strip
+			segments = path.split('.', -1).map(&:strip)
+			if path.empty? || segments.any?(&:empty?)
+				raise ConfigurationError, "`#{context}.where` paths must contain non-blank dot-separated fields."
+			end
+
+			segments.join('.')
+		end
 	end
 end
 

data/lib/jekyll-relationships/configuration/tree_frontmatter.rb

@@ -14,7 +14,7 @@ class Configuration
 	# The resolved helper exposes explicit input and output paths so the tree
 	# graph never has to reimplement config merging rules.
 	class TreeFrontmatter
-		PATH_NAMES = %w[parent child parents children ancestors descendants].freeze
+		PATH_NAMES = %w[parent child parents children ancestors descendants depth].freeze
 
 		# Builds one tree-frontmatter helper from the resolved values.
 		def initialize(base:, raw_paths:, raw_output_path:, string_array:)
@@ -118,6 +118,11 @@ class Configuration
 			first_path_for('descendants')
 		end
 
+		# Returns the absolute prevailing depth output path.
+		def depth_output_path
+			first_path_for('depth')
+		end
+
 		# Returns the absolute output container path, if one is configured.
 		def output_path
 			return nil if blank_path?(@raw_output_path)
@@ -131,7 +136,7 @@ class Configuration
 		# The configured relative tree paths become nested keys within the output
 		# hash, while the configured output container path becomes the single
 		# frontmatter location on which that hash is written.
-		def output_payload(parent_value:, parents_value:, child_value:, children_value:, ancestors_value:, descendants_value:, max_parents:, max_children:)
+		def output_payload(parent_value:, parents_value:, child_value:, children_value:, ancestors_value:, descendants_value:, depth_value:, max_parents:, max_children:)
 			payload = {}
 			data_path = Jekyll::Plugins::Relationships::Support::DataPath.new
 
@@ -149,6 +154,7 @@ class Configuration
 
 			data_path.write(payload, first_relative_path_for('ancestors'), ancestors_value)
 			data_path.write(payload, first_relative_path_for('descendants'), descendants_value)
+			data_path.write(payload, first_relative_path_for('depth'), depth_value)
 			payload
 		end
 

data/lib/jekyll-relationships/configuration.rb

@@ -53,10 +53,6 @@ class Configuration
 			),
 			string_array: @string_array
 		)
-		@reference_template = References::Template.new(
-			config: build_reference_config,
-			count_enabled: @multiple_settings.count?
-		)
 		@tree_settings = TreeSettings.defaults(
 			string_array: @string_array
 		).merge_level(
@@ -81,6 +77,11 @@ class Configuration
 		@configured_relationships = parsed_result.fetch(:configured_relationships)
 		@normal_prune_rules = parsed_result.fetch(:normal_prune_rules)
 		@tree_prune_rules = parsed_result.fetch(:tree_prune_rules)
+		@reference_template = References::Template.new(
+			config: build_reference_config(scope_enabled: scope_configured?),
+			count_enabled: @multiple_settings.count?
+		)
+		validate_scope_reference_template!
 		attach_resolvers!(parser: parsed_relationships)
 	end
 
@@ -119,6 +120,24 @@ class Configuration
 		(normal_paths + tree_paths).uniq
 	end
 
+	# Returns every distinct primary-key and scope scheme used by configured relationships.
+	def identity_schemes
+		definitions = @normal_relationships.values.flat_map(&:values) + @tree_relationships
+		definitions.group_by do |definition|
+			[
+				definition.primary_path,
+				definition.scope_fields.map(&:signature)
+			]
+		end.map do |_, matching_definitions|
+			{
+				primary_path: matching_definitions.first.primary_path,
+				scope_fields: matching_definitions.first.scope_fields,
+				collections: matching_definitions.flat_map { |definition| [definition.from_collection, definition.to_collection] }.uniq.sort,
+				relationships: matching_definitions.map { |definition| "#{definition.from_collection} -> #{definition.to_collection}" }.uniq
+			}
+		end
+	end
+
 	private
 
 	# Builds the active global enabled setting.
@@ -142,7 +161,7 @@ class Configuration
 			string_array: @string_array
 		)
 		@reference_template = References::Template.new(
-			config: default_reference_config,
+			config: default_reference_config(scope_enabled: false),
 			count_enabled: @multiple_settings.count?
 		)
 		@tree_settings = TreeSettings.defaults(string_array: @string_array)
@@ -195,8 +214,8 @@ class Configuration
 	end
 
 	# Builds the resolved reference template config.
-	def build_reference_config
-		default_references = default_reference_config
+	def build_reference_config(scope_enabled:)
+		default_references = default_reference_config(scope_enabled: scope_enabled)
 		explicit_config = Configuration::HashUtilities.fetch_hash_value(@raw_config, 'references')
 		return explicit_config if explicit_config.is_a?(Hash)
 
@@ -212,12 +231,15 @@ class Configuration
 	end
 
 	# Builds the default reference template shape for the active duplicate mode.
-	def default_reference_config
+	def default_reference_config(scope_enabled:)
 		default_references = {
 			'id' => Jekyll::Plugins::Relationships::Support::Placeholders::KEY,
 			'collection' => Jekyll::Plugins::Relationships::Support::Placeholders::COLLECTION,
 			'page' => Jekyll::Plugins::Relationships::Support::Placeholders::PAGE
 		}
+		if scope_enabled
+			default_references['scope'] = Jekyll::Plugins::Relationships::Support::Placeholders::SCOPE
+		end
 		if @multiple_settings.count?
 			default_references['count'] = Jekyll::Plugins::Relationships::Support::Placeholders::COUNT
 		end
@@ -225,6 +247,19 @@ class Configuration
 		default_references
 	end
 
+	# Returns true when at least one concrete relationship uses scoped identity.
+	def scope_configured?
+		identity_schemes.any? { |scheme| !scheme.fetch(:scope_fields).empty? }
+	end
+
+	# Ensures scoped relationships have a reserved location for their complete effective scope.
+	def validate_scope_reference_template!
+		return unless scope_configured?
+		return if @reference_template.scope_property
+
+		raise ConfigurationError, 'Reference config must define exactly one <scope> property when any relationship configures `frontmatter.scope`.'
+	end
+
 	# Attaches registered resolver classes to matching concrete relationships.
 	def attach_resolvers!(parser:)
 		Resolvers::Base.registered_subclasses.each do |resolver_class|

data/lib/jekyll-relationships/debug_logger.rb

@@ -11,10 +11,30 @@ module Relationships
 # Jekyll logger. Callers should pass only already-resolved runtime state.
 class DebugLogger
 	MAX_VALUE_LENGTH = 500
+	STRING_ID_PROPERTIES = %w[
+		id
+		key
+		target_key
+		reference
+		result
+		references
+		entries
+		value
+		parent_value
+		child_value
+		ancestors_value
+		descendants_value
+	].freeze
+
+	# Builds one logger with the active reference key property for hash parsing.
+	def initialize(reference_key_property:)
+		@reference_key_property = reference_key_property.to_s
+		@data_path = Jekyll::Plugins::Relationships::Support::DataPath.new
+	end
 
 	# Emits one debug line for one normal relationship state.
 	def relationship_event(document:, definition:, area:, event:, details: {})
-		return unless definition.debug?(area)
+		return unless should_log?(definition: definition, area: area, document: document, details: details)
 
 		log(
 			area: area,
@@ -25,7 +45,9 @@ class DebugLogger
 
 	# Emits one debug line for a document-level write-back event.
 	def document_event(document:, definitions:, area:, event:, details: {})
-		debug_definitions = Array(definitions).select { |definition| definition.debug?(area) }
+		debug_definitions = Array(definitions).select do |definition|
+			should_log?(definition: definition, area: area, document: document, details: details)
+		end
 		return if debug_definitions.empty?
 
 		log(
@@ -41,7 +63,7 @@ class DebugLogger
 
 	# Emits one debug line for one tree relationship event.
 	def tree_event(document:, definition:, area:, event:, details: {})
-		return unless definition.debug?(area)
+		return unless should_log?(definition: definition, area: area, document: document, details: details)
 
 		log(
 			area: area,
@@ -62,6 +84,21 @@ class DebugLogger
 
 	private
 
+	# Returns true when one definition wants this area and its ID filter matches.
+	def should_log?(definition:, area:, document:, details:)
+		return false unless definition.debug?(area)
+
+		definition.debug_ids_match?(related_ids_for(definition: definition, document: document, details: details))
+	end
+
+	# Collects every document or reference ID that one event obviously touches.
+	def related_ids_for(definition:, document:, details:)
+		([document_key(document, primary_path: definition.primary_path)] + extract_related_ids(
+			details,
+			primary_path: definition.primary_path
+		)).compact.uniq
+	end
+
 	# Emits one line through the standard Jekyll logger.
 	def log(area:, prefix:, details:)
 		detail_text = details.each_with_object([]) do |(key, value), parts|
@@ -72,6 +109,60 @@ class DebugLogger
 		Jekyll.logger.info('Relationships:', "[debug:#{area}] #{message}")
 	end
 
+	# Resolves one document back to the primary key used by the active definition.
+	def document_key(document, primary_path:)
+		return nil unless document.is_a?(Jekyll::Document)
+
+		if primary_path.nil?
+			document.relative_path.sub(/\A_/, '').sub(/#{Regexp.escape(document.extname)}\z/, '')
+		else
+			value = @data_path.read(document.data, primary_path)
+			value.nil? ? nil : value.to_s
+		end
+	end
+
+	# Walks one debug payload and extracts any obvious relationship IDs from it.
+	def extract_related_ids(value, primary_path:, property_name: nil)
+		case value
+		when Jekyll::Document
+			[document_key(value, primary_path: primary_path)].compact
+		when Array
+			value.flat_map do |item|
+				extract_related_ids(item, primary_path: primary_path, property_name: property_name)
+			end
+		when Hash
+			extract_related_ids_from_hash(value, primary_path: primary_path)
+		when String
+			return [] unless property_name && STRING_ID_PROPERTIES.include?(property_name.to_s)
+
+			trimmed_value = value.strip
+			trimmed_value.empty? ? [] : [trimmed_value]
+		else
+			[]
+		end
+	end
+
+	# Reads likely ID-bearing properties from one debug hash before recurring.
+	def extract_related_ids_from_hash(hash, primary_path:)
+		ids = []
+		hash.each do |key, value|
+			string_key = key.to_s
+			if string_key == @reference_key_property || string_key == 'id'
+				trimmed_value = value.to_s.strip
+				ids << trimmed_value unless trimmed_value.empty?
+			end
+
+			ids.concat(
+				extract_related_ids(
+					value,
+					primary_path: primary_path,
+					property_name: string_key
+				)
+			)
+		end
+		ids.uniq
+	end
+
 	# Normalises values so large document objects stay readable in logs.
 	def normalise_value(value)
 		case value

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

@@ -11,14 +11,15 @@ module Definitions
 # Each instance describes one source collection, one target collection, and the
 # resolved frontmatter rules that apply to links between them.
 class NormalRelationship
-	attr_reader :from_collection, :to_collection, :primary_path, :foreign_paths,
+	attr_reader :from_collection, :to_collection, :primary_path, :scope_fields, :foreign_paths,
 		:output_path, :sequence, :reads_frontmatter, :bidirectional, :resolver_classes
 
 	# Captures the resolved configuration for one concrete pair.
-	def initialize(from_collection:, to_collection:, primary_path:, foreign_paths:, output_path:, debug:, sequence:, reads_frontmatter:, bidirectional:)
+	def initialize(from_collection:, to_collection:, primary_path:, scope_fields: [], foreign_paths:, output_path:, debug:, sequence:, reads_frontmatter:, bidirectional:)
 		@from_collection = from_collection
 		@to_collection = to_collection
 		@primary_path = primary_path
+		@scope_fields = scope_fields.freeze
 		@foreign_paths = foreign_paths
 		@output_path = output_path
 		@debug = debug
@@ -38,6 +39,16 @@ class NormalRelationship
 		@debug.enabled?(area)
 	end
 
+	# Returns true when this relationship is the synthetic inverse of a bidirectional pair.
+	def bidirectional_mirror?
+		@bidirectional && !@reads_frontmatter
+	end
+
+	# Returns true when one event's related IDs satisfy this pair's debug filter.
+	def debug_ids_match?(ids)
+		@debug.matches_ids?(ids)
+	end
+
 	# Registers one resolver class against this relationship pair.
 	def add_resolver(resolver_class)
 		@resolver_classes << resolver_class

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

@@ -11,17 +11,19 @@ module Definitions
 # Raw relationship entries may expand into many concrete relationship members.
 # After the global prune settings have been applied, each expanded prune rule
 # targets exactly one subject collection and one set of configured relationship
-# members whose neighbour counts should be combined for that subject.
+# members. Rules select by neighbour count, frontmatter values, or both.
 class PruneRule
-	attr_reader :kind, :subject_collection, :members, :min, :depth, :entry_index
+	attr_reader :kind, :subject_collection, :members, :min, :depth, :where, :entry_index
 
 	# Captures one immutable prune rule.
-	def initialize(kind:, subject_collection:, members:, min:, depth:, inverse:, entry_index:)
+	def initialize(kind:, subject_collection:, members:, min:, depth:, where:, inverse:, entry_index:)
 		@kind = kind
 		@subject_collection = subject_collection
 		@members = members.sort_by(&:sequence).freeze
 		@min = min
 		@depth = depth
+		@where = where
+		@frontmatter_matcher = Support::FrontmatterMatcher.new(expected_values: @where) unless @where.nil?
 		@inverse = inverse
 		@entry_index = entry_index
 	end
@@ -41,6 +43,20 @@ class PruneRule
 		@kind == :normal
 	end
 
+	# Returns true when the document satisfies this rule's frontmatter mode.
+	def frontmatter_selected?(document)
+		return true unless @frontmatter_matcher
+
+		@frontmatter_matcher.matches?(document.data)
+	end
+
+	# Returns true when the document satisfies this rule's relationship mode.
+	def relationship_selected?(graph:, document:)
+		return true if @min.nil?
+
+		neighbour_documents(graph: graph, document: document).length < @min
+	end
+
 	# Returns the combined neighbour documents for one subject document.
 	def neighbour_documents(graph:, document:)
 		@members.each_with_object({}) do |member, neighbours|