coradoc 2.0.21 → 2.0.23

data/lib/coradoc/core_model/include_options.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Typed options for an include directive, parsed once at construction.
+    #
+    # Each asciidoctor selector (tags / lines / leveloffset / indent /
+    # encoding) gets one typed attribute. Selectors downstream operate on
+    # the typed form, never re-parsing the raw string (DRY).
+    #
+    #   tags          Array<String>   ["body"], [] when unspecified
+    #   tags_wildcard Boolean         true for tags=*
+    #   tags_inverted Boolean         true for tags=**
+    #   lines_spec    String?         raw "1..2;5;7..8" — parsed by Lines selector
+    #   leveloffset   IncludeLevelOffset?
+    #   indent        Integer?        0 = strip, N = re-indent, nil = passthrough
+    #   file_encoding String?         passed through to resolver for File.read
+    class IncludeOptions < Base
+      attribute :tags, :string, collection: true, default: -> { [] }
+      attribute :tags_wildcard, :boolean, default: -> { false }
+      attribute :tags_inverted, :boolean, default: -> { false }
+      attribute :lines_spec, :string
+      attribute :leveloffset, Coradoc::CoreModel::IncludeLevelOffset
+      attribute :indent, :integer
+      attribute :file_encoding, :string
+
+      # Whether the lines selector is in effect. Tags are ignored when
+      # lines is set — matches asciidoctor precedence (SPEC 3.5).
+      def lines?
+        !lines_spec.nil? && !lines_spec.strip.empty?
+      end
+
+      # Whether any tag selector is in effect.
+      def tags?
+        tags_wildcard || tags_inverted || !tags.empty?
+      end
+
+      # True when both selectors were specified (lines wins).
+      def conflict_resolved_to_lines?
+        lines? && tags?
+      end
+
+      # Build from a flat hash of asciidoctor-style key/value strings.
+      # Whitespace around keys and values is trimmed (SPEC 6.3).
+      #
+      # @param attrs [Hash{String=>String}] e.g. {"tags"=>"a;b", "leveloffset"=>"+2"}
+      # @return [IncludeOptions]
+      def self.from_hash(attrs)
+        new(build_args(attrs))
+      end
+
+      class << self
+        private
+
+        def build_args(attrs)
+          cleaned = clean_keys(attrs)
+          {
+            tags: parse_tags(cleaned['tags']),
+            tags_wildcard: wildcard?(cleaned['tags']),
+            tags_inverted: inverted?(cleaned['tags']),
+            lines_spec: cleaned['lines'],
+            leveloffset: CoreModel::IncludeLevelOffset.parse(cleaned['leveloffset']),
+            indent: parse_integer(cleaned['indent']),
+            file_encoding: cleaned['encoding']
+          }
+        end
+
+        def clean_keys(attrs)
+          attrs.each_with_object({}) do |(k, v), h|
+            h[k.to_s.strip] = v.to_s.strip
+          end
+        end
+
+        def parse_tags(raw)
+          return [] if raw.nil?
+          trimmed = raw.strip
+          return [] if trimmed.empty? || trimmed == '*' || trimmed == '**'
+
+          trimmed.split(';').map(&:strip).reject(&:empty?)
+        end
+
+        def wildcard?(raw)
+          !raw.nil? && raw.strip == '*'
+        end
+
+        def inverted?(raw)
+          !raw.nil? && raw.strip == '**'
+        end
+
+        def parse_integer(raw)
+          return nil if raw.nil? || raw.strip.empty?
+
+          Integer(raw.strip)
+        rescue ArgumentError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/inline_element.rb

@@ -24,6 +24,18 @@ module Coradoc
         self.class.format_type || format_type
       end
 
+      # Polymorphic classification used by LinkRewriter::Visitor. Returns
+      # :link / :xref when this node carries a rewrite-able target, nil
+      # otherwise. Generic InlineElement instances defer to their
+      # resolved format_type; typed subclasses override with a literal.
+      # Keeps the visitor free of class-keyed case/when (OCP).
+      def link_kind
+        case resolve_format_type
+        when 'link' then :link
+        when 'xref' then :xref
+        end
+      end
+
       FORMAT_TYPES = %w[
         bold italic monospace underline strikethrough
         subscript superscript highlight
@@ -99,12 +111,20 @@ module Coradoc
       def self.format_type
         'link'
       end
+
+      def link_kind
+        :link
+      end
     end
 
     class CrossReferenceElement < InlineElement
       def self.format_type
         'xref'
       end
+
+      def link_kind
+        :xref
+      end
     end
 
     class StemElement < InlineElement

data/lib/coradoc/core_model/list_block.rb

@@ -108,6 +108,23 @@ module Coradoc
       #   @return [Array<ListItem>] collection of list items
       attribute :items, ListItem, collection: true
 
+      # -- Fluent construction helpers (paired with Base.build) --
+
+      # Append a new ListItem, built via ListItem.build. The block
+      # (if given) is yielded the new item so callers can chain
+      # +add_text+ / +add_link+ on it inline:
+      #
+      #   ListBlock.build do |ul|
+      #     children.each { |c| ul.add_item { |li| li.add_link(c[:slug], text: c[:title]) } }
+      #   end
+      #
+      # Returns self for chaining at the list level.
+      def add_item(marker: self.marker_type == 'ordered' ? '.' : '*')
+        item = ListItem.build(marker: marker) { |li| yield li if block_given? }
+        self.items = Array(items) + [item]
+        self
+      end
+
       private
 
       # Attributes to compare for semantic equivalence

data/lib/coradoc/core_model/list_item.rb

@@ -109,6 +109,27 @@ module Coradoc
         true
       end
 
+      # -- Fluent construction helpers (paired with Base.build) --
+
+      # Append a plain-text inline to this item's children. Returns
+      # self for chaining. Pairs naturally with ListItem.build:
+      #
+      #   ListItem.build do |li|
+      #     li.add_text("See ")
+      #     li.add_link("foo.adoc", text: "Foo")
+      #   end
+      def add_text(text)
+        self.children = Array(children) + [TextContent.new(text: text)]
+        self
+      end
+
+      # Append a +link:+ inline to this item's children. +text+ becomes
+      # the link's visible label; +target+ is the URL/anchor.
+      def add_link(target, text: nil)
+        self.children = Array(children) + [LinkElement.new(target: target, content: text)]
+        self
+      end
+
       private
 
       # Compare two list blocks for equivalence

data/lib/coradoc/core_model/output_artifact.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Output-side state object for host-system emitters (VitePress, Hugo,
+    # Astro, plain ERB, etc.).
+    #
+    # coradoc's source side has +IncludeResolver::Filesystem+ to resolve
+    # include targets without coupling to a storage layer. The output side
+    # has no analogous state object — until now. +OutputArtifact+ captures
+    # the three pieces of state coradoc genuinely needs to hand to a
+    # downstream emitter:
+    #
+    # - +output_key+ — site-relative key (e.g. "author/iso/ref/foo")
+    # - +frontmatter_block+ — parsed YAML frontmatter (may be empty)
+    # - +core_document+ — the canonical CoreModel document
+    #
+    # The consumer takes these and renders whatever wrapper it needs in
+    # its host system's native template language. coradoc does not know
+    # about VitePress, ERB, or Liquid. Symmetric with the source side:
+    # minimal protocol object, not an engine.
+    #
+    # A mirror-tree document is deliberately NOT bundled here. coradoc
+    # core has no runtime dependency on coradoc-mirror; consumers that
+    # target the mirror JSON pipeline pair an +OutputArtifact+ with a
+    # separately-computed +Coradoc::Mirror.transform(core)+ result.
+    class OutputArtifact < Base
+      # @!attribute output_key
+      #   @return [String, nil] site-relative key with no leading slash
+      #     and no trailing extension. SSGs map this to their URL space.
+      attribute :output_key, :string
+
+      # @!attribute frontmatter_block
+      #   @return [FrontmatterBlock, nil] parsed YAML frontmatter
+      attribute :frontmatter_block, FrontmatterBlock
+
+      # @!attribute core_document
+      #   @return [DocumentElement, nil] canonical CoreModel document
+      attribute :core_document, DocumentElement
+
+      private
+
+      def comparable_attributes
+        %i[output_key frontmatter_block core_document]
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/paragraph_block.rb

@@ -7,6 +7,10 @@ module Coradoc
       def self.semantic_type
         :paragraph
       end
+
+      def whitespace_only?
+        flat_text.strip.empty?
+      end
     end
   end
 end

data/lib/coradoc/core_model/stem_block.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # STEM block — mathematical/scientific content authored in LaTeX,
+    # AsciiMath, or another STEM markup. Carries a +language+ attribute so
+    # downstream renderers know which interpreter to invoke.
+    #
+    # AsciiDoc surface forms:
+    #   [stem]\n++++\nx^2\n++++        # language: "latex" (default)
+    #   [latexmath]\n++++\nx^2\n++++   # language: "latex"
+    #   [asciimath]\n++++\nx^2\n++++   # language: "asciimath"
+    class StemBlock < Block
+      attribute :language, :string, default: -> { 'latex' }
+
+      def self.semantic_type
+        :stem
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/structural_element.rb

@@ -11,6 +11,11 @@ module Coradoc
     # Structural elements can contain other elements (blocks, lists, etc.)
     # and can be nested hierarchically to represent document structure.
     class StructuralElement < Base
+      # StructuralElements carry typed block children (sections, paragraphs,
+      # etc.) rather than mixed inline content, so they don't include
+      # ChildrenContent. HasChildren marks the structural predicate that
+      # downstream traversal dispatches on (OCP).
+      include HasChildren
       # @!attribute level
       #   @return [Integer, nil] hierarchical level (1-6 for sections)
       attribute :level, :integer
@@ -47,6 +52,38 @@ module Coradoc
         false
       end
 
+      # Override in subclasses that carry document-title semantics.
+      # HeaderElement at level 0 represents the document title (`= Title`
+      # in AsciiDoc). Consumers that walk the body — TOC builders,
+      # section numbering — skip these so the title is not counted as
+      # "section 1". Polymorphic dispatch (vs. an is_a? guard at the
+      # call site) keeps the predicate open for future subclasses.
+      def document_title?
+        false
+      end
+
+      # Children that count as body content and aren't whitespace-only.
+      # Derived from per-node {#body_content?} and {#whitespace_only?}
+      # predicates — no central walker, no is_a? switch to maintain.
+      def visible_children
+        Array(children).select(&:body_content?).reject(&:whitespace_only?)
+      end
+
+      # True when the body has no visible content anywhere in its subtree.
+      # A document with only frontmatter + comments returns true; a
+      # document with one non-whitespace paragraph returns false.
+      def empty_body?
+        return true if children.nil? || children.empty?
+
+        children.all? do |child|
+          next true unless child.body_content?
+          next true if child.whitespace_only?
+          next child.empty_body? if child.is_a?(StructuralElement)
+
+          false
+        end
+      end
+
       # Derived element_type string for backward compatibility with
       # templates and legacy consumers. Subclasses override this.
       def element_type
@@ -103,6 +140,15 @@ module Coradoc
         true
       end
 
+      # A level-0 HeaderElement represents the document title (the `= Title`
+      # line in AsciiDoc, the `<h1>` in HTML). It is structurally part of
+      # the body but semantically the document's title, not a section —
+      # section numbering, TOC builders, and other section-aware logic
+      # skip these so the title is not counted as "section 1".
+      def document_title?
+        level.to_i.zero?
+      end
+
       def self.element_type_name
         'header'
       end

data/lib/coradoc/core_model/text_content.rb

@@ -17,6 +17,10 @@ module Coradoc
       def to_s
         text.to_s
       end
+
+      def whitespace_only?
+        text.to_s.strip.empty?
+      end
     end
   end
 end

data/lib/coradoc/core_model.rb

@@ -12,6 +12,7 @@ module Coradoc
     # Autoload submodules lazily using relative paths
     autoload :Base, "#{__dir__}/core_model/base"
     autoload :ChildrenContent, "#{__dir__}/core_model/children_content"
+    autoload :HasChildren, "#{__dir__}/core_model/has_children"
     autoload :Callout, "#{__dir__}/core_model/callout"
     autoload :CalloutText, "#{__dir__}/core_model/callout_text"
     autoload :Block, "#{__dir__}/core_model/block"
@@ -69,6 +70,7 @@ module Coradoc
     autoload :SidebarBlock, "#{__dir__}/core_model/sidebar_block"
     autoload :LiteralBlock, "#{__dir__}/core_model/literal_block"
     autoload :PassBlock, "#{__dir__}/core_model/pass_block"
+    autoload :StemBlock, "#{__dir__}/core_model/stem_block"
     autoload :ListingBlock, "#{__dir__}/core_model/listing_block"
     autoload :OpenBlock, "#{__dir__}/core_model/open_block"
     autoload :VerseBlock, "#{__dir__}/core_model/verse_block"
@@ -78,5 +80,9 @@ module Coradoc
     autoload :CommentLine, "#{__dir__}/core_model/comment_line"
     autoload :HorizontalRuleBlock, "#{__dir__}/core_model/horizontal_rule_block"
     autoload :IdGenerator, "#{__dir__}/core_model/id_generator"
+    autoload :Include, "#{__dir__}/core_model/include"
+    autoload :IncludeOptions, "#{__dir__}/core_model/include_options"
+    autoload :IncludeLevelOffset, "#{__dir__}/core_model/include_level_offset"
+    autoload :OutputArtifact, "#{__dir__}/core_model/output_artifact"
   end
 end

data/lib/coradoc/errors.rb

@@ -283,6 +283,62 @@ module Coradoc
     end
   end
 
+  # Error raised when an include directive's target cannot be located.
+  # Honors the +missing_include+ policy: +:error+ raises this; +:warn+,
+  # +:silent+, and +:passthrough+ swallow it.
+  class IncludeNotFoundError < Error
+    attr_reader :target
+
+    def initialize(target)
+      @target = target
+      super("Include target not found: #{target}")
+    end
+  end
+
+  # Error raised when an include chain exceeds the configured depth limit.
+  class IncludeDepthExceededError < Error
+    attr_reader :depth, :target
+
+    def initialize(target:, depth:, max:)
+      @target = target
+      @depth = depth
+      super("Include depth #{depth} exceeds max #{max} at #{target}")
+    end
+  end
+
+  # Error raised when a cycle is detected in the include graph.
+  # The chain is the list of files leading back to the repeated target.
+  class CircularIncludeError < Error
+    attr_reader :chain, :target
+
+    def initialize(target:, chain:)
+      @target = target
+      @chain = chain
+      super("Circular include detected: #{chain.join(' -> ')} -> #{target}")
+    end
+  end
+
+  # Error raised when an include target escapes the resolver's safe base
+  # directory and +allow_unsafe_includes+ is not set.
+  class UnsafeIncludeError < Error
+    attr_reader :target
+
+    def initialize(target)
+      @target = target
+      super("Unsafe include path blocked: #{target}")
+    end
+  end
+
+  # Error raised when an include target exceeds the resolver's size limit.
+  class IncludeTooLargeError < Error
+    attr_reader :target
+
+    def initialize(target)
+      @target = target
+      super("Include target too large to read: #{target}")
+    end
+  end
+
   # Error raised when a requested format is not supported
   #
   # @example

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