coradoc 2.0.21 → 2.0.23

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/link_rewriter/identity.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module LinkRewriter
+    # Default no-op rewriter. Returns every target unchanged. Used when
+    # the caller only wants the visitor's immutable-copy guarantee.
+    class Identity
+      def call(target:, **)
+        target
+      end
+    end
+  end
+end

data/lib/coradoc/link_rewriter/visitor.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module LinkRewriter
+    # Focused rewriting visitor for the CoreModel tree.
+    #
+    # The set of node types that carry link/xref targets is closed and
+    # small: +LinkElement+, +CrossReferenceElement+, plus generic
+    # +InlineElement+ instances whose +format_type+ is +'link'+ or
+    # +'xref'+. That classification is owned polymorphically by
+    # +InlineElement#link_kind+ — the visitor just calls it. Adding a
+    # new link-bearing subclass means overriding +link_kind+ on it,
+    # not editing a case/when here (OCP).
+    #
+    # Verbatim block types are also closed: +SourceBlock+, +ListingBlock+,
+    # +LiteralBlock+, +PassBlock+, +StemBlock+. The visitor returns them
+    # unchanged so the rewriter never sees link-shaped text that is, in
+    # fact, raw code/math.
+    #
+    # Dispatch is class-based (no +respond_to?+ duck-typing). Unrecognized
+    # classes are returned unchanged — the visitor is closed by design.
+    class Visitor
+      # Verbatim block classes — content is raw, no link semantics.
+      VERBATIM_TYPES = [
+        Coradoc::CoreModel::SourceBlock,
+        Coradoc::CoreModel::ListingBlock,
+        Coradoc::CoreModel::LiteralBlock,
+        Coradoc::CoreModel::PassBlock,
+        Coradoc::CoreModel::StemBlock
+      ].freeze
+
+      # Structural/container classes that own a child collection. Each
+      # entry maps the class to the reader method that exposes its
+      # children. MECE — every "recurse into the children" case lands
+      # in this table. Exposed as a public constant so spec helpers
+      # and other visitors can mirror the same paths without restating
+      # the dispatch (DRY).
+      CONTAINER_TYPES = {
+        Coradoc::CoreModel::DocumentElement => :children,
+        Coradoc::CoreModel::SectionElement => :children,
+        Coradoc::CoreModel::PreambleElement => :children,
+        Coradoc::CoreModel::HeaderElement => :children,
+        Coradoc::CoreModel::Block => :children,
+        Coradoc::CoreModel::ListBlock => :items,
+        Coradoc::CoreModel::ListItem => :children,
+        Coradoc::CoreModel::Table => :rows,
+        Coradoc::CoreModel::TableRow => :cells,
+        Coradoc::CoreModel::TableCell => :children,
+        Coradoc::CoreModel::DefinitionList => :items,
+        Coradoc::CoreModel::Toc => :entries,
+        Coradoc::CoreModel::Bibliography => :entries,
+        Coradoc::CoreModel::AnnotationBlock => :children
+      }.freeze
+
+      def initialize(rewriter)
+        @rewriter = rewriter
+      end
+
+      # Entry point. Always returns a NEW root node — even Identity
+      # callers can rely on object identity to confirm the rewrite ran.
+      def visit_document(document)
+        return document unless document.is_a?(Coradoc::CoreModel::Base)
+
+        result = visit_subtree(document)
+        result.equal?(document) ? document.dup : result
+      end
+
+      private
+
+      def visit_subtree(node)
+        return node if VERBATIM_TYPES.any? { |type| node.is_a?(type) }
+        return rewrite_inline(node) if node.is_a?(Coradoc::CoreModel::InlineElement)
+
+        reader = reader_for(node)
+        return node unless reader
+
+        rewrite_collection(node, reader)
+      end
+
+      # Look up the children-reader method for +node+. Returns nil for
+      # unrecognized classes (no duck-typing — the CONTAINER_TYPES
+      # table is the single source of truth).
+      def reader_for(node)
+        CONTAINER_TYPES.each do |klass, reader|
+          return reader if node.is_a?(klass)
+        end
+        nil
+      end
+
+      def rewrite_collection(node, attr_name)
+        original = node.public_send(attr_name)
+        return node if original.nil? || original.empty?
+
+        rewritten = original.map { |child| visit_subtree(child) }
+        return node if unchanged?(rewritten, original)
+
+        rebuild_with(node, attr_name => rewritten)
+      end
+
+      # Inline dispatch. Typed LinkElement / CrossReferenceElement are
+      # always candidates; generic InlineElement instances must declare a
+      # matching format_type. Other typed subclasses (Bold, Italic, …)
+      # are walked for nested inlines instead of being rewritten.
+      def rewrite_inline(inline)
+        kind = inline.link_kind
+
+        rewritten_target = rewrite_target(inline, kind)
+        rewritten_nested = rewrite_nested(inline)
+
+        return inline if rewritten_target.nil? && rewritten_nested.nil?
+
+        overrides = {}
+        overrides[:target] = rewritten_target unless rewritten_target.nil?
+        overrides[:nested_elements] = rewritten_nested unless rewritten_nested.nil?
+        rebuild_with(inline, overrides)
+      end
+
+      def rewrite_target(inline, kind)
+        return nil unless kind
+
+        target = inline.target
+        return nil if target.nil? || target.empty?
+
+        new_target = @rewriter.call(
+          target: target,
+          kind: kind,
+          context: { in_verbatim: false }
+        )
+        return nil if new_target == target
+
+        new_target
+      end
+
+      def rewrite_nested(inline)
+        nested = inline.nested_elements
+        return nil if nested.nil? || nested.empty?
+
+        rewritten = nested.map { |child| visit_subtree(child) }
+        return nil if unchanged?(rewritten, nested)
+
+        rewritten
+      end
+
+      def rebuild_with(node, overrides)
+        duplicate = node.dup
+        overrides.each { |key, value| duplicate.public_send("#{key}=", value) }
+        duplicate
+      end
+
+      def unchanged?(rewritten, original)
+        return false unless rewritten.length == original.length
+
+        rewritten.each_with_index.all? { |node, i| node.equal?(original[i]) }
+      end
+    end
+  end
+end

data/lib/coradoc/link_rewriter.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Coradoc
+  # Post-parse link/xref rewriting.
+  #
+  # Consumers that need to canonicalize link and xref targets (snake→kebab,
+  # strip +.adoc+, redirect maps, dialect translation) get a single
+  # immutable entry point: +Coradoc.rewrite_links(doc, rewriter:, &)+.
+  # The visitor walks the parsed CoreModel, invokes the supplied rewriter
+  # for every link/xref target, and returns a NEW document. Verbatim
+  # blocks (source, listing, literal, pass, stem) are skipped entirely —
+  # coradoc owns the parse and guarantees those bodies never reach the
+  # rewriter, removing the "track parser state to avoid verbatim bodies"
+  # footgun that plagues regex-based rewriting.
+  #
+  # Two-step API mirrors +Coradoc.resolve_includes+: parse produces the
+  # document, rewrite is a separate explicit step the caller controls.
+  module LinkRewriter
+    autoload :Identity, "#{__dir__}/link_rewriter/identity"
+    autoload :Visitor, "#{__dir__}/link_rewriter/visitor"
+
+    class << self
+      # Rewrite every link/xref target in +doc+.
+      #
+      # +rewriter+ responds to +#call(target:, kind:, context:)+ and returns
+      # the new target String. If a block is given it is used as the
+      # rewriter. Omitting both falls back to {Identity} (no-op) — useful
+      # for "give me a structurally identical copy" cases.
+      #
+      # Returns a NEW document; the input is never mutated.
+      def rewrite(doc, rewriter: nil, &block)
+        callable = rewriter || block || Identity.new
+        Visitor.new(callable).visit_document(doc)
+      end
+    end
+  end
+end

data/lib/coradoc/relative_path.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Coradoc
+  # Pure-function module for relative-path arithmetic across output keys.
+  #
+  # Every SSG wrapper (VitePress, Hugo, Astro) needs to compute "how many
+  # directories up do I walk to reach the site root from this output?".
+  # The answer is the segment count of the source output_key. Everything
+  # else (template, imports) is host-system-specific; this module owns
+  # only the one piece of arithmetic that is genuinely shared.
+  #
+  # No state. No class. No knowledge of any specific SSG.
+  #
+  # @example Compute a VitePress import path
+  #   Coradoc::RelativePath.from("author/iso/ref/foo", to: ".vitepress/theme")
+  #   # => "../../../.vitepress/theme"
+  module RelativePath
+    module_function
+
+    # Compute a relative path from an output_key to a site-root-relative
+    # target.
+    #
+    # @param output_key [String, nil] site-relative key for the source
+    #   page (e.g. "author/iso/ref/foo"). No leading slash, no extension.
+    # @param to [String] destination path relative to the site root.
+    # @return [String] the composed relative path.
+    def from(output_key, to:)
+      depth = output_key.to_s.count('/')
+      ('../' * depth) + to.to_s
+    end
+  end
+end