springclean 0.1.0__tar.gz

springclean-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mario Ribeiro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

springclean-0.1.0/PKG-INFO

@@ -0,0 +1,390 @@
+Metadata-Version: 2.4
+Name: springclean
+Version: 0.1.0
+Summary: Spring Clean is a read-only GitHub repository cleanup audit tool.
+Author: Mario Ribeiro
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/marioribeiro/springclean
+Project-URL: Repository, https://github.com/marioribeiro/springclean
+Project-URL: Issues, https://github.com/marioribeiro/springclean/issues
+Keywords: github,audit,branches,pull-requests,cleanup
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: textual>=8.2.5
+Provides-Extra: dev
+Requires-Dist: build>=1.5.0; extra == "dev"
+Requires-Dist: coverage[toml]>=7.13.5; extra == "dev"
+Requires-Dist: pytest>=9.0.3; extra == "dev"
+Requires-Dist: ruff>=0.15.12; extra == "dev"
+Requires-Dist: twine>=6.2.0; extra == "dev"
+Dynamic: license-file
+
+# Spring Clean
+
+Spring Clean is a read-only GitHub repository cleanup tool. It helps teams review old branches and open pull requests so they can decide what to keep, close, or delete manually.
+
+The command is called `springclean`.
+
+Spring Clean never changes GitHub. It does not delete branches, close pull requests, push commits, or update repository settings.
+
+## What It Does
+
+- Shows saved audit reports in a terminal browser.
+- Audits one GitHub repository at a time.
+- Lists branches, latest activity, protection/default status, and associated pull requests.
+- Lists currently open pull requests, including drafts.
+- Adds cleanup status and reason columns to guide review.
+- Adds editable `review_action` and `review_comment` columns for team decisions.
+- Writes timestamped local files so reports do not overwrite each other.
+- Can list repositories available to your GitHub token.
+
+The terminal browser is built with [Textual](https://textual.textualize.io/), a Python framework for terminal user interfaces.
+
+## What You Need
+
+- Python 3.10 or newer.
+- A GitHub token that can read the repositories you want to audit.
+- Terminal access on the machine that can reach those repositories.
+
+For private repositories, use a token with read access to repository contents and pull requests. A fine-grained GitHub token with read-only permissions is recommended.
+
+## Quick Start
+
+Create and activate a virtual environment:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+```
+
+Install Spring Clean:
+
+```bash
+python -m pip install springclean
+```
+
+Create a local `.env` file in the directory where you will run Spring Clean:
+
+```bash
+GITHUB_TOKEN=ghp_your_token_here
+```
+
+Open Spring Clean:
+
+```bash
+springclean
+```
+
+If your machine uses `python3` and `pip3`, use these instead:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install springclean
+```
+
+## Using The Browser
+
+Run:
+
+```bash
+springclean
+```
+
+Spring Clean opens on the reports list. From there you can:
+
+- load an existing report
+- list repositories available to your token
+- run a new audit
+- search and filter rows
+- tag branch and pull request rows for follow-up
+- delete old local reports after confirmation
+
+Keyboard controls:
+
+| Key | Action |
+| --- | --- |
+| `o` | Show reports |
+| `b` | Show branch report |
+| `p` | Show pull request report |
+| `g` | Enter a GitHub repo or URL and run a new audit |
+| `l` | List repositories available to `GITHUB_TOKEN` |
+| `d` | Delete the selected local report, or mark a branch for deletion / PR for closure |
+| `k` | Mark the selected branch or PR as keep |
+| `r` | Mark the selected branch or PR as review |
+| `c` | Add or edit a short review comment |
+| `u` | Clear the selected review action and comment |
+| `enter` | Load the selected report or audit the selected GitHub repo |
+| `/` | Focus search |
+| `s` | Cycle filters |
+| `a` | Reset to all rows |
+| `escape` | Clear search or cancel a modal |
+| `q` | Quit |
+
+Delete only removes local Spring Clean report files. GitHub is not changed.
+
+Review tags are saved back into the selected branch or pull request CSV. They do not call the GitHub API.
+
+## Running Audits From The Command Line
+
+The browser is the main workflow, but the CLI is useful for repeatable runs or scripts.
+
+Audit branches:
+
+```bash
+springclean repo marioribeiro/springclean --branch
+```
+
+Audit open and draft pull requests:
+
+```bash
+springclean repo marioribeiro/springclean --pr
+```
+
+Audit both:
+
+```bash
+springclean repo marioribeiro/springclean --branch --pr
+```
+
+Use a different stale threshold:
+
+```bash
+springclean repo marioribeiro/springclean --branch --pr --stale-days 180
+```
+
+Choose another output directory:
+
+```bash
+springclean repo marioribeiro/springclean --branch --pr --out team-reports
+```
+
+Use another reports directory in the browser:
+
+```bash
+springclean --reports-dir team-reports
+```
+
+Show help:
+
+```bash
+springclean --help
+springclean repo --help
+```
+
+Show the installed version:
+
+```bash
+springclean --version
+```
+
+## Output Files
+
+By default, reports are written to `./reports`.
+
+File names include the repository and UTC timestamp:
+
+```text
+reports/marioribeiro_springclean_20260507T134500Z_branches.csv
+reports/marioribeiro_springclean_20260507T134500Z_pull_requests.csv
+reports/marioribeiro_springclean_20260507T134500Z_summary.md
+```
+
+Generated reports may contain private repo names, branch names, pull request titles, and usernames. Treat them as internal artifacts when auditing private repositories.
+
+## Branch Report
+
+The branch CSV includes:
+
+- branch name and GitHub links
+- best-effort branch creator/context owner
+- default and protected flags
+- latest commit metadata
+- days since latest commit
+- GitHub-like activity bucket
+- associated pull request numbers, authors, states, and URLs
+- cleanup status and reason
+- editable `review_action` and `review_comment` columns
+
+GitHub does not expose a durable branch creator field through the branch API. `branch_created_by` is inferred in this order:
+
+1. Associated PR author, when GitHub links the branch to a PR
+2. Latest commit author
+3. Latest commit committer
+
+`branch_created_by_source` records which fallback was used.
+
+Branch buckets:
+
+| Bucket | Meaning |
+| --- | --- |
+| `default` | Repository default branch |
+| `active` | Non-default branch with commits inside the stale threshold |
+| `stale` | Non-default branch with no commits inside the stale threshold |
+
+Branch cleanup statuses:
+
+| Status | Meaning |
+| --- | --- |
+| `keep_default` | Default branch |
+| `keep_protected` | Protected branch |
+| `review_active` | Branch has recent commit activity |
+| `review_stale_open_pr` | Stale branch has at least one associated open PR |
+| `candidate_stale_merged_pr` | Stale branch has at least one associated merged PR |
+| `candidate_stale_closed_pr` | Stale branch only has closed/unmerged associated PRs |
+| `candidate_stale_no_pr` | Stale branch has no associated PRs |
+
+## Pull Request Report
+
+The pull request CSV includes only currently open pull requests, including drafts.
+
+It includes:
+
+- PR number, title, state, and draft flag
+- `created_by`
+- base and head branch details
+- created and updated timestamps
+- age columns
+- GitHub URL
+- cleanup status and reason
+- editable `review_action` and `review_comment` columns
+
+Pull request cleanup statuses:
+
+| Status | Meaning |
+| --- | --- |
+| `open_active` | Open PR updated inside the stale threshold |
+| `open_stale` | Open PR not updated inside the stale threshold |
+| `draft_active` | Draft PR updated inside the stale threshold |
+| `draft_stale` | Draft PR not updated inside the stale threshold |
+
+## Summary
+
+The Markdown summary includes:
+
+- repo name and default branch
+- generation timestamp
+- stale threshold
+- branch counts by bucket and cleanup status
+- open PR counts by draft/ready state and cleanup status
+
+Use it as a quick overview before reviewing rows in the browser or CSV.
+
+## Troubleshooting
+
+`Missing GITHUB_TOKEN`
+
+Add `GITHUB_TOKEN` to `.env`, or set it in the shell where you run Spring Clean.
+
+`Could not access owner/repo`
+
+Check that the repository name is in `owner/name` format, the token can access that repository, and the command is running from the directory that contains your `.env`.
+
+`GitHub API returned 403`
+
+The token may not have enough permission, the API rate limit may be exhausted, or GitHub may have applied a secondary rate limit. Wait and retry, or use a token with the expected repository access.
+
+`python: command not found`
+
+Try the same command with `python3`:
+
+```bash
+python3 -m pip install springclean
+```
+
+## For Developers
+
+Install development dependencies:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+Create a local `.env` file from the example when working from the repository:
+
+```bash
+cp .env.example .env
+```
+
+Run tests:
+
+```bash
+coverage run -m pytest
+coverage report
+```
+
+The coverage gate is configured at 95%.
+
+Run lint and formatting checks:
+
+```bash
+ruff check .
+ruff format --check .
+```
+
+Build and check the package:
+
+```bash
+python -m build
+python -m twine check dist/*
+```
+
+Useful local checks:
+
+```bash
+springclean --help
+springclean repo --help
+```
+
+## Publishing
+
+The PyPI package name is `springclean`.
+
+Publishing uses PyPI Trusted Publishing through GitHub Actions. Before the first release, create pending trusted publishers in PyPI and TestPyPI with these values:
+
+| Field | PyPI | TestPyPI |
+| --- | --- | --- |
+| PyPI project name | `springclean` | `springclean` |
+| Owner | `marioribeiro` | `marioribeiro` |
+| Repository | `springclean` | `springclean` |
+| Workflow | `publish.yml` | `publish.yml` |
+| Environment | `pypi` | `testpypi` |
+
+Require manual approval for the `pypi` GitHub environment before publishing real releases.
+
+To test the package flow without publishing to PyPI, run the `Publish` workflow manually. That publishes to TestPyPI.
+
+To publish a real release:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+Main runtime dependency:
+
+- [Textual](https://textual.textualize.io/) for the terminal browser
+
+## Project Principles
+
+- Product name in prose: **Spring Clean**
+- CLI command: `springclean`
+- Read-only by default and by design
+- CSV-first for easy team review
+- Terminal review should work from saved report files unless the user explicitly asks for a GitHub action
+- Prefer explicit cleanup signals over hidden automation
+
+## License
+
+MIT