maquina_remend 0.1.0

data/lib/maquina_remend/handlers/single_tilde.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module MaquinaRemend
+  module Handlers
+    # Case 25. "20~25°C" is a numeric range, not the start of a strikethrough.
+    # Escaping the lone tilde makes that explicit before any parser has to guess.
+    # Doubled tildes are left alone — those are case 06's business.
+    #
+    # Enabled by `single_tilde:`, on by default.
+    #
+    # ```ruby
+    # MaquinaRemend.call("20~25°C") # => "20\\~25°C"
+    # ```
+    class SingleTilde < Base
+      # A single `~` that is neither doubled nor already escaped.
+      LONE_TILDE = /(?<![~\\])~(?!~)/
+
+      private
+        def option_key = :single_tilde
+
+        def repair(_text, scanner)
+          escape_matches(scanner, LONE_TILDE)
+        end
+    end
+  end
+end

data/lib/maquina_remend/handlers/strikethrough.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module MaquinaRemend
+  module Handlers
+    # Case 06. Double tildes only. A lone tilde is case 25's problem, and
+    # treating it as strikethrough is exactly the false positive that case
+    # exists to prevent.
+    #
+    # Enabled by `strikethrough:`, on by default.
+    #
+    # ```ruby
+    # MaquinaRemend.call("~~struck") # => "~~struck~~"
+    # ```
+    class Strikethrough < Base
+      private
+        def option_key = :strikethrough
+
+        def repair(text, scanner)
+          scanner.masked_paragraph.scan("~~").length.odd? ? text + "~~" : text
+        end
+    end
+  end
+end

data/lib/maquina_remend/pipeline.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require_relative "handlers/app_tags"
+require_relative "handlers/dangling_escape"
+require_relative "handlers/html_tags"
+require_relative "handlers/inline_code"
+require_relative "handlers/emphasis"
+require_relative "handlers/strikethrough"
+require_relative "handlers/links"
+require_relative "handlers/math"
+require_relative "handlers/setext_heading"
+require_relative "handlers/comparison_operators"
+require_relative "handlers/single_tilde"
+
+module MaquinaRemend
+  # Runs the built-in handlers in a fixed order, then any handlers the caller
+  # registered. Nothing runs at all when the cursor is inside a fenced code
+  # block: a fence is the one place where broken-looking markup is the content.
+  #
+  # MaquinaRemend.call builds one of these per call and throws it away; it holds
+  # no state between buffers. Constructing it directly is worth it only to
+  # validate an option hash once and reuse it across many buffers:
+  #
+  # ```ruby
+  # pipeline = MaquinaRemend::Pipeline.new(inline_math: true)
+  # deltas.map { |buffer| pipeline.call(buffer) }
+  # ```
+  class Pipeline
+    # Order is load-bearing, and two of these were learned from replaying real
+    # streamed output rather than from the spec:
+    #
+    # * Links run before Emphasis. Emphasis appending "**" into a half-typed
+    #   "[label](" puts the closer inside the destination, where the link
+    #   handler then eats it as a partial URL - and appends it again next pass.
+    # * DanglingEscape runs first. A trailing backslash escapes whatever any
+    #   later handler appends.
+    # * AppTags runs last. Its closing tag has to sit outside every other
+    #   completion, or Emphasis closes a bold run after `</thinking>` instead of
+    #   inside it.
+    BUILT_INS = [
+      Handlers::DanglingEscape,
+      Handlers::HtmlTags,
+      Handlers::InlineCode,
+      Handlers::Links,
+      Handlers::Math,
+      Handlers::Emphasis,
+      Handlers::Strikethrough,
+      Handlers::SetextHeading,
+      Handlers::ComparisonOperators,
+      Handlers::SingleTilde,
+      Handlers::AppTags
+    ].freeze
+
+    # The resolved option hash: MaquinaRemend::DEFAULTS merged with whatever the
+    # caller passed. Frozen defaults, so this is the merged copy.
+    attr_reader :options
+
+    # Validates `options` and builds a pipeline.
+    #
+    # * `options` — any subset of MaquinaRemend::DEFAULTS.
+    # * Raises MaquinaRemend::UnknownOption for a key outside
+    #   MaquinaRemend::DEFAULTS, or a `link_mode:` outside
+    #   MaquinaRemend::LINK_MODES.
+    #
+    # Validation happens here rather than at repair time so that a bad option is
+    # a startup error for the host, not a surprise halfway through a stream.
+    def initialize(**options)
+      unknown = options.keys - DEFAULTS.keys
+      raise UnknownOption, "unknown option(s): #{unknown.join(", ")}" if unknown.any?
+
+      @options = DEFAULTS.merge(options)
+      validate_link_mode
+      validate_app_tags
+    end
+
+    # Repairs `markdown` and returns the result. This is what
+    # MaquinaRemend.call delegates to.
+    #
+    # `nil` and the empty string are passed straight back. Otherwise each
+    # built-in in BUILT_INS gets a turn, and the buffer is rescanned after any
+    # handler that changed it — a handler must not read a view of the text that
+    # a previous handler has already invalidated by appending to its tail.
+    # Custom handlers from the `handlers:` option run last.
+    def call(markdown)
+      return markdown if markdown.nil? || markdown.empty?
+
+      scanner = Scanner.new(markdown)
+      text = markdown
+
+      # Built-ins each refuse to act inside a fence. Custom handlers are not
+      # short-circuited here: Context exposes #in_code_fence? precisely so a
+      # host handler can decide for itself, which it cannot do if it never runs.
+
+      BUILT_INS.each do |handler|
+        repaired = handler.new(options).call(text, scanner.context(options), scanner)
+        next if repaired == text
+
+        text = repaired
+        scanner = Scanner.new(text)
+      end
+
+      run_custom(text, scanner.context(options))
+    end
+
+    private
+      def run_custom(text, context)
+        Array(options[:handlers]).reduce(text) { |current, handler| handler.call(current, context) }
+      end
+
+      def validate_link_mode
+        return if LINK_MODES.include?(options[:link_mode])
+
+        raise UnknownOption, "link_mode must be one of #{LINK_MODES.join(", ")}"
+      end
+
+      def validate_app_tags
+        value = options[:app_tags]
+        return if !value || (value.is_a?(Array) && value.all? { |name| name.respond_to?(:to_str) || name.is_a?(Symbol) })
+
+        raise UnknownOption, "app_tags must be false or a list of tag names"
+      end
+  end
+end

data/lib/maquina_remend/scanner.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module MaquinaRemend
+  # One pass over the buffer, tracking the only three states a handler is
+  # allowed to ask about. The guards in the pattern spec are the reason this
+  # exists: nothing may be "repaired" inside a fence, inside inline code, or
+  # inside math, and the only way to know is to have walked the buffer.
+  #
+  # A scanner is built over one immutable buffer and caches everything it
+  # derives, so the expensive walk happens once. When a handler changes the
+  # text, MaquinaRemend::Pipeline throws the scanner away and builds a new one
+  # rather than trying to update this one.
+  #
+  # Hosts should reach for MaquinaRemend.context instead: it answers the
+  # question — is the tail inside a fence, and what language is it — without
+  # exposing the scanner's internals. The scanner itself is public because the
+  # built-in handlers need it, not because it is a stable surface.
+  class Scanner
+    # A fenced code block's opening or closing line: up to three spaces of
+    # indent, three or more backticks or tildes, then an optional info string
+    # captured as group 2.
+    FENCE_LINE = /\A {0,3}(`{3,}|~{3,})[ \t]*(\S*)/
+
+    # A *balanced* inline code span. Matching only balanced spans is the point:
+    # what is left over after these are masked out is the unterminated one.
+    INLINE_CODE = /(?<!`)(`+)(?!`)(.*?)(?<!`)\1(?!`)/m
+
+    # The math delimiters whose contents must never be treated as markdown.
+    # Underscores inside `$$a_1 + b_2$$` are subscripts, not emphasis, and a
+    # LaTeX span is math even when it uses no dollar sign at all.
+    MATH_SPANS = [
+      /\$\$.*?\$\$/m,          # block math
+      /\\\[.*?\\\]/m,          # LaTeX display
+      /\\\(.*?\\\)/m           # LaTeX inline
+    ].freeze
+
+    # Masked spans keep their length but must not read as whitespace: a "**" that
+    # follows `code` is a valid closer, and blanking the code span with spaces
+    # makes it look like an opener instead. Learned from real streamed output.
+    MASK = "\u0001"
+
+    # The buffer this scanner was built over, unmodified.
+    attr_reader :text
+
+    # The info string of the fence that is currently open — `"ruby"` for a
+    # fence opened with three backticks and `ruby` — or `nil` when no fence is
+    # open or the fence carried no info string.
+    attr_reader :open_fence_info
+
+    # Walks `text` once and caches what the walk found. The buffer is not
+    # copied and never mutated.
+    def initialize(text)
+      @text = text
+      @fence_open = false
+      @open_fence_info = nil
+      @paragraph_offset = 0
+      scan
+    end
+
+    # True when the buffer ends inside a fenced code block. Surfaces to handlers
+    # as MaquinaRemend::Context#in_code_fence?.
+    def fence_open? = @fence_open
+
+    # Everything after the last blank line outside a fence. Emphasis cannot span
+    # a blank line, so this is the only region a completion may touch.
+    def paragraph
+      text[@paragraph_offset..] || ""
+    end
+
+    # The byte offset #paragraph starts at: the end of the last blank line that
+    # was not inside a fence.
+    attr_reader :paragraph_offset
+
+    # Everything before #paragraph. A handler that rewrites the paragraph
+    # rebuilds the buffer as `scanner.prefix + repaired_paragraph`, which is how
+    # a repair stays confined to the region it is allowed to touch.
+    def prefix
+      text[0...@paragraph_offset] || ""
+    end
+
+    # An unterminated inline code span in the paragraph: an odd number of
+    # backticks once the balanced spans are gone.
+    def inline_code_open?
+      return @inline_code_open if defined?(@inline_code_open)
+
+      @inline_code_open = masked_code.count("`").odd?
+    end
+
+    # Block math spans paragraphs, so this question is asked of the whole
+    # document - but only of the parts of it that are prose. A document that
+    # merely writes about "$$x = 1" inside a code span has no open math.
+    def math_open?
+      return @math_open if defined?(@math_open)
+
+      @math_open = masked_text.scan(/(?<!\\)\$\$/).length.odd?
+    end
+
+    # The whole buffer with fenced blocks and inline code blanked out, lengths
+    # preserved.
+    def masked_text
+      @masked_text ||= mask_fences(text).gsub(INLINE_CODE) { MASK * ::Regexp.last_match(0).length }
+    end
+
+    # The paragraph with inline code and math replaced by placeholders of the
+    # same length, so delimiter counting cannot see inside them.
+    def masked_paragraph
+      @masked_paragraph ||= MATH_SPANS.reduce(masked_code) do |masked, pattern|
+        masked.gsub(pattern) { MASK * ::Regexp.last_match(0).length }
+      end
+    end
+
+    # The MaquinaRemend::Context for this buffer, carrying `options` through to
+    # any handler that wants to read them. Memoised per option hash, since the
+    # pipeline asks for the same one repeatedly.
+    def context(options = {})
+      @context ||= {}
+      @context[options] ||=
+        Context.new(
+          in_code_fence: fence_open?,
+          in_inline_code: inline_code_open?,
+          in_math: math_open?,
+          open_fence_info: open_fence_info,
+          options: options
+        )
+    end
+
+    private
+      def mask_fences(source)
+        inside = false
+        marker = nil
+
+        source.lines.map { |line|
+          match = FENCE_LINE.match(line.chomp)
+
+          if match && inside && closes?(marker, match[1])
+            inside = false
+            marker = nil
+            MASK * line.length
+          elsif match && !inside
+            inside = true
+            marker = match[1]
+            MASK * line.length
+          elsif inside
+            MASK * line.length
+          else
+            line
+          end
+        }.join
+      end
+
+      def masked_code
+        @masked_code ||= paragraph.gsub(INLINE_CODE) { MASK * ::Regexp.last_match(0).length }
+      end
+
+      def scan
+        offset = 0
+        marker = nil
+
+        text.each_line do |line|
+          stripped = line.chomp
+
+          if (match = FENCE_LINE.match(stripped))
+            if @fence_open && closes?(marker, match[1])
+              @fence_open = false
+              @open_fence_info = nil
+              marker = nil
+              @paragraph_offset = offset + line.length
+            elsif !@fence_open
+              @fence_open = true
+              marker = match[1]
+              @open_fence_info = match[2].empty? ? nil : match[2]
+            end
+          elsif !@fence_open && stripped.strip.empty?
+            @paragraph_offset = offset + line.length
+          end
+
+          offset += line.length
+        end
+      end
+
+      def closes?(opening, candidate)
+        return false unless opening
+
+        opening[0] == candidate[0] && candidate.length >= opening.length
+      end
+  end
+end

data/lib/maquina_remend/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module MaquinaRemend
+  # The released version of the gem, as a `String`. Follows semantic
+  # versioning; the option names in MaquinaRemend::DEFAULTS and the handler
+  # contract are the public surface a major bump would be about.
+  VERSION = "0.1.0"
+end

data/lib/maquina_remend.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+require_relative "maquina_remend/version"
+require_relative "maquina_remend/context"
+require_relative "maquina_remend/scanner"
+require_relative "maquina_remend/pipeline"
+
+# Repairs the tail of a markdown buffer that is still being streamed, so that a
+# renderer never sees half a bold run or a link whose URL has not arrived yet.
+#
+# ```ruby
+# MaquinaRemend.call("**unclosed bold")     # => "**unclosed bold**"
+# MaquinaRemend.call("`code")               # => "`code`"
+# MaquinaRemend.call("[label](https://exa") # => "[label](#)"
+# ```
+#
+# Pure function. Idempotent. Returns well-formed input unchanged, byte for byte.
+# Zero runtime dependencies, and no Rails: this gem must be usable from a plain
+# Ruby process with nothing else loaded.
+#
+# ## The shape of the library
+#
+# | Object | Role |
+# |---|---|
+# | MaquinaRemend.call | the whole public API: buffer in, repaired buffer out |
+# | MaquinaRemend.context | the scanner's reading of a buffer, with no repair |
+# | MaquinaRemend::DEFAULTS | every option and its default |
+# | MaquinaRemend::Context | what a handler is allowed to know |
+# | MaquinaRemend::Pipeline | the fixed order the built-in handlers run in |
+# | MaquinaRemend::Handlers | one class per repair |
+#
+# ## Guarantees
+#
+# Three properties are asserted over the whole test corpus rather than over
+# hand-picked inputs, and every handler is written to keep them:
+#
+# 1. **Idempotence** — `call(call(x)) == call(x)`.
+# 2. **No-op on well-formed input** — a complete document comes back
+#    byte-identical.
+# 3. **Prefix safety** — every truncation point of a document is repairable
+#    without raising.
+#
+# A repair that cannot be made safe is not made. Guards matter more than
+# completions here: a false repair corrupts a message that was never broken.
+# Nothing is ever completed inside a fenced code block, inside an inline code
+# span, or inside math, because in those places broken-looking markup is the
+# content.
+module MaquinaRemend
+  # The application tag names closed by default: the tags a model emits to
+  # carry application meaning rather than presentation. Each host gives them
+  # meaning of its own, so `app_tags:` takes a list rather than a boolean; this
+  # is the list a host gets when it says nothing.
+  APP_TAGS = %w[thinking answer tool_call citation scratchpad].freeze
+
+  # Every repair is individually disableable. Inline math is off because a bare
+  # dollar sign is far more often currency than mathematics.
+  #
+  # Pass any subset of these as keyword arguments to MaquinaRemend.call; an
+  # unrecognised key raises MaquinaRemend::UnknownOption rather than being
+  # ignored, so a typo in a host's configuration surfaces at once.
+  #
+  # ### Completion handlers
+  #
+  # Each flag switches one repair on or off.
+  #
+  # | Option | Default | Malformed input | Repaired to | Handler |
+  # |---|---|---|---|---|
+  # | `bold:` | `true` | `**unclosed bold` | `**unclosed bold**` | Handlers::Emphasis |
+  # | `italic:` | `true` | `*unclosed` / `_unclosed` | `*unclosed*` / `_unclosed_` | Handlers::Emphasis |
+  # | `bold_italic:` | `true` | `***both` | `***both***` | Handlers::Emphasis |
+  # | `inline_code:` | `true` | `` `code `` | `` `code` `` | Handlers::InlineCode |
+  # | `strikethrough:` | `true` | `~~struck` | `~~struck~~` | Handlers::Strikethrough |
+  # | `links:` | `true` | `[label` | `[label]()` | Handlers::Links |
+  # | `images:` | `true` | `![alt` | `![alt]()` | Handlers::Links |
+  # | `block_math:` | `true` | `$$x = 1` | `$$x = 1$$` | Handlers::Math |
+  # | `inline_math:` | **`false`** | `$x = 1` | `$x = 1$` | Handlers::Math |
+  # | `setext_headings:` | `true` | `Title` then a lone `=` | underline padded to the width of the title | Handlers::SetextHeading |
+  # | `comparison_operators:` | `true` | `- a > b` | `- a \> b` | Handlers::ComparisonOperators |
+  # | `html_tags:` | `true` | `text <div cla` | `text` — the truncated tag is dropped | Handlers::HtmlTags |
+  # | `single_tilde:` | `true` | `20~25°C` | `20\~25°C` | Handlers::SingleTilde |
+  # | `dangling_escape:` | `true` | a buffer ending in a lone `\` | the trailing backslash is dropped | Handlers::DanglingEscape |
+  # | `app_tags:` | MaquinaRemend::APP_TAGS | `<thinking>` with no closer yet | `</thinking>` appended | Handlers::AppTags |
+  #
+  # **`inline_math:` is off because a bare dollar sign is currency far more
+  # often than it is mathematics.** `costs $5 and $10` would otherwise acquire a
+  # closing `$` and turn a price list into an equation. Turn it on only if you
+  # know your corpus.
+  #
+  # ### `app_tags:`
+  #
+  # The list of application tag names MaquinaRemend::Handlers::AppTags will
+  # close, MaquinaRemend::APP_TAGS by default. Pass your own list to match the
+  # host's tag registry, or `false` to switch the handler off. Anything that is
+  # neither a list of names nor `false` raises MaquinaRemend::UnknownOption.
+  #
+  # ```ruby
+  # MaquinaRemend.call(buffer, app_tags: %w[thinking answer plan])
+  # MaquinaRemend.call(buffer, app_tags: false)
+  # ```
+  #
+  # **Only the listed names are closed, and the list is short on purpose.**
+  # Closing every unbalanced tag would close the ones that must not be closed:
+  # `<br>` and `<img>` have no closer, and a `<div>` wrapper is routinely opened
+  # in one streamed block and closed several blocks later, so a speculative
+  # `</div>` would land in the middle of its own content. An application tag is
+  # different in kind — it is emitted whole by the model, it wraps a single
+  # region of the answer, and the host knows its name in advance.
+  #
+  # ### `link_mode:`
+  #
+  # `:protocol` (the default) or `:text_only`. Anything else raises
+  # MaquinaRemend::UnknownOption. See MaquinaRemend::LINK_MODES.
+  #
+  # | Value | `[label` | `[label](https://exa` |
+  # |---|---|---|
+  # | `:protocol` | `[label]()` | `[label](#)` |
+  # | `:text_only` | `label` | `label` |
+  #
+  # A half-streamed destination is **never** kept. `https://exa` is a perfectly
+  # valid URL to the wrong host, and model output is untrusted; the destination
+  # is replaced by a placeholder until the real one arrives.
+  #
+  # ### `handlers:`
+  #
+  # An array of custom handlers, run after the built-ins. MaquinaRemend.call
+  # documents the contract.
+  DEFAULTS = {
+    bold: true,
+    italic: true,
+    bold_italic: true,
+    inline_code: true,
+    strikethrough: true,
+    links: true,
+    images: true,
+    block_math: true,
+    inline_math: false,
+    setext_headings: true,
+    comparison_operators: true,
+    html_tags: true,
+    single_tilde: true,
+    dangling_escape: true,
+    app_tags: APP_TAGS,
+    link_mode: :protocol,
+    handlers: []
+  }.freeze
+
+  # The accepted values for the `link_mode:` option: `:protocol` and
+  # `:text_only`. Both are described under MaquinaRemend::DEFAULTS.
+  LINK_MODES = %i[protocol text_only].freeze
+
+  # Base class for everything this gem raises, so a host can rescue the library
+  # as a whole without naming each error.
+  class Error < StandardError; end
+
+  # Raised when MaquinaRemend.call is given an option key that is not in
+  # MaquinaRemend::DEFAULTS, or a `link_mode:` outside
+  # MaquinaRemend::LINK_MODES.
+  #
+  # Unknown options are an error rather than a silent no-op: a misspelled flag
+  # would otherwise leave a repair quietly enabled that the host believed it had
+  # turned off.
+  class UnknownOption < Error; end
+
+  # Repairs the tail of `markdown` and returns the result.
+  #
+  # ```ruby
+  # MaquinaRemend.call(markdown, **options) # => String
+  # ```
+  #
+  # * `markdown` — the buffer so far, including its incomplete tail. `nil` and
+  #   the empty string are returned exactly as they came in.
+  # * `options` — any subset of MaquinaRemend::DEFAULTS.
+  # * Returns a `String` a markdown parser can render without producing
+  #   half-open constructs.
+  # * Raises MaquinaRemend::UnknownOption for an option key outside
+  #   MaquinaRemend::DEFAULTS, or a `link_mode:` outside
+  #   MaquinaRemend::LINK_MODES.
+  #
+  # The buffer is scanned once, passed through the built-in handlers in
+  # MaquinaRemend::Pipeline::BUILT_INS order, then through any handlers given in
+  # `handlers:`.
+  #
+  # ```ruby
+  # MaquinaRemend.call("A **bold run that is still")
+  # # => "A **bold run that is still**"
+  #
+  # MaquinaRemend.call("costs $5", inline_math: true)
+  # # => "costs $5$"   -- which is why inline_math is off by default
+  #
+  # MaquinaRemend.call("[label](https://exa", link_mode: :text_only)
+  # # => "label"
+  # ```
+  #
+  # ## Custom handlers
+  #
+  # A handler is any object that responds to `#call(text, context)` and returns
+  # the buffer — repaired, or untouched. There is no class to inherit from and
+  # no registration step.
+  #
+  # ```ruby
+  # class MyHandler
+  #   def call(text, context) # context: MaquinaRemend::Context
+  #     return text if context.in_code_fence?
+  #
+  #     text.end_with?("::") ? text + " " : text
+  #   end
+  # end
+  #
+  # MaquinaRemend.call(markdown, handlers: [MyHandler.new])
+  # ```
+  #
+  # The contract, in full:
+  #
+  # * **Arity is two.** `text` is the buffer as the built-ins left it; `context`
+  #   is a MaquinaRemend::Context describing where the tail sits.
+  # * **Return a String.** Returning the argument unchanged is the normal
+  #   outcome; most passes over most buffers repair nothing.
+  # * **Custom handlers run last**, in the order given, each one seeing the
+  #   previous one's output.
+  # * **Unlike the built-ins, a custom handler still runs inside a fenced code
+  #   block.** It is given the context and trusted to decide, which it could not
+  #   do if the pipeline had already returned. Ask
+  #   MaquinaRemend::Context#in_code_fence? and return early if a fence should
+  #   stop you.
+  # * **Stay idempotent, and stay byte-identical on well-formed input.** Those
+  #   two properties belong to the library, not just to the built-ins, and a
+  #   handler that appends unconditionally breaks both — the text it appended
+  #   dangles on the next pass and gets appended to again.
+  #
+  # A handler is not given the MaquinaRemend::Scanner. Context is deliberately
+  # the whole of what a handler may know; a repair that needs more state than it
+  # exposes is a sign the scanner is missing a state, not a sign that the
+  # context object should grow.
+  def self.call(markdown, **options)
+    Pipeline.new(**options).call(markdown)
+  end
+
+  # The scanner's view of a buffer, without repairing it. Callers that need to
+  # know whether the tail sits inside a fence - a renderer deciding whether to
+  # highlight, for one - should ask this rather than reach into Scanner.
+  #
+  # ```ruby
+  # context = MaquinaRemend.context("~~~ruby\ndef call")
+  # context.in_code_fence?  # => true
+  # context.open_fence_info # => "ruby"
+  # ```
+  #
+  # * `markdown` — the buffer so far; coerced with `#to_s`, so `nil` is a valid
+  #   argument and reads as an empty document.
+  # * Returns a MaquinaRemend::Context: the three states a handler is allowed to
+  #   ask about, plus the open fence's info string.
+  def self.context(markdown)
+    Scanner.new(markdown.to_s).context
+  end
+end