mdom 0.2.0 → 0.3.0

data/lib/mdom/block_detector.rb

@@ -0,0 +1,200 @@
+# 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 do].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)
+
+    # 在 +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
+
+      # 增量 parse 只在**候选所在的 CSM 块范围内**进行（CSM §3.5.4）：块由空行
+      # 或更浅的缩进收尾。逐行增加，直到解析成为以候选行起始的完整顶层语句，
+      # 立即给出结论——不做整篇一次解析，散文里的语法错误不会波及全篇。
+      (start_index..block_end(lines, start_index, indent)).each do |last|
+        line_count = last - start_index + 1
+        code = (start_index..last).map { |i| drop_indent(lines[i], indent) }.join("\n")
+        result = parse(code)
+        next unless result
+
+        node = result.value.statements.body.last
+        next if node.nil?
+        # 顶层语句必须恰好从候选行开始、到当前行结束；一旦成立就说明
+        # 「从候选行起的一个完整 Ruby 语句到此为止」，无论是否匹配块结构，
+        # 都不必再往下扩展。
+        next unless covers?(node, code, line_count)
+
+        match = kind == :keyword ? keyword_match(node, keyword) : call_match(node)
+        return nil unless match
+
+        assert_same_indent!(lines, start_index, last, indent)
+        assert_no_heredoc!(code, start_index, last)
+        return Detection.new(end_index: last, form: match[:form], render: match[:render])
+      end
+      nil
+    end
+
+    private
+
+    # 候选所在的 CSM 块的最后一行（CSM §1.1：块由空行或更浅的缩进收尾）。
+    #
+    # 更浅缩进的那一行**包含在内**——块尾缩进与块首不同时要能按 §3.5.2 报错，
+    # 而不是静默降级成排版。
+    def block_end(lines, start_index, indent)
+      (start_index + 1...lines.size).each do |i|
+        return i - 1 if lines[i].strip.empty?
+        return i if indent_width(lines[i]) < indent
+      end
+      lines.size - 1
+    end
+
+    # 收窄：行首词是引导块关键字 → B 类；否则行首是字母 → A 类；否则不判定。
+    def classify(first)
+      word = first[/\A[A-Za-z_][A-Za-z0-9_]*/]
+      return [nil, nil] unless word
+
+      if GUIDING_KEYWORDS.include?(word)
+        [:keyword, word]
+      elsif first.match?(/\A[A-Za-z]/)
+        [:call, nil]
+      else
+        [nil, nil]
+      end
+    end
+
+    def parse(code)
+      result = Prism.parse(code)
+      result.success? ? result : nil
+    rescue StandardError
+      nil
+    end
+
+    # 顶层语句是否恰好覆盖「整段代码」。
+    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.length
+    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)
+
+      cursor = node
+      while cursor.is_a?(Prism::CallNode)
+        block = cursor.block
+        return { form: :free, render: render } if block.is_a?(Prism::BlockNode) && block.closing_loc
+
+        cursor = cursor.receiver
+      end
+      nil
+    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
+
+    # CSM §3.12 / 附录 E：heredoc（`<<~SQL` 等）**明确不支持**。既然块判定本来就
+    # 要交给 Prism，就顺便让它把 heredoc 也认出来——被判定为块的内容里出现
+    # +HEREDOC_START+ 就报错，而不是当普通块收下。
+    def assert_no_heredoc!(code, start_index, last_index)
+      return unless heredoc?(code)
+
+      raise UnsupportedHeredocError,
+            "heredoc is not supported (CSM §3.12): " \
+            "line #{start_index + 1}..#{last_index + 1}"
+    end
+
+    def heredoc?(code)
+      Prism.lex(code).value.any? { |token, _state| token.type.to_s == "HEREDOC_START" }
+    end
+
+    def indent_width(line)
+      line[/\A[ \t]*/].to_s.length
+    end
+
+    def drop_indent(line, count)
+      index = 0
+      index += 1 while index < count && index < line.length && line[index] == " "
+      line[index..]
+    end
+  end
+end