Merge pull request #25036 from dvdksn/vale

vale: overhaul ruleset to reduce noise and false positives

Author: dvdksn

.agents/skills/write/SKILL.md

@@ -45,7 +45,7 @@ Prettier runs automatically after each edit via the PostToolUse hook.
 Run lint manually after all edits are complete:
 
 ```bash
-${CLAUDE_SKILL_DIR}/scripts/lint.sh <changed-files>
+scripts/lint.sh <changed-files>
 ```
 
 The lint script runs markdownlint and vale on only the files you pass it,

.vale.ini

@@ -3,45 +3,34 @@ MinAlertLevel = suggestion
 IgnoredScopes = text.frontmatter, code, tt, b, strong, i, a
 Vocab = Docker
 
-# Disable rules for genered content
-[content/reference/**/**.md]
-Vale.Spelling = NO
-Vale.Terms = NO
+# Generated reference content — disable rules that don't apply
+[content/reference/**]
 Docker.Capitalization = NO
-
-[content/manuals/*/release-notes/*.md]
 Vale.Spelling = NO
 Vale.Terms = NO
-Docker.Capitalization = NO
-Docker.We = NO
 
-[content/manuals/*/release-notes.md]
-Vale.Spelling = NO
-Vale.Terms = NO
-Docker.Capitalization = NO
-Docker.We = NO
-
-[content/contribute/*.md]
-Vale.Spelling = NO
-Vale.Terms = NO
+# Skip release notes and old desktop changelog content entirely
+[{content/manuals/*/release-notes.md,content/manuals/*/release-notes/**,content/manuals/desktop/previous-versions/**}]
+Docker.Avoid = NO
 Docker.Capitalization = NO
 Docker.Exclamation = NO
-
-[content/manuals/desktop/previous-versions/*.md]
+Docker.Forbidden = NO
+Docker.GenericCTA = NO
+Docker.HeadingPunctuation = NO
+Docker.ListComma = NO
+Docker.OxfordComma = NO
+Docker.RecommendedWords = NO
+Docker.Spacing = NO
+Docker.Terms = NO
+Docker.URLFormat = NO
+Docker.Units = NO
+Docker.VersionText = NO
+Docker.We = NO
 Vale.Spelling = NO
+Vale.Repetition = NO
 Vale.Terms = NO
-Docker.Capitalization = NO
-Docker.Exclamation = NO
 
 [*.md]
-BasedOnStyles = Vale, Docker
-# Exclude `{{< ... >}}`, `{{% ... %}}`, [Who]({{< ... >}})
-TokenIgnores = ({{[%<] .* [%>]}}.*?{{[%<] ?/.* [%>]}}), \
-(\[.+\]\({{< .+ >}}\)), \
-[^\S\r\n]({{[%<] \w+ .+ [%>]}})\s, \
-[^\S\r\n]({{[%<](?:/\*) .* (?:\*/)[%>]}})\s, \
-(?sm)({{[%<] .*?\s[%>]}})
-
-# Exclude `{{< myshortcode `This is some <b>HTML</b>, ... >}}`
-BlockIgnores = (?sm)^({{[%<] \w+ [^{]*?\s[%>]}})\n$, \
-(?s) *({{< highlight [^>]* ?>}}.*?{{< ?/ ?highlight >}})
+BasedOnStyles = Docker, Vale
+TokenIgnores = ({{[%<][^}]+[%>]}})
+BlockIgnores = (?m)^[ \t]*({{[%<][^}]+[%>]}})[ \t]*$

AGENTS.md

@@ -80,6 +80,25 @@ introduced, which is permanently true.
 
 - Use lowercase "config" in prose — `vale.Terms` flags a capital-C "Config"
 
+### Updating the vocabulary
+
+If Vale flags a legitimate tech term, product name, or compound identifier
+as a misspelling, add it to `_vale/config/vocabularies/Docker/accept.txt`.
+This is optional — only update when a real new term is missing, not to
+silence individual violations.
+
+- Use the canonical form for case-sensitive product names (`PyTorch`,
+  `GitHub`, `Kubernetes`, `BuildKit`). `Vale.Terms` enforces that exact
+  case across the docs.
+- Use `[Aa]bcd` character-class regex for words that legitimately appear
+  in multiple cases (e.g., sentence-starting capitalization, or a name
+  that's also a generic noun). This covers spelling without enforcing
+  a single canonical form.
+- Avoid broad regex patterns — entries that match many words at once
+  (especially with `(?i)`) suppress other rule checks on every match.
+- Don't add a wrong-cased entry to silence one false positive — it
+  cascades into `Vale.Terms` violations on every correct usage.
+
 ## Alpine.js patterns
 
 Do not combine Alpine's `x-show` with the HTML `hidden` attribute on the
@@ -111,12 +130,17 @@ produces broken HTML — always check COMPONENTS.md for correct syntax.
 
 ```sh
 npx prettier --write <file>        # Format before committing
+scripts/lint.sh <file>...          # Lint specific files (markdownlint + vale)
 docker buildx bake validate        # Run all validation checks
 docker buildx bake lint            # Markdown linting only
 docker buildx bake vale            # Style guide checks only
 docker buildx bake test            # HTML and link checking
 ```
 
+For incremental work, prefer `scripts/lint.sh` over the `bake` targets —
+it runs the same checks on just the files you pass, so the output stays
+scoped to your changes instead of the whole repo.
+
 ### Validation in git worktrees
 
 `docker buildx bake validate` fails in git worktrees because Hugo cannot
@@ -128,9 +152,14 @@ and `validate-vendor` targets run correctly in CI.
 
 1. Make changes
 2. Format with prettier: `npx prettier --write <file>`
-3. Run `docker buildx bake lint vale`
+3. Lint the changed files: `scripts/lint.sh <file>...`
 4. Run a full build with `docker buildx bake` (optional for small changes)
 
+Always lint the specific files you changed before committing. Use
+`scripts/lint.sh` rather than the `bake` targets so the output is scoped
+to your changes — bake runs across the entire repo and the noise makes
+real issues easy to miss.
+
 ## Git hygiene
 
 - **Stage files explicitly.** Never use `git add .` / `git add -A` /

_vale/Docker/Capitalization.yml

@@ -7,4 +7,4 @@ action:
   params:
     - Docker
 tokens:
-  - '[^\[/]docker[^/]'
+  - '[^\[/\-.]docker[^/\-.\w]'

_vale/Docker/RecommendedWords.yml

@@ -37,5 +37,5 @@ swap:
   repo: repository
   scroll: navigate
   url: URL
-  vs: versus
+  '\bvs\b(?!\.|\s+Code)': versus
   wish: want

_vale/Docker/Units.yml

@@ -3,7 +3,7 @@ message: "Use '%s' instead of '%s'"
 link: https://docs.docker.com/contribute/style/recommended-words/
 level: error
 swap:
-  (?:kilobytes?|KB): kB
+  kilobytes?: kB
   gigabytes?: GB
   megabytes?: MB
   petabytes?: PB

_vale/Docker/VersionText.yml

@@ -4,9 +4,9 @@ link: https://docs.docker.com/contribute/style/recommended-words/#later
 scope: raw
 raw:
   - '\bv?'
-  - '(?P<major>0|[1-9]\d*)\.?'
-  - '(?P<minor>0|[1-9]\d*)?\.?'
-  - '(?P<patch>0|[1-9]\d*)?'
+  - '(?P<major>0|[1-9]\d*)\.'
+  - '(?P<minor>0|[1-9]\d*)'
+  - '(?:\.(?P<patch>0|[1-9]\d*))?'
   - '(?:-(?P<prerelease>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?'
   - '(?:\+(?P<buildmetadata>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?'
   - '\b (and|or) (higher|above)'

_vale/Docker/We.yml

@@ -1,10 +1,11 @@
 extends: existence
 message: "Avoid using first-person plural like '%s'."
 level: warning
-ignorecase: true
+ignorecase: false
 tokens:
-  - we
-  - we'(?:ve|re)
-  - ours?
+  - '[Ww]e'
+  - "[Ww]e'(?:ve|re)"
+  - '[Oo]urs?'
   - us
-  - let's
+  - Us
+  - "[Ll]et's"

_vale/config/vocabularies/Docker/accept.txt

@@ -81,7 +81,7 @@ dockerignore
 Dockerize
 Dockerized
 Dockerizing
-Duckduckgo
+DuckDuckGo
 Entra
 EPERM
 ESXi
@@ -92,7 +92,7 @@ Fargate
 Fedora
 firewalld
 Flink
-fluentd
+Fluentd
 g?libc
 GeoNetwork
 GGUF
@@ -145,7 +145,6 @@ logback
 Loggly
 Logstash
 lookup
-Mac
 macOS
 macvlan
 Mail(chimp|gun)
@@ -223,7 +222,7 @@ stdin
 stdout
 subfolder
 sudo
-subvolume
+[Ss]ubvolume
 Syft
 syntaxes
 Sysbox
@@ -243,8 +242,7 @@ Ubuntu
 ufw
 uv
 umask
-uncaptured
-Uncaptured
+[Uu]ncaptured
 unconfigured
 undeterminable
 Unix
@@ -253,7 +251,7 @@ unmanaged
 upsert
 Visual Studio Code
 VMware
-vpnkit
+VPNKit
 vSphere
 Vulkan
 Vue
@@ -312,7 +310,7 @@ Zsh
 [Pp]roxied
 [Pp]roxying
 [pP]yright
-[Rr]eadme
+README
 [Rr]eal-time
 [Rr]egex(es)?
 [Rr]untimes?
@@ -346,3 +344,75 @@ Zsh
 [Ee]vals?
 [Ll]abspaces?
 [Uu]nsloth
+AppArmor
+[Aa]utolocking
+[Bb]oolean
+[Bb]reakpoint
+CMD
+[Dd]eno
+[Dd]evicemapper
+[Dd]ockerbot
+[Dd]ockerd
+docker_ce_version
+[Ee]nv
+ESLint
+gzip
+HAProxy
+[Ii]nlined
+journald
+JSON
+keypair
+Kustomize
+latest_engine_api_version
+[Mm]iddleware
+[Nn]onroot
+param
+[Pp]erformant
+Pinecone
+Qdrant
+[Rr]outable
+[Ss]emver
+setuid
+SHA
+spaCy
+src
+stderr
+Streamlit
+[Ss]ubcommand
+syslog
+TCP
+thinpool
+[Tt]runked
+UID
+[Uu]nencrypted
+[Uu]nmount
+URL
+VM
+Vite
+Vitest
+Wolfi
+[Aa]utoextend
+[Bb]ackoff
+[Bb]crypt
+[Bb]undler
+copy_up
+[Dd]eclaratively
+[Dd]eduplication
+dnf
+docker_gwbridge
+[Gg]lobbing
+GPG
+KVM
+[Mm]ulticast
+[Mm]isconfigured
+oldstable
+OpenSSL
+[Ss]tringified
+SwarmKit
+[Uu]ncomment
+Buildkite
+Graylog
+Libnetwork
+Nodemon
+PHPUnit
+PyTorch

.agents/skills/write/scripts/lint.sh scripts/lint.sh.agents/skills/write/scripts/lint.sh renamed to scripts/lint.sh

@@ -1,9 +1,9 @@
 #!/bin/bash
 # Run markdownlint and vale on specific files.
-# Usage: .agents/skills/write/scripts/lint.sh <file> [file...]
+# Usage: scripts/lint.sh <file> [file...]
 #
-# Designed for agent workflows — scoped output, no repo-wide noise.
-# For full repo validation, use: docker buildx bake validate
+# Scoped output — no repo-wide noise. For full repo validation, use:
+#   docker buildx bake validate
 set -uo pipefail
 
 if [ $# -eq 0 ]; then