alirezarezvani/claude-skills / markdown-html/skills/md-review
md-review
VerifiedUse when converting a markdown code review with diff blocks and severity callouts into a two-column HTML review. Parses diffs with diff_parser.py and annotations with annotation_extractor.py; requires a named reviewer.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.9 KB |
| assets/md_review_template.html | other | 4.5 KB |
| references/diff_rendering_canon.md | markdown | 5.0 KB |
| references/pr_annotation_ux.md | markdown | 5.4 KB |
| references/severity_coding.md | markdown | 4.9 KB |
| scripts/annotation_extractor.py | script | 7.6 KB |
| scripts/diff_parser.py | script | 9.9 KB |
| scripts/review_html_renderer.py | script | 21.7 KB |
scripts/review_html_renderer.py
View on GitHub#!/usr/bin/env python3
"""review_html_renderer.py - Render parsed diffs + annotations into a 2-column HTML review.
Stdlib-only. Combines:
- diff_parser.py output (hunks per file)
- annotation_extractor.py output (severity-tagged margin notes)
- design-system config (12-token palette + typography + design_style)
into a single-file HTML page with:
* Top jump-nav: every annotation listed with severity badge + file:line + 1-line preview
(Click jumps to the annotation in the right margin and highlights the hunk)
* 2-column layout: diff on left, annotation cards on right
(Falls back to stacked layout on viewports < 900px)
* Per-line diff coloring: additions in success-tinted bg, deletions in warn-tinted bg
* Severity badges: icon + color + aria-label (WCAG 1.4.1 — color is NOT the sole signal)
* Mandatory "Reviewer:" footer (refuses to render without --reviewer)
NO LLM CALLS. Pure templating + config-driven CSS.
Single-file output: all CSS + (optional) JS inline. Only external is Google
Fonts CSS for typography (same discipline as md-document; no Prism here —
we render diff coloring ourselves with stable conventions).
Usage:
python review_html_renderer.py \\
--diff-blocks hunks.json \\
--annotations annotations.json \\
--reviewer "Jane Doe" \\
--output review.html
python review_html_renderer.py --sample --reviewer "Sample Reviewer" --output /tmp/review.html
"""
from __future__ import annotations
import argparse
import html
import json
import os
import sys
from pathlib import Path
from typing import Any
_DESIGN_SYSTEM_SCRIPTS = (
Path(__file__).resolve().parent.parent.parent / "design-system" / "scripts"
)
sys.path.insert(0, str(_DESIGN_SYSTEM_SCRIPTS))
try:
import config_loader as _cfg
import brand_palette_validator as _bpv
except ImportError:
_cfg = None
_bpv = None
# ----- Severity → visual mapping (color + icon + aria-label) -------------------
# Color is NOT the sole signal (WCAG 1.4.1). Every badge has an icon and an
# aria-label that's announced by screen readers.
SEVERITY_DEFAULTS = {
# severity_name: {token_key_in_palette, icon_text, aria_phrase}
"BLOCKER": {"token": "_danger", "icon": "■", "aria": "Blocker — must fix before merge"},
"MAJOR": {"token": "--md-warn", "icon": "▲", "aria": "Major — strongly recommended fix"},
"MINOR": {"token": "--md-link", "icon": "●", "aria": "Minor — worth fixing"},
"NIT": {"token": "--md-text-muted", "icon": "◦", "aria": "Nit — cosmetic preference"},
}
def _derive_danger_color(palette: dict[str, str]) -> str:
"""Compute a 'danger' color by rotating the accent hue toward red.
Falls back to a generic red if the palette is unavailable.
"""
if not palette or _bpv is None:
return "#D04646"
accent_hex = palette.get("--md-accent", "#D04646")
try:
rgb = _bpv.parse_hex(accent_hex)
# Rotate hue toward red (0°) — pick the shorter rotation that lands near red
target = _bpv.shift_hue(rgb, -120) # rotate 120° toward red
return _bpv.rgb_to_hex(target)
except Exception:
return "#D04646"
def _resolve_severity_color(severity: str, palette: dict[str, str], danger: str) -> str:
sev = severity.upper()
spec = SEVERITY_DEFAULTS.get(sev, {"token": "--md-text-muted"})
token = spec["token"]
if token == "_danger":
return danger
return palette.get(token, "#888888")
def _palette_to_css(palette: dict[str, str]) -> str:
if not palette:
palette = {
"--md-bg": "#0E1E38", "--md-surface": "#142B50", "--md-border": "#1A3868",
"--md-text": "#F7F7F2", "--md-text-muted": "rgba(247, 247, 242, 0.68)",
"--md-accent": "#00D4AA", "--md-accent-soft": "rgba(0, 212, 170, 0.14)",
"--md-code-bg": "#122648",
"--md-link": "#00D4AA", "--md-link-hover": "#08FECE",
"--md-success": "#10A85C", "--md-warn": "#C87C10",
}
return "\n".join(f" {k}: {v};" for k, v in palette.items())
def _font_url(heading: str, body: str) -> str:
families = sorted({heading, body})
parts = "&".join(f"family={f.replace(' ', '+')}:wght@400;600" for f in families)
return f"https://fonts.googleapis.com/css2?{parts}&display=swap"
def _font_stack(name: str) -> str:
fallback = ("Georgia, serif" if name in
("Playfair Display", "Merriweather", "Lora", "Source Serif 4")
else "system-ui, -apple-system, sans-serif")
return f"'{name}', {fallback}"
BASE_CSS = """
:root {
__PALETTE__
--md-danger: __DANGER__;
--md-font-heading: __HEADING_FONT__;
--md-font-body: __BODY_FONT__;
--md-font-mono: 'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, monospace;
}
* { box-sizing: border-box; }
html { scroll-behavior: smooth; }
body {
margin: 0;
padding: 2rem 1.5rem;
background: var(--md-bg);
color: var(--md-text);
font-family: var(--md-font-body);
font-size: 16px;
line-height: 1.55;
max-width: 1400px;
margin-left: auto;
margin-right: auto;
}
h1, h2, h3 { font-family: var(--md-font-heading); color: var(--md-text); margin: 0 0 0.5em; line-height: 1.25; }
h1 { font-size: 1.75rem; }
h2 { font-size: 1.25rem; margin-top: 2rem; padding-bottom: 0.3em; border-bottom: 1px solid var(--md-border); }
a { color: var(--md-link); }
/* Severity badges (color + icon + aria-label — WCAG 1.4.1) */
.sev-badge {
display: inline-flex;
align-items: center;
gap: 0.35em;
font-family: var(--md-font-heading);
font-weight: 600;
font-size: 0.75rem;
letter-spacing: 0.05em;
padding: 0.15em 0.55em;
border-radius: 999px;
border: 1px solid currentColor;
background: var(--md-bg);
}
.sev-icon { font-family: var(--md-font-mono); font-size: 0.875em; }
/* Top jump-nav */
nav.jump-nav {
background: var(--md-surface);
border: 1px solid var(--md-border);
border-radius: 10px;
padding: 1rem 1.25rem;
margin: 1.5rem 0 2rem;
}
nav.jump-nav h2 { margin-top: 0; font-size: 1rem; border: none; padding: 0; }
nav.jump-nav ul { list-style: none; padding: 0; margin: 0.75rem 0 0; display: grid; gap: 0.4rem; }
nav.jump-nav li { display: flex; align-items: center; gap: 0.75rem; flex-wrap: wrap; }
nav.jump-nav a {
color: var(--md-text);
text-decoration: none;
flex: 1;
border-radius: 4px;
padding: 0.2em 0.4em;
}
nav.jump-nav a:hover { background: var(--md-accent-soft); color: var(--md-accent); }
nav.jump-nav .nav-target {
color: var(--md-text-muted);
font-family: var(--md-font-mono);
font-size: 0.875rem;
}
nav.jump-nav .nav-preview { color: var(--md-text-muted); font-size: 0.875rem; }
/* 2-column hunk layout */
.hunk-row {
display: grid;
grid-template-columns: minmax(0, 1fr) 320px;
gap: 1.25rem;
margin: 1.5rem 0 2rem;
scroll-margin-top: 1rem;
}
@media (max-width: 900px) {
.hunk-row { grid-template-columns: 1fr; }
.hunk-annotations { order: 2; }
}
.hunk {
background: var(--md-code-bg);
border: 1px solid var(--md-border);
border-radius: 8px;
overflow: hidden;
}
.hunk-head {
background: var(--md-surface);
border-bottom: 1px solid var(--md-border);
padding: 0.5rem 0.85rem;
font-family: var(--md-font-mono);
font-size: 0.8125rem;
color: var(--md-text-muted);
display: flex;
flex-wrap: wrap;
gap: 0.75rem;
}
.hunk-head strong { color: var(--md-text); font-weight: 600; }
.hunk pre {
margin: 0;
padding: 0;
background: transparent;
font-family: var(--md-font-mono);
font-size: 0.8125rem;
line-height: 1.55;
overflow-x: auto;
}
.hunk .line {
display: grid;
grid-template-columns: 3.5em 3.5em 1.25em 1fr;
padding-right: 0.75rem;
}
.hunk .ln, .hunk .lo {
color: var(--md-text-muted);
padding: 0 0.5em;
text-align: right;
user-select: none;
border-right: 1px solid var(--md-border);
font-size: 0.75rem;
}
.hunk .mark { text-align: center; user-select: none; color: var(--md-text-muted); }
.hunk .src { padding-left: 0.5em; white-space: pre; overflow-wrap: normal; }
.hunk .line.addition { background: color-mix(in srgb, var(--md-success) 15%, transparent); }
.hunk .line.addition .mark { color: var(--md-success); }
.hunk .line.deletion { background: color-mix(in srgb, var(--md-warn) 12%, transparent); }
.hunk .line.deletion .mark { color: var(--md-warn); }
.hunk .line.meta { color: var(--md-text-muted); font-style: italic; padding-left: 1em; }
/* Annotation cards on the right */
.hunk-annotations { display: grid; gap: 0.75rem; align-content: start; }
.annotation {
background: var(--md-surface);
border: 1px solid var(--md-border);
border-left-width: 4px;
border-radius: 8px;
padding: 0.75rem 0.85rem;
}
.annotation .annotation-head {
display: flex;
justify-content: space-between;
align-items: center;
gap: 0.5rem;
margin-bottom: 0.4rem;
}
.annotation .annotation-body { font-size: 0.9375rem; line-height: 1.5; color: var(--md-text); }
.annotation .annotation-body code {
font-family: var(--md-font-mono);
background: var(--md-code-bg);
padding: 0.1em 0.3em;
border-radius: 4px;
font-size: 0.875em;
}
.annotation.unanchored { border-left-color: var(--md-text-muted); }
/* Reviewer footer */
footer.review-footer {
margin-top: 3rem;
padding-top: 1.5rem;
border-top: 1px solid var(--md-border);
color: var(--md-text-muted);
font-size: 0.9375rem;
display: flex;
align-items: center;
gap: 1rem;
flex-wrap: wrap;
}
footer.review-footer strong { color: var(--md-text); }
/* Approval bar (LGTM markers) */
.approval-bar {
background: color-mix(in srgb, var(--md-success) 12%, transparent);
border: 1px solid var(--md-success);
color: var(--md-success);
padding: 0.5rem 0.85rem;
border-radius: 8px;
margin: 1rem 0;
font-weight: 600;
font-family: var(--md-font-heading);
}
@media (prefers-reduced-motion: reduce) {
* { animation: none !important; transition: none !important; }
html { scroll-behavior: auto; }
}
"""
def _hunk_anchor(block_idx: int, file_idx: int, hunk_idx: int) -> str:
return f"hunk-b{block_idx}-f{file_idx}-h{hunk_idx}"
def _annotation_anchor(idx: int) -> str:
return f"ann-{idx}"
def _render_severity_badge(severity: str, palette: dict[str, str], danger: str) -> str:
spec = SEVERITY_DEFAULTS.get(severity.upper(), {"icon": "?", "aria": severity})
color = _resolve_severity_color(severity, palette, danger)
icon = html.escape(spec["icon"])
aria = html.escape(spec["aria"])
return (
f'<span class="sev-badge" style="color: {color}" '
f'role="status" aria-label="{aria}">'
f'<span class="sev-icon" aria-hidden="true">{icon}</span>'
f'{html.escape(severity.upper())}'
f'</span>'
)
def _render_hunk(file_idx: int, file_entry: dict[str, Any],
block_idx: int, hunk_idx: int) -> str:
h = file_entry["hunks"][hunk_idx]
path = file_entry.get("path_new") or file_entry.get("path_old") or "(unknown)"
anchor = _hunk_anchor(block_idx, file_idx, hunk_idx)
head = (
f'<div class="hunk-head">'
f'<strong>{html.escape(path)}</strong>'
f'<span>@{h["old_start"]}{html.escape(" → ")}@{h["new_start"]}</span>'
f'<span>{html.escape(h.get("header_context") or "")}</span>'
f'</div>'
)
body_lines = []
for ln in h["lines"]:
kind = ln["kind"]
mark = {"addition": "+", "deletion": "−", "context": " ", "meta": "\\"}.get(kind, " ")
old = "" if ln.get("old") is None else str(ln["old"])
new = "" if ln.get("new") is None else str(ln["new"])
body_lines.append(
f'<div class="line {kind}">'
f'<span class="lo">{old}</span>'
f'<span class="ln">{new}</span>'
f'<span class="mark" aria-hidden="true">{mark}</span>'
f'<span class="src">{html.escape(ln["text"])}</span>'
f'</div>'
)
return (
f'<div class="hunk" id="{anchor}">'
f'{head}<pre>{"".join(body_lines)}</pre></div>'
)
def _render_annotation(idx: int, ann: dict[str, Any],
palette: dict[str, str], danger: str,
anchor_for_block: dict[int, str]) -> str:
color = _resolve_severity_color(ann["severity"], palette, danger)
anchor_target = anchor_for_block.get(ann.get("attached_block"))
target_link = (
f'<a href="#{anchor_target}" '
f'style="color: var(--md-text-muted); font-size: 0.75rem; '
f'text-decoration: none">jump to diff →</a>'
if anchor_target else ""
)
body = html.escape(ann["body"])
# Re-inflate inline `code` for readability
body = body.replace("`", "<code>", 1)
while "<code>" in body and body.count("<code>") > body.count("</code>"):
body = body.replace("`", "</code>", 1)
return (
f'<div class="annotation{" unanchored" if anchor_target is None else ""}" '
f'id="{_annotation_anchor(idx)}" style="border-left-color: {color}">'
f'<div class="annotation-head">'
f'{_render_severity_badge(ann["severity"], palette, danger)}'
f'{target_link}'
f'</div>'
f'<div class="annotation-body">{body}</div>'
f'</div>'
)
def render(
diff_blocks: dict[str, Any],
annotations: dict[str, Any],
config: dict[str, Any],
reviewer: str,
pr_title: str = "Code Review",
) -> str:
palette = config.get("derived_palette") or {}
typo = config.get("typography") or {}
heading_font = typo.get("heading_font", "Inter")
body_font = typo.get("body_font", "Inter")
style = config.get("design_style", "technical")
company_name = config.get("company_name", "")
danger = _derive_danger_color(palette)
css = (BASE_CSS
.replace("__PALETTE__", _palette_to_css(palette))
.replace("__DANGER__", danger)
.replace("__HEADING_FONT__", _font_stack(heading_font))
.replace("__BODY_FONT__", _font_stack(body_font)))
# Build anchor map for jump-nav targets
anchor_for_block: dict[int, str] = {}
for block in diff_blocks.get("blocks", []):
block_idx = block["block_index"]
for file_idx, file_entry in enumerate(block["files"]):
if file_entry["hunks"]:
# Anchor the first hunk of the first file in each block
anchor_for_block.setdefault(
block_idx, _hunk_anchor(block_idx, file_idx, 0)
)
# Top jump-nav (ordered by source position, which is annotation order)
annlist = annotations.get("annotations", [])
nav_items_html: list[str] = []
for i, ann in enumerate(annlist):
target_anchor = _annotation_anchor(i)
target_diff = anchor_for_block.get(ann.get("attached_block")) or target_anchor
preview = html.escape(ann["body"][:80] + ("…" if len(ann["body"]) > 80 else ""))
target_label = (
f'#{ann.get("attached_block") + 1}' if ann.get("attached_block") is not None
else "(unanchored)"
)
nav_items_html.append(
f'<li>'
f'{_render_severity_badge(ann["severity"], palette, danger)}'
f'<a href="#{target_anchor}">{preview}</a>'
f'<span class="nav-target">{html.escape(target_label)}</span>'
f'</li>'
)
jump_nav_html = ""
if annlist:
counts = annotations.get("summary", {}).get("counts_by_severity", {})
count_summary = " · ".join(
f"{n} {sev}" for sev, n in sorted(counts.items())
)
jump_nav_html = (
'<nav class="jump-nav" aria-label="Review annotations">'
f'<h2>Findings ({count_summary})</h2>'
f'<ul>{"".join(nav_items_html)}</ul>'
'</nav>'
)
# Approval bar (LGTM markers)
approvals = annotations.get("approvals", [])
approval_html = ""
if approvals and not annlist:
approval_html = (
'<div class="approval-bar" role="status">'
'LGTM — no findings flagged'
'</div>'
)
# Render hunks + their attached annotations
block_to_annotations: dict[int, list[tuple[int, dict[str, Any]]]] = {}
unanchored: list[tuple[int, dict[str, Any]]] = []
for i, ann in enumerate(annlist):
if ann.get("attached_block") is not None:
block_to_annotations.setdefault(ann["attached_block"], []).append((i, ann))
else:
unanchored.append((i, ann))
sections_html: list[str] = []
for block in diff_blocks.get("blocks", []):
block_idx = block["block_index"]
anns_for_block = block_to_annotations.get(block_idx, [])
for file_idx, file_entry in enumerate(block["files"]):
for hunk_idx in range(len(file_entry["hunks"])):
hunk_html = _render_hunk(file_idx, file_entry, block_idx, hunk_idx)
# All annotations for this block render alongside the first hunk
ann_html = ""
if file_idx == 0 and hunk_idx == 0 and anns_for_block:
ann_html = "".join(
_render_annotation(i, ann, palette, danger, anchor_for_block)
for i, ann in anns_for_block
)
sections_html.append(
'<div class="hunk-row">'
f'{hunk_html}'
f'<div class="hunk-annotations">{ann_html}</div>'
'</div>'
)
if unanchored:
sections_html.append('<h2>General comments</h2>')
sections_html.append('<div class="hunk-annotations">')
for i, ann in unanchored:
sections_html.append(
_render_annotation(i, ann, palette, danger, anchor_for_block)
)
sections_html.append('</div>')
# Footer with mandatory reviewer name
footer_html = (
'<footer class="review-footer">'
f'<span>Reviewer: <strong>{html.escape(reviewer)}</strong></span>'
+ (f'<span>· {html.escape(company_name)}</span>' if company_name else "")
+ '<span style="margin-left:auto">Generated by markdown-html / md-review</span>'
'</footer>'
)
return f"""<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>{html.escape(pr_title)}</title>
<link rel="preconnect" href="https://fonts.googleapis.com" crossorigin>
<link rel="stylesheet" href="{_font_url(heading_font, body_font)}">
<style>{css}</style>
</head>
<body class="style-{style}">
<header><h1>{html.escape(pr_title)}</h1></header>
{jump_nav_html}
{approval_html}
{"".join(sections_html)}
{footer_html}
</body>
</html>"""
def main(argv: list[str]) -> int:
p = argparse.ArgumentParser(description=__doc__.split("\n")[0])
p.add_argument("--diff-blocks", help="Path to diff_parser JSON output")
p.add_argument("--annotations", help="Path to annotation_extractor JSON output")
p.add_argument("--reviewer", help="Reviewer name (required; refuses to render without)")
p.add_argument("--title", default="Code Review", help="PR / review title")
p.add_argument("--output", help="Path to write HTML (else stdout)")
p.add_argument("--no-config", action="store_true",
help="Bypass design-system config (use DEFAULTS)")
p.add_argument("--sample", action="store_true",
help="Render the built-in sample PR review")
p.add_argument("--severity-convention",
default="BLOCKER,MAJOR,MINOR,NIT",
help="Comma-separated severity tier list (most → least)")
args = p.parse_args(argv)
if args.sample:
sys.path.insert(0, str(Path(__file__).resolve().parent))
import annotation_extractor
import diff_parser
text = diff_parser.SAMPLE_MARKDOWN
diff_blocks = diff_parser.parse_markdown_for_diffs(text)
sev_conv = [s.strip().upper() for s in args.severity_convention.split(",")]
annotations = annotation_extractor.extract_annotations(text, diff_blocks, sev_conv)
reviewer = args.reviewer or "Sample Reviewer"
pr_title = args.title
else:
if not (args.diff_blocks and args.annotations):
print("error: --diff-blocks and --annotations are required "
"(use --sample for a built-in demo)", file=sys.stderr)
return 2
diff_blocks = json.loads(Path(args.diff_blocks).read_text(encoding="utf-8"))
annotations = json.loads(Path(args.annotations).read_text(encoding="utf-8"))
reviewer = args.reviewer
pr_title = args.title
# Hard rule 1: reviewer name is mandatory (named owner per research-ops discipline)
if not reviewer or not reviewer.strip():
print("refusing: --reviewer is required. A code review must name a human reviewer.",
file=sys.stderr)
return 3
# Hard rule 2: refuse if there are no hunks (wrong skill — route to md-document)
if diff_blocks.get("summary", {}).get("total_hunks", 0) == 0:
print("refusing: no diff hunks present in input. This is not a code review — "
"route to md-document instead.", file=sys.stderr)
return 4
if args.no_config or os.environ.get("MARKDOWN_HTML_NO_CONFIG") == "1":
config = _cfg.DEFAULTS if _cfg else {}
else:
config = _cfg.load_config() if _cfg else {}
output = render(diff_blocks, annotations, config, reviewer, pr_title)
if args.output and args.output != "-":
Path(args.output).write_text(output, encoding="utf-8")
print(f"wrote {args.output}: {len(output):,} bytes "
f"({diff_blocks['summary']['total_hunks']} hunks, "
f"{annotations['summary']['total_annotations']} annotations, "
f"reviewer={reviewer})")
else:
print(output)
return 0
if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |