red_quilt 0.6.1

data/lib/red_quilt/footnote_definition.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module RedQuilt
+  # GitHub-style footnote definitions: `[^label]: content`. `match` handles
+  # the opener line; `Parser` (a cached BlockParser collaborator, like
+  # List::Parser) collects the optionally-indented, multi-paragraph
+  # continuation and parses it into a FOOTNOTE_DEFINITION node. Label
+  # normalization is shared with link reference definitions.
+  #
+  # NOTE: ReferenceDefinition's REF_DEF_RE also matches `[^label]:` (treating
+  # `^label` as an ordinary label), so the block dispatch must try this
+  # matcher BEFORE the reference-definition branch when footnotes are on.
+  module FootnoteDefinition
+    # Up to 3 spaces of indent, then `[^label]:`. The label is non-empty and
+    # contains no whitespace or `]` (GFM rule).
+    RE = /\A {0,3}\[\^([^\]\s]+)\]:(.*)\z/m
+
+    module_function
+
+    # Returns { label:, content_start:, content: } for a footnote-definition
+    # opener, or nil. `content_start` is the byte offset (within `text`)
+    # where the content begins, after `]:` and an optional single separating
+    # space/tab; `content` is that text (possibly empty).
+    def match(text)
+      m = RE.match(text)
+      return nil unless m
+
+      rest = m[2]
+      lead = rest.match?(/\A[ \t]/) ? 1 : 0
+      {
+        label: m[1],
+        content_start: text.bytesize - rest.bytesize + lead,
+        content: lead.zero? ? rest : rest[lead..],
+      }
+    end
+
+    # Cached collaborator for BlockParser (created once per document and
+    # reused for every definition). Footnote definitions are document-global:
+    # the parser lazily creates a single FOOTNOTES_SECTION under the root and
+    # memoizes it; per-call state otherwise lives in locals so the recursive
+    # parse_lines call is safe.
+    class Parser
+      # GFM footnote continuation indent (columns). Lines indented at least
+      # this much (plus blank lines between them) belong to the definition.
+      CONTENT_INDENT = 4
+
+      def initialize(block_parser)
+        @block_parser = block_parser
+        @arena = block_parser.arena
+        @section_id = nil
+      end
+
+      # Consumes the definition opening at `lines[index]` (its `match`
+      # already parsed), registers it in `registry`, and returns the next
+      # unconsumed line index.
+      def parse(lines, index, match, registry, root_id)
+        first = lines[index]
+        content_lines = [content_line(match[:content], first.start_byte + match[:content_start], first.end_byte)]
+        consumed_index = collect_continuation(lines, index + 1, content_lines)
+
+        label = ReferenceDefinition.normalize_label(match[:label])
+        span = SourceSpan.new(first.start_byte, lines[consumed_index - 1].end_byte)
+        if registry.defined?(label)
+          @block_parser.diagnostics << Diagnostic.new(
+            severity: :warning, rule: :duplicate_footnote,
+            message: "Duplicate footnote definition #{label.inspect} — keeping the first",
+            source_span: span,
+          )
+          return consumed_index
+        end
+
+        def_id = @arena.add_node(NodeType::FOOTNOTE_DEFINITION,
+                                 source_start: span.start_byte, source_len: span.length,
+                                 str1: label)
+        @arena.append_child(section_id(root_id), def_id)
+        registry.define(label, def_id)
+        @block_parser.parse_lines(def_id, content_lines, transformed: true)
+        consumed_index
+      end
+
+      # Make the footnotes section root's last child so it renders last and
+      # the inline pass numbers body references before any nested references
+      # inside the definitions. No-op when no definition was found.
+      def move_section_to_end(root_id)
+        return if @section_id.nil?
+
+        @arena.detach(@section_id)
+        @arena.append_child(root_id, @section_id)
+      end
+
+      private
+
+      def content_line(content, start_byte, end_byte)
+        Line.new(content, start_byte, end_byte, !content.match?(/[^ \t]/))
+      end
+
+      # Appends continuation lines to `content_lines` and returns the first
+      # line index NOT consumed (trailing blank lines are left for the
+      # surrounding flow). A line continues the definition when it is blank,
+      # indented >= CONTENT_INDENT columns (a fresh/continued paragraph), or
+      # — GFM treats footnote definitions like list items — a lazy
+      # continuation: an unindented non-blank line directly following open
+      # paragraph content that doesn't itself start a block or a new footnote
+      # definition.
+      def collect_continuation(lines, index, content_lines)
+        pending_blanks = []
+        while index < lines.length
+          current = lines[index]
+          if current.blank
+            pending_blanks << current
+            index += 1
+            next
+          end
+
+          if Indentation.leading_columns(current.content) >= CONTENT_INDENT
+            pending_blanks.each { |b| content_lines << Line.new("", b.start_byte, b.end_byte, true) }
+            pending_blanks = []
+            stripped = Indentation.strip_columns(current.content, CONTENT_INDENT)
+            advance = [Indentation.leading_ws_bytes(current.content), current.content.bytesize - stripped.bytesize].min
+            advance = 0 if advance.negative?
+            content_lines << Line.new(stripped, current.start_byte + advance, current.end_byte, false)
+            index += 1
+            next
+          end
+
+          break unless pending_blanks.empty?
+          break if content_lines.last.nil? || content_lines.last.blank
+          break if @block_parser.lazy_break?(lines, index) || FootnoteDefinition.match(current.content)
+
+          stripped = current.content.sub(/\A[ \t]+/, "")
+          strip_len = current.content.length - stripped.length
+          content_lines << Line.new(stripped, current.start_byte + strip_len, current.end_byte, false, true)
+          index += 1
+        end
+        index - pending_blanks.length
+      end
+
+      def section_id(root_id)
+        @section_id ||= begin
+          id = @arena.add_node(NodeType::FOOTNOTES_SECTION, source_start: -1, source_len: 0)
+          @arena.append_child(root_id, id)
+          id
+        end
+      end
+    end
+  end
+end

data/lib/red_quilt/footnote_pass.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module RedQuilt
+  # Post-inline pass for the footnotes extension. After the inline pass has
+  # resolved `[^label]` references (assigning numbers in first-reference
+  # order on the shared FootnoteRegistry), this reorders the definition
+  # nodes under the document-level footnotes section into that order, drops
+  # definitions that were never referenced, and removes the whole section
+  # when nothing referenced it.
+  class FootnotePass
+    def initialize(document)
+      @document = document
+      @arena = document.arena
+      @registry = document.footnotes
+    end
+
+    def apply
+      return if @registry.nil?
+
+      # BlockParser moves the footnotes section to be root's last child, so
+      # that's where it is (if any definitions were collected at all).
+      section_id = @arena.raw_last_child_id(@document.root_id)
+      return if section_id == -1 || @arena.type(section_id) != NodeType::FOOTNOTES_SECTION
+
+      unless @registry.any_referenced?
+        @arena.detach(section_id)
+        return
+      end
+
+      # Re-append referenced definitions in first-reference order; detaching
+      # all current children first means unreferenced definitions are left
+      # orphaned (and so never rendered).
+      @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))
+      end
+    end
+  end
+end

data/lib/red_quilt/footnote_registry.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module RedQuilt
+  # Shared state for the footnotes extension, created once per parse when
+  # `footnotes: true` and threaded (by reference) through the block parser,
+  # the inline builders, the FootnotePass, and the renderer. A single shared
+  # object is required because the inline pass builds a fresh Builder per
+  # materialized target, so the first-reference numbering counter cannot live
+  # on a Builder instance.
+  #
+  # `nil` is used in place of a registry when footnotes are disabled, so the
+  # collectors/resolvers can cheaply opt out.
+  class FootnoteRegistry
+    def initialize
+      @definitions = {}            # normalized label => FOOTNOTE_DEFINITION node id
+      @numbers = {}                # normalized label => footnote number
+      @occurrences = Hash.new(0)   # normalized label => reference count
+      @order = []                  # normalized labels in first-reference order
+    end
+
+    # Records a definition node for a label during block parsing. Returns
+    # false when the label is already defined (duplicate), true otherwise.
+    def define(label, node_id)
+      return false if @definitions.key?(label)
+
+      @definitions[label] = node_id
+      true
+    end
+
+    def defined?(label)
+      @definitions.key?(label)
+    end
+
+    def definition_node(label)
+      @definitions[label]
+    end
+
+    # Records an inline reference to a label. Returns [number, occurrence]
+    # (assigning the number on first reference, in encounter order), or nil
+    # when the label has no definition.
+    def reference(label)
+      return nil unless @definitions.key?(label)
+
+      unless @numbers.key?(label)
+        @order << label
+        @numbers[label] = @order.length
+      end
+      [@numbers[label], @occurrences[label] += 1]
+    end
+
+    def number(label)
+      @numbers[label]
+    end
+
+    def occurrences(label)
+      @occurrences[label]
+    end
+
+    # Referenced labels in first-reference order (the render order).
+    def referenced_labels
+      @order
+    end
+
+    def any_referenced?
+      !@order.empty?
+    end
+  end
+end

data/lib/red_quilt/indentation.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module RedQuilt
+  # Stateless CommonMark indentation / column arithmetic, shared by the
+  # block parser and its collaborator parsers (List, Blockquote, Footnote).
+  # Tabs expand to the next multiple of 4 columns.
+  module Indentation
+    module_function
+
+    # Leading-whitespace width of `text` in columns (tabs expanded to the
+    # next tab stop of 4).
+    def leading_columns(text)
+      col = 0
+      i = 0
+      bytes = text.bytesize
+      while i < bytes
+        b = text.getbyte(i)
+        if b == 0x20
+          col += 1
+        elsif b == 0x09
+          col = ((col / 4) + 1) * 4
+        else
+          break
+        end
+        i += 1
+      end
+      col
+    end
+
+    # Strips up to `n` columns of leading whitespace from `text` and
+    # returns the rest. Leading whitespace is normalised to spaces in the
+    # returned string so subsequent strips compose correctly regardless of
+    # where they land relative to the original tab stops.
+    def strip_columns(text, n)
+      return text if n <= 0
+
+      col = 0
+      i = 0
+      bytes = text.bytesize
+      while i < bytes
+        b = text.getbyte(i)
+        if b == 0x20
+          col += 1
+        elsif b == 0x09
+          col = ((col / 4) + 1) * 4
+        else
+          break
+        end
+        i += 1
+      end
+      # text[0...i] is all leading whitespace representing `col` cols.
+      if n >= col
+        i.zero? ? text : text.byteslice(i..)
+      else
+        # Keep the unstripped portion as a run of spaces.
+        (" " * (col - n)) + text.byteslice(i..)
+      end
+    end
+
+    # Bytes of literal leading 0x20 / 0x09 in `text`.
+    def leading_ws_bytes(text)
+      i = 0
+      bytes = text.bytesize
+      while i < bytes
+        b = text.getbyte(i)
+        break unless b == 0x20 || b == 0x09
+
+        i += 1
+      end
+      i
+    end
+  end
+end