Skip to content

feat: enable Coder.AmbiguousWords Vale rule - #30792

Closed
nickvigilante wants to merge 6 commits into
mainfrom
vigilante/docs-1263-style-guide-add-choose-words-that-have-one-meaning-rule-and
Closed

nickvigilante wants to merge 6 commits into
mainfrom
vigilante/docs-1263-style-guide-add-choose-words-that-have-one-meaning-rule-and

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 14, 2026 •

Copy link
Copy Markdown
Collaborator

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

Decision log
  • 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.

Generated by Coder Agents on behalf of @nickvigilante.

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
@linear-code

linear-code Bot commented Oct 14, 2026

Copy link
Copy Markdown

DOCS-1263

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
nickvigilante marked this pull request as ready for review October 23, 2026 05:27
coder Bot pushed a commit that referenced this pull request Oct 23, 2026
Recreated from #30792 under coder[bot] so it can be reviewed by its requester. Stacked on #31181.
nickvigilante added a commit that referenced this pull request Oct 23, 2026
Recreated from #30792 under coder[bot] so it can be reviewed by its requester. Stacked on #31181.
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>

@ianjevans ianjevans left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

@nickvigilante

Copy link
Copy Markdown
Collaborator Author

Superseded by #31182, which merged the same change into main as part of the stacked Vale rule PRs. Closing as a duplicate.

Generated by Coder Agents on behalf of @nickvigilante.

@github-actions github-actions Bot locked and limited conversation to collaborators Oct 24, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants