coradoc 2.0.22 → 2.0.24

data/lib/coradoc/format_catalog.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Coradoc
+  # Format registry, detection, and capability introspection. Single
+  # source of truth for "what formats exist and what can they do?",
+  # extracted from the top-level Coradoc façade. Public API on
+  # +Coradoc+ delegates here.
+  module FormatCatalog
+    class << self
+      def registry
+        @registry ||= Registry.new
+      end
+
+      def register_format(format_name, format_module, **options)
+        format_module.extend(FormatModule::Interface) unless format_module.is_a?(FormatModule::Interface)
+        registry.register(format_name, format_module, options)
+        FormatModule.validate!(format_module, format_name)
+      end
+
+      def get_format(format_name)
+        registry.get(format_name)
+      end
+
+      def registered_formats
+        registry.list
+      end
+
+      def detect_format(filename)
+        ext = File.extname(filename).downcase
+        registry.each_key do |name|
+          opts = registry.options_for(name)
+          return name if opts[:extensions]&.include?(ext)
+        end
+        nil
+      end
+
+      def binary_format?(format)
+        opts = registry.options_for(format)
+        opts&.fetch(:binary, false) == true
+      end
+
+      def normalize_format(name)
+        return nil unless name
+
+        key = name.to_s.downcase
+        registry.each_key do |fmt_name|
+          opts = registry.options_for(fmt_name)
+          return fmt_name if opts[:aliases]&.include?(key)
+        end
+        key.to_sym
+      end
+
+      def serialize_format?(format)
+        mod = get_format(format)
+        return false unless mod
+
+        mod.serialize?
+      end
+
+      def parse_format?(format)
+        mod = get_format(format)
+        return false unless mod
+
+        mod.public_methods.include?(:parse_to_core) || mod.public_methods.include?(:parse)
+      end
+
+      def capabilities
+        registered_formats.each_with_object({}) do |name, caps|
+          caps[name] = {
+            parse: parse_format?(name),
+            serialize: serialize_format?(name)
+          }
+        end
+      end
+
+      def resolve_output_format(output_file, default: :html)
+        return default unless output_file
+
+        detect_format(output_file) || default
+      end
+    end
+  end
+end

data/lib/coradoc/introspection/element_counter.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Introspection
+    # Visitor that walks a document and counts each CoreModel node by
+    # its type key. Used by Introspection.count_element_types to back
+    # the +Coradoc.document_stats+ API.
+    #
+    # Typed StructuralElement / Block nodes are counted under their
+    # +element_type+ (semantic identity). Other nodes fall back to a
+    # snake_case rendering of their class name.
+    class ElementCounter < Visitor::Base
+      def initialize
+        @counts = Hash.new(0)
+      end
+
+      attr_reader :counts
+
+      def visit(element)
+        return super(element) unless element.is_a?(CoreModel::Base)
+
+        @counts[type_key_for(element)] += 1
+        super(element)
+      end
+
+      private
+
+      def type_key_for(element)
+        if typed_node?(element) && element.element_type
+          element.element_type
+        else
+          snake_case(element.class.name)
+        end
+      end
+
+      def typed_node?(element)
+        element.is_a?(CoreModel::StructuralElement) || element.is_a?(CoreModel::Block)
+      end
+
+      def snake_case(class_name)
+        class_name.split('::').last
+                  .gsub(/([A-Z])/, '_\1')
+                  .downcase
+                  .sub(/^_/, '')
+      end
+    end
+  end
+end

data/lib/coradoc/introspection.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Coradoc
+  # Document introspection: file metadata, validation, stats. Extracted
+  # from the top-level Coradoc façade so the document-counting visitor
+  # and file-metadata helpers have their own home. Public API on
+  # +Coradoc+ delegates here.
+  module Introspection
+    autoload :ElementCounter, "#{__dir__}/introspection/element_counter"
+
+    class << self
+      def file_info(path)
+        fmt = FormatCatalog.detect_format(path)
+        info = { size: File.size(path), format: fmt }
+        info[:lines] = File.foreach(path).count unless FormatCatalog.binary_format?(fmt)
+        info
+      end
+
+      def validate_file(path, format: nil)
+        doc = Pipeline.parse_file(path, format: format)
+
+        schema = Validation::SchemaGenerator.generate(doc.class)
+        return schema.validate(doc) if schema
+
+        Validation::Result.new
+      end
+
+      def document_stats(doc)
+        stats = {}
+        stats[:title] = doc.title if doc.title
+
+        if doc.is_a?(CoreModel::StructuralElement)
+          stats[:child_count] = count_elements(doc)
+          stats[:element_counts] = count_element_types(doc)
+        end
+
+        stats
+      end
+
+      def describe_element(elem)
+        return elem.to_s unless elem.is_a?(CoreModel::Base)
+
+        type = elem.class.name.split('::').last
+        if elem.title
+          "#{type}: #{elem.title}"
+        elsif elem.is_a?(CoreModel::Block) && elem.content
+          preview = elem.content.to_s[0..50]
+          preview += '...' if elem.content.to_s.length > 50
+          "#{type}: #{preview}"
+        else
+          type
+        end
+      end
+
+      private
+
+      def count_elements(doc)
+        return 0 unless doc.is_a?(CoreModel::StructuralElement)
+
+        doc.children.sum do |child|
+          1 + (child.is_a?(CoreModel::StructuralElement) ? count_elements(child) : 0)
+        end
+      end
+
+      def count_element_types(doc)
+        counter = ElementCounter.new
+        counter.visit(doc)
+        counter.counts.reject { |_, v| v.zero? }
+      end
+    end
+  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/pipeline.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Coradoc
+  # Parse / serialize / convert pipeline. Single source of truth for
+  # the document transformation flow, extracted from the top-level
+  # Coradoc façade so pipeline logic has its own home and its own
+  # spec surface. Public API on +Coradoc+ delegates here.
+  module Pipeline
+    class << self
+      # Parse text to a document model. Graph mode: +include::+
+      # directives survive as +CoreModel::Include+ link nodes — no
+      # file I/O happens during parse. Splicing included content is
+      # a separate, explicit step (see +Coradoc.resolve_includes+).
+      def parse(text, format:)
+        format_module = FormatCatalog.get_format(format)
+        unless format_module
+          raise UnsupportedFormatError,
+                "Format '#{format}' is not registered. " \
+                "Available formats: #{FormatCatalog.registered_formats.join(', ')}"
+        end
+
+        text = Hooks.invoke(:before_parse, text, format: format)
+        result = format_module.parse_to_core(text)
+        Hooks.invoke(:after_parse, result, format: format)
+      end
+
+      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
+
+      def rewrite_links(document, rewriter: nil, &block)
+        Coradoc::LinkRewriter.rewrite(document, rewriter: rewriter, &block)
+      end
+
+      def convert(text, from:, to:, **)
+        core = parse(text, format: from)
+        serialize(core, to: to, **)
+      end
+
+      def to_core(model)
+        return model if model.is_a?(CoreModel::Base)
+
+        FormatCatalog.registry.each_value do |format_module|
+          next unless format_module.handles_model?(model)
+
+          return format_module.to_core(model)
+        end
+
+        raise TransformationError, "No transformer found for #{model.class}"
+      end
+
+      def serialize(model, to:, **)
+        format_module = FormatCatalog.get_format(to)
+        raise UnsupportedFormatError, "Format '#{to}' is not registered" unless format_module
+
+        model = Hooks.invoke(:before_serialize, model, format: to)
+        result = format_module.serialize(model, **)
+        Hooks.invoke(:after_serialize, result, format: to)
+      end
+
+      def build(&block)
+        CoreModel::DocumentElement.build(children: [], &block)
+      end
+
+      def parse_file(path, format: nil)
+        raise FileNotFoundError, path unless File.exist?(path)
+
+        source_format = format || FormatCatalog.detect_format(path)
+        raise UnsupportedFormatError, "Could not detect format for: #{path}" unless source_format
+
+        format_module = FormatCatalog.get_format(source_format)
+        raise UnsupportedFormatError, "Format '#{source_format}' is not registered" unless format_module
+
+        if FormatCatalog.binary_format?(source_format)
+          format_module.parse_to_core(path)
+        else
+          content = File.read(path)
+          content = Hooks.invoke(:before_parse, content, format: source_format)
+          result = format_module.parse_file_to_core(path, content)
+          Hooks.invoke(:after_parse, result, format: source_format)
+        end
+      end
+
+      def convert_file(path, to:, from: nil, **)
+        source_format = from || FormatCatalog.detect_format(path)
+        raise UnsupportedFormatError, "Could not detect format for: #{path}" unless source_format
+
+        core = parse_file(path, format: source_format)
+        serialize(core, to: to, **)
+      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

data/lib/coradoc/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Coradoc
-  VERSION = '2.0.22'
+  VERSION = '2.0.24'
 end

data/lib/coradoc.rb

@@ -20,18 +20,13 @@
 #
 # @example Manipulating documents
 #   doc = Coradoc.parse(text, format: :asciidoc)
-#   html = Coradoc.manipulate(doc)
-#              .transform_text(&:upcase)
-#              .add_toc
-#              .to_html
+#   html = Coradoc.serialize(doc, to: :html)
 #
 # @example Building documents programmatically
-#   doc = Coradoc.build do
-#     title "My Document"
-#     section "Intro" do
-#       paragraph "Hello world"
-#     end
-#   end.to_core
+#   doc = Coradoc.build do |d|
+#     d.title = "My Document"
+#     d.children << Coradoc::CoreModel::ParagraphBlock.new(content: "Hello")
+#   end
 #   Coradoc.serialize(doc, to: :html)
 
 require_relative 'coradoc/coradoc'
@@ -39,8 +34,7 @@ require_relative 'coradoc/version'
 
 module Coradoc
   autoload :CLI, 'coradoc/cli'
-  autoload :DocumentBuilder, 'coradoc/document_builder'
-  autoload :DocumentManipulator, 'coradoc/document_manipulator'
   autoload :Visitor, 'coradoc/visitor'
-  autoload :Serializer, 'coradoc/serializer/registry'
+  autoload :LinkRewriter, 'coradoc/link_rewriter'
+  autoload :RelativePath, 'coradoc/relative_path'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: coradoc
 version: !ruby/object:Gem::Version
-  version: 2.0.22
+  version: 2.0.24
 platform: ruby
 authors:
 - Ribose Inc.
@@ -83,6 +83,7 @@ files:
 - lib/coradoc/core_model/include.rb
 - lib/coradoc/core_model/include_level_offset.rb
 - lib/coradoc/core_model/include_options.rb
+- lib/coradoc/core_model/inline_content.rb
 - lib/coradoc/core_model/inline_element.rb
 - lib/coradoc/core_model/list_block.rb
 - lib/coradoc/core_model/list_item.rb
@@ -90,6 +91,7 @@ files:
 - lib/coradoc/core_model/literal_block.rb
 - lib/coradoc/core_model/metadata.rb
 - lib/coradoc/core_model/open_block.rb
+- lib/coradoc/core_model/output_artifact.rb
 - lib/coradoc/core_model/paragraph_block.rb
 - lib/coradoc/core_model/pass_block.rb
 - lib/coradoc/core_model/quote_block.rb
@@ -97,6 +99,7 @@ files:
 - lib/coradoc/core_model/reviewer_block.rb
 - lib/coradoc/core_model/sidebar_block.rb
 - lib/coradoc/core_model/source_block.rb
+- lib/coradoc/core_model/stem_block.rb
 - lib/coradoc/core_model/structural_element.rb
 - lib/coradoc/core_model/table.rb
 - lib/coradoc/core_model/term.rb
@@ -104,9 +107,9 @@ files:
 - lib/coradoc/core_model/toc.rb
 - lib/coradoc/core_model/toc_generator.rb
 - lib/coradoc/core_model/verse_block.rb
-- lib/coradoc/document_builder.rb
-- lib/coradoc/document_manipulator.rb
+- lib/coradoc/dispatch.rb
 - lib/coradoc/errors.rb
+- lib/coradoc/format_catalog.rb
 - lib/coradoc/format_module.rb
 - lib/coradoc/hooks.rb
 - lib/coradoc/include_resolver.rb
@@ -116,17 +119,18 @@ files:
 - lib/coradoc/include_selectors/level_offset.rb
 - lib/coradoc/include_selectors/lines.rb
 - lib/coradoc/include_selectors/tags.rb
-- lib/coradoc/input.rb
+- lib/coradoc/introspection.rb
+- lib/coradoc/introspection/element_counter.rb
+- lib/coradoc/link_rewriter.rb
+- lib/coradoc/link_rewriter/identity.rb
+- lib/coradoc/link_rewriter/visitor.rb
 - lib/coradoc/logger.rb
-- lib/coradoc/output.rb
 - lib/coradoc/performance_regression.rb
-- lib/coradoc/processor_registry.rb
+- lib/coradoc/pipeline.rb
 - lib/coradoc/query.rb
 - lib/coradoc/registry.rb
+- lib/coradoc/relative_path.rb
 - lib/coradoc/resolve_includes.rb
-- lib/coradoc/serializer/registry.rb
-- lib/coradoc/transform.rb
-- lib/coradoc/transform/base.rb
 - lib/coradoc/validation.rb
 - lib/coradoc/version.rb
 - lib/coradoc/visitor.rb