dreampiler/kandev
1
0
Fork 0
Code Issues 43 Pull Requests Actions 6 Packages Projects Releases Wiki Activity

feat: add PR walkthrough generation workflow (#2933)

Browse Source
This commit is contained in:
Carlos Florêncio
2026-08-22 21:46:57 +01:00
committed by GitHub
parent 906be89036
commit eb0df0a492
31 changed files with 4852 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/pr-walkthrough/SKILL.md
+245
View File
@@ -0,0 +1,245 @@
---
name: pr-walkthrough
description: Generate a single-file HTML walkthrough for a pull request. Use when the user wants a visual, scrollable page that explains a PR's problem, approach, architecture, key code changes, data flow, and trade-offs for reviewers. Trigger on "walkthrough for this PR", "explain this PR visually", "generate a PR walkthrough", or a PR URL with a request to explain it. Not for code review: do not load this skill to critique a PR, post review findings, or approve or request changes. Use a code-review skill for that.
---
# PR Walkthrough
Generate one HTML file that orients a reviewer to a pull request. The page is a vertical, center-contained "story": the reviewer scrolls from the problem, through the architecture and the key code changes, to the data model and the trade-offs.
This skill is **not** a code-review skill. Do not produce review findings, approve/request-changes verdicts, or a full critique. Explain the change so a reviewer understands it fast.
The skill is provider-neutral. In Kandev CI, OpenCode runs it in read-only mode
and a trusted workflow renders and publishes the resulting HTML. The skill never
uploads files, changes a pull request, or handles hosting credentials.
## Output
You do not write HTML. You write one JSON data file per PR, then run a renderer that builds the HTML:
- Data file: `<output-dir>/pr-<number>.json`
- HTML page: `<output-dir>/pr-<number>.html`
`<output-dir>` is the directory for walkthrough files. The default is `docs/pr-walkthrough/`. The caller may set a different directory. If the host or a CI job gives you an exact path in your instruction, use that path and do not change it. Otherwise use the default and create it if it is missing. `<skill-dir>` is the directory this skill lives in; use it for the `references/` paths in the commands below.
For example, PR #12407 writes `pr-12407.json`, and the renderer writes `pr-12407.html`. Never write to a shared `index.html`, and never overwrite a walkthrough for a different PR. This keeps earlier walkthroughs on disk so several can be opened and compared at once. If a file for the same PR already exists, ask the user before overwriting it.
The renderer is `references/build.py` (Python standard library only). It reads your JSON and the fixed shell at `references/shell.html`, then writes the HTML page. The shell holds all CSS and JS and stays the same for every PR. **Do not edit `shell.html` or `build.py`.** The renderer owns the parts that are easy to get wrong: it escapes all code, builds both the canvas and the list from one data source, places the canvas nodes, computes the GitHub file links, and fails loudly on a missing field.
The renderer does not judge whether the content is true, clear, or useful. That is your job, and it is the whole job. A page that passes the build but has a vague `tldr`, a wrong `sig`, or a diagram that does not match the code is a failed walkthrough. Spend your effort on the quality of each JSON section, not on the mechanics the renderer already handles. Each section below states the bar it must meet.
See `references/example.json` for a complete, working data file. Copy its shape.
### CI output mode
When a trusted CI caller asks for machine-readable output, return exactly one
block in this form and do not write any explanation before or after it:
```text
<kandev_pr_walkthrough>
{the complete walkthrough JSON object}
</kandev_pr_walkthrough>
```
The caller extracts and validates this block before invoking the renderer. Keep
the JSON object complete and use the PR number supplied by the caller. Do not
include Markdown fences around the block.
The HTML page loads from `file://` with no dev server. Runtime code (Tailwind, Mermaid, Marked, DOMPurify, Shiki) loads from exact-version CDN URLs owned by the fixed shell. Marked output is sanitized with DOMPurify before it goes into the page. The `build.py` step runs only at generation time; it adds no runtime dependency to the page.
## Writing style: Simplified Technical English (ASD-STE100)
All prose in the page (captions, "why" text, trade-offs) must follow ASD-STE100:
- One instruction or idea per sentence. Keep sentences short (procedure ≤ 20 words, description ≤ 25).
- Use the active voice. Use the present tense where possible.
- Use approved, simple words. Prefer one meaning per word (e.g. "use", not "utilize"; "start", not "initiate").
- Do not use synonyms for variety. Repeat the same word for the same thing.
- Avoid slang, idioms, and long noun clusters (max three nouns in a row).
- No emdashes. No emojis. Write plain, natural sentences.
The goal is text that a non-native reviewer reads once and understands.
## Design constraints
- **Vertical, center-contained.** Content sits in a single column, max width ~72rem, centered. The page reads top to bottom.
- **Visual-heavy, low text.** Prefer bullet points, tables, diagrams, and code blocks over paragraphs. Each prose block is a few short sentences at most.
- **Default dark theme**, with a working light-theme toggle in the topbar. Persist the choice in `localStorage`.
- **Sticky topbar** with the PR title, in-page anchor links, and the theme toggle.
- Syntax-highlighted code (Shiki, dual light/dark theme), with optional GitHub-style green/red diff lines. Diagrams with Mermaid.
- **Code blocks link to GitHub.** Each code change links to its file in the PR diff, so the reviewer can jump to the source.
- **Interactive code canvas.** The key code changes also show as a pan and zoom canvas. Each change is a node. Arrows show how the nodes interact. A click on a node opens a right-side detail panel with the full code.
## Workflow
### 1. Establish PR context
Find the repository root, current branch, and comparison base. If a GitHub PR exists, read it and record the URL:
```bash
gh pr view --json baseRefName,headRefName,title,body,url,state,files
```
If there is no PR, infer the base from the remote default:
```bash
git symbolic-ref --short refs/remotes/origin/HEAD
```
**Always compare against the remote-tracking base, not the bare branch name.** A fresh checkout (this is the normal case in CI) has no local `master`, so `git diff master...HEAD` fails with `ambiguous argument 'master...HEAD': unknown revision`. Prefix the base branch from `gh pr view` with `origin/`. So for a PR based on `master`, `<base>` is `origin/master`. Use that `<base>` in every command below. Do not run the diff against the bare name first.
Collect the diff and history:
```bash
git --no-pager diff --stat <base>...HEAD
git --no-pager diff --name-status <base>...HEAD
git --no-pager log --oneline <base>..HEAD
git --no-pager diff <base>...HEAD
```
### 2. Understand the change against the full codebase
Do not build the page from the diff alone. Read the full current version of each important changed file. Follow imports, call sites, types, state owners, and tests. Use the available repository search and read tools when the architecture is not obvious from filenames. The diff shows what changed; the surrounding code explains what it means.
Read each file once and keep it in mind. Do not re-open the same file to copy one more excerpt; scroll back to what you already read. Copy code excerpts straight from the diff and the first read, not from a second `view` of the same file.
Scale the page to the PR size. A small PR gets a short page with 2-3 code changes and one diagram. A large PR gets more sections, but never filler. If two blocks teach the same fact, merge them.
### 3. Plan the sections
The JSON drives these sections. Keep only the ones that add value. The renderer draws a section when its key is present, and skips `architecture` and `data` when you omit them. The keys map to sections like this:
1. **Header / TL;DR** (`pr`) - the PR title, URL, base and head, file and line counts, and a one line `tldr`. The renderer builds the `<h1>`, the badges, and the topbar. The topbar **Review split button** opens the GitHub review pane and copies `gh pr review <number> --repo <repo> --approve`. It never approves on its own; the page holds no credentials. Set `pr.repo` to the `owner/repo` slug (for example `example-org/parcel-service`) so the copied command is correct.
- Quality bar: `tldr` states, in one sentence, what the PR changes and why. A reader who reads only this line knows the point of the PR. Do not restate the title. Do not use vague words such as "improve" or "update" without the concrete change.
2. **Why and what** (`why`) - `why.problem` is one or two sentences. `why.what` is a bullet list of what the change does.
- Quality bar: `why.problem` names the concrete problem the PR fixes, not the solution. `why.what` lists the real changes a reviewer will see in the diff, one per bullet, with no filler and no repeat of `tldr`.
3. **Architecture, end to end** (`architecture`) - one high-level Mermaid `flowchart` in `architecture.mermaid`, with a short `architecture.caption`. Omit the key for a PR that needs no diagram. Choose the flow direction from the first token: use `flowchart LR` (left to right) for a linear pipeline so it fills the full-width container and stays short, and `flowchart TD` (top to bottom) when the flow branches enough that `LR` would grow too wide. The renderer passes the direction through unchanged; it is your choice, not a fixed default.
- Quality bar: the diagram shows the real components and the real flow the PR touches, with names that match the code. It is not a generic box diagram. Omit the section rather than draw a diagram that does not match the change.
4. **Key code changes** (`changes`, `edges`) - the code canvas plus a linear fallback list. See "Changes" below. Use 2-6 changes.
- Quality bar: each change points at a real file and shows real code from the head commit. Each `why` says what the code does, not that it "was added". Each `sig` is the true signature. Each `edge` is a real call or data flow. A reviewer can trust the canvas as a map of the change. Show changed code as a diff so the reviewer sees what moved: use `patch` for a real hunk, or `diff: true` for an excerpt that is entirely new in this PR (it renders green). Use a plain `code` block only for context that the PR does not change.
5. **Data and storage** (`data`) - a Mermaid diagram in `data.mermaid`, or a `data.fields` table of `field`, `type`, and `note`. Keep only what the PR touches. Omit the key when the PR touches no data.
- Quality bar: every field or entity is one the PR adds or changes. Types match the code. Omit the section for a PR that touches no data model.
6. **Risk** (`risk`) - a score from 1 to 10 (10 = highest risk) in `risk.score`, and short bullets in `risk.reasons`. See "Risk score" below.
- Quality bar: the score follows from the reasons, and each reason is a real signal from this PR (blast radius, test coverage, rollback cost, data or contract change). Do not give a default middle score with generic reasons.
7. **Trade-offs and review notes** (`review`) - `review.tradeoffs` is a bullet list. `review.focus` is an ordered "where to look first" list.
- Quality bar: `review.tradeoffs` names real choices the PR makes and what it gives up. `review.focus` orders the files or areas a reviewer should read first, most important first. Do not fill it with "check the tests" boilerplate.
For a section the PR needs but the schema does not cover (for example a state-machine diagram or a config table), tell the user which section you cannot express and ask how to proceed. Do not edit `shell.html` to add it.
#### Changes
The renderer builds two views from one `changes[]` array: the pan and zoom canvas (primary) and a collapsed list (plain-text fallback). You never place a node or keep two views in sync; the renderer does both from each change object.
Each entry in `changes[]` has these fields:
- `title` - a short node title. Required.
- `file` - the file path. Required. The renderer links it to the PR diff (see "GitHub file links").
- `why` - one short sentence on what the change does. Required.
- `id` - a stable node id such as `"n1"`. Optional; the renderer assigns `n1`, `n2`, ... in order when you omit it. Set it when you reference the node in `edges`.
- `sig` - one function or type signature shown on the compact node (for example `func (h *Handler) Get(...)`). Use the primary symbol the change adds or edits. Do not put a statement, an assignment, or two symbols here. Optional.
- `group` - a boundary-box name (see below). Optional.
- `blocks` - one or more code blocks. Required, at least one.
Each block in `blocks[]` has:
- `code` - the code excerpt. Required unless the block sets `patch` or renders Markdown. Write it as plain source; the renderer escapes it. Do not pre-escape `<`, `>`, or `&`.
- `lang` - the Shiki language id (for example `go`, `typescript`, `bash`, `json`, `sql`). Required unless the block renders Markdown.
- `label` - a short label above the block (for example `Handler`, `Get`). Optional.
- `patch` - paste the raw hunk from `git diff` here to show a GitHub-style diff without marking lines by hand. Optional. The renderer drops the diff headers (`@@`, `---`, `+++`), keeps context lines, and records which lines are added or removed for you. Prefer `patch` over `code` + `diff` for any real diff; it removes the hand-marking a weak model gets wrong. Set `patch` or `code`, not both, and do not also set `diff`.
- `diff` - set `true` to show a block as a GitHub-style diff. Optional; prefer `patch` for a real hunk. Two modes: (1) Hand-marked: put both old and new lines in `code`, then mark each changed line with a trailing comment, `// [!code --]` on a removed line and `// [!code ++]` on an added line. Use the language comment token (`#` for shell or Python, `--` for SQL). The renderer strips the marker and records the line. (2) All-added: set `diff: true` and mark no lines; the renderer treats every line as added, including blank lines, so a code excerpt that is entirely new in this PR renders green with no hand-marking and no untinted gaps. Use this for a new file or a new function. Removed lines tint red and added lines tint green.
- `render` - set `"markdown"` to render the block as HTML (a table, list, or the PR comment the change produces) instead of a code excerpt. A Markdown block needs no `lang` and must not set `diff`. Use a Markdown table only when it shows data the prose does not. Do not restate the `why` or repeat the same cell value down a column; drop the block if the code excerpt already tells the reader enough.
- `risk` - an optional risk heatmap for the block, so the reader sees where the risk sits while reading the code. It has:
- `score` - a block risk score from 1 to 10. Optional. The renderer draws a colored chip (Low, Medium, High) beside the block label, using the same thresholds as the page risk score.
- `reason` - one short sentence on why the block carries risk. Optional. Shown as the chip's hover tooltip.
- `lines` - an optional list that tints specific lines. Each entry has `match` (a substring the renderer searches for in the block's code; the first line that contains it is flagged), `severity` (`low`, `medium`, or `high`; `low` draws no tint), and an optional `note` shown when the reader hovers the line. Match on a stable, distinctive substring, not a whole line, so the flag survives small edits. Add `risk` only where it earns its place: a terminal flag, an unbounded loop, an auth check. Do not flag every line.
**Reserved tokens.** The renderer substitutes seven sentinels in the shell: `{{PR_TITLE}}`, `{{PR_URL}}`, `{{PR_FILES_URL}}`, `{{PR_NUMBER}}`, `{{REPO}}`, `{{RISK_SCORE}}`, and `{{CONTENT}}`. A code excerpt must not contain one of these tokens. If the real source holds one (this only happens when you walk through the walkthrough tool itself), the build fails with `unreplaced placeholder(s)`. Trim the excerpt so the token is not in it.
`edges[]` connects nodes and draws labelled arrows. Each edge has `from`, `to` (both must match a change `id`), and a short `label` that names the interaction (for example `"writes row"`, `"reads rows"`). The renderer fails if an edge points at an unknown id.
Draw an edge only for a real interaction: one node calls, reads, writes, or passes data to another. Prefer edges between neighbours. The renderer lays out groups as left-to-right columns, so an edge that skips a column draws a long arrow over the box between them and reads as clutter. Do not add an edge for a loose theme such as "same pattern" or "similar change"; leave those nodes unconnected.
`group` draws a boundary box per service, job, or runtime the change touches. Give the same `group` string to every change that runs in that place; the renderer draws one box around them and lays out each group as a column. Add a `group` only when the change crosses a boundary (for example different backend services, or a CI job that writes to GitHub). Leave `group` off for a change that stays in one place.
Use the canvas view when 3 or more changes interact. For a trivial PR with one or two isolated changes, still list them; the renderer keeps the list and the canvas holds few nodes.
#### GitHub file links
The renderer builds each file link for you. It anchors a file on the PR diff page by the SHA-256 of its path (`<pr.url>/files#diff-<sha256>`). You do not compute the hash. Set `pr.url` correctly, and the links are right. For a rare case that needs a different target (for example a link to the file at the head commit, `<repo_url>/blob/<head_sha>/<path>`), set `file_url` on that change to override the default.
#### Risk score
Score the PR risk from 1 to 10, where 10 is the highest risk, in `risk.score`. The renderer sets the knob position and the level color (Low, Medium, High) from the number. Judge the score from real signals: blast radius, test coverage of the change, rollback cost, data or migration changes, and public contract changes. Give three short bullets in `risk.reasons` that justify the score.
### 4. Generate the page
Write the data file to `<output-dir>/pr-<number>.json` (see "Output" for how to resolve `<output-dir>`). Follow the shape in `references/example.json`. Use real file paths and real code from the head commit. Do not fabricate code. Keep the diagrams small: 5-12 nodes each.
Then run the renderer (`<skill-dir>` is the directory this skill lives in):
```bash
python3 <skill-dir>/references/build.py \
<output-dir>/pr-<number>.json \
<output-dir>/pr-<number>.html
```
The renderer validates the data and fails with a clear message on a missing field (for example `changes[0].file is required`). If it fails, fix the JSON and run it again. Do not edit the HTML by hand; the next run overwrites it. When it prints `wrote ...`, the page is built.
The renderer has its own test suite. Run it after changing `build.py` to confirm the escaping, patch conversion, layout, and validation rules still hold:
```bash
cd <skill-dir>/references && python3 -m unittest test_build
```
### 5. Validate
The renderer already guarantees the mechanical parts: every code block is escaped, the canvas and the list match, no placeholder is left, and every edge points at a real node. Open the HTML in a browser and confirm the parts that need a live page:
- Confirm the file opens from `file://` and needs no local server.
- Confirm the theme toggle switches dark and light, and that code and diagrams stay readable in both.
- Confirm every code block is highlighted and every Mermaid diagram renders.
- Confirm the canvas spans the full browser width while the prose around it stays centered, and that the page has no horizontal scrollbar.
- Confirm the canvas pans by dragging, the +/- buttons zoom in and out, and the mouse wheel scrolls the page (it does not zoom the canvas) even with the pointer over the canvas.
- Confirm the Fit button frames all nodes and boundary boxes, and the Maximize button fills the viewport with an opaque background that hides the page content behind it, then re-fits.
- Confirm a node click opens the right-side panel with the node title, file link, description, and highlighted code, even after a drag (the click hit-test uses the element under the pointer, not the drag capture target).
- Confirm a node with more than one code block shows every block in the panel, each under its own label.
- Confirm the panel opens wide enough to read the code, and that the reviewer can drag the panel left edge to resize it.
- Confirm the panel close button, the Esc key, and a click on empty canvas space all close the panel and clear the node highlight.
- Confirm panning does not highlight node text, and that text inside the panel is still selectable.
- Confirm a block with `"render": "markdown"` renders as HTML (a table shows rows and columns, not raw pipes).
- Confirm a block with `"diff": true` tints removed lines red and added lines green, and that no `[!code ++]` or `[!code --]` marker is visible in the rendered code. A blank line inside an all-added block keeps the green tint but shows no `+` glyph, and its tint never overflows onto the line below it.
- Confirm every Mermaid diagram is legible: a tall or square diagram fills the container width, and a wide `LR` chain holds a readable height and scrolls sideways instead of shrinking to a thin strip.
- Confirm every boundary box sits behind its nodes, holds them with a margin, and shows a readable label.
- Confirm every canvas edge draws an arrow and no node overlaps another.
- Confirm the `<h1>` title and the `PR #<number>` badge both link to the PR URL.
- Confirm each GitHub file link opens the right file in the PR diff.
- Confirm the risk knob sits at the score and the level color matches (Low, Medium, High).
- Confirm a block with a `risk` shows a colored chip beside its label, tints each flagged line with a left bar, and shows the line's `note` on hover.
- Confirm the Review split button opens the correct GitHub review pane, and the dropdown copies the `gh pr review ... --approve` command for the right PR number and repo.
- Confirm all prose follows Simplified Technical English.
If a browser is not available to verify rendering, report rendering as unverified instead of ready.
**In a non-interactive run (CI, no human at the screen)**, you cannot do the manual checks above. Run one headless check that loads the page and confirms the parts are present:
```bash
chromium --headless --no-sandbox --disable-gpu --disable-dbus \
--virtual-time-budget=15000 --dump-dom \
"file://$PWD/<output-dir>/pr-<number>.html" > /tmp/wt.dom.html
grep -q 'PR #<number>' /tmp/wt.dom.html && \
grep -q 'class="shiki' /tmp/wt.dom.html && \
grep -q 'mermaid-host' /tmp/wt.dom.html && \
grep -q 'id="canvas-wrap"' /tmp/wt.dom.html && echo OK
```
`--disable-dbus` stops the harmless `Failed to connect to the bus` noise. The `--dump-dom` grep is the terminal validation for a non-interactive run. Do not take a screenshot: a screenshot only helps when a human will view it, and in CI no one does. If you do take one for a check, you must `view` it before you finish; never end a turn on a screenshot you did not read.
## Final response
Report:
- The generated file path and the `file://` URL.
- The inferred base branch and the PR title or branch name.
- The PR URL, if one exists.
- Which sections you included, and any you left out.
- Any caveats or validation you could not perform.
.agents/skills/pr-walkthrough/references/build.py
+631
View File
@@ -0,0 +1,631 @@
#!/usr/bin/env python3
"""Render a PR walkthrough HTML page from a JSON data file.
Usage:
python3 build.py <data.json> [output.html]
The model writes only the JSON. This script owns the fixed shell, HTML
escaping, the dual canvas/list views, canvas node layout, GitHub file
anchors, and required-field validation. It fails loudly on a missing field,
so a walkthrough is never silently incomplete.
"""
import re
import sys
import json
import html
import hashlib
from pathlib import Path
from urllib.parse import urlparse
HERE = Path(__file__).resolve().parent
SHELL = HERE / "shell.html"
# ---- canvas layout constants (canvas pixels) ----
NODE_W = 340
# Node column stride (node width + gap). The gap must stay wide enough for an
# edge label pill to sit in the clear space between two adjacent group boxes:
# clear gap = COL_STRIDE - NODE_W - 2*GROUP_PAD, kept around 120px so a
# nowrap label ("passes close") reads without overlapping either box.
COL_STRIDE = 500
ROW_STRIDE = 240 # node row stride
ORIGIN_X = 40
ORIGIN_Y = 60
GROUP_PAD = 20
GROUP_TOP_PAD = 28
NODE_EST_H = 150 # estimated node height for group-box sizing
STAGE_PAD = 120
class BuildError(Exception):
pass
def esc(s):
"""Escape text for HTML body content."""
return html.escape("" if s is None else str(s), quote=False)
def esc_attr(s):
"""Escape text for an HTML attribute value."""
return html.escape("" if s is None else str(s), quote=True)
def require(cond, msg):
if not cond:
raise BuildError(msg)
def sha256_hex(s):
return hashlib.sha256(s.encode("utf-8")).hexdigest()
def file_url(change, pr):
"""The GitHub link for a change: an explicit URL, or the diff anchor."""
if change.get("file_url"):
value = change["file_url"]
parsed = urlparse(value)
require(parsed.scheme in {"http", "https"} and bool(parsed.netloc),
"file_url must be an HTTP or HTTPS URL")
return value
return f'{pr["url"]}/files#diff-{sha256_hex(change["file"])}'
# Comment token per Shiki language, for the "// [!code ++]" marker a raw
# patch is converted into. Falls back to "//" for anything not listed.
COMMENT_TOKENS = {
"python": "#", "py": "#", "bash": "#", "sh": "#", "shell": "#",
"shellscript": "#", "zsh": "#", "fish": "#", "ruby": "#", "rb": "#",
"yaml": "#", "yml": "#", "toml": "#", "makefile": "#", "dockerfile": "#",
"r": "#", "perl": "#", "elixir": "#",
"sql": "--", "haskell": "--", "lua": "--",
"lisp": ";", "clojure": ";", "scheme": ";",
}
def patch_to_marked(patch):
"""Turn a raw unified diff into clean code plus added/removed line indices.
Each patch line drives the output: '+' becomes an added line, '-' a
removed line, and a leading space is context. Diff headers (---, +++,
@@, diff --git, index) are dropped. The +/- classification is returned as
two lists of 1-based line indices, not as inline comment markers, so a
changed line whose body contains a comment token inside a string (for
example a Rust `r#"...//..."#` literal) is still tagged correctly.
File headers (---, +++, diff , index ) only appear before the first @@ hunk,
so they are stripped only while not yet inside a hunk. Once a hunk starts,
every line is classified by its first character. This keeps content lines
whose body starts with "--" (a removed "-- comment") or "++" (an added
"++i") instead of mistaking them for headers and dropping them.
Returns (code, added, removed): the joined source, and two 1-based index
lists for the added and removed lines.
"""
out, added, removed = [], [], []
in_hunk = False
for raw in patch.splitlines():
if raw.startswith("@@"):
in_hunk = True
continue
if not in_hunk and raw.startswith(("+++", "---", "diff ", "index ")):
continue
if not raw:
out.append("")
continue
tag, body = raw[0], raw[1:]
if tag == "+":
out.append(body)
added.append(len(out))
elif tag == "-":
out.append(body)
removed.append(len(out))
elif tag == "\\":
# "\ No newline at end of file" is a git marker, not source.
continue
else:
out.append(body if tag == " " else raw)
return "\n".join(out), added, removed
# Line-risk severities that get a colored heatmap bar. "low" is accepted in
# the schema but draws no bar (it is not a concern the reviewer must see).
RISK_SEVERITIES = ("low", "medium", "high")
RISK_TINTED = ("medium", "high")
def validate_block_risk(risk, ctx):
"""Check an optional per-block "risk" object. Return it unchanged."""
require(isinstance(risk, dict), f'{ctx}: "risk" must be an object')
if risk.get("score") is not None:
s = int(risk["score"])
require(1 <= s <= 10, f'{ctx}: risk.score must be 1-10')
for j, ln in enumerate(risk.get("lines") or []):
lctx = f'{ctx}: risk.lines[{j}]'
require(ln.get("match"), f'{lctx}.match is required')
sev = (ln.get("severity") or "").lower()
require(sev in RISK_SEVERITIES,
f'{lctx}.severity must be one of {RISK_SEVERITIES}')
return risk
def block_risk_attr(risk):
"""A JSON data-risk attribute the page JS reads after Shiki renders.
Only the fields the JS needs (lines: match/severity/note) are carried;
the score/reason drive the chip, which build.py renders directly.
"""
lines = [
{"match": ln["match"],
"severity": (ln.get("severity") or "").lower(),
"note": ln.get("note", "")}
for ln in (risk.get("lines") or [])
]
if not lines:
return ""
return f" data-risk='{esc_attr(json.dumps(lines))}'"
def block_risk_chip(risk):
"""A colored risk chip for the block label row, colored client-side.
Carries data-score so initRisk's shared riskStyle colors it with the
same thresholds as the risk section and the topbar badge.
"""
if risk.get("score") is None:
return ""
score = int(risk["score"])
reason = risk.get("reason", "")
title = f' title="{esc_attr(reason)}"' if reason else ""
return (f'<span class="block-risk-chip" data-score="{esc_attr(score)}"'
f'{title}><span class="block-risk-word">Risk</span> '
f'<span class="block-risk-score">{esc(score)}</span>'
f'<span class="block-risk-level"></span></span>')
# A hand-marked diff line ends with a "[!code ++]" or "[!code --]" comment.
# The comment token before the marker is optional and any token is accepted,
# so the same regex works for every language.
_MARK_ADD = re.compile(r"\s*(?://|#|--|;)?\s*\[!code \+\+\]\s*$")
_MARK_DEL = re.compile(r"\s*(?://|#|--|;)?\s*\[!code --\]\s*$")
def parse_hand_marked(code):
"""Split hand-marked diff code into clean code plus added/removed indices.
A line ending with "[!code ++]" (added) or "[!code --]" (removed) is
stripped of its marker and its 1-based index is recorded. This removes the
marker at build time, so a marker inside a string never survives to the
page. Returns (code, added, removed).
"""
out, added, removed = [], [], []
for ln in code.splitlines():
if _MARK_ADD.search(ln):
out.append(_MARK_ADD.sub("", ln))
added.append(len(out))
elif _MARK_DEL.search(ln):
out.append(_MARK_DEL.sub("", ln))
removed.append(len(out))
else:
out.append(ln)
return "\n".join(out), added, removed
def all_added_indices(code):
"""Return the 1-based index of every line in an entirely-new block.
Used for a block that is entirely new in the PR: the agent sets
"diff": true but marks no lines, so every line reads as added. Blank lines
are included too, so the green background stays continuous across a blank
line in the middle of the excerpt instead of leaving an untinted gap.
"""
return list(range(1, len(code.splitlines()) + 1))
def diff_attrs(added, removed):
"""The data attributes the page JS reads to tint diff lines by index."""
out = ' data-diff="true"'
if added:
out += f' data-added="{",".join(str(i) for i in added)}"'
if removed:
out += f' data-removed="{",".join(str(i) for i in removed)}"'
return out
def render_block(block, ctx):
"""One code block: a Shiki excerpt, a diff, or rendered Markdown."""
if block.get("render") == "markdown":
require(block.get("code") is not None, f'{ctx}: block missing "code"')
lang = block.get("lang", "markdown")
return (f'<pre class="code-block" data-lang="{esc_attr(lang)}" '
f'data-render="markdown"><code>{esc(block["code"])}</code></pre>')
require(block.get("lang"), f'{ctx}: block missing "lang"')
added, removed = [], []
if block.get("patch") is not None:
require(block.get("code") is None,
f'{ctx}: set "patch" or "code", not both')
require(not block.get("diff"),
f'{ctx}: "patch" already implies a diff; drop "diff"')
code, added, removed = patch_to_marked(block["patch"])
is_diff = True
else:
require(block.get("code") is not None, f'{ctx}: block missing "code"')
code, is_diff = block["code"], block.get("diff")
if is_diff and "[!code " in code:
# Hand-marked lines: strip the markers and record their indices.
code, added, removed = parse_hand_marked(code)
elif is_diff:
# A diff block with no marker is a fully-added excerpt, so every
# non-blank line reads as added and the block tints green.
added = all_added_indices(code)
diff = diff_attrs(added, removed) if is_diff else ""
risk_attr = block_risk_attr(block["risk"]) if block.get("risk") else ""
return (f'<pre class="code-block" data-lang="{esc_attr(block["lang"])}"'
f'{diff}{risk_attr}><code>{esc(code)}</code></pre>')
def layout(changes):
"""Assign an id and (x, y) to each change. Return group boxes.
When changes carry a "group", each group is one column of nodes and gets
a boundary box. Otherwise the nodes fall into a 2 or 3 column grid.
"""
for i, c in enumerate(changes):
c.setdefault("id", f"n{i + 1}")
if any(c.get("group") for c in changes):
order, cols = [], {}
for c in changes:
g = c.get("group") or ""
if g not in cols:
cols[g] = []
order.append(g)
cols[g].append(c)
boxes = []
for col_idx, g in enumerate(order):
for row_idx, c in enumerate(cols[g]):
c["_x"] = ORIGIN_X + col_idx * COL_STRIDE
c["_y"] = ORIGIN_Y + row_idx * ROW_STRIDE
if g:
rows = len(cols[g])
boxes.append((
g,
ORIGIN_X + col_idx * COL_STRIDE - GROUP_PAD,
ORIGIN_Y - GROUP_TOP_PAD,
NODE_W + GROUP_PAD * 2,
(rows - 1) * ROW_STRIDE + NODE_EST_H + GROUP_PAD * 2,
))
return boxes
ncols = 3 if len(changes) > 4 else 2
for i, c in enumerate(changes):
c["_x"] = ORIGIN_X + (i % ncols) * COL_STRIDE
c["_y"] = ORIGIN_Y + (i // ncols) * ROW_STRIDE
return []
def stage_size(changes, boxes):
"""Size the stage so every node and box fits inside it."""
max_x = max([c["_x"] + NODE_W for c in changes]
+ [b[1] + b[3] for b in boxes] + [0])
max_y = max([c["_y"] + NODE_EST_H for c in changes]
+ [b[2] + b[4] for b in boxes] + [0])
return max(2400, max_x + STAGE_PAD), max(1400, max_y + STAGE_PAD)
def block_label_row(b):
"""The label line above a code block, with an optional risk chip.
Emitted when the block has a label or a risk chip; otherwise empty so a
plain block keeps its old markup.
"""
chip = block_risk_chip(b["risk"]) if b.get("risk") else ""
label = b.get("label")
if not label and not chip:
return ""
text = esc(label) if label else '<span class="block-risk-only">Code</span>'
return f'<div class="cpanel-block-label">{text}{chip}</div>'
def render_cnode(c, pr):
"""One canvas node with its hidden detail block for the panel."""
url = file_url(c, pr)
file_link = (f'<a href="{esc_attr(url)}" target="_blank" rel="noopener" '
f'class="cnode-file">{esc(c["file"])} \u2197</a>') if url else ""
blocks = "".join(
block_label_row({**b, "label": b.get("label", "Change")})
+ render_block(b, f'change {c["id"]}')
for b in c["blocks"]
)
group = c.get("group") or ""
group_attr = f' data-group="{esc_attr(group)}"' if group else ""
return (
f'<div class="cnode" data-id="{esc_attr(c["id"])}"{group_attr} '
f'style="left: {c["_x"]}px; top: {c["_y"]}px;">'
f'<div class="cnode-head"><span class="cnode-title">{esc(c["title"])}</span>'
f'{file_link}</div>'
f'<div class="cnode-sig">{esc(c.get("sig", ""))}</div>'
f'<div class="cnode-more">Click for details \u2192</div>'
f'<div class="cnode-detail" data-title="{esc_attr(c["title"])}" '
f'data-file="{esc_attr(c["file"])}" data-file-url="{esc_attr(url)}">'
f'<p class="cpanel-desc">{esc(c["why"])}</p>{blocks}</div></div>'
)
def render_article(c, pr):
"""The linear-list version of one change (plain-text fallback)."""
url = file_url(c, pr)
blocks = ""
for b in c["blocks"]:
blocks += block_label_row(b)
blocks += render_block(b, f'change {c["id"]}')
return (
'<article class="mb-9">'
f'<h3 class="font-semibold text-brand-soft mb-1">{esc(c["title"])}</h3>'
f'<a href="{esc_attr(url)}" target="_blank" rel="noopener" '
'class="inline-flex items-center gap-1 text-sm text-slate-500 '
'dark:text-slate-400 font-mono mb-2 hover:text-brand">'
f'{esc(c["file"])} <span aria-hidden="true">\u2197</span></a>'
f'<p class="mb-3">{esc(c["why"])}</p>{blocks}</article>'
)
def render_groups(boxes):
# The initial left/top/width/height are estimates. sizeGroups() in the shell
# recomputes each box from its member nodes' real heights after Shiki settles
# them, keyed on data-group, so the dashed box always wraps its nodes.
return "".join(
f'<div class="cgroup" data-group="{esc_attr(name)}" '
f'style="left: {left}px; top: {top}px; '
f'width: {w}px; height: {h}px;">'
f'<span class="cgroup-label"><span class="dot"></span>{esc(name)}</span></div>'
for name, left, top, w, h in boxes
)
def render_edges(edges, ids):
out = ""
for e in edges:
require(e.get("from") in ids, f'edge references unknown node "{e.get("from")}"')
require(e.get("to") in ids, f'edge references unknown node "{e.get("to")}"')
out += (f'<div class="cedge" data-from="{esc_attr(e["from"])}" '
f'data-to="{esc_attr(e["to"])}" '
f'data-label="{esc_attr(e.get("label", ""))}"></div>')
return out
def mermaid_box(src, extra=""):
return (f'<div class="rounded-xl border border-slate-200 dark:border-white/10 '
f'p-4 bg-slate-50/60 dark:bg-white/5{extra}">'
f'<pre class="mermaid-src"><code>{esc(src)}</code></pre></div>')
def sec_tldr(pr):
url = esc_attr(pr["url"])
return f'''<section id="tldr" class="anchor-target mb-14">
<h1 class="text-3xl font-bold tracking-tight"><a href="{url}" class="hover:text-brand">{esc(pr["title"])} <span class="text-slate-400 dark:text-slate-500 font-normal">\u2197</span></a></h1>
<div class="mt-3 flex flex-wrap gap-2 text-xs">
<span class="rounded-full bg-slate-100 dark:bg-white/10 px-2.5 py-1">{esc(pr["base"])} \u2190 {esc(pr["head"])}</span>
<span class="rounded-full bg-slate-100 dark:bg-white/10 px-2.5 py-1">{esc(pr.get("files_changed", "?"))} files</span>
<span class="rounded-full bg-emerald-100 text-emerald-700 dark:bg-emerald-500/15 dark:text-emerald-300 px-2.5 py-1">+{esc(pr.get("added", "?"))}</span>
<span class="rounded-full bg-rose-100 text-rose-700 dark:bg-rose-500/15 dark:text-rose-300 px-2.5 py-1">\u2212{esc(pr.get("removed", "?"))}</span>
<a href="{url}" class="rounded-full border border-slate-300 dark:border-white/15 px-2.5 py-1 hover:text-brand">PR #{esc(pr["number"])} \u2197</a>
</div>
<p class="mt-5 text-lg text-slate-600 dark:text-slate-300">{esc(pr.get("tldr", ""))}</p>
</section>'''
def sec_why(why):
items = "".join(f'<li>{esc(w)}</li>' for w in why["what"])
return f'''<section id="why" class="anchor-target mb-14">
<h2 class="text-xl font-semibold mb-3">Why this change</h2>
<p class="mb-4">{esc(why["problem"])}</p>
<h3 class="text-sm font-semibold uppercase tracking-wide text-slate-500 dark:text-slate-400 mb-2">What it does</h3>
<ul class="list-disc pl-5 space-y-1.5 marker:text-brand">{items}</ul>
</section>'''
def sec_arch(arch):
return f'''<section id="architecture" class="anchor-target mb-14">
<h2 class="text-xl font-semibold mb-3">Architecture, end to end</h2>
<p class="mb-4 text-slate-600 dark:text-slate-300">{esc(arch.get("caption", ""))}</p>
{mermaid_box(arch["mermaid"])}
</section>'''
def sec_changes(changes, edges, pr):
boxes = layout(changes)
ids = {c["id"] for c in changes}
sw, sh = stage_size(changes, boxes)
stage_inner = (f'<svg id="canvas-edges" class="absolute left-0 top-0 '
f'pointer-events-none" width="{sw}" height="{sh}" '
f'style="overflow: visible;"></svg>'
+ render_groups(boxes)
+ "".join(render_cnode(c, pr) for c in changes)
+ render_edges(edges, ids))
articles = "".join(render_article(c, pr) for c in changes)
return f'''<section id="changes" class="anchor-target mb-14">
<h2 class="text-xl font-semibold mb-2">Key code changes</h2>
<p class="mb-4 text-slate-600 dark:text-slate-300">Drag to pan. Use the + and \u2212 buttons to zoom. Click a node to open the full code. The arrows show how the parts interact.</p>
<div id="canvas-wrap" class="canvas-full-bleed relative rounded-xl border border-slate-200 dark:border-white/10 bg-slate-50/60 dark:bg-white/5 overflow-hidden" style="height: 640px; touch-action: none;">
<div class="absolute right-3 top-3 z-20 flex gap-1">
<button data-cz="out" class="w-8 h-8 rounded-lg border border-slate-300 dark:border-white/15 bg-white/90 dark:bg-white/10 text-lg leading-none hover:bg-slate-100 dark:hover:bg-white/20">\u2212</button>
<button data-cz="in" class="w-8 h-8 rounded-lg border border-slate-300 dark:border-white/15 bg-white/90 dark:bg-white/10 text-lg leading-none hover:bg-slate-100 dark:hover:bg-white/20">+</button>
<button data-cz="fit" class="h-8 px-2 rounded-lg border border-slate-300 dark:border-white/15 bg-white/90 dark:bg-white/10 text-xs hover:bg-slate-100 dark:hover:bg-white/20">Fit</button>
<button data-cz="max" title="Maximize" aria-label="Maximize canvas" class="h-8 px-2 rounded-lg border border-slate-300 dark:border-white/15 bg-white/90 dark:bg-white/10 text-xs hover:bg-slate-100 dark:hover:bg-white/20"><span class="label-max">Maximize</span><span class="label-min" style="display:none">Close</span></button>
</div>
<p class="absolute left-3 bottom-2 z-20 text-[11px] text-slate-400 dark:text-slate-500 pointer-events-none">drag to pan \u00b7 +/\u2212 to zoom \u00b7 click a node for details</p>
<aside id="canvas-panel" class="cpanel" aria-hidden="true">
<div id="cpanel-resizer" class="cpanel-resizer" role="separator" aria-orientation="vertical" aria-label="Resize details panel"></div>
<div class="cpanel-head">
<div>
<div id="cpanel-title" class="cpanel-title"></div>
<a id="cpanel-file" class="cpanel-file" target="_blank" rel="noopener"></a>
</div>
<button id="cpanel-close" type="button" class="cpanel-close" aria-label="Close details">\u00d7</button>
</div>
<div id="cpanel-body" class="cpanel-body"></div>
</aside>
<div id="canvas-stage" class="absolute left-0 top-0 origin-top-left" style="width: {sw}px; height: {sh}px;">{stage_inner}</div>
</div>
<details class="mt-5 group">
<summary class="cursor-pointer select-none text-sm text-slate-500 dark:text-slate-400 hover:text-brand">Read the changes as a list</summary>
<div class="mt-5">{articles}</div>
</details>
</section>'''
def sec_data(data):
parts = []
if data.get("mermaid"):
parts.append(mermaid_box(data["mermaid"], extra=" mb-6"))
if data.get("fields"):
rows = "".join(
f'<tr><td class="px-4 py-2 font-mono">{esc(f.get("field", ""))}</td>'
f'<td class="px-4 py-2 font-mono">{esc(f.get("type", ""))}</td>'
f'<td class="px-4 py-2">{esc(f.get("note", ""))}</td></tr>'
for f in data["fields"]
)
parts.append(
'<div class="overflow-x-auto rounded-xl border border-slate-200 dark:border-white/10">'
'<table class="w-full text-sm"><thead class="bg-slate-100 dark:bg-white/5 text-left">'
'<tr><th class="px-4 py-2 font-semibold">Field</th>'
'<th class="px-4 py-2 font-semibold">Type</th>'
'<th class="px-4 py-2 font-semibold">Notes</th></tr></thead>'
f'<tbody class="divide-y divide-slate-200 dark:divide-white/10">{rows}</tbody></table></div>'
)
return f'''<section id="data" class="anchor-target mb-14">
<h2 class="text-xl font-semibold mb-3">Data and storage</h2>
<p class="mb-4 text-slate-600 dark:text-slate-300">{esc(data.get("caption", ""))}</p>
{"".join(parts)}
</section>'''
def sec_risk(risk):
score = int(risk["score"])
level = "Low" if score <= 3 else "Medium" if score <= 6 else "High"
reasons = "".join(f'<li>{esc(r)}</li>' for r in risk["reasons"])
return f'''<section id="risk" class="anchor-target mb-14">
<h2 class="text-xl font-semibold mb-3">Risk</h2>
<div class="rounded-xl border border-slate-200 dark:border-white/10 p-5 bg-slate-50/60 dark:bg-white/5">
<div class="flex items-baseline gap-3">
<span class="text-4xl font-bold" id="risk-score">{score}</span>
<span class="text-slate-500 dark:text-slate-400 text-lg">/ 10</span>
<span id="risk-level" class="ml-auto rounded-full px-3 py-1 text-sm font-semibold">{level}</span>
</div>
<div id="risk-meter" data-score="{score}" class="mt-4 relative">
<div class="risk-track"></div>
<div class="absolute -top-1" id="risk-knob-wrap" style="left: 0%;"><div class="risk-knob"></div></div>
<div class="mt-1 flex justify-between text-[11px] text-slate-400 dark:text-slate-500"><span>1 low</span><span>5 medium</span><span>10 high</span></div>
</div>
<h3 class="text-sm font-semibold uppercase tracking-wide text-slate-500 dark:text-slate-400 mt-6 mb-2">Why this score</h3>
<ul class="list-disc pl-5 space-y-1.5 marker:text-brand">{reasons}</ul>
</div>
</section>'''
def sec_review(review):
tradeoffs = "".join(f'<li>{esc(t)}</li>' for t in review.get("tradeoffs", []))
focus = "".join(f'<li>{esc(f)}</li>' for f in review.get("focus", []))
return f'''<section id="review" class="anchor-target mb-8">
<h2 class="text-xl font-semibold mb-3">Trade-offs and review notes</h2>
<ul class="list-disc pl-5 space-y-1.5 marker:text-brand">{tradeoffs}</ul>
<h3 class="text-sm font-semibold uppercase tracking-wide text-slate-500 dark:text-slate-400 mt-6 mb-2">Where to look first</h3>
<ol class="list-decimal pl-5 space-y-1.5">{focus}</ol>
</section>'''
def render_content(data):
pr = data["pr"]
parts = [sec_tldr(pr), sec_why(data["why"])]
if data.get("architecture"):
parts.append(sec_arch(data["architecture"]))
parts.append(sec_changes(data["changes"], data.get("edges", []), pr))
if data.get("data"):
parts.append(sec_data(data["data"]))
parts.append(sec_risk(data["risk"]))
parts.append(sec_review(data["review"]))
return "\n\n ".join(parts)
def require_str_list(value, ctx):
"""Require a non-empty list whose entries are all non-empty strings.
A plain string passes a truthiness check but the renderer iterates it
character by character into one <li> per letter, so the shape is checked
here to fail loudly on malformed walkthrough data.
"""
require(isinstance(value, list) and value,
f"{ctx} needs at least one item")
for k, item in enumerate(value):
require(isinstance(item, str) and item.strip(),
f"{ctx}[{k}] must be a non-empty string")
def validate(data):
require("pr" in data, 'missing "pr"')
pr = data["pr"]
for k in ("number", "title", "url", "base", "head", "repo"):
require(pr.get(k) not in (None, ""), f'pr.{k} is required')
require(data.get("why", {}).get("problem"), "why.problem is required")
require_str_list(data.get("why", {}).get("what"), "why.what")
changes = data.get("changes") or []
require(len(changes) >= 1, "changes needs at least one entry")
for i, c in enumerate(changes):
for k in ("title", "file", "why"):
require(c.get(k), f'changes[{i}].{k} is required')
require(c.get("blocks"), f'changes[{i}].blocks needs at least one block')
for j, b in enumerate(c["blocks"]):
if b.get("risk"):
validate_block_risk(b["risk"], f'changes[{i}].blocks[{j}]')
score = data.get("risk", {}).get("score")
require(score is not None, "risk.score is required")
try:
score = int(score)
except (TypeError, ValueError):
require(False, "risk.score must be a number")
require(1 <= score <= 10, "risk.score must be 1-10")
require_str_list(data.get("risk", {}).get("reasons"), "risk.reasons")
require("review" in data, 'missing "review"')
def build(data):
validate(data)
pr = data["pr"]
content = render_content(data)
shell = SHELL.read_text(encoding="utf-8")
require("{{CONTENT}}" in shell, "shell.html has no {{CONTENT}} marker")
files_url = pr.get("files_url") or f'{pr["url"]}/files'
for token, value in (
("{{PR_TITLE}}", esc(pr["title"])),
("{{PR_URL}}", esc_attr(pr["url"])),
("{{PR_FILES_URL}}", esc_attr(files_url)),
("{{PR_NUMBER}}", esc_attr(pr["number"])),
("{{REPO}}", esc_attr(pr.get("repo", ""))),
("{{RISK_SCORE}}", esc_attr(int(data["risk"]["score"]))),
):
shell = shell.replace(token, value)
shell = shell.replace("{{CONTENT}}", content)
leftover = [t for t in ("{{PR_TITLE}}", "{{PR_URL}}", "{{PR_FILES_URL}}",
"{{PR_NUMBER}}", "{{REPO}}", "{{RISK_SCORE}}",
"{{CONTENT}}")
if t in shell]
require(not leftover, f"unreplaced placeholder(s): {leftover}")
return shell
def main(argv):
if len(argv) < 2:
print(__doc__)
return 2
data = json.loads(Path(argv[1]).read_text(encoding="utf-8"))
out = Path(argv[2]) if len(argv) > 2 else Path(f'pr-{data["pr"]["number"]}.html')
try:
html_out = build(data)
except BuildError as e:
print(f"build failed: {e}", file=sys.stderr)
return 1
out.write_text(html_out, encoding="utf-8")
print(f"wrote {out} ({len(html_out.splitlines())} lines)")
return 0
if __name__ == "__main__":
raise SystemExit(main(sys.argv))
.agents/skills/pr-walkthrough/references/example.json
+107
View File
@@ -0,0 +1,107 @@
{
"pr": {
"number": 314,
"title": "Add bounded retries to webhook delivery",
"url": "https://github.com/example-org/parcel-service/pull/314",
"repo": "example-org/parcel-service",
"base": "main",
"head": "feature/webhook-retry-budget",
"files_changed": 5,
"added": 148,
"removed": 21,
"tldr": "Webhook delivery now retries transient failures with bounded backoff. Permanent failures stop immediately, which protects downstream services from repeated invalid requests."
},
"why": {
"problem": "The delivery worker treats every send failure the same. A short network interruption loses a webhook, while repeated retries of a rejected payload waste worker capacity.",
"what": [
"Classify transient and permanent send failures.",
"Retry transient failures with three attempts and exponential backoff.",
"Record a terminal failure after the retry budget is exhausted.",
"Add tests for recovery, permanent failure, and exhausted retries."
]
},
"architecture": {
"caption": "The worker checks the retry policy before each send. Exhausted jobs move to the dead-letter queue.",
"mermaid": "flowchart LR\n Worker[Delivery worker] --> Policy[Retry policy]\n Policy --> Sender[Webhook sender]\n Sender --> Endpoint[Remote endpoint]\n Policy -- exhausted --> DeadLetter[(Dead-letter queue)]"
},
"changes": [
{
"id": "n1",
"title": "Retry-aware delivery worker",
"file": "src/webhooks/delivery-service.ts",
"group": "Delivery worker",
"sig": "async deliver(job: DeliveryJob): Promise<DeliveryResult>",
"why": "The worker applies the retry policy around each webhook send and returns a terminal result when the budget ends.",
"blocks": [
{
"label": "Delivery loop",
"lang": "typescript",
"code": "async deliver(job: DeliveryJob): Promise<DeliveryResult> {\n let attempt = job.attempts;\n\n while (true) {\n const result = await this.sender.send(job.payload);\n if (result.ok) return { status: \"delivered\" };\n\n attempt += 1;\n job.lastError = result.error;\n if (!this.policy.canRetry(attempt, job.lastError)) break;\n await this.policy.wait(attempt);\n }\n\n return { status: \"failed\", reason: \"retry budget exhausted\" };\n}"
}
]
},
{
"id": "n2",
"title": "Bounded retry policy",
"file": "src/webhooks/retry-policy.ts",
"group": "Delivery worker",
"sig": "canRetry(attempt: number, error?: DeliveryError): boolean",
"why": "The policy retries only transient errors and caps attempts with a short exponential delay.",
"blocks": [
{
"label": "Policy",
"lang": "typescript",
"diff": true,
"code": "export class RetryPolicy {\n constructor(private readonly maxAttempts = 3) {}\n\n canRetry(attempt: number, error?: DeliveryError): boolean {\n return error?.kind === \"transient\" && attempt < this.maxAttempts;\n }\n\n delay(attempt: number): number {\n return Math.min(1000 * 2 ** attempt, 8000);\n }\n}"
}
]
},
{
"id": "n3",
"title": "Failure classification",
"file": "src/webhooks/webhook-sender.ts",
"group": "Delivery worker",
"sig": "async send(payload: WebhookPayload): Promise<SendResult>",
"why": "The sender turns response status into a retryable or permanent error before the worker decides what to do next.",
"blocks": [
{
"label": "Send result",
"lang": "typescript",
"code": "async send(payload: WebhookPayload): Promise<SendResult> {\n const response = await this.http.post(payload.url, payload.body);\n if (response.status === 429 || response.status >= 500) {\n return { ok: false, error: { kind: \"transient\", status: response.status } };\n }\n if (!response.ok) {\n return { ok: false, error: { kind: \"permanent\", status: response.status } };\n }\n return { ok: true };\n}"
}
]
}
],
"edges": [
{ "from": "n1", "to": "n2", "label": "checks budget" },
{ "from": "n1", "to": "n3", "label": "sends payload" },
{ "from": "n3", "to": "n1", "label": "returns outcome" }
],
"data": {
"caption": "Each delivery record stores retry state so a resumed worker can continue from the last attempt.",
"fields": [
{ "field": "attempts", "type": "integer", "note": "number of sends already made" },
{ "field": "status", "type": "enum", "note": "pending, delivered, or failed" },
{ "field": "last_error", "type": "json", "note": "classified error from the latest send" }
]
},
"risk": {
"score": 4,
"reasons": [
"A policy mistake could delay delivery or drop a transient failure.",
"The attempt cap bounds extra traffic to the remote endpoint.",
"Existing successful deliveries keep the same single-send path."
]
},
"review": {
"tradeoffs": [
"Exponential backoff improves recovery but increases delivery time during an outage.",
"Permanent failures stop early but require accurate response classification."
],
"focus": [
"Check that status classification matches the endpoint contract.",
"Confirm the attempt count is persisted before a worker restart.",
"Verify exhausted jobs receive a clear terminal status."
]
}
}
.agents/skills/pr-walkthrough/references/shell.html
+1034
View File
File diff suppressed because it is too large Load Diff
.agents/skills/pr-walkthrough/references/test_build.py
+450
View File
@@ -0,0 +1,450 @@
"""Unit tests for build.py.
Run from this directory with:
python3 -m unittest test_build
These tests guard the parts of the renderer a bad JSON file could break
silently: the raw-patch to Shiki-marker conversion, per-language comment
tokens, block rendering and its mutual-exclusion rules, HTML escaping,
GitHub file links, canvas layout, edge validation, and the required-field
checks. build.py uses only the standard library, and so do these tests.
"""
import os
import sys
import unittest
HERE = os.path.dirname(os.path.abspath(__file__))
sys.path.insert(0, HERE)
import build # noqa: E402
def minimal_change():
"""A fresh, valid change dict. layout() mutates it, so never share one."""
return {
"title": "T",
"file": "a/b.go",
"why": "does a thing",
"blocks": [{"lang": "go", "code": "x := 1"}],
}
def minimal_data():
return {
"pr": {"number": 1, "title": "P", "url": "https://h/pr/1",
"repo": "o/r", "base": "master", "head": "feat"},
"why": {"problem": "p", "what": ["w"]},
"changes": [minimal_change()],
"risk": {"score": 2, "reasons": ["r"]},
"review": {},
}
class TestPatchToMarked(unittest.TestCase):
def test_headers_dropped_context_kept_indices_recorded(self):
patch = ("diff --git a/f b/f\nindex 1..2 100644\n--- a/f\n+++ b/f\n"
"@@ -1,3 +1,3 @@ func F() {\n ctx\n-old\n+new\n more")
code, added, removed = build.patch_to_marked(patch)
self.assertEqual(code, "ctx\nold\nnew\nmore")
self.assertEqual(added, [3])
self.assertEqual(removed, [2])
for h in ("diff --git", "index ", "@@", "--- ", "+++ ", "[!code"):
self.assertNotIn(h, code)
def test_blank_line_preserved(self):
self.assertEqual(build.patch_to_marked(" a\n\n b"), ("a\n\nb", [], []))
def test_marker_never_inlined(self):
code, added, removed = build.patch_to_marked("+x\n-y")
self.assertEqual(code, "x\ny")
self.assertEqual((added, removed), ([1], [2]))
def test_no_newline_marker_dropped(self):
code, added, removed = build.patch_to_marked(
"@@ -1 +1 @@\n-old\n+new\n\\ No newline at end of file")
self.assertEqual(code, "old\nnew")
self.assertEqual((added, removed), ([2], [1]))
def test_removed_line_starting_with_double_dash_is_kept(self):
# Inside a hunk, a removed "-- note" line becomes "--- note" in the
# patch (leading '-' diff marker). It must be kept as a removed line,
# not dropped as a header. The diff marker is stripped, leaving "-- note".
patch = "@@ -1,1 +1,0 @@\n--- note"
code, added, removed = build.patch_to_marked(patch)
self.assertEqual(code, "-- note")
self.assertEqual((added, removed), ([], [1]))
def test_added_line_starting_with_double_plus_is_kept(self):
# Inside a hunk, an added "++i" line becomes "+++i" in the patch. It
# must be kept as an added line, not dropped as a header.
patch = "@@ -1,0 +1,1 @@\n+++i"
code, added, removed = build.patch_to_marked(patch)
self.assertEqual(code, "++i")
self.assertEqual((added, removed), ([1], []))
def test_file_headers_before_first_hunk_still_dropped(self):
patch = ("diff --git a/f b/f\nindex 1..2 100644\n--- a/f\n+++ b/f\n"
"@@ -1,1 +1,1 @@\n-old\n+new")
code, added, removed = build.patch_to_marked(patch)
self.assertEqual(code, "old\nnew")
self.assertEqual((added, removed), ([2], [1]))
def test_comment_token_inside_string_is_not_treated_as_marker(self):
# A Rust raw string that contains "//" must stay intact: the marker is
# never inlined, so nothing inside the code can look like a diff marker.
patch = '@@ -1,0 +1,1 @@\n+ r#"{"url":"/x"}, // note"#'
code, added, removed = build.patch_to_marked(patch)
self.assertEqual(code, ' r#"{"url":"/x"}, // note"#')
self.assertEqual((added, removed), ([1], []))
self.assertNotIn("[!code", code)
class TestCommentTokens(unittest.TestCase):
def test_known_languages(self):
self.assertEqual(build.COMMENT_TOKENS["python"], "#")
self.assertEqual(build.COMMENT_TOKENS["bash"], "#")
self.assertEqual(build.COMMENT_TOKENS["sql"], "--")
self.assertEqual(build.COMMENT_TOKENS["clojure"], ";")
def test_unknown_language_falls_back_to_slashes(self):
self.assertEqual(build.COMMENT_TOKENS.get("go", "//"), "//")
class TestRenderBlock(unittest.TestCase):
def test_plain_excerpt_escapes_and_has_no_diff(self):
html = build.render_block({"lang": "go", "code": "a < b & c"}, "c")
self.assertIn("a &lt; b &amp; c", html)
self.assertNotIn('data-diff="true"', html)
def test_hand_marked_diff_strips_markers_and_records_indices(self):
html = build.render_block(
{"lang": "go", "code": "old // [!code --]\nnew // [!code ++]",
"diff": True}, "c")
self.assertIn('data-diff="true"', html)
# The markers are stripped from the code and turned into index attrs.
self.assertNotIn("[!code", html)
self.assertIn('data-added="2"', html)
self.assertIn('data-removed="1"', html)
# The bare code text (marker removed) is still present, escaped.
self.assertIn("old\nnew", html)
def test_diff_with_no_markers_marks_all_lines_added(self):
html = build.render_block(
{"lang": "python", "code": "def f():\n\n return 1",
"diff": True}, "c")
self.assertIn('data-diff="true"', html)
# Every line is added, including the blank line 2, so the green tint
# stays continuous across the excerpt.
self.assertIn('data-added="1,2,3"', html)
self.assertNotIn("data-removed", html)
self.assertNotIn("[!code", html)
def test_all_added_indices_includes_blank_lines(self):
self.assertEqual(build.all_added_indices("a\n\nb"), [1, 2, 3])
def test_parse_hand_marked_strips_any_comment_token(self):
code, added, removed = build.parse_hand_marked(
"keep\nx = 1 # [!code ++]\ndrop -- [!code --]")
self.assertEqual(code, "keep\nx = 1\ndrop")
self.assertEqual((added, removed), ([2], [3]))
def test_markdown_block(self):
html = build.render_block(
{"render": "markdown", "code": "| a |"}, "c")
self.assertIn('data-render="markdown"', html)
def test_patch_block_marks_diff_by_index(self):
html = build.render_block(
{"lang": "bash", "patch": "+echo hi"}, "c")
self.assertIn('data-diff="true"', html)
self.assertIn('data-added="1"', html)
self.assertNotIn("[!code", html)
def test_patch_and_code_together_fails(self):
with self.assertRaises(build.BuildError):
build.render_block(
{"lang": "go", "patch": "+x", "code": "x"}, "c")
def test_patch_with_diff_flag_fails(self):
with self.assertRaises(build.BuildError):
build.render_block(
{"lang": "go", "patch": "+x", "diff": True}, "c")
def test_missing_lang_fails(self):
with self.assertRaises(build.BuildError):
build.render_block({"code": "x"}, "c")
def test_block_risk_emits_data_attr(self):
html = build.render_block(
{"lang": "go", "code": "x := 1",
"risk": {"score": 7,
"lines": [{"match": "x", "severity": "high",
"note": "n"}]}},
"c")
self.assertIn("data-risk=", html)
self.assertIn("&quot;match&quot;: &quot;x&quot;", html)
self.assertIn("&quot;severity&quot;: &quot;high&quot;", html)
def test_block_risk_without_lines_emits_no_data_attr(self):
html = build.render_block(
{"lang": "go", "code": "x := 1", "risk": {"score": 4}}, "c")
self.assertNotIn("data-risk=", html)
class TestBlockRiskChip(unittest.TestCase):
def test_chip_carries_score_and_reason(self):
chip = build.block_risk_chip({"score": 7, "reason": "spins"})
self.assertIn('data-score="7"', chip)
self.assertIn('title="spins"', chip)
self.assertIn('block-risk-score">7<', chip)
def test_chip_empty_without_score(self):
self.assertEqual(build.block_risk_chip({"reason": "x"}), "")
class TestValidateBlockRisk(unittest.TestCase):
def test_valid_risk_passes(self):
risk = {"score": 5,
"lines": [{"match": "y", "severity": "medium"}]}
self.assertIs(build.validate_block_risk(risk, "c"), risk)
def test_score_out_of_range_fails(self):
with self.assertRaises(build.BuildError):
build.validate_block_risk({"score": 11}, "c")
def test_line_missing_match_fails(self):
with self.assertRaises(build.BuildError):
build.validate_block_risk(
{"lines": [{"severity": "high"}]}, "c")
def test_bad_severity_fails(self):
with self.assertRaises(build.BuildError):
build.validate_block_risk(
{"lines": [{"match": "y", "severity": "critical"}]}, "c")
def test_validate_catches_bad_block_risk(self):
data = minimal_data()
data["changes"][0]["blocks"][0]["risk"] = {"score": 99}
with self.assertRaises(build.BuildError):
build.validate(data)
def test_missing_pr_repo_fails(self):
data = minimal_data()
del data["pr"]["repo"]
with self.assertRaises(build.BuildError):
build.validate(data)
def test_why_what_string_fails(self):
data = minimal_data()
data["why"]["what"] = "one string not a list"
with self.assertRaises(build.BuildError):
build.validate(data)
def test_risk_reasons_string_fails(self):
data = minimal_data()
data["risk"]["reasons"] = "one string not a list"
with self.assertRaises(build.BuildError):
build.validate(data)
def test_top_level_risk_score_non_numeric_fails(self):
data = minimal_data()
data["risk"]["score"] = "high"
with self.assertRaises(build.BuildError):
build.validate(data)
def test_top_level_risk_score_out_of_range_fails(self):
data = minimal_data()
data["risk"]["score"] = 11
with self.assertRaises(build.BuildError):
build.validate(data)
class TestEscaping(unittest.TestCase):
def test_esc_leaves_quotes_but_escapes_angles(self):
self.assertEqual(build.esc('a<b>"c'), 'a&lt;b&gt;"c')
def test_esc_attr_escapes_quotes(self):
self.assertIn("&quot;", build.esc_attr('a"b'))
def test_none_becomes_empty(self):
self.assertEqual(build.esc(None), "")
class TestFileUrl(unittest.TestCase):
def test_explicit_url_wins(self):
pr = {"url": "https://h/pr/1"}
self.assertEqual(
build.file_url({"file": "x", "file_url": "https://o"}, pr),
"https://o")
def test_default_is_sha_anchor(self):
url = build.file_url({"file": "a/b.go"}, {"url": "https://h/pr/1"})
self.assertTrue(url.startswith("https://h/pr/1/files#diff-"))
self.assertEqual(len(url.split("diff-")[1]), 64)
def test_executable_scheme_is_rejected(self):
with self.assertRaises(build.BuildError):
build.file_url(
{"file": "x", "file_url": "javascript:alert(1)"},
{"url": "https://h/pr/1"})
def test_non_http_scheme_is_rejected(self):
with self.assertRaises(build.BuildError):
build.file_url(
{"file": "x", "file_url": "data:text/html,payload"},
{"url": "https://h/pr/1"})
class TestLayout(unittest.TestCase):
def test_ids_assigned_and_two_column_grid(self):
changes = [minimal_change() for _ in range(3)]
boxes = build.layout(changes)
self.assertEqual([c["id"] for c in changes], ["n1", "n2", "n3"])
self.assertEqual(boxes, [])
# 3 changes -> 2 columns, so n3 wraps to the second row, column 0.
self.assertEqual(changes[2]["_x"], build.ORIGIN_X)
self.assertEqual(changes[2]["_y"], build.ORIGIN_Y + build.ROW_STRIDE)
def test_more_than_four_changes_uses_three_columns(self):
changes = [minimal_change() for _ in range(5)]
build.layout(changes)
self.assertEqual(changes[3]["_x"], build.ORIGIN_X + 0 * build.COL_STRIDE)
self.assertEqual(changes[3]["_y"], build.ORIGIN_Y + build.ROW_STRIDE)
def test_groups_make_one_column_each_with_a_box(self):
changes = [minimal_change(), minimal_change(), minimal_change()]
changes[0]["group"] = "A"
changes[1]["group"] = "A"
changes[2]["group"] = "B"
boxes = build.layout(changes)
self.assertEqual(len(boxes), 2)
# Group A is column 0, its two nodes stack in rows 0 and 1.
self.assertEqual(changes[0]["_x"], build.ORIGIN_X)
self.assertEqual(changes[1]["_y"], build.ORIGIN_Y + build.ROW_STRIDE)
# Group B is column 1.
self.assertEqual(changes[2]["_x"], build.ORIGIN_X + build.COL_STRIDE)
class TestRenderEdges(unittest.TestCase):
def test_valid_edge_renders(self):
html = build.render_edges(
[{"from": "n1", "to": "n2", "label": "calls"}], {"n1", "n2"})
self.assertIn('data-from="n1"', html)
self.assertIn('data-label="calls"', html)
def test_unknown_from_node_fails(self):
with self.assertRaises(build.BuildError):
build.render_edges([{"from": "nX", "to": "n1"}], {"n1"})
def test_unknown_to_node_fails(self):
with self.assertRaises(build.BuildError):
build.render_edges([{"from": "n1", "to": "nX"}], {"n1"})
class TestValidate(unittest.TestCase):
def test_minimal_data_passes(self):
build.validate(minimal_data()) # no raise
def test_missing_pr_field_fails(self):
data = minimal_data()
del data["pr"]["url"]
with self.assertRaises(build.BuildError):
build.validate(data)
def test_empty_changes_fails(self):
data = minimal_data()
data["changes"] = []
with self.assertRaises(build.BuildError):
build.validate(data)
def test_change_missing_blocks_fails(self):
data = minimal_data()
data["changes"][0]["blocks"] = []
with self.assertRaises(build.BuildError):
build.validate(data)
def test_missing_review_fails(self):
data = minimal_data()
del data["review"]
with self.assertRaises(build.BuildError):
build.validate(data)
class TestBuild(unittest.TestCase):
def test_full_build_escapes_and_fills_placeholders(self):
data = minimal_data()
data["pr"]["title"] = "Fix <a> & <b>"
data["changes"][0]["blocks"] = [{"lang": "go", "code": "if a < b {}"}]
out = build.build(data)
# No placeholder survives.
for token in ("{{PR_TITLE}}", "{{PR_URL}}", "{{PR_FILES_URL}}",
"{{PR_NUMBER}}", "{{REPO}}", "{{RISK_SCORE}}",
"{{CONTENT}}"):
self.assertNotIn(token, out)
# Title and code are escaped in the output.
self.assertIn("Fix &lt;a&gt; &amp; &lt;b&gt;", out)
self.assertIn("if a &lt; b {}", out)
def test_topbar_risk_badge_carries_score(self):
data = minimal_data()
data["risk"]["score"] = 8
out = build.build(data)
# The topbar badge and its score span both get the filled score.
self.assertIn('id="topbar-risk" href="#risk" data-score="8"', out)
self.assertIn('<span id="topbar-risk-score">8</span>', out)
def test_block_risk_chip_and_lines_render(self):
data = minimal_data()
data["changes"][0]["blocks"] = [
{"lang": "go", "code": "close := true",
"risk": {"score": 7, "reason": "terminal flag",
"lines": [{"match": "close", "severity": "high",
"note": "wrong value stalls stream"}]}}]
out = build.build(data)
self.assertIn('class="block-risk-chip" data-score="7"', out)
self.assertIn("data-risk=", out)
self.assertIn("wrong value stalls stream", out)
def test_dual_views_render_each_change(self):
data = minimal_data()
data["changes"][0]["title"] = "UniqueChangeTitle"
out = build.build(data)
# Rendered in both the canvas node and the list article.
self.assertIn(
'<span class="cnode-title">UniqueChangeTitle</span>', out)
self.assertIn(
'<h3 class="font-semibold text-brand-soft mb-1">'
'UniqueChangeTitle</h3>', out)
def test_shell_matches_kandev_landing_visual_language(self):
out = build.build(minimal_data())
self.assertIn("--wt-primary: #4f46e5", out)
self.assertIn("--wt-bg: #0d0d10", out)
self.assertIn("font-family: 'Figtree'", out)
self.assertIn("font-family: 'Geist Mono'", out)
self.assertIn('class="wt-topbar sticky', out)
self.assertIn('class="wt-brand-mark"', out)
def test_runtime_cdn_dependencies_use_exact_versions(self):
out = build.build(minimal_data())
for url in (
"https://cdn.tailwindcss.com/3.4.17",
"https://cdn.jsdelivr.net/npm/mermaid@11.17.0/dist/mermaid.esm.min.mjs",
"https://cdn.jsdelivr.net/npm/marked@12.0.2/+esm",
"https://cdn.jsdelivr.net/npm/dompurify@3.4.14/+esm",
"https://cdn.jsdelivr.net/npm/shiki@3.23.0/+esm",
):
self.assertIn(url, out)
self.assertNotIn('src="https://cdn.tailwindcss.com"', out)
def test_shell_has_mobile_section_navigation(self):
out = build.build(minimal_data())
self.assertIn('id="mobile-nav"', out)
self.assertIn('id="mobile-nav-architecture"', out)
self.assertIn('id="mobile-nav-data"', out)
self.assertIn("@media (max-width: 640px)", out)
if __name__ == "__main__":
unittest.main()