From 1d9625428c7c12861702ca2ff493126c1e6063a0 Mon Sep 17 00:00:00 2001 From: CoderDeltaLan Date: Sat, 13 Sep 2025 08:38:55 +0100 Subject: [PATCH] docs: refresh README (usage, badges, donations) --- README.md | 269 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 261 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 1963fd3..c577bc1 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,273 @@ -# diff-risk-dashboard +# ⭐ diff-risk-dashboard — APV → Risk Summary (Python CLI) -Visual dashboard for Pull Request risk exposure, designed to consume **ai-patch-verifier** JSON outputs. +A lean, production-grade **Python CLI** that ingests **ai-patch-verifier (APV)** JSON and outputs a clear **risk summary** (table / JSON / Markdown). +Designed for **always-green CI**, with strict checks and exit codes per risk level to gate merges professionally. + +
+ +[![CI / build](https://github.com/CoderDeltaLAN/diff-risk-dashboard/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/CoderDeltaLAN/diff-risk-dashboard/actions/workflows/build.yml) +[![CodeQL Analysis](https://github.com/CoderDeltaLAN/diff-risk-dashboard/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/CoderDeltaLAN/diff-risk-dashboard/actions/workflows/codeql.yml) +[![Release](https://img.shields.io/github/v/release/CoderDeltaLAN/diff-risk-dashboard?display_name=tag)](https://github.com/CoderDeltaLAN/diff-risk-dashboard/releases) +![Python 3.11|3.12](https://img.shields.io/badge/Python-3.11%20|%203.12-3776AB?logo=python) +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) +[![Donate](https://img.shields.io/badge/Donate-PayPal-0070ba?logo=paypal&logoColor=white)](https://www.paypal.com/donate/?hosted_button_id=YVENCBNCZWVPW) + +
+ +--- + +## Repo layout + +```text +. +├── examples/ +│ └── sample_apv.json # APV sample for demos/tests +├── src/diff_risk_dashboard/ +│ ├── __main__.py # module entry +│ ├── cli.py # CLI +│ ├── core.py # summarization logic +│ └── report.py # Markdown generator +├── tests/ # pytest +└── .github/workflows/ # CI + CodeQL + Release Drafter +``` + +--- + +## 🚀 Quick Start (end users) + +> Sin cambios en tu sistema ni shell. Usa el proyecto como **app Python** con su comando **`diff-risk`** tras instalarlo. + +```bash +# 1) Clonar +git clone https://github.com/CoderDeltaLAN/diff-risk-dashboard.git +cd diff-risk-dashboard + +# 2) Instalar como paquete (aislado con pipx, o pip estándar) +# Opción A (recomendada): pipx +pipx install . +# Opción B: pip usuario +python -m pip install --user . + +# 3) Usar el comando instalado +diff-risk examples/sample_apv.json --format md --output report.md +``` + +### CLI usage + +```bash +diff-risk -h +``` + +``` +usage: diff_risk_dashboard [-h] [-f {table,json,md}] [-o OUTPUT] + [--no-exit-by-risk] + input + +Diff Risk Dashboard (APV JSON -> summary) + +positional arguments: + input Path o texto JSON de ai-patch-verifier + +options: + -h, --help show this help message and exit + -f {table,json,md}, --format {table,json,md} + Formato de salida + -o OUTPUT, --output OUTPUT + Archivo de salida; '-' = stdout + --no-exit-by-risk No ajustar el exit code por nivel de riesgo +``` + +#### Examples + +Table (por defecto, al stdout): + +```bash +diff-risk examples/sample_apv.json +``` + +JSON (ideal para piping/automatización): + +```bash +diff-risk examples/sample_apv.json -f json +``` + +Markdown a archivo (para adjuntar en PRs/Wikis): + +```bash +diff-risk examples/sample_apv.json -f md -o report.md +``` + +Salida Markdown de ejemplo: + +```md +# Diff Risk Dashboard 🔴 — Worst: **HIGH** + +| Severity | Count | +|---|---:| +| CRITICAL | 0 | +| HIGH | 1 | +| MEDIUM | 1 | +| LOW | 1 | +| INFO | 0 | +| **TOTAL** | **3** | + +> Generated by diff-risk-dashboard CLI +``` + +--- + +## 📦 What the tool expects (APV JSON) + +- Entrada: JSON con findings tipo APV, ej. objetos que incluyen `predicted_risk` (`low|medium|high`). +- El sumario **normaliza mayúsculas/minúsculas** y calcula: + - `total` + - `by_severity` (claves `CRITICAL|HIGH|MEDIUM|LOW|INFO` y también minúsculas) + - `worst` + - `risk_level` (`red|yellow|green`) + +Ejemplo de salida `-f json`: + +```json +{ + "total": 3, + "by_severity": { + "critical": 0, + "high": 1, + "medium": 1, + "low": 1, + "info": 0, + "CRITICAL": 0, + "HIGH": 1, + "MEDIUM": 1, + "LOW": 1, + "INFO": 0 + }, + "worst": "HIGH", + "risk_level": "red" +} +``` + +--- + +## ⛳ Exit codes (CI gating) + +- `green` → **0** +- `yellow` → **1** +- `red` → **2** + +Por defecto, el proceso **sale** con el código según `risk_level`. +Para desactivar este comportamiento (p.ej., en local o cuando solo generas reportes): -## Quick Start ```bash -poetry install -poetry run drd summarize examples/sample_apv.json +diff-risk examples/sample_apv.json --no-exit-by-risk ``` -## Run checks (mirrors CI) +--- + +## 🧪 Local Developer Workflow (mirrors CI) + ```bash +# Requisitos de desarrollo +python -m pip install --upgrade pip +pip install poetry + +# Instalar deps +poetry install --no-interaction + +# Gates locales poetry run ruff check . poetry run black --check . PYTHONPATH=src poetry run pytest -q poetry run mypy src ``` -## License -MIT +--- + +## 🔧 CI (GitHub Actions) + +- Matriz **Python 3.11 / 3.12** alineada con los gates locales. +- **CodeQL** en PRs y `main`. +- **Release Drafter** para changelog/release notes. +- **Branch protection** y merges seguros (historial lineal via squash). + +Fragmento típico del job Python: + +```yaml +- run: python -m pip install --upgrade pip +- run: pip install poetry +- run: poetry install --no-interaction +- run: poetry run ruff check . +- run: poetry run black --check . +- env: + PYTHONPATH: src + run: poetry run pytest -q +- run: poetry run mypy src +# Ejemplo de uso del CLI en CI: +- run: poetry run python -m pip install . +- run: diff-risk examples/sample_apv.json -f md -o report.md +``` + +--- + +## 🗺 When to Use This Project + +- Necesitas **resumen de riesgo** claro y portable a partir de **APV**. +- Quieres **bloquear merges** cuando el riesgo supera el umbral (exit codes). +- Buscas **reportes en Markdown/JSON** para PRs, auditorías y tableros. + +--- + +## 🧩 Customization + +- Genera tus propios APV JSON y pásalos como `input`. +- Cambia el formato con `--format` (**table/json/md**) y redirige a archivo con `--output`. +- Integra el JSON de salida con otras herramientas o dashboards. + +--- + +## 🔒 Security + +- Sin cambios en tu shell o sistema: **no** requiere editar `.zshrc` ni configuración del usuario. +- CodeQL activo; se recomienda usar repos **privados** para datos sensibles. +- No subas JSON con información confidencial a PRs públicos. + +--- + +## 🙌 Contributing + +- PRs pequeños y atómicos, estilo **Conventional Commits**. +- Mantén los **gates** verdes antes de solicitar revisión. +- Activa **auto-merge** cuando pasen los checks. + +--- + +## 💚 Donations & Sponsorship + +If this project saves you time, consider supporting ongoing maintenance. Thank you! +[![Donate](https://img.shields.io/badge/Donate-PayPal-0070ba?logo=paypal&logoColor=white)](https://www.paypal.com/donate/?hosted_button_id=YVENCBNCZWVPW) + +--- + +## 🔎 SEO Keywords + +apv risk summary cli, ai patch verifier json, diff risk dashboard python, +markdown security report, always green ci python, ruff black pytest mypy, +github actions codeql release drafter, branch protection required checks, +console scripts professional cli ux + +--- + +## 👤 Author + +**CoderDeltaLAN (Yosvel)** +GitHub: https://github.com/CoderDeltaLAN + +--- + +## 📄 License + +Released under the **MIT License**. See [LICENSE](LICENSE). + +--- + +**Download this README**: This same file can be downloaded from the chat link.