Defame1297
ff187ef9fc
Description 654 -> 294 chars, Gotchas 36% -> 19%. Body 698 -> 642 words: up from the first pass, because a clean-context audit found four defects whose fixes are net-additive text. The suppression-markup warning covered only one of the two paths that write it -- the list is case-based, so a recurring false positive goes straight to step 3 and never read step 2's warning. Hoisted above both. The CI-failure trigger, which the description advertises, had no path to the file holding its answer: the negative diagnosis 'if the alerts are warnings, Vale is not what failed the build' survived only in troubleshooting.md, which no CI-entered invocation loads. An agent would confidently prescribe --no-exit for a failure Vale never caused. The description had lost every prose-domain word -- no 'prose', no 'linter' -- while vale-config kept all of them, so 'check prose style' routed to the wrong skill of the pair. Accepts two soft SUGGESTIONs rather than dropping restored content; neither fails the gate. Refs #99
59 lines
4.5 KiB
Markdown
59 lines
4.5 KiB
Markdown
---
|
|
name: vale-run
|
|
description: >
|
|
Use when running Vale (a prose/style linter) on a project that already has a
|
|
.vale.ini and acting on its output — even when the user does not say "Vale",
|
|
as in "lint the docs", "check prose style", or "why is CI failing on the docs
|
|
check". Not setting up Vale config or styles -> `vale-config`.
|
|
metadata:
|
|
version: "0.1.2"
|
|
category: lint
|
|
source_keys:
|
|
- context7-websites-vale-sh
|
|
---
|
|
|
|
## Gotchas
|
|
|
|
- Vale's exit code keys off `error`-level alerts only — `warning` and `suggestion` alerts print and still exit `0`, and `MinAlertLevel`/`--minAlertLevel` filter what is displayed, never the exit code — no flag makes warnings fail. A rule that must gate CI or a commit hook has to be `level: error`. This is the most common way a Vale gate silently passes everything.
|
|
- Check whether the target repo documents its own `vale` wrapper script (README, CONTRIBUTING, pre-commit config, `scripts/`) before calling the binary. Some projects wrap `vale` to work around real bugs — e.g. a scope that silently stops matching multi-line YAML block-scalar frontmatter — so bare `vale` skips whatever the wrapper fixes. Invoke the documented wrapper with the same arguments.
|
|
|
|
## Running vale
|
|
|
|
Default invocation (when the target repo has no documented Vale wrapper — see Gotchas):
|
|
|
|
```bash
|
|
vale <path-or-glob>
|
|
```
|
|
|
|
Key flags:
|
|
|
|
| Flag | Purpose |
|
|
|---|---|
|
|
| `--output=<style>` | Output format/template: `CLI` (default, human-readable), `line` (compact, one alert per line, good for grep/piping), `JSON` (for programmatic parsing), or a custom template. |
|
|
| `--minAlertLevel=<suggestion\|warning\|error>` | Overrides `MinAlertLevel` from `.vale.ini` for this run only, without editing config. Filters what is displayed; does not affect the exit code. |
|
|
| `--no-exit` | Suppresses the nonzero exit that `error`-level alerts would otherwise cause; a no-op when no rule is `error`-level. Use in CI stages that should surface lint output without hard-failing the build. |
|
|
| `--ignore-syntax` | Treats input as plain text, skipping format-aware parsing — use when a file's syntax-aware parser produces noisy or wrong results. |
|
|
|
|
`vale sync` downloads the packages/styles declared in `.vale.ini` — that's a one-time-per-change setup step (vale-config's territory), not part of a normal lint run. If a run behaves as though no styles are active, check `vale ls-config` to confirm what actually loaded before concluding it is a sync problem — an unrun `vale sync` is the usual cause, and not a `vale-run` problem.
|
|
|
|
Prefer `--output=JSON` whenever the caller (a script, a CI step, another agent) needs to act on individual alerts rather than just get a pass/fail signal — `CLI` and `line` are for humans reading the terminal.
|
|
|
|
## Fixing false positives
|
|
|
|
Before writing any inline suppression markup (steps 2 and 3 below), read `references/troubleshooting.md` for your file's format: the markup is format-specific, and the wrong form suppresses nothing while Vale reports no error — the Markdown HTML-comment form is inert in an MDX file.
|
|
|
|
Scope the fix as narrowly as possible, in this order:
|
|
|
|
1. **Mentioning banned phrasing rather than using it**: wrap it in backticks or a fenced code block. Vale skips code spans and fences, so no suppression is needed at all. Try this before any suppression markup.
|
|
2. **One-off**: inline-suppress the specific text run with the format's `vale off`/`vale on` markup.
|
|
3. **Recurring known-exception string, one rule**: disable that specific rule for that specific match inline (in Markdown, e.g. `<!-- vale Style.Redundancy["ACT test","OTHER"] = NO -->` ... `= YES`), rather than the whole rule.
|
|
4. **Known project term failing spell check**: add it to the style's `ignore` list, not an inline suppression.
|
|
|
|
Never disable a rule project-wide to fix one false positive — editing `.vale.ini`/`BasedOnStyles` is vale-config's job, and it silences the rule everywhere, not just the false-positive case.
|
|
|
|
If output looks wrong because Vale mis-parsed a file's format, rerun with `--ignore-syntax` before assuming the rule itself is broken.
|
|
|
|
For CI that fails solely because Vale returned non-zero on `error`-level alerts — not because the content is wrong for that pipeline stage — add `--no-exit` rather than disabling the rule. If the failing alerts are warnings or suggestions, Vale is not what failed the build; look elsewhere.
|
|
|
|
If a rule appears not to apply, if you need the spelling-ignore syntax, if a CI failure still needs diagnosing, or if setting Vale up as a pre-commit hook, read `references/troubleshooting.md`.
|