mdom 0.2.0 → 0.4.0

data/lib/mdom/block_detector.rb

@@ -0,0 +1,433 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "error"
+
+module MDOM
+  # 用 Ruby 官方解析器（Prism）判定「不带 `begin` 前缀的 Ruby 块」与
+  # 「引导块关键字段落」（CSM §3.5）。
+  #
+  # 之所以必须交给 Prism，是因为 `do` / `end` 在英语里也是常见单词，纯词法
+  # 无法区分「Ruby 块」与「英文散文」（CSM §3.5.1）。判定只在 CSM → AST1
+  # 这一侧发生（docs/IMPLEMENTATION.md §1.1）；AST1 一旦产出，后续阶段不再
+  # 需要任何词法能力。
+  #
+  # 判定按候选块**增量 parse**（CSM §3.5.4）：从候选行开始逐行增加，只解析
+  # 这一段，而不是整篇一次解析——文档里的英文散文可能构成语法错误，整篇解析
+  # 会让一处错误波及全篇。
+  class BlockDetector
+    # 会引导块的关键字（CSM §3.5.1 的 B 类）。大小写严格匹配。
+    GUIDING_KEYWORDS = %w[begin while until for if unless case def class module].freeze
+
+    # 关键字 → Prism 节点类。
+    KEYWORD_NODES = {
+      "begin" => Prism::BeginNode,
+      "while" => Prism::WhileNode,
+      "until" => Prism::UntilNode,
+      "for" => Prism::ForNode,
+      "if" => Prism::IfNode,
+      "unless" => Prism::UnlessNode,
+      "case" => Prism::CaseNode,
+      "def" => Prism::DefNode,
+      "class" => Prism::ClassNode,
+      "module" => Prism::ModuleNode
+    }.freeze
+
+    # 判定结果。
+    #
+    # * +end_index+ —— 块尾行在 +lines+ 中的下标（0 起）；
+    # * +form+ —— +:begin+（B 类）/ +:free+（A 类）；
+    # * +render+ —— 是否以 `.render` 收尾。
+    Detection = Struct.new(:end_index, :form, :render, keyword_init: true)
+
+    # 候选开始后无条件尝试解析的行数（不论该行是否含 `end` / `}`）。散文候选通常
+    # 在第一行就是硬语法错误或完整非块语句，这一小段探针能让它立刻退出，避免把
+    # 整篇文档拼进 code、再到每个闭合行上重复 parse（见 docs/IMPLEMENTATION.md §2.2.4）。
+    EARLY_PROBE_LINES = 4
+
+    # C1-min 的 A 类候选开头。`[` 还要在 #classify 里排除 `[[`（WikiLink 优先）。
+    CANDIDATE_PREFIXES = ["(", "{", "%", "_", "::", "["].freeze
+
+    # 行首是否落在 A 类候选的预筛范围内（字母或 CANDIDATE_PREFIXES）。
+    def self.candidate_start?(content)
+      content.match?(/\A[A-Za-z]/) ||
+        CANDIDATE_PREFIXES.any? { |prefix| content.start_with?(prefix) }
+    end
+
+    # 判定器的配置。
+    #
+    # * +free_blocks:+ —— **A 类（自由块）判定的总开关**，默认 +true+（CSM §3.5）。
+    #   置 +false+ 时不做任何 A 类判定，命中行按**排版**处理（CSM §3.5.3，不报错）。
+    #   B 类（引导关键字）与 `~` 行不受影响。
+    # * +free_blocks_allowed:+ —— A 类的**白名单**，默认 +nil+（不限制）。给出后，
+    #   只有行首标识符命中的行才尝试 A 类判定：+String+ 按标识符**精确相等**匹配
+    #   （大小写严格），+Regexp+ 对**已剥离 CSM 缩进的整行**做 +match?+（要不要锚定
+    #   行首由自己写的 `\A` 决定）。空数组等价于 +free_blocks: false+。
+    #
+    # 之所以要这道闸门：英文散文里「以字母开头的行」比比皆是，每行都交给 Prism
+    # 增量 parse 会让一篇普通文档产生几百到上万次调用（docs/IMPLEMENTATION.md §2.2.4）。
+    def initialize(free_blocks: true, free_blocks_allowed: nil)
+      @free_blocks = free_blocks
+      @free_blocks_allowed = free_blocks_allowed
+    end
+
+    # 行首是否值得进入块判定——CSM §3.5.4 的「收窄」，外加 A 类门控。
+    #
+    # Tokenizer 用它做预筛，从而对注定不会被判定的行连 +detect+ 都不必调用。
+    # +first+ 是**已剥离 CSM 缩进**的首行内容。B 类与引导关键字一律值得判定。
+    def candidate?(first)
+      kind, = classify(first)
+      return false unless kind
+
+      kind == :keyword || free_block_candidate?(first)
+    end
+
+    # 在 +lines+（已规范化：tab 展开、去 `\r`）中，从 +start_index+ 起判定候选块。
+    #
+    # +indent+ 是候选行的 CSM 缩进（前导空格数）。返回 +Detection+ 或 +nil+。
+    #
+    # 抛出 +CrossLevelError+，当 Prism 判定为块、但块尾行的缩进与块首行不同
+    # （CSM §3.5.2 条件 1）。
+    def detect(lines, start_index, indent)
+      first = drop_indent(lines[start_index], indent)
+      kind, keyword = classify(first)
+      return nil unless kind
+      # A 类被关掉或行首不在白名单里 → 按排版处理，且**在碰 Prism 之前**就收手。
+      return nil if kind == :call && !free_block_candidate?(first)
+
+      # 增量 parse 只在**候选行到同级块尾的范围内**进行（CSM §3.5.4）：范围由更浅
+      # 的缩进收尾，**空行不中断**——块内的空行是 Ruby 的普通空行，交给 prism 决定
+      # 块的实际收尾。先无条件探前几行，让散文候选就地失败。
+      code = String.new
+      cursor = start_index
+      early_stop = [start_index + EARLY_PROBE_LINES - 1, lines.size - 1].min
+
+      while cursor <= early_stop
+        line = lines[cursor]
+        boundary = cursor > start_index && boundary_line?(line, indent)
+        code << drop_indent(line, indent) << "\n"
+
+        verdict = evaluate(code, lines, start_index, cursor, indent, kind, keyword,
+                           closing: closing_line?(line))
+        return verdict unless verdict == :continue
+        return nil if boundary
+
+        cursor += 1
+      end
+      return nil if cursor >= lines.size
+
+      closers = closing_candidates(lines, cursor, indent)
+      return nil if closers.empty?
+
+      source, offsets = prefix_source(lines, start_index, closers.last, indent)
+      divide_and_conquer(source, offsets, lines, start_index, closers,
+                         indent, kind, keyword)
+    end
+
+    private
+
+    # 解析一个前缀并给出结论：+Detection+ / +nil+ / +:continue+。
+    # +closing+ 为 false 时，完整但非块的前缀还要检查下一行是否是 Ruby 的
+    # leading-dot 续行（`foo\n  .each do ... end`）。
+    def evaluate(code, lines, start_index, last, indent, kind, keyword,
+                 closing:, result: nil)
+      result ||= parse(code)
+      return nil if result.nil?
+      # 错误恢复可能把散文解析成 message_loc 为空（长度为 0 / 不存在）的
+      # CallNode，例如 `I do this till end.`；这种节点不能作为自由块。
+      return nil if kind == :call && result.failure? && empty_call_message?(result)
+      return :continue if result.failure? && incomplete?(result, code)
+      return nil unless result.success?
+
+      statements = result.value.statements.body
+      # 顶层已经不止一条语句：第一条既已闭合，再追加行也覆盖不到整段。
+      return nil if statements.size >= 2
+
+      node = statements.last
+      return :continue if node.nil?
+
+      line_count = last - start_index + 1
+      loc = node.location
+      last_line = code.lines.last.to_s.rstrip
+      covers = loc.start_line == 1 &&
+               loc.start_column.zero? &&
+               loc.end_line == line_count &&
+               loc.end_column == last_line.bytesize
+      return :continue unless covers
+
+      match = kind == :keyword ? keyword_match(node, keyword) : call_match(node)
+      if match
+        assert_same_indent!(lines, start_index, last, indent)
+        return Detection.new(end_index: last, form: match[:form], render: match[:render])
+      end
+      return :continue if !closing && leading_continuation?(lines, last)
+
+      nil
+    end
+
+    # 对闭合候选行做分治：找到**最早**一个不再 incomplete 的前缀。真实块在闭合前
+    # 始终 incomplete，闭合后才会成为完整语句，于是可以在候选下标上二分，而不是逐个
+    # 闭合行调用 Prism。
+    def divide_and_conquer(source, offsets, lines, start_index, closers,
+                           indent, kind, keyword)
+      low = 0
+      high = closers.size - 1
+      first = nil
+      cached = nil
+
+      while low <= high
+        mid = (low + high) / 2
+        last = closers[mid]
+        code = prefix(source, offsets, start_index, last)
+        result = parse(code)
+        return nil if result.nil?
+        return nil if kind == :call && result.failure? && empty_call_message?(result)
+
+        if result.failure? && incomplete?(result, code) && !first_statement_closed?(result)
+          low = mid + 1
+        else
+          first = mid
+          cached = [last, code, result]
+          high = mid - 1
+        end
+      end
+      return nil if first.nil?
+
+      last, code, result = cached
+      verdict = evaluate(code, lines, start_index, last, indent, kind, keyword,
+                         closing: true, result: result)
+      return verdict unless verdict == :continue
+
+      (first + 1...closers.size).each do |index|
+        last = closers[index]
+        code = prefix(source, offsets, start_index, last)
+        verdict = evaluate(code, lines, start_index, last, indent, kind, keyword, closing: true)
+        return verdict unless verdict == :continue
+      end
+      nil
+    end
+
+    # 前缀末尾可能落在后续散文的未完成构造里，使整段 parse 报 incomplete；但第一个
+    # 顶层语句其实已经闭合。此时不能把它当成“块还没结束”而向右二分。
+    def first_statement_closed?(result)
+      node = result.value.statements.body.first
+      return false if node.nil?
+
+      location = node.location
+      return false unless location.start_line == 1 && location.start_column.zero?
+
+      result.errors.all? { |error| error.location.start_offset > location.end_offset }
+    end
+
+    def prefix(source, offsets, start_index, last)
+      source.byteslice(0, offsets[last - start_index])
+    end
+
+    # 一次性构造候选到最后一个闭合行的源码，并记下每行结束的字节偏移；分治的各次
+    # 探测只需要 byteslice，不再反复 map/join。
+    def prefix_source(lines, start_index, last_index, indent)
+      parts = Array.new(last_index - start_index + 1)
+      offsets = Array.new(parts.size)
+      bytes = 0
+
+      parts.each_index do |index|
+        text = drop_indent(lines[start_index + index], indent)
+        parts[index] = text
+        bytes += text.bytesize + 1
+        offsets[index] = bytes
+      end
+
+      ["#{parts.join("\n")}\n", offsets]
+    end
+
+    # 闭合行候选：含 `end` 或 `}`，且与旧实现使用同一套正则收窄。扫描到同级块尾
+    # （更浅的非空行，包含在内）为止。
+    def closing_candidates(lines, from, indent)
+      candidates = []
+      cursor = from
+
+      while cursor < lines.size
+        line = lines[cursor]
+        candidates << cursor if closing_line?(line)
+        break if boundary_line?(line, indent)
+
+        cursor += 1
+      end
+      candidates
+    end
+
+    def closing_line?(line)
+      return false unless line.include?("end") || line.include?("}")
+
+      line =~ /(([^A-Za-z0-9_-]|^)end([^A-Za-z0-9_-]|$))|(})/
+    end
+
+    # 非空且缩进比块首更浅的行是块尾边界；它**包含在候选范围内**，供跨级缩进校验。
+    def boundary_line?(line, indent)
+      !line.strip.empty? && indent_width(line) < indent
+    end
+
+    # Ruby 的 leading-dot 续行：`foo` 下一行以 `.` / `&.` 开头时仍属于同一表达式，
+    # 因此完整但非块的前缀不能立刻判死。空行与注释行跳过（保守处理）。
+    def leading_continuation?(lines, index)
+      cursor = index + 1
+
+      while cursor < lines.size
+        stripped = lines[cursor].strip
+        if stripped.empty? || stripped.start_with?("#")
+          cursor += 1
+          next
+        end
+
+        return stripped.start_with?(".") || stripped.start_with?("&.")
+      end
+      false
+    end
+
+    # 收窄：行首词是引导块关键字 → B 类；否则字母或 C1-min 开头 → A 类。
+    # `[[` 一律按 WikiLink 处理，不进入 Ruby 候选；`__END__` 留给 Tokenizer。
+    def classify(first)
+      return [nil, nil] if first == "__END__" || first.start_with?("[[")
+
+      word = first[/\A[A-Za-z_][A-Za-z0-9_]*/]
+      return [:keyword, word] if word && GUIDING_KEYWORDS.include?(word)
+      return [:call, nil] if self.class.candidate_start?(first)
+
+      [nil, nil]
+    end
+
+    # A 类（自由块）的候选资格：总开关 + 白名单。
+    #
+    # 与 +classify+ 共用同一条「行首标识符」定义，所以白名单里的 +String+ 与
+    # B 类关键字一样是**精确相等**（`"list"` 不匹配 `lists.each do`），不做前缀模糊。
+    def free_block_candidate?(first)
+      return false unless @free_blocks
+      return true if @free_blocks_allowed.nil?
+
+      word = first[/\A[A-Za-z_][A-Za-z0-9_]*/]
+      @free_blocks_allowed.any? do |entry|
+        entry.is_a?(Regexp) ? entry.match?(first) : entry == word
+      end
+    end
+
+    def parse(code)
+      Prism.parse(code)
+    rescue StandardError
+      nil
+    end
+
+    # 解析失败是否只是「还缺东西」：
+    #
+    # * prism 把错误报在**输入末尾**（`unexpected end-of-input`），或
+    # * 报成 +*_term+——缺 `end` / `)` / `]` 等收尾（`case x` 的 +case_term+ 属此类，
+    #   它的错误位置在构造起始处而非末尾，光看末尾看不出来）。
+    #
+    # 以上都值得再加一行试试，其余是行内已定的硬错误、加多少行也补不上。末尾空白
+    # （含换行）会被 prism 跳过，因此 EOF 位置取 +rstrip+ 之后的字节数。
+    # （+Prism::ParseError#type+ 是 prism 的内部符号，这里只当提示用，取不到就退回
+    # 「只看末尾」。）
+    def incomplete?(result, code)
+      eof = code.rstrip.bytesize
+      result.errors.any? { |error| error.location.start_offset >= eof || terminator?(error) }
+    end
+
+    def terminator?(error)
+      # error.respond_to?(:type) && error.type.to_s.include?("_term")
+      error.type.to_s.include?("_term") # 有大概20%的性能提升，且未产生错误
+    end
+
+    # 顶层语句是否恰好覆盖「整段代码」。prism 的行内列号（+end_column+）按**字节**
+    # 计，因此这里比的是 +bytesize+，不是字符长度——否则末行含 CJK 时会误判为不覆盖，
+    # 循着空行一路追加到文末。
+    def covers?(node, code, line_count)
+      loc = node.location
+      last_line = code.lines.last.to_s.rstrip
+      loc.start_line == 1 &&
+        loc.start_column.zero? &&
+        loc.end_line == line_count &&
+        loc.end_column == last_line.bytesize
+    end
+
+    # A 类：`CallNode`（一个或多个）→ 带 `closing_loc` 的 `BlockNode`。
+    #
+    # 允许链上出现多个 `CallNode`，这自然覆盖了 `end.render` 这类收尾。
+    def call_match(node)
+      render = false
+      if render_call?(node)
+        render = true
+        node = node.receiver
+      end
+      return nil unless node.is_a?(Prism::CallNode)
+
+      match = nil
+      cursor = node
+      while cursor.is_a?(Prism::CallNode)
+        # 自由块必须是**有名字的**调用；`foo.() do ... end` 这种 message_loc 为空的
+        # 调用不算，避免把错误恢复出的空方法名当成 Ruby 块。
+        return nil if empty_message_loc?(cursor)
+
+        block = cursor.block
+        match ||= { form: :free, render: render } if block.is_a?(Prism::BlockNode) && block.closing_loc
+
+        cursor = cursor.receiver
+      end
+      match
+    end
+
+    def empty_message_loc?(node)
+      location = node.message_loc
+      location.nil? || location.start_offset == location.end_offset
+    end
+
+    # 错误恢复出的顶层语句可能是 message_loc 为空的 CallNode（如
+    # `I do this till end.`）；只检查顶层语句，避免遍历整棵错误恢复 AST。
+    # 成功结果由 #call_match 沿 receiver 链检查。
+    def empty_call_message?(result)
+      result.value.statements.body.any? do |node|
+        node.is_a?(Prism::CallNode) && empty_message_loc?(node)
+      end
+    end
+
+    # B 类：Prism 给出的节点类必须与首行关键字一致。
+    def keyword_match(node, keyword)
+      render = false
+      if render_call?(node)
+        render = true
+        node = node.receiver
+      end
+
+      expected = KEYWORD_NODES[keyword]
+      return nil unless expected && node.is_a?(expected)
+
+      { form: :begin, render: render }
+    end
+
+    def render_call?(node)
+      node.is_a?(Prism::CallNode) && node.name == :render && node.block.nil?
+    end
+
+    # CSM §3.5.2 条件 1：块首行与块尾行的缩进必须完全相同。
+    def assert_same_indent!(lines, start_index, last_index, indent)
+      found = indent_width(lines[last_index])
+      return if found == indent
+
+      raise CrossLevelError,
+            "ruby block opens with #{indent} space(s) of indentation " \
+              "(line #{start_index + 1}) but closes with #{found} (line #{last_index + 1})"
+    end
+
+    # 与 Tokenizer#indent_width 同一实现（见那里的说明）。
+    def indent_width(line)
+      line.index(/[^ \t]/) || line.length
+    end
+
+    def drop_indent(line, count)
+      return line if count.zero?
+
+      index = 0
+      index += 1 while index < count && index < line.length && line[index] == " "
+      line[index..]
+    end
+  end
+end