From 19c66103ec2094e95eab9156435e09685845807a Mon Sep 17 00:00:00 2001 From: CoderDeltaLan Date: Sat, 13 Sep 2025 15:15:20 +0100 Subject: [PATCH 1/3] docs(manual): complete, professional user guide --- docs/MANUAL.md | 313 +++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 300 insertions(+), 13 deletions(-) diff --git a/docs/MANUAL.md b/docs/MANUAL.md index 76ef81d..6f333d1 100644 --- a/docs/MANUAL.md +++ b/docs/MANUAL.md @@ -1,13 +1,300 @@ -# Diff Risk Dashboard — Manual - -This manual complements **docs/USAGE.md** with project context. -- Quick usage & CLI examples: see **docs/USAGE.md**. -- Short wrappers: drt/drb/drj/drmd (file or inline JSON). -- Exit codes: 0 (green), 1 (yellow), 2 (red). Use `--no-exit-by-risk` to force 0. - -More sections to expand: -1) Installation & environment -2) Input format (APV JSON) -3) Output formats (table, bar, json, md) -4) CI usage & exit codes -5) Troubleshooting +# Diff Risk Dashboard — User Manual + +> **Version:** v0.4.x • **Scope:** Complete guide for end‑users and maintainers +> **Project:** `diff-risk-dashboard` — APV → Risk Summary (Python CLI) + +--- + +## Table of Contents +- [1. What is this?](#1-what-is-this) +- [2. Who is it for](#2-who-is-it-for) +- [3. Installation](#3-installation) +- [4. Quick Start](#4-quick-start) +- [5. Inputs (APV JSON)](#5-inputs-apv-json) +- [6. Output formats](#6-output-formats) +- [7. Exit codes & CI gating](#7-exit-codes--ci-gating) +- [8. Short wrappers](#8-short-wrappers) +- [9. CLI reference](#9-cli-reference) +- [10. CI/CD integration (GitHub Actions)](#10-cicd-integration-github-actions) +- [11. Color/TTY tips](#11-colortty-tips) +- [12. Troubleshooting](#12-troubleshooting) +- [13. FAQ](#13-faq) +- [14. Security & Privacy](#14-security--privacy) +- [15. Contributing](#15-contributing) +- [16. Versioning & Releases](#16-versioning--releases) +- [17. Support](#17-support) +- [18. License](#18-license) + +--- + +## 1. What is this? +`diff-risk-dashboard` is a lean, production‑grade **Python CLI** that ingests +**ai‑patch‑verifier (APV)** JSON and emits a **risk summary** in **table**, **JSON**, +or **Markdown**. It is designed for **always‑green CI**, providing clear **exit codes** +to gate merges by risk level. + +### Key capabilities +- Normalize APV severities (`CRITICAL|HIGH|MEDIUM|LOW|INFO`, case‑insensitive). +- Summaries: `total`, `by_severity`, `worst`, and aggregate `risk_level`. +- Output suitable for **terminals**, **bots**, **PR comments**, and **dashboards**. + +--- + +## 2. Who is it for +- **Developers & DevOps**: need deterministic summaries to automate merge gates. +- **Security/QA**: require exportable JSON/Markdown for audits and reporting. +- **Team leads**: want a quick “is it safe to merge?” signal in CI. + +--- + +## 3. Installation + +### Option A — pipx (recommended) +```bash +pipx install . # run in project root, or: pipx install git+https://github.com/CoderDeltaLAN/diff-risk-dashboard.git +``` + +### Option B — pip (user site) +```bash +python -m pip install --user . +``` + +### Option C — development (Poetry) +```bash +pip install poetry +poetry install --no-interaction +``` + +> After installing, the `diff-risk` command is available on your PATH. + +--- + +## 4. Quick Start + +Run with the bundled sample: +```bash +diff-risk examples/sample_apv.json -f table +``` + +Generate Markdown to a file: +```bash +diff-risk examples/sample_apv.json -f md -o report.md +``` + +Inline JSON (single quotes outside, double inside): +```bash +diff-risk '{"by_severity":{"CRITICAL":0,"HIGH":1,"MEDIUM":1,"LOW":1,"INFO":0}}' -f table +``` + +--- + +## 5. Inputs (APV JSON) + +The tool accepts either: +1) **File path** to JSON, or +2) **Inline JSON** text (starting with `{` or `[`). + +Minimum shapes supported: +- **Aggregated**: + ```json + { "by_severity": { "HIGH": 1, "MEDIUM": 2, "LOW": 3 } } + ``` +- **Flat list** (each item has a severity/level field): + ```json + [ + {"severity":"high", "title":"..."}, + {"predicted_risk":"medium", "id": 42} + ] + ``` + +The CLI normalizes severities and computes: +- `total` +- `by_severity` (both UPPER and lower keys are included for convenience) +- `worst` (string) +- `risk_level`: `"red" | "yellow" | "green"` + +--- + +## 6. Output formats + +### Table (TTY‑friendly) +```bash +diff-risk input.json -f table +``` + +### JSON (machines/CI) +```bash +diff-risk input.json -f json +``` + +Example 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" +} +``` + +### Markdown (reports/PRs) +```bash +diff-risk input.json -f md -o _intel/report.md +``` + +--- + +## 7. Exit codes & CI gating + +Default behavior (raw CLI): +- `green` → exit **0** +- `yellow` → exit **1** +- `red` → exit **2** + +To force **always 0** (useful locally or for non‑blocking jobs): +```bash +diff-risk input.json --no-exit-by-risk +``` + +--- + +## 8. Short wrappers + +Convenience scripts (installed in `bin/`): +- `drt ` — colored table (TTY) +- `drb ` — bars (logs) +- `drj ` — JSON (CI) +- `drmd ` — Markdown (stdout) + +Examples: +```bash +drt examples/sample_apv.json +drt '{"by_severity":{"CRITICAL":0,"HIGH":1,"MEDIUM":1,"LOW":1,"INFO":0}}' +APV="/absolute/path/to/your_apv.json"; drt "$APV" +``` + +Add to PATH: +```bash +mkdir -p ~/.local/bin && ln -sf "$PWD/bin/"* ~/.local/bin/ && hash -r +``` + +--- + +## 9. CLI reference + +```bash +diff-risk -h +``` + +Options (common): +- `-f, --format {table,json,md,bar}` — output format +- `-o, --output` — file path; `-` = stdout +- `--no-exit-by-risk` — disable exit code gating + +--- + +## 10. CI/CD integration (GitHub Actions) + +Minimal job (Python 3.11 / 3.12): +```yaml +- uses: actions/checkout@v4 +- uses: actions/setup-python@v5 + with: + python-version: '3.12' +- 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 +# Smoke: +- run: | + poetry build + poetry run python -m pip install . + diff-risk examples/sample_apv.json -f md -o _intel/report.md +``` + +Upload report artifact: +```yaml +- uses: actions/upload-artifact@v4 + with: + name: sample-report + path: _intel/report.md +``` + +--- + +## 11. Color/TTY tips + +To force colorized output in recordings/CI logs: +```bash +script -qfc "drt examples/sample_apv.json" /dev/null +``` + +--- + +## 12. Troubleshooting + +- **JSONDecodeError**: Your argument is neither a readable file nor valid JSON. + Use a valid path or wrap inline JSON like: `'{"by_severity":{"HIGH":1}}'`. + +- **Exit code > 0 unexpectedly**: You likely used the raw CLI without + `--no-exit-by-risk`. The wrappers already add it for you. + +- **Command not found**: Ensure the package is installed and/or PATH updated + when using wrappers. + +--- + +## 13. FAQ + +**Q:** Can I feed arbitrary JSON? +**A:** Provide either the aggregated `by_severity` or a list with `severity`/`predicted_risk` keys. + +**Q:** Why duplicate lower & upper keys in `by_severity`? +**A:** Convenience for consumers with strict schemas. + +--- + +## 14. Security & Privacy + +- No credentials required. Do **not** upload sensitive JSON to public PRs. +- CodeQL runs in CI; keep dependencies updated. + +--- + +## 15. Contributing + +- Follow **Conventional Commits**. +- Keep **ruff/black/pytest/mypy** green before requesting review. +- Prefer small PRs with auto‑merge enabled after checks. + +--- + +## 16. Versioning & Releases + +- Tags `vMAJOR.MINOR.PATCH`. Release notes are drafted automatically. +- Use GitHub Releases to fetch artifacts and changelog. + +--- + +## 17. Support + +- Open Issues or Discussions on GitHub. +- For commercial support, contact the repository owner. + +--- + +## 18. License + +Released under the **MIT License**. See [LICENSE](../LICENSE). + +--- + +> **Tip:** The README “Manual” badge links to this page. From 185981c48304ed539195959997a25487755b49ec Mon Sep 17 00:00:00 2001 From: CoderDeltaLan Date: Sat, 13 Sep 2025 15:16:59 +0100 Subject: [PATCH 2/3] ci: stabilize build (poetry, lint, tests, mypy, smoke) --- .github/workflows/build.yml | 66 +++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 .github/workflows/build.yml diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml new file mode 100644 index 0000000..04b7f63 --- /dev/null +++ b/.github/workflows/build.yml @@ -0,0 +1,66 @@ +name: CI / build + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + workflow_dispatch: + +permissions: + contents: read + +jobs: + build: + name: build (${{ matrix.python-version }}) + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + python-version: [ "3.11", "3.12" ] + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Python + uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python-version }} + + - name: Upgrade pip + run: python -m pip install --upgrade pip + + - name: Install Poetry + run: pip install poetry + + - name: Install dependencies + run: poetry install --no-interaction + + - name: Ruff + run: poetry run ruff check . + + - name: Black (check) + run: poetry run black --check . + + - name: Pytest + env: + PYTHONPATH: src + run: poetry run pytest -q + + - name: Mypy + run: poetry run mypy src + + - name: Package & smoke-test CLI + run: | + poetry build + poetry run python -m pip install . + mkdir -p _intel + diff-risk examples/sample_apv.json -f md -o _intel/report.md + + - name: Upload sample report + if: always() + uses: actions/upload-artifact@v4 + with: + name: sample-report + path: _intel/report.md From d03f063ff74f9527ed8e001419dd34b0537c1139 Mon Sep 17 00:00:00 2001 From: CoderDeltaLan Date: Sat, 13 Sep 2025 15:19:22 +0100 Subject: [PATCH 3/3] docs(manual): complete professional user guide --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index bb2942a..2c09975 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,14 @@ # ⭐ diff-risk-dashboard — APV → Risk Summary (Python CLI) - -[![Manual](https://img.shields.io/badge/Manual-User%20Guide-blue?style=for-the-badge)](docs/MANUAL.md) 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.
+[![Manual](https://img.shields.io/badge/Manual-User%20Guide-blue?style=for-the-badge)](docs/MANUAL.md) + +
+ [![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) @@ -17,7 +19,6 @@ Designed for **always-green CI**, with strict checks and exit codes per risk lev
--- - ## Repo layout ```text