Skip to content

feat(vale): publish Vale's grammars as @taskless/vale-grammars - #704

Merged
theCodeDrift merged 5 commits into
mainfrom
vale-grammars-package
Nov 20, 2026
Merged

theCodeDrift merged 5 commits into
mainfrom
vale-grammars-package

Conversation

@theCodeDrift

@theCodeDrift theCodeDrift commented Nov 20, 2026 •

Copy link
Copy Markdown
Member

Stack (root → tip):

Vale 3.27.0 moved its tree-sitter grammars out of the binary into WebAssembly modules that vale sync installs. We never run vale sync, so on 3.27.0 Vale reads code comments by their delimiters. That's what fails 6 vendor-contract cases on #703:

  • Linter directives (//nolint, # noqa, // eslint-disable…, // NOSONAR) and Python docstring :param: lines get linted as prose.
  • One-line CSS /* … */ comments aren't linted at all.
  • Every run warns W101 grammar "<name>" is not installed for each language.

With the upstream grammars supplied through VALE_GRAMMARS_PATH, all 373 Vale tests pass on 3.27.0 unchanged.

This is the first of two landings. It packages and publishes the grammars as one platform-independent package, @taskless/vale-grammars, so every OS gets the same bytes. It changes nothing for a CLI user. The CLI doesn't pin the new package until the second PR, so there's no changeset.

What's here

  • OpenSpec change vale-grammars-package: proposal, design, and deltas for vale-binary-packages, cli-vale-rule-engine and cli-runtime-binary-export. It's archived by the second PR.
  • vale-manifest.json gains a grammars section pinning all 22 upstream grammar archives for 3.27.0. Upstream's checksums.txt doesn't cover them, so each digest is the sha256 GitHub records for the release asset at upload. Detect reads those from the releases API, and you can check them the same way: gh api repos/errata-ai/vale/releases/tags/v3.27.0 --jq '.assets[]|select(.name|startswith("grammar-"))|"\(.name) \(.digest)"'. All 22 match a local download.
  • vale-prepare.cjs verifies each archive against the manifest, then streams its one .wasm member out with unzip -p and checks the WebAssembly magic bytes. No archive path is ever written to disk. --version stamps at a version the rest of the set already has, for the bootstrap below.
  • vale-gate.cjs counts the grammar package as part of a published release. vale-detect.cjs rewrites the grammar list and digests from the release's assets.
  • vale-upgrade-detect.cjs needs no logic change. The grammar package matches @taskless/vale-*, so once pinned it's held to the same single exact version as the binaries. New tests cover that.
  • packages/vale-grammars/: metadata only. The modules are gitignored and placed by the pipeline.

The workflow filenames, workflow names and environment: are unchanged, so the existing OIDC bindings still hold.

Before merging: bootstrap publish (maintainer)

npm trusted publishing can't create a package, so the first publish is manual, and it has to happen before this merges. Otherwise the gate sees the grammar package missing and tries to publish all seven.

node .github/scripts/vale-prepare.cjs --only grammars --version 3.27.0-20261117230017
npm publish --access public --tag latest .vale-dist/taskless-vale-grammars-3.27.0-20261117230017.tgz

Then register the trusted publisher for @taskless/vale-grammars against release-vale.yml and the npm-autopublish environment. The stamp matches the 3.27.0 binaries, so all seven pins can share one version. After merging, the gate should report all seven published and publish nothing.

Next

The second PR is cut from #703's head. It pins the grammar package, sets VALE_GRAMMARS_PATH, refuses a .taskless/rules/vale/config/grammars/ directory in validate and check, exports the grammar resolver from @taskless/cli/node/runtimes, adds the coverage check, and supersedes #703.

Refs #703

Vale 3.27.0 moved its tree-sitter grammars out of the binary. Without
them it reads code comments by delimiters, which fails 6 vendor-contract
cases on #703. Propose @taskless/vale-grammars, pinned and released with
the platform packages, named to Vale through VALE_GRAMMARS_PATH.
Vale 3.27.0 ships its tree-sitter grammars as separate WebAssembly
modules. Add a grammars section to vale-manifest.json pinning all 22
upstream grammar archives for 3.27.0. Upstream's checksums file does not
cover them, so each digest is the one GitHub records for the release
asset; all 22 match a local download.

vale-release.cjs validates the section, lists the seven packages a
release covers, reads grammar digests from a release's asset list, and
accepts an explicit stamp for the grammar package's bootstrap publish.
packages/vale-grammars holds only metadata; the pipeline places the
modules.

The design and tasks now record the GitHub digest source and that all
seven pins share one exact stamp, as vale-upgrade-detect already
requires.
vale-prepare.cjs packs @taskless/vale-grammars beside the six platform
packages. Each grammar archive is verified against its committed digest,
then its one module is streamed out with unzip -p and must carry the
WebAssembly magic, so nothing in the archive reaches the filesystem.
--version stamps a package at a version the set already carries, for
the grammar package's manual first publish.

vale-detect.cjs reads the grammar list and digests from the release's
asset list; vale-gate.cjs counts the grammar package as part of a
published release. vale-upgrade-detect.cjs needs no change: the grammar
pin matches @taskless/vale-* and is held to the same single version,
which the new tests pin. Workflow comments and PR bodies now say seven.
@theCodeDrift theCodeDrift added the skip-changeset PR intentionally ships no release note (bypasses the changeset requirement) label Nov 20, 2026
@theCodeDrift

Copy link
Copy Markdown
Member Author

@claude /review

@github-actions github-actions Bot added the Open OpenSpec Contains unresolved OpenSpec changes. All openspec changes must eventually reach an archive state. label Nov 20, 2026
@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

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


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

.prior-review.json contained no review threads, no reviews, and no top-level comments other than the trigger itself — this is the first review of this PR, so everything below is assessed fresh against the whole diff.

  • Read .prior-review.json
  • Fetch PR diff and metadata (gh pr diff, gh pr view)
  • Review vale-prepare.cjs, vale-gate.cjs, vale-detect.cjs, vale-release.cjs, vale-upgrade-detect.cjs
  • Review manifest, workflows, package metadata
  • Post findings

Summary

This is a careful, well-tested piece of infrastructure work. The core additions hold up under close reading:

  • Path/command safety: readGrammarMember in vale-prepare.cjs passes the archive path and member as argv to unzip -p (never through a shell), and since the member is never extracted to disk, a ../ or symlinked member can't place a file anywhere — assertWasmModule catches a symlink-target string or wrong-file read by rejecting anything that isn't a real wasm module. assertGrammars in vale-release.cjs validates archiveMember for ../absolute/empty segments and restricts grammar names to a safe character set, so a hand-edited manifest can't be used to traverse out of the archive.
  • Ordering: downloads are checksummed against the committed manifest digest before anything is read out of the archive, consistently, for both platforms and grammars.
  • Cross-cutting correctness: manifestPackages() is now the single source of truth consumed by vale-gate.cjs (publish-gate completeness) and planStamp (shared stamping), so the grammar package can't be silently dropped from either. vale-upgrade-detect.cjs needs no code change because its PIN_PATTERN already matches @taskless/vale-grammars, and the new tests exercise that it is held to the same one-version-for-the-set invariant as the platform pins, and that it lives in dependencies (not optionalDependencies) while still being collected correctly by collectPins.
  • Tests: new cases cover the manifest validation edge cases (missing fields, path traversal attempts, duplicate names/packages), the digest-sourcing paths (planGrammarModules, including the "no assets" and "no digest" failure cases), the gate's partial-publish matrix, and the upgrade script's "grammars pinned at a different version blocks the upgrade" case. This is a good spread for a change that's otherwise hard to exercise end-to-end (there's no vale-prepare.test.cjs, but that matches the existing architecture — the I/O-heavy prepare script has no tests before this PR either; the testable logic already lives in vale-release.cjs).

Two minor, non-blocking documentation nits found ([New]):

  1. .github/scripts/vale-gate.cjs:9 and :23 — the top-of-file docstring still says "would publish six fresh packages" and "requiring all six makes the gate double as partial-release repair," but planPublish now iterates manifestPackages(manifest), which is seven packages (six platforms + grammars). Every other file touched in this PR (the workflow YAML headers, vale-prepare.cjs, the README) was carefully updated from "six" to "seven" or genericized to "every package" — this script's own header comment was missed. Purely cosmetic (the code itself is correct and generic), but worth a one-line fix for consistency since this file's comments are otherwise treated as load-bearing documentation elsewhere in the PR.
  2. .github/scripts/vale-gate.test.cjs:6 — same stale "six packages" reference in the file's top docstring, same low-priority nit.

Nothing else raised. In particular, I did not find issues with: the digest validation logic, the stamp/version invariants (assertRequestedStamp correctly restricts --version to the manifest's own Vale release), the manifest's new grammars section (digest lengths/format match SHA256_PATTERN, and the committed values are independently checkable per the PR description), the release-notes assets plumbing, or the packages/vale-grammars/ package metadata (no bin/scripts, correct files, correct publishConfig).

@theCodeDrift

Copy link
Copy Markdown
Member Author

Re: @github-actions — "Claude finished @theCodeDrift's task in 3m 3s… Two minor, non-blocking documentation nits"
#704 (comment)

Both nits are fixed in a83b34d: vale-gate.cjs and vale-gate.test.cjs now say seven packages, including two more "six lookups" mentions in the same file.

— AI Coding Agent

@theCodeDrift
theCodeDrift merged commit ae2147d into main Nov 20, 2026
4 checks passed
@theCodeDrift
theCodeDrift deleted the vale-grammars-package branch November 20, 2026 02:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Open OpenSpec Contains unresolved OpenSpec changes. All openspec changes must eventually reach an archive state. skip-changeset PR intentionally ships no release note (bypasses the changeset requirement)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant