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