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
« prev ^ index » next coverage.py v7.14.1, created at 2026-10-31 23:22 -0500
1from __future__ import annotations
3import os
4import subprocess
5import sys
6from collections import Counter, deque
7from pathlib import Path
8from textwrap import dedent
10import click
11from pydantic import ValidationError
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
29@click.group()
30@click.version_option(package_name="pullapprove")
31@click.pass_context
32def cli(ctx: click.Context) -> None:
33 pass
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)
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
50 contents = f"""
51 [[scopes]]
52 name = "default"
53 paths = ["**/*"]
54 request = 1
55 require = 1
56 reviewers = ["<YOU>"]
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}")
69@cli.command()
70@click.option("--quiet", is_flag=True)
71def check(quiet: bool) -> ConfigModels:
72 """
73 Validate configuration files
74 """
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 )
94 errors = {}
95 configs = ConfigModels(root={})
97 for root, _, files in os.walk("."):
98 for f in files:
99 if is_config_filename(f):
100 config_path = Path(root) / f
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 )
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")
115 errors[config_path] = e
117 for path, error in errors.items():
118 click.secho(str(path), fg="red", err=True)
119 click.echo(str(error), err=True)
121 if errors:
122 raise click.ClickException("Configuration validation failed.")
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.")
135 if not configs and not quiet:
136 click.secho(f"No {CONFIG_FILENAME} files found.", fg="red", err=True)
137 sys.exit(1)
139 return configs
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
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
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
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.
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.")
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 )
217 if base and (staged or changed):
218 raise click.UsageError("--base can't be combined with --staged or --changed.")
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()
235 if not configs:
236 raise click.ClickException("No valid configurations found.")
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)}")
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
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 )
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)
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 = []
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 )
316 return match_files(configs, iter(expanded_paths)), expanded_paths
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")
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
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
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()
367 num_matched = 0
368 num_total = 0
369 uncovered_files = []
371 # First, get all files to know the total count for progress bar
372 all_files = list(git.git_ls_files(Path(path)))
374 if not all_files:
375 click.echo("No files found")
376 return
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))
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
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
399 percentage = (num_matched / num_total) * 100
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")
413 click.secho(
414 f"\n{num_matched}/{num_total} files covered ({percentage:.1f}%)",
415 fg="yellow",
416 )
418 if check_flag and num_matched != num_total:
419 sys.exit(1)
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`.
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:
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
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 )
489 diff_text = _read_diff(git_diff_args)
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
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)
514 filtered = filter_diff_text(
515 diff_text, lambda path, old_line, new_line: keep.popleft()
516 )
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)
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 )
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.
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
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.
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)
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} @@"
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}")
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
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
624 def pct(n: int) -> int:
625 return round(n / total * 100)
627 click.echo(
628 f"{total} {plural(total, 'hunk')} · {len(files)} {plural(len(files), 'file')}"
629 )
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")
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 )
651# list - find open PRs, find status url and send json request (needs PA token)