.vale.ini

# Prose linting for the family documentation site (plan §I.3).
#
# The site is EN-only by decision (§I.0), which removes the usual excuse for
# not linting the English: there is no second language to keep in step and no
# translator in the loop. Vale is the only objective gate on it.
#
# Scope: the hand-written sections only. `docs/src/api/**` is generated from
# docblocks (docs/scripts/generate-api.mjs) — a prose linter on it produces
# findings whose only fix is rewriting PHP docblocks to satisfy a Microsoft
# style rule, and that volume would bury the real findings on the first run.
# The scope is enforced by the paths passed on the command line, not here;
# see .github/workflows/docs.yml and `make docs-vale`.
#
# The rule set is Microsoft's, minus the rules that contradict the house
# style this documentation already has. Each exclusion is a decision, not a
# way to make the run green — do not add to the list to silence a finding
# that is simply correct.

StylesPath = docs/.vale/styles
MinAlertLevel = warning
# Pinned to a release URL, not the bare `Microsoft` alias: the alias resolves
# to whatever upstream serves that morning, and this gate sits at zero
# findings — one new warning-level rule would redden master with no local
# change. The binary is version- and checksum-pinned in .github/workflows/docs.yml
# for the same reason; pinning one and floating the other is not a policy.
Packages = https://github.com/vale-cli/Microsoft/releases/download/v0.15.1/Microsoft.zip
Vocab = PropertyTesting

[*.md]
BasedOnStyles = Vale, Microsoft

# Spaced em dashes are this documentation's main punctuation for an aside —
# like this one. Microsoft's guide forbids them outright; changing 130+ of
# them into commas and parentheses would flatten the prose, not improve it.
Microsoft.Dashes = NO

# Microsoft prefers contractions ("don't", "isn't"). These docs are written
# in the same register as the AGENTS.md files next to them, which spell out
# "do not". Consistency with the surrounding corpus beats the style guide.
Microsoft.Contractions = NO

# Flags every -ly adverb. "Silently", "deliberately" and "atomically" are
# load-bearing words here: they distinguish a failure mode that is reported
# from one that is not.
Microsoft.Adverbs = NO

# Wants the word after a colon in a heading capitalized. Our headings put
# code after the colon ("Dependent generators: flatMap vs draw"), and
# capitalizing an identifier makes it a different identifier.
Microsoft.HeadingColons = NO

# American punctuation-inside-quotes. Wrong for a documentation set that
# quotes exact strings — moving the period inside "abc\n" changes the value
# being discussed.
Microsoft.Quotes = NO

# "CI", "PHPUnit" and "API" in a heading are clearer than their expansions.
Microsoft.HeadingAcronyms = NO

# Question headings ("Why no #[Property] attribute?") are the clearest form
# for a rationale section, and the rule cannot tell them from a stray period.
Microsoft.HeadingPunctuation = NO