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" \
|
check T15-fail-line-names-check "$(printf '%s\n' "$out" \
|
||||||
| grep -c '^FAIL em-dash:')" 1
|
| 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"
|
printf 'explain-diff checker: %d pass, %d fail\n' "$pass" "$fail"
|
||||||
[ "$fail" -eq 0 ]
|
[ "$fail" -eq 0 ]
|
||||||
@@ -113,11 +113,18 @@ less than three styled boxes.
|
|||||||
|
|
||||||
The skill folder is `$HOME/.claude/skills/explain-diff/`.
|
The skill folder is `$HOME/.claude/skills/explain-diff/`.
|
||||||
|
|
||||||
1. Read `references/components.md` (the snippet catalog), then start from
|
1. Read `references/components.md` (the snippet catalog) and the
|
||||||
a copy of `assets/template.html`.
|
placeholders of `assets/template.html`.
|
||||||
2. Replace every `{{…}}` placeholder. Section ids stay `background`,
|
2. Write each section body as its own HTML fragment file, the quiz as a
|
||||||
`intuition`, `code` and `quiz`: the table of contents and the checker
|
JSON list, and a `values.json` mapping every placeholder to its text or
|
||||||
rely on them.
|
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 `>`,
|
3. Code goes in `<pre>` blocks, HTML-escaped (`<` as `<`, `>` as `>`,
|
||||||
`&` as `&`). An unescaped `<T>` generic or JSX tag silently swallows
|
`&` as `&`). An unescaped `<T>` generic or JSX tag silently swallows
|
||||||
the code that follows it.
|
the code that follows it.
|
||||||
|
|||||||
@@ -200,7 +200,7 @@ details.deep[open] > summary {
|
|||||||
border-bottom: 1px solid var(--line);
|
border-bottom: 1px solid var(--line);
|
||||||
}
|
}
|
||||||
|
|
||||||
/* Diagrams: flow and states */
|
/* Diagrams: flow and states (.arrow links two nodes) */
|
||||||
.flow { display: flex; align-items: stretch; }
|
.flow { display: flex; align-items: stretch; }
|
||||||
.node {
|
.node {
|
||||||
flex: 1 1 0;
|
flex: 1 1 0;
|
||||||
@@ -215,17 +215,17 @@ details.deep[open] > summary {
|
|||||||
.node.state { border-radius: 999px; text-align: center; }
|
.node.state { border-radius: 999px; text-align: center; }
|
||||||
.node-title { display: block; font-weight: 650; }
|
.node-title { display: block; font-weight: 650; }
|
||||||
.node-sub { display: block; font-size: 0.82rem; color: var(--muted); }
|
.node-sub { display: block; font-size: 0.82rem; color: var(--muted); }
|
||||||
.edge {
|
.arrow {
|
||||||
position: relative;
|
position: relative;
|
||||||
flex: 0 0 7rem;
|
flex: 0 0 9rem;
|
||||||
align-self: center;
|
align-self: center;
|
||||||
padding: 0 0.6rem 0.7rem;
|
padding: 0 0.6rem 0.7rem;
|
||||||
font: 0.75rem/1.3 var(--mono);
|
font: 0.75rem/1.3 var(--mono);
|
||||||
color: var(--muted);
|
color: var(--muted);
|
||||||
text-align: center;
|
text-align: center;
|
||||||
overflow-wrap: anywhere;
|
overflow-wrap: break-word;
|
||||||
}
|
}
|
||||||
.edge::before {
|
.arrow::before {
|
||||||
content: "";
|
content: "";
|
||||||
position: absolute;
|
position: absolute;
|
||||||
left: 0.3rem;
|
left: 0.3rem;
|
||||||
@@ -233,7 +233,7 @@ details.deep[open] > summary {
|
|||||||
bottom: 0.3rem;
|
bottom: 0.3rem;
|
||||||
border-top: 1.5px solid var(--muted);
|
border-top: 1.5px solid var(--muted);
|
||||||
}
|
}
|
||||||
.edge::after {
|
.arrow::after {
|
||||||
content: "";
|
content: "";
|
||||||
position: absolute;
|
position: absolute;
|
||||||
right: 0.3rem;
|
right: 0.3rem;
|
||||||
@@ -360,13 +360,13 @@ table.data th { font-weight: 650; color: var(--muted); }
|
|||||||
h2 { margin-top: 3.5rem; }
|
h2 { margin-top: 3.5rem; }
|
||||||
.compare { grid-template-columns: 1fr; }
|
.compare { grid-template-columns: 1fr; }
|
||||||
.flow { flex-direction: column; }
|
.flow { flex-direction: column; }
|
||||||
.edge {
|
.arrow {
|
||||||
flex-basis: auto;
|
flex-basis: auto;
|
||||||
align-self: flex-start;
|
align-self: flex-start;
|
||||||
padding: 0.55rem 0 0.75rem 1.5rem;
|
padding: 0.55rem 0 0.75rem 1.5rem;
|
||||||
text-align: left;
|
text-align: left;
|
||||||
}
|
}
|
||||||
.edge::before {
|
.arrow::before {
|
||||||
top: 0;
|
top: 0;
|
||||||
bottom: 0.2rem;
|
bottom: 0.2rem;
|
||||||
left: 0.65rem;
|
left: 0.65rem;
|
||||||
@@ -374,7 +374,7 @@ table.data th { font-weight: 650; color: var(--muted); }
|
|||||||
border-top: 0;
|
border-top: 0;
|
||||||
border-left: 1.5px solid var(--muted);
|
border-left: 1.5px solid var(--muted);
|
||||||
}
|
}
|
||||||
.edge::after {
|
.arrow::after {
|
||||||
right: auto;
|
right: auto;
|
||||||
bottom: 0;
|
bottom: 0;
|
||||||
left: calc(0.65rem - 4.25px);
|
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
|
## 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
|
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.
|
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="flow">
|
||||||
<div class="node"><span class="node-title">Browser</span>
|
<div class="node"><span class="node-title">Browser</span>
|
||||||
<span class="node-sub">guest g-42, no session</span></div>
|
<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>
|
<div class="node hl"><span class="node-title">fetchHint</span>
|
||||||
<span class="node-sub">new: session first</span></div>
|
<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>
|
<div class="node"><span class="node-title">Database</span>
|
||||||
<span class="node-sub">auth-gated RPC</span></div>
|
<span class="node-sub">auth-gated RPC</span></div>
|
||||||
</div>
|
</div>
|
||||||
@@ -60,7 +60,7 @@ the component the change touches. On a phone the flow turns vertical.
|
|||||||
</figure>
|
</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.
|
(`hint(day=12) → "starts with B"`) or through a second flow below.
|
||||||
|
|
||||||
## Row of states
|
## Row of states
|
||||||
@@ -70,7 +70,7 @@ Same markup with `state` nodes; `hl` marks the state the change adds.
|
|||||||
```html
|
```html
|
||||||
<div class="flow">
|
<div class="flow">
|
||||||
<div class="node state"><span class="node-title">running</span></div>
|
<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>
|
<div class="node state hl"><span class="node-title">stopped</span>
|
||||||
<span class="node-sub">new: final</span></div>
|
<span class="node-sub">new: final</span></div>
|
||||||
</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