jekyll-relationships 0.1.0.alpha → 0.1.1.alpha

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9656850968f173e997fe9e9a0b5500f12682c94d613f84444827bc5e52aa955a
-  data.tar.gz: e56a5ec1a9a44b58d2aa03e2066e99f7a4b39df1335c449e5325f6a5599b6871
+  metadata.gz: f4f49c60e8c57f7661b7fdec54b0d4d8ce2e9564dca858e86126ed2f810bfdec
+  data.tar.gz: f0c22961ff04cc0493e923676d45a9de3c69ff6720f72160e7897bf921272687
 SHA512:
-  metadata.gz: 010f090f1083c9f8ede2f8a99bd23e05a68b474f6c90b1519a4002c2446bf97eee6256b8cb7858cbd9a7e9aa9def901885fed07290e8a83c995656f71e47afd4
-  data.tar.gz: 1f0c0c85af8fd938f7d6d66a15e4dfb2941615057656867702a01b146e10426901969a2498e10d9fe08427d2226fe9d0f3968e50e262560223fff439ebfcda0f
+  metadata.gz: d4b352ce61991bf340b239a9aa881e1314274371637a96e24f317597a6343fb5bebb763fbe6b60f31d8877b3e01f1e4bfc5076994382940f08a757906f632933
+  data.tar.gz: 1ec40c78e1bf65e5781b580c4effc37e5510424031267c120a08be6bb6a0c5ffc1f36ccffa1fc4817b6c1ddc451fe996947b4403af48e36db7112d875dcd0bc2

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

@@ -26,7 +26,8 @@ class Configuration
 				'parents' => 'parents',
 				'children' => 'children',
 				'ancestors' => 'ancestors',
-				'descendants' => 'descendants'
+				'descendants' => 'descendants',
+				'depth' => 'depth'
 			}.freeze,
 			'max' => {
 				'parents' => -1,

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/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

@@ -38,6 +38,11 @@ class NormalRelationship
 		@debug.enabled?(area)
 	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/tree_relationship.rb

@@ -35,6 +35,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/engine/normal_seed.rb

@@ -0,0 +1,217 @@
+# 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)
+				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,
+					registry: @registry,
+					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),
+				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),
+				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)
+			@raw_path_states[[document.object_id, path]] ||= RawPathState.new(
+				document: document,
+				path: path,
+				data_path: @data_path,
+				string_array: @string_array,
+				reference_template: @configuration.reference_template
+			)
+		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