Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

refactor(lint): retrofit vale-config to the ADR-0020 context contract

Browse Source 
Description 657 -> 244 chars, body 504 -> 342 words, Gotchas 50% -> 24%.
The 50% was the worst ratio in the corpus and a real inverted body, not
the denominator artefact the ratio usually flags: half the body was a
Gotchas section doing duty as reference material.

A clean-context audit caught the split leaving a false statement behind.
Gotcha 1's kernel lost the qualifier that only package styles need
fetching, so it asserted that any style vale sync has not fetched fails
-- contradicting the same file twice, since the built-in Vale style and
any committed custom style are never fetched. An agent adding a custom
style would have added a spurious Packages entry and broken vale sync
outright. The qualifier is restored in the body rather than behind a
fourth reference pointer.

Also corrects the moved fixture's framing, which tabulated a control row
under a heading claiming it came from a multi-line fixture.

Refs #99
This commit is contained in:
Defame1297
2026-08-30 15:07:15 +00:00
parent c59e4bf0c5
commit 45cd26045a
6 changed files with 52 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
plugins/lint/skills/vale-config/references/configuration-reference.md
View File

@@ -70,9 +70,25 @@ The underlying functions a rule's `extends` field can reference: `existence`, `s
## Built-in Style
Vale ships with a default `Vale` style containing four rules, usable without `vale sync`:
Only *package* styles need fetching. A style whose YAML rule files are already committed under `StylesPath` lints immediately, with no `Packages` entry and no `vale sync`; the same is true of the built-in `Vale` style, which ships with the binary and contains four rules:
- `Vale.Spelling` — spell-checks against Hunspell-compatible dictionaries in `<StylesPath>/config/dictionaries`.
- `Vale.Terms` — enforces the project's accepted vocabulary terms.
- `Vale.Avoid` — enforces the project's rejected vocabulary terms.
- `Vale.Repetition` — flags repeated words (e.g. "the the").
## Frontmatter Scopes
A rule scoped to `text.frontmatter.<key>` (e.g. `text.frontmatter.description`) matches reliably when that field's value is a single physical line, and breaks on most — not all — multi-line forms.
Confirmed against Vale 3.15.2, multi-line forms spanning 2+ lines:
| Frontmatter value form | Result |
|---|---|
| Single physical line (control) | Lints, exits 1 |
| `\|` literal block scalar | Lints, exits 1 |
| `>` folded block scalar | 0 findings, exits 0 |
| Plain (unquoted) continuation lines | 0 findings, exits 0 |
| Single- or double-quoted multi-line scalar | 0 findings, exits 0 |
The silent cases produce no error of any kind, so a passing run is indistinguishable from a clean one. Do not assume a literal block scalar and a folded one behave alike — reproduce both against your own config before trusting a frontmatter-scoped rule in production. If the field is commonly authored in one of the broken forms, flatten it to one physical line ahead of the `vale` call rather than relying on the scope alone.