fix(filter): stop Python docstrings corrupting MinimalFilter state

[guyoron1]

Summary

Fixes #2712

MinimalFilter corrupted its in_docstring state on Python docstrings whose closing """ isn't on a line of its own, so comment stripping went wrong for the rest of the file. The state is now driven by one rule: count the """ on the line, and an odd count flips the state. That covers:

• open and close on separate lines
• open + close on one line ("""Return the sum.""")
• a closing """ appended to content (and return result.""")
• a closing """ with trailing text (""" # note)
• the empty """""" docstring

History of this PR: the first commit handled the single-line case. After pszymkowiak's review, the second commit handled a closing """ appended to content (his repro). Re-testing found the same failure one closing style further out (text after the closing quotes), so the second commit now replaces both special cases with the odd-count rule, which is net shorter than what is on develop.

Verified

pszymkowiak's exact repro (rtk read <file>.py -l minimal), develop vs this PR: on develop both # subtract comment and # multiply comment are left unstripped; here both are stripped, the docstring is kept and the following method is unaffected. Single-line, empty and sequential docstrings are correct.

To try it by hand use a real .py file: rtk read - -l minimal from stdin resolves to Language::Unknown, so no Python handling runs.

Tests

Five docstring tests (single-line, closing on a content line, closing with trailing text, sequential single-line docstrings, empty docstring); all five fail on develop's code.

• cargo fmt --all -- --check, cargo clippy --all-targets (0 warnings), cargo test --all (all pass)

[pszymkowiak]

Tested extensively with the compiled binary. The targeted fix works correctly: a docstring that opens and closes on the same line ("""Return the sum.""") no longer corrupts state — confirmed with single and sequential occurrences, plus the empty-docstring edge case.

However, the same class of bug (from #2712) still reproduces for an equally common style: a multi-line docstring whose closing """ is appended directly to content rather than sitting alone on its own line — e.g.:

def subtract(self, a, b):
    """Subtract b from a
    and return result."""
    # subtract comment
    return a - b

def multiply(self, a, b):
    # multiply comment, no docstring before
    return a * b

This outputs both # subtract comment and # multiply comment unstripped — the second one belongs to a completely different, docstring-less method, showing the corruption persists across the rest of the file exactly like the original bug, just triggered by a different closing style. Root cause: the fix only handles the open+close-on-one-line case; a closing """ line whose trimmed text doesn't start with """ never reaches the toggle logic and falls straight into the unconditional if in_docstring { push verbatim } path, so in_docstring never resets. It happens to "self-heal" the next time another line starts with """ (regardless of whether that's semantically related), but if none follows, corruption persists to EOF — as in this example.

Given the docstring-with-trailing-close style is arguably more common in real Python code than the single-line case this PR targets, I'd consider #2712 still open rather than fully fixed. cargo fmt, cargo clippy --all-targets, cargo test --all are otherwise clean (2 unrelated pre-existing locale failures).

[guyoron1]

Pushed a fix addressing the multi-line docstring closing case — the in_docstring verbatim block now checks for """ at end of content lines (e.g. and return result."""), not just lines starting with """. Added a test reproducing the exact scenario from your review. CI should be green shortly.

[guyoron1]

Thanks for the thorough testing @pszymkowiak — the case you found (multi-line docstring whose closing """ sits on a content line) is now handled: while in docstring state, a line ending with """ exits the state. Added test_python_multiline_docstring_closing_on_content_line covering your exact repro (docstring kept, trailing # subtract comment stripped, following method unaffected). Rebased on latest develop; all filter tests pass.

[guyoron1]

@pszymkowiak rebased on current develop and ready for another look.

Your repro (a multi-line docstring whose closing """ sits on a content line, followed by a docstring-less method) is fixed. I also tried the same failure one closing style further out and it was still broken: a closing """ with trailing text (and return result.""" # note) missed the toggle too and left in_docstring stuck to EOF. Rather than add a third special case, the second commit now replaces both branches with one rule: count the """ on the line, and an odd count flips the state. It's net shorter than what's on develop and covers open, close, open + close on one line, closing appended to content, closing with trailing text, and the empty """""" docstring. Five tests, all failing on develop.

To re-check by hand, use a real .py file (rtk read <file>.py -l minimal). From stdin (rtk read - -l minimal) the language resolves to Unknown, so no Python handling runs at all.

Two things I noticed while poking at it, both pre-existing and unrelated to this PR: r"""...""" docstrings are dropped entirely and ''' docstrings aren't recognised. Happy to file those separately.

Heads-up: #2715 edits the same function (adjacent hunks), so whichever merges second needs a mechanical rebase.

[KuSh]

Thank you for this fix and the thorough test cases. #3336 (merged 2026-09-26) gave Python its own triple-quote-aware path in the minimal filter, so the docstring toggle this PR edits is no longer reached for Python files. All five of your shapes (one-line, closed on a content line, text after the closing quotes, sequential, empty) are now handled correctly on develop. Only the one-line case is pinned by a test there, so a small test-only PR adding the other shapes against the current code would be welcome, as would one removing the now-unused Python branch in the generic loop. If I missed a case, please comment or reopen.