40 lines
2.4 KiB
Markdown
40 lines
2.4 KiB
Markdown
---
|
||
name: repo-change-html-report
|
||
description: "Build a self-contained HTML report of a branch's changes (per-file detail grouped by atomic change, inline SVG diagrams) and open it in the user's browser"
|
||
---
|
||
|
||
# Repo change → HTML report in browser
|
||
|
||
Produce a standalone HTML report covering `git log main..HEAD`, grouped into atomic tasks (one task may span commits; one commit may serve several tasks), per-file `what`/`why` tables, inline SVG diagrams, then `xdg-open file://…`.
|
||
|
||
## 1. Gather facts first (never from memory)
|
||
```
|
||
git log --reverse --format="COMMIT %h %s" main..HEAD
|
||
for c in $(git log --reverse --format=%h main..HEAD); do
|
||
echo "== $c $(git log -1 --format=%s $c)"; git show --format="" --stat=200 "$c"; done
|
||
```
|
||
`--stat=short` is invalid; use `--stat=200`. Supplement with the session's per-file notes.
|
||
|
||
## 2. Write to a file OUTSIDE the repo
|
||
`~/reports/<repo>-<branch-date>.html` — keeps the worktree clean.
|
||
|
||
## 3. Chunk the writes (payload limits are real)
|
||
- First chunk: `write` (head + CSS + hero cards + nav).
|
||
- Later chunks: `edit` with `PUT >$` (append), ~6–8 KB each. A single giant `write` gets truncated mid-arguments.
|
||
- **No appended body line may begin with `-`** (e.g. a wrapped `--host H`); the edit parser rejects it as a deletion row. Keep flag-like tokens inline.
|
||
- Never end a PUT mid-sentence; if a sentence spills, include ALL its lines in the same PUT, then verify the seam region reads cleanly.
|
||
|
||
## 4. Structure that worked (7-task, 13-commit branch)
|
||
- Stat cards (commits, tasks, tests green, key counts) + sticky anchor nav.
|
||
- Commit-arc SVG (dots on a timeline, colored by task; dashed edge for a task spanning two commits).
|
||
- One section per atomic task: `why` callout → SVG before/after diagram → per-commit `File | What | Why` tables.
|
||
- Footer: deploy-day notes, trash/retirement pending approvals.
|
||
- CSS: only theme vars (`--fg --muted --surface --border --accent --success --error --c1..--c6`) with a `prefers-color-scheme: dark` block; SVGs style via `currentColor`/vars; no external assets, no scripts.
|
||
|
||
## 5. Validate before opening
|
||
Python `html.parser` pass: tag stack empty, zero mismatches (treat `path rect circle line marker` + void HTML tags as self-closing); assert every nav anchor id exists; print table/figure counts. Then:
|
||
```
|
||
xdg-open "file:///home/blank/reports/<file>.html"
|
||
```
|
||
`xdg-open` may block in foreground — background it, don't poll.
|