fix(cli): stop one AsciiDoc file from disabling every Vale rule

[thecodedrift]

Stack (root → tip):

• feat(cli): state each local engine's reach in the routing recipe #155
  • fix(cli): require both fixture buckets for an ast-grep rule #156
  • ➡️ fix(cli): stop one AsciiDoc file from disabling every Vale rule #157 (you are here)

Stacked on #155. Review only the last two commits; the base is that PR.

One .adoc, .rst, .mdx, .xml, .dita or .asc anywhere a Vale rule's matcher reaches disabled every Vale rule in the repo. Measured: a run reporting 5 Vale findings across 5 files dropped to 0 with one .adoc added, and check still exited on an unrelated ast-grep finding — so the disappearance read as a normal red check.

Vale genuinely supports these formats upstream. The failure is a missing external converter in our distribution, not absent support.

Refs #151

Mechanism, established before designing the fix

Vale aborts the whole run; our code discards nothing. On the first E100, stdout is 0 bytes and exit is 2 — the Markdown findings are destroyed inside Vale before serialization. That ruled out "tolerate the exit code and parse partial output," which was the obvious first guess.

Two further measured facts shaped it: the trigger is the config, not the file (with [*.{html,md}] an .adoc is inert; with [*] it crashes), and per-file invocation would cost N subprocesses. A Vale config setting ([formats] adoc = md) would lint AsciiDoc with the Markdown parser and emit nonsense. So: exclude the converter-dependent files from the set handed to Vale, and name the skip rather than letting it be silent.

Notice: Vale did not check 3 file(s): guide.adoc, legacy.asc, spec.rest. Vale supports these
formats, but parsing them needs an external converter (asciidoctor, rst2html) that this build
does not ship. … every other file was checked normally.
5 issues (1 error, 4 warnings) across 4 files

Two things that looked correct and were not

• Vale honours exactly one --glob, last-wins. Two flags silently drop the first.
• --glob matches the basename only when the pattern has no /. Combined with the existing .taskless/** exclusion the expression goes path-wise, at which point a bare *.adoc excluded root-level d.adoc but not docs/e.adoc — a fix that looks right in whichever directory you happened to test it in. Hence **/*.adoc. Both are now pinned by tests.

Assert known support, with one deliberate inversion

The operative list is the converter tier, not a native allowlist. Vale lints far more than markup — source comments, plain text, and extensionless files (README, LICENSE, Makefile) — so a positive allowlist would have to enumerate every language Vale knows and would still drop every extensionless file, trading a loud crash for silent disabling across a much larger set. Unknown-to-us is safe because it is unknown-to-Vale.

The assert-known-support property is carried instead by the table naming what was measured, the exclusion being derived from it so the two cannot drift, and a per-extension test that re-measures every row against the real binary.

The exclusion applies even to explicitly named paths, overriding the prior "an explicit path is a request" rule in run.ts. Justified in-comment: honouring the request does not check that file badly, it costs the user the rest of their check.

Vale's stderr JSON is now also decoded to a sentence (E201: 'level' must be one of [...] in .../bogus.yml), preserving the error code — following decode-sg-stderr.md.

Reconciliation with capabilities.ts

This branch and #155 independently measured Vale's tiers and produced two tables. The second commit merges them into one record in capabilities.ts, with the converter name riding in the tier ("converter:asciidoctor") so one row states both the tier and the program to install — adding an extension is one line in one file. formats.ts now holds no data at all; everything derives, and a test asserts the derivation.

Both tables were wrong about different things, which is a decent argument for having built them independently:

	verdict	evidence
.asc, .rest	converter-dependent — missing from capabilities.ts	exit 2, E100 [lintAdoc] / [lintRST]
.tex, .rmd	plaintext, not native — overclaimed here	lints its own % comment / an R chunk, where .md skips a fence
.mkd, .mkdn	plaintext, not native — overclaimed here	lint through a fence, an HTML comment and an indented block
.mdown	native — missing from capabilities.ts	fence/comment/indent all yield 0
.ditamap	plaintext, deliberately not excluded	exit 0; excluding it would drop a file Vale lints fine

The .mkd/.mkdn error was the more expensive direction: calling them markup promises a scope: that has nothing to act on.

A per-extension probe now covers every row (probes every row of VALE_FORMAT_TIERS asserts set-equality between the table's keys and what the suites measure), so a row cannot be added without being measured. The old bare-prose tier loop was removed rather than kept — bare prose cannot discriminate any of the three readable tiers, and leaving it would let a weaker fixture overrule a stronger one.

MDX and the next bump

MDX is described as not supported yet, with Vale 3.18.0 parsing it natively and a CLI update expected to carry it. No date promised — a test asserts the recipe contains no 20NN-NN.

⚠️ 3.18.0 also adds a Typst converter (typst2vast). .typ is plaintext today, so a bump without re-measuring walks straight back into this bug under a new extension. The table's doc comment carries that warning and names both known 3.18.0 moves (.typ → converter, .mdx → markup). Vale updates within the 0.11.x lineage, separately from this fix.

On textlint

There is no recorded comparison anywhere — zero mentions of textlint, proselint, LanguageTool or alex in the working tree, all history, all 40 archived changes. Vale appears already chosen, on gap-filling grounds plus one substantive criterion: its Tengo sandbox exposes only text/math/fmt, so a Vale rule is inert data, which is what lets it ship static-tier with no login gate.

The converter gap is a real dent in the "self-sufficient binary" reasoning that decision rested on — it anticipated engine-level unavailability, not a per-file input killing an available engine mid-run. But textlint's rules are JavaScript, which cannot be static-tier; they would need the runtime harness, signing, and a login. That is the load-bearing property and Vale wins on it. Not close to justifying a migration; worth recording in the spec.

OpenSpec: none

cli-vale-rule-engine already requires that engine trouble is reported and does not abort the run. The crash violated that; the fix restores it. One caveat flagged rather than papered over: the spec says a rule's scope is expressed through its own matchers, and this narrows that above the user's config, including for explicitly named paths. If that should be recorded, the natural home is next to "Vale check executes against an assembled run config over the target paths."

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[thecodedrift]

@claude /review

[claude]

Claude finished @thecodedrift's task in 6m 33s —— View job

---

I'll analyze this and get back to you.

[thecodedrift]

@claude /review

The earlier review on this PR stopped before posting findings (the checklist above is unfinished), and the branch has changed since — it was rebased onto a corrected base and carries new commits. Please review the current head.

[claude]

Claude finished @thecodedrift's task in 3m 14s —— View job

---

Review mode: incremental — read 1 prior review thread(s) before reviewing.

.prior-review.json contained no reviewThreads, no prior review body with findings, and only the two @claude /review comments plus a Copilot quota-limit failure — so this is effectively the first substantive review of this PR. Nothing to mark as already-addressed.

I read the full diff against origin/fix/engine-capabilities plus the whole of formats.ts, run.ts, and the relevant parts of capabilities.ts, and ran four independent review passes (line-by-line diff scan, removed-behavior audit, cross-file tracer, reuse/simplification/efficiency pass).

Findings posted inline

1. [New] packages/cli/src/rules/vale/formats.ts:131 — converterExclusionGlobs() builds the --glob exclusion from all-lowercase extensions with no case normalization, while the sibling converterFor() (line 114) deliberately lowercases with a doc comment explaining why case matters. Two independent passes converged on this. If Vale's own extension routing is case-insensitive (which is the premise converterFor's own comment relies on), an uppercase-extension file such as GUIDE.ADOC would bypass the exclusion and reproduce the exact whole-run-crash bug this PR fixes. Untested either way — no fixture exercises an uppercase converter-dependent extension end-to-end.
2. [New] packages/cli/src/rules/vale/formats.ts:181-183 — the same case-sensitivity gap in the directory-walk glob used to build the skip notice, which would leave the crash in finding 1 with no explanatory notice for files reached via traversal (as opposed to being named explicitly).
3. [New] packages/cli/src/rules/vale/run.ts:209-211 — the pre-computed skip notice (skipped) is only attached to the ok outcome; it's silently dropped on the failed/timeout branches even though it was already computed. Low severity (the check still fails either way) but looks inconsistent with ValeRunOutcome's own stated intent to always surface the notice.

Considered and not posted inline

• A cosmetic ordering break in the "comment" tier list in capabilities.ts (.bsh lands between .c++/.cc instead of before .c) — affects only agent-facing prompt prose, not pinned by any test, no functional effect.
• Several reuse/efficiency observations (a third bespoke "directories to skip while walking" list alongside detect/scan.ts's IGNORED_DIRECTORIES; findConverterDependentFiles awaited serially before the Vale subprocess spawns rather than run concurrently; redundant named/roots array tracking in the same function) — all real but minor, no correctness impact, and the module's own doc comments already acknowledge the relevant tradeoffs (e.g. the duplicate tree-walk cost).
• The "Vale skips dot-directories, so this never lets the crash back in" claim in the findConverterDependentFiles doc comment (lines 172-175) is asserted but not verified against the real binary — flagged as a coverage gap by one pass, not a demonstrated bug.

Everything else — the single---glob merge, describeValeStderr's fallback behavior, the tier-table derivation and its set-equality test, the MDX/Typst version-bump warning — checked out against the PR's stated invariants and existing real-binary tests.

[claude]

[New] Correctness — the exclusion glob is case-sensitive, but converterFor (used to name the same files) is deliberately case-insensitive

converterFor at line 114 lowercases extname(path) specifically because, per its own doc comment, "letting case decide would make the crash reappear on exactly one platform." But converterExclusionGlobs() here builds the --glob patterns straight from CONVERTER_DEPENDENT_EXTENSIONS (all lowercase, per capabilities.ts's VALE_FORMAT_TIERS keys) with no case handling, and hands them to Vale's own --glob matcher — which the PR's own buildValeGlob docstring establishes does literal string matching.

If Vale's own extension→parser routing is case-insensitive (which is exactly what converterFor's comment assumes is true of Vale's model), a file like docs/GUIDE.ADOC would still be routed to asciidoctor by Vale but not excluded by this glob — reproducing the exact crash-that-takes-down-every-finding bug this PR exists to fix, on any filesystem, not just a case-insensitive one.

converterFor is only exercised for case-insensitivity in vale-formats.test.ts (converterFor("docs/README.RST")); nothing exercises converterExclusionGlobs() or an end-to-end runVale() with an uppercase-extension fixture. Worth either lowercasing here to match converterFor, or confirming against the real binary that Vale's routing is case-sensitive (in which case the asymmetry is harmless, but the comment on converterFor would then be misleading about why the lowercasing there matters).

[claude]

[New] Correctness — same case-sensitivity gap in the directory-walk glob used to build the skip notice

Same root cause as the converterExclusionGlobs() comment on line 131: extensions is built from the all-lowercase CONVERTER_DEPENDENT_EXTENSIONS with no case normalization, and feeds the glob() pattern at line 202. For a file reached via directory traversal (as opposed to being named explicitly, which correctly goes through the lowercasing converterFor at line 193), an uppercase-extension file like docs/GUIDE.ADOC is never matched.

This compounds the exclusion-glob issue: if docs/GUIDE.ADOC isn't excluded from Vale's run (per the other comment) and isn't found here, skippedFilesNotice never mentions it — the user gets a hard crash with no explanation, which the module's own doc comment (lines 160-163) calls out as the exact failure mode this file exists to prevent ("a fix whose entire user experience is 'some findings are quietly not there' would be the bug again one layer down").

[claude]

[New] Minor — the pre-computed skip notice is silently dropped on a failed/timeout outcome

skipped is computed unconditionally before the run, but it's only attached to the notice field on the ok path (lines 316-323, used at 331/361). The failed branches (297, 347, 364) and the timeout branch (256) never reference it, so if a repo has both converter-dependent files (correctly excluded) and, say, an unrelated config error elsewhere, the user sees only the config-error message — the "N files were not checked because this build can't parse them" notice that was already computed is thrown away.

Low severity since the check fails regardless (nothing goes silently green), but ValeRunOutcome's own doc comment (lines 70-76) frames the notice as important enough to always surface, so this looks like an inconsistency rather than a deliberate choice. Worth confirming intent, or including skipped in the failure/timeout messages too.