coradoc 2.0.21 → 2.0.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4ebd4f989cb1c3bc9c6adcede592e91c6013a29bf94c3d12319e03c5c42ab38
-  data.tar.gz: d321f36297bb31aac76fe30a6195aa9cd1456c840dfb1888405c0e36f474c4b7
+  metadata.gz: a33595a0aa6205f5a5d1adabd8ede0dc8f3d4237c2376a910800822400af2f59
+  data.tar.gz: ecb898a27a6cb1540b553fdb3aa97bef73077a85a13175099738fefe3307faf2
 SHA512:
-  metadata.gz: 1bba8d765b1af164d1713f16013eddbdbc906340f37d1918777fd3ec1c6f1ec784e869155ccae100b6d4a4306bea003c4031fbf6276890608471a97d5a407bd2
-  data.tar.gz: e76a4e152ebbc25ee03732c6870fbfbdf062d8a3e0af8423b4da9486d14483952a56a3af6b25c256a6350e60e475afa89112e25931b08b47209884ceb1e8089a
+  metadata.gz: db01c4272054b9f2907ba0af6444e741c6d3151bf916f22aeb11dc25380ea7b0a9d63f88ba2fe2eeacd07bfcf08e50a30b8eeac914605ac394d4bccc9d3d282a
+  data.tar.gz: c40699fd199f0f74a8f657ff7ee26036703e0865862919f2787acd52f532e40c825687cd52c4ef4c4a01337f3819121813f6f291dcd76d264c27bd916f1bc823

data/lib/coradoc/cli.rb

@@ -22,6 +22,16 @@ module Coradoc
     option :section_numbers, desc: 'Enable section numbering', type: :boolean, default: false
     option :section_number_levels, desc: 'Section numbering depth (1-6)', type: :numeric, default: 3
     option :lang, desc: 'Document language code', type: :string, default: 'en'
+    option :resolve_includes, desc: 'Resolve include:: directives inline (default: leave as link nodes)',
+           type: :boolean, default: false
+    option :base_dir, desc: 'Base directory for include resolution (default: dirname of FILE)',
+           type: :string
+    option :missing_include, desc: 'Policy for missing includes: error, warn, silent, passthrough',
+           type: :string, default: 'error'
+    option :max_include_depth, desc: 'Maximum include nesting depth', type: :numeric,
+           default: 64
+    option :allow_unsafe_includes, desc: 'Disable path-traversal protection (asciidoctor :unsafe mode)',
+           type: :boolean, default: false
     def convert(file)
       source_format = resolve_format(file, :from)
       target_format = options[:to] ? Coradoc.normalize_format(options[:to]) : Coradoc.resolve_output_format(options[:output])
@@ -38,8 +48,11 @@ module Coradoc
 
       verbose_log "Converting #{file} (#{source_format}) to #{target_format}"
 
+      doc = Coradoc.parse_file(file, format: source_format)
+      doc = resolve_includes!(doc, file) if options[:resolve_includes]
+
       opts = build_convert_options
-      result = Coradoc.convert_file(file, from: source_format, to: target_format, **opts)
+      result = Coradoc.serialize(doc, to: target_format, **opts)
       write_output(result, options[:output])
     rescue Coradoc::Error => e
       error "Error: #{e.message}"
@@ -215,5 +228,17 @@ module Coradoc
         opts[key] = SYMBOL_OPTIONS.include?(key) ? value.to_sym : value
       end
     end
+
+    def resolve_includes!(doc, source_file)
+      base_dir = options[:base_dir] || File.expand_path(File.dirname(source_file))
+      verbose_log "Resolving includes against #{base_dir}"
+      Coradoc.resolve_includes(
+        doc,
+        base_dir: base_dir,
+        missing_include: options[:missing_include].to_sym,
+        max_depth: options[:max_include_depth],
+        allow_unsafe: options[:allow_unsafe_includes]
+      )
+    end
   end
 end

data/lib/coradoc/coradoc.rb

@@ -86,22 +86,27 @@ module Coradoc
       registry.list
     end
 
-    # Parse text to a document model
+    # Parse text to a document model.
     #
-    # This is the main entry point for parsing documents. It automatically
-    # selects the appropriate parser based on the format.
+    # Graph mode is the only mode: +include::+ directives survive as
+    # +CoreModel::Include+ link nodes pointing at other files. NO file
+    # I/O happens during parse. The result is a single document that
+    # references other documents via Include edges — a text graph.
+    #
+    # To splice included content inline, call +Coradoc.resolve_includes+
+    # on the parsed document. This is an explicit, separate step so the
+    # caller controls when (and whether) file I/O happens.
     #
     # @param text [String] the document text to parse
     # @param format [Symbol] the source format (:asciidoc, :html, :markdown)
     # @return [Coradoc::CoreModel::Base, Object] the parsed document model
     # @raise [UnsupportedFormatError] if the format is not registered
     #
-    # @example Parse AsciiDoc
-    #   doc = Coradoc.parse("= Title\n\nContent", format: :asciidoc)
-    #   doc = Coradoc.parse(File.read("doc.adoc"), format: :asciidoc)
+    # @example Parse — Include directives stay as link nodes
+    #   doc = Coradoc.parse(text, format: :asciidoc)
     #
-    # @example Parse and get CoreModel
-    #   core = Coradoc.parse(text, format: :asciidoc)  # Returns CoreModel
+    # @example Then flatten — splice included files inline
+    #   flat = Coradoc.resolve_includes(doc, base_dir: Dir.pwd)
     def parse(text, format:)
       format_module = get_format(format)
       unless format_module
@@ -115,6 +120,56 @@ module Coradoc
       Hooks.invoke(:after_parse, result, format: format)
     end
 
+    # Resolve +include::+ directives in a parsed document.
+    #
+    # Walks the document tree and replaces every +CoreModel::Include+
+    # link node with the parsed content of its target file, recursing
+    # into the result. The original document is left unchanged; a new
+    # subtree is constructed.
+    #
+    # This is the explicit "flatten" step that turns a text graph into
+    # a single spliced document. Callers control:
+    #   - +base_dir+ — where to root relative include paths
+    #   - +missing_include+ — what to do when a target is missing
+    #   - +max_depth+ — recursion cap
+    #   - +allow_unsafe+ — opt out of path-traversal protection
+    #   - +resolver+ — custom resolution strategy (e.g. HTTP, in-memory)
+    #
+    # @param document [Coradoc::CoreModel::Base] parsed document
+    # @param base_dir [String] base directory for relative include paths
+    # @param missing_include [Symbol] :error (default), :warn, :silent, :passthrough
+    # @param max_depth [Integer] recursion cap (default 64)
+    # @param allow_unsafe [Boolean] disable path-traversal protection
+    # @param resolver [Object, nil] custom resolver. Defaults to
+    #   +Coradoc::IncludeResolver::Filesystem+ rooted at +base_dir+.
+    # @return [Coradoc::CoreModel::Base] new document with includes expanded
+    # @raise [Coradoc::IncludeNotFoundError] when a target is missing
+    #   and policy is :error
+    # @raise [Coradoc::IncludeDepthExceededError] when +max_depth+ is hit
+    # @raise [Coradoc::CircularIncludeError] when an include cycle is detected
+    #
+    # @example
+    #   doc = Coradoc.parse(text, format: :asciidoc)
+    #   flat = Coradoc.resolve_includes(doc, base_dir: Dir.pwd)
+    def resolve_includes(document, base_dir:,
+                         missing_include: :error,
+                         max_depth: Coradoc::ResolveIncludes::DEFAULT_MAX_DEPTH,
+                         allow_unsafe: false,
+                         resolver: nil)
+      resolver = Coradoc::IncludeResolver.coerce(
+        resolver,
+        base_dir: base_dir,
+        allow_unsafe: allow_unsafe
+      )
+      Coradoc::ResolveIncludes.call(
+        document,
+        resolver: resolver,
+        base_dir: base_dir,
+        missing_include: missing_include,
+        max_depth: max_depth
+      )
+    end
+
     # Convert document text from one format to another
     #
     # This is the main entry point for format conversion. It handles the
@@ -459,6 +514,9 @@ module Coradoc
   autoload :DocumentManipulator, "#{__dir__}/document_manipulator"
   autoload :Visitor, "#{__dir__}/visitor"
   autoload :PerformanceRegression, "#{__dir__}/performance_regression"
+  autoload :IncludeResolver, "#{__dir__}/include_resolver"
+  autoload :IncludeSelectors, "#{__dir__}/include_selectors"
+  autoload :ResolveIncludes, "#{__dir__}/resolve_includes"
 end
 
 # Format gems self-register via Coradoc.register_format when they are required.

data/lib/coradoc/core_model/children_content.rb

@@ -11,7 +11,12 @@ module Coradoc
     #   attribute :children, Base, collection: true
     # on each including class. This module overrides the setter to
     # auto-wrap raw strings as TextContent, keeping all callers simple.
+    #
+    # Includes HasChildren so all mixed-content classes also satisfy
+    # the structural predicate (OCP — no subclass enumeration needed
+    # for children-based dispatch).
     module ChildrenContent
+      include HasChildren
       # Override the children= setter to auto-wrap strings as TextContent.
       # This is defined via define_method so it always overrides the
       # lutaml-generated setter, regardless of include order.

data/lib/coradoc/core_model/frontmatter/frontmatter_value.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    class FrontmatterBlock
+      # Single typed value node in a FrontmatterBlock entry tree.
+      #
+      # Replaces the previous `attribute :data, :hash` representation.
+      # Each value carries a `value_type` discriminator plus one populated
+      # slot matching that type. Container types (`array`, `map`) hold
+      # nested FrontmatterValue / FrontmatterEntry children.
+      #
+      # Supported value types (mirror what YAML.safe_load returns given
+      # the Codec's PERMITTED_CLASSES):
+      #
+      #   scalar  -> string, integer, float, boolean, date, datetime, symbol, nil
+      #   container -> array, map
+      #
+      # Adding a new scalar type is purely additive: declare a new typed
+      # slot and extend the case in Codec::ValueBridge (OCP).
+      class FrontmatterValue < Base
+        SCALAR_TYPES = %w[
+          string integer float boolean date datetime symbol nil
+        ].freeze
+        CONTAINER_TYPES = %w[array map].freeze
+        ALL_TYPES = (SCALAR_TYPES + CONTAINER_TYPES).freeze
+
+        attribute :value_type, :string
+
+        # Scalar slots — exactly one populated, selected by value_type.
+        attribute :string_value, :string
+        attribute :integer_value, :integer
+        attribute :float_value, :float
+        attribute :boolean_value, :boolean
+        attribute :date_value, :date
+        attribute :datetime_value, :date_time
+        attribute :symbol_value, :symbol
+
+        # Container slots — populated when value_type is array/map.
+        attribute :items, FrontmatterValue, collection: true
+        attribute :entries, FrontmatterEntry, collection: true
+
+        # Convenience: return the Ruby-native scalar value for this node,
+        # or nil for containers / nil-typed values. Used by callers that
+        # don't care about the type discriminator.
+        def ruby_value
+          case value_type
+          when 'string'   then string_value
+          when 'integer'  then integer_value
+          when 'float'    then float_value
+          when 'boolean'  then boolean_value
+          when 'date'     then date_value
+          when 'datetime' then datetime_value
+          when 'symbol'   then symbol_value
+          when 'nil'      then nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/has_children.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Marker module for "this model exposes a +children+ collection".
+    #
+    # Including this is the canonical way to opt a CoreModel class into
+    # children-based traversal. Downstream code (e.g. mirror's
+    # CoreModelToMirror#element_children) dispatches on +is_a?(HasChildren)+
+    # rather than enumerating subclasses, so adding a new children-bearing
+    # class is purely additive (OCP).
+    #
+    # ChildrenContent (the mixed-content auto-wrap behavior) includes
+    # HasChildren, so every class that mixes in ChildrenContent also
+    # satisfies HasChildren. Classes that carry typed block children
+    # only (StructuralElement, etc.) include HasChildren directly.
+    module HasChildren
+      def has_children?
+        true
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/include.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # First-class include directive node in the canonical document model.
+    #
+    # An include directive is a LINK from one document to another file.
+    # Parsing preserves these nodes verbatim — no file I/O happens during
+    # parse. The result is a text graph: a document referencing other
+    # documents via Include edges.
+    #
+    # Splicing the linked content inline is an explicit, separate step:
+    # +Coradoc.resolve_includes(doc, base_dir:)+ walks the tree and
+    # replaces each Include node with the parsed content of its target,
+    # recursing into the result.
+    #
+    # This separation lets callers:
+    #   - inspect the graph before deciding to flatten
+    #   - resolve with different base dirs / resolvers without re-parsing
+    #   - treat includes as external links (e.g. when parsing a site)
+    #
+    # Attributes:
+    #   target       String           path or URL as authored
+    #   options      IncludeOptions   parsed selectors (tags/lines/leveloffset/indent/encoding)
+    #   raw_options  String           original bracket body, preserved for verbatim round-trip
+    #   line_break   String           trailing line break, default "\n"
+    #
+    # The node is block-level: it appears in the +content+ / +children+
+    # array of any block container (Document, Section, Paragraph, List
+    # item, Table cell, etc.) alongside other block-level nodes.
+    class Include < Base
+      attribute :target, :string
+      attribute :options, Coradoc::CoreModel::IncludeOptions,
+                default: -> { Coradoc::CoreModel::IncludeOptions.new }
+      attribute :raw_options, :string, default: -> { '' }
+      attribute :line_break, :string, default: -> { "\n" }
+
+      def self.semantic_type
+        :include
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/include_level_offset.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # A leveloffset value parsed from an include directive.
+    #
+    # asciidoctor supports two forms:
+    #   leveloffset=+N   → relative shift (heading.level += N)
+    #   leveloffset=-N   → relative shift (heading.level -= N)
+    #   leveloffset=N    → absolute set (heading.level = N)
+    #
+    # The parsed form keeps the mode and delta separate so that the
+    # selector that applies the offset does not need to re-parse the
+    # string each time it walks a section (DRY).
+    class IncludeLevelOffset < Base
+      # "relative" (+N/-N) or "absolute" (bare N).
+      attribute :mode, :string
+
+      # Signed integer for relative shifts; the absolute target level
+      # for absolute mode.
+      attribute :delta, :integer
+
+      # Construct from a raw asciidoctor-style string ("+2", "-1", "3").
+      # Returns nil if the input is nil or unparsable.
+      #
+      # @param raw [String, nil]
+      # @return [IncludeLevelOffset, nil]
+      def self.parse(raw)
+        return nil if raw.nil? || raw.strip.empty?
+
+        matched_offset(raw.strip)
+      end
+
+      # Apply this offset to a heading level (1-indexed asciidoctor level).
+      #
+      # @param level [Integer] original section level
+      # @return [Integer] new section level, clamped to >= 0
+      def apply(level)
+        case mode
+        when 'relative' then [level + delta, 0].max
+        when 'absolute' then [delta, 0].max
+        else level
+        end
+      end
+
+      # Render back to the asciidoctor wire form ("+2", "-1", "3").
+      #
+      # @return [String]
+      def to_s
+        case mode
+        when 'relative' then format('%+d', delta)
+        when 'absolute' then delta.to_s
+        else ''
+        end
+      end
+
+      class << self
+        private
+
+        def matched_offset(trimmed)
+          %r{\A(?<sign>[+-]?)(?<digits>\d+)\z}.match(trimmed) do |m|
+            digits = m[:digits].to_i
+            signed = m[:sign] == '-' ? -digits : digits
+            mode = m[:sign].empty? ? 'absolute' : 'relative'
+            new(mode: mode, delta: signed)
+          end
+        end
+      end
+    end
+  end
+end

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/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

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"
@@ -78,5 +79,8 @@ 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"
   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