Skip to content

fix(ci): repair the Vale prose gate - #197

Merged
oskarth merged 1 commit into
masterfrom
fix/vale-ci
Sep 10, 2026
Merged

fix(ci): repair the Vale prose gate#197
oskarth merged 1 commit into
masterfrom
fix/vale-ci

Conversation

@oskarth

@oskarth oskarth commented Sep 10, 2026

Copy link
Copy Markdown
Collaborator

The Prose Quality (Vale) job has never worked as a gate. It went red on every master push from the July rebrand until #196, and #196 turned it green by making it unable to fail. This fixes the underlying defects so the job can gate again.

Master is green because the step stopped reporting

#196 added continue-on-error: true to the Vale step. The green run itself still contains the failure. From run 34344604531, the first success on master in months:

##[warning]User-specified path (patterns
vendors
...
domains) is invalid; falling back to 'all'.
[command]/home/runner/vale --output=.../rdjsonl.tmpl .
...
reviewdog: found at least one result in diff
##[error]Vale and reviewdog exited with status code: 1

207 findings, exit 1, job green.

Three defects

1. The files input never reaches Vale. It was passed as a YAML block scalar. #196 changed that to a block scalar plus separator: "\n", which cannot work either: vale-action reads separator through @actions/core getInput, which trims whitespace, so the newline arrives as an empty string. The value then falls through to the JSON.parse branch in src/input.ts, throws, and the action falls back to .. So the job has been grading CHANGELOG.md, QA-AUDIT.md and rfps/ rather than the six content directories.

2. EthSystems.Marketing flags ordinary English. It matches the bare words only, first and unique, which produce most of the findings in the intended scope: "only the sender learns the amount", "the first step", "a unique nullifier". None of that is marketing language.

3. reviewdog exits 1 on any result, whatever fail_on_error says. On top of that GitHub caps annotations at 50 per job, so the same run also logs ##[error]reviewdog: Too many results (annotations) in diff. The job fails on volume, and the only way anyone found to stop it failing was to stop it reporting.

Why it started when it did

The last green run before #196 is 2ac67ab "chore: release v0.4.0" (2026-07-02), which touched only CHANGELOG.md and package.json. The first red run is b4ae66d "chore: rebrand (#176)" (2026-07-14), which rewrote about 50 files, and every push since failed the same way. The rebrand only renamed IPTF to EthSystems. The rules were always this broad; the repo had just never pushed a diff big enough to trip the cap.

What this changes

  • Marketing.yml matches promotional claims rather than bare words: the only solution, world's first, first-of-its-kind, truly unique, leading provider, plus the superlative and buzzword lists that were already there.
  • Terminology.yml drops the swap that forced Multi-Party Computation down to lower case, and GLOSSARY.md gets the title-case expansion back. fix(ci): clear the Vale findings that keep master red #195 lower-cased it to clear that finding, which left it disagreeing with FHE (Fully Homomorphic Encryption) and TEE (Trusted Execution Environment) on the lines around it. GLOSSARY.md is not one of the six directories the job lints, so the finding should never have been reported.
  • .vale.ini ignores file names used as markdown link text. pattern-dvp-erc7573.md is an identifier, not prose.
  • ci.yml passes files as a JSON array, the one form the action parses, and drops continue-on-error from the Vale step so it can gate again.
  • Content: the five genuine offenders (enterprise-grade, next-generation, scalable, robust, comprehensive) in five vendor and pattern cards, plus the remaining ERC-7573 and DA Layer drift.

fail_on_error and the reviewdog level are left alone. Fixing the rules is enough, and lowering the level would hide findings we want to see.

Verification

Vale 3.20.0, the version the action installs. The whole-repository count on master matches run 34344604531 exactly, which is the cross-check that the local method reproduces CI.

Scope master (b468053) this branch
The six linted directories 187 0
Whole repository 207 7

The 7 remaining are all outside what the job lints: file names in QA-AUDIT.md and the gitignored validation-report.md.

On a fixture with a positive block and a negative block, the new rules report 16 findings, all in the positive block: leading provider, enterprise-grade, world-class, best-in-class, comprehensive, cutting-edge, world's first, industry-first, first-of-its-kind, truly unique, uniquely positioned, the only solution, fastest, most secure, next-generation, one-stop. Zero in the negative block. The same fixture under master's rules produces three false positives on "Only the sender learns the amount", "a unique nullifier" and "first-come-first-served".

check-terminology.js passes on 154 files. validate-patterns.js exits 0 (word-count warnings only, unchanged by this PR).

Left open, worth separate issues

  • fail_on_error: false does nothing in this job. reviewdog returns 1 on any result regardless. The name is misleading and someone will trust it again.
  • The Validate Vendor Documentation job still greps the old broad word list and duplicates Vale. It is warning-only and has its own continue-on-error, so it cannot fail anything.
  • TCA: TCA and RFQ: RFQ in Terminology.yml are no-op self-swaps. Harmless, left alone to keep the diff tight.
  • origin/centaur/vale-master-green is the merged branch of fix(ci): clear the Vale findings that keep master red #195 and can be deleted.

The Prose Quality (Vale) job has never worked as a gate. #196 turned it
green by adding `continue-on-error: true`, so the step can no longer fail
the build. The green run itself proves it: run 34344604531 still logs
`##[error]Vale and reviewdog exited with status code: 1` after reporting
207 findings.

Three defects stack up.

1. The `files` input never reaches Vale. `.github/workflows/ci.yml` passed
   it as a YAML block scalar, and #196 changed that to a block scalar plus
   `separator: "\n"`. Neither works. vale-action reads `separator` through
   `@actions/core` `getInput`, which trims whitespace, so the newline
   arrives as an empty string and the multi-line `files` value falls
   through to `JSON.parse` and throws. The action logs "User-specified
   path is invalid; falling back to 'all'" and lints the whole repository
   instead of the six content directories.
2. EthSystems.Marketing flags the bare words "only", "first" and "unique".
   Those are ordinary technical prose and produce most of the findings in
   the linted scope.
3. reviewdog exits 1 on any result, whatever `fail_on_error` says, and
   GitHub caps annotations at 50 per job. So the job fails on volume, and
   the only way anyone found to stop it failing was to stop it reporting.

Changes:

- Scope the Marketing rule to promotional claims: "the only solution",
  "world's first", "first-of-its-kind", "truly unique", "leading
  provider", and the existing superlative and buzzword lists.
- Drop the Terminology swap that forced "Multi-Party Computation" to
  lower case, and restore the title-case expansion in GLOSSARY.md that
  #195 changed to satisfy it. The glossary writes "FHE (Fully Homomorphic
  Encryption)" and "TEE (Trusted Execution Environment)" in title case on
  the lines around it, and GLOSSARY.md is not one of the files the job
  lints, so that finding should never have been reported.
- Ignore file names used as markdown link text. They are identifiers, not
  prose.
- Pass `files` as a JSON array, the one form the action parses.
- Drop `continue-on-error` from the Vale step so it can gate again.
- Fix the real content: enterprise-grade, next-generation, scalable,
  robust and comprehensive in five vendor and pattern cards, plus the
  remaining ERC-7573 and DA Layer terminology drift.

Verified with Vale 3.20.0, the version CI installs. Findings in the
linted scope: 187 on master, 0 here. Whole repository: 207 to 7, all in
QA-AUDIT.md and the gitignored validation report, neither of which the
job lints. On a fixture the rules still catch "leading provider",
"enterprise-grade" and "world's first", and no longer flag "only the
sender learns the amount", "the first step" or "a unique nullifier".
@oskarth
oskarth merged commit d74a996 into master Sep 10, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants