Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "claudius",
"version": "4.2.0",
"version": "4.3.0",
"description": "Collection of specialized development agents and skills for Claude Code",
"author": {
"name": "lklimek",
Expand Down
13 changes: 13 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,19 @@ Format follows [Keep a Changelog](https://keepachangelog.com/). This project use

## [Unreleased]

## [4.3.0] - 2026-05-29

### Added

- Schema 3.1.0 (additive over 3.0.0; both validate): `metadata.report_type: pr_audit`, optional finding `author_type` (`bot`/`human`), optional `finding_section.verdict` (`PASS`/`FAIL`/`NEEDS_REVIEW`).
- Shared `scripts/severity_util.py` — single source of truth for the OWASP severity band table, per-finding severity derivation, and the summary-statistics / category-matrix builder, imported by both the coordinator (`consolidate_reports.py`) and the renderer (`generate_review_report.py`).

### Fixed

- check-pr-comments findings rendered INFO with zero severity counts — the renderer now derives per-finding severity from `risk`/`impact`/`scope` and recomputes summary statistics on-the-fly when absent or all-zero, so standalone producer reports show real severities and counts across Markdown / HTML / triage / PDF. A non-zero supplied `severity_counts` is never overwritten. The recompute also realigns `total_findings` so the HTML KPI can't disagree with the rebuilt counts.
- `consolidate_reports.ACCEPTED_SCHEMA_VERSIONS` is now derived from the schema's `schema_version` enum (single read) instead of a hard-coded set, so it can't drift on the next schema bump.
- Permalink commit now derives from `git rev-parse @{u}` (falling back to local `HEAD` only when the branch has no upstream) in `check-pr-comments`, `report-format`, and `grumpy-review`, so generated permalinks resolve on GitHub instead of 404-ing on an unpushed HEAD.

## [4.2.0] - 2026-05-28

### Added
Expand Down
18 changes: 14 additions & 4 deletions schemas/review-report.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
"properties": {
"schema_version": {
"type": "string",
"enum": ["3.0.0"],
"enum": ["3.0.0", "3.1.0"],
"description": "Schema version (SemVer). Renderers check this for compatibility."
},
"metadata": {
Expand Down Expand Up @@ -43,7 +43,7 @@
},
"report_type": {
"type": "string",
"enum": ["code_review", "comment_check"],
"enum": ["code_review", "comment_check", "pr_audit"],
"description": "Type of report. Defaults to code_review if omitted."
},
"pr_number": {
Expand Down Expand Up @@ -212,7 +212,7 @@
"type": "integer",
"minimum": 1,
"maximum": 5,
"description": "Numeric severity: 5=CRITICAL, 4=HIGH, 3=MEDIUM, 2=LOW, 1=INFO. Coordinator-derived from overall_severity via the OWASP band table."
"description": "Numeric severity: 5=CRITICAL, 4=HIGH, 3=MEDIUM, 2=LOW, 1=INFO. Coordinator-derived from overall_severity via the OWASP band table. Optional on producer/standalone reports; renderers derive it on-the-fly from risk/impact/scope when absent."
},
"severity_float": {
"type": "number",
Expand All @@ -235,6 +235,11 @@
"impact": { "$ref": "#/$defs/severity_float", "description": "OWASP Impact normalized to [0,1]." },
"scope": { "$ref": "#/$defs/severity_float", "description": "PR relevance: 1.0 in-diff, 0.5 indirectly affected, 0.0 pre-existing/unrelated." },
"overall_severity": { "$ref": "#/$defs/severity_float", "description": "Coordinator-computed mean of risk, impact, scope." },
"author_type": {
"type": "string",
"enum": ["bot", "human"],
"description": "Comment author classification (check-pr-comments)."
},
"title": { "type": "string", "minLength": 1 },
"tags": {
"type": "array",
Expand Down Expand Up @@ -299,7 +304,12 @@
"type": "array",
"items": { "$ref": "#/$defs/finding" }
},
"positives": { "type": "string", "description": "Positive observations for this section" }
"positives": { "type": "string", "description": "Positive observations for this section" },
"verdict": {
"type": "string",
"enum": ["PASS", "FAIL", "NEEDS_REVIEW"],
"description": "Section-level audit verdict (review-pr Pass C)."
}
}
},
"triage_decision": {
Expand Down
72 changes: 28 additions & 44 deletions scripts/consolidate_reports.py
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,13 @@
from typing import Any
from urllib.parse import quote as _url_quote

from severity_util import (
SEV_LABELS,
SEV_ORDER,
derive_overall,
derive_severity_int,
)

try:
import jsonschema

Expand All @@ -56,15 +63,6 @@
Path(__file__).resolve().parent.parent / "schemas" / "review-report.schema.json"
)

SEV_LABELS: dict[int, str] = {
5: "CRITICAL",
4: "HIGH",
3: "MEDIUM",
2: "LOW",
1: "INFO",
}
SEV_ORDER: list[str] = list(SEV_LABELS.values()) # CRITICAL, HIGH, ... INFO

CATEGORY_PREFIX: dict[str, str] = {
"security": "SEC-",
"project": "PROJ-",
Expand Down Expand Up @@ -119,21 +117,26 @@ def _strip_none_values(d: dict[str, Any]) -> dict[str, Any]:
return {k: v for k, v in d.items() if v is not None and v != ""}


def _read_schema_version() -> str:
"""Read schema_version from the schema file, falling back to a default."""
def _read_schema_versions() -> list[str]:
"""Read the schema_version enum (oldest..newest) from the schema file."""
try:
schema = json.loads(SCHEMA_PATH.read_text(encoding="utf-8"))
versions = (
schema.get("properties", {}).get("schema_version", {}).get("enum", [])
)
if versions:
return versions[-1]
return list(versions)
except (FileNotFoundError, json.JSONDecodeError, KeyError):
pass
return "3.0.0"
return ["3.0.0"]


_SCHEMA_VERSIONS = _read_schema_versions()
SCHEMA_VERSION = _SCHEMA_VERSIONS[-1]

SCHEMA_VERSION = _read_schema_version()
# Every enum entry validates (additive 3.0 -> 3.1), derived from the schema so
# the accepted set never drifts from the source on the next version bump.
ACCEPTED_SCHEMA_VERSIONS = set(_SCHEMA_VERSIONS)


# ---------------------------------------------------------------------------
Expand Down Expand Up @@ -243,34 +246,11 @@ def _build_permalink(


# ---------------------------------------------------------------------------
# OWASP severity derivation
# OWASP severity derivation (shared with the renderer via severity_util)
# ---------------------------------------------------------------------------
def _derive_overall(finding: dict[str, Any]) -> float | None:
"""Arithmetic mean of risk + impact + scope when all three are numeric floats."""
dims = []
for key in ("risk", "impact", "scope"):
value = finding.get(key)
if not isinstance(value, (int, float)) or isinstance(value, bool):
return None
dims.append(float(value))
return sum(dims) / 3.0


# Band table mirrors the plan §Standard adopted.
_SEVERITY_BANDS: list[tuple[float, int]] = [
(0.9, 5),
(0.7, 4),
(0.4, 3),
(0.1, 2),
]


def _derive_severity_int(overall: float) -> int:
"""Map an overall_severity float to the 1..5 integer severity band."""
for threshold, level in _SEVERITY_BANDS:
if overall >= threshold:
return level
return 1
# Re-exported under the legacy private names the test-suite imports.
_derive_overall = derive_overall
_derive_severity_int = derive_severity_int


# ---------------------------------------------------------------------------
Expand Down Expand Up @@ -720,15 +700,19 @@ def cmd_prepare(args: argparse.Namespace) -> int:
# hard cutover: v1/v2 must be rejected with a pointer at the schema.
if isinstance(data, dict):
declared = data.get("schema_version")
if isinstance(declared, str) and declared and declared != SCHEMA_VERSION:
if (
isinstance(declared, str)
and declared
and declared not in ACCEPTED_SCHEMA_VERSIONS
):
log.error(
"Input %s declares schema_version=%r; only %r is accepted. "
"Input %s declares schema_version=%r; only %s are accepted. "
"v1/v2 reports are no longer supported — re-run the "
"producer against the current commit to regenerate. See "
"schemas/review-report.schema.json v%s.",
path_str,
declared,
SCHEMA_VERSION,
sorted(ACCEPTED_SCHEMA_VERSIONS),
SCHEMA_VERSION,
)
return 2
Expand Down
82 changes: 82 additions & 0 deletions scripts/generate_review_report.py
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,8 @@
from typing import Any
from xml.sax.saxutils import escape as xml_escape

from severity_util import build_severity_stats, derive_overall, derive_severity_int

logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
log = logging.getLogger(__name__)

Expand Down Expand Up @@ -120,6 +122,82 @@ def sev_label(value: int | str | None) -> str:
return "INFO"


# ===================================================================
# On-the-fly severity normalization
# ===================================================================
# Producer-shape reports (e.g. check-pr-comments) emit risk/impact/scope floats
# but never the coordinator-derived integer ``severity`` nor real
# ``severity_counts``. Without these, findings render INFO and the summary
# table / charts read all-zero. These helpers derive the missing values from
# the floats at render time so a standalone producer report displays correctly.


def _normalize_finding_severities(data: dict[str, Any]) -> None:
"""Fill a finding's overall_severity + integer severity from floats in-place.

Producer-shape findings carry risk/impact/scope but often lack a valid
integer ``severity`` and/or ``overall_severity``. Derive both from the
floats (overall = mean; severity = band of overall) so the Markdown overall
suffix and HTML ``data-overall`` sort key are populated. Findings already
carrying valid values are left untouched.
"""
for section in data.get("findings", []):
for f in section.get("findings", []):
sev = f.get("severity")
has_sev = (
isinstance(sev, int) and not isinstance(sev, bool) and 1 <= sev <= 5
)
overall = f.get("overall_severity")
has_overall = isinstance(overall, (int, float)) and not isinstance(
overall, bool
)
if has_sev and has_overall:
continue
derived_overall = derive_overall(f)
if derived_overall is None:
continue
if not has_overall:
f["overall_severity"] = derived_overall
if not has_sev:
f["severity"] = derive_severity_int(derived_overall)


def _counts_all_zero(counts: dict[str, Any] | None) -> bool:
"""True when severity_counts is absent, empty, or every band is zero."""
if not counts:
return True
return all(not v for v in counts.values())


def _normalize_summary_statistics(data: dict[str, Any]) -> None:
"""Recompute severity_counts + severity_category_matrix in-place when absent.

Triggers only when ``severity_counts`` is missing or all-zero and the report
contains at least one finding (a hand-supplied non-zero statistics block is
never overwritten). Note floatless findings are counted as INFO, so the
trigger is finding-existence, not severity-derivability. ``total_findings``
is realigned to the rebuilt count so the HTML KPI never disagrees with it.
"""
Comment thread
lklimek marked this conversation as resolved.
Resolved
stats = data.get("summary_statistics")
if not isinstance(stats, dict):
return
if not _counts_all_zero(stats.get("severity_counts")):
return
sections = data.get("findings", [])
rebuilt = build_severity_stats(sections)
if rebuilt["total_findings"] == 0:
return
stats["severity_counts"] = rebuilt["severity_counts"]
stats["severity_category_matrix"] = rebuilt["severity_category_matrix"]
Comment thread
lklimek marked this conversation as resolved.
Resolved
stats["total_findings"] = rebuilt["total_findings"]


def _normalize_report(data: dict[str, Any]) -> None:
"""Run both severity-normalization passes; safe to call from every renderer."""
_normalize_finding_severities(data)
_normalize_summary_statistics(data)


# ===================================================================
# Validation
# ===================================================================
Expand Down Expand Up @@ -470,6 +548,7 @@ def render_markdown_to_reportlab(s: str) -> list[tuple[str, str]]:
# ===================================================================
def render_markdown(data: dict[str, Any]) -> str:
"""Render the report as a Markdown string."""
_normalize_report(data)
meta = _meta(data)
es = data.get("executive_summary", {})
stats = data.get("summary_statistics", {})
Expand Down Expand Up @@ -1644,6 +1723,7 @@ def _build_html_context(
"""
import copy as _copy

_normalize_report(data)
meta = _meta(data)
stats = data.get("summary_statistics", {})

Expand Down Expand Up @@ -2152,6 +2232,8 @@ def _configure_matplotlib_font(matplotlib: Any) -> None:

def render_pdf(data: dict[str, Any], output_path: Path) -> None:
"""Render the report as a PDF using reportlab and matplotlib."""
_normalize_report(data)

import io

import matplotlib
Expand Down
Loading
Loading