From 50aed32b20cb15516c52f59ba2986728295cd966 Mon Sep 17 00:00:00 2001 From: Roman Marek~ Date: Mon, 9 Mar 2026 13:32:15 +0100 Subject: [PATCH 1/2] ci: add Claude agentic quality gate and project context - Add CLAUDE.md with project context for all Claude agents - Add codecov.yml to suppress spurious uploader warnings - Add claude-quality-gate.yml with three parallel agents: test coverage, docs/changelog enforcement, code review Co-Authored-By: Claude Sonnet 4.6 --- .github/workflows/claude-quality-gate.yml | 110 ++++++++++++++++++++++ CLAUDE.md | 41 ++++++++ codecov.yml | 10 ++ 3 files changed, 161 insertions(+) create mode 100644 .github/workflows/claude-quality-gate.yml create mode 100644 CLAUDE.md create mode 100644 codecov.yml diff --git a/.github/workflows/claude-quality-gate.yml b/.github/workflows/claude-quality-gate.yml new file mode 100644 index 0000000..834a725 --- /dev/null +++ b/.github/workflows/claude-quality-gate.yml @@ -0,0 +1,110 @@ +name: Claude Quality Gate + +on: + pull_request: + branches: [main] + types: [opened, synchronize, reopened] + +permissions: + contents: read + pull-requests: write + issues: write + id-token: write + +jobs: + # Agent 1 — verify tests exist for all changed code + test-coverage-agent: + name: Test Coverage Agent + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - uses: anthropics/claude-code-action@v1 + with: + claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + prompt: | + You are a test quality agent for the ptop3 project. + + Review the diff of this PR (compare HEAD to the base branch) and: + 1. List every new or modified function/method in ptop3/ source files. + 2. Check tests/ to confirm each one has a corresponding test. + 3. For any function missing a test, write the missing test(s) following the project rules: + - Mock /proc/* files with tmp_path fixtures + - Mock curses — never test TUI rendering directly + - Patch os.geteuid for root-required paths + - Tests must pass on Python 3.10–3.13 + 4. If all functions are covered, post a short confirmation comment. + 5. If you added tests, create a commit on this PR branch with message "test: add missing tests for " + + Project test style is in tests/conftest.py and existing test files. + Quality rules are in .github/instructions/code-review.instructions.md. + + # Agent 2 — verify CHANGELOG and docs are updated + docs-changelog-agent: + name: Docs & Changelog Agent + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - uses: anthropics/claude-code-action@v1 + with: + claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + prompt: | + You are a documentation quality agent for the ptop3 project. + + Review the diff of this PR and: + + 1. CHANGELOG check: + - If any user-facing behavior changed (new feature, bug fix, CLI flag, keybinding), + verify CHANGELOG.md has an entry under ## [Unreleased]. + - If missing, add the appropriate entry under the correct section + (Added / Changed / Fixed / Security / Deprecated / Removed). + - Do NOT bump version numbers. + + 2. README check: + - If new keybindings, CLI flags, or entry points were added, verify README.md documents them. + - If missing, add the documentation. + + 3. Docstring check: + - For any new public function in ptop3/ that lacks a docstring, add a one-line docstring. + + If you made changes, commit them with message "docs: update changelog/readme for ". + If everything is already documented, post a short confirmation comment. + + # Agent 3 — code quality and security review + code-review-agent: + name: Code Review Agent + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - uses: anthropics/claude-code-action@v1 + with: + claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + prompt: | + You are a code quality and security agent for the ptop3 project. + + Review the diff of this PR against the standards in + .github/instructions/code-review.instructions.md and check for: + + 1. Style violations: bare except, print() in library code, typing.Dict/List/Optional, + shell=True in subprocess, string path concatenation instead of pathlib. + 2. Security issues: unsanitized input to subprocess, hardcoded secrets, + missing root check before writing /proc/sys/vm/drop_caches or calling swapoff/swapon, + missing visudo validation before sudoers writes. + 3. GitHub Actions: missing permissions blocks, missing skip-existing on TestPyPI steps. + 4. Module-specific rules from the instructions file. + + For each issue found: + - Post an inline PR review comment at the exact file+line. + - If the fix is straightforward (style, missing guard), apply it directly and commit + with message "fix: ". + - If the fix requires design decisions, comment only — do not auto-fix. + + If no issues are found, post a brief approval comment summarising what was checked. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..cc61a97 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,41 @@ +# ptop3 — Claude Code Context + +`ptop3` is a Linux TUI process monitor (htop-like) that groups processes by application. +It uses `curses` for the UI, `psutil` for process data, and ships two privileged scripts +(`ptop3-drop-caches`, `ptop3-swap-clean`) that run via passwordless sudo. + +## Key Files + +| File | Purpose | +|------|---------| +| `ptop3/monitor.py` | Core TUI + data aggregation | +| `ptop3/sudo_config.py` | Passwordless sudo setup | +| `ptop3/scripts/drop_caches.py` | Kernel cache clearing | +| `ptop3/scripts/swap_clean.py` | Swap cleanup | +| `tests/` | Pytest suite — all 4 Python versions | +| `CHANGELOG.md` | User-facing change log | +| `.github/instructions/code-review.instructions.md` | Full style & quality guide | + +## Code Standards + +- Python 3.10+: use `X | None`, `list[str]`, `match`, builtin generics — no `typing.Dict/List/Optional` +- Ruff: line-length 100, rules E/F/I/UP — run `ruff check ptop3/` before committing +- No bare `except:`, no `print()` in library code, no `shell=True` in subprocess calls +- File paths via `pathlib.Path` — never string concatenation + +## Testing + +- Run: `pytest --cov=ptop3 --cov-report=term-missing` +- Every new function must have a test; mock `/proc/*` files with `tmp_path`; mock `curses` +- Tests must not require root — patch `os.geteuid` for privileged paths + +## CHANGELOG + +Every PR with user-facing changes must add an entry under `## [Unreleased]`. +Sections: `Added`, `Changed`, `Fixed`, `Security`, `Deprecated`, `Removed`. +Do **not** bump versions manually — that's handled by `bump-my-version` in the release workflow. + +## Commits + +Conventional format: `feat:`, `fix:`, `docs:`, `ci:`, `chore:`, `refactor:`, `test:` +CI must be green on all 4 Python versions (3.10–3.13) before merging. diff --git a/codecov.yml b/codecov.yml new file mode 100644 index 0000000..2f1ac83 --- /dev/null +++ b/codecov.yml @@ -0,0 +1,10 @@ +coverage: + status: + project: + default: + target: auto + threshold: 1% + +codecov: + notify: + after_n_builds: 4 # match matrix size (3.10, 3.11, 3.12, 3.13) From 550d54c95b0d11b6984150e6c7bea74a7fda66db Mon Sep 17 00:00:00 2001 From: Roman Marek~ Date: Mon, 9 Mar 2026 13:35:30 +0100 Subject: [PATCH 2/2] ci: publish to TestPyPI on test branch push instead of main MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Aligns with feature → test → main branching strategy: test branch is now the staging gate before production. Co-Authored-By: Claude Sonnet 4.6 --- .github/workflows/publish-testpypi.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/publish-testpypi.yml b/.github/workflows/publish-testpypi.yml index 7e9aeca..71569f9 100644 --- a/.github/workflows/publish-testpypi.yml +++ b/.github/workflows/publish-testpypi.yml @@ -2,7 +2,7 @@ name: Publish to TestPyPI on: push: - branches: [main] + branches: [test] workflow_dispatch: permissions: