Coverage for src/pullapprove/trust/formatting.py: 96%
212 statements
« prev ^ index » next coverage.py v7.14.1, created at 2026-07-28 14:54 -0500
1"""Trust rules: changes that don't alter meaning — empty new files, whitespace,
2line wrapping, inter-token spacing, and punctuation/quote style."""
4from __future__ import annotations
6from itertools import pairwise
8from ..diff import DiffCode, DiffFile, DiffHunk
9from .delta import paired_changed_lines, paired_token_delta
10from .helpers import extension, leading_indent
11from .labels import Trust
12from .linescan import collapse_ws_outside_strings, consume_string, scan_string
13from .tokens import OP, STRING, Token
15# The deeply-tested core the content rules (`_style`, `_line_length`) share: the
16# JS/TS family + Python. These have free-form whitespace (so a reflow is neutral)
17# and use `'`/`"`/`;`/`,` interchangeably enough for `_style` — and they're the
18# ones we've actually validated. Other brace languages (Go, Rust, Java, C, …) are
19# plausible but unverified per-language — add them here only with a test corpus.
20# Data/markup (csv, tsv, yaml, md, …) stays out entirely: there a newline, comma,
21# or quote can be semantic, so these rules would hide real changes.
22_CORE_CONTENT_LANGUAGES = frozenset("js jsx ts tsx mjs mts cjs cts py".split())
25def _empty_file(file: DiffFile, hunk: DiffHunk) -> Trust | None:
26 # A brand-new file's hunk is all additions, so "empty" is just "all blank".
27 if not hunk.is_new_file:
28 return None
29 if all(not line.content.strip() for line in hunk.lines):
30 return Trust.EMPTY_FILE
31 return None
34def _whitespace(file: DiffFile, hunk: DiffHunk) -> Trust | None:
35 # Same language gate as the other content rules: in data/markup a blank line
36 # is often semantic (a Markdown paragraph break, a line inside a YAML block
37 # scalar), so only the validated code languages qualify.
38 if extension(file) not in _CORE_CONTENT_LANGUAGES:
39 return None
40 # KNOWN LIMITATION: a blank-line-only change *inside* a multi-line string
41 # literal (a `'''…'''` docstring, a template literal, a heredoc) changes the
42 # string's value, but reads as trivial here. We can't tell from a single hunk
43 # whether a blank line falls inside a literal — the opening delimiter is
44 # usually above the hunk, out of view — so this rare case is accepted rather
45 # than guarded with an unreliable heuristic.
46 changed = hunk.changed_lines
47 if changed and all(not line.content.strip() for line in changed):
48 return Trust.WHITESPACE
49 return None
52# A wrapped line "continues" to the next when it ends inside an open bracket,
53# with a `\`, or on an operator / opener / comma / dot / colon — never on an
54# identifier, value, closer, or `;`. That separates a real reflow from two
55# statements joined (a Python suite boundary, a JS ASI point), where the newline
56# is semantic and joining changes meaning.
57_CONTINUATION_CHARS = frozenset("=+-*/%<>&|^~,.:?([{")
60def _bracket_delta(text: str) -> int:
61 """Net bracket-depth change of `text`, ignoring brackets inside strings."""
62 depth = 0
63 i, n = 0, len(text)
64 while i < n:
65 ch = text[i]
66 if ch in "\"'`":
67 i = consume_string(text, i)
68 continue
69 if ch in "([{":
70 depth += 1
71 elif ch in ")]}":
72 depth -= 1
73 i += 1
74 return depth
77def _is_reflow(lines: list[DiffCode]) -> bool:
78 """True if `lines` is one statement wrapped across lines: every break (all but
79 the last) sits inside an open bracket, ends with `\\`, or ends on a
80 continuation operator. Otherwise the join crosses a statement boundary and the
81 newline is not neutral."""
82 depth = 0
83 for line in lines[:-1]:
84 stripped = line.content.rstrip()
85 depth += _bracket_delta(line.content)
86 if (
87 depth > 0
88 or stripped.endswith("\\")
89 or (stripped and stripped[-1] in _CONTINUATION_CHARS)
90 ):
91 continue
92 return False
93 return True
96def _contiguous_replacement(hunk: DiffHunk) -> bool:
97 """True when the hunk's changed lines form ONE deletions-then-additions block
98 with no context line inside it. A reflow rewraps one statement in place;
99 deletions that bracket a context line mean code crossed a statement boundary,
100 and joining the sides would compare a reordering as if it were a rewrap."""
101 seen_deletion = False
102 seen_addition = False
103 done = False
104 for line in hunk.lines:
105 if line.is_context():
106 if seen_deletion or seen_addition:
107 done = True
108 continue
109 if done:
110 return False # a second changed block — not one replacement
111 if line.is_deletion():
112 if seen_addition:
113 return False # deletions after additions — interleaved blocks
114 seen_deletion = True
115 else:
116 seen_addition = True
117 return True
120def _has_line_comment(text: str, prefix: str, quotes: str) -> bool:
121 """True if `text` starts a line comment outside a string literal. Unlike
122 `strip_inline_comment`, no whitespace-before-prefix requirement: for reflow
123 safety a glued comment (`foo()// note`) swallows a join just the same."""
124 i, n = 0, len(text)
125 while i < n:
126 if text[i] in quotes:
127 i = consume_string(text, i)
128 elif text.startswith(prefix, i):
129 return True
130 else:
131 i += 1
132 return False
135def _join_crosses_string(lines: list[DiffCode]) -> bool:
136 """True if a join between these lines lands INSIDE a multi-line string
137 literal (a `\"\"\"…\"\"\"` body, a `` `…` `` template literal spanning lines).
139 `_line_length` joins the lines with a space to compare the reflow. When a
140 break sits inside a string, that space replaces a real interior newline, so
141 the string's *value* changes (`\"SELECT a,\\nb\"` -> `\"SELECT a, b\"`) yet both
142 sides join to the same text — the change would be hidden. Detect it by
143 tracking string state across the lines: any non-last line that ends inside
144 an unclosed string means the following join is inside that string.
145 """
146 open_delim: str | None = None # delimiter of a string still open at line end
147 for line in lines[:-1]:
148 text = line.content
149 i, n = 0, len(text)
150 if open_delim is not None: # continuing a string opened on an earlier line
151 close = text.find(open_delim)
152 if close == -1:
153 return True # still open across this join
154 i, open_delim = close + len(open_delim), None
155 while i < n:
156 if text[i] in "\"'`":
157 delim = text[i] * 3 if text[i : i + 3] == text[i] * 3 else text[i]
158 close = scan_string(text, i)
159 if close is None: # opens a string that runs past end-of-line
160 open_delim = delim
161 break
162 i = close
163 else:
164 i += 1
165 if open_delim is not None:
166 return True
167 return False
170def _line_length(file: DiffFile, hunk: DiffHunk) -> Trust | None:
171 """Code wrapped/unwrapped across lines: identical content after joining."""
172 # In data/markup a newline separates records, so joining two lines isn't neutral.
173 ext = extension(file)
174 if ext not in _CORE_CONTENT_LANGUAGES:
175 return None
176 added, removed = hunk.added_lines, hunk.removed_lines
177 if not added or not removed:
178 return None
179 # Wrapping/unwrapping changes the line count; an equal-count edit is a
180 # same-shape change (handled by _style), not a reflow.
181 if len(added) == len(removed):
182 return None
183 # The joined comparison below flattens line positions, so it's only sound
184 # when the change is one contiguous replacement — deletions bracketing a
185 # context line would let moved code read as a neutral rewrap.
186 if not _contiguous_replacement(hunk):
187 return None
188 # Default-deny: a neutral reflow requires every break on BOTH sides to be a
189 # continuation (inside brackets / `\` / an operator). A break anywhere at
190 # statement level means the newline is semantic (a Python suite, a JS ASI
191 # point), so the "reflow" isn't neutral — decline rather than hide it.
192 if not (_is_reflow(added) and _is_reflow(removed)):
193 return None
194 # A break INSIDE a multi-line string (a triple-quote body, a template
195 # literal) means the join splices the string's value (interior newline ->
196 # space). collapse_ws_outside_strings preserves interiors, but the join
197 # itself already changed them, so decline rather than hide a literal edit.
198 if _join_crosses_string(added) or _join_crosses_string(removed):
199 return None
200 # Indentation is semantic in Python (block scope); a reflow that also shifts
201 # the statement's own indent is a dedent/indent, not a neutral wrap. Only the
202 # FIRST line carries the statement's indent (continuation lines are naturally
203 # re-indented), and `collapse_ws_outside_strings` strips leading space — so
204 # without this guard an indent change would compare equal and be hidden.
205 if leading_indent(added[0].content) != leading_indent(removed[0].content):
206 return None
207 # A line comment runs to end-of-line, so joining a commented line with the
208 # next drags the next line's code INTO the comment (`foo(a, // why` + `b)`
209 # joins to a line where `b)` is comment text). Even when the joined texts
210 # compare equal, that join is never neutral — decline if any line but the
211 # last starts a line comment. A comment on the LAST line is fine (nothing is
212 # joined after it), and block comments are fine (`/* … */` spans the join
213 # unchanged either way).
214 prefix = "#" if ext == "py" else "//"
215 quotes = "\"'" if ext == "py" else "\"'`"
216 for side in (added, removed):
217 if any(_has_line_comment(line.content, prefix, quotes) for line in side[:-1]):
218 return None
219 # Collapse only the whitespace *between* tokens — preserving string interiors
220 # so a real edit inside a literal can't masquerade as a reflow.
221 joined_added = collapse_ws_outside_strings(" ".join(line.content for line in added))
222 joined_removed = collapse_ws_outside_strings(
223 " ".join(line.content for line in removed)
224 )
225 if joined_added and joined_added == joined_removed:
226 return Trust.LINE_LENGTH
227 return None
230def _string_value(text: str) -> str:
231 """The value of a `'`/`"` string literal, delimiter-agnostic — so `'a'` and
232 `"a"` compare equal but a change to the *contents* does not. Delimiter escapes
233 are normalized (`'it\\'s'` and `"it's"` both decode to `it's`); a backtick
234 template literal is returned verbatim (its semantics aren't delimiter-style)."""
235 quote = text[0]
236 if quote not in "\"'":
237 return text
238 return text[1:-1].replace("\\" + quote, quote)
241def _style_key(
242 tokens: list[Token], collapse_comma: bool, collapse_semicolon: bool
243) -> list[object]:
244 """A token key in which only *stylistic* differences collapse: quote-delimiter
245 style (strings compare by decoded value), plus a trailing `,`/`;` when
246 `collapse_comma`/`collapse_semicolon` say it is stylistic here. Everything else
247 — identifiers, operators, numbers, string *contents* — is compared verbatim, so
248 a real change survives.
250 Trailing punctuation isn't always stylistic: a Python trailing comma builds a
251 tuple (`(x,)`, `x = a,`, `a[1,]`), and a JS/TS trailing semicolon can be
252 ASI-load-bearing. In those cases the flag is False and the punctuation stays in
253 the key, so the change is never hidden as style."""
254 key: list[object] = []
255 n = len(tokens)
256 for i, tok in enumerate(tokens):
257 if collapse_semicolon and tok.kind == OP and tok.text == ";" and i == n - 1:
258 continue # trailing semicolon
259 if (
260 collapse_comma
261 and tok.kind == OP
262 and tok.text == ","
263 and (
264 i == n - 1 or (tokens[i + 1].kind == OP and tokens[i + 1].text in ")]}")
265 )
266 ):
267 # A line-final comma is treated as a trailing comma (stylistic in
268 # JS/TS). KNOWN RESIDUAL: a comma-separated declaration written one
269 # per line (`let a = 1,` / `b = 2`) is also line-final, so dropping
270 # the separator reads as style — a real scope change (under sloppy
271 # mode; strict mode throws). Distinguishing it needs the next line,
272 # which this per-pair rule can't see; not worth showing every
273 # multi-line trailing-comma reformat to close a narrow, usually-loud
274 # case.
275 continue # trailing comma (line end, or before a closer)
276 # Tag string values so a literal can't collide with an identifier of the
277 # same text (a `'foo'` -> `foo` change must stay visible).
278 key.append(("str", _string_value(tok.text)) if tok.kind == STRING else tok.text)
279 return key
282def _style_delta(
283 old_tokens: list[Token],
284 new_tokens: list[Token],
285 collapse_comma: bool,
286 collapse_semicolon: bool,
287) -> bool | None:
288 """Compare one line pair: True if it differs ONLY in style (semicolons /
289 trailing commas / quote delimiters), False if token-identical, None to
290 decline (a non-style difference remains)."""
291 old_key = _style_key(old_tokens, collapse_comma, collapse_semicolon)
292 new_key = _style_key(new_tokens, collapse_comma, collapse_semicolon)
293 if old_key != new_key:
294 return None # a non-style difference remains
295 # Style-only iff the tokens themselves differ (a quote delimiter or trailing
296 # punctuation). If the raw tokens match, any remaining difference is in a
297 # comment or whitespace the tokenizer drops — not this rule's job (leave it
298 # for _comments), so don't claim it as style.
299 return [t.text for t in old_tokens] != [t.text for t in new_tokens]
302# Line-leading characters that, under JS/TS Automatic Semicolon Insertion,
303# continue the previous statement rather than start a new one. A leading `/` is
304# also a continuation (regex literal or division) but is handled separately, since
305# `//` and `/*` start comments, not statements.
306_ASI_LEADERS = frozenset(("(", "[", "`", "+", "-"))
309def _continues_previous_line(text: str) -> bool:
310 """True if `text` begins with a token that, under JS/TS ASI, attaches to the
311 previous line instead of starting a new statement."""
312 stripped = text.lstrip()
313 if not stripped:
314 return False
315 if stripped[0] in _ASI_LEADERS:
316 return True
317 # A leading `/` is a regex literal or division that continues the line above —
318 # unless it opens a comment (`//`, `/*`), which is inert.
319 return stripped[0] == "/" and not stripped.startswith(("//", "/*"))
322def _asi_hazard(hunk: DiffHunk) -> bool:
323 """True if the hunk's new-file side has a statement line that continues the
324 previous non-blank line under JS/TS Automatic Semicolon Insertion. There,
325 adding or removing a trailing `;` on the line above merges or splits two
326 statements — a real behavior change — so `_style` must not treat that `;` as
327 stylistic. ASI ignores blank lines, so we compare against the last non-blank
328 line, not the strictly-adjacent one.
330 When only blank lines are visible after the last changed line, the statement
331 ASI would merge with sits past the context window — the scan can't prove the
332 `;` inert, so that counts as a hazard too (default-deny). A hunk that ENDS on
333 the changed line is different: git always emits trailing context when lines
334 exist, so that's the end of the file and there is nothing to merge with."""
335 prev_nonblank = ""
336 last_nonblank_changed = False
337 blanks_after = False
338 for line in hunk.lines:
339 if line.is_deletion():
340 continue
341 if prev_nonblank and _continues_previous_line(line.content):
342 return True
343 if line.content.strip():
344 prev_nonblank = line.content
345 last_nonblank_changed = line.is_addition()
346 blanks_after = False
347 else:
348 blanks_after = True
349 return last_nonblank_changed and blanks_after
352def _style(file: DiffFile, hunk: DiffHunk) -> Trust | None:
353 """Paired lines that differ only in semicolons, quotes, or trailing commas.
355 Python tokenizes under the `py` dialect and the JS family under `ts` — they
356 can't share one dialect, because `//` is a line comment in JS but floor
357 DIVISION in Python (tokenizing `x // 2` as `ts` would drop `// 2` as a comment
358 and hide a divisor change). The two semantic splits — a Python trailing comma
359 builds a tuple, a JS/TS trailing semicolon can be ASI-load-bearing — are
360 handled by `collapse_comma`/`collapse_semicolon`."""
361 ext = extension(file)
362 if ext not in _CORE_CONTENT_LANGUAGES:
363 return None # elsewhere ';'/','/quotes may be semantic (data, char literals)
364 # The positional pairing gate runs first, so the O(hunk-lines) ASI scan
365 # below never runs for hunks the pairing would reject anyway.
366 pairs = paired_changed_lines(hunk)
367 if pairs is None:
368 return None
369 dialect = "py" if ext == "py" else "ts"
370 collapse_comma = ext != "py" # a Python trailing comma builds a tuple
371 # Python has no ASI, so its `;` is always stylistic; in JS/TS a trailing `;` is
372 # only stylistic when no following line continues the statement.
373 collapse_semicolon = ext == "py" or not _asi_hazard(hunk)
374 return (
375 Trust.STYLE
376 if paired_token_delta(
377 pairs,
378 dialect,
379 lambda old, new, o, n: _style_delta(
380 o, n, collapse_comma, collapse_semicolon
381 ),
382 )
383 else None
384 )
387def _whitespace_gaps_only(stripped: str, tokens: list[Token]) -> bool:
388 """True if everything between consecutive tokens is whitespace. The tokenizer
389 silently skips block comments, so without this check a mid-line `/* … */`
390 edit would compare token-identical and read as a spacing change."""
391 pos = 0
392 for tok in tokens:
393 if stripped[pos : tok.start].strip():
394 return False
395 pos = tok.end
396 return True
399def _line_tail(stripped: str, tokens: list[Token]) -> str:
400 """The text after the last token — a trailing line comment, or empty."""
401 return stripped[tokens[-1].end :].strip() if tokens else stripped
404def _spacing_delta(
405 old: DiffCode,
406 new: DiffCode,
407 old_tokens: list[Token],
408 new_tokens: list[Token],
409 dialect: str,
410) -> bool | None:
411 """Compare one line pair: True if only the whitespace between or after the
412 tokens moved, False if the lines are identical, None to decline (something
413 other than inter-token whitespace changed)."""
414 if [t.text for t in old_tokens] != [t.text for t in new_tokens]:
415 return None # a token changed — not a whitespace-only edit
416 # Token offsets index into the stripped line (what `paired_token_delta`
417 # tokenized), so the gap/tail checks scan that same text.
418 old_stripped, new_stripped = old.content.strip(), new.content.strip()
419 if not _whitespace_gaps_only(old_stripped, old_tokens):
420 return None # a mid-line block comment sits in a gap
421 if not _whitespace_gaps_only(new_stripped, new_tokens):
422 return None
423 if _line_tail(old_stripped, old_tokens) != _line_tail(new_stripped, new_tokens):
424 return None # the trailing comment changed — _comments' territory
425 for (o1, o2), (n1, n2) in zip(pairwise(old_tokens), pairwise(new_tokens)):
426 if (o1.end == o2.start) == (n1.end == n2.start):
427 continue # this pair's grouping didn't change
428 if (o1.kind == OP) == (o2.kind == OP):
429 return None # regrouped punctuation / word+string — semantic
430 if dialect == "ts" and (o1.text in "/<>" or o2.text in "/<>"):
431 return None # regex / generic ambiguity — spacing decides parse
432 return old.content != new.content
435def _spacing(file: DiffFile, hunk: DiffHunk) -> Trust | None:
436 """Paired lines whose tokens are identical and only the whitespace between or
437 after them moved — `x=1` -> `x = 1`, `f( a )` -> `f(a)`, trailing-whitespace
438 trims, alignment shifts.
440 Whitespace inside a string literal is a value change and never qualifies
441 (string tokens compare verbatim). Two default-deny guards beyond the shared
442 pairing/indent/tokenize gates in `delta.py`:
444 - Regrouping punctuation is semantic even with identical token texts
445 (`a + +b` vs `a ++ b` in JS, `a ** b` vs `a * * b` in Python), and so is
446 gluing a word to a string (`f "x"` vs f-string `f"x"`) — a glue change is
447 only trusted when exactly one side of the touching pair is punctuation.
448 In JS/TS, `/`, `<`, and `>` never qualify at all: spacing decides whether
449 they read as regex-vs-division or generic-vs-comparison.
450 - The tokenizer skips comments, so the text after the last token (a trailing
451 line comment) must match exactly and interior gaps must be pure whitespace;
452 otherwise a comment edit would read as spacing. Comment-only changes stay
453 `_comments`' job (this rule declines and falls through).
454 """
455 ext = extension(file)
456 if ext not in _CORE_CONTENT_LANGUAGES:
457 return None
458 pairs = paired_changed_lines(hunk)
459 if pairs is None:
460 return None
461 dialect = "py" if ext == "py" else "ts"
462 return (
463 Trust.SPACING
464 if paired_token_delta(
465 pairs,
466 dialect,
467 lambda old, new, o, n: _spacing_delta(old, new, o, n, dialect),
468 )
469 else None
470 )