red_quilt 0.6.1

data/lib/red_quilt/plain_text.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module RedQuilt
+  # Extracts plain-text content from an arena subtree.
+  #
+  # TEXT / CODE_SPAN contribute their textual content as-is;
+  # SOFTBREAK / HARDBREAK become a single space; every other inline
+  # structure (EMPHASIS, STRONG, LINK, ...) is transparently recursed
+  # into. The starting `node_id` itself is treated as a container — its
+  # children are visited, but the node's own type does not appear in
+  # the output (callers pass an IMAGE / HEADING / PARAGRAPH and want
+  # the assembled inner text).
+  #
+  # Used by:
+  # - Renderer::HTML for an image's alt attribute
+  # - Document#first_heading_text for the CLI's --auto-title
+  # - LintPass#check_missing_alt
+  module PlainText
+    module_function
+
+    def from(arena, node_id)
+      out = +""
+      walk(arena, node_id, out)
+      out
+    end
+
+    def walk(arena, node_id, out)
+      arena.each_child(node_id) do |child_id|
+        case arena.type(child_id)
+        when NodeType::TEXT
+          # TEXT may be span-only or carry a literal (entity / escape
+          # decoded). Arena#text handles both.
+          out << arena.text(child_id).to_s
+        when NodeType::CODE_SPAN
+          # CODE_SPAN always has str1 (normalized content), so read it
+          # directly to skip Arena#text's nil-check / byteslice branch.
+          out << arena.str1(child_id).to_s
+        when NodeType::SOFTBREAK, NodeType::HARDBREAK
+          out << " "
+        else
+          walk(arena, child_id, out)
+        end
+      end
+    end
+  end
+end

data/lib/red_quilt/reference_definition.rb

@@ -0,0 +1,309 @@
+# frozen_string_literal: true
+
+module RedQuilt
+  # CommonMark link reference definitions (`[label]: dest "title"`).
+  #
+  # Module-level functions are stateless helpers reused by BlockParser
+  # (fenced-code info string also calls `unescape_text`) and
+  # Inline::Builder (reference lookup uses `normalize_label`).
+  # `ReferenceDefinition::Parser` carries the per-call state (`@lines`,
+  # `@index`) and walks the lines for one definition attempt.
+  module ReferenceDefinition
+    # A reference label may contain `\[` / `\]` (backslash-escaped),
+    # but never an unescaped `[` or `]`. Newlines inside the label are
+    # allowed and collapsed by normalize_label.
+    REF_DEF_RE = /\A {0,3}\[((?:[^\\\[\]]|\\.)+)\]:(.*)\z/m
+
+    TITLE_CLOSERS = { '"' => '"', "'" => "'", "(" => ")" }.freeze
+
+    # CommonMark spec: "A link label can have at most 999 characters
+    # inside the square brackets." Applies to both reference definitions
+    # and reference link uses.
+    LABEL_MAX_LENGTH = 999
+
+    # CommonMark 6.3 link-tail whitespace: space/tab only (line endings
+    # are handled separately by the caller). Intentionally narrower than
+    # Ruby's `strip`/`lstrip`, which also match FF (U+000C) and VT
+    # (U+000B). Mirrors Inline::Builder#link_tail_whitespace_byte?.
+    LINK_TAIL_WS_RE = /[ \t]/
+
+    module_function
+
+    # True when `text` exceeds the spec's link-label length limit.
+    def label_too_long?(text)
+      text.to_s.length > LABEL_MAX_LENGTH
+    end
+
+    # Narrow lstrip: only space and tab. Used for the spec-defined
+    # whitespace around link destinations and titles in reference
+    # definitions.
+    def link_lstrip(text)
+      text.sub(/\A[ \t]+/, "")
+    end
+
+    # True when the string is empty or contains only spaces and tabs.
+    def link_blank?(text)
+      text.match?(/\A[ \t]*\z/)
+    end
+
+    # Attempts to consume a reference definition starting at `lines[index]`.
+    # Returns `{ reference: { label:, destination:, title: }, consumed: N,
+    # source_span: SourceSpan }` or nil. The reference hash is what
+    # BlockParser should store in its @references table; the source_span
+    # covers the byte range of the consumed lines (useful for
+    # duplicate-definition diagnostics).
+    def consume(lines, index)
+      Parser.new(lines, index).consume
+    end
+
+    # Unescape Markdown text: backslash-escapes for ASCII punctuation and
+    # HTML entity references. Also used by BlockParser#fenced_code_start
+    # for the info string, which shares the same unescape semantics.
+    def unescape_text(text)
+      out = text.gsub(/\\([!-\/:-@\[-`{-~])/, "\\1")
+      out.gsub(Inline::ENTITY_RE) { |m| Inline.decode_entity(m) }
+    end
+
+    # Spec-required normalization: full Unicode case fold + whitespace
+    # collapse. Inline::Builder uses the same rule when looking up the
+    # destination of a reference link.
+    def normalize_label(label)
+      # CommonMark spec: full Unicode case fold (`downcase(:fold)`), not
+      # the default per-codepoint lowercase. This makes labels like `ẞ`
+      # (U+1E9E) match a definition of `SS` because the case-fold of `ẞ`
+      # is `ss`.
+      label.to_s.strip.downcase(:fold).gsub(/[ \t\r\n]+/, " ")
+    end
+
+    class Parser
+      def initialize(lines, index)
+        @lines = lines
+        @index = index
+      end
+
+      def consume
+        text = @lines[@index].content
+        return unless text.match?(/\A {0,3}\[/)
+
+        match, consumed = match_label(text)
+        return unless match
+
+        label = ReferenceDefinition.normalize_label(match[1])
+        return if label.empty?
+
+        remainder = match[2].to_s
+        chunks, consumed = collect_destination_chunks(remainder, consumed)
+        return unless chunks
+
+        destination, rest = parse_destination(chunks.shift.to_s)
+        if destination.nil?
+          destination, rest = parse_destination(chunks.first.to_s)
+          return unless destination
+
+          chunks.shift
+        end
+
+        title, consumed = consume_title(rest, consumed)
+        return if title == :invalid
+
+        {
+          reference: {
+            label: label,
+            destination: ReferenceDefinition.unescape_text(strip_angle_brackets(destination)),
+            title: title,
+          },
+          consumed: consumed,
+          source_span: SourceSpan.new(@lines[@index].start_byte,
+                                      @lines[@index + consumed - 1].end_byte),
+        }
+      end
+
+      private
+
+      def match_label(text)
+        match = REF_DEF_RE.match(text)
+        if match
+          return [nil, nil] if ReferenceDefinition.label_too_long?(match[1])
+
+          return [match, 1]
+        end
+
+        # Multi-line label: accumulate subsequent lines until `]:` is
+        # found. Blank lines terminate the attempt.
+        accumulated = text
+        extra = 0
+        loop do
+          probe = @index + 1 + extra
+          return [nil, nil] if probe >= @lines.length
+
+          next_line = @lines[probe]
+          return [nil, nil] if next_line.blank
+
+          accumulated += "\n" + next_line.content
+          extra += 1
+          m = REF_DEF_RE.match(accumulated)
+          next unless m
+          return [nil, nil] if ReferenceDefinition.label_too_long?(m[1])
+
+          return [m, 1 + extra]
+        end
+      end
+
+      def collect_destination_chunks(remainder, consumed)
+        chunks = [remainder]
+        return [chunks, consumed] unless ReferenceDefinition.link_blank?(remainder)
+
+        return [nil, nil] if @index + consumed >= @lines.length
+
+        next_line = @lines[@index + consumed]
+        return [nil, nil] if next_line.blank
+
+        chunks << next_line.content
+        [chunks, consumed + 1]
+      end
+
+      def consume_title(rest, consumed)
+        title_source = rest.to_s
+        consumed_before_title = consumed
+        title_on_separate_line = false
+        if ReferenceDefinition.link_blank?(title_source) && @index + consumed < @lines.length
+          next_line = @lines[@index + consumed]
+          if next_line && potential_title_start?(next_line.content)
+            title_source = next_line.content
+            consumed += 1
+            title_on_separate_line = true
+          end
+        end
+
+        while @index + consumed < @lines.length && title_needs_more_lines?(title_source)
+          next_line = @lines[@index + consumed]
+          break if next_line.blank
+
+          title_source = title_source.empty? ? next_line.content : "#{title_source}\n#{next_line.content}"
+          consumed += 1
+        end
+
+        title, trailing = parse_title(title_source)
+        if trailing && trailing.match?(/\S/)
+          if title_on_separate_line
+            # The title was pulled from a follow-up line; back off so
+            # that line is reparsed as ordinary content and the def is
+            # still accepted (sans title).
+            return [nil, consumed_before_title]
+          else
+            # Title was on the destination line itself; the whole def is
+            # invalid.
+            return [:invalid, consumed]
+          end
+        end
+
+        [title, consumed]
+      end
+
+      def strip_angle_brackets(destination)
+        destination.start_with?("<") && destination.end_with?(">") ? destination[1...-1] : destination
+      end
+
+      def parse_destination(text)
+        source = ReferenceDefinition.link_lstrip(text)
+        return [nil, nil] if source.empty?
+
+        if source.start_with?("<")
+          close = source.index(">")
+          if close
+            tail = source[(close + 1)..].to_s
+            if tail.empty? || tail.match?(/\A[ \t\r\n]/)
+              return [source[0..close], tail]
+            end
+          end
+          # Raw destinations cannot start with `<`, so once the angle
+          # form fails there is no fallback.
+          return [nil, nil]
+        end
+
+        parse_raw_destination(source)
+      end
+
+      # Raw destination per CommonMark 6.3: no ASCII control chars or
+      # space; parentheses must be balanced or backslash-escaped. Mirrors
+      # the inline-link logic in Inline::Builder#parse_raw_destination
+      # so a reference definition is not more permissive than an inline
+      # link destination.
+      RAW_DEST_FORBIDDEN_RE = /[\u0000-\u0020\u007F]/
+      ASCII_PUNCT_RE = /[!-\/:-@\[-`{-~]/
+
+      def parse_raw_destination(source)
+        depth = 0
+        i = 0
+        len = source.length
+        while i < len
+          c = source[i]
+          if c == "\\" && i + 1 < len && ASCII_PUNCT_RE.match?(source[i + 1])
+            i += 2
+            next
+          end
+          break if RAW_DEST_FORBIDDEN_RE.match?(c)
+
+          if c == "("
+            depth += 1
+          elsif c == ")"
+            break if depth.zero?
+
+            depth -= 1
+          end
+          i += 1
+        end
+
+        return [nil, nil] if i.zero?
+        return [nil, nil] unless depth.zero?
+
+        [source[0...i], source[i..].to_s]
+      end
+
+      def title_needs_more_lines?(text)
+        stripped = ReferenceDefinition.link_lstrip(text)
+        return false if stripped.empty?
+
+        quote = stripped[0]
+        closer = TITLE_CLOSERS[quote]
+        return false unless closer
+        return false if stripped.length > 1 && stripped.end_with?(closer)
+
+        true
+      end
+
+      def potential_title_start?(text)
+        %w[" ' (].include?(ReferenceDefinition.link_lstrip(text)[0])
+      end
+
+      def parse_title(text)
+        stripped = ReferenceDefinition.link_lstrip(text)
+        return [nil, stripped] if stripped.empty?
+
+        opener = stripped[0]
+        closer = TITLE_CLOSERS[opener]
+        return [nil, stripped] unless closer
+
+        body = +""
+        escaped = false
+        index = 1
+        while index < stripped.length
+          char = stripped[index]
+          if char == "\\" && !escaped
+            escaped = true
+            body << char
+          elsif char == closer && !escaped
+            trailing = stripped[(index + 1)..].to_s
+            return [ReferenceDefinition.unescape_text(body), trailing]
+          else
+            body << char
+            escaped = false
+          end
+          index += 1
+        end
+
+        [nil, stripped]
+      end
+    end
+  end
+end

data/lib/red_quilt/renderer/html.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+
+module RedQuilt
+  module Renderer
+    class HTML
+      def initialize(document)
+        @document = document
+        @arena = document.arena
+        @out = +""
+      end
+
+      def render
+        render_children(@document.root_id)
+        @out
+      end
+
+      private
+
+      # CommonMark-compliant HTML escape: only `&`, `<`, `>`, `"` are
+      # rewritten. Apostrophes are left as-is (escape_html on Ruby
+      # 3.0+ rewrites `'` -> `&#39;` which fails CommonMark spec
+      # comparisons).
+      HTML_ESCAPE_TABLE = { "&" => "&amp;", "<" => "&lt;", ">" => "&gt;", '"' => "&quot;" }.freeze
+      HTML_ESCAPE_RE = /[&<>"]/
+
+      def escape_html(str)
+        return str unless HTML_ESCAPE_RE.match?(str)
+
+        str.gsub(HTML_ESCAPE_RE, HTML_ESCAPE_TABLE)
+      end
+
+      def render_children(node_id)
+        child_id = @arena.raw_first_child_id(node_id)
+        until child_id == -1
+          render_node(child_id)
+          child_id = @arena.raw_next_sibling_id(child_id)
+        end
+      end
+
+      def render_node(node_id)
+        case @arena.type(node_id)
+        when NodeType::PARAGRAPH
+          @out << "<p>"
+          render_children(node_id)
+          @out << "</p>\n"
+        when NodeType::HEADING
+          level = @arena.int1(node_id)
+          @out << "<h#{level}>"
+          render_children(node_id)
+          @out << "</h#{level}>\n"
+        when NodeType::THEMATIC_BREAK
+          @out << "<hr />\n"
+        when NodeType::BLOCKQUOTE
+          @out << "<blockquote>\n"
+          render_children(node_id)
+          @out << "</blockquote>\n"
+        when NodeType::LIST
+          ordered = @arena.int1(node_id) == 1
+          tag = ordered ? "ol" : "ul"
+          start_number = @arena.int2(node_id)
+          attrs = ordered && start_number != 1 ? %( start="#{start_number}") : ""
+          @out << "<#{tag}#{attrs}>\n"
+          render_children(node_id)
+          @out << "</#{tag}>\n"
+        when NodeType::LIST_ITEM
+          @out << "<li>"
+          render_list_item(node_id)
+          @out << "</li>\n"
+        when NodeType::CODE_BLOCK
+          @out << "<pre><code"
+          info_word = @arena.str2(node_id).to_s.split.first.to_s
+          @out << %( class="language-#{escape_html(info_word)}") unless info_word.empty?
+          @out << ">"
+          @out << escape_html(@arena.text(node_id).to_s)
+          @out << "</code></pre>\n"
+        when NodeType::HTML_BLOCK
+          render_raw_html(@arena.text(node_id).to_s, block: true)
+        when NodeType::TABLE
+          @out << "<table>\n"
+          render_table(node_id)
+          @out << "</table>\n"
+        when NodeType::TEXT
+          @out << escape_html(@arena.text(node_id).to_s)
+        when NodeType::SOFTBREAK
+          @out << "\n"
+        when NodeType::HARDBREAK
+          @out << "<br />\n"
+        when NodeType::EMPHASIS
+          @out << "<em>"
+          render_children(node_id)
+          @out << "</em>"
+        when NodeType::STRONG
+          @out << "<strong>"
+          render_children(node_id)
+          @out << "</strong>"
+        when NodeType::STRIKETHROUGH
+          @out << "<del>"
+          render_children(node_id)
+          @out << "</del>"
+        when NodeType::CODE_SPAN
+          @out << "<code>#{escape_html(@arena.text(node_id).to_s)}</code>"
+        when NodeType::LINK
+          dest = escape_html(@arena.str1(node_id).to_s)
+          @out << %(<a href="#{dest}")
+          append_title_attribute(node_id)
+          @out << ">"
+          render_children(node_id)
+          @out << "</a>"
+        when NodeType::IMAGE
+          alt = PlainText.from(@arena, node_id)
+          dest = escape_html(@arena.str1(node_id).to_s)
+          @out << %(<img src="#{dest}" alt="#{escape_html(alt)}")
+          append_title_attribute(node_id)
+          @out << " />"
+        when NodeType::HTML_INLINE
+          render_raw_html(@arena.text(node_id).to_s, block: false)
+        when NodeType::FOOTNOTE_REFERENCE
+          render_footnote_reference(node_id)
+        when NodeType::FOOTNOTES_SECTION
+          render_footnotes_section(node_id)
+        end
+      end
+
+      # `[^label]` reference: a superscript link to the definition. The
+      # element ids use the footnote number; a second+ reference to the
+      # same footnote gets a `-M` suffix so each backref has a unique target.
+      def render_footnote_reference(node_id)
+        number = @arena.int1(node_id)
+        occurrence = @arena.int2(node_id)
+        ref_id = occurrence > 1 ? "fnref-#{number}-#{occurrence}" : "fnref-#{number}"
+        @out << %(<sup><a href="#fn-#{number}" id="#{ref_id}">#{number}</a></sup>)
+      end
+
+      def render_footnotes_section(node_id)
+        @out << %(<section class="footnotes">\n<ol>\n)
+        @arena.each_child(node_id) { |def_id| render_footnote_definition(def_id) }
+        @out << "</ol>\n</section>\n"
+      end
+
+      def render_footnote_definition(def_id)
+        label = @arena.str1(def_id).to_s
+        number = @document.footnotes.number(label)
+        occurrences = @document.footnotes.occurrences(label)
+        @out << %(<li id="fn-#{number}">\n)
+
+        # Append the backref(s) inside the definition's last paragraph (GFM);
+        # if the last block isn't a paragraph, emit a standalone one.
+        last = @arena.raw_last_child_id(def_id)
+        child = @arena.raw_first_child_id(def_id)
+        until child == -1
+          if child == last && @arena.type(child) == NodeType::PARAGRAPH
+            @out << "<p>"
+            render_children(child)
+            @out << footnote_backrefs(number, occurrences)
+            @out << "</p>\n"
+          else
+            render_node(child)
+          end
+          child = @arena.raw_next_sibling_id(child)
+        end
+        if last == -1 || @arena.type(last) != NodeType::PARAGRAPH
+          @out << "<p>#{footnote_backrefs(number, occurrences)}</p>\n"
+        end
+
+        @out << "</li>\n"
+      end
+
+      def footnote_backrefs(number, occurrences)
+        out = +""
+        (1..occurrences).each do |occ|
+          ref_id = occ > 1 ? "fnref-#{number}-#{occ}" : "fnref-#{number}"
+          suffix = occ > 1 ? "<sup>#{occ}</sup>" : ""
+          out << %( <a href="##{ref_id}">&#8617;#{suffix}</a>)
+        end
+        out
+      end
+
+      def render_table(table_id)
+        rows = @arena.child_ids(table_id).to_a
+        header_rows = rows.select { |row_id| @arena.int1(row_id) == 1 }
+        body_rows = rows.reject { |row_id| @arena.int1(row_id) == 1 }
+
+        unless header_rows.empty?
+          @out << "<thead>\n"
+          header_rows.each { |row_id| render_table_row(row_id) }
+          @out << "</thead>\n"
+        end
+        unless body_rows.empty?
+          @out << "<tbody>\n"
+          body_rows.each { |row_id| render_table_row(row_id) }
+          @out << "</tbody>\n"
+        end
+      end
+
+      def render_list_item(node_id)
+        parent_id = @arena.raw_parent_id(node_id)
+        tight = parent_id != -1 && @arena.type(parent_id) == NodeType::LIST && @arena.int3(parent_id) == 1
+
+        first_child_id = @arena.raw_first_child_id(node_id)
+        first_is_para = first_child_id != -1 &&
+                        @arena.type(first_child_id) == NodeType::PARAGRAPH
+
+        # Empty <li> renders inline; otherwise loose lists and tight
+        # items opening with a non-paragraph block get a leading newline.
+        if first_child_id != -1 && (!tight || !first_is_para)
+          @out << "\n"
+        end
+
+        child_id = first_child_id
+        prev_type = nil
+        until child_id == -1
+          type = @arena.type(child_id)
+          if tight && type == NodeType::PARAGRAPH
+            # Paragraph in a tight list: drop the wrapping <p>. Only
+            # insert a separator `\n` when the previous child was also
+            # a tight paragraph — every other block already trails its
+            # own `\n`, so adding another would double-space the gap.
+            @out << "\n" if prev_type == NodeType::PARAGRAPH
+            render_children(child_id)
+          else
+            # Non-paragraph block. Tight list paragraphs were emitted
+            # without their tag, so follow them with `\n` to land the
+            # next block on a fresh line. Other blocks already end with
+            # their own `\n`, so no extra separator is needed.
+            @out << "\n" if tight && prev_type == NodeType::PARAGRAPH
+            render_node(child_id)
+          end
+          prev_type = type
+          child_id = @arena.raw_next_sibling_id(child_id)
+        end
+      end
+
+      def render_table_row(row_id)
+        @out << "<tr>"
+        @arena.each_child(row_id) do |cell_id|
+          tag = @arena.int1(cell_id) == 1 ? "th" : "td"
+          @out << "<#{tag}>"
+          render_children(cell_id)
+          @out << "</#{tag}>"
+        end
+        @out << "</tr>\n"
+      end
+
+      # GFM "Disallowed Raw HTML" extension: when allow_html is on but
+      # the caller has opted into filtering, the 9 dangerous tag names
+      # have their leading `<` rewritten to `&lt;` so the browser sees
+      # them as text. Word boundary (\b) prevents over-filtering
+      # (e.g. `<scripts>` is left alone).
+      DISALLOWED_RAW_TAGS = %w[title textarea style xmp iframe noembed noframes script plaintext].freeze
+      DISALLOWED_RAW_TAG_RE = /<(?=\/?(?:#{DISALLOWED_RAW_TAGS.join('|')})\b)/i
+
+      def render_raw_html(text, block:)
+        if @document.allow_html?
+          out_text = @document.disallow_raw_html? ? filter_disallowed_raw(text) : text
+          @out << out_text
+          @out << "\n" if block
+        else
+          escaped = escape_html(text)
+          if block
+            @out << escaped << "\n"
+          else
+            @out << escaped
+          end
+        end
+      end
+
+      def filter_disallowed_raw(text)
+        text.gsub(DISALLOWED_RAW_TAG_RE, "&lt;")
+      end
+
+      def append_title_attribute(node_id)
+        title = @arena.str2(node_id).to_s
+        return if title.empty?
+
+        @out << %( title="#{escape_html(title)}")
+      end
+    end
+  end
+end