feat(docs): ODF reference docs, and a lint that reads documents #121

Merged

peterswimm merged 1 commit from feat/udg-odf-document-product into main

2026-09-10 20:50:02 +00:00

peterswimm commented

2026-09-10 20:16:22 +00:00

Owner

Makes the native document pipeline UDG-aware: proposals and SOWs now build on-brand from tokens instead of from stock pandoc or a one-off design tool.

Scope

udg/generators/docs.py — ODF writer: reference.odt (pandoc --reference-doc), template.ott, proposal.odt for every product. Fixes _type_scale, which read a non-existent type tier and returned {}.
tools/doc_build.py + just doc <src.md> — markdown → branded ODT; YAML front matter (title, short-title, doc-number, classification, date, org) fills the running header/footer; images clamped to the page measure.
udg/generators/align_check.py + just doc-lint <path> — font audit beside the hex audit, scan / scan-strict for documents that live outside the repo, UDG:BEGIN/END generated-block skip, and the fragment-reference false positive in _HEX fixed. Deliberately not added to just check — see Impact.
dist/ — regenerated: 39 new ODF files; DOCX/DOTX/PDF/SVG changed by the _type_scale fix.

Testing

Rebased onto origin/main (0336756); resolved align_check.py against 1a532e5, keeping its worktree-safe sibling lookup, its "NOT AUDITED" wording and its native-must-run gate. docs.py build --all on the new base changes 0 dist/ files.
just check exit 0; pytest all pass (incl. test_word_builder).
docs.py build --all run twice → byte-identical ODF; docs.py check --all passes.
soffice --headless --convert-to pdf accepts reference.odt and proposal.odt — the real test of ODF packaging.
pandoc on the same markdown with vs without --reference-doc: styles.xml goes from Arial/Courier, a relative H1 and no header → Sora/DM Mono, a token-derived H1 and a running header. A reference doc that is silently ignored would otherwise look like success.
doc_build.py leaves dist/ byte-identical (hashed before and after).
doc-lint on the original sales HTML: 120 findings, exit 1. On the re-tokened pages: 0, exit 0.
_HEX cases: url(#add), href="#fade", xlink:href='#bead' are not matched; real colour literals still are.

Impact Statement

Every product's DOCX/DOTX headings change size (previously all body-sized) and the token sheets gain the type scale — intended, from the _type_scale fix.
just check membership is unchanged. 1a532e5 made align_check.py check fail when no Toilville_Rituals sibling is checked out, and CI's checkout has none (only udg-copy-coverage and udg-native-sync clone it). Wiring it into just check would fail any clone without the sibling for reasons unrelated to its change. Documents gate through just doc-lint, which needs no sibling.
No token source changes. Companion spel PR #562 (migration 20260910_1700) adds the matching design-canon rules and widens the guidance query that could only see apps-rituals.

Makes the native document pipeline UDG-aware: proposals and SOWs now build on-brand from tokens instead of from stock pandoc or a one-off design tool. ## Scope - `udg/generators/docs.py` — ODF writer: `reference.odt` (pandoc `--reference-doc`), `template.ott`, `proposal.odt` for every product. Fixes `_type_scale`, which read a non-existent `type` tier and returned `{}`. - `tools/doc_build.py` + `just doc <src.md>` — markdown → branded ODT; YAML front matter (`title`, `short-title`, `doc-number`, `classification`, `date`, `org`) fills the running header/footer; images clamped to the page measure. - `udg/generators/align_check.py` + `just doc-lint <path>` — font audit beside the hex audit, `scan` / `scan-strict` for documents that live outside the repo, `UDG:BEGIN/END` generated-block skip, and the fragment-reference false positive in `_HEX` fixed. Deliberately **not** added to `just check` — see Impact. - `dist/` — regenerated: 39 new ODF files; DOCX/DOTX/PDF/SVG changed by the `_type_scale` fix. ## Testing - Rebased onto `origin/main` (`0336756`); resolved `align_check.py` against `1a532e5`, keeping its worktree-safe sibling lookup, its "NOT AUDITED" wording and its native-must-run gate. `docs.py build --all` on the new base changes 0 `dist/` files. - `just check` exit 0; `pytest` all pass (incl. `test_word_builder`). - `docs.py build --all` run twice → byte-identical ODF; `docs.py check --all` passes. - `soffice --headless --convert-to pdf` accepts `reference.odt` and `proposal.odt` — the real test of ODF packaging. - pandoc on the same markdown with vs without `--reference-doc`: `styles.xml` goes from Arial/Courier, a relative H1 and no header → Sora/DM Mono, a token-derived H1 and a running header. A reference doc that is silently ignored would otherwise look like success. - `doc_build.py` leaves `dist/` byte-identical (hashed before and after). - `doc-lint` on the original sales HTML: 120 findings, exit 1. On the re-tokened pages: 0, exit 0. - `_HEX` cases: `url(#add)`, `href="#fade"`, `xlink:href='#bead'` are not matched; real colour literals still are. ## Impact Statement - Every product's DOCX/DOTX headings change size (previously all body-sized) and the token sheets gain the type scale — intended, from the `_type_scale` fix. - `just check` membership is unchanged. `1a532e5` made `align_check.py check` fail when no `Toilville_Rituals` sibling is checked out, and CI's checkout has none (only `udg-copy-coverage` and `udg-native-sync` clone it). Wiring it into `just check` would fail any clone without the sibling for reasons unrelated to its change. Documents gate through `just doc-lint`, which needs no sibling. - No token source changes. Companion spel PR #562 (migration `20260910_1700`) adds the matching design-canon rules and widens the guidance query that could only see `apps-rituals`.

peterswimm added 1 commit

2026-09-10 20:16:22 +00:00

feat(docs): ODF reference docs, and a lint that reads documents

PR policy check / policy-gate (pull_request) Successful in 1s

Details

Security Scans / Gitleaks secret scan (pull_request) Successful in 31s

Details

Security Scans / Trivy filesystem scan (pull_request) Successful in 32s

Details

UDG dist drift gate / dist/ matches dtcg + udg sources (pull_request) Successful in 16s

Details

Test Generator / lint-prose (pull_request) Successful in 20s

Details

Test Generator / test (pull_request) Failing after 52s

Details

Test Generator / lint-workflows (pull_request) Successful in 21s

Details

Copy coverage / Design copy reaching rendered HTML (pull_request) Failing after 24s

Details

2eff4d18b9

The document pipeline could hash a generated file but never look inside
one, and it had no ODF output — so a proposal built with bare pandoc
shipped in Times and Arial with no running header.

docs.py
- ODF writer: reference.odt (pandoc --reference-doc), template.ott and
  proposal.odt for every product. mimetype is written first and STORED;
  _zip_package sorts and deflates every member, which LibreOffice rejects.
- Styles carry the names pandoc looks up (Heading_20_1, Text_20_body …);
  any other name is silently ignored and the output stays unstyled.
- Print type ramp: body at its token size, only the distance above it
  compressed (0.55), so h1 is ~2x body on paper rather than 3x.
- Fix: _type_scale read a tier named "type"; it is "typography". It
  returned {}, so every DOCX heading rendered at body size and the token
  sheets had no type scale. That is most of the dist/ churn here.

tools/doc_build.py (just doc)
- Stamps header/footer from YAML front matter onto a throwaway copy of
  reference.odt, so dist/ stays byte-deterministic for the drift gate.
- Clamps images to the page measure: pandoc writes pixel counts as
  points (932px becomes 12.9in on a 6.5in measure).

align_check.py (just doc-lint <path>)
- Font audit beside the hex audit; scan / scan-strict for documents that
  live outside the repo; UDG:BEGIN/END generated blocks skipped.
- _HEX no longer matches url(#id) or href="#id" fragment references.
- Rebased onto 1a532e5, which made `check` fail when the Toilville_Rituals
  sibling is absent. CI's checkout has no sibling, so align_check stays
  out of `just check`; documents gate through scan-strict, which needs
  none. The font audit reports the 5 pre-existing Inter/Arial
  declarations in atahualpa-tctd without failing on them.

peterswimm merged commit 9bdcf4acc2 into main

2026-09-10 20:50:02 +00:00

peterswimm deleted branch feat/udg-odf-document-product

2026-09-10 20:50:02 +00:00

peterswimm referenced this pull request from a commit

2026-09-10 20:50:03 +00:00

Merge pull request 'feat(docs): ODF reference docs, and a lint that reads documents' (#121) from feat/udg-odf-document-product into main

peterswimm referenced this pull request

2026-09-11 18:05:57 +00:00

feat(docs): an HTML target, so one source feeds the ODT and the artifact pages #124