cov-loupe 3.0.0 → 4.0.0.pre

data/lib/cov_loupe/option_parsers/error_helper.rb

@@ -1,21 +1,22 @@
 # frozen_string_literal: true
 
+require_relative '../output_chars'
+
 module CovLoupe
   module OptionParsers
     class ErrorHelper
-      SUBCOMMANDS = %w[list summary raw uncovered detailed totals version].freeze
-
-      def initialize(subcommands = SUBCOMMANDS)
+      def initialize(subcommands)
         @subcommands = subcommands
       end
 
-      def handle_option_parser_error(error, argv: [], usage_hint: "Run '#{program_name} --help' for usage information.")
-        message = error.message.to_s
+      def handle_option_parser_error(error, argv: [], output_chars: :default,
+        usage_hint: "Run '#{program_name} --help' for usage information.")
+        message = convert_text(error.message.to_s, output_chars)
         # Suggest a subcommand when an invalid option matches a known subcommand
         option = extract_invalid_option(message)
 
         if option&.start_with?('--') && @subcommands.include?(option[2..])
-          suggest_subcommand(option)
+          suggest_subcommand(option, output_chars)
         else
           # Generic message from OptionParser
           warn "Error: #{message}"
@@ -34,10 +35,16 @@ module CovLoupe
         nil
       end
 
-      private def suggest_subcommand(option)
+      private def suggest_subcommand(option, output_chars)
         subcommand = option[2..]
-        warn "Error: '#{option}' is not a valid option. Did you mean the '#{subcommand}' subcommand?"
-        warn "Try: #{program_name} #{subcommand} [args]"
+        msg1 = convert_text("Error: '#{option}' is not a valid option. Did you mean the '#{subcommand}' subcommand?", output_chars)
+        msg2 = convert_text("Try: #{program_name} #{subcommand} [args]", output_chars)
+        warn msg1
+        warn msg2
+      end
+
+      private def convert_text(text, output_chars)
+        OutputChars.convert(text, output_chars)
       end
 
       private def build_enum_value_hint(argv)
@@ -92,7 +99,6 @@ module CovLoupe
 
       private def enumerated_option_rules
         [
-          { switches: ['-S', '--staleness'], values: %w[off o error e], display: 'o[ff]|e[rror]' },
           { switches: ['-s', '--source'], values: %w[full f uncovered u],
             display: 'f[ull]|u[ncovered]' },
           { switches: ['--error-mode'], values: %w[off o log l debug d],

data/lib/cov_loupe/output_chars.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+module CovLoupe
+  # Central module for controlling ASCII vs Unicode (fancy) output.
+  #
+  # This module provides:
+  # - Mode resolution (:default -> :fancy or :ascii based on output encoding)
+  # - Character sets for table borders (Unicode box-drawing vs ASCII)
+  # - Text conversion for ensuring ASCII-only output when needed
+  #
+  # Usage:
+  #   mode = OutputChars.resolve_mode(:default)  # => :fancy or :ascii
+  #   charset = OutputChars.charset_for(mode)    # => hash of border chars
+  #   text = OutputChars.convert("café", mode)   # => "caf?" in :ascii mode
+  module OutputChars
+    # Valid output character modes
+    MODES = %i[default fancy ascii].freeze
+
+    # Unicode box-drawing characters (fancy mode)
+    UNICODE_CHARSET = {
+      top_left: "\u250C",
+      top_right: "\u2510",
+      bottom_left: "\u2514",
+      bottom_right: "\u2518",
+      horizontal: "\u2500",
+      vertical: "\u2502",
+      top_tee: "\u252C",
+      bottom_tee: "\u2534",
+      left_tee: "\u251C",
+      right_tee: "\u2524",
+      cross: "\u253C"
+    }.freeze
+
+    # ASCII characters for table borders (ascii mode)
+    ASCII_CHARSET = {
+      top_left: '+',
+      top_right: '+',
+      bottom_left: '+',
+      bottom_right: '+',
+      horizontal: '-',
+      vertical: '|',
+      top_tee: '+',
+      bottom_tee: '+',
+      left_tee: '+',
+      right_tee: '+',
+      cross: '+'
+    }.freeze
+
+    class << self
+      # Resolves :default mode to :fancy or :ascii based on output encoding.
+      #
+      # @param mode [Symbol] One of :default, :fancy, or :ascii
+      # @param io [IO] The output stream to check encoding for (default: $stdout)
+      # @return [Symbol] :fancy or :ascii
+      def resolve_mode(mode, io: $stdout)
+        case mode
+        when :fancy then :fancy
+        when :ascii then :ascii
+        when :default then default_mode_for(io)
+        else
+          raise ArgumentError, "Invalid output_chars mode: #{mode.inspect}"
+        end
+      end
+
+      # Returns the character set hash for the given mode.
+      #
+      # @param mode [Symbol] :fancy or :ascii (use resolve_mode first if :default)
+      # @return [Hash] Character set with keys like :top_left, :horizontal, etc.
+      def charset_for(mode)
+        case mode
+        when :fancy then UNICODE_CHARSET
+        when :ascii then ASCII_CHARSET
+        when :default then charset_for(resolve_mode(:default))
+        else
+          raise ArgumentError, "Invalid output_chars mode: #{mode.inspect}"
+        end
+      end
+
+      # Converts text to ASCII-only when in :ascii mode.
+      # In :fancy mode, returns text unchanged.
+      #
+      # @param text [String] The text to convert
+      # @param mode [Symbol] :fancy, :ascii, or :default
+      # @param io [IO] The output stream for resolving :default (default: $stdout)
+      # @return [String] Original text (:fancy) or ASCII-only text (:ascii)
+      def convert(text, mode, io: $stdout)
+        return text if text.nil?
+
+        resolved = mode == :default ? resolve_mode(mode, io: io) : mode
+        return text if resolved == :fancy
+
+        to_ascii(text)
+      end
+
+      # Checks if output should be ASCII-only for the given mode.
+      #
+      # @param mode [Symbol] :fancy, :ascii, or :default
+      # @param io [IO] The output stream for resolving :default (default: $stdout)
+      # @return [Boolean] true if ASCII-only output is required
+      def ascii_mode?(mode, io: $stdout)
+        resolved = mode == :default ? resolve_mode(mode, io: io) : mode
+        resolved == :ascii
+      end
+
+      private def default_mode_for(io)
+        encoding = io.respond_to?(:external_encoding) ? io.external_encoding : nil
+        encoding ||= Encoding.default_external
+
+        utf8_compatible?(encoding) ? :fancy : :ascii
+      end
+
+      # Checks if the encoding is UTF-8 compatible.
+      #
+      # @param encoding [Encoding, nil] The encoding to check
+      # @return [Boolean] true if UTF-8 compatible
+      private def utf8_compatible?(encoding)
+        return false if encoding.nil?
+
+        encoding_name = encoding.name.upcase
+        encoding_name.include?('UTF-8') || encoding_name == 'UTF8'
+      end
+
+      # Converts a string to ASCII-only, replacing non-ASCII characters.
+      #
+      # Uses transliteration for common characters where sensible,
+      # falls back to '?' for others. This is a best-effort conversion
+      # that prioritizes readability over exactness.
+      #
+      # @param text [String] The text to convert
+      # @return [String] ASCII-only text
+      private def to_ascii(text)
+        text.each_char.map do |char|
+          if char.ord < 128
+            char
+          else
+            transliterate(char)
+          end
+        end.join
+      end
+
+      # Transliterates a single non-ASCII character to ASCII.
+      #
+      # @param char [String] Single character to transliterate
+      # @return [String] ASCII replacement (may be multiple characters)
+      private def transliterate(char)
+        # Common transliterations for readability
+        TRANSLITERATIONS[char] || '?'
+      end
+      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/MethodLength
+    end
+
+    # Common character transliterations to ASCII.
+    # This covers common accented characters and symbols users might encounter.
+    # Box-drawing characters are not included here; they're handled by charset_for.
+    TRANSLITERATIONS = {
+      # Accented vowels
+      'á' => 'a', 'à' => 'a', 'â' => 'a', 'ä' => 'a', 'ã' => 'a', 'å' => 'a',
+      'Á' => 'A', 'À' => 'A', 'Â' => 'A', 'Ä' => 'A', 'Ã' => 'A', 'Å' => 'A',
+      'é' => 'e', 'è' => 'e', 'ê' => 'e', 'ë' => 'e',
+      'É' => 'E', 'È' => 'E', 'Ê' => 'E', 'Ë' => 'E',
+      'í' => 'i', 'ì' => 'i', 'î' => 'i', 'ï' => 'i',
+      'Í' => 'I', 'Ì' => 'I', 'Î' => 'I', 'Ï' => 'I',
+      'ó' => 'o', 'ò' => 'o', 'ô' => 'o', 'ö' => 'o', 'õ' => 'o', 'ø' => 'o',
+      'Ó' => 'O', 'Ò' => 'O', 'Ô' => 'O', 'Ö' => 'O', 'Õ' => 'O', 'Ø' => 'O',
+      'ú' => 'u', 'ù' => 'u', 'û' => 'u', 'ü' => 'u',
+      'Ú' => 'U', 'Ù' => 'U', 'Û' => 'U', 'Ü' => 'U',
+      # Other common characters
+      'ñ' => 'n', 'Ñ' => 'N',
+      'ç' => 'c', 'Ç' => 'C',
+      'ß' => 'ss',
+      'æ' => 'ae', 'Æ' => 'AE',
+      'œ' => 'oe', 'Œ' => 'OE',
+      # Common symbols
+      "\u20AC" => 'EUR', "\u00A3" => 'GBP', "\u00A5" => 'JPY',
+      "\u00A9" => '(c)', "\u00AE" => '(R)', "\u2122" => '(TM)',
+      "\u00B0" => 'deg',
+      "\u2026" => '...',
+      "\u2018" => "'", "\u2019" => "'", "\u201C" => '"', "\u201D" => '"',
+      "\u2013" => '-', "\u2014" => '--',
+      "\u00D7" => 'x', "\u00F7" => '/',
+      "\u2264" => '<=', "\u2265" => '>=', "\u2260" => '!=',
+      "\u2192" => '->', "\u2190" => '<-', "\u2194" => '<->',
+      "\u2713" => '[x]', "\u2717" => '[ ]', "\u2714" => '[x]', "\u2718" => '[ ]',
+      # Bullets and list markers
+      "\u2022" => '*', "\u25E6" => 'o', "\u25AA" => '-', "\u25B8" => '>',
+      # Box-drawing (for any stray usage outside tables)
+      "\u250C" => '+', "\u2510" => '+', "\u2514" => '+', "\u2518" => '+',
+      "\u2500" => '-', "\u2502" => '|',
+      "\u252C" => '+', "\u2534" => '+', "\u251C" => '+', "\u2524" => '+', "\u253C" => '+'
+    }.freeze
+  end
+end

data/lib/cov_loupe/paths/glob_utils.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require_relative 'path_utils'
+
+module CovLoupe
+  module GlobUtils
+    GLOB_MATCH_FLAGS = File::FNM_PATHNAME | File::FNM_EXTGLOB
+
+    # Returns a lambda that normalizes path separators for the current platform.
+    # On Windows, returns a lambda that converts backslashes to forward slashes.
+    # On Unix, returns a pass-through lambda.
+    # The lambda is memoized so platform detection only happens once.
+    # @return [Proc] lambda that takes a string and returns it normalized
+    module_function def fn_normalize_path_separators
+      @fn_normalize_path_separators ||= if CovLoupe.windows?
+        ->(str) { str.tr('\\', '/') }
+      else
+        ->(str) { str }
+      end
+    end
+
+    module_function def normalize_patterns(globs)
+      Array(globs).compact.map(&:to_s).reject(&:empty?)
+    end
+
+    # Converts a pattern to absolute path relative to a root.
+    # Handles both relative patterns ("lib/*.rb") and absolute ones ("/tmp/*.rb").
+    #
+    # @param pattern [String] glob pattern
+    # @param root [String] root directory path
+    # @return [String] absolute pattern
+    module_function def absolutize_pattern(pattern, root)
+      File.expand_path(pattern, root)
+    end
+
+    # Tests if a file path matches any of the given absolute glob patterns.
+    # Uses File.fnmatch? for pure string matching without filesystem access.
+    # Normalizes paths to forward slashes on Windows for cross-platform compatibility.
+    # Automatically handles case-insensitive filesystems by detecting volume case-sensitivity.
+    #
+    # @param abs_path [String] absolute file path to test
+    # @param patterns [Array<String>] absolute glob patterns
+    # @return [Boolean] true if the path matches at least one pattern
+    module_function def matches_any_pattern?(abs_path, patterns)
+      normalizer = fn_normalize_path_separators
+      normalized_path = normalizer.call(abs_path)
+
+      # Determine match flags based on volume case-sensitivity
+      # Find first existing parent directory to test volume properties
+      test_dir = abs_path
+      until File.directory?(test_dir)
+        parent = File.dirname(test_dir)
+        break if parent == test_dir # Reached root (works on Windows and Unix)
+
+        test_dir = parent
+      end
+
+      flags = GLOB_MATCH_FLAGS
+      begin
+        # Add case-insensitive matching for case-insensitive volumes
+        flags |= File::FNM_CASEFOLD unless PathUtils.volume_case_sensitive?(test_dir)
+      rescue SystemCallError, IOError
+        # If we can't detect case sensitivity, assume case-insensitive to be conservative
+        flags |= File::FNM_CASEFOLD
+      end
+
+      patterns.any? do |pattern|
+        normalized_pattern = normalizer.call(pattern)
+        File.fnmatch?(normalized_pattern, normalized_path, flags)
+      end
+    end
+
+    # Filters items where a key contains a file path matching the patterns.
+    #
+    # @param items [Array<Hash>] items to filter
+    # @param patterns [Array<String>] absolute glob patterns
+    # @param key [String] key in item hash containing the absolute file path
+    # @return [Array<Hash>] items whose file path matches at least one pattern
+    module_function def filter_by_pattern(items, patterns, key: 'file')
+      return items if patterns.nil? || patterns.empty?
+
+      items.select { |item| matches_any_pattern?(item[key], patterns) }
+    end
+
+    # Filters an array of absolute file paths by glob patterns.
+    # Handles normalization and absolutization of patterns internally.
+    #
+    # @param paths [Array<String>] absolute file paths to filter
+    # @param globs [Array<String>, String, nil] glob patterns (can be relative)
+    # @param root [String] root directory for resolving relative patterns
+    # @return [Array<String>] paths that match at least one pattern (or all if no patterns)
+    module_function def filter_paths(paths, globs, root:)
+      patterns = normalize_patterns(globs)
+      return paths if patterns.empty?
+
+      absolute_patterns = patterns.map { |p| absolutize_pattern(p, root) }
+      paths.select { |path| matches_any_pattern?(path, absolute_patterns) }
+    end
+  end
+end

data/lib/cov_loupe/{path_relativizer.rb → paths/path_relativizer.rb}

@@ -1,13 +1,14 @@
 # frozen_string_literal: true
 
 require 'pathname'
+require_relative 'path_utils'
 
 module CovLoupe
   # Utility object that converts configured path-bearing keys to forms
-  # relative to the project root while leaving the original payload untouched.
+  # relative to a project root while leaving the original payload untouched.
   class PathRelativizer
     def initialize(root:, scalar_keys:, array_keys: [])
-      @root = Pathname.new(File.absolute_path(root || '.'))
+      @root = Pathname.new(PathUtils.expand(root || '.'))
       @scalar_keys = Array(scalar_keys).map(&:to_s).freeze
       @array_keys = Array(array_keys).map(&:to_s).freeze
     end
@@ -22,13 +23,8 @@ module CovLoupe
     # @param path [String] file path (absolute or relative)
     # @return [String] relative path or original path on failure
     def relativize_path(path)
-      root_str = @root.to_s
-      abs = File.absolute_path(path, root_str)
-      return path unless abs.start_with?(root_prefix(root_str)) || abs == root_str
-
-      Pathname.new(abs).relative_path_from(@root).to_s
-    rescue ArgumentError
-      path
+      # PathUtils handles all the complexity automatically
+      PathUtils.relativize(path, @root.to_s)
     end
 
     private def deep_copy_and_relativize(obj)
@@ -56,9 +52,5 @@ module CovLoupe
         deep_copy_and_relativize(value)
       end
     end
-
-    private def root_prefix(root_str)
-      root_str.end_with?(File::SEPARATOR) ? root_str : root_str + File::SEPARATOR
-    end
   end
 end

data/lib/cov_loupe/paths/path_utils.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require_relative 'volume_case_sensitivity'
+
+module CovLoupe
+  # Centralized path handling utilities providing consistent normalization,
+  # relativization, and absolutization across all components.
+  module PathUtils
+    # Platform detection - delegates to main CovLoupe module for testability
+    def self.windows?
+      CovLoupe.windows?
+    end
+
+    def self.windows_drive?
+      File.expand_path('.').match?(/^[A-Za-z]:/)
+    end
+
+    # Normalizes a path by handling:
+    # 1. Slash normalization (Windows backslashes -> forward slashes)
+    # 2. Case normalization (case-insensitive volumes)
+    # 3. Path cleaning (removing ., .., redundant separators)
+    #
+    # @param path [String, Pathname] path to normalize
+    # @param options [Hash] normalization options
+    # @option options [Boolean] :normalize_case (true on case-insensitive volumes)
+    # @option options [String] :root (nil) root directory for determining volume case-sensitivity
+    # @return [String] normalized path
+    def self.normalize(path, options = {})
+      return path if path.nil? || path.empty?
+
+      result = path.to_s
+
+      # Always normalize slashes on Windows (Pathname#cleanpath does this anyway)
+      result = result.tr('\\', '/') if windows?
+
+      # Handle case normalization for case-insensitive volumes
+      # If root is provided, derive case-sensitivity from root's volume
+      root = options[:root]
+      begin
+        default_normalize_case = if root
+          !VolumeCaseSensitivity.volume_case_sensitive?(root)
+        else
+          !VolumeCaseSensitivity.volume_case_sensitive?
+        end
+      rescue SystemCallError, IOError
+        # If we can't detect case sensitivity, assume case-insensitive to be conservative
+        default_normalize_case = true
+      end
+      if options.fetch(:normalize_case, default_normalize_case)
+        result = result.downcase
+      end
+
+      # Clean path components
+      Pathname.new(result).cleanpath.to_s
+    end
+
+    # Expands a path to absolute form, optionally relative to a base directory
+    #
+    # @param path [String] path to expand
+    # @param base [String, nil] base directory (defaults to current working directory)
+    # @return [String] absolute path
+    def self.expand(path, base = nil)
+      return path if path.nil? || path.empty?
+
+      # On Windows, only bypass File.expand_path if path already has a drive letter.
+      # Paths like "/foo" are considered absolute by absolute? but need File.expand_path
+      # to acquire the current drive letter (e.g., "C:/foo").
+      if absolute?(path) && (!windows? || path.match?(/^[A-Za-z]:/))
+        # Use Pathname#cleanpath to preserve case on Windows, as File.expand_path
+        # can sometimes canonicalize case for existing files.
+        Pathname.new(path).cleanpath.to_s
+      else
+        base ? File.expand_path(path, base) : File.expand_path(path)
+      end
+    end
+
+    # Converts an absolute path to a path relative to the given root
+    #
+    # @param path [String] absolute path to relativize
+    # @param root [String] root directory for relativization
+    # @return [String] relative path or original path if conversion fails
+    def self.relativize(path, root)
+      return path if path.nil? || path.empty? || root.nil? || root.empty?
+
+      # Only expand relative paths against root; absolute paths expand without base
+      abs_path = absolute?(path) ? expand(path) : expand(path, root)
+      abs_root = expand(root)
+
+      # Check if path is within root using normalized comparison
+      # Derive case-sensitivity from root's volume for accurate cross-volume handling
+      return path unless normalized_start_with?(abs_path, abs_root, root: abs_root)
+
+      # Normalize paths before calling relative_path_from to handle case-insensitive
+      # volumes and mixed separators. This ensures Pathname can correctly compute
+      # the relative path even when the input paths have different casings or separators.
+      # On case-insensitive volumes, normalize case as well so Pathname recognizes them as the same path.
+      # Derive case-sensitivity from root's volume
+      case_sensitive = begin
+        VolumeCaseSensitivity.volume_case_sensitive?(abs_root)
+      rescue SystemCallError, IOError
+        # If we can't detect case sensitivity, assume case-insensitive to be conservative
+        false
+      end
+      normalized_path = normalize(abs_path, normalize_case: !case_sensitive, root: abs_root)
+      normalized_root = normalize(abs_root, normalize_case: !case_sensitive, root: abs_root)
+
+      relative = Pathname.new(normalized_path)
+        .relative_path_from(Pathname.new(normalized_root))
+        .to_s
+
+      # Preserve original casing from abs_path by mapping normalized components back
+      if !case_sensitive && relative != '.'
+        preserve_original_casing(relative, abs_path, abs_root)
+      else
+        relative
+      end
+    rescue ArgumentError
+      # Path is on a different drive or cannot be made relative
+      path
+    end
+
+    # Checks if a path is absolute
+    #
+    # @param path [String] path to check
+    # @return [Boolean] true if path is absolute
+    def self.absolute?(path)
+      return false if path.nil? || path.empty?
+
+      # Check for Windows drive paths (C:/, D:/, etc.)
+      return true if path.match?(/^[A-Za-z]:[\/\\]/)
+
+      Pathname.new(path).absolute?
+    end
+
+    # Checks if a path is relative
+    #
+    # @param path [String] path to check
+    # @return [Boolean] true if path is relative
+    def self.relative?(path)
+      !absolute?(path)
+    end
+
+    # Checks if a path is within a given root directory
+    #
+    # @param path [String] path to check
+    # @param root [String] root directory
+    # @return [Boolean] true if path is within root
+    def self.within_root?(path, root)
+      return false if path.nil? || root.nil?
+
+      abs_path = expand(path)
+      abs_root = expand(root)
+
+      normalized_start_with?(abs_path, abs_root, root: abs_root)
+    end
+
+    # Extracts basename from a path, handling normalization
+    #
+    # @param path [String] path to extract basename from
+    # @param options [Hash] options passed to normalize
+    # @return [String] basename
+    def self.basename(path, options = {})
+      return '' if path.nil? || path.empty?
+
+      normalize(path, options).split('/').last
+    end
+
+    # Joins path components using platform-appropriate separators
+    #
+    # @param components [Array<String>] path components
+    # @return [String] joined path
+    def self.join(*components)
+      File.join(*components)
+    end
+
+    # Detects whether the volume at the given path is case-sensitive.
+    # Delegates to VolumeCaseSensitivity module for implementation.
+    #
+    # @param path [String, nil] directory path to test (defaults to current directory)
+    # @return [Boolean] true if case-sensitive, false if case-insensitive or on error
+    def self.volume_case_sensitive?(path = nil)
+      VolumeCaseSensitivity.volume_case_sensitive?(path)
+    end
+
+    # Clears the volume case sensitivity cache (useful for testing)
+    #
+    # @return [void]
+    def self.clear_volume_case_sensitivity_cache
+      VolumeCaseSensitivity.clear_cache
+    end
+
+    # Returns root path with trailing separator for prefix matching
+    #
+    # @param root [String] root path
+    # @return [String] root with trailing separator
+    def self.root_prefix(root)
+      return '' if root.nil? || root.empty?
+
+      root.end_with?(File::SEPARATOR) ? root : "#{root}#{File::SEPARATOR}"
+    end
+
+    # Preserves original casing from the source path when creating a relative path
+    #
+    # @param relative_path [String] normalized relative path
+    # @param source_path [String] original source path with original casing
+    # @param root_path [String] root path
+    # @return [String] relative path with original casing preserved
+    def self.preserve_original_casing(relative_path, source_path, root_path)
+      # Split paths into components
+      relative_components = relative_path.split('/')
+      source_components = normalize(source_path, normalize_case: false, root: root_path).split('/')
+      root_components = normalize(root_path, normalize_case: false, root: root_path).split('/')
+
+      # Skip root components to get to the relative part
+      relative_start_index = root_components.length
+
+      # Map each normalized component back to its original casing
+      original_components = relative_components.map.with_index do |_component, index|
+        source_index = relative_start_index + index
+        source_components[source_index] || relative_components[index]
+      end
+
+      original_components.join('/')
+    end
+
+    # Checks if a path starts with a prefix using normalized comparison
+    # to handle case-insensitive volumes and mixed separators
+    #
+    # @param path [String] path to check
+    # @param prefix [String] prefix to match against
+    # @param root [String, nil] root directory for determining volume case-sensitivity
+    # @return [Boolean] true if path starts with prefix (after normalization)
+    def self.normalized_start_with?(path, prefix, root: nil)
+      return false if path.nil? || prefix.nil? || prefix.empty?
+
+      # Normalize both paths for comparison (case + separators)
+      # If root is provided, derive case-sensitivity from root's volume
+      case_sensitive = begin
+        if root
+          VolumeCaseSensitivity.volume_case_sensitive?(root)
+        else
+          VolumeCaseSensitivity.volume_case_sensitive?
+        end
+      rescue SystemCallError, IOError
+        # If we can't detect case sensitivity, assume case-insensitive to be conservative
+        false
+      end
+      normalized_path = normalize(path, normalize_case: !case_sensitive, root: root)
+      normalized_prefix = normalize(prefix, normalize_case: !case_sensitive, root: root)
+
+      # Check if normalized path starts with normalized prefix
+      # AND ensure we have proper path boundary (either exact match or followed by separator)
+      return false unless normalized_path.start_with?(normalized_prefix)
+
+      # If exact match, return true
+      return true if normalized_path == normalized_prefix
+
+      # Otherwise, ensure character after prefix is a path separator
+      # (normalize converts all backslashes to forward slashes, so only check for /)
+      prefix_length = normalized_prefix.length
+      normalized_path[prefix_length] == '/'
+    end
+  end
+end