Defame1297
4d6f313b1e
Merge duplicate gotcha in vale-config (Packages vs BasedOnStyles was stated twice) and align vale-run's category field with vale-config's (lint, not linting) so sibling skills in the plugin agree. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FxG5T8EJDgkABXxuneuFfn
62 lines
3.8 KiB
Markdown
62 lines
3.8 KiB
Markdown
---
|
|
name: vale-run
|
|
description: >
|
|
Use when running Vale (a prose/style linter) against files or directories in an
|
|
already-configured project — one that already has a .vale.ini — and interpreting
|
|
or reporting its results: choosing an output format for humans vs. CI, filtering
|
|
by severity, handling Vale's exit codes in scripts, or resolving common runtime
|
|
issues like false positives and unexpected CI failures. Use even if the user
|
|
doesn't say "vale" explicitly, e.g. "lint the docs", "check prose style", "run
|
|
the style linter", "why is CI failing on the docs check". Do not use when the
|
|
project has no .vale.ini yet, or needs styles installed/configured — that's the
|
|
vale-config skill.
|
|
metadata:
|
|
version: "0.1.0"
|
|
category: lint
|
|
source_keys:
|
|
- context7-websites-vale-sh
|
|
---
|
|
|
|
## Gotchas
|
|
|
|
- Vale exits non-zero whenever it finds an alert at or above `MinAlertLevel` — that's what makes it usable as a CI gate, not a sign the invocation failed. Read the output before concluding the command errored.
|
|
- `vale ls-config` prints the fully-resolved, currently active configuration as JSON — the fastest way to check why a rule "isn't applying" is what's actually active, not what's written in `.vale.ini`.
|
|
- Inline suppression syntax is format-specific: Markdown/MDX uses `{/* vale off */}` / `{/* vale on */}`, Org mode uses `# vale off` / `# vale on`. Don't assume one syntax works across formats.
|
|
|
|
## Running vale
|
|
|
|
Default invocation:
|
|
|
|
```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. |
|
|
| `--no-exit` | Forces exit code `0` regardless of findings. 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, that's a sign `vale sync` hasn't been run yet, 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
|
|
|
|
Scope the fix as narrowly as possible, in this order:
|
|
|
|
1. **One-off**: inline-suppress the specific text run with the format's `vale off`/`vale on` markup.
|
|
2. **Recurring known-exception string, one rule**: disable that specific rule for that specific match inline (e.g. `{/* vale Style.Redundancy["ACT test","OTHER"] = NO */}` ... `= YES`), rather than the whole rule.
|
|
3. **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 found alerts — not because the content is wrong for that pipeline stage — add `--no-exit` rather than disabling the rule.
|
|
|
|
If setting up Vale as a pre-commit hook or need the full inline-suppression/spelling-ignore syntax reference, read `references/troubleshooting.md`.
|