fix(explain-diff): arrow class no longer collides with edge callout; bundle fill_template.py
Eval iteration 1: the callout 'edge' variant picked up the diagram connector styles, and all three skill runs hand-wrote a template filler. fill_template.py takes values.json with @fragment files, escapes </ in the quiz; suite 21 checks.
This commit is contained in:
1 parent
b353fac2ba
commit
faedb98699
5 files changed
+112
-19
No files matched your search
@@ -97,5 +97,30 @@ out=$(python3 "$CHECK" "$D-dash.html")
|
||||
check T15-fail-line-names-check "$(printf '%s\n' "$out" \
|
||||
| grep -c '^FAIL em-dash:')" 1
|
||||
|
||||
# fill_template.py: a valid values file builds a page the checker passes;
|
||||
# a missing placeholder is refused (rc 1).
|
||||
FILL="$SKILL/scripts/fill_template.py"
|
||||
python3 -I - "$SKILL/assets/template.html" "$WORK/values.json" <<'PY'
|
||||
import json, re, sys
|
||||
keys = set(re.findall(r"\{\{([A-Z_]+)\}\}", open(sys.argv[1]).read()))
|
||||
values = {k: "x" for k in keys}
|
||||
values.update(LANG="en", BACKGROUND_BODY="@bg.html", QUIZ_JSON=[
|
||||
{"q": "Q?", "options": [
|
||||
{"text": "a", "correct": True, "why": "yes </script>"},
|
||||
{"text": "b", "correct": False, "why": "no"},
|
||||
{"text": "c", "correct": False, "why": "no"}]}] * 5)
|
||||
json.dump(values, open(sys.argv[2], "w"))
|
||||
PY
|
||||
echo '<p>Fragment.</p>' > "$WORK/bg.html"
|
||||
python3 "$FILL" "$WORK/values.json" "$D-filled.html" >/dev/null
|
||||
check T16-filled-page-passes "$(rc "$D-filled.html")" 0
|
||||
check T17-fragment-inlined "$(grep -c '<p>Fragment.</p>' "$D-filled.html")" 1
|
||||
check T18-script-close-escaped "$(grep -c 'yes </script>' "$D-filled.html")" 0
|
||||
python3 -I -c 'import json, sys
|
||||
d = json.load(open(sys.argv[1])); d.pop("LANG")
|
||||
json.dump(d, open(sys.argv[2], "w"))' "$WORK/values.json" "$WORK/bad.json"
|
||||
python3 "$FILL" "$WORK/bad.json" "$D-bad.html" >/dev/null 2>&1
|
||||
check T19-missing-placeholder-refused "$?" 1
|
||||
|
||||
printf 'explain-diff checker: %d pass, %d fail\n' "$pass" "$fail"
|
||||
[ "$fail" -eq 0 ]
|
||||
@@ -113,11 +113,18 @@ less than three styled boxes.
|
||||
|
||||
The skill folder is `$HOME/.claude/skills/explain-diff/`.
|
||||
|
||||
1. Read `references/components.md` (the snippet catalog), then start from
|
||||
a copy of `assets/template.html`.
|
||||
2. Replace every `{{…}}` placeholder. Section ids stay `background`,
|
||||
`intuition`, `code` and `quiz`: the table of contents and the checker
|
||||
rely on them.
|
||||
1. Read `references/components.md` (the snippet catalog) and the
|
||||
placeholders of `assets/template.html`.
|
||||
2. Write each section body as its own HTML fragment file, the quiz as a
|
||||
JSON list, and a `values.json` mapping every placeholder to its text or
|
||||
to `@<fragment file>`. Keep these working files in a temporary folder,
|
||||
never in the repo. Then build the page:
|
||||
```bash
|
||||
python3 "$HOME/.claude/skills/explain-diff/scripts/fill_template.py" values.json <file>
|
||||
```
|
||||
It refuses a missing or unknown placeholder. Section ids stay
|
||||
`background`, `intuition`, `code` and `quiz`: the table of contents and
|
||||
the checker rely on them.
|
||||
3. Code goes in `<pre>` blocks, HTML-escaped (`<` as `<`, `>` as `>`,
|
||||
`&` as `&`). An unescaped `<T>` generic or JSX tag silently swallows
|
||||
the code that follows it.
|
||||
|
||||
@@ -200,7 +200,7 @@ details.deep[open] > summary {
|
||||
border-bottom: 1px solid var(--line);
|
||||
}
|
||||
|
||||
/* Diagrams: flow and states */
|
||||
/* Diagrams: flow and states (.arrow links two nodes) */
|
||||
.flow { display: flex; align-items: stretch; }
|
||||
.node {
|
||||
flex: 1 1 0;
|
||||
@@ -215,17 +215,17 @@ details.deep[open] > summary {
|
||||
.node.state { border-radius: 999px; text-align: center; }
|
||||
.node-title { display: block; font-weight: 650; }
|
||||
.node-sub { display: block; font-size: 0.82rem; color: var(--muted); }
|
||||
.edge {
|
||||
.arrow {
|
||||
position: relative;
|
||||
flex: 0 0 7rem;
|
||||
flex: 0 0 9rem;
|
||||
align-self: center;
|
||||
padding: 0 0.6rem 0.7rem;
|
||||
font: 0.75rem/1.3 var(--mono);
|
||||
color: var(--muted);
|
||||
text-align: center;
|
||||
overflow-wrap: anywhere;
|
||||
overflow-wrap: break-word;
|
||||
}
|
||||
.edge::before {
|
||||
.arrow::before {
|
||||
content: "";
|
||||
position: absolute;
|
||||
left: 0.3rem;
|
||||
@@ -233,7 +233,7 @@ details.deep[open] > summary {
|
||||
bottom: 0.3rem;
|
||||
border-top: 1.5px solid var(--muted);
|
||||
}
|
||||
.edge::after {
|
||||
.arrow::after {
|
||||
content: "";
|
||||
position: absolute;
|
||||
right: 0.3rem;
|
||||
@@ -360,13 +360,13 @@ table.data th { font-weight: 650; color: var(--muted); }
|
||||
h2 { margin-top: 3.5rem; }
|
||||
.compare { grid-template-columns: 1fr; }
|
||||
.flow { flex-direction: column; }
|
||||
.edge {
|
||||
.arrow {
|
||||
flex-basis: auto;
|
||||
align-self: flex-start;
|
||||
padding: 0.55rem 0 0.75rem 1.5rem;
|
||||
text-align: left;
|
||||
}
|
||||
.edge::before {
|
||||
.arrow::before {
|
||||
top: 0;
|
||||
bottom: 0.2rem;
|
||||
left: 0.65rem;
|
||||
@@ -374,7 +374,7 @@ table.data th { font-weight: 650; color: var(--muted); }
|
||||
border-top: 0;
|
||||
border-left: 1.5px solid var(--muted);
|
||||
}
|
||||
.edge::after {
|
||||
.arrow::after {
|
||||
right: auto;
|
||||
bottom: 0;
|
||||
left: calc(0.65rem - 4.25px);
|
||||
|
||||
@@ -39,7 +39,7 @@ worth remembering), `risk` (what can still go wrong, or a follow-up).
|
||||
|
||||
## Flow of components
|
||||
|
||||
Nodes left to right, an edge between each pair. The edge label carries the
|
||||
Nodes left to right, an `arrow` between each pair. Its label carries the
|
||||
example data that travels (a call, a payload, a return value). `hl` marks
|
||||
the component the change touches. On a phone the flow turns vertical.
|
||||
|
||||
@@ -48,10 +48,10 @@ the component the change touches. On a phone the flow turns vertical.
|
||||
<div class="flow">
|
||||
<div class="node"><span class="node-title">Browser</span>
|
||||
<span class="node-sub">guest g-42, no session</span></div>
|
||||
<div class="edge">ensureGuest()</div>
|
||||
<div class="arrow">ensureGuest()</div>
|
||||
<div class="node hl"><span class="node-title">fetchHint</span>
|
||||
<span class="node-sub">new: session first</span></div>
|
||||
<div class="edge">rpc hint(day=12)</div>
|
||||
<div class="arrow">rpc hint(day=12)</div>
|
||||
<div class="node"><span class="node-title">Database</span>
|
||||
<span class="node-sub">auth-gated RPC</span></div>
|
||||
</div>
|
||||
@@ -60,7 +60,7 @@ the component the change touches. On a phone the flow turns vertical.
|
||||
</figure>
|
||||
```
|
||||
|
||||
A return value travels back through the label of the same edge
|
||||
A return value travels back through the label of the same arrow
|
||||
(`hint(day=12) → "starts with B"`) or through a second flow below.
|
||||
|
||||
## Row of states
|
||||
@@ -70,7 +70,7 @@ Same markup with `state` nodes; `hl` marks the state the change adds.
|
||||
```html
|
||||
<div class="flow">
|
||||
<div class="node state"><span class="node-title">running</span></div>
|
||||
<div class="edge">crash ×3</div>
|
||||
<div class="arrow">crash ×3</div>
|
||||
<div class="node state hl"><span class="node-title">stopped</span>
|
||||
<span class="node-sub">new: final</span></div>
|
||||
</div>
|
||||
|
||||
Executable
+61
@@ -0,0 +1,61 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Fill the explain-diff template: fill_template.py <values.json> <out.html>.
|
||||
|
||||
values.json maps each placeholder name (without braces) to its content.
|
||||
A value starting with "@" names a file whose content is used instead, so
|
||||
long HTML bodies can live in their own fragment files. QUIZ_JSON may be a
|
||||
JSON list: it is serialised here, with "</" escaped for the script block.
|
||||
Exit 1 when a placeholder is missing or unknown.
|
||||
"""
|
||||
import json
|
||||
import re
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
TEMPLATE = Path(__file__).resolve().parent.parent / "assets/template.html"
|
||||
PLACEHOLDER = re.compile(r"\{\{([A-Z_]+)\}\}")
|
||||
|
||||
|
||||
def resolve(value, base):
|
||||
if isinstance(value, str) and value.startswith("@"):
|
||||
return (base / value[1:]).read_text(encoding="utf-8")
|
||||
return value
|
||||
|
||||
|
||||
def quiz_text(value):
|
||||
if isinstance(value, str):
|
||||
value = json.loads(value)
|
||||
return json.dumps(value, ensure_ascii=False, indent=1).replace(
|
||||
"</", "<\\/")
|
||||
|
||||
|
||||
def fill(template, values):
|
||||
wanted = set(PLACEHOLDER.findall(template))
|
||||
missing, unknown = wanted - set(values), set(values) - wanted
|
||||
if missing or unknown:
|
||||
raise KeyError(f"missing: {sorted(missing)}, "
|
||||
f"unknown: {sorted(unknown)}")
|
||||
return PLACEHOLDER.sub(lambda m: values[m.group(1)], template)
|
||||
|
||||
|
||||
def main(argv):
|
||||
if len(argv) != 3:
|
||||
print(__doc__.strip())
|
||||
return 2
|
||||
values_path = Path(argv[1]).expanduser()
|
||||
raw = json.loads(values_path.read_text(encoding="utf-8"))
|
||||
values = {k: resolve(v, values_path.parent) for k, v in raw.items()}
|
||||
if "QUIZ_JSON" in values:
|
||||
values["QUIZ_JSON"] = quiz_text(values["QUIZ_JSON"])
|
||||
try:
|
||||
page = fill(TEMPLATE.read_text(encoding="utf-8"), values)
|
||||
except KeyError as err:
|
||||
print(f"ERROR {err}")
|
||||
return 1
|
||||
Path(argv[2]).expanduser().write_text(page, encoding="utf-8")
|
||||
print(f"wrote {argv[2]}")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main(sys.argv))
|
||||
Reference in new issue
Block a user