mdom 0.3.0 → 0.4.0

data/lib/mdom/block_detector.rb

@@ -18,7 +18,7 @@ module MDOM
   # 会让一处错误波及全篇。
   class BlockDetector
     # 会引导块的关键字（CSM §3.5.1 的 B 类）。大小写严格匹配。
-    GUIDING_KEYWORDS = %w[begin while until for if unless case def class module do].freeze
+    GUIDING_KEYWORDS = %w[begin while until for if unless case def class module].freeze
 
     # 关键字 → Prism 节点类。
     KEYWORD_NODES = {
@@ -41,6 +41,48 @@ module MDOM
     # * +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+。
@@ -51,76 +93,260 @@ module MDOM
       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 块范围内**进行（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
+      # 增量 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
 
-        node = result.value.statements.body.last
-        next if node.nil?
-        # 顶层语句必须恰好从候选行开始、到当前行结束；一旦成立就说明
-        # 「从候选行起的一个完整 Ruby 语句到此为止」，无论是否匹配块结构，
-        # 都不必再往下扩展。
-        next unless covers?(node, code, line_count)
+    # 解析一个前缀并给出结论：+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?
 
-        match = kind == :keyword ? keyword_match(node, keyword) : call_match(node)
-        return nil unless match
+      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)
-        assert_no_heredoc!(code, start_index, last)
         return Detection.new(end_index: last, form: match[:form], render: match[:render])
       end
+      return :continue if !closing && leading_continuation?(lines, last)
+
       nil
     end
 
-    private
+    # 对闭合候选行做分治：找到**最早**一个不再 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
 
-    # 候选所在的 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
+      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
-      lines.size - 1
+      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
 
-    # 收窄：行首词是引导块关键字 → B 类；否则行首是字母 → A 类；否则不判定。
+    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 [nil, nil] unless word
-
-      if GUIDING_KEYWORDS.include?(word)
-        [:keyword, word]
-      elsif first.match?(/\A[A-Za-z]/)
-        [:call, nil]
-      else
-        [nil, nil]
+      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)
-      result = Prism.parse(code)
-      result.success? ? result : nil
+      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.length
+        loc.end_column == last_line.bytesize
     end
 
     # A 类：`CallNode`（一个或多个）→ 带 `closing_loc` 的 `BlockNode`。
@@ -134,14 +360,33 @@ module MDOM
       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
-        return { form: :free, render: render } if block.is_a?(Prism::BlockNode) && block.closing_loc
+        match ||= { form: :free, render: render } if block.is_a?(Prism::BlockNode) && block.closing_loc
 
         cursor = cursor.receiver
       end
-      nil
+      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 给出的节点类必须与首行关键字一致。
@@ -169,29 +414,17 @@ module MDOM
 
       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" }
+              "(line #{start_index + 1}) but closes with #{found} (line #{last_index + 1})"
     end
 
+    # 与 Tokenizer#indent_width 同一实现（见那里的说明）。
     def indent_width(line)
-      line[/\A[ \t]*/].to_s.length
+      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..]