[satoryu]

Why

After #199, Paragraph#substitute did everything in one ~40-line loop do … break … end:

• collect the w:t nodes and compute their offsets
• find the match and skip empty matches
• work out which w:t the match spans
• rewrite them

That made it hard to see what the method does.

What

The method body is now just "find the next match, replace it, move on":

def substitute(pattern, replacement)
  search_from = 0
  while (match = find_match(pattern, search_from))
    replaced = match[0].sub(pattern, replacement)
    replace_text_range(match.begin(0)...match.end(0), replaced)

    # advance past the inserted replacement so it is not re-matched
    search_from = match.begin(0) + replaced.length
  end
  self
end

with private helpers:

• find_match(pattern, from): the next match in the paragraph text, or nil. An empty match also gives nil, the same as the previous break.
• replace_text_range(range, string): replaces a range of the paragraph text across its w:t nodes. A single boundaries array (texts[i] spans boundaries[i]...boundaries[i + 1]) replaces the separate offsets and length arithmetic, and the single-node case returns early.
• text_nodes: the paragraph's w:t in document order.

No behavior change. The only cost is that the w:t XPath runs twice per match instead of once.

Verification

• Full suite passes (294 examples), including the Text Replacement not working as Expected #147 and substitute leaves placeholders unfilled, or garbles the line, in files saved by LibreOffice #187 specs.
• The reproduction script from substitute leaves placeholders unfilled, or garbles the line, in files saved by LibreOffice #187 gives the same output.
• Mutation check on the final code: temporarily breaking each of the two boundary comparisons, the emptying of middle nodes, the separator removal, or the single-node tail is caught by the existing specs. Breaking the search_from advance makes the "does not re-match" spec loop forever, so it is detected, but as a hang rather than a failure.
• The guard against empty matches had no coverage: removing it made no spec fail, although /x*/ then loops forever. This PR adds a spec for it, run under a timeout so a regression fails instead of hanging.

🤖 Generated with Claude Code