polytypo 1.1.0 → 1.3.0

data/lib/polytypo/modes/spans.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../engine/origin"
 require_relative "../engine/sentinels"
 require_relative "../errors"
 
@@ -11,6 +12,9 @@ module Polytypo
     module Spans
       LINE_TERMINATORS = [0x0A, 0x0D, 0x0B, 0x0C, 0x85, 0x2028, 0x2029].freeze
 
+      # U+0020, the one emitted code point whose meaning is positional (modes.md 3.4, 5 item 2).
+      SPACE = 0x20
+
       # A processable span, identified by its offsets in the original source, addressed as
       # code-point indices (ARCHITECTURE.md section 4.2) -- Ruby String indices are already
       # code-point indices for a UTF-8 String, no separate byte/char distinction to manage here.
@@ -68,6 +72,19 @@ module Polytypo
         cp
       end
 
+      # The origin map for concatenate_spans (analyze.md section 2): for every code point of the
+      # joined array, the code-point offset of the character it came from IN THE DOCUMENT, and
+      # NO_ORIGIN for the markers, which came from nowhere. A Span's bounds are already
+      # code-point offsets, so no coordinate conversion belongs here.
+      def self.origin_of_spans(spans)
+        origin = []
+        spans.each_with_index do |span, i|
+          origin << Engine::Origin::NO_ORIGIN unless i.zero?
+          origin.concat((span.start...span.end).to_a)
+        end
+        origin
+      end
+
       # The span extents of the array as it stands. Recomputed after every rule, because applying
       # edits shifts every index after the first one -- the markers themselves always survive,
       # since no edit may contain one.
@@ -94,7 +111,13 @@ module Polytypo
       #  1. No edit may contain a marker -- one that does is a bug, discarded rather than
       #     redistributed.
       #  2. The edge-growth rule: an edit is discarded if it would place code points at an
-      #     extremity of its span that were not there before.
+      #     extremity of its span that were not there before. That sentence is the rule;
+      #     "r > d" alone is an incorrect formalisation of it and misses r == d. dashes P3
+      #     admits a run of THREE dashes, so "---" -> U+0020 en-dash U+0020 is 3 -> 3: the
+      #     length test sees nothing while U+0020 lands on both extremities anyway. The second
+      #     clause tests the CHARACTER, and only U+0020 needs testing -- it is the one code
+      #     point any rule emits whose meaning comes from its position rather than from itself
+      #     (modes.md 5 item 2).
       def self.filter_boundary_edits(cp, edits, ranges)
         edits.select do |edit|
           next false if (edit.start...edit.end).any? { |i| Engine.marker?(cp[i]) }
@@ -104,7 +127,12 @@ module Polytypo
           d = edit.end - edit.start
           r = edit.replacement.length
           span = span_containing(ranges, p)
-          !(span && r > d && (p == span.first || q == span.last))
+          next true unless span && (p == span.first || q == span.last)
+          next false if r > d
+          next false if r.positive? && p == span.first && edit.replacement[0] == SPACE && cp[p] != SPACE
+          next false if r.positive? && q == span.last && edit.replacement[r - 1] == SPACE && cp[q] != SPACE
+
+          true
         end
       end
 

data/lib/polytypo/modes/yaml.rb

@@ -0,0 +1,312 @@
+# frozen_string_literal: true
+
+module Polytypo
+  module Modes
+    # spec/rules/modes.md 3.8. "yaml" differs from the other two document modes twice over.
+    #
+    # It uses NO PARSER (3.8.1): two of the five ecosystems' YAML libraries cannot report the
+    # source offsets the round-trip guarantee needs, so the scan below is specified rather than
+    # delegated and is written the same way in every runtime.
+    #
+    # And the caller names the keys (3.8.2). YAML is a data format with islands of prose in it --
+    # the inverse of HTML and Markdown -- and nothing in its syntax separates "description:" from
+    # "run:". A keyless draft of this file rewrote "if !" as "if!" inside a workflow's shell
+    # script; there is no content test that would not, because shell and template expressions are
+    # written in words.
+    #
+    # It also SKIPS BY DEFAULT -- the inverse of 3.6's closed skip list. A construct this scan
+    # does not recognise with certainty yields no spans, so the worst outcome of a gap in it is
+    # prose left untypeset, never a changed byte.
+    module Yaml
+      SPACE = " "
+      TAB = "\t"
+      LF = "\n"
+      CR = "\r"
+      DECLINING_KEY_CHARS = ['"', "'", "{", "[", "&", "*", "!", "#"].freeze
+      NON_SCALAR_VALUE_CHARS = ["#", "&", "*", "!", "{", "["].freeze
+
+      Line = Struct.new(:start, :end)
+
+      # Offsets are code-point indices, like every Span in this runtime (ARCHITECTURE.md 4.2).
+      def self.yaml_spans(source, keys)
+        chars = source.chars
+        lines = split_lines(chars)
+        spans = []
+        li = 0
+        li = scan_line(chars, lines, li, keys, spans) while li < lines.length
+        spans
+      end
+
+      # 3.8.4: a line ends at U+000A, and A U+000D IMMEDIATELY BEFORE IT IS NOT PART OF THE LINE
+      # -- it is a terminator like the U+000A itself, so it lies outside every span and comes back
+      # untouched. Without that clause a CRLF file behaves differently from the same bytes with
+      # LF: the block header reads as "|\r" and is unrecognised, and a plain scalar carries the
+      # carriage return inside its span. Five runtimes split lines with five different standard
+      # library calls, so the treatment has to be stated rather than inherited.
+      def self.split_lines(chars)
+        lines = []
+        start = 0
+        end_of = ->(i) { i > start && chars[i - 1] == CR ? i - 1 : i }
+        chars.each_with_index do |ch, i|
+          next unless ch == LF
+
+          lines << Line.new(start, end_of.call(i))
+          start = i + 1
+        end
+        lines << Line.new(start, end_of.call(chars.length)) if start < chars.length
+        lines
+      end
+      private_class_method :split_lines
+
+      def self.first_non_space(chars, line)
+        i = line.start
+        i += 1 while i < line.end && chars[i] == SPACE
+        i
+      end
+      private_class_method :first_non_space
+
+      def self.blank?(chars, line)
+        first_non_space(chars, line) == line.end
+      end
+      private_class_method :blank?
+
+      def self.tab?(chars, line)
+        (line.start...line.end).any? { |i| chars[i] == TAB }
+      end
+      private_class_method :tab?
+
+      # 3.8.4 step 3. "---" and "..." at the head of a line, bare or introducing a node: the
+      # trailing-content form is declined too, so "--- key: value" never yields a key of
+      # "--- key".
+      def self.document_marker?(chars, from, to)
+        return false if to - from < 3
+
+        c = chars[from]
+        return false unless ["-", "."].include?(c)
+        return false unless chars[from + 1] == c && chars[from + 2] == c
+
+        from + 3 == to || chars[from + 3] == SPACE
+      end
+      private_class_method :document_marker?
+
+      # A colon that ends the line or is followed by U+0020 -- the only colon YAML reads as an
+      # indicator.
+      def self.indicator_colon?(chars, j, to)
+        return false unless chars[j] == ":"
+
+        j + 1 == to || chars[j + 1] == SPACE
+      end
+      private_class_method :indicator_colon?
+
+      def self.sequence_dash?(chars, j, to)
+        return false unless chars[j] == "-"
+
+        j + 1 == to || chars[j + 1] == SPACE
+      end
+      private_class_method :sequence_dash?
+
+      # The value run of 3.8.4 step 7: every following line that is blank or indented more than
+      # the key line. THOSE LINES ARE NEVER SCANNED AGAIN -- without that, a multi-line quoted
+      # scalar, a multi-line flow collection and a folded plain scalar all leak their continuation
+      # lines back into the scan as if they were mappings, and a span can end up holding a
+      # scalar's own closing delimiter.
+      def self.value_run_end(chars, lines, li, indent)
+        k = li + 1
+        while k < lines.length
+          nxt = lines[k]
+          break if !blank?(chars, nxt) && first_non_space(chars, nxt) - nxt.start <= indent
+
+          k += 1
+        end
+        k
+      end
+      private_class_method :value_run_end
+
+      # One step of 3.8.4. Returns the index of the next line to scan.
+      def self.scan_line(chars, lines, li, keys, spans)
+        line = lines[li]
+        skip_line = li + 1
+
+        # step 1 -- blank, or a tab anywhere, which makes indentation undecidable.
+        start = first_non_space(chars, line)
+        return skip_line if start == line.end || tab?(chars, line)
+
+        indent = start - line.start
+
+        # steps 2 and 3 -- comment, directive, document marker.
+        return skip_line if ["#", "%"].include?(chars[start])
+        return skip_line if document_marker?(chars, start, line.end)
+
+        # step 4 -- block sequence entries are consumed, not skipped; "- - key: v" nests.
+        i = start
+        while i < line.end && sequence_dash?(chars, i, line.end)
+          i += 2
+          i += 1 while i < line.end && chars[i] == SPACE
+        end
+        return skip_line if i >= line.end
+
+        # step 5 -- find the key. A colon NOT followed by U+0020 or the line end is an ordinary
+        # key character, so "a:b: v" has the key "a:b"; stating that is what keeps five scanners
+        # agreeing.
+        key_start = i
+        colon = -1
+        (i...line.end).each do |j|
+          return skip_line if DECLINING_KEY_CHARS.include?(chars[j])
+
+          if indicator_colon?(chars, j, line.end)
+            colon = j
+            break
+          end
+        end
+        return skip_line if colon.negative?
+
+        key_end = colon
+        key_end -= 1 while key_end > key_start && chars[key_end - 1] == SPACE
+        return skip_line if key_end <= key_start
+
+        # step 6 -- an empty value means a nested node, whose lines ARE scanned on their own.
+        v = colon + 1
+        v += 1 while v < line.end && chars[v] == SPACE
+        return skip_line if v >= line.end
+
+        # step 7 -- the line carries an inline value, so its continuation lines belong to it.
+        nxt = value_run_end(chars, lines, li, indent)
+
+        # step 8 -- the key must be listed. Checked before the value's form, so an unlisted key
+        # costs nothing to decline: this is what makes "run:", "if:" and "image:" unreachable.
+        return nxt unless keys.include?(chars[key_start...key_end].join)
+
+        # step 9 -- the scalar form.
+        value = chars[v]
+        return nxt if NON_SCALAR_VALUE_CHARS.include?(value)
+
+        if ["|", ">"].include?(value)
+          block_scalar(chars, line, lines[(li + 1)...nxt], indent, v, spans)
+        elsif ['"', "'"].include?(value)
+          quoted_scalar(chars, line, v, spans) if nxt == li + 1
+        elsif nxt == li + 1
+          plain_scalar(chars, line, v, spans)
+        end
+        nxt
+      end
+      private_class_method :scan_line
+
+      # 3.8.5. One span per non-blank content line, starting after the block's own indentation.
+      # The header, the indentation and every line terminator lie outside every span -- including
+      # the run of line terminators at the end that the chomping indicator governs, which is why
+      # "|", "|-", "|+", ">", ">-" and ">+" are handled identically here.
+      def self.block_scalar(chars, line, run_lines, indent, v, spans)
+        # The header: at most one chomping indicator and at most one indentation indicator, in
+        # either order, then optional spaces and an optional comment. Anything else is
+        # unrecognised.
+        h = v + 1
+        explicit_indent = 0
+        chomping = false
+        while h < line.end
+          c = chars[h]
+          if ["-", "+"].include?(c) && !chomping
+            chomping = true
+            h += 1
+          elsif c >= "1" && c <= "9" && explicit_indent.zero?
+            explicit_indent = c.ord - "0".ord
+            h += 1
+          else
+            break
+          end
+        end
+        h += 1 while h < line.end && chars[h] == SPACE
+        return if h < line.end && chars[h] != "#"
+
+        # One definition of the run, and three conditions that make the whole block yield no
+        # spans.
+        content = []
+        content_indent = -1
+        run_lines.each do |nxt|
+          next if blank?(chars, nxt) # blank lines belong to the block and yield no span
+
+          # A tab makes indentation undecidable; an explicit indicator that disagrees with the
+          # block as written, or a later line dedented inside it, is ambiguous rather than
+          # guessable. All three make the WHOLE block yield no spans -- bail rather than choose.
+          break content_indent = -1 if tab?(chars, nxt)
+
+          next_indent = first_non_space(chars, nxt) - nxt.start
+          if content_indent.negative?
+            content_indent = explicit_indent.positive? ? indent + explicit_indent : next_indent
+          end
+          break content_indent = -1 if next_indent < content_indent
+
+          content << nxt
+        end
+        return if content_indent <= 0
+
+        content.each do |c_line|
+          from = c_line.start + content_indent
+          spans << Spans::Span.new(from, c_line.end) if c_line.end > from
+        end
+      end
+      private_class_method :block_scalar
+
+      # 3.8.6. The span is the content between the quotes. Both bails exist so that source
+      # characters and content characters are the same thing, which the offset model of 3.1
+      # requires -- the same constraint that makes an HTML character reference an opaque unit in
+      # 3.6. No colon test applies here: quoting neutralises the colon, and applying the
+      # plain-scalar test would decline `title: "Chapter 1: the beginning"`.
+      def self.quoted_scalar(chars, line, v, spans)
+        quote = chars[v]
+        close = -1
+        j = v + 1
+        while j < line.end
+          c = chars[j]
+          return if quote == '"' && c == "\\"
+          return if quote == "'" && c == "'" && j + 1 < line.end && chars[j + 1] == "'"
+
+          if c == quote
+            close = j
+            break
+          end
+          j += 1
+        end
+        return if close.negative?
+
+        after = close + 1
+        after += 1 while after < line.end && chars[after] == SPACE
+        return if after < line.end && chars[after] != "#"
+
+        spans << Spans::Span.new(v + 1, close) if close > v + 1
+      end
+      private_class_method :quoted_scalar
+
+      # 3.8.6. In a plain scalar ":" and "#" are still live: U+0020 beside either of them is what
+      # turns a scalar into a mapping indicator or a comment, and `dashes` emits U+0020 in every
+      # "-spaced" locale. Lifting both out as opaque units puts the dash token at a span
+      # extremity, where the edge-growth rule of 3.4 discards the replacement that emits one.
+      def self.plain_scalar(chars, line, v, spans)
+        # The scalar ends before a trailing comment, so a colon inside that comment is not the
+        # scalar's and must not decline it.
+        to = line.end
+        (v...line.end).each do |j|
+          if chars[j] == "#" && j > v && chars[j - 1] == SPACE
+            to = j - 1
+            break
+          end
+        end
+        to -= 1 while to > v && chars[to - 1] == SPACE
+        return if to <= v
+
+        # Compact nesting is not a value: "key: - item" opens a sequence, and "key: a .:" is a
+        # mapping whose key is "a ." -- a plain scalar can never contain a colon in that position.
+        return if sequence_dash?(chars, v, line.end)
+        return if (v...to).any? { |j| indicator_colon?(chars, j, line.end) }
+
+        segment = v
+        (v..to).each do |j|
+          next unless j == to || [":", "#"].include?(chars[j])
+
+          spans << Spans::Span.new(segment, j) if j > segment
+          segment = j + 1
+        end
+      end
+      private_class_method :plain_scalar
+    end
+  end
+end

data/lib/polytypo/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Polytypo
-  VERSION = "1.1.0"
+  VERSION = "1.3.0"
 end

data/lib/polytypo.rb

@@ -3,11 +3,13 @@
 require_relative "polytypo/version"
 require_relative "polytypo/errors"
 require_relative "polytypo/engine/codepoints"
+require_relative "polytypo/engine/origin"
 require_relative "polytypo/engine/pipeline"
 require_relative "polytypo/engine/rules" # side effect: registers all 9 rules
 require_relative "polytypo/modes/spans"
 require_relative "polytypo/modes/runner"
 require_relative "polytypo/modes/html"
+require_relative "polytypo/modes/yaml"
 
 # polytypo normalizes typography across languages: locale-correct quotes, dashes, ellipses,
 # apostrophes, symbols and no-break spaces, from a spec shared across every polytypo runtime
@@ -17,9 +19,12 @@ module Polytypo
   # Applies polytypo's rule pipeline to +input+ and returns the result.
   #
   # +locale+ is required, with no default -- an unknown locale raises Polytypo::Error with
-  # CODE_UNKNOWN_LOCALE; there is never a fallback to English. +mode+ is "text" (default), "html"
-  # or "markdown". +dialect+ is required iff mode is "markdown" ("commonmark"; "mdx" is not
-  # implemented by this runtime). +rules+ is an opt-out Hash keyed by rule id.
+  # CODE_UNKNOWN_LOCALE; there is never a fallback to English. +mode+ is "text" (default),
+  # "html", "markdown" or "yaml". +dialect+ is required iff mode is "markdown" ("commonmark";
+  # "mdx" is not implemented by this runtime). +keys+ is required iff mode is "yaml" and names
+  # the mapping keys whose scalar values are prose (modes.md 3.8.2) -- it has no default, because
+  # nothing in YAML's syntax separates "description:" from "run:". +rules+ is an opt-out Hash
+  # keyed by rule id.
   #
   # Pure: no I/O, no environment, no clock, no globals, no class-level mutable state --
   # thread-safe and reentrant, callable concurrently from any number of Threads with no external
@@ -27,22 +32,65 @@ module Polytypo
   #
   # Only `mode: "text"`/`"html"` ever touch this file's own requires; `mode: "markdown"` lazily
   # requires "commonmarker" from within Modes::Markdown, never at load time of this file.
-  def self.transform(input, locale:, mode: "text", dialect: nil, rules: nil)
+  def self.transform(input, locale:, mode: "text", dialect: nil, keys: nil, rules: nil, narrow_nbsp: nil)
     resolved_mode = resolve_mode(mode)
+    narrow_target = Engine.resolve_narrow_target(narrow_nbsp)
 
     case resolved_mode
     when "text"
       if dialect
         raise Error.new(CODE_INVALID_DIALECT, '"dialect" is only valid when mode is "markdown"')
       end
-      transform_text(input, locale, rules)
+      transform_text(input, locale, rules, narrow_target)
     when "html"
       if dialect
         raise Error.new(CODE_INVALID_DIALECT, '"dialect" is only valid when mode is "markdown"')
       end
-      transform_html(input, locale, rules)
+      transform_html(input, locale, rules, narrow_target)
+    when "yaml"
+      if dialect
+        raise Error.new(CODE_INVALID_DIALECT, '"dialect" is only valid when mode is "markdown"')
+      end
+      transform_yaml(input, locale, keys, rules, narrow_target)
+    else # "markdown"
+      transform_markdown(input, locale, dialect, rules, narrow_target)
+    end
+  end
+
+  # Runs the same pipeline as .transform and reports what it would do instead of doing it
+  # (spec/rules/analyze.md), returning an Array of Polytypo::Engine::Change. Offsets are
+  # code-point offsets into +input+ in every mode -- into the document, in "html" and "markdown"
+  # mode, not into a span.
+  #
+  # What it guarantees: the list is empty exactly when .transform would return the input
+  # unchanged, every +rule_id+ was enabled for the call, and every offset is inside the input.
+  # What it does not: the list is a report, not a patch -- two rules may touch the same original
+  # range, so replaying it is not guaranteed to reproduce .transform's output. Call .transform
+  # for the text (analyze.md sections 4 and 5).
+  #
+  # Pure and thread-safe on the same terms as .transform.
+  def self.analyze(input, locale:, mode: "text", dialect: nil, keys: nil, rules: nil, narrow_nbsp: nil)
+    resolved_mode = resolve_mode(mode)
+    narrow_target = Engine.resolve_narrow_target(narrow_nbsp)
+
+    case resolved_mode
+    when "text"
+      if dialect
+        raise Error.new(CODE_INVALID_DIALECT, '"dialect" is only valid when mode is "markdown"')
+      end
+      analyze_text(input, locale, rules, narrow_target)
+    when "html"
+      if dialect
+        raise Error.new(CODE_INVALID_DIALECT, '"dialect" is only valid when mode is "markdown"')
+      end
+      analyze_html(input, locale, rules, narrow_target)
+    when "yaml"
+      if dialect
+        raise Error.new(CODE_INVALID_DIALECT, '"dialect" is only valid when mode is "markdown"')
+      end
+      analyze_yaml(input, locale, keys, rules, narrow_target)
     else # "markdown"
-      transform_markdown(input, locale, dialect, rules)
+      analyze_markdown(input, locale, dialect, rules, narrow_target)
     end
   end
 
@@ -50,42 +98,105 @@ module Polytypo
     case mode
     when nil, "text"
       "text"
-    when "html", "markdown"
+    when "html", "markdown", "yaml"
       mode
     else
-      raise Error.new(CODE_INVALID_MODE, "unknown mode #{mode.inspect}. Expected \"text\", \"html\" or \"markdown\"")
+      raise Error.new(CODE_INVALID_MODE,
+                      "unknown mode #{mode.inspect}. Expected \"text\", \"html\", \"markdown\" or \"yaml\"")
     end
   end
   private_class_method :resolve_mode
 
-  def self.transform_text(input, locale, rules)
+  def self.transform_text(input, locale, rules, narrow_target)
     _resolved, locale_data, plan = Engine::Pipeline.prepare(locale, rules)
     cp = Engine::Codepoints.to_codepoints(input)
-    ctx = Engine::RuleContext.new(mode: "text", dialect: nil, locale: locale)
+    ctx = Engine::RuleContext.new(mode: "text", dialect: nil, locale: locale,
+                                  narrow_target: narrow_target)
     result = Engine::Pipeline.run_rules(cp, plan, locale_data, ctx)
     Engine::Codepoints.from_codepoints(result)
   end
   private_class_method :transform_text
 
-  def self.transform_html(input, locale, rules)
+  def self.transform_html(input, locale, rules, narrow_target)
     resolved_locale, locale_data, plan = Engine::Pipeline.prepare(locale, rules)
     spans = Modes::Html.html_spans(input)
-    ctx = Engine::RuleContext.new(mode: "html", dialect: nil, locale: resolved_locale)
+    ctx = Engine::RuleContext.new(mode: "html", dialect: nil, locale: resolved_locale,
+                                  narrow_target: narrow_target)
     cp = Engine::Codepoints.to_codepoints(input)
     Modes::Runner.run_over_spans(cp, spans, plan, locale_data, ctx)
   end
   private_class_method :transform_html
 
-  def self.transform_markdown(input, locale, dialect, rules)
+  # "yaml" mode: the only pipeline here with no parser dependency at all -- span selection is the
+  # specified scan of modes.md 3.8, not a library. There is likewise no CODE_MALFORMED_INPUT
+  # counterpart: with no declared grammar to violate, a file that is not YAML yields few spans or
+  # none and comes back byte for byte (modes.md 3.8.3). The only raise this mode adds is +keys+,
+  # which is about the call and not the input.
+  def self.transform_yaml(input, locale, keys, rules, narrow_target)
+    resolved_locale, locale_data, plan = Engine::Pipeline.prepare(locale, rules)
+    resolved_keys = Engine.resolve_yaml_keys(keys)
+    spans = Modes::Yaml.yaml_spans(input, resolved_keys)
+    ctx = Engine::RuleContext.new(mode: "yaml", dialect: nil, locale: resolved_locale,
+                                  narrow_target: narrow_target)
+    cp = Engine::Codepoints.to_codepoints(input)
+    Modes::Runner.run_over_spans(cp, spans, plan, locale_data, ctx)
+  end
+  private_class_method :transform_yaml
+
+  def self.transform_markdown(input, locale, dialect, rules, narrow_target)
     # Validation order is public, tested behaviour, identical across every runtime: rules (an
     # unknown rule id), then locale (an unknown locale), then dialect/parsing.
     resolved_locale, locale_data, plan = Engine::Pipeline.prepare(locale, rules)
     require_relative "polytypo/modes/markdown"
     Modes::Markdown.resolve_dialect(dialect)
     spans = Modes::Markdown.markdown_spans(input)
-    ctx = Engine::RuleContext.new(mode: "markdown", dialect: dialect, locale: resolved_locale)
+    ctx = Engine::RuleContext.new(mode: "markdown", dialect: dialect, locale: resolved_locale,
+                                  narrow_target: narrow_target)
     cp = Engine::Codepoints.to_codepoints(input)
     Modes::Runner.run_over_spans(cp, spans, plan, locale_data, ctx)
   end
   private_class_method :transform_markdown
+
+  def self.analyze_text(input, locale, rules, narrow_target)
+    _resolved, locale_data, plan = Engine::Pipeline.prepare(locale, rules)
+    cp = Engine::Codepoints.to_codepoints(input)
+    ctx = Engine::RuleContext.new(mode: "text", dialect: nil, locale: locale,
+                                  narrow_target: narrow_target)
+    Engine::Pipeline.run_rules_recording(cp, plan, locale_data, ctx, (0...cp.length).to_a, cp.length)
+  end
+  private_class_method :analyze_text
+
+  def self.analyze_html(input, locale, rules, narrow_target)
+    resolved_locale, locale_data, plan = Engine::Pipeline.prepare(locale, rules)
+    spans = Modes::Html.html_spans(input)
+    ctx = Engine::RuleContext.new(mode: "html", dialect: nil, locale: resolved_locale,
+                                  narrow_target: narrow_target)
+    Modes::Runner.analyze_over_spans(Engine::Codepoints.to_codepoints(input), spans, plan, locale_data, ctx)
+  end
+  private_class_method :analyze_html
+
+  # analyze.md section 1, "yaml" mode: offsets are into the document, not into a span
+  # (analyze.md section 6).
+  def self.analyze_yaml(input, locale, keys, rules, narrow_target)
+    resolved_locale, locale_data, plan = Engine::Pipeline.prepare(locale, rules)
+    resolved_keys = Engine.resolve_yaml_keys(keys)
+    spans = Modes::Yaml.yaml_spans(input, resolved_keys)
+    ctx = Engine::RuleContext.new(mode: "yaml", dialect: nil, locale: resolved_locale,
+                                  narrow_target: narrow_target)
+    Modes::Runner.analyze_over_spans(Engine::Codepoints.to_codepoints(input), spans, plan, locale_data, ctx)
+  end
+  private_class_method :analyze_yaml
+
+  def self.analyze_markdown(input, locale, dialect, rules, narrow_target)
+    # Validation order is public, tested behaviour and is shared with .transform: rules, then
+    # locale, then dialect/parsing (analyze.md section 4, A1).
+    resolved_locale, locale_data, plan = Engine::Pipeline.prepare(locale, rules)
+    require_relative "polytypo/modes/markdown"
+    Modes::Markdown.resolve_dialect(dialect)
+    spans = Modes::Markdown.markdown_spans(input)
+    ctx = Engine::RuleContext.new(mode: "markdown", dialect: dialect, locale: resolved_locale,
+                                  narrow_target: narrow_target)
+    Modes::Runner.analyze_over_spans(Engine::Codepoints.to_codepoints(input), spans, plan, locale_data, ctx)
+  end
+  private_class_method :analyze_markdown
 end