fix(cli): state converter-backed formats as unsupported, not as needing a tool

Maintainer decision: we do not offer support for any Vale format that
parses through an external program.

The skip notice used to end "Install it and put it on your PATH to have
these files checked." That offered a path this build does not ship and does
not test, and for `.xml` cannot deliver at all — an XSLT stylesheet is
specific to the document, so no install makes it lintable. It also made
behaviour host-dependent: macOS ships /usr/bin/xsltproc and typical Linux
CI images do not, so the same repository checked differently depending on
the machine. That split is what made this stack red in CI while green
locally, which is the strongest argument for excluding unconditionally: a
repository should check the same way everywhere.

The exclusion mechanism is unchanged — it is what prevents the total-run
crash. What changed is the promise. The programs are still named, as the
reason rather than as a remedy, and the recipes now say plainly that
installing them does not change the answer.

The cost, accepted: a user who genuinely has asciidoctor installed loses
`.adoc` checking that would have worked.

Also reconciles the comment tier against Vale's own documentation, and
sharpens the version-bump note now that the 3.18.0 picture is confirmed:
`.mdx` gains a native parser and becomes supported, `.typ` gains one that
shells out to typst2vast and so stays unsupported permanently, and MyST,
Quarto and QDoc arrive needing no external program. All four require
3.18.0, so none is reachable from the pinned 3.17.1.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Cyga14bww8rmazH2XrF8ms

Author: theCodeDrift

.changeset/vale-converter-formats.md

@@ -48,3 +48,24 @@ expression goes path-wise, at which point a bare `*.adoc` stops matching
 tested. Vale's error output is also decoded now rather than forwarded verbatim,
 so a failure reads as a sentence naming the missing program instead of a
 five-field JSON object.
+
+**These formats are now stated as unsupported rather than as needing a tool.**
+The notice used to end "Install it and put it on your PATH to have these files
+checked", which offered a path this build does not ship, does not test, and for
+`.xml` cannot deliver — an XSLT stylesheet is specific to the document, so no
+install makes it lintable. It also made behaviour host-dependent: macOS ships
+`/usr/bin/xsltproc` and typical Linux CI images do not, so the same repository
+checked differently depending on the machine. The exclusion is unconditional
+for that reason, and the programs are still named as the reason rather than as
+a remedy.
+
+The comment tier was reconciled against Vale's own documentation at
+docs.vale.sh/formats/code, which adds `.bsh`, `.csx`, `.pod`, `.py3` and `.sbt`
+once measured. It also documents `.pyi`, `.qml` and `.scss` as comment-aware,
+and on the pinned 3.17.1 a bare non-comment line in each of them lints — so they
+stay in the plaintext tier. That divergence is the argument for probing rather
+than transcribing: the docs describe the current Vale, this build pins an older
+one, and copying the list would have shipped `.scss` as comment-aware and been
+wrong. `.pod` is a reminder of how easily this is misread — it lints Perl
+comments but not POD blocks, so probing it with `=head1` looks like no support
+at all.

packages/cli/src/agent/create-vale-rule.txt

@@ -316,11 +316,16 @@ it.
      not what the rule means, narrow the glob rather than accepting it.
      These land here despite reading like markup, so a `scope:` value
      has nothing to act on in them: %(VALE_PLAINTEXT_FORMATS)s
-   - **cannot be read at all** — Vale supports these formats but shells
-     out to an external converter to parse them, and this CLI ships none
-     of those converters:
+   - **not supported** — Vale parses these only by shelling out to an
+     external program, and this build does not support any format that
+     needs one:
      %(VALE_CONVERTER_FORMATS)s
 
+     Do not tell the user to install the program. Taskless excludes these
+     files from the run whatever is installed, so that a repository
+     checks the same way on every machine; `.xml` could not work anyway,
+     since an XSLT stylesheet is specific to the document.
+
    **A single unreadable file fails the whole Vale pass.** Vale exits 2
    with an `E100` runtime error and abandons the run — `--no-exit` does
    not suppress it — so every other Vale rule over every other file goes

packages/cli/src/agent/route.txt

@@ -124,11 +124,16 @@ answered together.
        scoped to YAML flags the code as readily as the comments. That is
        rarely what was asked for — say so before writing it. These read
        like markup and are not: %(VALE_PLAINTEXT_FORMATS)s
-     - *cannot be read at all* — Vale supports these formats but shells
-       out to an external converter to parse them, and this CLI ships
-       none of those converters:
+     - *not supported* — Vale parses these only by shelling out to an
+       external program, and this build does not support any format that
+       needs one:
        %(VALE_CONVERTER_FORMATS)s
 
+       Installing the program does not change this. Taskless excludes
+       these files from the Vale run whatever is on the machine, so that
+       a repository checks the same way everywhere rather than depending
+       on what a given host happens to have available.
+
        **One such file fails the entire Vale pass, not just that file.**
        Vale exits 2 with an `E100` runtime error, `--no-exit` does not
        suppress it, and every other Vale rule over every other file goes

packages/cli/src/rules/capabilities.ts

@@ -156,11 +156,24 @@ const CONVERTER_TIER_PREFIX = "converter:";
  * are a property of {@link VALE_VERSION}'s binary, and the dangerous direction
  * is a format Vale *learns*: an extension missing from this table is read as
  * plain text today, but the moment Vale routes it to a converter the same
- * omission is a crash that takes down every Vale rule in the run. Vale 3.18.0
- * is the known incoming case in both directions — it parses MDX natively, and
- * it adds a Typst converter, so `.typ` moves from `plaintext` to
- * `converter:typst2vast` on that bump while `.mdx` moves to `markup`. Neither
- * happens on its own; re-probe every row.
+ * omission is a crash that takes down every Vale rule in the run.
+ *
+ * Vale 3.18.0 is the known incoming bump, and it moves rows in three different
+ * directions — which is why "re-measure" is not boilerplate here:
+ *
+ * - `.mdx` gains a native parser, so it moves `converter:mdx2vast` → `markup`
+ *   and becomes supported.
+ * - `.typ` gains a parser that shells out to `typst2vast`
+ *   (https://docs.vale.sh/formats/typst), so it moves `plaintext` →
+ *   `converter:typst2vast`. That is the dangerous direction: today it is read
+ *   as prose, and after the bump the same row would crash the run. It also
+ *   stays unsupported permanently, since we do not support formats needing an
+ *   external program.
+ * - MyST, Quarto and QDoc arrive with parsers needing no external program, so
+ *   they become genuinely supportable and want `markup` rows once measured.
+ *
+ * All four are documented as requiring v3.18.0 or later, so none of them is
+ * reachable from {@link VALE_VERSION}. Re-probe every row on the bump.
  */
 export const VALE_FORMAT_TIERS: Readonly<Record<string, ValeFormatTier>> = {
   // markup — parsed, the format's own constructs skipped
@@ -174,11 +187,13 @@ export const VALE_FORMAT_TIERS: Readonly<Record<string, ValeFormatTier>> = {
   // comment text only — the code body is invisible
   ".c": "comment",
   ".c++": "comment",
+  ".bsh": "comment",
   ".cc": "comment",
   ".clj": "comment",
   ".cpp": "comment",
   ".cs": "comment",
   ".css": "comment",
+  ".csx": "comment",
   ".cxx": "comment",
   ".go": "comment",
   ".h": "comment",
@@ -194,15 +209,18 @@ export const VALE_FORMAT_TIERS: Readonly<Record<string, ValeFormatTier>> = {
   ".php": "comment",
   ".pl": "comment",
   ".pm": "comment",
+  ".pod": "comment",
   ".proto": "comment",
   ".ps1": "comment",
   ".py": "comment",
+  ".py3": "comment",
   ".pyw": "comment",
   ".r": "comment",
   ".R": "comment",
   ".rb": "comment",
   ".rs": "comment",
   ".sass": "comment",
+  ".sbt": "comment",
   ".scala": "comment",
   ".swift": "comment",
   ".ts": "comment",
@@ -213,6 +231,14 @@ export const VALE_FORMAT_TIERS: Readonly<Record<string, ValeFormatTier>> = {
   ".rmd": "plaintext",
   ".tex": "plaintext",
   ".typ": "plaintext",
+  // plaintext HERE, though Vale's own docs list them as comment-tier. The docs
+  // describe the CURRENT Vale; we pin 3.17.1. Measured on the pinned binary a
+  // bare non-comment line lints, which is the plaintext signature. Transcribing
+  // the docs would have shipped these as comment-tier and been wrong for this
+  // build — the case for probing rather than copying.
+  ".pyi": "plaintext",
+  ".qml": "plaintext",
+  ".scss": "plaintext",
   // converter-dependent — Vale supports the format, we ship no converter
   ".adoc": "converter:asciidoctor",
   ".asc": "converter:asciidoctor",

packages/cli/src/rules/vale/formats.ts

@@ -81,11 +81,16 @@ export const TASKLESS_DIRECTORY = ".taskless";
  * Vale": the moment Vale learns a format, it starts routing that extension to a
  * parser, and if that parser shells out, an extension missing from the table is
  * a crash rather than a plain-text read. Vale 3.18.0 is the live example — it
- * adds Typst, which converts through `typst2vast`, so `.typ` stops being the
+ * adds Typst, which parses through `typst2vast`, so `.typ` stops being the
  * plaintext read it is today and upgrading the `@taskless/vale-*` packages
  * without re-measuring would reintroduce exactly this bug under a new
  * extension. Re-measure the whole table on every bump; the per-extension cases
  * in `vale-vendor-contract.test.ts` are how.
+ *
+ * Note what the exclusion policy buys here. Because a format needing an
+ * external program is never supported, a newly-converter-backed extension has
+ * one correct destination rather than a judgement call, and the answer does not
+ * depend on what happens to be installed on the machine running `check`.
  */
 
 /**
@@ -240,10 +245,10 @@ export function skippedFilesNotice(files: string[]): string | undefined {
       : sample.join(", ");
 
   return (
-    `Vale did not check ${String(files.length)} file(s): ${listed}. Vale ` +
-    `supports these formats, but parsing them needs an external converter ` +
-    `(${converters.join(", ")}) that this build does not ship. Install it and ` +
-    `put it on your PATH to have these files checked; every other file was ` +
-    `checked normally.`
+    `Vale did not check ${String(files.length)} file(s): ${listed}. These ` +
+    `formats are not supported by this build — Vale parses them only through ` +
+    `an external program (${converters.join(", ")}), which this build does ` +
+    `not ship and does not check for. Scope the rule to a supported format; ` +
+    `every other file was checked normally.`
   );
 }

packages/cli/test/vale-formats.test.ts

@@ -153,16 +153,25 @@ describe("the skipped-files notice", () => {
     expect(skippedFilesNotice([])).toBeUndefined();
   });
 
-  it("names the files, the converter, and that the rest was checked", () => {
-    const notice = skippedFilesNotice(["docs/guide.adoc", "spec/api.rst"]);
+  it("names the files and says the format is unsupported, not that a tool is missing", () => {
+    const notice =
+      skippedFilesNotice(["docs/guide.adoc", "spec/api.rst"]) ?? "";
     expect(notice).toContain("docs/guide.adoc");
     expect(notice).toContain("spec/api.rst");
+    expect(notice).toContain("every other file was checked normally");
+    // The programs are still named — they are the REASON, and a user reading
+    // "asciidoctor" understands what kind of gap this is.
     expect(notice).toContain("asciidoctor");
     expect(notice).toContain("rst2html");
-    expect(notice).toContain("every other file was checked normally");
-    // Vale supports these formats; this build cannot parse them. Telling a user
-    // otherwise sends them to the wrong project's issue tracker.
-    expect(notice).toContain("Vale supports these formats");
+    // But the notice must not read as an offer. We do not support any format
+    // that needs an external program, so telling a user to install one promises
+    // a path that is untested, and for `.xml` impossible — an XSLT stylesheet is
+    // specific to the document. It would also make behaviour host-dependent:
+    // macOS ships /usr/bin/xsltproc and Linux CI images do not, so the same
+    // repository would check differently per machine.
+    expect(notice).toContain("not supported by this build");
+    expect(notice).not.toMatch(/install/i);
+    expect(notice).not.toMatch(/\bPATH\b/);
   });
 
   it("summarizes rather than printing an unbounded file list", () => {

packages/cli/test/vale-vendor-contract.test.ts

@@ -395,13 +395,21 @@ withVale("Vale vendor contract", () => {
  * See taskless/cli#151.
  */
 /** The comment syntax Vale must see through, per extension. */
+/**
+ * A correct comment for `extension`, which is the whole difficulty of this
+ * file: a wrong delimiter reads exactly like absent support. `.css` looks
+ * unsupported if fed `//` and is comment-aware with a block comment; `.pod` is
+ * linted as Perl, so a `#` comment fires while a `=head1` POD block does not.
+ */
 function comment(extension: string): string {
   const HASH = new Set([
     ".jl",
     ".pl",
     ".pm",
     ".ps1",
+    ".pod",
     ".py",
+    ".py3",
     ".pyw",
     ".r",
     ".R",
@@ -546,6 +554,11 @@ withVale("Vale engine capabilities", () => {
     ".rmd": "Fine.\n\n```{r}\nsimply <- 1\n```\n",
     ".tex": "% simply in a comment\nFine.\n",
     ".typ": "// simply\nFine.\n",
+    // Documented by Vale as comment-aware, measured as plaintext on the pinned
+    // binary — the construct here is the comment a parser would have skipped.
+    ".pyi": "# simply\nFine.\n",
+    ".qml": "// simply\nFine.\n",
+    ".scss": "// simply\nFine.\n",
   };
 
   it("covers every extension in VALE_PLAINTEXT_EXTENSIONS", () => {