dannystocker/iftypeset
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
iftypeset/docs/10-project-brief.md
codex e92f1c3b93
Some checks are pending
ci / ci (push) Waiting to run
Details
iftypeset: document CI pipeline + Playwright + font contract
2026-01-08 18:10:41 +00:00

3 KiB
Raw Export PDF Blame History

iftypeset — Project Brief (downloadable)

What This Is

iftypeset is a deterministic Markdown → HTML → PDF pipeline with:

  • A machine-readable rule registry (Chicago/Bringhurst-backed pointers; paraphrased rules only)
  • Profiles that map typographic intent → rendering tokens (spec/profiles/*.yaml)
  • QA gates that fail builds when layout degrades (spec/quality_gates.yaml)

The wedge is not “perfect typography by AI”. The wedge is CI for document quality: measurable, reproducible, auditable.

Non‑Negotiables

  • No bulk OCR/transcription of Chicago/Bringhurst into the repo (copyright).
  • Rules are paraphrases with pointer refs (e.g., CMOS18 §X.Y pNN (scan pMM)).
  • If a rule cannot be automated safely, it must be tagged manual_checklist=true and emitted in out/manual-checklist.md.

Where We Are (2026‑01‑03 snapshot)

Verified via ./scripts/ci.sh (validate-spec + report + tests):

  • CLI: validate-spec, report, lint, render-html, render-pdf, qa, emit-css
  • Deterministic lint with safe rewrite mode (lint --fix --fix-mode rewrite)
  • Deterministic HTML rendering; PDF rendering works when an engine is available
  • QA (HTML-based v0) with incident details:
    • bare URL/DOI/email wrap risk
    • overfull token detection
    • table/code overflow (profile-aware thresholds)
  • Forgejo CI workflow: .forgejo/workflows/ci.yml
  • Session resilience tooling:
    • ./scripts/audit.sh, ./scripts/resume.sh, ./scripts/checkpoint.sh
    • checkpoints tracked in docs/CHECKPOINTS.md

Rule registry snapshot (from out/coverage-report.json):

  • Total rules: 524
  • Enforced: 145 (lint + typeset + postrender)
  • Manual: 379

The repo also emits a “trust contract” describing what is enforced vs manual:

  • out/trust-contract.md
  • out/trust-contract.json

What’s Next (priority order)

  1. Make QA less “HTML heuristic” and more layout-aware

    • Add at least one truly page-aware detector (widows/orphans or stranded headings) with measurable thresholds.

  2. Increase enforced coverage where it reduces real PDF pain

    • citations normalization variants
    • link/DOI handling + wrap policy
    • table/code overflow strategies

  3. Forgejo integration

    • run iftypeset as a PDF export/typeset worker
    • attach QA artifacts to exports

  4. Expand rule batches

    • continue adding pointer-backed rules for remaining categories (figures, front/back matter, etc.)
    • promote high-confidence rules from manual → lint/typeset/postrender incrementally

Quick Commands

From repo root:

  • Resume sanity snapshot: ./scripts/resume.sh
  • CI sanity: ./scripts/ci.sh
  • Portable restore point: ./scripts/checkpoint.sh "note"

Canonical “single source of truth” docs

  • docs/09-project-status.md (most current, short + factual)
  • docs/06-project-overview.md (narrative overview)
  • docs/05-external-evaluation-prompt.md (external review prompt)
  • docs/07-session-resilience.md (how to avoid “lost work”)
  • docs/CHECKPOINTS.md (restore points)