API Reference

def build_parser() -> argparse.ArgumentParser:
    """Build the argument parser."""
    parser = argparse.ArgumentParser(
        prog="pup-clean",
        description=(
            "Identify and remove known generated and disposable repository artifacts."
        ),
    )

    parser.add_argument(
        "--root",
        type=Path,
        default=None,
        help=(
            "Repository root to clean. Defaults to the nearest parent "
            "directory containing .git, or the current directory."
        ),
    )

    parser.add_argument(
        "--delete",
        action="store_true",
        help=(
            "Delete detected cleanup targets. Without this flag, "
            "pup-clean performs a dry run only."
        ),
    )

    parser.add_argument(
        "paths",
        nargs="*",
        type=Path,
        help=(
            "Optional repository-relative cleanup targets. "
            "When provided, operate only on detected targets matching these paths."
        ),
    )

    return parser

def main(argv: Sequence[str] | None = None) -> int:
    """Run the command-line interface.

    Args:
        argv: Optional command-line arguments. If None, uses sys.argv.

    Returns:
        Exit code from the clean command.
    """
    parser = build_parser()
    args = parser.parse_args(argv)

    return clean.run(
        root=args.root,
        delete=args.delete,
        paths=tuple(args.paths),
    )

def print_cleanup_plan(
    context: RepositoryContext,
    targets: Sequence[CleanupTarget],
    *,
    delete: bool,
) -> None:
    """Print the repository cleanup plan.

    Args:
        context (RepositoryContext): The repository context.
        targets (Sequence[CleanupTarget]): The list of cleanup targets.
        delete (bool): Whether to actually delete the targets or just perform a dry run.

    Returns:
        None
    """
    mode = "DELETE" if delete else "DRY RUN"

    print(f"[pup-clean] {mode}")
    print(f"[pup-clean] repo: {context.repo_name}")
    print(f"[pup-clean] root: {context.root}")
    print()

    if not targets:
        print("[pup-clean] no cleanup targets found")
        return

    label = "DELETED" if delete else "WOULD DELETE"

    for target in targets:
        suffix = "/" if target.kind == "directory" else ""
        print(f"{label:13} {target.path.as_posix()}{suffix}")

    print()
    print(f"[pup-clean] summary: {len(targets)} cleanup target(s)")

    if not delete:
        print("[pup-clean] nothing deleted; rerun with --delete to apply cleanup")

def discover_generated_paths(root: Path) -> tuple[Path, ...]:
    """Discover generated data artifacts referenced by project source code.

    Python files under ``src/`` are parsed using the AST. Known data-writing
    operations are inspected and statically resolvable output paths are
    returned.

    A path is returned only when it can be resolved from source code with
    sufficient confidence. Dynamic or ambiguous paths are ignored.

    Args:
        root: Repository root.

    Returns:
        Repository-relative paths for discovered generated artifacts.
    """
    src_root = root / "src"

    if not src_root.is_dir():
        return ()

    discovered: set[Path] = set()

    for source_path in sorted(src_root.rglob("*.py")):
        discovered.update(
            _discover_generated_paths_in_file(
                root=root,
                source_path=source_path,
            )
        )

    return tuple(sorted(discovered, key=lambda path: path.as_posix()))