dep-pr-cleanup

Files (13)

• SKILL.md
• coverage-rules.md · references/
• manifest-formats.md · references/
• report-format.md · references/
• analyze_prs.py · scripts/
• collect_prs.py · scripts/
• __init__.py · scripts/deplib/
• coverage.py · scripts/deplib/
• diffparse.py · scripts/deplib/
• ghcli.py · scripts/deplib/
• manifests.py · scripts/deplib/
• versions.py · scripts/deplib/
• verify_selection.py · scripts/

SKILL.md (first lines)

# dep-pr-cleanup

Dependency bots open pull requests faster than teams merge them. Renovate opens a minor and a
major PR side by side, a grouped PR repeats updates that single PRs already carry, a security
update targets an older version than the version-update PR next to it. This skill finds the
bot PRs whose every update is already contained in other open PRs of the same bot, shows the
overlaps, and closes the obsolete ones once the user has agreed.

## Contract

- **Input:** a GitHub repository (the working directory's by default); optionally extra bot
  accounts, the replacement options, and `.github/dep-pr-cleanup.json`.
- **Output:** a side-by-side comparison of the overlapping bot PRs and the proposed obsolete
  ones in the conversation; after confirmation, the chosen PRs closed with a comment and their
  branches deleted; a report in `docs/dep-pr-cleanup/`.
- **Not in scope:** merging, rebasing, or approving PRs; changing manifests; configuring the bots.
- **Never commits.** The report is written to the working tree; the user decides about it.

## Why the rules are what they are

Closing a bot PR is not free: Renovate treats a closed PR as "ignore this update" — closing
"Update lodash to v4.17.21" ignores that version, closing "Update lodash to v4" ignores every
future v4 update — and Dependabot answers a closed PR with "I won't notify you again about this
release". An update that was wrongly judged as covered is silently lost. Hence:

- **Obsolete means fully covered by PRs that stay open.** A PR is proposed only when *each* of
  its updates — same ecosystem, same package, same manifest path — is contained in another open
  PR of the same bot against the same base branch, at the same target version or, if the user
  allows it, a newer one. A covering PR is never itself proposed, so closing any subset of the
  proposals is safe.
- **Only the diff counts.** Titles and descriptions are templated and incomplete; the manifest
  lines the PR actually changes are the truth. Lockfiles are ignored (they carry transitive
  noise). A changed manifest line that cannot be interpreted makes the whole PR *unevaluable*:
  it is never proposed and never counts as a cover.
- **The scripts decide, not you.** Coverage is computed by `analyze_prs.py`. Do not move a PR
  between "obsolete" and "kept" by reading the diff yourself; if a result looks wrong, explain it
  with [references/coverage-rules.md](references/coverage-rules.md) or report it.

## Prerequisites

- `gh` (GitHub CLI), authenticated with write access to the repository for closing
  (`gh auth status`). If missing or not logged in, stop and suggest `! gh auth login`.
- Python 3.8+ with the standard library only. Find the interpreter once and reuse it: try
  `python3 --version`, then `python --version`, then `py -3 --version` (Windows) — take the
  first that prints `Python 3.8` or newer. On Windows, `python3` may be a Microsoft Store stub
  that prints nothing; skip it then. Below, `PY` stands for the command found.

The scripts live in this skill's `scripts/` directory; call them by absolute path. They print
JSON on stdout and accept file paths, so they work the same in bash, zsh, PowerShell, and cmd.
Keep intermediate files in the system temp directory, never in the repository.

## Parameters

| Parameter | Default | Changed by |
| --- | --- | --- |
| Repository | the working directory's GitHub repository | "for acme/shop", `--repo` |
| Bots | `dependabot[bot]`, `renovate[bot]` | the prompt ("also my-renovate[bot]") → `--bot`; config `bots`; config `includeDefaultBots: false` drops the defaults |
| Newer version counts as replacement | **yes** | the prompt; config `newerCountsAsReplacement`; the question in Step 4 |
| … also across major versions | **no** | the prompt; config `acrossMajor`; the question in Step 4 |
| Per-pair exceptions | none | Step 5 |

Precedence: the prompt over `.github/dep-pr-cleanup.json` over the default. Record the origin of
every value (`prompt`, `config`, `question`, `default`) — the report states it. The config file
is optional; `collect_prs.py` reads it from the repository root and rejects unknown keys
(exit 4):

```json
{ "bots": ["my-renovate[bot]"], "includeDefaultBots": true,
  "newerCountsAsReplacement": true, "acrossMajor": false }
```

Why "across major versions" defaults to no: Renovate deliberately opens a minor PR next to a
major PR (`separateMajorMinor`), so the user can take the safe update without the breaking one.
Letting the major PR replace the minor PR would close exactly that safe path.

## Workflow

### Step 1 — Collect

```bash
PY <skill>/scripts/collect_prs.py [--repo OWNER/NAME] [--bot LOGIN]... [--output <tmp>/collected.json]
```

Exit codes: **0** ok (also with zero bot PRs) · **1** usage (also: no bots left to look for) ·
**2** `gh` missing or not authenticated — stop, suggest `! gh auth login` · **3** repository or PR
list not readable — report the message and stop · **4** malformed config file — show the message
and ask the user to fix the file; do not ignore it.

Stdout is a summary with `output` (the file to pass on), `bot_prs`, `bots`, `config`,
`diff_errors`, `other_open_prs`, and `truncated`. If `bot_prs` is 0, say so — name the bots
searched and how many non-bot PRs were skipped — and stop without a report. If `truncated` is
true, re-run with a higher `--limit`.

### Step 2 — Analyze

```bash
PY <skill>/scripts/analyze_prs.py --input <collected> [--newer yes|no] [--across-major yes|no] \
   [--pair-mode COVERER:COVERED=exact|newer|any]... --output <tmp>/analysis.json
```

Exit codes: **0** ok · **1** usage (bad option value, a `--pair-mode` naming an uncollected PR) ·
**3** malformed input — re-collect. The script reads no network, so re-run it freely.

Run it first with the values from the prompt or config, else the defaults. The result holds:

| Field | Meaning |
| --- | --- |
| `prs[]` | every bot PR: `status` `obsolete` / `kept` / `unevaluable`, `updates[]` (ecosystem, name, path, from, to, `major_change`), `unevaluable_reasons[]`, `ignored_lockfiles[]`, `flags` |
| `proposals[]` | the obsolete PRs: `covered_by[]`, `details[]` (each update, the PR that covers it, `relation` `equal` / `newer` / `newer-major`), `warnings[]` |
| `overlaps[]` | every PR pair sharing a package: `shared[]` with both targets and the relation (`equal`, `a-newer`, `b-newer-major`, …), `counted` and `not_counted_reason` (`different-bot`, `different-base`, `unevaluable`) |
| `pair_toggles[]` | directed pairs (`coverer`, `covered`) where a newer target exists: the `mode` in effect, whether those newer targets count now (`counts_now` `all` / `some` / `none`), and the `switch_to` mode that flips it — the candidates for Step 5 |

Which manifest lines are understood and why a PR became unevaluable is in
[references/manifest-formats.md](references/manifest-formats.md); read it when the user asks why
a PR was not evaluated.

### Step 3 — Present the comparison

Write in the conversation's language. Group by bot and base branch. Use

From CreativeCodersTeam/ai-store, Apache-2.0.

More from CreativeCodersTeam/ai-store