From 4fe7724d16f18167ddefd4d0a116cee1a803d6c3 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Mon, 7 Sep 2026 08:28:33 +0000 Subject: [PATCH] vale: expand Docker prose checks Several documented prose patterns were not enforced, and agents could overlook non-fatal Vale warnings. Expand Docker's local Vale rules, remove obsolete rule links, and clarify scoped agent validation. --- .agents/skills/write/SKILL.md | 6 ++++-- .github/workflows/build.yml | 2 +- .vale.ini | 2 ++ AGENTS.md | 20 ++++++++++++++------ _vale/Docker/Avoid.yml | 11 ++++++++++- _vale/Docker/GenericCTA.yml | 1 - _vale/Docker/ListComma.yml | 1 - _vale/Docker/MetaCommentary.yml | 8 ++++++++ _vale/Docker/PromotionalOpeners.yml | 8 ++++++++ _vale/Docker/RecommendedWords.yml | 10 +++++++++- _vale/Docker/Units.yml | 1 - _vale/Docker/VersionText.yml | 1 - scripts/lint.sh | 20 ++++++++++++++++---- 13 files changed, 72 insertions(+), 19 deletions(-) create mode 100644 _vale/Docker/MetaCommentary.yml create mode 100644 _vale/Docker/PromotionalOpeners.yml diff --git a/.agents/skills/write/SKILL.md b/.agents/skills/write/SKILL.md index 1b6879aa7d..24195efc42 100644 --- a/.agents/skills/write/SKILL.md +++ b/.agents/skills/write/SKILL.md @@ -45,11 +45,13 @@ rumdl runs automatically after each edit via the PostToolUse hook. Run lint manually after all edits are complete: ```bash -scripts/lint.sh +scripts/lint.sh ``` The lint script runs rumdl and Vale on only the files you pass it, -so the output is scoped to your changes. Fix any errors it reports. +so the output is scoped to your changes. Fix errors and warnings on lines you +added or changed, and review each suggestion. Vale can exit successfully when +warnings or suggestions remain in its output. ## 5. Self-review diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index f92187e766..992f6e7485 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -106,6 +106,6 @@ jobs: name: Run reviewdog for vale if: ${{ matrix.target == 'vale' && github.event_name == 'pull_request' }} run: | - cat ./tmp/vale.out | reviewdog -f=rdjsonl -name=vale -reporter=github-pr-annotations -fail-on-error=false -filter-mode=added -level=info -fail-level=warning + cat ./tmp/vale.out | reviewdog -f=rdjsonl -name=vale -reporter=github-pr-annotations -filter-mode=added -level=info -fail-level=warning env: REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.vale.ini b/.vale.ini index 398c9a2fd8..28997b65c5 100644 --- a/.vale.ini +++ b/.vale.ini @@ -18,7 +18,9 @@ Docker.Forbidden = NO Docker.GenericCTA = NO Docker.HeadingPunctuation = NO Docker.ListComma = NO +Docker.MetaCommentary = NO Docker.OxfordComma = NO +Docker.PromotionalOpeners = NO Docker.RecommendedWords = NO Docker.Spacing = NO Docker.Terms = NO diff --git a/AGENTS.md b/AGENTS.md index d335fddbe7..9d33bbadef 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -185,16 +185,24 @@ produces broken HTML — always check COMPONENTS.md for correct syntax. ```sh npx --no-install rumdl fmt # Format Markdown before committing npx prettier --write # Format non-Markdown files -scripts/lint.sh ... # Lint specific files (rumdl + Vale) +scripts/lint.sh ... # Lint specific files (rumdl + 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. +`npx --no-install` uses the repository-pinned rumdl binary and never downloads +a replacement. If the binary is unavailable, run `npm ci` to install the +repository dependencies. Install Vale separately. + +For incremental work, prefer `scripts/lint.sh` over the `bake` targets. Pass +only the Markdown files you changed so the output stays scoped instead of +including the whole repository. + +Vale exits successfully when it reports only warnings or suggestions. Read the +full output: fix errors and warnings on lines you added or changed, and review +each suggestion. Don't expand the change to unrelated alerts in existing text. ### Validation in git worktrees @@ -207,10 +215,10 @@ and `validate-vendor` targets run correctly in CI. 1. Make changes 2. Format Markdown with rumdl: `npx --no-install rumdl fmt ` -3. Lint the changed files: `scripts/lint.sh ...` +3. Lint the changed Markdown files: `scripts/lint.sh ...` 4. Run a full build with `docker buildx bake` (optional for small changes) -Always lint the specific files you changed before committing. Use +Always lint the specific Markdown 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. diff --git a/_vale/Docker/Avoid.yml b/_vale/Docker/Avoid.yml index d49063c801..908292bf7b 100644 --- a/_vale/Docker/Avoid.yml +++ b/_vale/Docker/Avoid.yml @@ -3,6 +3,15 @@ message: "Consider removing '%s'." ignorecase: true level: warning tokens: + - amazing + - easily + - game-changing + - 'just(?!-in-time)' - please - - very + - powerful - really + - revolutionary + - robust + - seamlessly + - simply + - very diff --git a/_vale/Docker/GenericCTA.yml b/_vale/Docker/GenericCTA.yml index 4f4b0bfa92..1d123ba8f0 100644 --- a/_vale/Docker/GenericCTA.yml +++ b/_vale/Docker/GenericCTA.yml @@ -1,6 +1,5 @@ extends: existence message: "Avoid generic calls to action: '%s'" -link: https://docs.docker.com/contribute/style/formatting/#links level: warning scope: raw ignorecase: true diff --git a/_vale/Docker/ListComma.yml b/_vale/Docker/ListComma.yml index 2af0bc710d..0efaf14a04 100644 --- a/_vale/Docker/ListComma.yml +++ b/_vale/Docker/ListComma.yml @@ -1,6 +1,5 @@ extends: existence message: Don’t add commas (,) or semicolons (;) to the ends of list items. -link: https://docs.docker.com/contribute/style/grammar/#lists level: warning scope: list raw: '[,;]$' diff --git a/_vale/Docker/MetaCommentary.yml b/_vale/Docker/MetaCommentary.yml new file mode 100644 index 0000000000..53e4bf7d75 --- /dev/null +++ b/_vale/Docker/MetaCommentary.yml @@ -0,0 +1,8 @@ +extends: existence +message: "Remove meta-commentary '%s' and state the information directly." +ignorecase: true +level: warning +tokens: + - 'worth noting(?: that)?' + - 'important to (?:note|understand) that' + - 'keep in mind(?: that)?' diff --git a/_vale/Docker/PromotionalOpeners.yml b/_vale/Docker/PromotionalOpeners.yml new file mode 100644 index 0000000000..ec56280af9 --- /dev/null +++ b/_vale/Docker/PromotionalOpeners.yml @@ -0,0 +1,8 @@ +extends: existence +message: "Replace promotional opener '%s' with a specific description." +ignorecase: true +level: warning +scope: sentence +tokens: + - '^in today' + - '^(?:whether you[\x27’]re|whether you are)\b' diff --git a/_vale/Docker/RecommendedWords.yml b/_vale/Docker/RecommendedWords.yml index 8a37d58f0e..4a85a17e64 100644 --- a/_vale/Docker/RecommendedWords.yml +++ b/_vale/Docker/RecommendedWords.yml @@ -1,6 +1,5 @@ extends: substitution message: "Consider using '%s' instead of '%s'" -link: https://docs.docker.com/contribute/style/recommended-words/ ignorecase: true level: suggestion action: @@ -29,11 +28,20 @@ swap: click: select distro: distribution ergo: therefore + facilitate: help + facilitates: helps + facilitated: helped + facilitating: helping file name: filename + in order to: to keypress: keystroke mutices: mutexes repo: repository scroll: navigate url: URL + utilize: use + utilizes: uses + utilized: used + utilizing: using '\bvs\b(?!\.|\s+Code)': versus wish: want diff --git a/_vale/Docker/Units.yml b/_vale/Docker/Units.yml index 4e67c1ac27..b87f0e0538 100644 --- a/_vale/Docker/Units.yml +++ b/_vale/Docker/Units.yml @@ -1,6 +1,5 @@ extends: substitution message: "Use '%s' instead of '%s'" -link: https://docs.docker.com/contribute/style/recommended-words/ level: error swap: kilobytes?: kB diff --git a/_vale/Docker/VersionText.yml b/_vale/Docker/VersionText.yml index 37061de8da..1af1a048f8 100644 --- a/_vale/Docker/VersionText.yml +++ b/_vale/Docker/VersionText.yml @@ -1,6 +1,5 @@ extends: existence message: Use later when talking about version numbers. -link: https://docs.docker.com/contribute/style/recommended-words/#later scope: raw raw: - '\bv?' diff --git a/scripts/lint.sh b/scripts/lint.sh index 23a29bdd47..51204a4d95 100755 --- a/scripts/lint.sh +++ b/scripts/lint.sh @@ -1,16 +1,25 @@ #!/bin/bash -# Run rumdl and Vale on specific files. -# Usage: scripts/lint.sh [file...] +# Run rumdl and Vale on specific Markdown files. +# Usage: scripts/lint.sh [markdown-file...] # # Scoped output — no repo-wide noise. For full repo validation, use: # docker buildx bake validate set -uo pipefail if [ $# -eq 0 ]; then - echo "Usage: $0 [file...]" >&2 + echo "Usage: $0 [markdown-file...]" >&2 exit 1 fi +for file in "$@"; do + if [[ "$file" != *.md ]]; then + echo "Error: scripts/lint.sh only accepts Markdown files: $file" >&2 + exit 2 + fi +done + +repo_root=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd) + exit_code=0 echo "=== rumdl ===" @@ -20,8 +29,11 @@ fi echo "" echo "=== vale ===" -if ! vale "$@" 2>&1; then +if ! vale --no-global --config="$repo_root/.vale.ini" "$@" 2>&1; then exit_code=1 fi +echo "" +echo "Review Vale warnings and suggestions on changed lines; they don't affect the exit status." + exit $exit_code