jekyll-relationships 0.1.0.alpha

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Jekyll
+module Plugins
+
+module Relationships
+
+class Configuration
+
+	# Encapsulates the global settings that control pruning behaviour.
+	#
+	# These settings determine whether expanded relationship entries should be
+	# combined into one prune rule per subject collection, how many prune rounds
+	# may run before the final rebuild pass, and how tree orphans should be
+	# handled after parent documents disappear.
+	class PruneSettings
+		DEFAULTS = {
+			'combine' => true,
+			'iterations' => 10,
+			'tree' => {
+				'orphans' => 'grandparents'
+			}.freeze
+		}.freeze
+
+		attr_reader :iterations, :tree_orphans
+
+		# Builds one prune-settings helper from raw configuration.
+		def initialize(raw_config:)
+			config = normalise_config(raw_config)
+			@combine = Configuration::HashUtilities.boolean_value(config.fetch('combine'), 'relationships.prune.combine')
+			@iterations = normalise_iterations(config.fetch('iterations'))
+			@tree_orphans = normalise_tree_orphans(Configuration::HashUtilities.fetch_hash_value(config, 'tree'))
+		end
+
+		# Returns true when expanded relationship members should combine by subject collection.
+		def combine?
+			@combine
+		end
+
+		# Returns the total number of prune rounds to run before the final rebuild pass.
+		def prune_rounds
+			@iterations + 1
+		end
+
+		private
+
+		# Converts the loose raw value into one normalised hash.
+		def normalise_config(raw_config)
+			return DEFAULTS if raw_config.nil?
+			raise ConfigurationError, '`relationships.prune` must be a hash.' unless raw_config.is_a?(Hash)
+
+			Configuration::HashUtilities.merge_hash(DEFAULTS, raw_config)
+		end
+
+		# Clamps the configured prune-round iteration count into the supported range.
+		def normalise_iterations(raw_iterations)
+			interpreted_iterations = Configuration::HashUtilities.integer_value(raw_iterations, 'relationships.prune.iterations')
+			return 0 if interpreted_iterations < 0
+			return 100 if interpreted_iterations > 100
+
+			interpreted_iterations
+		end
+
+		# Resolves the configured orphan-handling mode for tree pruning.
+		def normalise_tree_orphans(raw_tree_config)
+			tree_config = raw_tree_config.is_a?(Hash) ? raw_tree_config : {}
+			raw_mode = Configuration::HashUtilities.hash_key?(tree_config, 'orphans') ? Configuration::HashUtilities.fetch_hash_value(tree_config, 'orphans') : DEFAULTS.fetch('tree').fetch('orphans')
+			string_mode = raw_mode.to_s.strip.downcase
+			string_mode = DEFAULTS.fetch('tree').fetch('orphans') if string_mode.empty?
+			return 'grandparents' if %w[grandparent grandparents].include?(string_mode)
+			return 'grandparents required' if %w[grandparent\ required grandparents\ required].include?(string_mode)
+			return string_mode if %w[prune orphan].include?(string_mode)
+
+			raise ConfigurationError, "Unsupported relationships.prune.tree.orphans value `#{raw_mode}`."
+		end
+	end
+end
+
+end
+
+end
+end

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

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+module Jekyll
+module Plugins
+
+module Relationships
+
+class Configuration
+
+	# Resolves the tree-specific frontmatter locations for one effective config.
+	#
+	# Tree frontmatter inherits the active relationship frontmatter base at each
+	# override level, but may replace that base with its own `tree.frontmatter.base`.
+	# 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
+
+		# Builds one tree-frontmatter helper from the resolved values.
+		def initialize(base:, raw_paths:, raw_output_path:, string_array:)
+			@base = normalise_base(base)
+			@raw_paths = stringify_hash(raw_paths)
+			@raw_output_path = raw_output_path
+			@string_array = string_array
+			validate_paths!
+		end
+
+		# Builds the built-in default tree frontmatter configuration.
+		def self.defaults(string_array:)
+			new(
+				base: Defaults::FRONTMATTER.fetch('base'),
+				raw_paths: Defaults::TREE.fetch('frontmatter'),
+				raw_output_path: nil,
+				string_array: string_array
+			)
+		end
+
+		# Returns one cloned helper with one override level merged in.
+		#
+		# Relationship `frontmatter.base` is applied first for the level, then
+		# `tree.frontmatter.base` may replace it for tree paths only.
+		def merge_level(frontmatter_override:, tree_frontmatter_override:)
+			override_hash = tree_frontmatter_override.is_a?(Hash) ? tree_frontmatter_override : {}
+			next_base = base_after_overrides(frontmatter_override: frontmatter_override, tree_frontmatter_override: override_hash)
+			next_paths = @raw_paths.dup
+			next_output_path = @raw_output_path
+
+			PATH_NAMES.each do |name|
+				next unless Configuration::HashUtilities.hash_key?(override_hash, name)
+
+				next_paths[name] = Configuration::HashUtilities.fetch_hash_value(override_hash, name)
+			end
+
+			if Configuration::HashUtilities.hash_key?(override_hash, 'output')
+				next_output_path = Configuration::HashUtilities.fetch_hash_value(override_hash, 'output')
+			end
+
+			self.class.new(
+				base: next_base,
+				raw_paths: next_paths,
+				raw_output_path: next_output_path,
+				string_array: @string_array
+			)
+		end
+
+		# Returns the effective base path applied to tree frontmatter.
+		def base
+			@base
+		end
+
+		# Returns every absolute input path used to read parent references.
+		#
+		# Single-parent trees only read the singular parent keys, matching the
+		# documented contract that plural keys are ignored once the maximum is 1.
+		def parent_input_paths(max_parents:)
+			return paths_for('parent') if max_parents == 1
+
+			(paths_for('parent') + paths_for('parents')).uniq
+		end
+
+		# Returns every absolute input path used to read child references.
+		#
+		# Single-child trees mirror the parent-side behaviour and only read the
+		# singular child keys when the configured maximum is 1.
+		def child_input_paths(max_children:)
+			return paths_for('child') if max_children == 1
+
+			(paths_for('child') + paths_for('children')).uniq
+		end
+
+		# Returns the absolute prevailing singular parent output path.
+		def parent_output_path
+			first_path_for('parent')
+		end
+
+		# Returns the absolute prevailing singular child output path.
+		def child_output_path
+			first_path_for('child')
+		end
+
+		# Returns the absolute prevailing plural parent output path.
+		def parents_output_path
+			first_path_for('parents')
+		end
+
+		# Returns the absolute prevailing plural child output path.
+		def children_output_path
+			first_path_for('children')
+		end
+
+		# Returns the absolute prevailing ancestors output path.
+		def ancestors_output_path
+			first_path_for('ancestors')
+		end
+
+		# Returns the absolute prevailing descendants output path.
+		def descendants_output_path
+			first_path_for('descendants')
+		end
+
+		# Returns the absolute output container path, if one is configured.
+		def output_path
+			return nil if blank_path?(@raw_output_path)
+			raise ConfigurationError, 'Tree frontmatter output must be one path, not an array.' if @raw_output_path.is_a?(Array)
+
+			apply_base(@raw_output_path.to_s.strip)
+		end
+
+		# Builds the final tree-output hash for one document.
+		#
+		# 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:)
+			payload = {}
+			data_path = Jekyll::Plugins::Relationships::Support::DataPath.new
+
+			if max_parents == 1
+				data_path.write(payload, first_relative_path_for('parent'), parent_value)
+			else
+				data_path.write(payload, first_relative_path_for('parents'), parents_value)
+			end
+
+			if max_children == 1
+				data_path.write(payload, first_relative_path_for('child'), child_value)
+			else
+				data_path.write(payload, first_relative_path_for('children'), children_value)
+			end
+
+			data_path.write(payload, first_relative_path_for('ancestors'), ancestors_value)
+			data_path.write(payload, first_relative_path_for('descendants'), descendants_value)
+			payload
+		end
+
+		private
+
+		# Resolves the next effective base for one override level.
+		def base_after_overrides(frontmatter_override:, tree_frontmatter_override:)
+			next_base = @base
+
+			if Configuration::HashUtilities.hash_key?(frontmatter_override, 'base')
+				next_base = normalise_base(Configuration::HashUtilities.fetch_hash_value(frontmatter_override, 'base'))
+			end
+
+			if Configuration::HashUtilities.hash_key?(tree_frontmatter_override, 'base')
+				next_base = normalise_base(Configuration::HashUtilities.fetch_hash_value(tree_frontmatter_override, 'base'))
+			end
+
+			next_base
+		end
+
+		# Returns the configured absolute paths for one tree property.
+		def paths_for(name)
+			configured_paths_for(name).map { |path| apply_base(path) }
+		end
+
+		# Returns the first prevailing absolute path for one tree property.
+		def first_path_for(name)
+			paths_for(name).first
+		end
+
+		# Returns the first prevailing relative path for one tree property.
+		def first_relative_path_for(name)
+			configured_paths_for(name).first
+		end
+
+		# Returns the configured relative paths for one property.
+		def configured_paths_for(name)
+			raw_value = @raw_paths[name]
+			paths = @string_array.interpret(raw_value, split: true, flatten: true).map do |path|
+				string_path = path.to_s.strip
+				raise ConfigurationError, "Tree frontmatter path `#{name}` cannot be blank." if string_path.empty?
+
+				string_path
+			end
+			raise ConfigurationError, "Tree frontmatter must define at least one path for `#{name}`." if paths.empty?
+
+			paths.uniq
+		end
+
+		# Applies the current base to one relative path.
+		def apply_base(path)
+			return path if @base.empty?
+			return @base if path.to_s.empty?
+
+			"#{@base}.#{path}"
+		end
+
+		# Ensures the helper only stores string-keyed frontmatter fields.
+		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
+
+		# Normalises nil bases to the empty string for path resolution.
+		def normalise_base(raw_base)
+			return '' if raw_base.nil?
+
+			raw_base.to_s
+		end
+
+		# Returns true when one configured path is blank or missing.
+		def blank_path?(path)
+			path.nil? || path.to_s.strip.empty?
+		end
+
+		# Validates only the known path-bearing properties eagerly.
+		def validate_paths!
+			PATH_NAMES.each { |name| configured_paths_for(name) }
+			return if blank_path?(@raw_output_path)
+			return unless @raw_output_path.is_a?(Array)
+
+			raise ConfigurationError, 'Tree frontmatter output must be one path, not an array.'
+		end
+	end
+end
+
+end
+
+end
+end

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Jekyll
+module Plugins
+
+module Relationships
+
+class Configuration
+
+	# Encapsulates one effective tree configuration scope.
+	#
+	# Tree settings are merged level by level so relationship-level
+	# `frontmatter.base` overrides can replace higher-level tree bases before a
+	# lower-level `tree.frontmatter.base` optionally replaces them again.
+	class TreeSettings
+		attr_reader :frontmatter
+
+		# Builds one tree-settings helper from already-resolved values.
+		def initialize(frontmatter:, maximums:, url:)
+			@frontmatter = frontmatter
+			@maximums = Configuration::HashUtilities.merge_hash(Defaults::TREE.fetch('max'), maximums)
+			@url = !!url
+		end
+
+		# Builds the built-in default tree settings.
+		def self.defaults(string_array:)
+			new(
+				frontmatter: TreeFrontmatter.defaults(string_array: string_array),
+				maximums: Defaults::TREE.fetch('max'),
+				url: Defaults::TREE.fetch('url')
+			)
+		end
+
+		# Returns one cloned helper with one override level merged in.
+		def merge_level(frontmatter_override:, tree_override:)
+			override_hash = tree_override.is_a?(Hash) ? tree_override : {}
+			next_frontmatter = @frontmatter.merge_level(
+				frontmatter_override: frontmatter_override,
+				tree_frontmatter_override: Configuration::HashUtilities.fetch_hash_value(override_hash, 'frontmatter')
+			)
+			next_maximums = Configuration::HashUtilities.merge_hash(
+				@maximums,
+				Configuration::HashUtilities.fetch_hash_value(override_hash, 'max')
+			)
+			next_url = Configuration::HashUtilities.hash_key?(override_hash, 'url') ? !!Configuration::HashUtilities.fetch_hash_value(override_hash, 'url') : @url
+
+			self.class.new(
+				frontmatter: next_frontmatter,
+				maximums: next_maximums,
+				url: next_url
+			)
+		end
+
+		# Returns the configured maximum parent count.
+		def max_parents
+			Configuration::HashUtilities.integer_value(@maximums['parents'], 'tree.max.parents')
+		end
+
+		# Returns the configured maximum child count.
+		def max_children
+			Configuration::HashUtilities.integer_value(@maximums['children'], 'tree.max.children')
+		end
+
+		# Returns true when URL-derived tree inference is enabled.
+		def url?
+			@url
+		end
+	end
+end
+
+end
+
+end
+end

data/lib/jekyll-relationships/configuration.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require 'jekyll-relationships/definitions/normal_relationship'
+require 'jekyll-relationships/definitions/tree_relationship'
+require 'jekyll-relationships/configuration/defaults'
+require 'jekyll-relationships/configuration/debug_setting'
+require 'jekyll-relationships/configuration/hash_utilities'
+require 'jekyll-relationships/configuration/frontmatter'
+require 'jekyll-relationships/configuration/multiple_settings'
+require 'jekyll-relationships/configuration/prune_settings'
+require 'jekyll-relationships/configuration/prune_rule_settings'
+require 'jekyll-relationships/configuration/tree_frontmatter'
+require 'jekyll-relationships/configuration/tree_settings'
+require 'jekyll-relationships/configuration/parser'
+
+module Jekyll
+module Plugins
+
+module Relationships
+
+# Normalises the site configuration into explicit relationship definitions.
+#
+# The object resolves defaults once, exposes the final keyword and frontmatter
+# rules, and indexes the concrete relationship definitions used by the engine.
+class Configuration
+	attr_reader :keywords, :multiple_settings, :reference_template, :tree_settings, :global_frontmatter, :debug, :prune_settings
+
+	# Builds the full configuration model from `site.config`.
+	def initialize(site_config)
+		@string_array = Jekyll::Plugins::Relationships::Support::StringArray.new
+		@raw_config = Configuration::HashUtilities.fetch_hash_value(site_config, 'relationships') || {}
+		@enabled = build_enabled_setting
+
+		if !enabled?
+			initialise_disabled_configuration
+			return
+		end
+
+		@debug = build_debug_setting
+		global_frontmatter_override = Configuration::HashUtilities.fetch_hash_value(@raw_config, 'frontmatter')
+		global_tree_override = Configuration::HashUtilities.fetch_hash_value(@raw_config, 'tree')
+		@keywords = build_keywords(Configuration::HashUtilities.fetch_hash_value(@raw_config, 'keywords'))
+		@multiple_settings = MultipleSettings.new(
+			raw_config: Configuration::HashUtilities.fetch_hash_value(@raw_config, 'multiple')
+		)
+		@prune_settings = PruneSettings.new(
+			raw_config: Configuration::HashUtilities.fetch_hash_value(@raw_config, 'prune')
+		)
+		@global_frontmatter = Frontmatter.new(
+			raw_config: Configuration::HashUtilities.merge_hash(
+				Defaults::FRONTMATTER,
+				global_frontmatter_override
+			),
+			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(
+			frontmatter_override: global_frontmatter_override,
+			tree_override: global_tree_override
+		)
+
+		parsed_relationships = Parser.new(
+			raw_config: @raw_config,
+			string_array: @string_array,
+			global_debug: @debug,
+			global_frontmatter: @global_frontmatter,
+			global_tree_settings: @tree_settings,
+			keywords: @keywords,
+			prune_settings: @prune_settings
+		)
+
+		parsed_result = parsed_relationships.parse
+		@normal_relationships = parsed_result.fetch(:normal_relationships)
+		@tree_relationships = parsed_result.fetch(:tree_relationships)
+		@collections = parsed_result.fetch(:collections)
+		@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)
+		attach_resolvers!(parser: parsed_relationships)
+	end
+
+	# Returns true when relationship processing is globally enabled.
+	def enabled?
+		@enabled
+	end
+
+	# Returns the concrete normal relationship definition for one pair.
+	def normal_relationship_for(from_collection:, to_collection:)
+		collection_relationships = @normal_relationships[from_collection]
+		return nil unless collection_relationships
+
+		collection_relationships[to_collection]
+	end
+
+	# Returns all normal relationship definitions for one source collection.
+	def normal_relationships_for(collection)
+		(@normal_relationships[collection] || {}).values.sort_by(&:sequence)
+	end
+
+	# Returns all configured tree relationships.
+	def tree_relationships
+		@tree_relationships.sort_by(&:sequence)
+	end
+
+	# Returns every collection that participates in any relationship.
+	def collections
+		@collections.dup
+	end
+
+	# Returns every primary-key path used anywhere in the configuration.
+	def primary_paths
+		normal_paths = @normal_relationships.values.flat_map(&:values).map(&:primary_path)
+		tree_paths = @tree_relationships.map(&:primary_path)
+		(normal_paths + tree_paths).uniq
+	end
+
+	private
+
+	# Builds the active global enabled setting.
+	def build_enabled_setting
+		return Defaults::ENABLED unless Configuration::HashUtilities.hash_key?(@raw_config, 'enabled')
+
+		Configuration::HashUtilities.boolean_value(
+			Configuration::HashUtilities.fetch_hash_value(@raw_config, 'enabled'),
+			'relationships.enabled'
+		)
+	end
+
+	# Sets up the inert configuration used when the plugin is globally disabled.
+	def initialise_disabled_configuration
+		@debug = Configuration::DebugSetting.disabled
+		@keywords = build_keywords(nil)
+		@multiple_settings = MultipleSettings.new(raw_config: nil)
+		@prune_settings = PruneSettings.new(raw_config: nil)
+		@global_frontmatter = Frontmatter.new(
+			raw_config: Defaults::FRONTMATTER,
+			string_array: @string_array
+		)
+		@reference_template = References::Template.new(
+			config: default_reference_config,
+			count_enabled: @multiple_settings.count?
+		)
+		@tree_settings = TreeSettings.defaults(string_array: @string_array)
+		@normal_relationships = {}
+		@tree_relationships = []
+		@collections = []
+		@configured_relationships = []
+		@normal_prune_rules = []
+		@tree_prune_rules = []
+	end
+
+	public
+
+	# Returns every configured forward-facing relationship member in sequence order.
+	def configured_relationships
+		@configured_relationships.sort_by(&:sequence)
+	end
+
+	# Returns every configured prune rule for normal relationships.
+	def normal_prune_rules
+		@normal_prune_rules.sort_by do |rule|
+			[rule.subject_collection, rule.entry_index, rule.members.first.sequence]
+		end
+	end
+
+	# Returns every configured prune rule for tree relationships.
+	def tree_prune_rules
+		@tree_prune_rules.sort_by do |rule|
+			[rule.subject_collection, rule.entry_index, rule.members.first.sequence]
+		end
+	end
+
+	# Returns true when any relationship entry defined a prune rule.
+	def pruning_enabled?
+		!@normal_prune_rules.empty? || !@tree_prune_rules.empty?
+	end
+
+	# Builds the active keyword table.
+	def build_keywords(raw_keywords)
+		Configuration::HashUtilities.merge_hash(Defaults::KEYWORDS, raw_keywords)
+	end
+
+	# Builds the active global debug setting.
+	def build_debug_setting
+		Configuration::DebugSetting.build(
+			value: Configuration::HashUtilities.hash_key?(@raw_config, 'debug') ? Configuration::HashUtilities.fetch_hash_value(@raw_config, 'debug') : Defaults::DEBUG,
+			string_array: @string_array,
+			context: 'relationships.debug'
+		)
+	end
+
+	# Builds the resolved reference template config.
+	def build_reference_config
+		default_references = default_reference_config
+		explicit_config = Configuration::HashUtilities.fetch_hash_value(@raw_config, 'references')
+		return explicit_config if explicit_config.is_a?(Hash)
+
+		nested_frontmatter = Configuration::HashUtilities.fetch_hash_value(
+			Configuration::HashUtilities.fetch_hash_value(@raw_config, 'frontmatter'),
+			'references'
+		)
+		if nested_frontmatter.is_a?(Hash)
+			raise ConfigurationError, '`relationships.references` must be configured directly under `relationships`, not under `relationships.frontmatter`.'
+		end
+
+		default_references
+	end
+
+	# Builds the default reference template shape for the active duplicate mode.
+	def default_reference_config
+		default_references = {
+			'id' => Jekyll::Plugins::Relationships::Support::Placeholders::KEY,
+			'collection' => Jekyll::Plugins::Relationships::Support::Placeholders::COLLECTION,
+			'page' => Jekyll::Plugins::Relationships::Support::Placeholders::PAGE
+		}
+		if @multiple_settings.count?
+			default_references['count'] = Jekyll::Plugins::Relationships::Support::Placeholders::COUNT
+		end
+
+		default_references
+	end
+
+	# Attaches registered resolver classes to matching concrete relationships.
+	def attach_resolvers!(parser:)
+		Resolvers::Base.registered_subclasses.each do |resolver_class|
+			parser.pairs_for(
+				from_definition: resolver_class.from_definition,
+				to_definition: resolver_class.to_definition
+			).each do |from_collection, to_collection|
+				definition = normal_relationship_for(
+					from_collection: from_collection,
+					to_collection: to_collection
+				)
+				next unless definition
+
+				definition.add_resolver(resolver_class)
+			end
+		end
+	end
+end
+
+end
+
+end
+end