'
f'{html.escape(path)}'
f'@{h["old_start"]}{html.escape(" → ")}@{h["new_start"]}'
f'{html.escape(h.get("header_context") or "")}'
f'
'
)
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'
'
f'{old}'
f'{new}'
f'{mark}'
f'{html.escape(ln["text"])}'
f'
'
)
return (
f'
'
f'{head}
{"".join(body_lines)}
'
)
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'jump to diff →'
if anchor_target else ""
)
body = html.escape(ann["body"])
# Re-inflate inline `code` for readability
body = body.replace("`", "", 1)
while "" in body and body.count("") > body.count(""):
body = body.replace("`", "", 1)
return (
f'
'
f'
'
f'{_render_severity_badge(ann["severity"], palette, danger)}'
f'{target_link}'
f'
'
f'
{body}
'
f'
'
)
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'
'
f'{_render_severity_badge(ann["severity"], palette, danger)}'
f'{preview}'
f'{html.escape(target_label)}'
f'
'
)
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 = (
''
)
# Approval bar (LGTM markers)
approvals = annotations.get("approvals", [])
approval_html = ""
if approvals and not annlist:
approval_html = (
'
'
'LGTM — no findings flagged'
'
'
)
# 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(
'
'
f'{hunk_html}'
f'
{ann_html}
'
'
'
)
if unanchored:
sections_html.append('
General comments
')
sections_html.append('
')
for i, ann in unanchored:
sections_html.append(
_render_annotation(i, ann, palette, danger, anchor_for_block)
)
sections_html.append('
')
# Footer with mandatory reviewer name
footer_html = (
''
)
return f"""
{html.escape(pr_title)}
{html.escape(pr_title)}
{jump_nav_html}
{approval_html}
{"".join(sections_html)}
{footer_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:]))