diff --git a/.changeset/vale-3-27-0.md b/.changeset/vale-3-27-0.md new file mode 100644 index 000000000..d08b1bc19 --- /dev/null +++ b/.changeset/vale-3-27-0.md @@ -0,0 +1,9 @@ +--- +"@taskless/cli": patch +--- + +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 b95d0851a..49ab0c6ca 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/.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 89% rename from openspec/changes/vale-grammars-package/design.md rename to openspec/changes/archive/2026-11-19-vale-grammars-package/design.md index bc55a2c31..edf86ab8c 100644 --- a/openspec/changes/vale-grammars-package/design.md +++ b/openspec/changes/archive/2026-11-19-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/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 80% rename from openspec/changes/vale-grammars-package/tasks.md rename to openspec/changes/archive/2026-11-19-vale-grammars-package/tasks.md index da7b60dc1..16e1d6191 100644 --- a/openspec/changes/vale-grammars-package/tasks.md +++ b/openspec/changes/archive/2026-11-19-vale-grammars-package/tasks.md @@ -20,28 +20,28 @@ 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) -- [ ] 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) -- [ ] 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) -- [ ] 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 -- [ ] 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 6242cfc6d..dc492c393 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 afdd7eab3..01dfd9a56 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 3de6c3f8d..248b0429a 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 diff --git a/packages/cli/assets/reference.json b/packages/cli/assets/reference.json index c08c16f30..3c5969ac9 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/package.json b/packages/cli/package.json index 5dbfed57b..abf7d6e9c 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": { @@ -92,11 +93,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/agent/update.md b/packages/cli/src/agent/update.md index bfcfd6cb7..7a6fae138 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 diff --git a/packages/cli/src/generated/vale-vocabulary-report.md b/packages/cli/src/generated/vale-vocabulary-report.md index dc0e02e3c..75f82a4a9 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 0d5d477db..51e42650e 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/node/runtimes/index.ts b/packages/cli/src/node/runtimes/index.ts index 2064f9908..12d8a112e 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/assemble.ts b/packages/cli/src/rules/assemble.ts index 165930be9..61a5131a9 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/capabilities.ts b/packages/cli/src/rules/capabilities.ts index 05d631a2a..657365807 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/packages/cli/src/rules/constraints.ts b/packages/cli/src/rules/constraints.ts index 9c4f7bb20..5bf617a76 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 33bf4b7ef..9f9187434 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 083489c9c..4eb7cc365 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 000000000..2d1749a5d --- /dev/null +++ b/packages/cli/src/rules/vale/grammar-tree.ts @@ -0,0 +1,53 @@ +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. + * + * 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 +): 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} 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/src/rules/vale/grammars.ts b/packages/cli/src/rules/vale/grammars.ts new file mode 100644 index 000000000..6c0044552 --- /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 847f76598..fa395167b 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/constraints.test.ts b/packages/cli/test/constraints.test.ts index 412c69867..a0536e292 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 exists\. Vale would read any grammar placed there/, + }, }; 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 25f920e2d..cf0c8da10 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 new file mode 100644 index 000000000..3321a9c73 --- /dev/null +++ b/packages/cli/test/vale-grammars.test.ts @@ -0,0 +1,72 @@ +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" + ); + // 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 f66f1aa79..1d494e3e7 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 f0470f36b..95e2a16fa 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( @@ -2679,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 bcfa8420f..1473fcb83 100644 --- a/packages/cli/test/validate-verify-commands.test.ts +++ b/packages/cli/test/validate-verify-commands.test.ts @@ -241,6 +241,56 @@ 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 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 diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index d33f64601..c961643bd 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 @@ -164,23 +167,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 +894,36 @@ 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-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] 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 +3382,24 @@ 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-grammars@3.27.0-20261117230017': {} + + '@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':