coradoc 2.0.20 → 2.0.22

data/lib/coradoc/include_resolver/filesystem.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+module Coradoc
+  class IncludeResolver
+    # Default include resolver: reads files from the local filesystem,
+    # rooted at +base_dir+. Path-traversal protection is ON by default
+    # to match asciidoctor's +:safe+ mode.
+    #
+    # Pass +allow_unsafe: true+ to opt out (matches +:unsafe+ mode).
+    class Filesystem < IncludeResolver
+      attr_reader :base_dir, :allow_unsafe, :max_bytes
+
+      # @param base_dir [String] absolute path to the directory includes
+      #   are resolved against. Usually the directory of the including
+      #   document. Relative paths inside the resolver are expanded
+      #   against this.
+      # @param allow_unsafe [Boolean] when false (default), refuses any
+      #   resolved path that escapes +base_dir+ via .. or that is an
+      #   absolute path outside +base_dir+.
+      # @param max_bytes [Integer, nil] if set, refuses files larger
+      #   than this. Defense against accidental megabyte-include loops.
+      def initialize(base_dir:, allow_unsafe: false, max_bytes: nil)
+        @base_dir = File.expand_path(base_dir)
+        @allow_unsafe = allow_unsafe
+        @max_bytes = max_bytes
+      end
+
+      def call(target:, base_dir:, options:, context:)
+        full = File.expand_path(target, base_dir)
+        enforce_safety!(full, base_dir) unless allow_unsafe
+        raise Coradoc::IncludeNotFoundError, target unless File.file?(full)
+
+        enforce_size!(full, target)
+
+        encoding = options&.file_encoding || 'utf-8'
+        read_with_encoding(full, encoding)
+      end
+
+      private
+
+      def enforce_safety!(full_path, base_dir)
+        base_expanded = File.expand_path(base_dir)
+        base_with_sep = "#{base_expanded}#{File::SEPARATOR}"
+
+        return if full_path == base_expanded || full_path.start_with?(base_with_sep)
+
+        raise Coradoc::UnsafeIncludeError, full_path
+      end
+
+      def enforce_size!(full_path, target)
+        return unless max_bytes
+        return unless File.exist?(full_path)
+
+        size = File.size(full_path)
+        return if size <= max_bytes
+
+        raise Coradoc::IncludeTooLargeError, target
+      end
+
+      def read_with_encoding(full_path, encoding_name)
+        content = File.binread(full_path)
+        return content if encoding_name.to_s.downcase == 'binary'
+
+        content.force_encoding(clean_encoding_name(encoding_name))
+        encoded = content.encode('utf-8', invalid: :replace, undef: :replace)
+        normalize_line_endings(encoded)
+      rescue ArgumentError => e
+        raise Coradoc::Error, "Unsupported encoding #{encoding_name.inspect}: #{e.message}"
+      end
+
+      # asciidoctor parity: normalize CRLF and lone CR to LF so the parser
+      # sees consistent line endings regardless of the source platform.
+      def normalize_line_endings(text)
+        text.gsub(/\r\n?/, "\n")
+      end
+
+      def clean_encoding_name(name)
+        name.to_s.downcase.sub(/^utf-8$/, 'utf-8')
+      end
+    end
+  end
+end

data/lib/coradoc/include_resolver.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Coradoc
+  # Include resolver protocol.
+  #
+  # A resolver is anything that responds to +#call(target:, base_dir:,
+  # options:, context:)+ and returns the raw bytes of the included
+  # target, BEFORE tag/line/indent selectors are applied. Selectors
+  # live in the processor; the resolver only fetches bytes.
+  #
+  # The default resolver is {IncludeResolver::Filesystem}. Custom
+  # resolvers (HTTP, database, generated) plug in here without changes
+  # to the processor (OCP).
+  #
+  # Contract:
+  #   call(target:, base_dir:, options:, context:) -> String
+  #     target   String              path/URL as authored
+  #     base_dir String              absolute path to the including file's dir
+  #     options  CoreModel::IncludeOptions
+  #     context  Hash                recursion state (depth, parent_chain, ...)
+  #
+  #   Raises Coradoc::IncludeNotFoundError if the target cannot be located.
+  #   The processor's missing-file policy decides what to do with that.
+  #
+  # This base class is provided for documentation and for is_a? checks.
+  # Custom resolvers do NOT need to inherit — duck typing on the call
+  # signature is sufficient. ( SPEC 13 uses a bare Object with
+  # define_singleton_method, which we support.)
+  class IncludeResolver
+    autoload :Filesystem, "#{__dir__}/include_resolver/filesystem"
+
+    def call(target:, base_dir:, options:, context:)
+      raise NotImplementedError,
+            "#{self.class} must implement #call(target:, base_dir:, options:, context:)"
+    end
+
+    class << self
+      # Coerce +value+ into something that quacks like an IncludeResolver.
+      # - Already-callable objects (respond to :call) are returned as-is.
+      # - Symbols are interpreted as built-in names: +:filesystem+,
+      #   +:filesystem_strict+ (path-traversal protection on).
+      #
+      # @param value [Object, nil] the resolver or built-in name
+      # @param base_dir [String] required for built-in filesystem resolvers
+      # @param allow_unsafe [Boolean] opt-out of path-traversal protection
+      # @return [Object] something callable as a resolver
+      def coerce(value, base_dir:, allow_unsafe: false)
+        return Filesystem.new(base_dir: base_dir, allow_unsafe: allow_unsafe) if value.nil?
+
+        case value
+        when Symbol then coerce_symbol(value, base_dir: base_dir, allow_unsafe: allow_unsafe)
+        else value
+        end
+      end
+
+      private
+
+      def coerce_symbol(name, base_dir:, allow_unsafe:)
+        case name
+        when :filesystem then Filesystem.new(base_dir: base_dir, allow_unsafe: allow_unsafe)
+        else
+          raise ArgumentError, "Unknown include resolver: #{name.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/include_selectors/indent.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module IncludeSelectors
+    # Indent normalization. Two modes per asciidoctor:
+    #
+    #   indent=0   strip all leading whitespace from every line
+    #   indent=N   normalize leading whitespace to exactly N spaces
+    #   nil        pass through unchanged
+    module Indent
+      # @param text [String]
+      # @param options [Coradoc::CoreModel::IncludeOptions]
+      # @return [String]
+      def self.call(text, options:)
+        return text if options.indent.nil?
+
+        if options.indent.zero?
+          strip_all(text)
+        else
+          reindent(text, options.indent)
+        end
+      end
+
+      class << self
+        private
+
+        def strip_all(text)
+          text.lines.map { |line| line.sub(/\A[[:space:]]+/, '') }.join
+        end
+
+        def reindent(text, target)
+          min_indent = text.lines
+                           .reject { |l| l.strip.empty? }
+                           .map { |l| l.length - l.lstrip.length }
+                           .min || 0
+
+          pad = ' ' * target
+          text.lines.map do |line|
+            stripped = strip_common_prefix(line, min_indent)
+            if stripped.strip.empty?
+              stripped.strip + "\n"
+            else
+              pad + stripped
+            end
+          end.join
+        end
+
+        def strip_common_prefix(line, count)
+          line.sub(/\A[[:space:]]{0,#{count}}/, '')
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/include_selectors/level_offset.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module IncludeSelectors
+    # Shifts section heading levels in a parsed CoreModel subtree.
+    #
+    # Applied AFTER parsing — works on SectionElement instances. Two modes:
+    #
+    #   relative (+N / -N)   every SectionElement#level += delta
+    #   absolute (N)         the FIRST section's level becomes N, and
+    #                         descendants shift by the same delta so their
+    #                         relative structure is preserved (asciidoctor
+    #                         behavior).
+    #
+    # The processor passes a freshly-parsed subtree to this selector, so
+    # there are no external references and in-place mutation is safe.
+    module LevelOffset
+      # @param core [Coradoc::CoreModel::Base] freshly parsed — mutated
+      # @param options [Coradoc::CoreModel::IncludeOptions]
+      # @return [Coradoc::CoreModel::Base] the same core (mutated)
+      def self.call(core, options:)
+        offset = options.leveloffset
+        return core if offset.nil?
+
+        first_level = find_first_level(core)
+        actual_delta = compute_actual_delta(offset, first_level)
+        return core if actual_delta.zero?
+
+        walk_and_shift(core, actual_delta)
+        core
+      end
+
+      class << self
+        private
+
+        def compute_actual_delta(offset, first_level)
+          case offset.mode
+          when 'relative' then offset.delta
+          when 'absolute'
+            return 0 if first_level.nil?
+
+            offset.delta - first_level
+          else 0
+          end
+        end
+
+        def find_first_level(node)
+          case node
+          when Coradoc::CoreModel::SectionElement
+            node.level || 1
+          when Coradoc::CoreModel::StructuralElement, Coradoc::CoreModel::Block
+            walk_for_first_level(node.children)
+          else
+            nil
+          end
+        end
+
+        def walk_for_first_level(children)
+          return nil if children.nil?
+
+          children.each do |child|
+            lvl = find_first_level(child)
+            return lvl unless lvl.nil?
+          end
+          nil
+        end
+
+        def walk_and_shift(node, delta)
+          case node
+          when Coradoc::CoreModel::SectionElement
+            node.level = [(node.level || 1) + delta, 0].max
+            walk_children(node, delta)
+          when Coradoc::CoreModel::StructuralElement, Coradoc::CoreModel::Block
+            walk_children(node, delta)
+          end
+        end
+
+        def walk_children(node, delta)
+          return if node.children.nil?
+
+          node.children.each { |c| walk_and_shift(c, delta) }
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/include_selectors/lines.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module IncludeSelectors
+    # Line-range selection. Parses asciidoctor-style specs:
+    #
+    #   N            single line
+    #   A..B         inclusive range
+    #   A..B;C;D..E  multiple, semicolon-separated
+    #
+    # Out-of-bounds clamps gracefully (SPEC 3.4). One-based indexing
+    # (asciidoctor convention).
+    module Lines
+      SPEC_PART = %r{
+        \A
+        (?<start>\d+)
+        (?:\.\.(?<finish>\d+))?
+        \z
+      }x.freeze
+
+      # @param text [String]
+      # @param options [Coradoc::CoreModel::IncludeOptions]
+      # @return [String]
+      def self.call(text, options:)
+        return text unless options.lines?
+
+        ranges = parse_spec(options.lines_spec, max: text.lines.length)
+        return '' if ranges.empty?
+
+        indices = ranges.flat_map { |start, finish| (start..finish).to_a }.uniq.sort
+        text.lines.values_at(*indices.map { |i| i - 1 }).join
+      end
+
+      class << self
+        private
+
+        def parse_spec(spec, max:)
+          spec.split(';').map(&:strip).filter_map do |part|
+            parse_part(part, max: max)
+          end
+        end
+
+        def parse_part(part, max:)
+          SPEC_PART.match(part) do |m|
+            start = m[:start].to_i
+            finish = m[:finish] ? m[:finish].to_i : start
+            [start, finish].minmax.map { |n| clamp(n, max: max) }
+          end
+        end
+
+        def clamp(n, max:)
+          return nil if n < 1
+          return max if n > max
+
+          n
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/include_selectors/tags.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module IncludeSelectors
+    # Extracts regions delimited by +// tag::name[]+ / +// end::name[]+
+    # markers from included content. Supports single, multiple,
+    # wildcard (*), and inverted (**) selection.
+    #
+    # Tag markers themselves are never emitted as text (SPEC 2.8).
+    # Unknown tag names yield empty content (SPEC 2.6). Nested tag
+    # regions are included when an outer tag is selected (SPEC 2.7).
+    #
+    # Marker forms recognized:
+    #   // tag::name[]      (AsciiDoc line comment)
+    #   ## tag::name[]      (Markdown line comment, permissive)
+    #
+    # Markers may appear on their own line; they must be the first
+    # non-whitespace token on that line (asciidoctor convention).
+    module Tags
+      MARKER_OPEN  = /\A[[:space:]]*(?:\/\/+|#+)[[:space:]]*tag::([^\[\]]+)\[[[:space:]]*\]/
+      MARKER_CLOSE = /\A[[:space:]]*(?:\/\/+|#+)[[:space:]]*end::([^\[\]]+)\[[[:space:]]*\]/
+
+      # @param text [String] raw included file content
+      # @param options [Coradoc::CoreModel::IncludeOptions]
+      # @return [String] filtered content
+      def self.call(text, options:)
+        return text unless options.tags?
+
+        if options.tags_inverted
+          inverted(text)
+        elsif options.tags_wildcard
+          wildcard(text)
+        else
+          named(text, options.tags)
+        end
+      end
+
+      class << self
+        private
+
+        def scan_markers(text)
+          markers = []
+          text.each_line.with_index do |line, idx|
+            if (m = MARKER_OPEN.match(line))
+              markers << [:open, m[1].strip, idx]
+            elsif (m = MARKER_CLOSE.match(line))
+              markers << [:close, m[1].strip, idx]
+            end
+          end
+          markers
+        end
+
+        def named(text, names)
+          wanted_indices = selected_line_indices(text, names).to_set
+          pick_lines(text, wanted_indices)
+        end
+
+        def selected_line_indices(text, wanted_names)
+          markers = scan_markers(text)
+          wanted = wanted_names.to_set
+          open_stack = []
+          emit = {}
+
+          markers.each do |kind, name, idx|
+            case kind
+            when :open
+              next unless wanted.include?(name)
+
+              open_stack.push([name, idx])
+            when :close
+              next unless wanted.include?(name)
+
+              open_idx = open_stack.rindex { |n, _| n == name }
+              next unless open_idx
+
+              _open_name, open_line = open_stack.delete_at(open_idx)
+              (open_line + 1...idx).each { |i| emit[i] = true }
+            end
+          end
+
+          emit.keys
+        end
+
+        def wildcard(text)
+          markers = scan_markers(text)
+          open_stack = []
+          emit = {}
+
+          markers.each do |kind, _name, idx|
+            case kind
+            when :open
+              open_stack.push(idx)
+            when :close
+              next if open_stack.empty?
+
+              open_line = open_stack.pop
+              (open_line + 1...idx).each { |i| emit[i] = true }
+            end
+          end
+
+          pick_lines(text, emit.keys.to_set)
+        end
+
+        def inverted(text)
+          markers = scan_markers(text)
+          open_stack = []
+          excluded = {}
+
+          markers.each do |kind, _name, idx|
+            case kind
+            when :open
+              open_stack.push(idx)
+            when :close
+              next if open_stack.empty?
+
+              open_line = open_stack.pop
+              (open_line..idx).each { |i| excluded[i] = true }
+            end
+          end
+
+          markers.each { |_kind, _name, idx| excluded[idx] = true }
+
+          lines = text.lines
+          kept = lines.each_with_index.reject { |_line, idx| excluded[idx] }
+          kept.map(&:first).join
+        end
+
+        def pick_lines(text, wanted_indices)
+          lines = text.lines
+          lines.each_with_index.select { |_line, idx| wanted_indices.include?(idx) }
+               .map(&:first).join
+        end
+      end
+    end
+  end
+end
+
+require 'set'

data/lib/coradoc/include_selectors.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Coradoc
+  # Pure-function selectors applied to resolved include content.
+  #
+  # Each selector owns exactly one transformation (MECE):
+  #   Tags         // tag::X[] ... // end::X[] region extraction
+  #   Lines        line-range selection (1..N;2;3..4)
+  #   Indent       leading-whitespace normalization
+  #   LevelOffset  section-level shift (applied AFTER parsing)
+  #
+  # Tags, Lines, and Indent take a String and return a String.
+  # LevelOffset takes a parsed CoreModel and returns a new CoreModel.
+  #
+  # The processor orchestrates the order:
+  #   1. Tags   (or Lines; Lines wins if both specified — SPEC 3.5)
+  #   2. Indent
+  #   3. parse → CoreModel
+  #   4. LevelOffset
+  module IncludeSelectors
+    autoload :Tags, "#{__dir__}/include_selectors/tags"
+    autoload :Lines, "#{__dir__}/include_selectors/lines"
+    autoload :Indent, "#{__dir__}/include_selectors/indent"
+    autoload :LevelOffset, "#{__dir__}/include_selectors/level_offset"
+  end
+end

data/lib/coradoc/performance_regression.rb

@@ -23,6 +23,11 @@ module Coradoc
       def passed?
         duration < threshold
       end
+
+      def format_line
+        status = passed? ? 'PASS' : 'FAIL'
+        "  #{status} #{name}: #{duration.round(4)}s (threshold: #{threshold}s)"
+      end
     end
 
     ComparisonResult = Struct.new(:name, :duration, :baseline, keyword_init: true) do
@@ -31,6 +36,12 @@ module Coradoc
 
         (duration - baseline).abs / baseline > pct
       end
+
+      def format_line
+        status = regressed? ? 'WARN' : 'OK'
+        baseline_str = baseline ? "(baseline: #{baseline.round(4)}s)" : '(no baseline)'
+        "  #{status} #{name}: #{duration.round(4)}s #{baseline_str}"
+      end
     end
 
     class << self
@@ -50,14 +61,15 @@ module Coradoc
         { results:, failed_count: failed, total: results.size }
       end
 
-      def print_results(summary)
-        results = summary[:results]
-        results.each do |r|
-          status = r.passed? ? 'PASS' : 'FAIL'
-          puts "  #{status} #{r.name}: #{r.duration.round(4)}s (threshold: #{r.threshold}s)"
+      def print_results(summary_or_results)
+        if summary_or_results.is_a?(Hash)
+          summary = summary_or_results
+          summary[:results].each { |r| puts r.format_line }
+          puts
+          puts "#{summary[:total] - summary[:failed_count]}/#{summary[:total]} passed"
+        else
+          Array(summary_or_results).each { |r| puts r.format_line }
         end
-        puts
-        puts "#{summary[:total] - summary[:failed_count]}/#{summary[:total]} passed"
       end
 
       def compare_with_baseline(baseline_path, iterations: 3)