# 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:

```yaml
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)