Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .changeset/vale-3-27-0.md
Original file line number Diff line number Diff line change
@@ -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.
2 changes: 1 addition & 1 deletion .taskless/taskless.json
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@
"reconciledTo": "0.13.7",
"engines": {
"sg": "0.51.3",
"vale": "3.26.0"
"vale": "3.27.0"
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -69,9 +69,13 @@ _Alternative: copy the grammars into `<StylesPath>/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 "<name>" 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 `<rules tree>/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

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<rules tree>/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 "<name>" 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 `<rules tree>/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 "<name>" 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`.
20 changes: 20 additions & 0 deletions openspec/specs/cli-runtime-binary-export/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
51 changes: 51 additions & 0 deletions openspec/specs/cli-vale-rule-engine/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
63 changes: 63 additions & 0 deletions openspec/specs/vale-binary-packages/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<valeVersion>-<yyyymmddhhmmss>` 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
Loading