Coverage for src/pullapprove/cli.py: 78%

285 statements  

« prev     ^ index     » next       coverage.py v7.14.1, created at 2026-10-31 23:22 -0500

1from __future__ import annotations 

2 

3import os 

4import subprocess 

5import sys 

6from collections import Counter, deque 

7from pathlib import Path 

8from textwrap import dedent 

9 

10import click 

11from pydantic import ValidationError 

12 

13from . import git 

14from .config import ( 

15 CONFIG_FILENAME, 

16 CompiledConfigModels, 

17 ConfigModel, 

18 ConfigModels, 

19 is_config_filename, 

20 is_config_path, 

21) 

22from .diff import DiffFile, DiffHunk, filter_diff_text, iter_file_hunks 

23from .matches import ChangeMatches, match_diff, match_files 

24from .printer import MatchesPrinter 

25from .text import plural 

26from .trust import TRUST_FAMILIES, Trust, trust_diff, trust_label 

27 

28 

29@click.group() 

30@click.version_option(package_name="pullapprove") 

31@click.pass_context 

32def cli(ctx: click.Context) -> None: 

33 pass 

34 

35 

36@cli.command() 

37@click.option("--filename", default=CONFIG_FILENAME, help="Configuration filename") 

38def init(filename: str) -> None: 

39 """Create a new config file""" 

40 config_path = Path(filename) 

41 if config_path.exists(): 

42 click.secho(f"{filename} already exists!", fg="red") 

43 sys.exit(1) 

44 

45 # Could we use blame to guess? 

46 # go straight to agent? 

47 # gh auth status can give us the user? or ask what's their username? 

48 # keep it simple - agent can do more when I get to it 

49 

50 contents = f""" 

51 [[scopes]] 

52 name = "default" 

53 paths = ["**/*"] 

54 request = 1 

55 require = 1 

56 reviewers = ["<YOU>"] 

57 

58 [[scopes]] 

59 name = "pullapprove" 

60 paths = ["**/{CONFIG_FILENAME}"] 

61 request = 1 

62 require = 1 

63 reviewers = ["<YOU>"] 

64 """ 

65 config_path.write_text(dedent(contents).strip() + "\n") 

66 click.secho(f"Created {filename}") 

67 

68 

69@cli.command() 

70@click.option("--quiet", is_flag=True) 

71def check(quiet: bool) -> ConfigModels: 

72 """ 

73 Validate configuration files 

74 """ 

75 

76 if not quiet: 

77 if Path(".pullapprove.yml").exists(): 

78 click.secho( 

79 f"{click.style('[Warning]', fg='yellow')} This repo still contains a PullApprove v3 config file (.pullapprove.yml). Consider migrating it to PullApprove v5." 

80 ) 

81 if Path("CODEOWNERS").exists(): 

82 click.secho( 

83 f"{click.style('[Warning]', fg='yellow')} This repo still contains a CODEOWNERS file. Consider migrating it to PullApprove v5." 

84 ) 

85 if Path("docs/CODEOWNERS").exists(): 

86 click.secho( 

87 f"{click.style('[Warning]', fg='yellow')} This repo still contains a CODEOWNERS file (docs/CODEOWNERS). Consider migrating it to PullApprove v5." 

88 ) 

89 if Path(".github/CODEOWNERS").exists(): 

90 click.secho( 

91 f"{click.style('[Warning]', fg='yellow')} This repo still contains a CODEOWNERS file (.github/CODEOWNERS). Consider migrating it to PullApprove v5." 

92 ) 

93 

94 errors = {} 

95 configs = ConfigModels(root={}) 

96 

97 for root, _, files in os.walk("."): 

98 for f in files: 

99 if is_config_filename(f): 

100 config_path = Path(root) / f 

101 

102 if not quiet: 

103 click.echo(config_path, nl=False) 

104 try: 

105 configs.add_config( 

106 ConfigModel.from_filesystem(config_path), config_path 

107 ) 

108 

109 if not quiet: 

110 click.secho(" -> OK", fg="green") 

111 except ValidationError as e: 

112 if not quiet: 

113 click.secho(" -> ERROR", fg="red") 

114 

115 errors[config_path] = e 

116 

117 for path, error in errors.items(): 

118 click.secho(str(path), fg="red", err=True) 

119 click.echo(str(error), err=True) 

120 

121 if errors: 

122 raise click.ClickException("Configuration validation failed.") 

123 

124 # Compile the whole set offline to catch what per-file validation 

125 # can't: unknown aliases, missing/circular extends, and invalid 

126 # combinations like wildcard+negation. teams=None leaves `@team` refs 

127 # unexpanded — the same partial resolution `match`/`coverage` use — 

128 # so anything that errors here would also error in production. 

129 try: 

130 configs.compiled() 

131 except (ValidationError, ValueError) as e: 

132 click.secho(f"ERROR: {e}", fg="red", err=True) 

133 raise click.ClickException("Configuration validation failed.") 

134 

135 if not configs and not quiet: 

136 click.secho(f"No {CONFIG_FILENAME} files found.", fg="red", err=True) 

137 sys.exit(1) 

138 

139 return configs 

140 

141 

142def _compiled_configs_at(ref: str) -> CompiledConfigModels: 

143 """The configs committed at `ref`, which is what PullApprove enforces on a 

144 pull request into it. A pull request's own config changes only take 

145 effect once they merge.""" 

146 try: 

147 contents = { 

148 path: git.git_file_at(path=Path("."), ref=ref, file_path=path) 

149 for path in git.git_ls_tree(path=Path("."), ref=ref) 

150 if is_config_path(path) 

151 } 

152 except subprocess.CalledProcessError as exc: 

153 raise click.ClickException(f"Could not read the configs at {ref}.") from exc 

154 

155 try: 

156 return ConfigModels.from_contents(contents).compiled() 

157 except (ValidationError, ValueError) as e: 

158 raise click.ClickException(f"The configs at {ref} are invalid: {e}") from e 

159 

160 

161@cli.command() 

162@click.option("--changed", is_flag=True, help="Show only changed files") 

163@click.option("--staged", is_flag=True, help="Show only staged files") 

164@click.option("--diff", is_flag=True, help="Show diff content with matches") 

165@click.option( 

166 "--by-scope", is_flag=True, help="Organize output by scope instead of by path" 

167) 

168@click.option( 

169 "--scope", 

170 multiple=True, 

171 help="Filter to show only files matching these scopes (can be used multiple times)", 

172) 

173@click.option( 

174 "--base", 

175 help="Match HEAD as a pull request into this branch or commit, " 

176 "using the configs committed there", 

177) 

178@click.option( 

179 "--author", 

180 help="Match as a pull request by this user, applying each scope's `authors`", 

181) 

182@click.option("--json", "as_json", is_flag=True, help="Output matches as JSON") 

183@click.argument("paths", nargs=-1, type=click.Path()) 

184@click.pass_context 

185def match( 

186 ctx: click.Context, 

187 changed: bool, 

188 staged: bool, 

189 diff: bool, 

190 by_scope: bool, 

191 scope: tuple[str, ...], 

192 base: str | None, 

193 author: str | None, 

194 as_json: bool, 

195 paths: tuple[str, ...], 

196) -> None: 

197 """ 

198 Show files and their matching scopes 

199 

200 If PATHS are provided, only those specific paths will be matched. 

201 Directories will be recursively expanded to include all files within them. 

202 Otherwise, all files in the repository will be matched. 

203 

204 With --base, HEAD is matched the way PullApprove would match a pull 

205 request into that branch: the diff since HEAD branched off it, against 

206 the configs committed there. 

207 """ 

208 if as_json and (by_scope or scope): 

209 # JSON is every match, for the script to slice however it wants 

210 raise click.UsageError("--json can't be combined with --by-scope or --scope.") 

211 

212 if paths and (diff or staged or changed or base): 

213 raise click.UsageError( 

214 "Cannot use --diff, --staged, --changed, or --base with specific paths." 

215 ) 

216 

217 if base and (staged or changed): 

218 raise click.UsageError("--base can't be combined with --staged or --changed.") 

219 

220 if base: 

221 # Resolved once, so the configs and the diff come from the same commit 

222 try: 

223 base = git.git_commit_sha(path=Path("."), ref=base) 

224 except subprocess.CalledProcessError as exc: 

225 # Usually a shallow clone that never fetched the base 

226 raise click.ClickException( 

227 f"Could not find the commit {base}. --base needs it and the " 

228 "history back to where HEAD branched off it (in GitHub " 

229 "Actions, checkout with fetch-depth: 0)." 

230 ) from exc 

231 configs = _compiled_configs_at(base) 

232 else: 

233 configs = ctx.invoke(check, quiet=True).compiled() 

234 

235 if not configs: 

236 raise click.ClickException("No valid configurations found.") 

237 

238 # A misspelled --scope would otherwise just look like nothing matched 

239 known_scopes: set[str] = set() 

240 for config in configs.root.values(): 

241 for config_scope in config.scopes: 

242 known_scopes.add(config_scope.name) 

243 unknown_scopes = [s for s in scope if s not in known_scopes] 

244 if unknown_scopes: 

245 raise click.UsageError(f"Unknown scope: {', '.join(unknown_scopes)}") 

246 

247 if author: 

248 # PullApprove drops the scopes an author is excluded from before 

249 # matching, so which scope owns a path can depend on who opened the 

250 # pull request 

251 try: 

252 configs = configs.filter_for_pullrequest(author_username=author) 

253 except ValueError as e: 

254 raise click.ClickException( 

255 f"Can't apply --author: {e}. " 

256 "The command line can't look up team members." 

257 ) from e 

258 

259 matches, all_files = _match_changes( 

260 configs=configs, 

261 paths=paths, 

262 changed=changed, 

263 staged=staged, 

264 diff=diff, 

265 base=base, 

266 ) 

267 

268 printer = MatchesPrinter(matches=matches, all_files=all_files) 

269 if as_json: 

270 printer.print_json() 

271 elif by_scope: 

272 printer.print_by_scope(scope_filter=scope) 

273 else: 

274 printer.print_by_path(scope_filter=scope) 

275 

276 

277def _match_changes( 

278 *, 

279 configs: CompiledConfigModels, 

280 paths: tuple[str, ...], 

281 changed: bool, 

282 staged: bool, 

283 diff: bool, 

284 base: str | None, 

285) -> tuple[ChangeMatches, list[str]]: 

286 """Match the files `match` was pointed at, returning the matches and every 

287 one of those files (including the ones no scope owns).""" 

288 if paths: 

289 # Match only the git-tracked files at or under the provided paths 

290 all_git_files = set(git.git_ls_files(Path("."))) 

291 expanded_paths = [] 

292 

293 for path_str in paths: 

294 path = Path(path_str) 

295 if path.is_dir(): 

296 # Filter git files that are within this directory 

297 dir_prefix = str(path) + "/" 

298 for git_file in all_git_files: 

299 if git_file.startswith(dir_prefix) or git_file == str(path): 

300 expanded_paths.append(git_file) 

301 elif path.is_file() or str(path) in all_git_files: 

302 # Include if it's a git-tracked file 

303 if str(path) in all_git_files: 

304 expanded_paths.append(str(path)) 

305 else: 

306 click.secho( 

307 f"File not tracked by git: {path}", fg="yellow", err=True 

308 ) 

309 else: 

310 click.secho( 

311 f"Path does not exist or not tracked by git: {path}", 

312 fg="yellow", 

313 err=True, 

314 ) 

315 

316 return match_files(configs, iter(expanded_paths)), expanded_paths 

317 

318 if diff or staged or base: 

319 diff_args = list(git.HOST_DIFF_ARGS) 

320 if staged: 

321 diff_args.append("--staged") 

322 if base: 

323 diff_args.append(f"{base}...HEAD") 

324 

325 try: 

326 diff_results = match_diff( 

327 configs, git.git_diff_stream(Path("."), *diff_args) 

328 ) 

329 except subprocess.CalledProcessError as exc: 

330 # git failed (not a repo, bad state) — it already explained itself on 

331 # stderr, so exit cleanly instead of dumping a traceback. 

332 if base: 

333 # Usually a shallow clone that stops before the merge base 

334 raise click.ClickException( 

335 f"Could not diff {base}...HEAD. The history back to where " 

336 "HEAD branched off has to be fetched (in GitHub Actions, " 

337 "checkout with fetch-depth: 0)." 

338 ) from exc 

339 raise click.ClickException("Could not read a diff from git.") from exc 

340 # For diff mode, we only show files in the diff 

341 return diff_results.matches, diff_results.changed_paths 

342 

343 if changed: 

344 # For changed mode, we only show changed files 

345 all_files = git.git_ls_changes(Path(".")) 

346 else: 

347 # For normal mode, show all files to see gaps 

348 all_files = list(git.git_ls_files(Path("."))) 

349 return match_files(configs, iter(all_files)), all_files 

350 

351 

352@cli.command() 

353@click.option( 

354 "--check", 

355 "check_flag", 

356 is_flag=True, 

357 help="Exit with non-zero status if coverage is incomplete", 

358) 

359@click.argument("path", type=click.Path(exists=True), default=".") 

360@click.pass_context 

361def coverage(ctx: click.Context, path: str, check_flag: bool) -> None: 

362 """ 

363 Calculate file coverage for review scopes 

364 """ 

365 configs = ctx.invoke(check, quiet=True).compiled() 

366 

367 num_matched = 0 

368 num_total = 0 

369 uncovered_files = [] 

370 

371 # First, get all files to know the total count for progress bar 

372 all_files = list(git.git_ls_files(Path(path))) 

373 

374 if not all_files: 

375 click.echo("No files found") 

376 return 

377 

378 # Process files with progress bar 

379 with click.progressbar( 

380 all_files, label="Analyzing coverage", show_percent=True, show_pos=True 

381 ) as files: 

382 # Use match_files to get proper scope matching including code patterns 

383 results = match_files(configs, iter(files)) 

384 

385 # Count files with and without scope matches 

386 for path_str, path_match in results.paths.items(): 

387 if path_match.scopes: 

388 num_matched += 1 

389 else: 

390 uncovered_files.append(path_str) 

391 num_total += 1 

392 

393 # Also count files that weren't in the results (no scope matches at all) 

394 for f in all_files: 

395 if f not in results.paths: 

396 uncovered_files.append(f) 

397 num_total += 1 

398 

399 percentage = (num_matched / num_total) * 100 

400 

401 # Display coverage statistics 

402 if num_matched == num_total: 

403 click.secho(f"\n✓ {num_matched}/{num_total} files covered (100.0%)", fg="green") 

404 else: 

405 # Show uncovered files 

406 if uncovered_files: 

407 click.echo("\nUncovered files:") 

408 for file in sorted(uncovered_files)[:10]: # Show first 10 

409 click.echo(f" - {file}") 

410 if len(uncovered_files) > 10: 

411 click.echo(f" ...and {len(uncovered_files) - 10} more") 

412 

413 click.secho( 

414 f"\n{num_matched}/{num_total} files covered ({percentage:.1f}%)", 

415 fg="yellow", 

416 ) 

417 

418 if check_flag and num_matched != num_total: 

419 sys.exit(1) 

420 

421 

422@cli.command( 

423 "diff", 

424 context_settings={ 

425 "ignore_unknown_options": True, 

426 # Everything from the first git argument onward is git's, verbatim — 

427 # including a `--` separator, which click otherwise swallows. Without 

428 # this, `pullapprove diff HEAD -- deleted.py` reaches git as 

429 # `diff HEAD deleted.py`, and git refuses a path it can't also read as 

430 # a revision. The cost is that PullApprove's own flags have to come 

431 # first, which the help text says. 

432 "allow_interspersed_args": False, 

433 }, 

434) 

435@click.option( 

436 "--hide", 

437 "hide_families", 

438 multiple=True, 

439 help="Hide only these label families, e.g. formatting (repeatable). " 

440 "Default: hide every labeled hunk.", 

441) 

442@click.option( 

443 "--no-pager", 

444 is_flag=True, 

445 help="Write to stdout instead of paging (paging is the default at a terminal).", 

446) 

447@click.option( 

448 "--quiet", is_flag=True, help="Don't print the hidden-hunk summary to stderr." 

449) 

450@click.argument("git_diff_args", nargs=-1, type=click.UNPROCESSED) 

451def diff( 

452 hide_families: tuple[str, ...], 

453 no_pager: bool, 

454 quiet: bool, 

455 git_diff_args: tuple[str, ...], 

456) -> None: 

457 """ 

458 Show a diff with mechanically-trivial hunks hidden — a trust-aware `git diff`. 

459 

460 Runs `git diff`, forwarding any extra arguments (`--staged`, revisions, 

461 pathspecs); with no arguments, piped stdin is read instead. Trusted hunks — 

462 lockfiles, whitespace, formatting, comments, imports, type annotations — are 

463 dropped, and the result stays a valid unified diff. At a terminal the output 

464 is paged through git's pager (like `git diff`); when piped it goes straight 

465 to stdout: 

466 

467 pullapprove diff # paged, an alternative to `git diff` 

468 pullapprove diff --staged # forwarded to git 

469 pullapprove diff main -- app/ # `--` and pathspecs reach git intact 

470 git diff | pullapprove diff # paged 

471 git diff | pullapprove diff --no-pager | delta 

472 

473 PullApprove's own options (--hide, --no-pager, --quiet) must come 

474 before the first git argument. Everything from there on is handed to git 

475 untouched, so `--` and pathspecs mean to git exactly what they always do. 

476 """ 

477 # --hide takes a family (e.g. formatting) or a full label (formatting:style). 

478 # Reject typos up front so a misspelled filter can't silently hide everything. 

479 known = TRUST_FAMILIES | {label.value for label in Trust} 

480 unknown = [name for name in hide_families if name not in known] 

481 if unknown: 

482 raise click.BadParameter( 

483 f"unknown trust {'family' if len(unknown) == 1 else 'families'}: " 

484 f"{', '.join(unknown)}. " 

485 f"Valid families: {', '.join(sorted(TRUST_FAMILIES))}.", 

486 param_hint="--hide", 

487 ) 

488 

489 diff_text = _read_diff(git_diff_args) 

490 

491 def is_hidden(label: Trust) -> bool: 

492 if not hide_families: 

493 return True 

494 return label in hide_families or label.family in hide_families 

495 

496 # Classify each hunk, queueing one keep/hide decision per hunk in document 

497 # order. `filter_diff_text` re-parses the same lines with the same header 

498 # parsers, so its `keep_hunk` calls arrive in that same order and the queue 

499 # joins the two walks — no coordinate keys needed (concatenated multi-commit 

500 # input like `git log -p` can repeat identical coordinates). The shared 

501 # `split("\n")` is what guarantees the alignment: `str.splitlines` also 

502 # breaks on `\r` and other separators, which could let the two walks see 

503 # different lines. 

504 keep: deque[bool] = deque() 

505 counts: Counter[str] = Counter() 

506 for file, hunk in iter_file_hunks(diff_text.split("\n")): 

507 label = trust_label(file, hunk) 

508 if label and is_hidden(label): 

509 keep.append(False) 

510 counts[label] += 1 

511 else: 

512 keep.append(True) 

513 

514 filtered = filter_diff_text( 

515 diff_text, lambda path, old_line, new_line: keep.popleft() 

516 ) 

517 

518 # Page at a terminal like git does; pipe straight through when redirected. 

519 if no_pager or not sys.stdout.isatty(): 

520 click.echo(filtered, nl=False) 

521 else: 

522 git.page(filtered) 

523 

524 if not quiet and counts: 

525 total = sum(counts.values()) 

526 breakdown = ", ".join(f"{label} ({n})" for label, n in sorted(counts.items())) 

527 click.secho( 

528 f"Hid {total} {plural(total, 'hunk')}: {breakdown}", 

529 fg="yellow", 

530 err=True, 

531 ) 

532 

533 

534def _read_diff(git_diff_args: tuple[str, ...]) -> str: 

535 """Read a unified diff: from `git diff` when arguments were given, from piped 

536 stdin otherwise. 

537 

538 Explicit arguments always win — hooks, CI, and cron run with stdin redirected 

539 from /dev/null (not a tty), and `pullapprove diff --staged` there must run 

540 git, not silently read an empty stdin.""" 

541 if not git_diff_args and not sys.stdin.isatty(): 

542 return sys.stdin.read() 

543 try: 

544 # Run from the caller's cwd (not the repo root) so any forwarded pathspec 

545 # is resolved relative to where the user invoked us, matching `git diff`. 

546 # Git still emits repo-root-relative paths in the diff body regardless. 

547 return "".join(git.git_diff_stream(Path.cwd(), *git_diff_args)) 

548 except subprocess.CalledProcessError as exc: 

549 # Not a git repo, or git rejected the arguments — git already explained 

550 # why on stderr, so exit cleanly instead of dumping a traceback. 

551 raise click.ClickException("Could not read a diff from git.") from exc 

552 

553 

554@cli.command("trust", context_settings={"ignore_unknown_options": True}) 

555@click.option( 

556 "--list", 

557 "list_hunks", 

558 is_flag=True, 

559 help="List every hunk and its trust label, grouped by file.", 

560) 

561@click.argument("git_diff_args", nargs=-1, type=click.UNPROCESSED) 

562def trust(list_hunks: bool, git_diff_args: tuple[str, ...]) -> None: 

563 """ 

564 Report what the trust classifier identifies in a diff. 

565 

566 Runs `git diff`, forwarding any extra arguments (`--staged`, revisions, 

567 pathspecs); with no arguments, piped stdin is read instead. The default 

568 prints a summary of how much of the change is mechanical; --list prints 

569 every hunk and its label, so you can see — and debug — exactly what the 

570 classifier identifies. 

571 """ 

572 files = trust_diff(_read_diff(git_diff_args)) 

573 if list_hunks: 

574 _trust_list(files) 

575 else: 

576 _trust_summary(files) 

577 

578 

579def _hunk_header(hunk: DiffHunk) -> str: 

580 old = ( 

581 f"{hunk.old_line}" 

582 if hunk.old_length is None 

583 else f"{hunk.old_line},{hunk.old_length}" 

584 ) 

585 new = ( 

586 f"{hunk.new_line}" 

587 if hunk.new_length is None 

588 else f"{hunk.new_line},{hunk.new_length}" 

589 ) 

590 return f"@@ -{old} +{new} @@" 

591 

592 

593def _trust_list(files: list[DiffFile]) -> None: 

594 hunks = [(file, hunk) for file in files for hunk in file.hunks] 

595 if not hunks: 

596 click.echo("No changes.") 

597 return 

598 width = max(len(_hunk_header(hunk)) for _, hunk in hunks) 

599 current_path = None 

600 for file, hunk in hunks: 

601 if file.new_path != current_path: 

602 current_path = file.new_path 

603 click.secho(current_path, bold=True) 

604 header = _hunk_header(hunk).ljust(width) 

605 label = ( 

606 click.style(hunk.trust, fg="green") 

607 if hunk.trust 

608 else click.style("needs review", fg="yellow") 

609 ) 

610 click.echo(f" {header} {label}") 

611 

612 

613def _trust_summary(files: list[DiffFile]) -> None: 

614 all_hunks = [hunk for file in files for hunk in file.hunks] 

615 total = len(all_hunks) 

616 if not total: 

617 click.echo("No changes.") 

618 return 

619 

620 counts = Counter(hunk.trust for hunk in all_hunks if hunk.trust) 

621 n_trusted = sum(counts.values()) 

622 n_review = total - n_trusted 

623 

624 def pct(n: int) -> int: 

625 return round(n / total * 100) 

626 

627 click.echo( 

628 f"{total} {plural(total, 'hunk')} · {len(files)} {plural(len(files), 'file')}" 

629 ) 

630 

631 click.secho(f" {n_trusted} trusted ({pct(n_trusted)}%)", fg="green") 

632 if counts: 

633 width = max(len(label) for label in counts) 

634 for label, n in sorted(counts.items(), key=lambda kv: (-kv[1], kv[0])): 

635 click.echo(f" {label.ljust(width)} {n:>3}") 

636 click.secho(f" {n_review} need review ({pct(n_review)}%)", fg="yellow") 

637 

638 fully = [ 

639 file.new_path 

640 for file in files 

641 if file.hunks and all(hunk.trust for hunk in file.hunks) 

642 ] 

643 if fully: 

644 shown = ", ".join(fully[:10]) 

645 more = f" +{len(fully) - 10} more" if len(fully) > 10 else "" 

646 click.echo( 

647 f" {len(fully)} {plural(len(fully), 'file')} fully trusted: {shown}{more}" 

648 ) 

649 

650 

651# list - find open PRs, find status url and send json request (needs PA token)