Lint reStructuredText prose with Vale to ban em dashes

[adamtheturtle]

Adds Vale as a pre-commit hook so em dashes cannot creep into our reStructuredText.

The rules come from the pinned ClearProse style package (v1.1.0) rather than a hand-written local rule, configured in a new .vale.ini; vale sync downloads it into a gitignored styles/ directory before the lint runs. That release ships as a Vale config package, so it carries the TokenIgnores pattern that keeps Sphinx role targets such as :ref: out of the prose check, and this repository does not configure that itself. vale==3.13.0.0 is pinned in the dev extra, and .vale.ini is added to the check-manifest ignores.

Verified locally: existing .rst files pass, a seeded em dash fails with ClearProse.NoEmDash while a :ref: target containing one does not, and the full prek run --all-files plus check-manifest pass.

Note that the vale PyPI wrapper is behind the upstream binary (3.13.0 against 3.17.1), and 3.13.0 drops the occasional alert: on the ClearProse fixture with seven em dashes it reports six, where 3.17.1 reports all seven. The ban still holds, because a file with an em dash is still reported, but the pin is worth bumping when the wrapper publishes a newer Vale.

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation and developer-tooling only; no production code, auth, or data-path changes.

Overview
Adds Vale to pre-commit so reStructuredText prose is checked against the pinned ClearProse package (v1.1.0 in .vale.ini), including rules such as banning em dashes.

A vale sync hook runs before vale on .rst files; synced styles land in a gitignored styles/ directory. vale==3.13.0.0 is added to the dev extra, and .vale.ini is listed in check-manifest ignores so release checks stay green.

^{Reviewed by Cursor Bugbot for commit e307e5d. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit e307e5d. Configure here.}

[cursor]

Sphinx roles lack TokenIgnores

Medium Severity

The [*.rst] section no longer sets TokenIgnores, so Vale can treat Sphinx inline role targets (for example :file: and :doc:) as prose. Docutils still renders those arguments as normal text when parsing reStructuredText, which can trigger ClearProse errors on non-prose strings such as paths and doc names.

 

^{Reviewed by Cursor Bugbot for commit e307e5d. Configure here.}

[adamtheturtle]

Not a defect, so no change made.

TokenIgnores moved rather than disappeared. ClearProse 1.1.0 ships as a Vale config package, so vale sync installs the pattern to styles/.vale-config/0-ClearProse.ini, which Vale reads before this project's own .vale.ini. Verified on this branch:

$ uv run --extra=dev vale ls-config | jq .TokenIgnores
{
  "*.rst": [
    "(:\\w+:`[^`]*`)"
  ]
}

The pattern matches any role name, so :file: and :doc: behave exactly as :ref: does. Linting this fixture:

See :doc:`some—doc` and :file:`a/b—c.txt` and :ref:`t—x`.

Prose with an em dash — here.

reports one alert, on the prose em dash on the last line, and nothing on the three role targets.

The upstream change is adamtheturtle/vale-style-clear-prose#1, and the reasoning for keeping this in the package rather than in every consumer is in the 1.1.0 changelog entry.