red_quilt 0.7.2 → 0.9.0

data/lib/red_quilt/code_block.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module RedQuilt
+  # Fenced and indented code blocks (CommonMark 4.4 / 4.5). The module
+  # functions detect a code-block start; the nested Parser builds the arena
+  # node, mirroring the List / Blockquote split (detection used by the
+  # block dispatch, construction by a cached collaborator).
+  module CodeBlock
+    module_function
+
+    # Detects a fenced code opener. Returns a Hash describing the fence
+    # ({ char:, count:, info:, indent: }) or nil.
+    def fenced_start(text)
+      match = /\A( {0,3})(`{3,}|~{3,})[ \t]*(.*?)\s*\z/.match(text)
+      return unless match
+
+      info = match[3]
+      # CommonMark: a backtick-style fence cannot have backticks in its
+      # info string (they'd be ambiguous with the fence itself).
+      return if match[2].start_with?("`") && info.include?("`")
+
+      {
+        char: match[2][0],
+        count: match[2].length,
+        info: ReferenceDefinition.unescape_text(info),
+        indent: match[1].length,
+      }
+    end
+
+    # True when `text` is an indented code line: 4+ columns of leading
+    # whitespace (tabs expand to a 4-column tab stop).
+    def indented_line?(text)
+      Indentation.leading_columns(text) >= 4
+    end
+
+    # Cached collaborator for BlockParser. A single instance is created in
+    # BlockParser#initialize and reused; per-call state lives in method
+    # locals so reentrant calls are safe.
+    class Parser
+      def initialize(block_parser)
+        @arena = block_parser.arena
+      end
+
+      # Parses a fenced block. `fence` is CodeBlock.fenced_start's result
+      # for lines[index]. Returns the index past the block.
+      def parse_fenced(parent_id, lines, index, fence)
+        start_line = lines[index]
+        content_lines = []
+        index += 1
+        while index < lines.length
+          break if fence_close?(lines[index].content, fence[:char], fence[:count])
+
+          content_lines << lines[index]
+          index += 1
+        end
+        index += 1 if index < lines.length
+
+        # Each content line is stripped of up to the fence's own leading
+        # indent (CommonMark spec: a fence indented by N spaces strips up
+        # to N spaces from every content line, but never more). Manual
+        # byte scan beats compiling an interpolated regex per block and
+        # short-circuits when the fence had no indent (the common case).
+        indent_n = fence[:indent] || 0
+        code = content_lines.map { |l| Indentation.strip_leading_spaces(l.content, indent_n) }.join("\n")
+        code << "\n" unless content_lines.empty?
+        # The span covers the fences too, as cmark and mdast both report — a
+        # span of the content alone points a line below the block. Leading
+        # indent is excluded, so `  ```rb` starts at the backticks. `index`
+        # now sits past the closing fence, or past the last line when the
+        # fence was never closed, so lines[index - 1] is the block's last line
+        # either way.
+        source_start = start_line.start_byte + indent_n
+        source_end = lines[index - 1].end_byte
+        code_id = @arena.add_node(NodeType::CODE_BLOCK,
+                                  source_start: source_start,
+                                  source_len: source_end - source_start,
+                                  str1: code,
+                                  str2: fence[:info])
+        @arena.append_child(parent_id, code_id)
+        index
+      end
+
+      # Parses an indented code block. Returns the index past the block.
+      def parse_indented(parent_id, lines, index)
+        start_index = index
+        code_lines = []
+        while index < lines.length
+          line = lines[index]
+          break unless line.blank || CodeBlock.indented_line?(line.content)
+
+          # CommonMark: strip up to 4 columns of leading whitespace
+          # (tab-aware) from every line, including blank lines whose
+          # content beyond column 4 must be preserved verbatim.
+          code_lines << Indentation.strip_columns(line.content, 4)
+          index += 1
+        end
+
+        # Trailing blank lines are not part of the code block.
+        while !code_lines.empty? && code_lines.last.strip.empty?
+          code_lines.pop
+          index -= 1
+        end
+
+        start_byte = lines[start_index].start_byte
+        end_byte = lines[index - 1].end_byte
+        code = code_lines.empty? ? "" : code_lines.join("\n") + "\n"
+
+        code_id = @arena.add_node(NodeType::CODE_BLOCK,
+                                  source_start: start_byte,
+                                  source_len: end_byte - start_byte,
+                                  str1: code)
+        @arena.append_child(parent_id, code_id)
+        index
+      end
+
+      private
+
+      def fence_close?(text, char, count)
+        # Manual byte scan beats compiling a per-(char,count) regex on
+        # every line of a fenced block. Pattern: 0-3 spaces, >=count of
+        # `char`, optional trailing spaces/tabs, end-of-line.
+        bytes = text.bytesize
+        i = 0
+        # CommonMark spec: at most 3 spaces of indent.
+        while i < 3 && i < bytes && text.getbyte(i) == 0x20
+          i += 1
+        end
+        char_byte = char.getbyte(0)
+        fence_start = i
+        while i < bytes && text.getbyte(i) == char_byte
+          i += 1
+        end
+        return false if i - fence_start < count
+
+        while i < bytes
+          b = text.getbyte(i)
+          return false unless b == 0x20 || b == 0x09
+
+          i += 1
+        end
+        true
+      end
+    end
+  end
+end

data/lib/red_quilt/document.rb

@@ -2,9 +2,9 @@
 
 module RedQuilt
   class Document
-    attr_reader :source, :arena, :root_id, :references, :footnotes
+    attr_reader :source, :arena, :root_id, :references, :footnotes, :frontmatter
 
-    def initialize(source, arena, root_id, allow_html: false, disallow_raw_html: false, references: {}, footnotes: nil)
+    def initialize(source, arena, root_id, allow_html: false, disallow_raw_html: false, references: {}, footnotes: nil, frontmatter: nil)
       @source = source
       @arena = arena
       @root_id = root_id
@@ -12,6 +12,7 @@ module RedQuilt
       @disallow_raw_html = disallow_raw_html
       @references = references
       @footnotes = footnotes
+      @frontmatter = frontmatter
     end
 
     def allow_html?
@@ -51,11 +52,18 @@ module RedQuilt
     #   `<pre class="mermaid">` containers instead of `<pre><code>`. In
     #   standalone mode the mermaid.js runtime is also loaded from a CDN so
     #   the diagrams render in the browser without further setup.
-    def to_html(standalone: false, title: nil, lang: "en", css: nil, theme: :none, heading_ids: false, mermaid: false)
+    #
+    # When standalone and the document was parsed with `frontmatter: true`,
+    # the frontmatter's `title` / `lang` keys fill in the corresponding
+    # `<title>` / `<html lang>` if no explicit argument was given
+    # (explicit argument > frontmatter > default).
+    def to_html(standalone: false, title: nil, lang: nil, css: nil, theme: :none, heading_ids: false, mermaid: false)
       body = Renderer::HTML.new(self, heading_ids: heading_ids, mermaid: mermaid).render
       return body unless standalone
 
-      wrap_standalone_html(body, title: title.to_s, lang: lang.to_s, css: css, theme: Theme.css(theme), mermaid: mermaid)
+      effective_title = title || frontmatter_value("title")
+      effective_lang = lang || frontmatter_value("lang") || "en"
+      wrap_standalone_html(body, title: effective_title.to_s, lang: effective_lang.to_s, css: css, theme: Theme.css(theme), mermaid: mermaid)
     end
 
     def to_ast
@@ -91,6 +99,12 @@ module RedQuilt
 
     private
 
+    def frontmatter_value(key)
+      return nil unless @frontmatter.is_a?(Hash)
+
+      @frontmatter[key]
+    end
+
     # Self-contained assets embedded in standalone output when mermaid
     # support is enabled. Loads the mermaid.js runtime from a CDN as an ES
     # module, renders every `<pre class="mermaid">` container, then makes

data/lib/red_quilt/footnote_anchors.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module RedQuilt
+  # Single source of truth for the HTML element ids used to wire footnote
+  # references to their definitions and back. Both the reference (`<sup>`),
+  # the definition (`<li>`), and the back-reference links must agree on
+  # these strings, so they live in one place rather than being rebuilt at
+  # each call site.
+  module FootnoteAnchors
+    module_function
+
+    # Id of the definition `<li>` and the target of a reference link.
+    def definition_id(number)
+      "fn-#{number}"
+    end
+
+    # Id of a reference `<sup>` and the target of a back-reference link.
+    # A repeated reference (occurrence > 1) gets a `-N` suffix so every
+    # back-reference has a unique anchor.
+    def reference_id(number, occurrence)
+      occurrence > 1 ? "fnref-#{number}-#{occurrence}" : "fnref-#{number}"
+    end
+  end
+end

data/lib/red_quilt/footnote_pass.rb

@@ -29,10 +29,14 @@ module RedQuilt
 
       # Re-append referenced definitions in first-reference order; detaching
       # all current children first means unreferenced definitions are left
-      # orphaned (and so never rendered).
+      # orphaned (and so never rendered). The number and reference count are
+      # materialized onto each definition node so the renderer reads them off
+      # the arena rather than consulting the registry.
       @arena.child_ids(section_id).to_a.each { |child| @arena.detach(child) }
       @registry.referenced_labels.each do |label|
-        @arena.append_child(section_id, @registry.definition_node(label))
+        def_id = @registry.definition_node(label)
+        @arena.resolve_footnote_definition(def_id, @registry.number(label), @registry.occurrences(label))
+        @arena.append_child(section_id, def_id)
       end
     end
   end

data/lib/red_quilt/frontmatter.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "psych"
+require "date"
+
+module RedQuilt
+  # Extracts a leading YAML frontmatter block from a Markdown source.
+  module Frontmatter
+    # Matches a frontmatter block at the very start of the document.
+    PATTERN = /\A---\n(.*?)\n(?:---|\.\.\.)[ \t]*(?:\n|\z)/m
+    private_constant :PATTERN
+
+    module_function
+
+    # Extracts frontmatter from +source+, returning a two-element array:
+    # [data, body]. +data+ is the parsed Hash (or nil when there is no
+    # frontmatter), and +body+ is the source with the frontmatter region
+    # blanked out.
+    #
+    # +diagnostics+ is an optional array; on a YAML syntax error a warning
+    # Diagnostic is appended and +data+ is returned as nil.
+    def extract(source, diagnostics: nil)
+      match = PATTERN.match(source)
+      return [nil, source] unless match
+
+      data = parse_yaml(match[1], diagnostics: diagnostics)
+      body = blank_out(source, match.end(0))
+      [data, body]
+    end
+
+    # Parses the YAML body with a restricted loader (no arbitrary object
+    # instantiation; Date / Time permitted for common frontmatter dates).
+    # Returns the parsed value, or nil on a syntax error.
+    def parse_yaml(yaml, diagnostics: nil)
+      Psych.safe_load(yaml, permitted_classes: [Date, Time], aliases: false)
+    rescue Psych::SyntaxError => e
+      diagnostics&.push(
+        Diagnostic.new(
+          severity: :warning,
+          rule: :frontmatter,
+          message: "invalid YAML frontmatter: #{e.message}",
+        ),
+      )
+      nil
+    end
+
+    # Replaces every character before +offset+ with a blank line for each
+    # consumed source line, keeping later line numbers intact.
+    def blank_out(source, offset)
+      consumed = source[0, offset]
+      ("\n" * consumed.count("\n")) + source[offset..]
+    end
+  end
+end

data/lib/red_quilt/html_block.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module RedQuilt
+  # CommonMark HTML-block classification (spec 4.6). Pure functions over a
+  # line's text: given the raw line they decide whether it opens an HTML
+  # block and of which of the seven types. No arena or parser state is
+  # involved, so this lives apart from BlockParser's node construction.
+  module HtmlBlock
+    module_function
+
+    # True when `text` opens an HTML block (any of the 7 types). Indented
+    # code (4+ leading spaces) takes precedence and is never an HTML block.
+    def start?(text)
+      return false if text.start_with?("    ")
+
+      !type(text).nil?
+    end
+
+    # The HTML block type (1..7) opened by `text`, or nil if it opens none.
+    def type(text)
+      # Fast reject: every HTML block starts with `<`. lstrip strips
+      # 0-3 indent spaces (more would already be indented code), so peek
+      # the leading non-space byte before doing any allocations.
+      i = 0
+      # CommonMark: HTML block lines may have 0-3 spaces of indent.
+      while i < 3 && i < text.length && text.getbyte(i) == 0x20
+        i += 1
+      end
+      return nil unless i < text.length && text.getbyte(i) == 0x3C
+
+      stripped = i.zero? ? text : text[i..]
+
+      # Type 1: <script|pre|style|textarea (case-insensitive) followed by
+      # space/tab/end-of-line or `>`. CommonMark restricts the separator
+      # to space, tab, or a line ending (not any whitespace class).
+      return 1 if stripped.match?(%r{\A<(script|pre|style|textarea)(?:[ \t]|>|$)}i)
+
+      # Type 2: <!--
+      return 2 if stripped.start_with?("<!--")
+
+      # Type 3: <?
+      return 3 if stripped.start_with?("<?")
+
+      # Type 4: <! followed by uppercase ASCII letter
+      return 4 if stripped.match?(%r{\A<![A-Z]})
+
+      # Type 5: <![CDATA[
+      return 5 if stripped.start_with?("<![CDATA[")
+
+      # Type 6: line opens with one of the listed block-level tags.
+      return 6 if stripped.match?(TYPE_6_RE)
+
+      # Type 7: a complete open or closing tag spanning the line.
+      return 7 if valid_tag?(stripped)
+
+      nil
+    end
+
+    TYPE_6_NAMES = %w[
+      address article aside base basefont blockquote body caption center
+      col colgroup dd details dialog dir div dl dt fieldset figcaption
+      figure footer form frame frameset h1 h2 h3 h4 h5 h6 head header
+      hr html iframe legend li link main menu menuitem nav noframes ol
+      optgroup option p param search section summary table tbody td
+      tfoot th thead title tr track ul
+    ].freeze
+    TYPE_6_RE = %r{\A</?(?:#{TYPE_6_NAMES.join('|')})(?:[ \t]|>|/>|\z)}i
+    private_constant :TYPE_6_NAMES, :TYPE_6_RE
+
+    # Type 7: a complete open or closing tag on its own line.
+    # Closing tags must not have attributes.
+    #
+    # HTML tag separators per CommonMark 6.6 are space, tab, or up to one
+    # line ending -- not the broader \s class (which would include form
+    # feed and vertical tab).
+    TYPE_7_OPEN_TAG_RE = %r{
+      \A
+      <[A-Za-z][A-Za-z0-9-]*
+      (?:[ \t\r\n]+[A-Za-z_:][A-Za-z0-9_.:-]*(?:[ \t\r\n]*=[ \t\r\n]*(?:"[^"\n]*"|'[^'\n]*'|[^ \t\r\n"'=<>`]+))?)*
+      [ \t\r\n]*/?>
+      \z
+    }x
+    TYPE_7_CLOSING_TAG_RE = %r{\A</[A-Za-z][A-Za-z0-9-]*[ \t\r\n]*>\z}
+    private_constant :TYPE_7_OPEN_TAG_RE, :TYPE_7_CLOSING_TAG_RE
+
+    def valid_tag?(text)
+      # Fast reject: every type-7 tag must begin with `<`.
+      return false unless text.start_with?("<")
+
+      TYPE_7_OPEN_TAG_RE.match?(text) || TYPE_7_CLOSING_TAG_RE.match?(text)
+    end
+
+    # Closing-condition strings for HTML block types 2-5 (types 1, 6, 7 use
+    # dynamic / blank-line termination).
+    FIXED_TERMINATORS = { 2 => "-->", 3 => "?>", 4 => ">", 5 => "]]>" }.freeze
+    private_constant :FIXED_TERMINATORS
+
+    # Cached collaborator for BlockParser. A single instance is created in
+    # BlockParser#initialize and reused; per-call state lives in method
+    # locals so reentrant calls are safe.
+    class Parser
+      def initialize(block_parser)
+        @arena = block_parser.arena
+      end
+
+      # Parses the HTML block starting at lines[index] (its type already
+      # confirmed by HtmlBlock.start?). Returns the index past the block.
+      def parse(parent_id, lines, index)
+        start_index = index
+        type = HtmlBlock.type(lines[index].content)
+        end_index = locate_end(lines, index, type)
+
+        start_byte = lines[start_index].start_byte
+        end_byte = lines[end_index].end_byte
+        html_lines = (start_index..end_index).map { |i| lines[i].content }
+        html_id = @arena.add_node(NodeType::HTML_BLOCK,
+                                  source_start: start_byte,
+                                  source_len: end_byte - start_byte,
+                                  str1: html_lines.join("\n"))
+        @arena.append_child(parent_id, html_id)
+        end_index + 1
+      end
+
+      private
+
+      def locate_end(lines, index, type)
+        terminator = terminator_for(type, lines[index].content)
+
+        if terminator
+          case_insensitive = (type == 1)
+          while index < lines.length
+            line = lines[index].content
+            haystack = case_insensitive ? line.downcase : line
+            return index if haystack.include?(terminator)
+
+            index += 1
+          end
+          lines.length - 1
+        else
+          # Types 6 & 7: terminated by blank line (or end of input)
+          index += 1 while index < lines.length && !lines[index].blank
+          index - 1
+        end
+      end
+
+      def terminator_for(type, first_line)
+        case type
+        when 1
+          "</#{closing_tag_name(first_line)}>"
+        when 2..5
+          FIXED_TERMINATORS[type]
+        end
+      end
+
+      def closing_tag_name(text)
+        match = /\A<(script|pre|style|textarea)/i.match(text)
+        match ? match[1].downcase : "script"
+      end
+    end
+  end
+end

data/lib/red_quilt/indentation.rb

@@ -57,6 +57,41 @@ module RedQuilt
       end
     end
 
+    # Strips up to `max` leading 0x20 (space) bytes from `text`, returning
+    # the rest. Unlike #strip_columns this is a plain byte strip (tabs are
+    # not expanded); used where the spec counts literal spaces, e.g. a
+    # fenced code block stripping its own opening indent. No-alloc return
+    # when `text` already starts at a non-space byte.
+    def strip_leading_spaces(text, max)
+      return text if max <= 0
+
+      bytes = text.bytesize
+      i = 0
+      while i < max && i < bytes && text.getbyte(i) == 0x20
+        i += 1
+      end
+      return text if i.zero?
+
+      text.byteslice(i..)
+    end
+
+    # Strips all leading 0x20 / 0x09 bytes from `text` (spaces and tabs,
+    # no column cap). Same no-alloc return as #strip_leading_spaces when
+    # `text` already starts at a non-whitespace byte.
+    def strip_leading_whitespace(text)
+      bytes = text.bytesize
+      i = 0
+      while i < bytes
+        b = text.getbyte(i)
+        break unless b == 0x20 || b == 0x09
+
+        i += 1
+      end
+      return text if i.zero?
+
+      text.byteslice(i..)
+    end
+
     # Bytes of literal leading 0x20 / 0x09 in `text`.
     def leading_ws_bytes(text)
       i = 0