coradoc 2.0.21 → 2.0.23

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4ebd4f989cb1c3bc9c6adcede592e91c6013a29bf94c3d12319e03c5c42ab38
-  data.tar.gz: d321f36297bb31aac76fe30a6195aa9cd1456c840dfb1888405c0e36f474c4b7
+  metadata.gz: 7370b3dabd4535faf0592e455d0bfd13c582b37941c411a0c4c7b86528843896
+  data.tar.gz: c61e126d88a2dc69c507657201b9b3e7875a7d6beffac957d5b805a81ffcc6d5
 SHA512:
-  metadata.gz: 1bba8d765b1af164d1713f16013eddbdbc906340f37d1918777fd3ec1c6f1ec784e869155ccae100b6d4a4306bea003c4031fbf6276890608471a97d5a407bd2
-  data.tar.gz: e76a4e152ebbc25ee03732c6870fbfbdf062d8a3e0af8423b4da9486d14483952a56a3af6b25c256a6350e60e475afa89112e25931b08b47209884ceb1e8089a
+  metadata.gz: 548b69fbd08a23cabf10e60ed599bafb904c87e857678bd539f820fc824ff2d407761728c10a2c6be2359a40b8d6973211adaf7c41171e7928c83a8816f43360
+  data.tar.gz: 04e7b4f63d935208df375f2ecf979104db5b0b7de9e95b6c04d77939d1a293114f2c285ccea7cc7a7e0709e364d7fe1c58d2038e2b6adc923591421be4d2ade8

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,83 @@ 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
+
+    # Rewrite every link/xref target in a parsed document.
+    #
+    # Walks the document tree and invokes the supplied rewriter for each
+    # link and cross-reference target. The original document is never
+    # mutated — a NEW document is returned.
+    #
+    # Verbatim blocks (+SourceBlock+, +ListingBlock+, +LiteralBlock+,
+    # +PassBlock+, +StemBlock+) are skipped entirely so link-shaped text
+    # inside code/math bodies is never rewritten.
+    #
+    # The rewriter responds to +#call(target:, kind:, context:)+ and
+    # returns the new target String. +kind+ is +:link+ or +:xref+; the
+    # block form is supported for one-liners.
+    #
+    # @param document [Coradoc::CoreModel::Base] parsed document
+    # @param rewriter [#call, nil] callable rewriter; ignored when a block is given
+    # @return [Coradoc::CoreModel::Base] new document with rewritten targets
+    #
+    # @example Canonicalize snake_case targets to kebab-case
+    #   doc = Coradoc.parse(adoc, format: :asciidoc)
+    #   rewritten = Coradoc.rewrite_links(doc) do |target:, kind:, **|
+    #     target.tr('_', '-')
+    #   end
+    def rewrite_links(document, rewriter: nil, &block)
+      Coradoc::LinkRewriter.rewrite(document, rewriter: rewriter, &block)
+    end
+
     # Convert document text from one format to another
     #
     # This is the main entry point for format conversion. It handles the
@@ -459,6 +541,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/base.rb

@@ -41,6 +41,28 @@ module Coradoc
       #   @return [Array<MetadataEntry>] additional metadata entries
       attribute :metadata_entries, MetadataEntry, collection: true
 
+      # Construct an instance and yield it for in-place mutation.
+      #
+      # This is the programmatic-construction entry point for CoreModel
+      # nodes. It calls +new+ exactly as a caller would, then yields
+      # the resulting instance for append-style construction. No new
+      # class hierarchy, no +method_missing+ — the block operates on
+      # the real model object.
+      #
+      # Per-class fluent helpers (e.g., +ListBlock#add_item+,
+      # +ListItem#add_text+) compose naturally with +build+:
+      #
+      #   list = ListBlock.build do |ul|
+      #     children.each { |c| ul.add_item { |li| li.add_link(c[:slug], text: c[:title]) } }
+      #   end
+      #
+      # Without a block, +build(**attrs)+ is identical to +new(**attrs)+.
+      def self.build(**attrs)
+        instance = new(**attrs)
+        yield instance if block_given?
+        instance
+      end
+
       # Get all metadata as a hash, or a specific metadata value by key
       # @overload metadata
       #   @return [Hash] All metadata as key-value pairs
@@ -145,6 +167,23 @@ module Coradoc
         visitor.visit(self)
       end
 
+      # True when this node counts as "real body content" for the
+      # purposes of empty-document detection and similar structural
+      # queries. Default is true; metadata and ephemeral nodes
+      # (FrontmatterBlock, CommentBlock, CommentLine) override to
+      # false. Polymorphic dispatch keeps the predicate open for
+      # future "skip-me" types — no central walker to edit (OCP).
+      def body_content?
+        true
+      end
+
+      # True when this node is structurally present but carries no
+      # visible characters. Default is false; inline text and
+      # paragraph blocks override to inspect their text content.
+      def whitespace_only?
+        false
+      end
+
       private
 
       # List of attributes to compare for semantic equivalence

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/comment_block.rb

@@ -7,6 +7,10 @@ module Coradoc
       def self.semantic_type
         :comment
       end
+
+      def body_content?
+        false
+      end
     end
   end
 end

data/lib/coradoc/core_model/comment_line.rb

@@ -13,6 +13,10 @@ module Coradoc
         :comment_line
       end
 
+      def body_content?
+        false
+      end
+
       attribute :text, :string
     end
   end

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

@@ -10,42 +10,89 @@ module Coradoc
       # No other code in any gem may call YAML directly for frontmatter.
       # This isolates permitted-classes configuration and error handling
       # in one MECE location (DRY).
+      #
+      # The Codec emits flat YAML — values rendered with their natural
+      # YAML type. This is what Jekyll, Hugo, VitePress, VuePress, 11ty
+      # and every SSG expects: +title: Foo+ / +date: 2024-01-01+.
+      # Round-trip fidelity for typed values (Date, Time, Symbol) is
+      # preserved by Psych's permitted-classes mechanism, not by a
+      # custom discriminator scheme.
+      #
+      # For the typed-tree representation used by the coradoc-mirror JSON
+      # pipeline, see +Coradoc::Mirror::Node::FrontmatterValue+ and
+      # +Coradoc::Mirror::Handlers::Frontmatter+. The typed-tree concern
+      # lives in the mirror gem; this Codec stays focused on YAML.
       module Codec
         PERMITTED_CLASSES = [Date, Time, DateTime, Symbol].freeze
 
         class << self
-          # Parse a YAML string into a FrontmatterBlock.
-          # Returns an empty FrontmatterBlock on malformed YAML (graceful
-          # degradation — body parsing continues).
+          # Parse YAML text into a FrontmatterBlock. Returns an empty
+          # FrontmatterBlock on malformed YAML or non-Hash payload.
+          # Logs a warning so the conversion pipeline can surface the
+          # skip rather than silently dropping user-authored content.
           def from_yaml(yaml_text)
             return FrontmatterBlock.new if yaml_text.nil? || yaml_text.strip.empty?
 
-            parsed = YAML.safe_load(
-              yaml_text,
-              permitted_classes: PERMITTED_CLASSES,
-              aliases: true
-            )
-            return FrontmatterBlock.new unless parsed.is_a?(Hash)
-
-            schema = parsed['$schema']
-            data = parsed.except('$schema')
-            FrontmatterBlock.new(schema: schema&.to_s, data: data)
-          rescue YAML::SyntaxError, Psych::DisallowedClass
+            build_from_loaded(load_yaml(yaml_text))
+          rescue YAML::SyntaxError, Psych::DisallowedClass => e
+            Coradoc::Logger.warn("frontmatter parse failed: #{e.message}")
             FrontmatterBlock.new
           end
 
+          # Build a FrontmatterBlock from a Ruby hash with native-typed
+          # values (String, Integer, Date, …). Returns an empty block
+          # for non-Hash input.
+          def from_hash(hash)
+            return FrontmatterBlock.new unless hash.is_a?(Hash)
+
+            build_from_loaded(hash)
+          end
+
           # Serialize a FrontmatterBlock to canonical YAML text.
-          # Does NOT include leading/trailing `---` delimiters; the caller
-          # wraps the output.
+          # Does NOT include leading/trailing +---+ delimiters; the
+          # caller wraps the output. Returns +''+ for empty blocks.
           def to_yaml(block)
             return '' unless block.is_a?(FrontmatterBlock)
 
+            payload = flat_tree(block)
+            return '' if payload.empty?
+
+            YAML.dump(payload).delete_prefix("---\n").delete_suffix("\n...")
+          end
+
+          # Return the frontmatter as a native-typed Ruby hash.
+          # +$schema+ is included when present.
+          def to_hash(block)
+            return {} unless block.is_a?(FrontmatterBlock)
+
+            flat_tree(block)
+          end
+
+          private
+
+          def load_yaml(yaml_text)
+            YAML.safe_load(
+              yaml_text,
+              permitted_classes: PERMITTED_CLASSES,
+              aliases: true
+            )
+          end
+
+          def build_from_loaded(loaded)
+            return FrontmatterBlock.new unless loaded.is_a?(Hash)
+
+            schema = loaded['$schema']
+            FrontmatterBlock.new(
+              schema: schema&.to_s,
+              data: loaded.except('$schema')
+            )
+          end
+
+          def flat_tree(block)
             tree = {}
             tree['$schema'] = block.schema if block.schema
             tree.merge!(block.data || {})
-            return '' if tree.empty?
-
-            YAML.dump(tree).delete_prefix("---\n").delete_suffix("\n...")
+            tree
           end
         end
       end

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/frontmatter.rb

@@ -50,6 +50,10 @@ module Coradoc
         schema.nil? && (data.nil? || data.empty?)
       end
 
+      def body_content?
+        false
+      end
+
       # Sub-namespaces (Codec, SchemaResolver, FieldTransform, TextSplitter)
       # live under FrontmatterBlock and autoload lazily.
       autoload :Codec, "#{__dir__}/frontmatter/codec"

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