Scan every comment on a line, and read a verbatim string correctly

[ptr727]

Two findings from the low-confidence block of Copilot's third review of promotion PR #460, fixed at the source. That PR's head is develop, so it picks these up when this squashes in.

Closes#462.

Every comment on a line, not just the first

The extractor searched each marker kind from column 0 against a ceiling. A ceiling can only describe the first comment on a line, which is why the same structure produced three defects in a row across this promotion:

1. a marker quoted inside the first comment read as real (Bound block-comment scanning by the earliest line-comment marker #461)
2. a doc marker excluded from the ceiling unbounded it (Bound block-comment scanning by the earliest line-comment marker #461, second commit)
3. anything after the first comment was unreachable (this PR)

var x = 1; /* Note. */ // Two things. Here. -> [(1, 'Note.', False)]

The trailing comment is dropped, so every comment rule is blind to it.

Rather than patch the third instance, this replaces the ceiling with a single left-to-right pass over a cursor. Whichever marker comes first wins, a line comment ends the line, and a closed block resumes the scan after its closer. Two cases nobody asked for come with it: several blocks on one line, and a comment trailing the line where a multi-line block closes.

Verbatim strings, both directions

The masker treated a backslash as an escape inside every quoted span. In a C# verbatim string the backslash is ordinary and a doubled quote is the escape, so it was wrong both ways:

var p = @"C:\tmp\"; // Two things. Here. -> masked to `var p = @"` , comment hidden
var s = @"a""// One thing. Another thing.""b"; -> string content read as a comment

The first is a false negative, the second a false positive. C# takes its own syntax entry for this, since the rest of the C-like family shares the markers but has no verbatim form and .js, .ts, .json, and .jsonc would be wrong to inherit it.

Verification

Six new assertions, each watched failing against the extractor currently on develop:

case	before	after
code /* Note. */ // run-on	[]	flagged
/* Note. */ /* run-on */	[]	flagged
block closing mid-line, then // run-on	[]	flagged
@"C:\tmp\"; // run-on	[]	flagged
@"a""// run-on""b"	flagged	[]
SYNTAX['.cs']['verbatim']	KeyError	True

65 self-tests and 19 repo_gate tests pass, repo_gate is clean, and charset plus dupword exit 0.

The warn-only backlog is unchanged at comment-wrap 454, semicolon 388, comment-case 56. The wider scan first reported comment-wrap 457, and the three extra were this change's own new comments wrapping across lines, which the rule forbids. They are rewritten one sentence per line rather than left standing in the linter's own source.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR updates the repo’s prose-lint comment extractor so it can (1) discover multiple comments on a single line across supported syntaxes and (2) correctly mask C# verbatim strings so comment markers inside them aren’t misinterpreted (and real trailing comments aren’t hidden).

Changes:

• Replace the “first comment ceiling” approach with a left-to-right cursor scan that can extract multiple comments on one line (including multiple block comments and a trailing comment after a mid-line block close).
• Add a per-syntax verbatim capability and implement C# verbatim-string masking rules ("" escapes a quote; \ is literal).
• Add regression tests covering multi-comment lines and C# verbatim masking (both false-negative and false-positive cases).

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
scripts/prose_lint.py	Implements cursor-based multi-comment extraction and C# verbatim-string masking via a syntax-level verbatim flag.
scripts/test_prose_lint.py	Adds assertions that reproduce the previously missed cases and verify the new behavior.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

scripts/prose_lint.py:429

• extracted_comments() stops scanning the entire line when it encounters any documentation marker (including block-doc /**). For a same-line block doc comment like /** docs */ // Two things. Here. this will drop the trailing // comment, even though the doc block closes before it. This makes comment rules blind to comments that follow a closed block doc comment on the same line.

 # A documentation comment is left to CODESTYLE, so the rest of the line goes with it.
if any(line[at:].startswith(d) for d in spec['doc']):
break

[ptr727]

Answering the round-two low-confidence finding here, since a suppressed finding has no thread to reply on. It is right, and it is a regression this PR introduced rather than a pre-existing gap. Fixed in 27bd097.

Checked against the extractor being replaced rather than assumed:

develop : [(1, 'Two things. Here.', False)]
this PR : []

The rewrite ended the whole line on any documentation marker. That is correct for the line form, which does run to end of line, and wrong for the block form, which closes where it closes. A closed block now resumes the scan after its closer, and an unclosed one still ends the line without carrying into the lines below, which is what CODESTYLE expects while it owns the comment.

Worth recording why the old code got this right without meaning to. Its doc check skipped the block pair and left the ceiling unlowered, so the separate line-marker search still ran across the whole line and found the trailing comment. The behavior was a side effect of the structure this PR removes, which is exactly the kind of thing a rewrite drops silently. It is now pinned by a case, together with one asserting a line doc comment still takes the rest of its line and one asserting doc content itself stays unlinted.

Parity with develop is restored on the case, 66 self-tests and 19 repo_gate tests pass, uvx mypy --strict is clean, repo_gate is clean, charset and dupword exit 0, and the warn-only backlog holds at comment-wrap 454, semicolon 388, comment-case 56.

This is the fifth defect in this promotion's review sequence to surface only in the suppressed block, with no inline thread on the round that found it.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (4)

scripts/prose_lint.py:434

• In the documentation-comment branch, end < 0 currently just breaks out of the scan for this line. To actually skip a multi-line /** ... */ doc block (so markers inside it aren’t parsed as comments), this needs to set the doc-block closing marker so the next lines are treated as inside a CODESTYLE-owned doc block until the closer is found.

 end = masked.find(found[1], at + len(found[0]))
if end < 0:
break # CODESTYLE owns it until it closes

scripts/prose_lint.py:292

• C# verbatim strings are only valid with double quotes (e.g. @"..." / $@"..." / @$"..."). Right now, verbatim mode is enabled for any quote character if the prefix contains '@', so something like @'x' would be treated as verbatim and parsed with doubled-quote escape rules. Restricting verbatim handling to quote == '"' keeps the masking logic aligned with actual C# syntax and avoids mis-parsing char literals or other stray @ uses.

 inside_verbatim = verbatim and '@' in line[start:i]

scripts/prose_lint.py:402

• extracted_comments() now skips doc markers, but it doesn’t currently keep any state for a multi-line block doc comment (/** ... where the closer isn’t on the same line). Without that, subsequent lines inside the doc block are scanned normally and can misinterpret // or /* that appear in documentation text as real comments. Tracking a separate doc_closing marker (similar to closing) lets you skip lines until the doc block closes, then resume scanning after the closer.

This issue also appears on line 432 of the same file.

 out: list[tuple[int, str, bool]] = []
closing = ''
for n, raw in enumerate(lines, 1):
line = raw.rstrip('\r')
masked = strip_strings(line, spec['quotes'], spec['verbatim'])

scripts/test_prose_lint.py:310

• There’s coverage for a single-line /** ... */ doc block giving the rest of the line back, but the extractor change also affects multi-line /** ... doc blocks. Adding a regression assertion where a later line inside the doc block contains // Two things. Here. (and must still be skipped as CODESTYLE-owned documentation) would help prevent future regressions of doc-block state handling.

 self.assertEqual([], self.flag('a.cs', f'/** {self.RUN_ON} */\n'))
self.assertEqual([], self.flag('a.cs', f'/// {self.RUN_ON} // and more\n'))
self.assertEqual(['comment-wrap'],
self.flag('a.cs', '/** Docs. */ // Two things. Here.\n'))

[ptr727]

Answering the four findings in the round-three low-confidence block. All four are right. They are two defects, one of them reported three ways. Both fixed in 8e1ea08.

The multi-line doc block (prose_lint.py:402, :434, and the test note)

Confirmed, and checked against the extractor being replaced rather than assumed:

input : /** Docs start
| * // Two things. Here.
| * /* not an opener
| */
develop : [(2, 'Two things. Here.', False), (3, 'not an opener', False)]
this PR : [(2, 'Two things. Here.', False), (3, 'not an opener', False)]

Identical, so this is an old hole rather than a regression: an unclosed /** left no state, and the documentation lines below were scanned as code. A // in the prose became a comment to lint, and a /* in it opened a block that ran on. Worth fixing here anyway, since the rewrite is where the state to close it belongs, and the doc branch you flagged in the previous round is what made the gap visible.

A doc_closing marker now carries the block, skipping whole lines until the closer and giving back whatever follows it on that line. Your suggestion to track it separately from closing is what the fix does, since the two differ in that a doc block emits nothing while an ordinary block emits its interior.

The three reports are the same defect seen from the state, the branch, and the missing test, so one case covers all three. It asserts the interior is skipped and the closing line still gives back its trailing comment, which is the single finding it expects.

The char literal (prose_lint.py:292)

Also confirmed, and this one is mine:

before : var c = @' '; // t <- doubled quotes eaten as one escaped character
after : var c = @' '' '; // t <- ordinary open, close, open, close

Keying on the @ prefix alone applied verbatim rules to any quote character. C# spells the verbatim form with double quotes only, so the condition now requires one. The case counts surviving quotes rather than asserting on a comment, since both readings happen to leave the trailing comment visible and only the masking distinguishes them.

State

68 self-tests and 19 repo_gate tests pass, both new cases watched failing against 27bd097 first. uvx mypy --strict is clean, repo_gate is clean, charset and dupword exit 0, and the warn-only backlog holds at comment-wrap 454, semicolon 388, comment-case 56.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.