Files

Defame1297 ff187ef9fc refactor(lint): retrofit vale-run to the ADR-0020 context contract

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

2026-08-30 15:07:16 +00:00

3.5 KiB

Raw Blame History

source_keys

context7-websites-vale-sh

Vale troubleshooting reference

Why a rule isn't applying

vale ls-config prints the fully-resolved, currently active configuration as JSON. Check that before rereading .vale.ini — what is written in the config file is not necessarily what is active, and the resolved output is the fastest way to see which styles and rules a run actually loaded.

Inline suppression syntax by format

Markdown uses HTML comments — the MDX {/* */} form does not suppress anything in a plain .md file:

<!-- vale off -->
This text will be ignored.
<!-- vale on -->

MDX:

{/* vale off */}
This text will be ignored.
{/* vale on */}

Org mode:

# vale off
This text will be ignored.
# vale on

Disabling a specific rule for specific matches

Targets one rule and specific known-exception strings, then re-enables — the preferred fix for a recurring false positive on a specific term, since it keeps the rule active everywhere else:

Markdown:

<!-- vale Style.Redundancy["ACT test","OTHER"] = NO -->
This is some text ACT test
<!-- vale Style.Redundancy["ACT test","OTHER"] = YES -->

MDX:

{/* vale Style.Redundancy["ACT test","OTHER"] = NO */}
This is some text ACT test
{/* vale Style.Redundancy["ACT test","OTHER"] = YES */}

Ignoring words in spell check

The spelling check accepts an ignore list of external plain-text files, so project-specific terms don't need touching the dictionary:

extends: spelling
message: "Did you really mean '%s'?"
level: error
ignore:
  - ignore1.txt
  - ignore2.txt

Plain-text fallback

If a file's syntax-aware parsing produces noisy or incorrect results (an unsupported or malformed format), rerun with --ignore-syntax to treat it as plain text instead of relying on the format-specific parser.

CI failing unexpectedly

Only error-level alerts make Vale exit non-zero; warning and suggestion alerts are printed but exit 0. If a CI job fails solely because of error-level alerts — not because the content is actually wrong for that pipeline stage — add --no-exit rather than suppressing the rule itself. This preserves the lint output while not gating the build on it. If the alerts are warnings or suggestions, Vale did not fail the job — look elsewhere.

pre-commit integration

Vale ships a pre-commit hook definition. A typical setup runs vale sync once (with pass_filenames: false) plus the actual lint pass with CI-appropriate flags:

repos:
  - repo: https://github.com/errata-ai/vale
    rev: 16d3a7f
    hooks:
      - id: vale
        name: vale sync
        pass_filenames: false
        args: [sync]
      - id: vale
        args: [--output=line, --minAlertLevel=error]

If the project has documented a wrapper script for a known Vale scope/escaping limitation (see the Gotchas section of SKILL.md), point the second hook's entry: at that wrapper instead of at bare vale, even though the hook's repo/rev/id still come from the upstream definition above — only the invocation target changes:

      - id: vale
        entry: <path-to-project-wrapper>
        args: [--output=line, --minAlertLevel=error]

Using the upstream hook's bare vale entry in a project that has such a wrapper reintroduces exactly the bug the wrapper exists to fix.

CI output for machine parsing

$ vale --output=JSON README.md

Use --output=JSON when a CI step needs to parse results programmatically rather than read the default CLI-formatted output.

3.5 KiB Raw Blame History