Add source linter, negative test fixtures, and fallback guidance

- scripts/lint.py: reject raw rectangles, absolute coordinates, hue-budget
  and callout/group/formula-order violations at the source level
- tests/invalid/ + tests/lint-invalid/: negative fixtures proving the
  package and linter reject bad input; test.sh now runs both directions
- references/fallback.md: degraded path when no LaTeX is available
- tests/group-callout.tex: exercise \stgroup and \stcallout
- agents/openai.yaml: agent config
- Docs and .sty updated to match
This commit is contained in:
dela
2026-08-05 16:41:22 +08:00
parent 7b59c81d02
commit 866173a831
34 changed files with 786 additions and 54 deletions
+9 -7
View File
@@ -18,8 +18,8 @@ A figure built from raw TikZ has to re-earn every invariant by hand and usually
## Workflow
1. **Preflight.** `./scripts/preflight.sh`. Exit 0 = TikZ+CJK path. Exit 1 = degraded
(say so in the delivery). Exit 2 = no LaTeX; fall back to SVG/matplotlib and say
explicitly that the figure is not TikZ.
(say so in the delivery). Exit 2 = no LaTeX; read `references/fallback.md` before
falling back and state explicitly which package guarantees are unavailable.
2. **Reduce** the input to one primary computation path. Drop equivalent objectives,
diagnostics, and secondary metrics unless asked for.
3. **Build two ledgers** before drawing anything:
@@ -33,9 +33,9 @@ A figure built from raw TikZ has to re-earn every invariant by hand and usually
flow layout — `\ststage` / `\strow` … `\strowend`, empty coordinate arguments, gaps
declared once. Reach for an absolute coordinate only when no band can express the
placement. See `references/api.md` and `references/layout.md`.
5. **Build and audit.** `./scripts/build.sh fig.tex`. A clean build only proves TeX was
happy; then run the visual audit in `references/checklist.md` against the PNG at full
size and at thumbnail size. Redraw on any mandatory-invariant violation.
5. **Build and audit.** `./scripts/build.sh fig.tex` runs the source linter, TeX checks and
exports. Then run the remaining visual/semantic audit in `references/checklist.md`
against the PNG at full size and thumbnail size. Redraw on any mandatory violation.
For code input, trace the concrete `matmul`, `einsum`, `reshape/view`, `transpose/permute`,
concat, broadcast, and collective calls. Keep code variable names where useful; state any
@@ -51,6 +51,8 @@ shape or convention you inferred.
| discrete choices (indices, token ids, expert ids) | symbols in cells, no ramp | `\stindexface` |
| data movement, collectives, non-linear ops | arrows and nodes | `\stlink`, `\stcomm` |
| a split along the contracted axis | a vertical pair inside one band slot | `\stcol` … `\stcolend` |
| adjacent objects that are one composite (heads of `q`, shards of `W`) | an outline in their own role hue | `\stgroup` … `\stgroupend` |
| an aside about a whole band | a side card off its right edge, one per band | `\stcallout` |
Combine grammars only when each one adds information. Known zeros stay unfilled; masks,
diagonals, sparsity and partitions must encode their exact structure.
@@ -86,8 +88,8 @@ and the `.tex` source plus vector artifact.
select an OS-specific CJK font unless the user asks and accepts the portability cost.
- **English figures:** `\usepackage[en]{supertensor}` — same geometry, English rail labels.
- Keep math in LaTeX, not raw Unicode.
- The identification line is `\stsignature{<subject>}{<box>}`; it renders
`<subject>@五道口纳什`. Change the handle with `\stsetauthor{...}` only when asked.
- Add `\stsignature{<subject>}{<box>}` only when the user or house template asks for an
identification line. It renders only the subject, with no author or handle.
## Iterating