From f31979811de8dab5f10775d7df3bc50d48da3766 Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Mon, 22 Jun 2026 21:19:56 +0000 Subject: [PATCH 1/2] fix(.github/workflows/ci.yaml): preserve Vale severity in CI annotations The Vale prose lint step in CI ran 'vale --output=line' through a GitHub Actions problem matcher at .github/vale-problem-matcher.json. The matcher hard-codes severity=warning at the top level, and Vale's line format strips per-finding severity, so every Vale finding rendered as a GitHub 'warning' annotation, even error-level findings from Coder.BrandNames. Switch to 'vale --output=JSON' and pipe through jq to emit GitHub workflow commands directly. Mapping: Vale 'suggestion' -> ::notice::, Vale 'warning' -> ::warning::, Vale 'error' -> ::error::. URL-encode message bodies for '%', carriage return, and newline per the GitHub Actions workflow command spec. Delete the now-unused .github/vale-problem-matcher.json. The CI step stays continue-on-error: true so Vale annotations remain advisory and never block merge. See DOCS-426. --- .github/vale-problem-matcher.json | 18 ------------------ .github/workflows/ci.yaml | 22 +++++++++++++++++++--- 2 files changed, 19 insertions(+), 21 deletions(-) delete mode 100644 .github/vale-problem-matcher.json diff --git a/.github/vale-problem-matcher.json b/.github/vale-problem-matcher.json deleted file mode 100644 index bedf0e0b3e3..00000000000 --- a/.github/vale-problem-matcher.json +++ /dev/null @@ -1,18 +0,0 @@ -{ - "problemMatcher": [ - { - "owner": "vale", - "severity": "warning", - "pattern": [ - { - "regexp": "^(.+):(\\d+):(\\d+):([^:]+):(.+)$", - "file": 1, - "line": 2, - "column": 3, - "code": 4, - "message": 5 - } - ] - } - ] -} diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 321c647bdf6..39ac276db1b 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -234,9 +234,25 @@ jobs: echo "No changed Markdown files under docs/ on disk; skipping Vale." exit 0 fi - echo "::add-matcher::.github/vale-problem-matcher.json" - printf '%s\n' "$files" | xargs -d '\n' mise exec "aqua:errata-ai/vale" -- vale --no-exit --output=line - echo "::remove-matcher owner=vale::" + # Vale's --output=line strips per-finding severity, so the + # previous problem-matcher approach collapsed every finding to + # a single hard-coded severity. Use --output=JSON instead and + # emit GitHub workflow commands directly so error/warning/ + # suggestion render with their actual Vale severities. URL- + # encode message bodies for `%`, `\r`, and `\n` per the + # GitHub Actions workflow command spec. See DOCS-426. + printf '%s\n' "$files" \ + | xargs -d '\n' mise exec "aqua:errata-ai/vale" -- vale --no-exit --output=JSON \ + | jq -r ' + to_entries[] + | .key as $file + | .value[] + | (if .Severity == "suggestion" then "notice" + elif .Severity == "warning" then "warning" + else "error" end) as $level + | (.Message | gsub("%"; "%25") | gsub("\r"; "%0D") | gsub("\n"; "%0A")) as $msg + | "::\($level) file=\($file),line=\(.Line),col=\(.Span[0]),title=\(.Check)::\($msg)" + ' - name: Save Vale styles # Only the default branch is trusted to write the cache, so PR From c55cd7c964a3a713d0adb1436e193855354eb306 Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Mon, 22 Jun 2026 21:20:52 +0000 Subject: [PATCH 2/2] demo(docs/.style): add three-severity Vale annotation rendering canary Adds three throwaway Coder.Demo* rules and a single demo doc that triggers each rule exactly once. Together with the matcher fix in the previous commit, this PR's CI surfaces three GitHub annotations in three distinct severities (notice, warning, error). Used to visually verify that severity rendering works correctly after the fix. Files: - docs/.style/styles/Coder/DemoError.yml (level: error) - docs/.style/styles/Coder/DemoWarning.yml (level: warning) - docs/.style/styles/Coder/DemoSuggestion.yml (level: suggestion) - docs/.style/_vale-annotation-demo.md (one trigger phrase per rule) Each rule uses Vale's 'existence' extension type to match a single literal token (vale-demo-{error,warning,suggestion}-marker) that appears only in the demo doc. The demo doc carries a NOTE callout explaining its purpose. Demo content drops in a follow-up commit on this branch before merge; only the matcher fix lands. Or, on @vigilante's call, the demo stays as a permanent canary that monitors severity rendering across future CI changes. See DOCS-426. --- docs/.style/_vale-annotation-demo.md | 25 +++++++++++++++++++++ docs/.style/styles/Coder/DemoError.yml | 11 +++++++++ docs/.style/styles/Coder/DemoSuggestion.yml | 11 +++++++++ docs/.style/styles/Coder/DemoWarning.yml | 11 +++++++++ 4 files changed, 58 insertions(+) create mode 100644 docs/.style/_vale-annotation-demo.md create mode 100644 docs/.style/styles/Coder/DemoError.yml create mode 100644 docs/.style/styles/Coder/DemoSuggestion.yml create mode 100644 docs/.style/styles/Coder/DemoWarning.yml diff --git a/docs/.style/_vale-annotation-demo.md b/docs/.style/_vale-annotation-demo.md new file mode 100644 index 00000000000..facbf2487ea --- /dev/null +++ b/docs/.style/_vale-annotation-demo.md @@ -0,0 +1,25 @@ +# Vale annotation rendering demo + +> [!NOTE] +> This page exists only to verify how GitHub renders Vale annotations +> at each severity level. +> The three `Coder.Demo*` rules under +> [`docs/.style/styles/Coder/`](styles/Coder/) fire on the marker +> strings below. +> This page and its rules disappear in a follow-up commit on the same +> PR once the rendering check completes; see DOCS-426. + +## Markers + +Each marker fires exactly one Vale annotation when this page lints: + +- Suggestion (rendered as GitHub `notice`): + vale-demo-suggestion-marker. +- Warning (rendered as GitHub `warning`): + vale-demo-warning-marker. +- Error (rendered as GitHub `error`): + vale-demo-error-marker. + +The rules use Vale's `existence` extension type and target a single +literal token each, so each marker produces a single annotation at its +exact location. diff --git a/docs/.style/styles/Coder/DemoError.yml b/docs/.style/styles/Coder/DemoError.yml new file mode 100644 index 00000000000..366736701a5 --- /dev/null +++ b/docs/.style/styles/Coder/DemoError.yml @@ -0,0 +1,11 @@ +# DemoError - canary rule used to verify how GitHub renders error-level +# Vale annotations in PR diffs. Fires on the literal phrase +# `vale-demo-error-marker`, which appears only in +# docs/.style/_vale-annotation-demo.md. Demo rules drop in a follow-up +# commit before the parent PR merges; see DOCS-426. +extends: existence +message: "[Demo] Error-level Vale annotation." +link: https://github.com/coder/coder/blob/main/docs/.style/_vale-annotation-demo.md +level: error +tokens: + - vale-demo-error-marker diff --git a/docs/.style/styles/Coder/DemoSuggestion.yml b/docs/.style/styles/Coder/DemoSuggestion.yml new file mode 100644 index 00000000000..dd6dda6a342 --- /dev/null +++ b/docs/.style/styles/Coder/DemoSuggestion.yml @@ -0,0 +1,11 @@ +# DemoSuggestion - canary rule used to verify how GitHub renders +# suggestion-level Vale annotations in PR diffs. Fires on the literal +# phrase `vale-demo-suggestion-marker`, which appears only in +# docs/.style/_vale-annotation-demo.md. Demo rules drop in a follow-up +# commit before the parent PR merges; see DOCS-426. +extends: existence +message: "[Demo] Suggestion-level Vale annotation." +link: https://github.com/coder/coder/blob/main/docs/.style/_vale-annotation-demo.md +level: suggestion +tokens: + - vale-demo-suggestion-marker diff --git a/docs/.style/styles/Coder/DemoWarning.yml b/docs/.style/styles/Coder/DemoWarning.yml new file mode 100644 index 00000000000..bd03e1c8db3 --- /dev/null +++ b/docs/.style/styles/Coder/DemoWarning.yml @@ -0,0 +1,11 @@ +# DemoWarning - canary rule used to verify how GitHub renders +# warning-level Vale annotations in PR diffs. Fires on the literal phrase +# `vale-demo-warning-marker`, which appears only in +# docs/.style/_vale-annotation-demo.md. Demo rules drop in a follow-up +# commit before the parent PR merges; see DOCS-426. +extends: existence +message: "[Demo] Warning-level Vale annotation." +link: https://github.com/coder/coder/blob/main/docs/.style/_vale-annotation-demo.md +level: warning +tokens: + - vale-demo-warning-marker