jekyll-relationships 0.1.0.alpha

data/lib/jekyll-relationships/references/template.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+module Jekyll
+module Plugins
+
+module Relationships
+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
+# output hashes.
+class Template
+
+	# Represents one parsed reference before or after it is resolved.
+	#
+	# 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
+
+		# Captures the parsed reference fields in one immutable object.
+		def initialize(key:, collection:, page:, count:, metadata:, original_value:)
+			@key = key
+			@collection = collection
+			@page = page
+			@count = count
+			@metadata = metadata
+			@original_value = original_value
+		end
+
+		# Returns true when the parsed reference already points at a document.
+		def document?
+			@page.is_a?(Jekyll::Document)
+		end
+	end
+
+	attr_reader :key_property, :collection_property, :page_property, :count_property
+
+	# Builds the reference template from config and duplicate-handling settings.
+	def initialize(config:, count_enabled:)
+		@config = stringify_hash(config || {})
+		@count_enabled = !!count_enabled
+		@key_property = nil
+		@collection_property = nil
+		@page_property = nil
+		@count_property = nil
+
+		parse_config!
+	end
+
+	# Parses one raw reference value from frontmatter or resolver input.
+	def parse(value)
+		case value
+		when String
+			key = value.to_s.strip
+			return nil if key.empty?
+
+			ParsedReference.new(
+				key: key,
+				collection: nil,
+				page: nil,
+				count: 1,
+				metadata: {},
+				original_value: value
+			)
+		when Hash
+			parse_hash_reference(value)
+		when Jekyll::Document
+			ParsedReference.new(
+				key: nil,
+				collection: nil,
+				page: value,
+				count: 1,
+				metadata: {},
+				original_value: value
+			)
+		else
+			raise ConfigurationError, "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)
+		hash = {}
+		hash[@key_property] = key
+		hash[@collection_property] = document.collection.label if @collection_property
+		hash[@page_property] = document if @page_property
+		hash[@count_property] = normalise_count(count) if include_count && @count_property
+
+		filter_metadata(metadata).each do |property, value|
+			hash[property] = value
+		end
+
+		hash
+	end
+
+	# Returns the configured property names that are reserved for the engine.
+	def reserved_properties
+		[@key_property, @collection_property, @page_property, @count_property].compact
+	end
+
+	# Returns the input properties that should never survive into free-form metadata.
+	#
+	# `count` is always treated as reserved input so resolver metadata cannot
+	# smuggle explicit multiplicities into modes that do not support them.
+	def reserved_input_properties
+		(reserved_properties + ['count']).uniq
+	end
+
+	private
+
+	# Validates and captures the configured placeholder mappings.
+	def parse_config!
+		@config.each do |property, value|
+			case value.to_s
+			when Jekyll::Plugins::Relationships::Support::Placeholders::KEY
+				raise ConfigurationError, 'Reference config can only define one <key> property.' if @key_property
+				@key_property = property
+			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::PAGE
+				raise ConfigurationError, 'Reference config can only define one <page> property.' if @page_property
+				@page_property = property
+			when Jekyll::Plugins::Relationships::Support::Placeholders::COUNT
+				raise ConfigurationError, 'Reference config can only define one <count> property.' if @count_property
+				@count_property = property
+			else
+				raise ConfigurationError, "Unsupported reference template value `#{value.inspect}`. Only placeholder keywords are supported."
+			end
+		end
+
+		raise ConfigurationError, 'Reference config must define exactly one <key> property.' unless @key_property
+		if @count_enabled && @count_property.nil?
+			raise ConfigurationError, 'Reference config must define exactly one <count> property when `relationships.multiple` is `count`.'
+		end
+	end
+
+	# Parses one hash reference according to the configured property names.
+	def parse_hash_reference(hash)
+		key = fetch_hash_value(hash, @key_property)
+		collection = @collection_property ? fetch_hash_value(hash, @collection_property) : nil
+		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}`."
+		end
+
+		ParsedReference.new(
+			key: key,
+			collection: collection,
+			page: page,
+			count: parsed_count(hash),
+			metadata: filter_metadata(hash),
+			original_value: hash
+		)
+	end
+
+	# Returns the parsed count value for one reference hash.
+	def parsed_count(hash)
+		return 1 unless @count_enabled
+		return 1 unless @count_property
+
+		raw_count = fetch_hash_value(hash, @count_property)
+		return 1 if raw_count.nil?
+
+		normalise_count(raw_count)
+	end
+
+	# Removes reserved engine properties from a metadata hash.
+	def filter_metadata(hash)
+		return {} unless hash.is_a?(Hash)
+
+		metadata = {}
+		hash.each do |property, value|
+			string_property = property.to_s
+			next if reserved_input_properties.include?(string_property)
+
+			metadata[string_property] = value
+		end
+
+		metadata
+	end
+
+	# Reads one property from a string- or symbol-keyed hash.
+	def fetch_hash_value(hash, property)
+		return nil unless property
+
+		Jekyll::Plugins::Relationships::Support::FrontmatterPath.read_hash(hash, property)
+	end
+
+	# Converts one hash to a shallow string-keyed copy.
+	def stringify_hash(hash)
+		return {} unless hash.is_a?(Hash)
+
+		hash.each_with_object({}) do |(key, value), stringified|
+			stringified[key.to_s] = value
+		end
+	end
+
+	# Validates and normalises one reference count.
+	def normalise_count(value)
+		integer_count = if value.is_a?(Integer)
+							 value
+						 elsif value.is_a?(String) && value.strip.match?(/\A\d+\z/)
+							 value.to_i
+						 else
+							 raise ResolutionError, "Relationship count `#{value.inspect}` must be a positive integer."
+						 end
+		raise ResolutionError, "Relationship count `#{value.inspect}` must be a positive integer." if integer_count < 1
+
+		integer_count
+	end
+end
+
+end
+end
+
+end
+end

data/lib/jekyll-relationships/resolvers/base.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module Jekyll
+module Plugins
+
+module Relationships
+module Resolvers
+
+# Base class for custom relationship resolvers.
+#
+# Subclass this in `_plugins`, declare `from` and `to`, then implement
+# `resolve` to add or remove links while the engine is resolving one concrete
+# document-to-collection pair.
+class Base
+
+	@registered_subclasses = []
+
+	class << self
+		attr_reader :from_definition, :to_definition
+
+		# Tracks subclasses while their class bodies are still being declared.
+		def inherited(subclass)
+			Base.remove_registered_subclass(subclass: subclass)
+			super
+		end
+
+		# Declares or reads the resolver's `from` selector.
+		def from(value = nil)
+			unless value.nil?
+				@from_definition = value
+				Base.refresh_registered_subclass(subclass: self)
+			end
+			@from_definition
+		end
+
+		# Declares or reads the resolver's `to` selector.
+		def to(value = nil)
+			unless value.nil?
+				@to_definition = value
+				Base.refresh_registered_subclass(subclass: self)
+			end
+			@to_definition
+		end
+
+		# Returns every resolver subclass whose `from` and `to` selectors are complete.
+		def registered_subclasses
+			@registered_subclasses ||= []
+		end
+
+		# Synchronises one resolver subclass with the shared registry after class-level declarations change.
+		def refresh_registered_subclass(subclass:)
+			remove_registered_subclass(subclass: subclass)
+			return if subclass == Base
+			return if subclass.from_definition.nil? || subclass.to_definition.nil?
+
+			registered_subclasses << subclass
+		end
+
+		# Removes one resolver subclass from the shared registry while declaration is incomplete.
+		def remove_registered_subclass(subclass:)
+			registered_subclasses.delete(subclass)
+		end
+	end
+
+	# Builds one resolver instance for one resolving relationship state.
+	def initialize(engine:, state:)
+		@engine = engine
+		@state = state
+		@document = state.document
+		@key = @engine.registry.key_for(@document, primary_path: state.definition.primary_path)
+		@from = state.definition.from_collection
+		@to = state.definition.to_collection
+		@site = @engine.site
+	end
+
+	# Override this in subclasses to change relationship output.
+	def resolve
+		raise NotImplementedError, "#{self.class} must implement `resolve`."
+	end
+
+	# Returns current relationships for one document and target collection.
+	def relationships(reference = nil, to: nil, from: nil)
+		target_collection = to || @to
+		document = resolve_helper_document(reference, from)
+		result = if document == @document && target_collection == @to && @state.resolving?
+						 @state.current_references
+					 else
+						 @engine.resolve_relationships(document, target_collection)
+					 end
+		debug_helper('resolver_relationships', {
+			reference: reference,
+			from: from,
+			target_document: document,
+			to: target_collection,
+			result: result
+		})
+		result
+	end
+
+	# Returns the referenced document, resolving its outgoing pairs if needed.
+	def document(reference = nil, from: nil)
+		document = resolve_helper_document(reference, from)
+		if document == @document
+			debug_helper('resolver_document', {
+				reference: reference,
+				from: from,
+				target_document: document
+			})
+			return document
+		end
+
+		@engine.resolve_document(document)
+		debug_helper('resolver_document', {
+			reference: reference,
+			from: from,
+			target_document: document
+		})
+		document
+	end
+
+	# Returns ancestors for one document reference.
+	def ancestors(reference = nil, from: nil, min: 1, max: -1)
+		document = resolve_helper_document(reference, from)
+		result = @engine.tree_graph.ancestors_for(document, min: min, max: max)
+		debug_helper('resolver_ancestors', {
+			reference: reference,
+			from: from,
+			target_document: document,
+			min: min,
+			max: max,
+			result: result
+		})
+		result
+	end
+
+	# Returns parents for one document reference.
+	def parents(reference = nil, from: nil)
+		ancestors(reference, from: from, min: 1, max: 1)
+	end
+
+	# Returns descendants for one document reference.
+	def descendants(reference = nil, from: nil, min: 1, max: -1)
+		document = resolve_helper_document(reference, from)
+		result = @engine.tree_graph.descendants_for(document, min: min, max: max)
+		debug_helper('resolver_descendants', {
+			reference: reference,
+			from: from,
+			target_document: document,
+			min: min,
+			max: max,
+			result: result
+		})
+		result
+	end
+
+	# Returns children for one document reference.
+	def children(reference = nil, from: nil)
+		descendants(reference, from: from, min: 1, max: 1)
+	end
+
+	# Adds one relationship from the current document to the target collection.
+	def link(target_reference, reference: nil)
+		@state.link(
+			target_reference,
+			metadata: reference,
+			origin: "resolver #{self.class.name || self.class}"
+		)
+	end
+
+	# Removes one relationship, or all of them when no reference is given.
+	def unlink(reference = nil)
+		@state.unlink(
+			reference,
+			origin: "resolver #{self.class.name || self.class}"
+		)
+	end
+
+	private
+
+	# Resolves one resolver helper argument to a real document.
+	def resolve_helper_document(reference, from_collection)
+		return @document if reference.nil?
+
+		@engine.resolve_reference_document(
+			reference,
+			primary_path: @state.definition.primary_path,
+			collection_hint: from_collection
+		)
+	end
+
+	# Emits one debug line for one resolver helper call when enabled.
+	def debug_helper(event, details)
+		@engine.debug_logger.relationship_event(
+			document: @document,
+			definition: @state.definition,
+			area: 'resolvers',
+			event: event,
+			details: details
+		)
+	end
+end
+
+end
+end
+
+end
+end

data/lib/jekyll-relationships/run_logger.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Jekyll
+module Plugins
+
+module Relationships
+
+# Emits the default high-level summary lines for relationship processing.
+#
+# This logger stays separate from debug logging so the engine can always report
+# the configured relationship coverage, prune removals, and total run time
+# without mixing that output into the lower-level trace areas.
+class RunLogger
+	MAX_REMOVED_FILENAME_CHARACTERS = 50
+	NON_BREAKING_SPACE = "\u00a0"
+
+	# Builds one summary logger for one engine run.
+	def initialize
+		@started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+	end
+
+	# Logs one multi-line summary of the configured relationships.
+	def relationship_summary(entries:, relationship_count:)
+		log_lines(
+			header: "#{relationship_count} relationships defined.",
+			lines: justified_lines(entries)
+		)
+	end
+
+	# Logs one multi-line summary of the documents removed by pruning.
+	def pruning_summary(removed_documents_by_collection:)
+		total_removed = removed_documents_by_collection.values.flatten.length
+		entries = removed_documents_by_collection.keys.sort.map do |collection|
+			documents = removed_documents_by_collection.fetch(collection)
+			{
+				label: "#{collection}:",
+				details: "#{documents.length} removed (#{removed_filenames(documents)})"
+			}
+		end
+		log_lines(
+			header: "Removed #{total_removed} items because of pruning rules.",
+			lines: justified_lines(entries)
+		)
+	end
+
+	# Logs the total elapsed time for relationship processing.
+	def finish!
+		elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @started_at
+		Jekyll.logger.info('Relationships:', format('Done in %.2f seconds.', elapsed))
+	end
+
+	private
+
+	# Writes one heading plus a tree-shaped list of lines.
+	def log_lines(header:, lines:)
+		Jekyll.logger.info('Relationships:', header)
+		lines.each_with_index do |line, index|
+			branch = index == lines.length - 1 ? '└─' : '├─'
+			Jekyll.logger.info('Relationships:', "#{branch} #{line}")
+		end
+	end
+
+	# Builds one truncated filename list for the removed-documents summary.
+	def removed_filenames(documents)
+		filenames = Array(documents).map do |document|
+			File.basename(document.relative_path)
+		end.sort
+		return '' if filenames.empty?
+
+		included_names = []
+		character_total = 0
+
+		filenames.each do |filename|
+			next_total = character_total + filename.length
+			break if !included_names.empty? && next_total > MAX_REMOVED_FILENAME_CHARACTERS
+
+			included_names << filename
+			character_total = next_total
+		end
+
+		text = included_names.join(', ')
+		return text if included_names.length == filenames.length
+
+		"#{text}, ..."
+	end
+
+	# Aligns summary details with non-breaking spaces so Jekyll preserves padding.
+	def justified_lines(entries)
+		maximum_label_length = Array(entries).map { |entry| entry.fetch(:label).length }.max || 0
+		Array(entries).map do |entry|
+			label = entry.fetch(:label)
+			padding_width = [maximum_label_length - label.length, 0].max + 1
+			"#{label}#{NON_BREAKING_SPACE * padding_width}#{entry.fetch(:details)}"
+		end
+	end
+end
+
+end
+
+end
+end