diff --git a/plugins/lint/.apm/skills/vale-config/README.md b/plugins/lint/.apm/skills/vale-config/README.md index 2a5d0bc..b49138a 100644 --- a/plugins/lint/.apm/skills/vale-config/README.md +++ b/plugins/lint/.apm/skills/vale-config/README.md @@ -19,5 +19,5 @@ Describe what you want configured: initial setup, adding a third-party style pac | File | Purpose | |------|---------| | `SKILL.md` | Skill instructions for agents | -| `references/configuration-reference.md` | Full `.vale.ini` field and rule-header reference | +| `references/configuration-reference.md` | Full `.vale.ini` fields, rule-header fields, and frontmatter-scope behaviour | | `references/sources.md` | Research sources backing the Vale configuration guidance | diff --git a/plugins/lint/.apm/skills/vale-config/SKILL.md b/plugins/lint/.apm/skills/vale-config/SKILL.md index c5b192f..be534fb 100644 --- a/plugins/lint/.apm/skills/vale-config/SKILL.md +++ b/plugins/lint/.apm/skills/vale-config/SKILL.md @@ -2,27 +2,22 @@ name: vale-config description: > - Use when installing or configuring Vale, the cross-platform prose/style linter — setting up - .vale.ini, choosing a StylesPath, adding built-in, third-party, or custom styles, and activating - them per file glob via BasedOnStyles. Covers the setup side of Vale only: getting a project from - "no Vale config" to "vale sync runs clean and BasedOnStyles is wired up correctly". Use even if the - user doesn't say "Vale" explicitly — "set up prose linting", "lint our docs for style", "enforce a - vocabulary/terminology list in markdown" all apply. Do not use when the user wants to actually run - Vale and interpret its output on existing config — use vale-run for that. + Use when installing or configuring Vale, the prose/style linter — writing a `.vale.ini` whose + styles are fetched and actually activated — even when the user says only "set up prose + linting". Not running Vale on an existing config -> `vale-run`. metadata: category: lint - version: "0.1.0" + version: "0.1.1" source_keys: - context7-websites-vale-sh --- ## Gotchas -- Installing the `vale` binary installs no styles, but only *package* styles need fetching. A fresh `.vale.ini` naming a style in `BasedOnStyles` that is declared in `Packages` will fail or find nothing until `vale sync` downloads it. A built-in style (`Vale`) or a style whose YAML rule files are already committed under `StylesPath` lints immediately, with no `Packages` entry and no sync. -- `.vale.ini` is order-sensitive: global (core) settings first, then the optional `[formats]` section, then glob sections (`[*]`, `[*.md]`, …). Settings in a glob section only apply to files matching that glob. -- `Packages` (top-level, fetched by `vale sync`) and `BasedOnStyles` (per-glob, activates) are separate keys — a style only lints files once it's in both. This is the step people forget. -- A rule scoped to `text.frontmatter.` (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 with a deliberately-bad fixture: a `>` folded block scalar, plain (unquoted) continuation lines, and single- or double-quoted multi-line scalars each yield 0 findings and exit 0, silently and with no error; a `|` literal block scalar spanning the same 2+ lines lints normally and exits 1. Do not assume `|` and `>` 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. +- A style in `BasedOnStyles` that is neither built-in nor already under `StylesPath` finds nothing until `vale sync` fetches it — a clean run is not proof anything linted. +- `.vale.ini` is order-sensitive: core settings first, then `[formats]`, then glob sections. Anything written below a glob header applies only to files matching that glob. +- A rule scoped to `text.frontmatter.` silently matches nothing when the field spans multiple lines in most YAML forms. If you scope a rule to frontmatter, read `references/configuration-reference.md` first. ## Setup workflow @@ -59,4 +54,4 @@ styles/ └── NoJargon.yml ``` -Each rule file needs `extends` (the check it implements, e.g. `existence`) and `message` at minimum. Activate the style the same way as any other: add `MyStyle` to `BasedOnStyles` for the relevant glob. See `references/configuration-reference.md` for the full rule header field table. +Each rule file needs `extends` (the check it implements, e.g. `existence`) and `message` at minimum. Activate the style the same way as any other: add `MyStyle` to `BasedOnStyles` for the relevant glob. If a rule needs a field beyond those two, read `references/configuration-reference.md` for the full rule header field table. diff --git a/plugins/lint/.apm/skills/vale-config/references/configuration-reference.md b/plugins/lint/.apm/skills/vale-config/references/configuration-reference.md index d2bca35..7da0086 100644 --- a/plugins/lint/.apm/skills/vale-config/references/configuration-reference.md +++ b/plugins/lint/.apm/skills/vale-config/references/configuration-reference.md @@ -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 `/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.` (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. diff --git a/plugins/lint/skills/vale-config/README.md b/plugins/lint/skills/vale-config/README.md index 2a5d0bc..b49138a 100644 --- a/plugins/lint/skills/vale-config/README.md +++ b/plugins/lint/skills/vale-config/README.md @@ -19,5 +19,5 @@ Describe what you want configured: initial setup, adding a third-party style pac | File | Purpose | |------|---------| | `SKILL.md` | Skill instructions for agents | -| `references/configuration-reference.md` | Full `.vale.ini` field and rule-header reference | +| `references/configuration-reference.md` | Full `.vale.ini` fields, rule-header fields, and frontmatter-scope behaviour | | `references/sources.md` | Research sources backing the Vale configuration guidance | diff --git a/plugins/lint/skills/vale-config/SKILL.md b/plugins/lint/skills/vale-config/SKILL.md index c5b192f..be534fb 100644 --- a/plugins/lint/skills/vale-config/SKILL.md +++ b/plugins/lint/skills/vale-config/SKILL.md @@ -2,27 +2,22 @@ name: vale-config description: > - Use when installing or configuring Vale, the cross-platform prose/style linter — setting up - .vale.ini, choosing a StylesPath, adding built-in, third-party, or custom styles, and activating - them per file glob via BasedOnStyles. Covers the setup side of Vale only: getting a project from - "no Vale config" to "vale sync runs clean and BasedOnStyles is wired up correctly". Use even if the - user doesn't say "Vale" explicitly — "set up prose linting", "lint our docs for style", "enforce a - vocabulary/terminology list in markdown" all apply. Do not use when the user wants to actually run - Vale and interpret its output on existing config — use vale-run for that. + Use when installing or configuring Vale, the prose/style linter — writing a `.vale.ini` whose + styles are fetched and actually activated — even when the user says only "set up prose + linting". Not running Vale on an existing config -> `vale-run`. metadata: category: lint - version: "0.1.0" + version: "0.1.1" source_keys: - context7-websites-vale-sh --- ## Gotchas -- Installing the `vale` binary installs no styles, but only *package* styles need fetching. A fresh `.vale.ini` naming a style in `BasedOnStyles` that is declared in `Packages` will fail or find nothing until `vale sync` downloads it. A built-in style (`Vale`) or a style whose YAML rule files are already committed under `StylesPath` lints immediately, with no `Packages` entry and no sync. -- `.vale.ini` is order-sensitive: global (core) settings first, then the optional `[formats]` section, then glob sections (`[*]`, `[*.md]`, …). Settings in a glob section only apply to files matching that glob. -- `Packages` (top-level, fetched by `vale sync`) and `BasedOnStyles` (per-glob, activates) are separate keys — a style only lints files once it's in both. This is the step people forget. -- A rule scoped to `text.frontmatter.` (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 with a deliberately-bad fixture: a `>` folded block scalar, plain (unquoted) continuation lines, and single- or double-quoted multi-line scalars each yield 0 findings and exit 0, silently and with no error; a `|` literal block scalar spanning the same 2+ lines lints normally and exits 1. Do not assume `|` and `>` 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. +- A style in `BasedOnStyles` that is neither built-in nor already under `StylesPath` finds nothing until `vale sync` fetches it — a clean run is not proof anything linted. +- `.vale.ini` is order-sensitive: core settings first, then `[formats]`, then glob sections. Anything written below a glob header applies only to files matching that glob. +- A rule scoped to `text.frontmatter.` silently matches nothing when the field spans multiple lines in most YAML forms. If you scope a rule to frontmatter, read `references/configuration-reference.md` first. ## Setup workflow @@ -59,4 +54,4 @@ styles/ └── NoJargon.yml ``` -Each rule file needs `extends` (the check it implements, e.g. `existence`) and `message` at minimum. Activate the style the same way as any other: add `MyStyle` to `BasedOnStyles` for the relevant glob. See `references/configuration-reference.md` for the full rule header field table. +Each rule file needs `extends` (the check it implements, e.g. `existence`) and `message` at minimum. Activate the style the same way as any other: add `MyStyle` to `BasedOnStyles` for the relevant glob. If a rule needs a field beyond those two, read `references/configuration-reference.md` for the full rule header field table. diff --git a/plugins/lint/skills/vale-config/references/configuration-reference.md b/plugins/lint/skills/vale-config/references/configuration-reference.md index d2bca35..7da0086 100644 --- a/plugins/lint/skills/vale-config/references/configuration-reference.md +++ b/plugins/lint/skills/vale-config/references/configuration-reference.md @@ -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 `/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.` (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.