jekyll-test-harness 0.1.0.alpha

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e4a625cf3a3297d317602eba915e696eba8dc382122cf1ea22f329e36bdd15b7
+  data.tar.gz: cfa090aa27f25047e324736879dba8dbbf53dbfec5ae0d23464f2a84c228ff44
+SHA512:
+  metadata.gz: cc34a86b991338ce3088bd0a0cfd346d6f6bbf0625e9b16a4747de18eb1c7dcfc955f4a90640fc5a169badc06fd6334bb3a50ba2f53fecf1e54e42b79877d2ef
+  data.tar.gz: 073d5e32c6f0e110352b04c77ef76afa55778c89b7270b60c8652c321e690796a47eb7b9aed7a430d2ceedd19944c4650f0e6af4c0e5571ebe21ceae79434775

data/lib/jekyll_test_harness/core/configuration.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+module JekyllTestHarness
+	# Stores runtime harness settings and shared defaults used by SiteHarness.
+	module Configuration
+		DEFAULT_FAILURE_MODE = :clean
+		SUPPORTED_FAILURE_MODES = %i[clean keep].freeze
+		TEMPORARY_DIRECTORY_PREFIX = 'jekyll-test-harness'.freeze
+
+		module_function
+
+		# Returns the baseline Jekyll configuration for a temporary site.
+		def default_config(source:, destination:)
+			{
+				'source' => source,
+				'destination' => destination,
+				'quiet' => true,
+				'incremental' => false
+			}
+		end
+
+		# Applies runtime settings for failure handling and site root location.
+		def configure_runtime!(failures:, output:, project_root:)
+			@failure_mode = normalise_failure_mode(failures)
+			@project_root = File.expand_path((project_root || Dir.pwd).to_s)
+			@output = normalise_output(output, @project_root)
+		end
+
+		# Resets runtime settings to defaults.
+		def reset_runtime!
+			configure_runtime!(failures: DEFAULT_FAILURE_MODE, output: nil, project_root: Dir.pwd)
+		end
+
+		# Returns the configured behaviour for failed Jekyll builds.
+		def failure_mode
+			@failure_mode || DEFAULT_FAILURE_MODE
+		end
+
+		# Returns true when failed build directories should be kept for debugging.
+		def keep_failures?
+			failure_mode == :keep
+		end
+
+		# Exposes the temporary directory prefix used for unnamed fallback directories.
+		def temporary_directory_prefix
+			TEMPORARY_DIRECTORY_PREFIX
+		end
+
+		# Returns the project root captured during install!.
+		def project_root
+			@project_root || Dir.pwd
+		end
+
+		# Returns the configured base directory for build output roots, or nil for system temp.
+		def output
+			@output
+		end
+
+		# Validates and normalises failure mode values.
+		def normalise_failure_mode(failures)
+			selected_failures = failures.nil? ? DEFAULT_FAILURE_MODE : failures
+			normalised_failures = normalise_symbol_option(
+				option_name: 'failures',
+				value: selected_failures,
+				usage: 'Use `failures: :clean` (default) or `failures: :keep`.'
+			)
+			return normalised_failures if SUPPORTED_FAILURE_MODES.include?(normalised_failures)
+
+			raise ArgumentError, ValidationMessages.unsupported_value(
+				argument_name: 'failures',
+				value: failures,
+				supported_values: SUPPORTED_FAILURE_MODES,
+				usage: 'Use `failures: :clean` (default) or `failures: :keep`.'
+			)
+		end
+		private_class_method :normalise_failure_mode
+
+		# Expands custom output roots relative to project root.
+		def normalise_output(output, project_root)
+			return nil if output.nil?
+
+			output_path = normalise_path_argument(
+				argument_name: 'output',
+				value: output,
+				usage: "Use `nil` for system temp, a relative String like `'tmp/jekyll-sites'`, or an absolute path."
+			)
+			raise ArgumentError, '`output` must not be empty.' if output_path.strip.empty?
+
+			return File.expand_path(output_path) if Pathname.new(output_path).absolute?
+
+			File.expand_path(output_path, project_root)
+		end
+		private_class_method :normalise_output
+
+		# Normalises Symbol/String option values and rejects invalid input types.
+		def normalise_symbol_option(option_name:, value:, usage:)
+			return value if value.is_a?(Symbol)
+			return value.strip.to_sym if value.is_a?(String) && !value.strip.empty?
+
+			raise ArgumentError, ValidationMessages.type_error(argument_name: option_name, expected: 'a Symbol or non-empty String', value: value, usage: usage)
+		end
+		private_class_method :normalise_symbol_option
+
+		# Normalises path-like arguments and rejects unsupported input types.
+		def normalise_path_argument(argument_name:, value:, usage:)
+			return value if value.is_a?(String)
+			return value.to_path.to_s if value.respond_to?(:to_path)
+
+			raise ArgumentError, ValidationMessages.type_error(argument_name: argument_name, expected: 'a String path or Pathname', value: value, usage: usage)
+		end
+		private_class_method :normalise_path_argument
+	end
+end
+
+JekyllTestHarness::Configuration.reset_runtime!

data/lib/jekyll_test_harness/core/data_tools.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module JekyllTestHarness
+	# Provides deep clone and deep merge helpers used across config, files, and blueprints.
+	module DataTools
+		module_function
+
+		# Returns a deep clone so callers can safely mutate returned values.
+		def deep_clone(value)
+			case value
+			when Hash
+				value.each_with_object({}) do |(key, nested_value), clone|
+					clone[key] = deep_clone(nested_value)
+				end
+			when Array
+				value.map { |item| deep_clone(item) }
+			when String
+				value.dup
+			else
+				value
+			end
+		end
+
+		# Deep-merges hashes in the same spirit as ActiveSupport::Hash#deep_merge.
+		def deep_merge_hashes(base_hash, new_hash)
+			unless base_hash.is_a?(Hash) && new_hash.is_a?(Hash)
+				raise ArgumentError, "jekyll_merge hash inputs must both be Hash values. Received `base_hash`: #{ValidationMessages.describe_value(base_hash)} and `new_hash`: #{ValidationMessages.describe_value(new_hash)}. Usage: `jekyll_merge({ ... }, { ... })`."
+			end
+
+			merged_hash = deep_clone(base_hash)
+			new_hash.each do |key, value|
+				merged_hash[key] = if merged_hash[key].is_a?(Hash) && value.is_a?(Hash)
+					deep_merge_hashes(merged_hash[key], value)
+				else
+					deep_clone(value)
+				end
+			end
+			merged_hash
+		end
+	end
+end

data/lib/jekyll_test_harness/core/errors.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module JekyllTestHarness
+	# Base error class for all harness-specific failures.
+	class Error < StandardError
+	end
+
+	# Raised when a block-based API is called without a block.
+	class MissingBlockError < Error
+		# Creates a clear error message for missing block usage.
+		def initialize(message = 'This method requires a block.')
+			super(message)
+		end
+	end
+
+	# Wraps Jekyll build failures with context to help debugging.
+	class SiteBuildError < Error
+		attr_reader :source_path, :destination_path, :config_snapshot, :original_error
+
+		# Captures build context and the original exception that failed the build.
+		def initialize(cause:, source_path:, destination_path:, config_snapshot:)
+			@original_error = cause
+			@source_path = source_path
+			@destination_path = destination_path
+			@config_snapshot = config_snapshot
+			super(build_message)
+			set_backtrace(cause.backtrace)
+		end
+
+		private
+
+		# Builds a diagnostic message that can be shown directly in failing specs.
+		def build_message
+			[
+				"Jekyll site build failed: #{original_error.class}: #{original_error.message}",
+				"Source path: #{source_path}",
+				"Destination path: #{destination_path}",
+				"Config snapshot: #{config_snapshot.inspect}",
+				'Hint: call JekyllTestHarness.install!(..., failures: :keep) to retain failed temporary sites for debugging.'
+			].join("\n")
+		end
+	end
+
+	# Builds consistent, actionable validation messages for invalid harness usage.
+	module ValidationMessages
+		module_function
+
+		# Describes a runtime value with a class name and a safely-truncated inspect payload.
+		def describe_value(value)
+			inspected_value = value.inspect
+			inspected_value = "#{inspected_value[0, 157]}..." if inspected_value.length > 160
+			"#{inspected_value} (#{value.class})"
+		end
+
+		# Builds an error message for arguments that do not match the expected type.
+		def type_error(argument_name:, expected:, value:, usage: nil)
+			append_usage("#{argument_name} must be #{expected}. Received #{describe_value(value)}.", usage)
+		end
+
+		# Builds an error message for unsupported option values.
+		def unsupported_value(argument_name:, value:, supported_values:, usage: nil)
+			supported_description = supported_values.map(&:inspect).join(', ')
+			append_usage("Unsupported value for #{argument_name}: #{describe_value(value)}. Supported values: #{supported_description}.", usage)
+		end
+
+		# Builds an error message for APIs that require a block.
+		def missing_block(method_name:, usage:)
+			"#{method_name} requires a block. Usage: #{usage}."
+		end
+
+		# Appends usage guidance only when it is present.
+		def append_usage(message, usage)
+			return message if usage.nil? || usage.to_s.strip.empty?
+
+			"#{message} #{usage}"
+		end
+	end
+end

data/lib/jekyll_test_harness/core/file_tree.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'yaml'
+
+module JekyllTestHarness
+	# Writes nested file trees used to construct temporary Jekyll sites.
+	module FileTree
+		module_function
+
+		# Writes a YAML file to disk, creating parent directories when needed.
+		def write_yaml(path, data)
+			FileUtils.mkdir_p(File.dirname(path))
+			File.write(path, data.to_yaml)
+		end
+
+		# Writes a nested hash of files and directories under the supplied root.
+		def write(root, files)
+			files.each do |relative_path, contents|
+				full_path = File.join(root, relative_path.to_s)
+				if contents.is_a?(Hash)
+					FileUtils.mkdir_p(full_path)
+					write(full_path, contents)
+				else
+					FileUtils.mkdir_p(File.dirname(full_path))
+					File.write(full_path, contents.to_s)
+				end
+			end
+		end
+	end
+end

data/lib/jekyll_test_harness/core/files_dsl.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module JekyllTestHarness
+	# Builds nested Jekyll source file hashes via a small folder/file DSL.
+	class FilesDsl
+		# Initialises the builder with a host context for delegated helper calls.
+		def initialize(host_context:, project_root:)
+			@host_context = host_context
+			@project_root = project_root
+		end
+
+		# Evaluates the DSL block and returns the resulting nested file hash.
+		def build(&block)
+			tree = {}
+			return tree if block.nil?
+
+			TreeContext.new(tree: tree, host_context: @host_context, project_root: @project_root).evaluate(&block)
+		end
+
+		# Supports nested folder/file declarations while delegating unknown methods to the test context.
+		class TreeContext
+			# Initialises a tree context for one folder level.
+			def initialize(tree:, host_context:, project_root:)
+				@tree = tree
+				@host_context = host_context
+				@project_root = project_root
+			end
+
+			# Creates a nested folder. The block can define additional folders or files.
+			def folder(name, &block)
+				folder_tree = {}
+				@tree[normalise_entry_name(name, entry_type: 'folder')] = folder_tree
+				return folder_tree if block.nil?
+
+				self.class.new(tree: folder_tree, host_context: @host_context, project_root: @project_root).evaluate(&block)
+			end
+
+			# Creates a file where the block defines its final string contents.
+			def file(name, &block)
+				@tree[normalise_entry_name(name, entry_type: 'file')] = FileContext.new(host_context: @host_context, project_root: @project_root).evaluate(&block)
+			end
+
+			# Evaluates folder/file calls for this level.
+			def evaluate(&block)
+				instance_exec(&block)
+				@tree
+			end
+
+			private
+
+			# Delegates unknown DSL calls to the test context so helper composition still works.
+			def method_missing(method_name, *arguments, &block)
+				return @host_context.public_send(method_name, *arguments, &block) if @host_context && @host_context.respond_to?(method_name)
+
+				raise NoMethodError, "Unknown helper `#{method_name}` in jekyll_files tree context. Available DSL methods: `folder` and `file`."
+			end
+
+			# Mirrors delegated method support checks for introspection.
+			def respond_to_missing?(method_name, include_private = false)
+				(@host_context && @host_context.respond_to?(method_name, include_private)) || super
+			end
+
+			# Normalises file/folder names and rejects empty values that are hard to debug.
+			def normalise_entry_name(name, entry_type:)
+				entry_name = name.to_s
+				raise ArgumentError, "#{entry_type} name must not be empty." if entry_name.strip.empty?
+
+				entry_name
+			end
+		end
+
+		# Evaluates one file body, supporting either helper composition or direct return values.
+		class FileContext
+			# Initialises file content collection state.
+			def initialize(host_context:, project_root:)
+				@host_context = host_context
+				@project_root = project_root
+				@fragments = []
+				@used_content_helpers = false
+			end
+
+			# Emits YAML front matter wrapped with separators and a trailing blank line.
+			def frontmatter(hash = nil, file: nil, **keyword_hash)
+				@used_content_helpers = true
+				fixture_hash = file.nil? ? {} : FixtureLoader.read_yaml_hash(file: file, project_root: @project_root)
+				inline_hash = coerce_hash(hash, argument_name: 'frontmatter hash')
+				inline_hash = DataTools.deep_merge_hashes(inline_hash, coerce_hash(keyword_hash, argument_name: 'frontmatter hash')) unless keyword_hash.empty?
+				merged_hash = DataTools.deep_merge_hashes(fixture_hash, inline_hash)
+
+				yaml_payload = YAML.dump(merged_hash).sub(/\A---[ \t]*\n?/, '')
+				fragment = "---\n#{yaml_payload}---\n\n"
+				@fragments << fragment
+				fragment
+			end
+
+			# Emits raw file contents directly from inline text and/or a fixture file.
+			def contents(text = nil, file: nil)
+				@used_content_helpers = true
+				fixture_text = file.nil? ? '' : FixtureLoader.read_text(file: file, project_root: @project_root)
+				inline_text = text.nil? ? '' : text.to_s
+				fragment = "#{fixture_text}#{inline_text}"
+				@fragments << fragment
+				fragment
+			end
+
+			# Evaluates the file block and returns a final string payload.
+			def evaluate(&block)
+				return '' if block.nil?
+
+				returned_value = instance_exec(&block)
+				return @fragments.join if @used_content_helpers
+
+				coerce_return_value(returned_value)
+			end
+
+			private
+
+			# Converts nil/hash/string/array file return values into final file text.
+			def coerce_return_value(returned_value)
+				case returned_value
+				when nil
+					''
+				when String
+					returned_value
+				when Array
+					returned_value.map(&:to_s).join("\n")
+				when Hash
+					YAML.dump(returned_value)
+				else
+					raise ArgumentError, "File DSL block must return `String`, `Array`, `Hash`, or `nil` when not using `frontmatter`/`contents`. Received #{ValidationMessages.describe_value(returned_value)}."
+				end
+			end
+
+			# Normalises optional hash arguments into strict hash values.
+			def coerce_hash(value, argument_name:)
+				return {} if value.nil?
+				return value if value.is_a?(Hash)
+
+				raise ArgumentError, ValidationMessages.type_error(argument_name: argument_name, expected: 'a Hash', value: value, usage: "Pass `#{argument_name}` as a hash, for example: `#{argument_name}(title: 'My page')`.")
+			end
+
+			# Delegates unknown helper calls to the outer test context.
+			def method_missing(method_name, *arguments, &block)
+				return @host_context.public_send(method_name, *arguments, &block) if @host_context && @host_context.respond_to?(method_name)
+
+				raise NoMethodError, "Unknown helper `#{method_name}` in jekyll_files file context. Available DSL methods: `frontmatter` and `contents`."
+			end
+
+			# Mirrors delegated method checks for introspection.
+			def respond_to_missing?(method_name, include_private = false)
+				(@host_context && @host_context.respond_to?(method_name, include_private)) || super
+			end
+		end
+	end
+end

data/lib/jekyll_test_harness/core/fixture_loader.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'rbconfig'
+require 'yaml'
+
+module JekyllTestHarness
+	# Loads fixture files relative to the configured project root for DSL helper APIs.
+	module FixtureLoader
+		module_function
+
+		# Reads a fixture file as raw text.
+		def read_text(file:, project_root:)
+			resolved_path = resolve_path(file: file, project_root: project_root)
+			File.read(resolved_path)
+		rescue Errno::ENOENT
+			raise ArgumentError, "Fixture file was not found: #{file.inspect}. Resolved path: #{resolved_path}. Project root: #{File.expand_path(project_root.to_s)}."
+		end
+
+		# Reads and parses a YAML fixture, requiring the root document to be a hash.
+		def read_yaml_hash(file:, project_root:)
+			loaded_yaml = YAML.safe_load(read_text(file: file, project_root: project_root))
+			return {} if loaded_yaml.nil?
+			return loaded_yaml if loaded_yaml.is_a?(Hash)
+
+			raise ArgumentError, "Fixture '#{file}' must contain a YAML hash. Received #{ValidationMessages.describe_value(loaded_yaml)}."
+		rescue Psych::SyntaxError => raised_error
+			raise ArgumentError, "Fixture '#{file}' contains invalid YAML: #{raised_error.problem || raised_error.message}."
+		end
+
+		# Resolves a fixture path relative to the project root and blocks path traversal.
+		def resolve_path(file:, project_root:)
+			fixture_path = normalise_fixture_path(file)
+			project_root_path = normalise_project_root(project_root)
+			resolved_path = File.expand_path(fixture_path, project_root_path)
+			return resolved_path if path_within_root?(resolved_path, project_root_path)
+
+			raise ArgumentError, "Fixture path escapes the configured project root: #{fixture_path.inspect}. Project root: #{project_root_path}."
+		end
+
+		# Returns true when the candidate path is inside the configured project root.
+		def path_within_root?(candidate_path, root_path)
+			normalised_candidate = normalise_path_for_comparison(candidate_path)
+			normalised_root = normalise_path_for_comparison(root_path)
+			normalised_candidate == normalised_root || normalised_candidate.start_with?("#{normalised_root}/")
+		end
+		private_class_method :path_within_root?
+
+		# Normalises path separators and applies Windows-only case-folding for path containment checks.
+		def normalise_path_for_comparison(path)
+			normalised_path = File.expand_path(path).tr('\\', '/')
+			return normalised_path.downcase if windows_platform?
+
+			normalised_path
+		end
+		private_class_method :normalise_path_for_comparison
+
+		# Returns true when running on a Windows platform with case-insensitive default semantics.
+		def windows_platform?
+			RbConfig::CONFIG['host_os'].to_s.match?(/mswin|mingw|cygwin/i)
+		end
+		private_class_method :windows_platform?
+
+		# Normalises and validates fixture path arguments.
+		def normalise_fixture_path(file)
+			fixture_path = if file.is_a?(String)
+				file
+			elsif file.respond_to?(:to_path)
+				file.to_path.to_s
+			else
+				raise ArgumentError, ValidationMessages.type_error(
+					argument_name: 'file',
+					expected: 'a String path or Pathname',
+					value: file,
+					usage: "Use a project-relative fixture path such as `file: 'spec/fixtures/dsl/config.yml'`."
+				)
+			end
+
+			raise ArgumentError, "file must not be empty. Use a project-relative fixture path such as `file: 'spec/fixtures/dsl/config.yml'`." if fixture_path.strip.empty?
+
+			fixture_path
+		end
+		private_class_method :normalise_fixture_path
+
+		# Normalises and validates project root arguments.
+		def normalise_project_root(project_root)
+			root_path = if project_root.is_a?(String)
+				project_root
+			elsif project_root.respond_to?(:to_path)
+				project_root.to_path.to_s
+			else
+				raise ArgumentError, ValidationMessages.type_error(
+					argument_name: 'project_root',
+					expected: 'a String path or Pathname',
+					value: project_root,
+					usage: 'Pass the project root captured by `JekyllTestHarness.install!`.'
+				)
+			end
+			raise ArgumentError, 'project_root must not be empty.' if root_path.strip.empty?
+
+			File.expand_path(root_path)
+		end
+		private_class_method :normalise_project_root
+	end
+end

data/lib/jekyll_test_harness/core/jekyll_blueprint.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module JekyllTestHarness
+	# Represents reusable Jekyll build inputs that can be merged and composed in tests.
+	class JekyllBlueprint
+		attr_reader :config, :files
+
+		# Stores deep-cloned config and file hashes so blueprint instances stay immutable to callers.
+		def initialize(config: {}, files: {})
+			validate_hash!(config, 'config')
+			validate_hash!(files, 'files')
+
+			@config = DataTools.deep_clone(config)
+			@files = DataTools.deep_clone(files)
+		end
+
+		private
+
+		# Ensures public blueprint inputs are always hash-like structures.
+		def validate_hash!(value, field_name)
+			return if value.is_a?(Hash)
+
+			raise ArgumentError, ValidationMessages.type_error(
+				argument_name: "JekyllBlueprint #{field_name}",
+				expected: 'a Hash',
+				value: value,
+				usage: 'Build blueprints with `jekyll_blueprint(config: { ... }, files: { ... })`.'
+			)
+		end
+	end
+end

data/lib/jekyll_test_harness/core/paths.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module JekyllTestHarness
+	# Exposes output-first helpers for a built site while still supporting source inspection.
+	class Files
+		attr_reader :dir, :source_dir
+
+		# Initialises helpers with output and source roots.
+		def initialize(source_dir:, dir:)
+			@source_dir = source_dir
+			@dir = dir
+		end
+
+		# Returns the absolute path to a generated output file.
+		def path(relative_path)
+			resolve_relative_path(dir, relative_path)
+		end
+
+		# Reads a generated file from the output directory.
+		def read(relative_path)
+			File.read(path(relative_path))
+		end
+
+		# Lists generated output files as paths relative to the output directory.
+		def list(root = nil)
+			list_relative_files(dir, root)
+		end
+
+		# Returns the absolute path to a source file in the temporary site.
+		def source_path(relative_path)
+			resolve_relative_path(source_dir, relative_path)
+		end
+
+		# Reads a source file from the source directory.
+		def source_read(relative_path)
+			File.read(source_path(relative_path))
+		end
+
+		# Lists source files as paths relative to the source directory.
+		def source_list(root = nil)
+			list_relative_files(source_dir, root)
+		end
+
+		private
+
+		# Resolves a relative path and prevents directory traversal outside the root.
+		def resolve_relative_path(root_path, relative_path)
+			normalised_relative_path = normalise_relative_path(relative_path)
+			if absolute_path?(normalised_relative_path)
+				raise ArgumentError, "relative_path must not be absolute. Received #{ValidationMessages.describe_value(relative_path)}."
+			end
+
+			resolved_path = File.expand_path(File.join(root_path, normalised_relative_path))
+			expanded_root = File.expand_path(root_path)
+			return resolved_path if resolved_path == expanded_root || resolved_path.start_with?("#{expanded_root}#{File::SEPARATOR}")
+
+			raise ArgumentError, "relative_path escapes the site root: #{normalised_relative_path.inspect}. Site root: #{expanded_root}."
+		end
+
+		# Lists file paths for either the root or a subfolder, always returned relative to root_path.
+		def list_relative_files(root_path, list_root)
+			search_root = list_root.nil? ? root_path : resolve_relative_path(root_path, list_root)
+			return [] unless File.exist?(search_root)
+
+			paths = if File.file?(search_root)
+				[search_root]
+			else
+				Dir.glob(File.join(search_root, '**', '*')).select { |candidate_path| File.file?(candidate_path) }
+			end
+			paths.map { |absolute_path| absolute_path.sub("#{File.expand_path(root_path)}#{File::SEPARATOR}", '').tr('\\', '/') }.sort
+		end
+
+		# Normalises relative path values and rejects invalid types.
+		def normalise_relative_path(relative_path)
+			return relative_path if relative_path.is_a?(String)
+			return relative_path.to_path.to_s if relative_path.respond_to?(:to_path)
+
+			raise ArgumentError, ValidationMessages.type_error(
+				argument_name: 'relative_path',
+				expected: 'a String path or Pathname',
+				value: relative_path,
+				usage: "Use a path relative to the build root, such as `'docs/index.html'`."
+			)
+		end
+
+		# Returns true when a candidate path is absolute in Unix or Windows forms.
+		def absolute_path?(candidate_path)
+			candidate_path.start_with?('/') || candidate_path.match?(/\A[A-Za-z]:[\\\/]/)
+		end
+	end
+
+	# Provides a backwards-compatible constant alias for older code paths.
+	Paths = Files
+end