diff --git a/plugins/lint/.apm/skills/vale-config/SKILL.md b/plugins/lint/.apm/skills/vale-config/SKILL.md index be534fb..352daeb 100644 --- a/plugins/lint/.apm/skills/vale-config/SKILL.md +++ b/plugins/lint/.apm/skills/vale-config/SKILL.md @@ -11,11 +11,14 @@ metadata: version: "0.1.1" source_keys: - context7-websites-vale-sh + - house-vale-3-15-2-repro --- ## Gotchas -- 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. +- A style in `BasedOnStyles` that is neither built-in nor a directory under `StylesPath` fails hard, not silently: `E100 [loadStyles]`, exit 2, nothing linted. +- `vale sync` alone does not clear that `E100`. Sync fetches only what the top-level `Packages` key declares, so against a `BasedOnStyles`-only name it reports `Synced 0 package(s)` and exits 0, fetching nothing. Add the style to `Packages`, then sync. A style lints only once it is in both keys — and the reverse case is silent, exiting 0. +- Only *package* styles need fetching: built-in `Vale`, and any style whose YAML is already committed under `StylesPath`, lint with no `Packages` entry and no sync. - `.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. @@ -42,7 +45,7 @@ metadata: - [ ] **Sync**: run `vale sync` to download everything listed in `Packages` into `StylesPath`. - [ ] **Verify activation**: confirm every style named in `Packages` also appears in at least one glob's `BasedOnStyles` — an unreferenced package downloads but never lints anything. -For the full `.vale.ini` field reference (formats mapping, vocab, local overrides, custom rule header fields), read `references/configuration-reference.md`. +For the full `.vale.ini` field reference (formats mapping, vocab, local overrides, custom rule header fields) and the verified style-resolution matrix — which error each misconfiguration raises, and the two that exit 0 while linting nothing — read `references/configuration-reference.md`. ## Custom styles 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 7da0086..aec5fa7 100644 --- a/plugins/lint/.apm/skills/vale-config/references/configuration-reference.md +++ b/plugins/lint/.apm/skills/vale-config/references/configuration-reference.md @@ -2,6 +2,7 @@ topic: configuration-reference source_keys: - context7-websites-vale-sh + - house-vale-3-15-2-repro --- ## Core Settings @@ -68,7 +69,7 @@ Individual rule YAML files (under a style's directory) support these header fiel The underlying functions a rule's `extends` field can reference: `existence`, `substitution`, `occurrence`, `repetition`, `consistency`, `conditional`, `capitalization`, `metric`, `spelling`, `sequence`, `script`. -## Built-in Style +## Style Resolution 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: @@ -77,11 +78,23 @@ Only *package* styles need fetching. A style whose YAML rule files are already c - `Vale.Avoid` — enforces the project's rejected vocabulary terms. - `Vale.Repetition` — flags repeated words (e.g. "the the"). +`Packages` (top-level, what `vale sync` downloads) and `BasedOnStyles` (per-glob, what activates) are separate keys: a style lints a file only once it is in both. Every row below reproduced against Vale 3.15.2 (slug `house-vale-3-15-2-repro`): + +| Configuration | Result | +|---|---| +| `BasedOnStyles` names a style with no directory under `StylesPath`, not built-in | `E100 [loadStyles] Runtime error` — `style 'X' does not exist on StylesPath`, exit 2 | +| `StylesPath` directory itself absent, even with only `Vale` active | `E201 Invalid value` — `The path '...' does not exist`, exit 2 | +| `vale sync` with a name in `BasedOnStyles` but not `Packages` | `SUCCESS Synced 0 package(s)`, exit 0, nothing downloaded — the next lint repeats the `E100` | +| `vale sync` with the name added to `Packages` | package lands under `StylesPath`, exit 0; lint then loads it | +| Style in `Packages` and synced, but in no glob's `BasedOnStyles` | 0 findings, exit 0 — downloads, never lints, indistinguishable from a clean run | +| `BasedOnStyles` names an *empty* directory under `StylesPath` | 0 findings, exit 0 — loads and lints nothing; `vale sync` never produces this state | +| Built-in `Vale`, or a style's YAML committed under `StylesPath` | lints immediately, no `Packages` entry, no sync | + ## 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. +House-verified behaviour, not documented on vale.sh — reproduced locally against Vale 3.15.2 (slug `house-vale-3-15-2-repro`). -Confirmed against Vale 3.15.2, multi-line forms spanning 2+ lines: +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. Multi-line forms spanning 2+ lines: | Frontmatter value form | Result | |---|---| diff --git a/plugins/lint/.apm/skills/vale-config/references/sources.md b/plugins/lint/.apm/skills/vale-config/references/sources.md index 854fe15..a983a59 100644 --- a/plugins/lint/.apm/skills/vale-config/references/sources.md +++ b/plugins/lint/.apm/skills/vale-config/references/sources.md @@ -7,3 +7,11 @@ - **Research doc:** plugins/lint/docs/research/docs/vale/sources.md - **Contributing files:** SKILL.md, references/configuration-reference.md - **Status:** `extracted` + +## house-vale-3-15-2-repro + +- **URL:** (house-verified — reproduced locally against the `vale` binary, not an external source) +- **Description:** Behaviour of Vale 3.15.2 established by running it against purpose-built fixtures in this repo, where vale.sh documents nothing: the `E100 [loadStyles]` / exit-2 failure for a `BasedOnStyles` name absent from `StylesPath`, `vale sync` reporting `Synced 0 package(s)` for a name not declared in `Packages`, the `E201` / exit-2 failure when the `StylesPath` directory does not exist, the exit-0 no-op of an empty style directory, and the `text.frontmatter.` scope matrix across multi-line YAML forms. +- **Research doc:** none — house-verified reproduction, not part of the plugin's research corpus (no `plugins/lint/docs/research/` topic file backs this entry) +- **Contributing files:** SKILL.md, references/configuration-reference.md +- **Status:** `extracted` diff --git a/plugins/lint/skills/vale-config/SKILL.md b/plugins/lint/skills/vale-config/SKILL.md index be534fb..352daeb 100644 --- a/plugins/lint/skills/vale-config/SKILL.md +++ b/plugins/lint/skills/vale-config/SKILL.md @@ -11,11 +11,14 @@ metadata: version: "0.1.1" source_keys: - context7-websites-vale-sh + - house-vale-3-15-2-repro --- ## Gotchas -- 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. +- A style in `BasedOnStyles` that is neither built-in nor a directory under `StylesPath` fails hard, not silently: `E100 [loadStyles]`, exit 2, nothing linted. +- `vale sync` alone does not clear that `E100`. Sync fetches only what the top-level `Packages` key declares, so against a `BasedOnStyles`-only name it reports `Synced 0 package(s)` and exits 0, fetching nothing. Add the style to `Packages`, then sync. A style lints only once it is in both keys — and the reverse case is silent, exiting 0. +- Only *package* styles need fetching: built-in `Vale`, and any style whose YAML is already committed under `StylesPath`, lint with no `Packages` entry and no sync. - `.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. @@ -42,7 +45,7 @@ metadata: - [ ] **Sync**: run `vale sync` to download everything listed in `Packages` into `StylesPath`. - [ ] **Verify activation**: confirm every style named in `Packages` also appears in at least one glob's `BasedOnStyles` — an unreferenced package downloads but never lints anything. -For the full `.vale.ini` field reference (formats mapping, vocab, local overrides, custom rule header fields), read `references/configuration-reference.md`. +For the full `.vale.ini` field reference (formats mapping, vocab, local overrides, custom rule header fields) and the verified style-resolution matrix — which error each misconfiguration raises, and the two that exit 0 while linting nothing — read `references/configuration-reference.md`. ## Custom styles diff --git a/plugins/lint/skills/vale-config/references/configuration-reference.md b/plugins/lint/skills/vale-config/references/configuration-reference.md index 7da0086..aec5fa7 100644 --- a/plugins/lint/skills/vale-config/references/configuration-reference.md +++ b/plugins/lint/skills/vale-config/references/configuration-reference.md @@ -2,6 +2,7 @@ topic: configuration-reference source_keys: - context7-websites-vale-sh + - house-vale-3-15-2-repro --- ## Core Settings @@ -68,7 +69,7 @@ Individual rule YAML files (under a style's directory) support these header fiel The underlying functions a rule's `extends` field can reference: `existence`, `substitution`, `occurrence`, `repetition`, `consistency`, `conditional`, `capitalization`, `metric`, `spelling`, `sequence`, `script`. -## Built-in Style +## Style Resolution 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: @@ -77,11 +78,23 @@ Only *package* styles need fetching. A style whose YAML rule files are already c - `Vale.Avoid` — enforces the project's rejected vocabulary terms. - `Vale.Repetition` — flags repeated words (e.g. "the the"). +`Packages` (top-level, what `vale sync` downloads) and `BasedOnStyles` (per-glob, what activates) are separate keys: a style lints a file only once it is in both. Every row below reproduced against Vale 3.15.2 (slug `house-vale-3-15-2-repro`): + +| Configuration | Result | +|---|---| +| `BasedOnStyles` names a style with no directory under `StylesPath`, not built-in | `E100 [loadStyles] Runtime error` — `style 'X' does not exist on StylesPath`, exit 2 | +| `StylesPath` directory itself absent, even with only `Vale` active | `E201 Invalid value` — `The path '...' does not exist`, exit 2 | +| `vale sync` with a name in `BasedOnStyles` but not `Packages` | `SUCCESS Synced 0 package(s)`, exit 0, nothing downloaded — the next lint repeats the `E100` | +| `vale sync` with the name added to `Packages` | package lands under `StylesPath`, exit 0; lint then loads it | +| Style in `Packages` and synced, but in no glob's `BasedOnStyles` | 0 findings, exit 0 — downloads, never lints, indistinguishable from a clean run | +| `BasedOnStyles` names an *empty* directory under `StylesPath` | 0 findings, exit 0 — loads and lints nothing; `vale sync` never produces this state | +| Built-in `Vale`, or a style's YAML committed under `StylesPath` | lints immediately, no `Packages` entry, no sync | + ## 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. +House-verified behaviour, not documented on vale.sh — reproduced locally against Vale 3.15.2 (slug `house-vale-3-15-2-repro`). -Confirmed against Vale 3.15.2, multi-line forms spanning 2+ lines: +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. Multi-line forms spanning 2+ lines: | Frontmatter value form | Result | |---|---| diff --git a/plugins/lint/skills/vale-config/references/sources.md b/plugins/lint/skills/vale-config/references/sources.md index 854fe15..a983a59 100644 --- a/plugins/lint/skills/vale-config/references/sources.md +++ b/plugins/lint/skills/vale-config/references/sources.md @@ -7,3 +7,11 @@ - **Research doc:** plugins/lint/docs/research/docs/vale/sources.md - **Contributing files:** SKILL.md, references/configuration-reference.md - **Status:** `extracted` + +## house-vale-3-15-2-repro + +- **URL:** (house-verified — reproduced locally against the `vale` binary, not an external source) +- **Description:** Behaviour of Vale 3.15.2 established by running it against purpose-built fixtures in this repo, where vale.sh documents nothing: the `E100 [loadStyles]` / exit-2 failure for a `BasedOnStyles` name absent from `StylesPath`, `vale sync` reporting `Synced 0 package(s)` for a name not declared in `Packages`, the `E201` / exit-2 failure when the `StylesPath` directory does not exist, the exit-0 no-op of an empty style directory, and the `text.frontmatter.` scope matrix across multi-line YAML forms. +- **Research doc:** none — house-verified reproduction, not part of the plugin's research corpus (no `plugins/lint/docs/research/` topic file backs this entry) +- **Contributing files:** SKILL.md, references/configuration-reference.md +- **Status:** `extracted`