iftypeset/spec/examples

Examples

Rules stay compact and machine-enforceable; examples live separately to avoid bloating the rule registry.

Goals

• Provide concrete fixtures for:

  • unit tests (lint, autofix, typeset transforms)
  • integration tests (render + QA gates)
  • documentation (human-readable “why this matters”)

• Keep examples small (a few lines) and targeted (each example triggers a known set of rules).

Example ID format

EX.<CATEGORY>.<TOPIC>.<NNN>

• CATEGORY must match the category taxonomy (e.g., PUNCTUATION, NUMBERS, CITATIONS)
• TOPIC is an uppercase short slug
• NNN is a zero-padded integer (000–999+)

Example:

• EX.PUNCTUATION.DASHES.001

Suggested on-disk layout

• spec/examples/<category>/EX.<CATEGORY>.<TOPIC>.<NNN>.yaml
• spec/examples/<category>/fixtures/<name>.md (optional)

Example YAML format (recommended)

Fields:

• id (required): example ID
• rules (required): list of rule IDs the example is meant to exercise
• before (required): inline Markdown or a reference to a fixture file
• after (optional): expected Markdown after autofix (if autofix exists)
• expected (optional): expected diagnostics/gates
  • lint_errors: array of rule IDs expected as errors
  • lint_warnings: array of rule IDs expected as warnings
  • qa_failures: array of gate keys expected to fail
• notes (optional): short human explanation (no book quotes)

Minimal example skeleton:

id: EX.PUNCTUATION.DASHES.001
rules:
  - CMOS.PUNCTUATION.DASHES.EM_DASH
before: |
  ...
after: |
  ...
expected:
  lint_errors:
    - CMOS.PUNCTUATION.DASHES.EM_DASH

Test corpus strategy

Maintain a small, curated corpus that triggers:

1. Lint-only issues (AST-level)

   • punctuation spacing
   • numeral formatting
   • heading numbering patterns
   • link normalization / unsafe URLs
   • citation field completeness

2. Typeset-only issues (token/CSS decisions)

   • paragraph indentation patterns
   • code block wrapping rules
   • table overflow strategies

3. Post-render QA issues (PDF/HTML layout)

   • widows/orphans
   • stranded headings (keep-with-next)
   • overfull lines (especially monospace/code)
   • table/caption overflow and clipping
   • link wrap incidents (URLs/DOIs split against policy)

Recommended corpus sizing:

• 30–80 fixtures total
• each fixture should target 3–10 rules max
• include “degraded mode” fixtures (intentionally malformed Markdown)