Repository navigation
feat: enable Coder.AmbiguousWords Vale rule - #30792
Closed
nickvigilante wants to merge 6 commits into
Closed
nickvigilante wants to merge 6 commits into
nickvigilante wants to merge 6 commits into
Conversation
Add the style rules from the Docs style guide Linear project that the guide was missing, and fix the guide's own self-violations from the second ASD-STE100 audit. Each new Vale rule lands in its own PR based on this one, so every footer for those rules is marked planned. The Vale doctrine now lets suggestion-level rules land with existing findings, per Nick's decision on DOCS-450. Refs DOCS-1282, DOCS-1265
Base automatically changed from
vigilante/docs-1282-style-guide-add-missing-rules-from-the-docs-style-guide
to
main
October 16, 2026 13:53
…ds-that-have-one-meaning-rule-and Take main's style guide, which carries the squash-merged base commits from #30782, and add the Coder.AmbiguousWords row and counts on top. Assisted-by: AI
Run pnpm run format-docs so markdown-table-formatter aligns the table after the merge added a row. Assisted-by: AI
nickvigilante
marked this pull request as ready for review
October 23, 2026 05:27
nickvigilante
added a commit
that referenced
this pull request
Oct 23, 2026
> [!NOTE] > Recreated from #30792 under coder[bot] by Superblink, at the request of @nickvigilante, so he can review and merge it. An AI agent wrote the original, which was opened from his account. The diff is identical to #30792, squashed onto current `main`. Superblink reviewed it and ran Vale over `docs/` before opening this PR (no new warnings or errors). #30792 should be closed in favor of this one. > Stack: based on #31181 (#31180 → #31181 → #31182 → #31183 → #31184 → #31185). The diff matches #30792 except for the counters in `docs/.style/style-guide/README.md`, which build on the PRs below this one. `make lint/style-claims` passes at every level. > Vale run on current `main`: this rule adds about 655 `suggestion`-level alerts across `docs/`. That matches its documented `suggestion` severity, and `make lint/prose` never fails on them. Builds on #30782, which is merged; the branch now merges `main`. Adds `Coder.AmbiguousWords` at `suggestion` severity. The rule flags the `ensure` family, `should`, `since`, and `may`, and suggests the one-meaning replacement from the guide: `make sure`, `must` or a recommendation, `might` or `can`, and `because` or `after`. It covers `docs/**` except `docs/.style/style-guide/**` and the generated `docs/reference/{api,cli}/*.md` pages. Baseline: 655 findings on current `main`, no cleanup commit. At branch creation it was 663: 128 `ensure`, 19 `ensures`, 13 `ensuring`, 174 `should`, 58 `since`, and 271 `may`. The rule ships as a suggestion with its backlog, as `docs/.style/README.md` allows. DOCS-1283 tracks the cleanup and the promotion to `warning`. Known false positives: `since` and `should` can be correct in context, such as `since` for time ("since version 2.20") and a `should` that states an expectation. The rule can't tell, so it stays a suggestion. Linear: DOCS-1263 <details> <summary>Decision log</summary> - **Rule type**: `substitution` with one swap per word form, so the message names the replacement. Replacements follow the guide's table: `make sure`, `must, recommend`, `might, can`, `because, after`. - **Case**: `ignorecase: false`, with `[Ee]nsure` and `[Ss]hould` classes, so lowercase `may` and the month `May` stay distinct. - **`May`**: the pattern `\bMay\b(?!,?\s+\d)` skips the month when a digit follows ("May 5, 2026", "May 2026", "May, 2026"). Vale compiles lookaheads with a backtracking engine, so the pattern works. The sentence-initial `May` in a list item ("May include minor bugs") is flagged, which is correct. - **Generated pages**: `.vale.ini` excludes `docs/reference/{api,cli}/*.md`, as `Coder.UnitSpacing` does. Those pages hold 168 more findings that come from Go comments and CLI flag text. With the exclusion the baseline is 663, close to the 664 expected. - **Footer and table**: the section footer names `Coder.AmbiguousWords` at `suggestion` severity. The checks table gets a row, and the counts move word choice from 2 to 3 tool-checked. The formatter widened the Severity column because `suggestion` is longer than `warning`. Test cases, run with `vale --config` against fixtures that are not committed, in LF and CRLF with identical results: - Positive: `Ensure`, `ensures`, `ensured`, `ensuring`, `should`, `Since`, lowercase `may`, and `May` in "May the build fail", "Then May is risky", and "May happen". - Negative: "May 5, 2026", "May 2026", "May, 2026", "May 12", `maybe`, `mayor`, `shoulder`, `sincere`, and the same words inside code spans. - A plain `since` in prose is flagged, as intended. Checks: `make lint/style-claims` passes, the pre-commit hooks pass, and `vale --output=line docs/` reports 663 `Coder.AmbiguousWords` findings and no new findings from other rules. </details> *Generated by [Coder Agents](https://coder.com/docs/ai-coder/agents) on behalf of @nickvigilante.* Created on behalf of @nickvigilante --------- Co-authored-by: Nick Vigilante <nick.vigilante@coder.com>
Collaborator
Author
|
Superseded by #31182, which merged the same change into Generated by Coder Agents on behalf of @nickvigilante. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Builds on #30782, which is merged; the branch now merges
main.Adds
Coder.AmbiguousWordsatsuggestionseverity.The rule flags the
ensurefamily,should,since, andmay, and suggests the one-meaning replacement from the guide:make sure,mustor a recommendation,mightorcan, andbecauseorafter.It covers
docs/**exceptdocs/.style/style-guide/**and the generateddocs/reference/{api,cli}/*.mdpages.Baseline: 655 findings on current
main, no cleanup commit.At branch creation it was 663: 128
ensure, 19ensures, 13ensuring, 174should, 58since, and 271may.The rule ships as a suggestion with its backlog, as
docs/.style/README.mdallows.DOCS-1283 tracks the cleanup and the promotion to
warning.Known false positives:
sinceandshouldcan be correct in context, such assincefor time ("since version 2.20") and ashouldthat states an expectation.The rule can't tell, so it stays a suggestion.
Linear: DOCS-1263
Decision log
substitutionwith one swap per word form, so the message names the replacement.Replacements follow the guide's table:
make sure,must, recommend,might, can,because, after.ignorecase: false, with[Ee]nsureand[Ss]houldclasses, so lowercasemayand the monthMaystay distinct.May: the pattern\bMay\b(?!,?\s+\d)skips the month when a digit follows ("May 5, 2026", "May 2026", "May, 2026").Vale compiles lookaheads with a backtracking engine, so the pattern works.
The sentence-initial
Mayin a list item ("May include minor bugs") is flagged, which is correct..vale.iniexcludesdocs/reference/{api,cli}/*.md, asCoder.UnitSpacingdoes.Those pages hold 168 more findings that come from Go comments and CLI flag text.
With the exclusion the baseline is 663, close to the 664 expected.
Coder.AmbiguousWordsatsuggestionseverity.The checks table gets a row, and the counts move word choice from 2 to 3 tool-checked.
The formatter widened the Severity column because
suggestionis longer thanwarning.Test cases, run with
vale --configagainst fixtures that are not committed, in LF and CRLF with identical results:Ensure,ensures,ensured,ensuring,should,Since, lowercasemay, andMayin "May the build fail", "Then May is risky", and "May happen".maybe,mayor,shoulder,sincere, and the same words inside code spans.sincein prose is flagged, as intended.Checks:
make lint/style-claimspasses, the pre-commit hooks pass, andvale --output=line docs/reports 663Coder.AmbiguousWordsfindings and no new findings from other rules.Generated by Coder Agents on behalf of @nickvigilante.