From 735399401bad37e8a40b82abca9b0606957694fc Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 07:56:28 +0000 Subject: [PATCH 1/6] chore(vale): release Vale 3.27.0 --- .changeset/vale-3-27-0.md | 5 ++ packages/cli/package.json | 12 ++-- .../src/generated/vale-vocabulary-report.md | 12 ++-- packages/cli/src/generated/vale-vocabulary.ts | 14 ++--- packages/cli/src/rules/capabilities.ts | 2 +- pnpm-lock.yaml | 60 +++++++++---------- 6 files changed, 55 insertions(+), 50 deletions(-) create mode 100644 .changeset/vale-3-27-0.md diff --git a/.changeset/vale-3-27-0.md b/.changeset/vale-3-27-0.md new file mode 100644 index 00000000..3e383784 --- /dev/null +++ b/.changeset/vale-3-27-0.md @@ -0,0 +1,5 @@ +--- +"@taskless/cli": patch +--- + +Update the bundled Vale to 3.27.0. diff --git a/packages/cli/package.json b/packages/cli/package.json index 5dbfed57..3373758c 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -92,11 +92,11 @@ "@ast-grep/cli-win32-arm64-msvc": "0.51.3", "@ast-grep/cli-win32-ia32-msvc": "0.51.3", "@ast-grep/cli-win32-x64-msvc": "0.51.3", - "@taskless/vale-darwin-arm64": "3.26.0-20261102164455", - "@taskless/vale-darwin-x64": "3.26.0-20261102164455", - "@taskless/vale-linux-arm64": "3.26.0-20261102164455", - "@taskless/vale-linux-x64": "3.26.0-20261102164455", - "@taskless/vale-win32-arm64": "3.26.0-20261102164455", - "@taskless/vale-win32-x64": "3.26.0-20261102164455" + "@taskless/vale-darwin-arm64": "3.27.0-20261117230017", + "@taskless/vale-darwin-x64": "3.27.0-20261117230017", + "@taskless/vale-linux-arm64": "3.27.0-20261117230017", + "@taskless/vale-linux-x64": "3.27.0-20261117230017", + "@taskless/vale-win32-arm64": "3.27.0-20261117230017", + "@taskless/vale-win32-x64": "3.27.0-20261117230017" } } diff --git a/packages/cli/src/generated/vale-vocabulary-report.md b/packages/cli/src/generated/vale-vocabulary-report.md index dc0e02e3..75f82a4a 100644 --- a/packages/cli/src/generated/vale-vocabulary-report.md +++ b/packages/cli/src/generated/vale-vocabulary-report.md @@ -1,10 +1,10 @@ -# Vale 3.26.0 vocabulary: divergence report +# Vale 3.27.0 vocabulary: divergence report GENERATED FILE — DO NOT EDIT. Produced by `pnpm generate:vale-schema` alongside `vale-vocabulary.ts`. Every value in the vocabulary is the recorded answer of the vendored Vale -3.26.0 binary. This file is what the binary said that its own +3.27.0 binary. This file is what the binary said that its own documentation does not, in both directions. A generator that dropped these would be quietly deciding which of the two to believe. @@ -28,25 +28,25 @@ the worse failure. ### `scope: meta` -Vale 3.26.0 documents this operand and it never fired, on any fixture probed (.md). +Vale 3.27.0 documents this operand and it never fired, on any fixture probed (.md). **Consequence.** It is omitted from the vocabulary, so `validate` rejects it. A rule written from the documentation would otherwise load, run, and match nothing, with no error reported anywhere. ### `scope: meta.class.title` -Vale 3.26.0 documents this operand and it never fired, on any fixture probed (.md). +Vale 3.27.0 documents this operand and it never fired, on any fixture probed (.md). **Consequence.** It is omitted from the vocabulary, so `validate` rejects it. A rule written from the documentation would otherwise load, run, and match nothing, with no error reported anywhere. ### `scope: frontmatter` -This operand fired and Vale 3.26.0 documents it nowhere. +This operand fired and Vale 3.27.0 documents it nowhere. **Consequence.** It is included in the vocabulary. It is also the standing counterexample to trusting the candidate list: a real operand nobody proposes is simply absent, and the schema then rejects a rule the binary honors. ### `scope: frontmatter.title` -This operand fired and Vale 3.26.0 documents it nowhere. +This operand fired and Vale 3.27.0 documents it nowhere. **Consequence.** It is included in the vocabulary. It is also the standing counterexample to trusting the candidate list: a real operand nobody proposes is simply absent, and the schema then rejects a rule the binary honors. diff --git a/packages/cli/src/generated/vale-vocabulary.ts b/packages/cli/src/generated/vale-vocabulary.ts index 0d5d477d..51e42650 100644 --- a/packages/cli/src/generated/vale-vocabulary.ts +++ b/packages/cli/src/generated/vale-vocabulary.ts @@ -6,7 +6,7 @@ * `scripts/generate-vale-schema.ts`, and its header explains what each value * below was measured with and what it is worth. * - * Derived against Vale 3.26.0. Every value here is the recorded answer + * Derived against Vale 3.27.0. Every value here is the recorded answer * of that binary to a rule the generator wrote and ran; nothing is transcribed * from documentation. Where the binary and the documentation disagree, the * disagreement is in `vale-vocabulary-report.md` rather than dropped. @@ -15,7 +15,7 @@ */ /** The binary this vocabulary was derived from. */ -export const VALE_VOCABULARY_VERSION = "3.26.0"; +export const VALE_VOCABULARY_VERSION = "3.27.0"; /** * Vale's check types, self-enumerated: an unknown `extends` makes the binary @@ -199,7 +199,7 @@ export const VALE_SCOPE_PREFIXES = [ ] as const; /** - * Where Vale 3.26.0 and its documentation disagree. + * Where Vale 3.27.0 and its documentation disagree. * * Carried in the artifact rather than only in the report, so that a consumer * can render them and a reviewer cannot miss them in a diff. @@ -208,26 +208,26 @@ export const VALE_DIVERGENCES = [ { subject: "scope: meta", finding: - "Vale 3.26.0 documents this operand and it never fired, on any fixture probed (.md).", + "Vale 3.27.0 documents this operand and it never fired, on any fixture probed (.md).", consequence: "It is omitted from the vocabulary, so `validate` rejects it. A rule written from the documentation would otherwise load, run, and match nothing, with no error reported anywhere.", }, { subject: "scope: meta.class.title", finding: - "Vale 3.26.0 documents this operand and it never fired, on any fixture probed (.md).", + "Vale 3.27.0 documents this operand and it never fired, on any fixture probed (.md).", consequence: "It is omitted from the vocabulary, so `validate` rejects it. A rule written from the documentation would otherwise load, run, and match nothing, with no error reported anywhere.", }, { subject: "scope: frontmatter", - finding: "This operand fired and Vale 3.26.0 documents it nowhere.", + finding: "This operand fired and Vale 3.27.0 documents it nowhere.", consequence: "It is included in the vocabulary. It is also the standing counterexample to trusting the candidate list: a real operand nobody proposes is simply absent, and the schema then rejects a rule the binary honors.", }, { subject: "scope: frontmatter.title", - finding: "This operand fired and Vale 3.26.0 documents it nowhere.", + finding: "This operand fired and Vale 3.27.0 documents it nowhere.", consequence: "It is included in the vocabulary. It is also the standing counterexample to trusting the candidate list: a real operand nobody proposes is simply absent, and the schema then rejects a rule the binary honors.", }, diff --git a/packages/cli/src/rules/capabilities.ts b/packages/cli/src/rules/capabilities.ts index 05d631a2..65736580 100644 --- a/packages/cli/src/rules/capabilities.ts +++ b/packages/cli/src/rules/capabilities.ts @@ -212,7 +212,7 @@ export const AST_GREP_TSX_SPLIT: Readonly< * Pinned against the binary by `test/vale-vendor-contract.test.ts` * ("engine capabilities" → "reports the pinned version"). */ -export const VALE_VERSION = "3.26.0"; +export const VALE_VERSION = "3.27.0"; /** * Which tier Vale routes an extension to. diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index d33f6460..60cb7963 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -164,23 +164,23 @@ importers: specifier: 0.51.3 version: 0.51.3 '@taskless/vale-darwin-arm64': - specifier: 3.26.0-20261102164455 - version: 3.26.0-20261102164455 + specifier: 3.27.0-20261117230017 + version: 3.27.0-20261117230017 '@taskless/vale-darwin-x64': - specifier: 3.26.0-20261102164455 - version: 3.26.0-20261102164455 + specifier: 3.27.0-20261117230017 + version: 3.27.0-20261117230017 '@taskless/vale-linux-arm64': - specifier: 3.26.0-20261102164455 - version: 3.26.0-20261102164455 + specifier: 3.27.0-20261117230017 + version: 3.27.0-20261117230017 '@taskless/vale-linux-x64': - specifier: 3.26.0-20261102164455 - version: 3.26.0-20261102164455 + specifier: 3.27.0-20261117230017 + version: 3.27.0-20261117230017 '@taskless/vale-win32-arm64': - specifier: 3.26.0-20261102164455 - version: 3.26.0-20261102164455 + specifier: 3.27.0-20261117230017 + version: 3.27.0-20261117230017 '@taskless/vale-win32-x64': - specifier: 3.26.0-20261102164455 - version: 3.26.0-20261102164455 + specifier: 3.27.0-20261117230017 + version: 3.27.0-20261117230017 packages/vale-darwin-arm64: {} @@ -891,33 +891,33 @@ packages: '@standard-schema/spec@1.1.0': resolution: {integrity: sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==} - '@taskless/vale-darwin-arm64@3.26.0-20261102164455': - resolution: {integrity: sha512-xr26EEnknO0gUrIK2bnUbNFjPF+dA++Wqeb/r/GN98moa6BqTNwAiZD+Gc+KEarhSWInxJMSTatLdCEP3vAEFg==} + '@taskless/vale-darwin-arm64@3.27.0-20261117230017': + resolution: {integrity: sha512-O4zVJ57nleFPhdpIMUC6pGDBdmNmlrHwyZgXOQo9/8dlQv2cXEuj9Wa9fWUmDcia//+T5Teh8jC0qVG6Quzqkg==} cpu: [arm64] os: [darwin] - '@taskless/vale-darwin-x64@3.26.0-20261102164455': - resolution: {integrity: sha512-swP5oYGaOeaNNHNxnxBoOSa1yEbPomrcvTRZe2efQcc6DNg6U/FdGm2tGJ/0QKVfdQtDP0sI3pYfPcyevfIRFQ==} + '@taskless/vale-darwin-x64@3.27.0-20261117230017': + resolution: {integrity: sha512-ct+yVvRqxny3En5q+nz3gwUm5cRtwo5Za2cjgqhrks31ss0qn8TB8uzkZ6L7G1NodEgeupnlYuyxAPrdgJkIXg==} cpu: [x64] os: [darwin] - '@taskless/vale-linux-arm64@3.26.0-20261102164455': - resolution: {integrity: sha512-hHGaE5ohR3Cl3KggoJlVp+hsrRZQKiXZyY/s73QmHgV8qaIj2oZLYYjPbfJyo+YERHVemlZBAnzEesXe/NuuaQ==} + '@taskless/vale-linux-arm64@3.27.0-20261117230017': + resolution: {integrity: sha512-xePLv6AYtEHu0P1taxFsjIlXkQ8P9XbZqsqRMZpoKKUXU/938/muo7SIRNXHzIQPBAGBCUpDOXyAyGr0tvQzfA==} cpu: [arm64] os: [linux] - '@taskless/vale-linux-x64@3.26.0-20261102164455': - resolution: {integrity: sha512-ULZPna6eb3hX8RsHte3GphvR9aTH9zKvV+D86RQM2mOg/z73qpgfRBdi3LNfA2vbpOPCGtz/keEFEcmREGFciQ==} + '@taskless/vale-linux-x64@3.27.0-20261117230017': + resolution: {integrity: sha512-QN+7lYUQ96+HBZ2bpQ1LkV7w1ILNTziVp1fZ7Bnez4W6dQT0cMGx9adTBQmS/qdrt4v1tHGGF6TmueM4EUGTSQ==} cpu: [x64] os: [linux] - '@taskless/vale-win32-arm64@3.26.0-20261102164455': - resolution: {integrity: sha512-1p8pqygEkReBAzEwH8HorqZGnCqF9z34BXqiHta84ajrdo/skKog/9fm7MfDrriGaF8ObJiclUX6zCPOOhQp7A==} + '@taskless/vale-win32-arm64@3.27.0-20261117230017': + resolution: {integrity: sha512-IfAuEEXv1VIPaZL5wmQUYURnmfSH7hmUtfk7mpl49Qtm0Xrqj92YjqWwUmePdQvH/NFhYT/XJsfDnvmZtr2jIA==} cpu: [arm64] os: [win32] - '@taskless/vale-win32-x64@3.26.0-20261102164455': - resolution: {integrity: sha512-S8ViSg3PZvJjrC0ClNuwmdYwmOnAxaOMxi6HlYSHgsnsXbf/0/ddf/oAGi/3FMXNh4PSUxyczZurGTcbu3DRqA==} + '@taskless/vale-win32-x64@3.27.0-20261117230017': + resolution: {integrity: sha512-RQxtyT1I3H432HNR1SToLsyjKmKkFnFjP5jFrkTJY8Y536fbsJieWgRAUBPK8MeDHkbjc4J7dali3a/cVhuMFw==} cpu: [x64] os: [win32] @@ -3376,22 +3376,22 @@ snapshots: '@standard-schema/spec@1.1.0': {} - '@taskless/vale-darwin-arm64@3.26.0-20261102164455': + '@taskless/vale-darwin-arm64@3.27.0-20261117230017': optional: true - '@taskless/vale-darwin-x64@3.26.0-20261102164455': + '@taskless/vale-darwin-x64@3.27.0-20261117230017': optional: true - '@taskless/vale-linux-arm64@3.26.0-20261102164455': + '@taskless/vale-linux-arm64@3.27.0-20261117230017': optional: true - '@taskless/vale-linux-x64@3.26.0-20261102164455': + '@taskless/vale-linux-x64@3.27.0-20261117230017': optional: true - '@taskless/vale-win32-arm64@3.26.0-20261102164455': + '@taskless/vale-win32-arm64@3.27.0-20261117230017': optional: true - '@taskless/vale-win32-x64@3.26.0-20261102164455': + '@taskless/vale-win32-x64@3.27.0-20261117230017': optional: true '@tybys/wasm-util@0.10.4': From 963c7a4c970f0ce0d652d1f652c54ed215aa38c2 Mon Sep 17 00:00:00 2001 From: Jakob Heuser Date: Thu, 19 Nov 2026 17:22:42 -0800 Subject: [PATCH 2/6] feat(vale): run Vale with the pinned grammars Pin @taskless/vale-grammars at the platform packages' exact version and resolve its grammars directory beside findValeBinary. Every Vale child gets VALE_GRAMMARS_PATH set to it, always replacing a value inherited from the user's shell, which would name grammars nobody pinned. The vendor contract spawns Vale in the same environment, and the six cases #703 failed pass again. The resolver and its spec are exported from @taskless/cli/node/runtimes, so a verifier runs Vale rules with the same grammars check does. --- .../changes/vale-grammars-package/tasks.md | 8 +- packages/cli/package.json | 1 + packages/cli/src/node/runtimes/index.ts | 40 ++++++++ packages/cli/src/rules/vale/grammars.ts | 96 +++++++++++++++++++ packages/cli/src/rules/vale/run.ts | 25 ++++- packages/cli/test/vale-grammars.test.ts | 64 +++++++++++++ .../cli/test/vale-vendor-contract.test.ts | 9 +- pnpm-lock.yaml | 8 ++ 8 files changed, 243 insertions(+), 8 deletions(-) create mode 100644 packages/cli/src/rules/vale/grammars.ts create mode 100644 packages/cli/test/vale-grammars.test.ts diff --git a/openspec/changes/vale-grammars-package/tasks.md b/openspec/changes/vale-grammars-package/tasks.md index da7b60dc..76b9ae34 100644 --- a/openspec/changes/vale-grammars-package/tasks.md +++ b/openspec/changes/vale-grammars-package/tasks.md @@ -25,10 +25,10 @@ Groups 1–3 are PR A, cut from `origin/main`. Group 4 is the maintainer's manua ## 5. CLI wiring (PR B) -- [ ] 5.1 Add `@taskless/vale-grammars` to `packages/cli/package.json` `dependencies` at the same exact version as the six platform pins, and regenerate `pnpm-lock.yaml`; verify with `pnpm install --frozen-lockfile`. -- [ ] 5.2 Add the grammar resolver beside `findValeBinary` (spec, per-process cache, miss as `{ path: undefined, tried }`); verify with unit tests for a resolved package and a missing one. -- [ ] 5.3 Set `VALE_GRAMMARS_PATH` in `spawnVale`'s child environment when the resolver returns a path; verify that the six #703 vendor-contract failures pass with no `VALE_GRAMMARS_PATH` in the test shell. -- [ ] 5.4 Export the grammar spec and resolver from `src/node/runtimes/index.ts` with a note in the entry's documentation; verify the build's export classification passes and `dist/node/runtimes/index.d.ts` declares both. +- [x] 5.1 Add `@taskless/vale-grammars` to `packages/cli/package.json` `dependencies` at the same exact version as the six platform pins, and regenerate `pnpm-lock.yaml`; verify with `pnpm install --frozen-lockfile`. +- [x] 5.2 Add the grammar resolver beside `findValeBinary` (spec, per-process cache, miss as `{ path: undefined, tried }`); verify with unit tests for a resolved package and a missing one. +- [x] 5.3 Set `VALE_GRAMMARS_PATH` in `spawnVale`'s child environment when the resolver returns a path; verify that the six #703 vendor-contract failures pass with no `VALE_GRAMMARS_PATH` in the test shell. +- [x] 5.4 Export the grammar spec and resolver from `src/node/runtimes/index.ts` with a note in the entry's documentation; verify the build's export classification passes and `dist/node/runtimes/index.d.ts` declares both. ## 6. Refusal and coverage (PR B) diff --git a/packages/cli/package.json b/packages/cli/package.json index 3373758c..abf7d6e9 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -56,6 +56,7 @@ "node": ">=22.22.0" }, "dependencies": { + "@taskless/vale-grammars": "3.27.0-20261117230017", "tsx": "^4.21.0" }, "devDependencies": { diff --git a/packages/cli/src/node/runtimes/index.ts b/packages/cli/src/node/runtimes/index.ts index 2064f990..12d8a112 100644 --- a/packages/cli/src/node/runtimes/index.ts +++ b/packages/cli/src/node/runtimes/index.ts @@ -115,3 +115,43 @@ export { } from "../../rules/platform-binary.js"; export { AST_GREP_BINARY } from "../../rules/ast-grep-binary.js"; export { VALE_BINARY } from "../../rules/vale/binary.js"; + +/** + * ## Vale needs its grammars too + * + * Since Vale 3.27.0 the tree-sitter grammars Vale uses to find comments in + * source code ship apart from the binary, as `@taskless/vale-grammars`, pinned + * at the same version as the platform packages. Without them Vale reads + * comments by their delimiters and reports different findings for the same + * rule: a `//nolint` line becomes prose, a one-line CSS comment is skipped. A + * verifier that runs a Vale rule over source code should name the same + * grammars `taskless check` does: + * + * ```ts + * import { + * VALE_BINARY, + * resolvePlatformBinary, + * resolveValeGrammars, + * } from "@taskless/cli/node/runtimes"; + * + * const vale = resolvePlatformBinary(VALE_BINARY); + * const grammars = resolveValeGrammars(); + * if (vale.path === undefined || grammars.path === undefined) { + * throw new Error("Vale or its grammars did not resolve"); + * } + * spawn(vale.path, argv, { + * env: { ...process.env, VALE_GRAMMARS_PATH: grammars.path }, + * }); + * ``` + * + * Set the variable even when one is already in the environment: Vale prefers + * a grammar in the StylesPath, then `VALE_GRAMMARS_PATH`, so an inherited + * value names grammars nobody pinned. A miss is reported as a value, like the + * binary's, so a verifier can fail closed. + */ +export { + resolveValeGrammars, + VALE_GRAMMARS, + type ValeGrammarsResolution, + type ValeGrammarsSpec, +} from "../../rules/vale/grammars.js"; diff --git a/packages/cli/src/rules/vale/grammars.ts b/packages/cli/src/rules/vale/grammars.ts new file mode 100644 index 00000000..6c004455 --- /dev/null +++ b/packages/cli/src/rules/vale/grammars.ts @@ -0,0 +1,96 @@ +import { readdirSync } from "node:fs"; +import { createRequire } from "node:module"; +import { dirname, resolve } from "node:path"; + +/** + * Where Vale's tree-sitter grammars are published. + * + * Since Vale 3.27.0 the grammars Vale uses to find comments in source code are + * WebAssembly modules shipped apart from the binary, and Vale normally installs + * them with `vale sync`. Without them it finds comments by their delimiters, + * which lints a `//nolint` directive as prose and misses a one-line CSS + * `/* … *\/` comment. `@taskless/vale-grammars` carries every grammar upstream + * publishes for the pinned Vale release, as one package for every platform, + * and the CLI pins it at the same exact version as the binary packages. + * + * Vale is told where they are through `VALE_GRAMMARS_PATH`, which it reads for + * any grammar the StylesPath does not hold, one grammar at a time. + */ +export interface ValeGrammarsSpec { + /** Human-readable name, for messages. */ + label: string; + /** The npm package that carries the grammar modules. */ + packageName: string; + /** The directory inside that package that holds `.wasm` files. */ + directory: string; +} + +export const VALE_GRAMMARS: ValeGrammarsSpec = { + label: "Vale grammars", + packageName: "@taskless/vale-grammars", + directory: "grammars", +}; + +/** + * The grammar directory, or why there is none. + * + * A miss is a value, not a throw, for the reason the binary resolver's is: + * `check` keeps running Vale without grammars (its `grammar … is not + * installed` warnings then reach the user as notices), while a verifier may + * want to fail closed. Each caller decides. + */ +export interface ValeGrammarsResolution { + /** Absolute path of the directory to name to Vale, or `undefined`. */ + path: string | undefined; + /** Locations searched, in order, for an actionable message. */ + tried: string[]; +} + +/** + * Locate the grammar directory of the installed grammar package. + * + * A directory that exists but holds no `.wasm` module is rejected: an empty or + * half-extracted install would otherwise be named to Vale and behave exactly + * like no grammars at all, with nothing saying why. + */ +export function resolveValeGrammars( + spec: ValeGrammarsSpec = VALE_GRAMMARS +): ValeGrammarsResolution { + const tried = [`${spec.packageName}/${spec.directory}`]; + let directory: string; + try { + const require = createRequire(import.meta.url); + directory = resolve( + dirname(require.resolve(`${spec.packageName}/package.json`)), + spec.directory + ); + } catch { + return { path: undefined, tried }; + } + tried[0] = directory; + try { + const hasModule = readdirSync(directory).some((entry) => + entry.endsWith(".wasm") + ); + return { path: hasModule ? directory : undefined, tried }; + } catch { + return { path: undefined, tried }; + } +} + +/** + * Resolution is cached for the process, a miss included, so every Vale run in + * one `check` names the same directory without repeating the search. + */ +let cached: ValeGrammarsResolution | undefined; + +/** The grammar directory the CLI names to Vale, cached for the process. */ +export function findValeGrammars(): ValeGrammarsResolution { + cached ??= resolveValeGrammars(); + return cached; +} + +/** Reset the process cache. Tests only. */ +export function resetValeGrammarsCache(): void { + cached = undefined; +} diff --git a/packages/cli/src/rules/vale/run.ts b/packages/cli/src/rules/vale/run.ts index 847f7659..fa395167 100644 --- a/packages/cli/src/rules/vale/run.ts +++ b/packages/cli/src/rules/vale/run.ts @@ -15,6 +15,7 @@ import { import { buildPath } from "../scan"; import { isWholeProjectWalk } from "../walk-scope"; import { findValeBinary, valeUnavailableMessage } from "./binary"; +import { findValeGrammars } from "./grammars"; import { buildValeGlob, converterExclusionGlobs, @@ -409,6 +410,28 @@ type ValeAttempt = configErrors?: readonly ValeConfigError[]; }; +/** + * The environment every Vale child runs in. + * + * `VALE_GRAMMARS_PATH` names the pinned grammar package's directory, which Vale + * reads for any grammar its StylesPath lacks. It is always REPLACED, never + * inherited: a value from the user's shell would hand Vale grammars the CLI + * did not ship or pin. When the package does not resolve the variable is + * dropped rather than left inherited, and Vale reads comments by delimiters, + * saying so in a `grammar … is not installed` warning that reaches the user as + * a notice. + */ +export function valeEnvironment( + grammars: string | undefined +): NodeJS.ProcessEnv { + const { VALE_GRAMMARS_PATH: _inherited, ...inherited } = process.env; + return { + ...inherited, + PATH: buildPath(), + ...(grammars === undefined ? {} : { VALE_GRAMMARS_PATH: grammars }), + }; +} + /** * Spawn Vale once and map what it reports. Extracted from {@link runVale} so * the retry loop there can call it again with a wider exclusion glob after @@ -427,7 +450,7 @@ async function spawnVale( const child = spawn(binary, argv, { cwd, stdio: ["ignore", "pipe", "pipe"], - env: { ...process.env, PATH: buildPath() }, + env: valeEnvironment(findValeGrammars().path), }); // One decoder per stream, not `chunk.toString()` per chunk. A multi-byte diff --git a/packages/cli/test/vale-grammars.test.ts b/packages/cli/test/vale-grammars.test.ts new file mode 100644 index 00000000..f47cda40 --- /dev/null +++ b/packages/cli/test/vale-grammars.test.ts @@ -0,0 +1,64 @@ +import { readdirSync } from "node:fs"; +import { isAbsolute } from "node:path"; + +import { describe, expect, it } from "vitest"; + +import { + findValeGrammars, + resolveValeGrammars, + VALE_GRAMMARS, +} from "../src/rules/vale/grammars"; +import { valeEnvironment } from "../src/rules/vale/run"; + +describe("resolveValeGrammars", () => { + it("resolves the pinned grammar package's module directory", () => { + const { path, tried } = resolveValeGrammars(); + expect(path).toBeDefined(); + expect(isAbsolute(path!)).toBe(true); + expect(tried).toEqual([path]); + expect( + readdirSync(path!).filter((entry) => entry.endsWith(".wasm")).length + ).toBeGreaterThan(0); + }); + + it("reports a missing package as a value, naming where it looked", () => { + const result = resolveValeGrammars({ + ...VALE_GRAMMARS, + packageName: "@taskless/vale-grammars-that-do-not-exist", + }); + expect(result).toEqual({ + path: undefined, + tried: ["@taskless/vale-grammars-that-do-not-exist/grammars"], + }); + }); + + it("rejects a directory that holds no grammar module", () => { + // The package root exists but holds only metadata. Naming it to Vale + // would behave like no grammars at all, with nothing saying why. + const result = resolveValeGrammars({ ...VALE_GRAMMARS, directory: "." }); + expect(result.path).toBeUndefined(); + expect(result.tried).toHaveLength(1); + }); + + it("caches the resolution for the process", () => { + expect(findValeGrammars()).toBe(findValeGrammars()); + }); +}); + +describe("valeEnvironment", () => { + it("names the pinned grammars, replacing a value from the user's shell", () => { + // A VALE_GRAMMARS_PATH inherited from the shell would hand Vale grammars + // the CLI did not ship or pin, so it never survives into the child. + const previous = process.env.VALE_GRAMMARS_PATH; + process.env.VALE_GRAMMARS_PATH = "/somewhere/else"; + try { + expect(valeEnvironment("/pinned/grammars").VALE_GRAMMARS_PATH).toBe( + "/pinned/grammars" + ); + expect(valeEnvironment()).not.toHaveProperty("VALE_GRAMMARS_PATH"); + } finally { + if (previous === undefined) delete process.env.VALE_GRAMMARS_PATH; + else process.env.VALE_GRAMMARS_PATH = previous; + } + }); +}); diff --git a/packages/cli/test/vale-vendor-contract.test.ts b/packages/cli/test/vale-vendor-contract.test.ts index f0470f36..c1dfa103 100644 --- a/packages/cli/test/vale-vendor-contract.test.ts +++ b/packages/cli/test/vale-vendor-contract.test.ts @@ -6,6 +6,8 @@ import { isAbsolute, join } from "node:path"; import { afterEach, describe, expect, it } from "vitest"; import { findValeBinary } from "../src/rules/vale/binary"; +import { findValeGrammars } from "../src/rules/vale/grammars"; +import { valeEnvironment } from "../src/rules/vale/run"; import { asValeConfigError } from "../src/rules/vale/map"; import { VALE_COMMENT_EXTENSIONS, @@ -42,6 +44,7 @@ import { VALE_CHECK_TYPES } from "../src/schemas/vale-rule"; */ const binary = findValeBinary().path; +const grammars = findValeGrammars().path; const withVale = binary === undefined ? describe.skip : describe; const workspaces: string[] = []; @@ -81,7 +84,7 @@ function runRaw(cwd: string, paths: string[], extraArguments: string[] = []) { "--", ...paths, ], - { cwd, encoding: "utf8" } + { cwd, encoding: "utf8", env: valeEnvironment(grammars) } ); } @@ -231,7 +234,7 @@ function assembled( "--", ...names, ], - { cwd, encoding: "utf8" } + { cwd, encoding: "utf8", env: valeEnvironment(grammars) } ); expect(result.status, result.stderr).toBe(0); const parsed = JSON.parse(result.stdout || "{}") as Record< @@ -2616,7 +2619,7 @@ function firing(cwd: string, config: string, path: string): string[] { const result = spawnSync( binary as string, ["--config", config, "--output=JSON", "--no-exit", "--", path], - { cwd, encoding: "utf8" } + { cwd, encoding: "utf8", env: valeEnvironment(grammars) } ); expect(result.status, result.stderr).toBe(0); return Object.keys( diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 60cb7963..c961643b 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -74,6 +74,9 @@ importers: packages/cli: dependencies: + '@taskless/vale-grammars': + specifier: 3.27.0-20261117230017 + version: 3.27.0-20261117230017 tsx: specifier: ^4.21.0 version: 4.21.0 @@ -901,6 +904,9 @@ packages: cpu: [x64] os: [darwin] + '@taskless/vale-grammars@3.27.0-20261117230017': + resolution: {integrity: sha512-8NMJzgnFjA4UyOCZD/Wjw1lb/gfKKHMeXVQaAV5n+W2uolOeef75mvDnapsLrjifRjz9S4LcCtRd6JqAnT94Nw==} + '@taskless/vale-linux-arm64@3.27.0-20261117230017': resolution: {integrity: sha512-xePLv6AYtEHu0P1taxFsjIlXkQ8P9XbZqsqRMZpoKKUXU/938/muo7SIRNXHzIQPBAGBCUpDOXyAyGr0tvQzfA==} cpu: [arm64] @@ -3382,6 +3388,8 @@ snapshots: '@taskless/vale-darwin-x64@3.27.0-20261117230017': optional: true + '@taskless/vale-grammars@3.27.0-20261117230017': {} + '@taskless/vale-linux-arm64@3.27.0-20261117230017': optional: true From f40021cca3f24f5bced02fef2284c18e1219925b Mon Sep 17 00:00:00 2001 From: Jakob Heuser Date: Thu, 19 Nov 2026 17:29:30 -0800 Subject: [PATCH 3/6] feat(vale): refuse unvetted grammars and check grammar coverage A config/grammars directory in .taskless/rules/vale would hand Vale grammars ahead of the pinned ones, since that tree is every assembled config's StylesPath. A new vale-tree-no-grammars constraint refuses it: validate reports it against every Vale rule, and assembly refuses the check run through one shared check. Presence is refused, not contents. The vendor contract now asks the binary whether every comment-tier extension has a pinned grammar, naming the one that is missing. engine-version-consistency reads dependencies, where the grammar pin lives, and holds it to the platform pins' exact version. Regenerate the reference corpus for the new constraint. --- .../changes/vale-grammars-package/design.md | 8 +++- .../changes/vale-grammars-package/tasks.md | 10 ++-- packages/cli/assets/reference.json | 7 +++ packages/cli/src/rules/assemble.ts | 18 ++++++- packages/cli/src/rules/constraints.ts | 10 ++++ packages/cli/src/rules/dispatch.ts | 15 ++++-- packages/cli/src/rules/inspect.ts | 9 ++++ packages/cli/src/rules/vale/grammar-tree.ts | 48 +++++++++++++++++++ packages/cli/test/constraints.test.ts | 11 +++++ .../test/engine-version-consistency.test.ts | 18 ++++++- packages/cli/test/vale-grammars.test.ts | 10 +++- packages/cli/test/vale-orchestration.test.ts | 41 ++++++++++++++++ .../cli/test/vale-vendor-contract.test.ts | 27 +++++++++++ .../cli/test/validate-verify-commands.test.ts | 35 ++++++++++++++ 14 files changed, 251 insertions(+), 16 deletions(-) create mode 100644 packages/cli/src/rules/vale/grammar-tree.ts diff --git a/openspec/changes/vale-grammars-package/design.md b/openspec/changes/vale-grammars-package/design.md index bc55a2c3..edf86ab8 100644 --- a/openspec/changes/vale-grammars-package/design.md +++ b/openspec/changes/vale-grammars-package/design.md @@ -69,9 +69,13 @@ _Alternative: copy the grammars into `/config/grammars/` at assembly The vendor contract runs every comment-tier extension in `VALE_FORMAT_TIERS` through the pinned binary with the pinned grammars. It fails on any `grammar "" is not installed` warning, naming the extension and the grammar. The binary is the authority on which grammar an extension needs, so the test asks it rather than keeping a mapping. The six cases failing on #703 stay as they are, and pass again once the grammars are present. -### D7. The rules-tree grammar directory is refused at assembly +### D7. One check for the rules-tree grammar directory, called by `validate` and by assembly -`assembleValeConfig` checks for `/config/grammars/` before writing anything. When it exists, the result is a refusal naming the directory. That refusal is a tree-level entry beside the existing per-rule ones, reported the same way, so `validate` and `check` both refuse through the code they already share. Its presence is refused, not its contents, because an empty directory today becomes a populated one after the next `vale sync`, and an unvetted grammar would win over ours for that language. The rest of `config/` (vocabularies, for example) is not touched by this change. +`validate` and `check` do not share an assembly path: `validate` judges one rule at a time in `inspect.ts`, while `check` refuses through `assembleValeConfig`. So the check is one function, `valeTreeGrammarsViolation`, that both call, under a new constraint `vale-tree-no-grammars` in the published constraint table. `validate` reports it against every Vale rule, since the tree is every rule's StylesPath. Assembly returns a refusal carrying it as a tree-level rejection beside the per-rule ones, and `check` reports it as the Vale engine's failure, with other engines still running. + +Its presence is refused, not its contents, because an empty directory today becomes a populated one after the next `vale sync`, and an unvetted grammar would win over ours for that language. The rest of `config/` (vocabularies, for example) is not touched by this change. + +The same reasoning covers the environment. `VALE_GRAMMARS_PATH` is always replaced in the child environment, never inherited, because a value from the user's shell is also a grammar directory nobody pinned. When the grammar package does not resolve, the variable is dropped rather than inherited. ## Risks / Trade-offs diff --git a/openspec/changes/vale-grammars-package/tasks.md b/openspec/changes/vale-grammars-package/tasks.md index 76b9ae34..a5be733c 100644 --- a/openspec/changes/vale-grammars-package/tasks.md +++ b/openspec/changes/vale-grammars-package/tasks.md @@ -20,8 +20,8 @@ Groups 1–3 are PR A, cut from `origin/main`. Group 4 is the maintainer's manua ## 4. Bootstrap (maintainer, between PR A and PR B) -- [ ] 4.1 Run `node .github/scripts/vale-prepare.cjs --only grammars --version 3.27.0-20261117230017` on PR A's branch, publish that tarball by hand with `npm publish --access public --tag latest`, and register its npm trusted publisher against `release-vale.yml` and `npm-autopublish`; verify `npm view @taskless/vale-grammars version` prints `3.27.0-20261117230017`. -- [ ] 4.2 Merge PR A, then confirm the `Release Vale` run's gate reports all seven packages published and publishes nothing. +- [x] 4.1 Run `node .github/scripts/vale-prepare.cjs --only grammars --version 3.27.0-20261117230017` on PR A's branch, publish that tarball by hand with `npm publish --access public --tag latest`, and register its npm trusted publisher against `release-vale.yml` and `npm-autopublish`; verify `npm view @taskless/vale-grammars version` prints `3.27.0-20261117230017`. +- [x] 4.2 Confirm `vale-gate.cjs`, run against PR A's manifest and the live registry, reports all seven packages published, so merging PR A publishes nothing. ## 5. CLI wiring (PR B) @@ -32,9 +32,9 @@ Groups 1–3 are PR A, cut from `origin/main`. Group 4 is the maintainer's manua ## 6. Refusal and coverage (PR B) -- [ ] 6.1 In `assembleValeConfig`, refuse when `/config/grammars/` exists, with a tree-level refusal that `validate` and `check` both report; verify with tests for the `validate` failure, the `check` failure with non-zero exit and ast-grep results still reported, and an empty directory. -- [ ] 6.2 Add the D6 coverage case to `test/vale-vendor-contract.test.ts`: every comment-tier extension in `VALE_FORMAT_TIERS`, run with the pinned grammars, produces no `grammar "" is not installed` warning; verify it fails when one grammar is withheld and passes with the full set. -- [ ] 6.3 Extend `engine-version-consistency.test.ts` so the grammar pin is the same exact version as the platform pins and its Vale component equals `VALE_VERSION`; verify it fails on a mismatched pin. +- [x] 6.1 Refuse a `/config/grammars/` directory through one shared check under a new `vale-tree-no-grammars` constraint, reported by `validate` against every Vale rule and by assembly as a tree-level refusal `check` reports; verify with tests for the `validate` failure, the `check` failure with non-zero exit and ast-grep results still reported, and an empty directory. +- [x] 6.2 Add the D6 coverage case to `test/vale-vendor-contract.test.ts`: every comment-tier extension in `VALE_FORMAT_TIERS`, run with the pinned grammars, produces no `grammar "" is not installed` warning; verify it fails when one grammar is withheld and passes with the full set. +- [x] 6.3 Extend `engine-version-consistency.test.ts` so the grammar pin is the same exact version as the platform pins and its Vale component equals `VALE_VERSION`; verify it fails on a mismatched pin. ## 7. Release notes (PR B) diff --git a/packages/cli/assets/reference.json b/packages/cli/assets/reference.json index c08c16f3..3c5969ac 100644 --- a/packages/cli/assets/reference.json +++ b/packages/cli/assets/reference.json @@ -137,6 +137,13 @@ "enforcedBy": "validate", "summary": "A `NO` matcher comes after the `YES` it narrows, never before every `YES`.", "rationale": "Matcher precedence is positional: where two matchers match a file, the later wins. A `NO` that precedes every `YES` is therefore either dead (the file matched nothing else, and the rule was already off) or overridden by the `YES` that follows it. Measured against the pinned Vale, `[docs/legacy/**] NO` then `[docs/**] YES` fires in `docs/legacy/`. No config means that, so it is refused rather than reported." + }, + { + "id": "vale-tree-no-grammars", + "engine": "vale", + "enforcedBy": "validate", + "summary": "The Vale rules tree holds no `config/grammars/` directory; Vale's grammars come only from the pinned grammar package.", + "rationale": "Since Vale 3.27.0 the tree-sitter grammars Vale uses to find comments in source code ship apart from the binary, and the CLI names its pinned `@taskless/vale-grammars` to Vale. The rules tree is the StylesPath of every assembled config, and Vale reads a grammar there before the pinned one, one language at a time, so a `vale sync` against an assembled config would swap in grammars nobody reviewed. Its presence is refused, not its contents, because an empty directory is a populated one after the next sync. `validate` reports it against every Vale rule, and `check` refuses the Vale run." } ], "rules": [ diff --git a/packages/cli/src/rules/assemble.ts b/packages/cli/src/rules/assemble.ts index 165930be..61a5131a 100644 --- a/packages/cli/src/rules/assemble.ts +++ b/packages/cli/src/rules/assemble.ts @@ -19,6 +19,7 @@ import { import { validateValeRuleConfig } from "../schemas/vale-config"; import type { RuleViolation } from "./constraints"; import { RULE_TESTS_DIRECTORY, RULES_DIRECTORY } from "./layout"; +import { valeTreeGrammarsViolation } from "./vale/grammar-tree"; /** * Assembling the per-rule configs into the single file each tool accepts. @@ -214,8 +215,17 @@ export interface AssembledValeConfig { */ export interface RefusedValeConfig { status: "refused"; - /** Every rule refused, in id order. Never empty. */ + /** + * Every rule refused, in id order. Empty only when the refusal is the + * tree's rather than any rule's ({@link treeRejections}). + */ refusals: ValeConfigRefusal[]; + /** + * What refuses the run whatever the rules say: a grammar directory in the + * Vale rules tree, which every assembled config's StylesPath would hand to + * Vale ahead of the pinned grammars. Empty when the tree is clean. + */ + treeRejections: RuleViolation[]; } export type ValeAssembly = AssembledValeConfig | RefusedValeConfig; @@ -268,6 +278,8 @@ export async function assembleValeConfig( options: AssembleOptions = {} ): Promise { const ruleIds = await listRuleIds(cwd, "vale"); + const grammars = await valeTreeGrammarsViolation(cwd); + const treeRejections = grammars === undefined ? [] : [grammars]; // A filter selects which validated blocks are written, and is deliberately // NOT applied to `ruleIds`: the loop below has to reach every rule so a // rejected sibling still lands in `refusals`. @@ -303,7 +315,9 @@ export async function assembleValeConfig( blocks.push(valeRuleBlock(ruleId, source, verdict.breadcrumbLines)); } - if (refusals.length > 0) return { status: "refused", refusals }; + if (refusals.length > 0 || treeRejections.length > 0) { + return { status: "refused", refusals, treeRejections }; + } if (blocks.length === 0) return undefined; const contents = [valeHeader(), ...blocks].join("\n"); diff --git a/packages/cli/src/rules/constraints.ts b/packages/cli/src/rules/constraints.ts index 9c4f7bb2..5bf617a7 100644 --- a/packages/cli/src/rules/constraints.ts +++ b/packages/cli/src/rules/constraints.ts @@ -211,6 +211,16 @@ export const RULE_CONSTRAINTS = [ rationale: "Matcher precedence is positional: where two matchers match a file, the later wins. A `NO` that precedes every `YES` is therefore either dead (the file matched nothing else, and the rule was already off) or overridden by the `YES` that follows it. Measured against the pinned Vale, `[docs/legacy/**] NO` then `[docs/**] YES` fires in `docs/legacy/`. No config means that, so it is refused rather than reported.", }, + // --- Vale: the rules tree as a whole --------------------------------------- + { + id: "vale-tree-no-grammars", + engine: "vale", + enforcedBy: "validate", + summary: + "The Vale rules tree holds no `config/grammars/` directory; Vale's grammars come only from the pinned grammar package.", + rationale: + "Since Vale 3.27.0 the tree-sitter grammars Vale uses to find comments in source code ship apart from the binary, and the CLI names its pinned `@taskless/vale-grammars` to Vale. The rules tree is the StylesPath of every assembled config, and Vale reads a grammar there before the pinned one, one language at a time, so a `vale sync` against an assembled config would swap in grammars nobody reviewed. Its presence is refused, not its contents, because an empty directory is a populated one after the next sync. `validate` reports it against every Vale rule, and `check` refuses the Vale run.", + }, ] as const satisfies readonly RuleConstraint[]; /** diff --git a/packages/cli/src/rules/dispatch.ts b/packages/cli/src/rules/dispatch.ts index 33bf4b7e..9f918743 100644 --- a/packages/cli/src/rules/dispatch.ts +++ b/packages/cli/src/rules/dispatch.ts @@ -282,11 +282,18 @@ async function runValeEngine(options: DispatchOptions): Promise { */ function describeValeRefusal(refused: RefusedValeConfig): string { const rules = refused.refusals.map((refusal) => refusal.ruleId).join(", "); - const lines = refused.refusals.flatMap((refusal) => - refusal.rejections.map((rejection) => rejection.message) - ); + const lines = [ + ...refused.treeRejections.map((rejection) => rejection.message), + ...refused.refusals.flatMap((refusal) => + refusal.rejections.map((rejection) => rejection.message) + ), + ]; + const reason = + refused.refusals.length === 0 + ? "the Vale rules tree was rejected" + : `the config of ${rules} was rejected by the config schema`; return [ - `Vale did not run: the config of ${rules} was rejected by the config schema. ` + + `Vale did not run: ${reason}. ` + `Run \`${getCliPrefix()} verify\` for the constraint behind each line.`, ...lines, ].join("\n"); diff --git a/packages/cli/src/rules/inspect.ts b/packages/cli/src/rules/inspect.ts index 083489c9..4eb7cc36 100644 --- a/packages/cli/src/rules/inspect.ts +++ b/packages/cli/src/rules/inspect.ts @@ -27,6 +27,7 @@ import { runRuntimeFixtures, } from "./runtime/run-fixtures"; import { validateValeRuleConfig } from "../schemas/vale-config"; +import { valeTreeGrammarsViolation } from "./vale/grammar-tree"; import { validateValeRule } from "../schemas/vale-rule"; import { collectNotices } from "../util/notices"; import { verifyRule, type VerifyResult } from "./verify"; @@ -429,6 +430,14 @@ async function validateRuleComponents( } } + // The rules tree is every Vale rule's StylesPath, so a grammar directory + // in it changes how every one of them reads source code. Reported against + // each rule, by the same check assembly refuses `check` on. + const grammars = await valeTreeGrammarsViolation(cwd); + if (grammars !== undefined) { + violate({ errors, violations }, grammars.constraintId, grammars.message); + } + // `violations` is empty, never absent, when nothing failed: a consumer // must be able to tell "no constraint was broken" from "this CLI does not // report violations". diff --git a/packages/cli/src/rules/vale/grammar-tree.ts b/packages/cli/src/rules/vale/grammar-tree.ts new file mode 100644 index 00000000..8ab3f6c0 --- /dev/null +++ b/packages/cli/src/rules/vale/grammar-tree.ts @@ -0,0 +1,48 @@ +import { lstat } from "node:fs/promises"; +import { join } from "node:path"; + +import type { RuleViolation } from "../constraints"; +import { engineRulesDirectory } from "../engines"; +import { RULES_DIRECTORY, TASKLESS_DIRECTORY } from "../layout"; + +/** + * Where a grammar directory would sit inside the Vale rules tree, relative to + * the project root. + * + * The Vale rules tree is the StylesPath of every config the CLI assembles, and + * Vale reads a grammar from `/config/grammars/` in preference to + * the pinned grammars named through `VALE_GRAMMARS_PATH`. A `vale sync` run + * against an assembled config puts one exactly here. + */ +export const VALE_TREE_GRAMMARS = [ + TASKLESS_DIRECTORY, + RULES_DIRECTORY, + "vale", + "config", + "grammars", +].join("/"); + +/** + * The violation a grammar directory in the Vale rules tree raises, or + * `undefined` when there is none. + * + * Its presence is refused, not its contents: an empty directory today is a + * populated one after the next `vale sync`, and any grammar in it would win + * over the pinned one for that language. Shared by `validate`, which reports + * it against every Vale rule, and by assembly, which refuses the `check` run, + * so the two cannot disagree about what they found. + */ +export async function valeTreeGrammarsViolation( + cwd: string +): Promise { + const path = join(engineRulesDirectory(cwd, "vale"), "config", "grammars"); + const stats = await lstat(path).catch(() => {}); + if (stats === undefined) return undefined; + return { + constraintId: "vale-tree-no-grammars", + message: + `${VALE_TREE_GRAMMARS} holds Vale grammars the CLI did not ship. Vale ` + + `would read them before the pinned grammars, so they are refused. ` + + `Remove the directory.`, + }; +} diff --git a/packages/cli/test/constraints.test.ts b/packages/cli/test/constraints.test.ts index 412c6986..06b9afd2 100644 --- a/packages/cli/test/constraints.test.ts +++ b/packages/cli/test/constraints.test.ts @@ -285,6 +285,17 @@ const VIOLATIONS: Record = { ), names: /disables probe-rule before any matcher enables it/, }, + "vale-tree-no-grammars": { + // A clean rule beside a grammar directory in the rules tree: the rule's + // own config is valid, so only the tree can be what refuses it. + run: async () => { + await mkdir(join(project, ".taskless/rules/vale/config/grammars"), { + recursive: true, + }); + return verifyValeConfig(VALID_VALE_CONFIG); + }, + names: /config\/grammars holds Vale grammars the CLI did not ship/, + }, }; describe("every documented constraint is a check that still fires", () => { diff --git a/packages/cli/test/engine-version-consistency.test.ts b/packages/cli/test/engine-version-consistency.test.ts index 25f920e2..cf0c8da1 100644 --- a/packages/cli/test/engine-version-consistency.test.ts +++ b/packages/cli/test/engine-version-consistency.test.ts @@ -56,12 +56,17 @@ import { resolvePlatformBinary } from "../src/rules/platform-binary"; const manifest = JSON.parse( readFileSync(join(import.meta.dirname, "..", "package.json"), "utf8") ) as { + dependencies?: Record; optionalDependencies: Record; devDependencies?: Record; }; -/** Every dependency field a pin can live in, merged. */ +/** + * Every dependency field a pin can live in, merged. `dependencies` is one: the + * Vale grammar package is a regular dependency, since every host needs it. + */ const allPins: Record = { + ...manifest.dependencies, ...manifest.devDependencies, ...manifest.optionalDependencies, }; @@ -96,8 +101,17 @@ describe("the published engine versions agree with their pins", () => { }); it("vale's constant is the version its platform packages pin, before our build stamp", () => { + // The grammar package is read by the binary, so it is held to the same + // exact pin: the family check below would pass vacuously without it. + expect( + allPins["@taskless/vale-grammars"], + "@taskless/vale-grammars is not pinned" + ).toBeDefined(); const pinned = pinnedVersions("@taskless/vale"); - expect(pinned.length, "platform packages disagree on a version").toBe(1); + expect( + pinned.length, + "the platform packages and the grammar package disagree on a version" + ).toBe(1); // Ours to repackage, so the pin carries a build stamp the upstream version // does not: `3.20.0` is what Vale reports, `3.20.0-` is the npm diff --git a/packages/cli/test/vale-grammars.test.ts b/packages/cli/test/vale-grammars.test.ts index f47cda40..3321a9c7 100644 --- a/packages/cli/test/vale-grammars.test.ts +++ b/packages/cli/test/vale-grammars.test.ts @@ -55,7 +55,15 @@ describe("valeEnvironment", () => { expect(valeEnvironment("/pinned/grammars").VALE_GRAMMARS_PATH).toBe( "/pinned/grammars" ); - expect(valeEnvironment()).not.toHaveProperty("VALE_GRAMMARS_PATH"); + // A grammar package that did not resolve drops the variable rather + // than letting the inherited one through. + const missing = resolveValeGrammars({ + ...VALE_GRAMMARS, + packageName: "@taskless/vale-grammars-that-do-not-exist", + }); + expect(valeEnvironment(missing.path)).not.toHaveProperty( + "VALE_GRAMMARS_PATH" + ); } finally { if (previous === undefined) delete process.env.VALE_GRAMMARS_PATH; else process.env.VALE_GRAMMARS_PATH = previous; diff --git a/packages/cli/test/vale-orchestration.test.ts b/packages/cli/test/vale-orchestration.test.ts index f66f1aa7..1d494e3e 100644 --- a/packages/cli/test/vale-orchestration.test.ts +++ b/packages/cli/test/vale-orchestration.test.ts @@ -669,3 +669,44 @@ describe("check renders one marker per notice", () => { } }); }); + +describe("a grammar directory in the Vale rules tree", () => { + // Vale reads a grammar from the StylesPath before the pinned grammars, and + // the rules tree is the StylesPath of every assembled config, so `check` + // refuses the Vale run rather than lint with grammars nobody pinned. The + // refusal is the tree's, so it needs no Vale binary to be decided. + it("refuses the Vale run, fails the check, and still reports ast-grep", async () => { + const cwd = makeMixedProject(); + mkdirSync(join(cwd, ".taskless", "rules", "vale", "config", "grammars"), { + recursive: true, + }); + + const assembledVale = await assembleValeConfig(cwd); + expect(assembledVale).toMatchObject({ + status: "refused", + refusals: [], + treeRejections: [{ constraintId: "vale-tree-no-grammars" }], + }); + + const dispatched = await runEngines({ + cwd, + paths: ["app.js", "doc.md"], + astGrepConfigPath: await assembleSgConfig(cwd), + vale: assembledVale, + runtimeRules: [], + }); + expect( + dispatched.results.some((result) => result.source === "ast-grep") + ).toBe(true); + expect(dispatched.results.some((result) => result.source === "vale")).toBe( + false + ); + expect(dispatched.failures.join("\n")).toContain( + "Vale did not run: the Vale rules tree was rejected" + ); + expect(dispatched.failures.join("\n")).toContain( + ".taskless/rules/vale/config/grammars" + ); + expect(dispatched.exitCode).not.toBe(0); + }); +}); diff --git a/packages/cli/test/vale-vendor-contract.test.ts b/packages/cli/test/vale-vendor-contract.test.ts index c1dfa103..95e2a16f 100644 --- a/packages/cli/test/vale-vendor-contract.test.ts +++ b/packages/cli/test/vale-vendor-contract.test.ts @@ -2682,3 +2682,30 @@ withVale("a matcher resolves against the working directory", () => { ]); }); }); + +withVale("Vale grammars (3.27.0 and later)", () => { + // Since 3.27.0 the tree-sitter grammars ship apart from the binary, and a + // comment-tier extension whose grammar is missing is read by its delimiters + // instead: directive comments become prose and one-line CSS comments are + // skipped, with only a W101 on stderr to say so. The binary is asked which + // grammar each listed extension needs, rather than keeping a mapping here, + // so a grammar upstream drops or renames fails this, naming the extension. + const document = + "// simply\n# simply\n/* simply */\n-- simply\n; simply\nx = 1\n"; + + it("resolves the pinned grammar package", () => { + expect(grammars, "@taskless/vale-grammars did not resolve").toBeDefined(); + }); + + it.each([...VALE_COMMENT_EXTENSIONS])( + "has a pinned grammar for every comment-tier extension: %s", + (extension) => { + const { stderr } = lines(existence("simply"), document, `g${extension}`); + const missing = /grammar "([^"]+)" is not installed/.exec(stderr); + expect( + missing, + `${extension} needs grammar "${missing?.[1]}", which @taskless/vale-grammars does not carry` + ).toBeNull(); + } + ); +}); diff --git a/packages/cli/test/validate-verify-commands.test.ts b/packages/cli/test/validate-verify-commands.test.ts index bcfa8420..3fc19317 100644 --- a/packages/cli/test/validate-verify-commands.test.ts +++ b/packages/cli/test/validate-verify-commands.test.ts @@ -241,6 +241,41 @@ describe("validate checks components without requiring tests", () => { ]); }); + // Vale reads a grammar from its StylesPath before the pinned grammars, and + // the rules tree is every assembled config's StylesPath. Presence is what is + // refused, so an empty directory fails exactly as a populated one does. + it.each([ + ["holds a grammar", true], + ["is empty", false], + ])( + "refuses every Vale rule when the rules tree's config/grammars %s", + async (_label, populated) => { + await valeRule("no-simply", { config: SCOPED }); + const grammars = join( + cwd, + ".taskless", + "rules", + "vale", + "config", + "grammars" + ); + await mkdir(grammars, { recursive: true }); + if (populated) await writeFile(join(grammars, "go.wasm"), "\0asm"); + const result = await runCli(["validate", "-d", cwd, "--json"]); + expect(result.exitCode).not.toBe(0); + const rule = (JSON.parse(result.stdout) as Report).rules.find( + (entry) => entry.ruleId === "no-simply" + ); + expect(rule?.ok).toBe(false); + expect( + rule?.violations.map((violation) => violation.constraintId) + ).toEqual(["vale-tree-no-grammars"]); + expect(rule?.violations[0]?.message).toContain( + ".taskless/rules/vale/config/grammars holds Vale grammars the CLI did not ship" + ); + } + ); + // The style schema's own advisory, through the real CLI. // `vale-schema-contract.test.ts` holds the advisory to its rule; this says // it reaches `notices` on `validate` output and `--json`, beside whatever the From 23c9c1e086a9a66a8d5f6ece11563d4c1380bc29 Mon Sep 17 00:00:00 2001 From: Jakob Heuser Date: Thu, 19 Nov 2026 17:31:19 -0800 Subject: [PATCH 4/6] docs(vale): record Vale 3.27.0 in the update ledger and changeset The 0.13.8 ledger entry says no rule reports anything different, and that a config/grammars directory in .taskless/rules/vale is now refused. The changeset grows to say the grammars ship as their own package and what is refused. Reconcile this repository's own rules to Vale 3.27.0 with update --rules. --- .changeset/vale-3-27-0.md | 6 +++++- .taskless/taskless.json | 2 +- openspec/changes/vale-grammars-package/tasks.md | 4 ++-- packages/cli/src/agent/update.md | 17 +++++++++++++++++ 4 files changed, 25 insertions(+), 4 deletions(-) diff --git a/.changeset/vale-3-27-0.md b/.changeset/vale-3-27-0.md index 3e383784..d08b1bc1 100644 --- a/.changeset/vale-3-27-0.md +++ b/.changeset/vale-3-27-0.md @@ -2,4 +2,8 @@ "@taskless/cli": patch --- -Update the bundled Vale to 3.27.0. +Update the bundled Vale to 3.27.0. No rule reports anything different. + +Vale 3.27.0 ships the grammars it uses to read comments in source code apart from its binary. They now arrive as `@taskless/vale-grammars`, pinned with Vale and installed with the CLI, and every Vale run uses them. Without them, Vale 3.27.0 would lint linter directives such as `//nolint` as prose and skip one-line CSS comments. + +A `config/grammars/` directory inside `.taskless/rules/vale/` is now refused by `validate` and `check`, under the new `vale-tree-no-grammars` constraint, because Vale would read grammars there ahead of the pinned ones. A `VALE_GRAMMARS_PATH` set in your shell is likewise ignored. `@taskless/cli/node/runtimes` also exports `resolveValeGrammars`, so a verifier can run Vale rules with the same grammars. diff --git a/.taskless/taskless.json b/.taskless/taskless.json index b95d0851..49ab0c6c 100644 --- a/.taskless/taskless.json +++ b/.taskless/taskless.json @@ -31,7 +31,7 @@ "reconciledTo": "0.13.7", "engines": { "sg": "0.51.3", - "vale": "3.26.0" + "vale": "3.27.0" } } } diff --git a/openspec/changes/vale-grammars-package/tasks.md b/openspec/changes/vale-grammars-package/tasks.md index a5be733c..5198aa7a 100644 --- a/openspec/changes/vale-grammars-package/tasks.md +++ b/openspec/changes/vale-grammars-package/tasks.md @@ -38,8 +38,8 @@ Groups 1–3 are PR A, cut from `origin/main`. Group 4 is the maintainer's manua ## 7. Release notes (PR B) -- [ ] 7.1 Add the Vale 3.27.0 entry to the `update` ledger in `src/agent/update.md`, stating that behavior is unchanged and that a `.taskless/rules/vale/config/grammars/` directory is now refused; verify the reconcile-marker and prompt parity tests pass. -- [ ] 7.2 Grow `.changeset/vale-3-27-0.md` (patch) to say the grammars ship as their own package and an unvetted grammar directory in the rules tree is refused; verify the `Changeset` check stays green. +- [x] 7.1 Add the Vale 3.27.0 entry to the `update` ledger in `src/agent/update.md`, stating that behavior is unchanged and that a `.taskless/rules/vale/config/grammars/` directory is now refused; verify the reconcile-marker and prompt parity tests pass. +- [x] 7.2 Grow `.changeset/vale-3-27-0.md` (patch) to say the grammars ship as their own package and an unvetted grammar directory in the rules tree is refused; verify the `Changeset` check stays green. ## 8. PR B checks and archive diff --git a/packages/cli/src/agent/update.md b/packages/cli/src/agent/update.md index bfcfd6cb..7a6fae13 100644 --- a/packages/cli/src/agent/update.md +++ b/packages/cli/src/agent/update.md @@ -726,6 +726,23 @@ can produce findings it did not before. findings disappear and a project vocabulary entry that existed only for such a word is now redundant. Leave it; it does no harm. + +## Migrating to 0.13.8 + +Vale moves from 3.26.0 to 3.27.0. Nothing here needs work by hand, +and no rule reports anything different. + +Vale 3.27.0 ships the grammars it uses to read comments in source code +apart from its binary. The CLI now installs them as +`@taskless/vale-grammars`, pinned with Vale, and hands them to every +run. Rules over code files behave exactly as they did on 3.26.0. + +**One thing is now refused: a `config/grammars/` directory inside +`.taskless/rules/vale/`.** Vale would read grammars there ahead of the +pinned ones, so `validate` and `check` fail while it exists. It only +appears if someone ran `vale sync` against an assembled config. Delete +the directory. Nothing in this project needs it. + ## Errors From 6a75984965d75da314bd6cf6bccf5f4be4c90acd Mon Sep 17 00:00:00 2001 From: Jakob Heuser Date: Thu, 19 Nov 2026 17:32:05 -0800 Subject: [PATCH 5/6] docs(openspec): archive vale-grammars-package Every task is done and every prior scenario in the three standing specs survives: vale-binary-packages 18 -> 27, cli-vale-rule-engine 41 -> 48, cli-runtime-binary-export 8 -> 10. --- .../.openspec.yaml | 0 .../design.md | 0 .../proposal.md | 0 .../specs/cli-runtime-binary-export/spec.md | 0 .../specs/cli-vale-rule-engine/spec.md | 0 .../specs/vale-binary-packages/spec.md | 0 .../tasks.md | 4 +- .../specs/cli-runtime-binary-export/spec.md | 20 ++++++ openspec/specs/cli-vale-rule-engine/spec.md | 51 +++++++++++++++ openspec/specs/vale-binary-packages/spec.md | 63 +++++++++++++++++++ 10 files changed, 136 insertions(+), 2 deletions(-) rename openspec/changes/{vale-grammars-package => archive/2026-11-19-vale-grammars-package}/.openspec.yaml (100%) rename openspec/changes/{vale-grammars-package => archive/2026-11-19-vale-grammars-package}/design.md (100%) rename openspec/changes/{vale-grammars-package => archive/2026-11-19-vale-grammars-package}/proposal.md (100%) rename openspec/changes/{vale-grammars-package => archive/2026-11-19-vale-grammars-package}/specs/cli-runtime-binary-export/spec.md (100%) rename openspec/changes/{vale-grammars-package => archive/2026-11-19-vale-grammars-package}/specs/cli-vale-rule-engine/spec.md (100%) rename openspec/changes/{vale-grammars-package => archive/2026-11-19-vale-grammars-package}/specs/vale-binary-packages/spec.md (100%) rename openspec/changes/{vale-grammars-package => archive/2026-11-19-vale-grammars-package}/tasks.md (98%) diff --git a/openspec/changes/vale-grammars-package/.openspec.yaml b/openspec/changes/archive/2026-11-19-vale-grammars-package/.openspec.yaml similarity index 100% rename from openspec/changes/vale-grammars-package/.openspec.yaml rename to openspec/changes/archive/2026-11-19-vale-grammars-package/.openspec.yaml diff --git a/openspec/changes/vale-grammars-package/design.md b/openspec/changes/archive/2026-11-19-vale-grammars-package/design.md similarity index 100% rename from openspec/changes/vale-grammars-package/design.md rename to openspec/changes/archive/2026-11-19-vale-grammars-package/design.md diff --git a/openspec/changes/vale-grammars-package/proposal.md b/openspec/changes/archive/2026-11-19-vale-grammars-package/proposal.md similarity index 100% rename from openspec/changes/vale-grammars-package/proposal.md rename to openspec/changes/archive/2026-11-19-vale-grammars-package/proposal.md diff --git a/openspec/changes/vale-grammars-package/specs/cli-runtime-binary-export/spec.md b/openspec/changes/archive/2026-11-19-vale-grammars-package/specs/cli-runtime-binary-export/spec.md similarity index 100% rename from openspec/changes/vale-grammars-package/specs/cli-runtime-binary-export/spec.md rename to openspec/changes/archive/2026-11-19-vale-grammars-package/specs/cli-runtime-binary-export/spec.md diff --git a/openspec/changes/vale-grammars-package/specs/cli-vale-rule-engine/spec.md b/openspec/changes/archive/2026-11-19-vale-grammars-package/specs/cli-vale-rule-engine/spec.md similarity index 100% rename from openspec/changes/vale-grammars-package/specs/cli-vale-rule-engine/spec.md rename to openspec/changes/archive/2026-11-19-vale-grammars-package/specs/cli-vale-rule-engine/spec.md diff --git a/openspec/changes/vale-grammars-package/specs/vale-binary-packages/spec.md b/openspec/changes/archive/2026-11-19-vale-grammars-package/specs/vale-binary-packages/spec.md similarity index 100% rename from openspec/changes/vale-grammars-package/specs/vale-binary-packages/spec.md rename to openspec/changes/archive/2026-11-19-vale-grammars-package/specs/vale-binary-packages/spec.md diff --git a/openspec/changes/vale-grammars-package/tasks.md b/openspec/changes/archive/2026-11-19-vale-grammars-package/tasks.md similarity index 98% rename from openspec/changes/vale-grammars-package/tasks.md rename to openspec/changes/archive/2026-11-19-vale-grammars-package/tasks.md index 5198aa7a..16e1d619 100644 --- a/openspec/changes/vale-grammars-package/tasks.md +++ b/openspec/changes/archive/2026-11-19-vale-grammars-package/tasks.md @@ -43,5 +43,5 @@ Groups 1–3 are PR A, cut from `origin/main`. Group 4 is the maintainer's manua ## 8. PR B checks and archive -- [ ] 8.1 Run `pnpm build`, `pnpm typecheck`, `pnpm lint`, and the full CLI suite and confirm they pass on every branch of PR B. -- [ ] 8.2 Archive with `pnpm openspec archive vale-grammars-package -y` after confirming every prior scenario in the three standing specs survives (the pre-archive check in AGENTS.md); open PR B to `main` with `Refs #703` and request `@claude /review`. +- [x] 8.1 Run `pnpm build`, `pnpm typecheck`, `pnpm lint`, and the full CLI suite and confirm they pass on every branch of PR B. +- [x] 8.2 Archive with `pnpm openspec archive vale-grammars-package -y` after confirming every prior scenario in the three standing specs survives (the pre-archive check in AGENTS.md); open PR B to `main` with `Refs #703` and request `@claude /review`. diff --git a/openspec/specs/cli-runtime-binary-export/spec.md b/openspec/specs/cli-runtime-binary-export/spec.md index 6242cfc6..dc492c39 100644 --- a/openspec/specs/cli-runtime-binary-export/spec.md +++ b/openspec/specs/cli-runtime-binary-export/spec.md @@ -109,3 +109,23 @@ also ship the command tree. - **AND** the check SHALL be made against the entry module rather than against the emitted CLI chunk, since bundling may move the command layer into a shared chunk the CLI entry itself merely re-exports + +### Requirement: The Vale grammar resolver is published beside the binary resolver + +The runtimes entry SHALL publish the resolver the CLI uses to locate the pinned Vale grammar directory, together with the grammar package's spec, from the same modules the CLI dispatches on. + +A consumer that verifies a Vale rule over source code has to run it with the grammars the CLI runs it with: without them Vale reads comments by delimiters and reports different findings for the same rule. Publishing the resolver makes the grammar version a consequence of the CLI pin, as the binary version already is. + +Resolution SHALL report a miss as a value, returning an absent path alongside the locations searched, and SHALL NOT throw, for the reason the binary resolver does: each caller decides whether a miss is fatal. + +#### Scenario: A consumer runs Vale with the CLI's grammars + +- **WHEN** a consumer imports the runtimes entry and resolves the grammar directory +- **THEN** it SHALL receive the absolute path of the directory the CLI names to Vale +- **AND** the resolver SHALL be the module the CLI itself uses, not a copy kept in step + +#### Scenario: The grammar package does not resolve + +- **WHEN** the grammar package is not installed +- **THEN** resolution SHALL return an absent path and the locations it searched +- **AND** it SHALL NOT throw diff --git a/openspec/specs/cli-vale-rule-engine/spec.md b/openspec/specs/cli-vale-rule-engine/spec.md index afdd7eab..01dfd9a5 100644 --- a/openspec/specs/cli-vale-rule-engine/spec.md +++ b/openspec/specs/cli-vale-rule-engine/spec.md @@ -327,3 +327,54 @@ The engine SHALL NOT choose a separator between notices: presentation belongs to - **WHEN** the config schema advises on an assembled rule and the Vale binary is unavailable - **THEN** the advisory and the unavailability message SHALL both reach the result, as separate notices + +### Requirement: Vale reads source code with the pinned grammars + +Every Vale invocation the CLI makes, for `check` and for `verify`, SHALL name the directory of the pinned grammar package as Vale's grammar directory. Vale reads that directory for any grammar its StylesPath does not hold. + +Every comment-tier extension the CLI lists SHALL be covered: run against the pinned binary with the pinned grammars, no listed extension SHALL produce a warning that its grammar is not installed. A listed extension Vale reads by delimiters with no grammar at all, as it did before grammars were separate, is not a gap. + +When the grammar package cannot be resolved, Vale SHALL still run, and its warnings that a grammar is not installed SHALL reach the user as notices, as any other zero-exit diagnostic does. + +#### Scenario: A directive comment is not linted as prose + +- **WHEN** a rule over comments runs on a Go file whose first line is `//nolint:simply` and whose second line is `// simply here` +- **THEN** the rule SHALL report line 2 and SHALL NOT report line 1 + +#### Scenario: A one-line CSS block comment is linted + +- **WHEN** a rule over comments runs on a CSS file containing `/* simply here */` +- **THEN** the rule SHALL report that line + +#### Scenario: No grammar warning on a covered extension + +- **WHEN** `check` runs Vale over a file with any comment-tier extension the CLI lists +- **THEN** Vale SHALL write no warning that a grammar is not installed, and the result SHALL carry no such notice + +#### Scenario: An extension needing an unshipped grammar fails the contract + +- **WHEN** a comment-tier extension is listed whose grammar the pinned grammar package does not carry +- **THEN** the vendor contract SHALL fail, naming the extension and the grammar + +### Requirement: A grammar directory in the Vale rules tree is refused + +The Vale rules tree is the StylesPath of every assembled config, and Vale reads a grammar from the StylesPath in preference to the pinned grammar directory. The system SHALL therefore refuse a grammar directory inside the Vale rules tree, whatever it contains, because its grammars were not shipped or pinned by the CLI. + +The refusal SHALL be made where the Vale config is assembled, so that `validate` and `check` both refuse it. Under `check` it SHALL refuse the Vale engine as a rejected rule config does: the engine reports a failure naming the directory, the failure reaches the exit code, and other engines still run. + +#### Scenario: validate refuses an unvetted grammar directory + +- **WHEN** `.taskless/rules/vale/config/grammars/` exists and `validate` runs +- **THEN** `validate` SHALL report a failure naming that directory and SHALL exit non-zero + +#### Scenario: check refuses the Vale engine over an unvetted grammar directory + +- **WHEN** `.taskless/rules/vale/config/grammars/` exists and `check` runs +- **THEN** the Vale engine SHALL report a failure naming that directory without running Vale +- **AND** the exit code SHALL be non-zero +- **AND** ast-grep results for the same run SHALL still be reported + +#### Scenario: A grammar directory elsewhere is not the CLI's concern + +- **WHEN** the project's own Vale StylesPath, outside the Vale rules tree, holds grammars from a user's `vale sync` +- **THEN** `validate` and `check` SHALL neither refuse nor read them diff --git a/openspec/specs/vale-binary-packages/spec.md b/openspec/specs/vale-binary-packages/spec.md index 3de6c3f8..248b0429 100644 --- a/openspec/specs/vale-binary-packages/spec.md +++ b/openspec/specs/vale-binary-packages/spec.md @@ -134,3 +134,66 @@ This is what allows the release workflow to run unattended. - **WHEN** a platform package is published for a newer upstream Vale release - **THEN** consumers continue to resolve the version they pin, and none resolves the new package until its pin is changed + +### Requirement: Vale's grammars are published as one platform-independent package + +The repository SHALL publish one npm package, `@taskless/vale-grammars`, carrying every tree-sitter grammar module that upstream publishes for the Vale release the platform packages carry. It SHALL declare no `os` or `cpu`, so every host installs the same bytes. + +The package SHALL follow the platform packages' rules for contents and versioning: grammar modules and package metadata only, no `bin` entry, no executable JavaScript, no lifecycle script, and a version of `-` whose Vale component is the release the grammars came from. + +#### Scenario: Every host installs the same grammars + +- **WHEN** the grammar package is installed on two hosts with different operating systems or architectures +- **THEN** both hosts SHALL receive byte-identical grammar modules + +#### Scenario: The grammar version names its Vale release + +- **WHEN** a grammar package version is read +- **THEN** its `major.minor.patch` component SHALL be the upstream Vale release whose grammars it carries + +#### Scenario: Grammars are usable without an install step + +- **WHEN** the grammar package is installed with dependency lifecycle scripts disabled +- **THEN** the grammar modules SHALL be present and readable, and the package SHALL declare no `bin` and no `scripts` entry + +### Requirement: Fetched grammars are verified against committed checksums + +The repository SHALL commit a SHA256 checksum for each upstream grammar archive. Upstream's checksums file does not cover these archives, so the detect phase SHALL take each digest from the digest the upstream release records for that asset, SHALL refuse an asset that has none, and SHALL propose the digests in the same manifest pull request as the binary digests, where a human reviews them before anything can be published. + +The release pipeline SHALL verify every fetched grammar archive against its committed checksum before unpacking it, SHALL refuse to publish on a mismatch, and SHALL refuse to publish when an archive the manifest names is missing upstream. Grammar modules SHALL NOT be stored in version control. + +#### Scenario: Grammar checksum mismatch aborts the release + +- **WHEN** a fetched grammar archive's SHA256 does not match its committed checksum +- **THEN** the release SHALL fail and no package, platform or grammar, SHALL be published + +#### Scenario: A new upstream release proposes grammar digests for review + +- **WHEN** the detect phase finds upstream Vale ahead of the manifest +- **THEN** the pull request it opens SHALL update every grammar digest alongside the binary digests, and SHALL publish nothing + +#### Scenario: A clean checkout contains no grammar modules + +- **WHEN** the repository is cloned +- **THEN** no grammar module SHALL be present in the grammar package directory + +### Requirement: The grammar package is released with the platform packages + +The workflow that releases the platform packages SHALL also release the grammar package, from the same reviewed manifest, stamped with the same version as the platform packages in the same run. A run SHALL be considered already published only when both the platform packages and the grammar package have a version for the pinned Vale release. + +The CLI's dependencies on the grammar package and on the platform packages SHALL be moved together, by the same pull request, and SHALL all be the same exact stamped version. Publishing the grammar package SHALL change no consumer until that pin moves. + +#### Scenario: Merging the update publishes binaries and grammars together + +- **WHEN** a manifest update pull request is merged +- **THEN** every platform package and the grammar package SHALL be stamped with one version and published in the same run + +#### Scenario: Missing grammars keep the gate open + +- **WHEN** the platform packages are published for the pinned Vale release and the grammar package is not +- **THEN** the publish gate SHALL NOT report the release as already published + +#### Scenario: The pins never straddle two Vale releases + +- **WHEN** the pull request that moves the CLI's Vale pins is opened +- **THEN** it SHALL move the grammar package pin with the platform pins, all to one exact stamped version From 88d3f4b7ba5b03d41a156618e0970975dbde1ad3 Mon Sep 17 00:00:00 2001 From: Jakob Heuser Date: Thu, 19 Nov 2026 17:49:49 -0800 Subject: [PATCH 6/6] fix(vale): pin validate's refusal with no Vale rules, and say the directory exists Review on #705 asked whether validate and check disagree on a project with no Vale rules and a stale config/grammars directory. Measured: both fail, because config/ itself is listed as a rule directory and validate judges it. That held by accident, so a test now pins it. The message said the directory "holds Vale grammars" even when empty, which is also refused. It now says the directory exists. --- packages/cli/src/rules/vale/grammar-tree.ts | 11 ++++++++--- packages/cli/test/constraints.test.ts | 2 +- .../cli/test/validate-verify-commands.test.ts | 17 ++++++++++++++++- 3 files changed, 25 insertions(+), 5 deletions(-) diff --git a/packages/cli/src/rules/vale/grammar-tree.ts b/packages/cli/src/rules/vale/grammar-tree.ts index 8ab3f6c0..2d1749a5 100644 --- a/packages/cli/src/rules/vale/grammar-tree.ts +++ b/packages/cli/src/rules/vale/grammar-tree.ts @@ -31,6 +31,11 @@ export const VALE_TREE_GRAMMARS = [ * over the pinned one for that language. Shared by `validate`, which reports * it against every Vale rule, and by assembly, which refuses the `check` run, * so the two cannot disagree about what they found. + * + * That includes a project with no Vale rules at all. `validate` then still + * has one directory to judge, `config/` itself, which `listRuleIds` reports + * like any other, so it fails on this check exactly where `check` refuses. + * `validate-verify-commands.test.ts` pins that case. */ export async function valeTreeGrammarsViolation( cwd: string @@ -41,8 +46,8 @@ export async function valeTreeGrammarsViolation( return { constraintId: "vale-tree-no-grammars", message: - `${VALE_TREE_GRAMMARS} holds Vale grammars the CLI did not ship. Vale ` + - `would read them before the pinned grammars, so they are refused. ` + - `Remove the directory.`, + `${VALE_TREE_GRAMMARS} exists. Vale would read any grammar placed ` + + `there before the pinned grammars, so the directory is refused even ` + + `when empty. Remove it.`, }; } diff --git a/packages/cli/test/constraints.test.ts b/packages/cli/test/constraints.test.ts index 06b9afd2..a0536e29 100644 --- a/packages/cli/test/constraints.test.ts +++ b/packages/cli/test/constraints.test.ts @@ -294,7 +294,7 @@ const VIOLATIONS: Record = { }); return verifyValeConfig(VALID_VALE_CONFIG); }, - names: /config\/grammars holds Vale grammars the CLI did not ship/, + names: /config\/grammars exists\. Vale would read any grammar placed there/, }, }; diff --git a/packages/cli/test/validate-verify-commands.test.ts b/packages/cli/test/validate-verify-commands.test.ts index 3fc19317..1473fcb8 100644 --- a/packages/cli/test/validate-verify-commands.test.ts +++ b/packages/cli/test/validate-verify-commands.test.ts @@ -271,11 +271,26 @@ describe("validate checks components without requiring tests", () => { rule?.violations.map((violation) => violation.constraintId) ).toEqual(["vale-tree-no-grammars"]); expect(rule?.violations[0]?.message).toContain( - ".taskless/rules/vale/config/grammars holds Vale grammars the CLI did not ship" + ".taskless/rules/vale/config/grammars exists. Vale would read any grammar placed there" ); } ); + // With no Vale rule left, `check` still refuses a stale grammar directory, + // so `validate` must fail too rather than pass a tree `check` rejects. It + // does through `config/` itself, which is listed like any rule directory. + it("refuses a grammar directory when no Vale rule is left", async () => { + await mkdir(join(cwd, ".taskless", "rules", "vale", "config", "grammars"), { + recursive: true, + }); + const result = await runCli(["validate", "-d", cwd, "--json"]); + expect(result.exitCode).not.toBe(0); + const violations = (JSON.parse(result.stdout) as Report).rules.flatMap( + (rule) => rule.violations.map((violation) => violation.constraintId) + ); + expect(violations).toContain("vale-tree-no-grammars"); + }); + // The style schema's own advisory, through the real CLI. // `vale-schema-contract.test.ts` holds the advisory to its rule; this says // it reaches `notices` on `validate` output and `--json`, beside whatever the