From 9047582c034eb5011d3cd22135855ba71e816f8c Mon Sep 17 00:00:00 2001
From: Dominic Tran <dominic.tran@clickhouse.com>
Date: Thu, 20 Nov 2025 10:20:01 -0600
Subject: [PATCH 1/2] Auditing vale style rules, adding a script to run a
 report, adding exclusions

---
 .vale.ini                             | 16 +++++++++--
 scripts/vale/vale-report.sh           | 41 +++++++++++++++++++++++++++
 styles/ClickHouse/CodeblockFences.yml |  2 +-
 styles/ClickHouse/FutureTense.yml     |  2 +-
 styles/ClickHouse/Uppercase.yml       |  3 ++
 5 files changed, 60 insertions(+), 4 deletions(-)
 create mode 100755 scripts/vale/vale-report.sh

diff --git a/.vale.ini b/.vale.ini
index 396707de9a9..98acdb23743 100644
--- a/.vale.ini
+++ b/.vale.ini
@@ -1,5 +1,17 @@
 StylesPath = styles
-MinAlertLevel = warning
 
-[*.{md}]
+# Exclude with more specific patterns
+# [!docs/engines/**/*.md]
+# [!docs/development/**/*.md]
+# [!docs/interfaces/**/*.md]
+# [!docs/operations/**/*.md]
+# [!docs/sql-reference/**/*.md]
+[!docs/whats-new/**/*.md]
+[!docs/releases/**/*.md]
+
+# Only check .md files (not .mdx)
+[docs/**/*.md]
 BasedOnStyles = ClickHouse
+
+ClickHouse.SentenceLength = NO
+ClickHouse.FutureTense = NO
diff --git a/scripts/vale/vale-report.sh b/scripts/vale/vale-report.sh
new file mode 100755
index 00000000000..cbdb9a880eb
--- /dev/null
+++ b/scripts/vale/vale-report.sh
@@ -0,0 +1,41 @@
+#!/bin/bash
+# vale-report.sh - Generate Vale report
+
+vale docs/ \
+  --glob='!docs/whats-new/**/*.md' \
+  --output=JSON > vale-report.json 2>&1
+
+# Check if vale-report.json is valid JSON
+if ! jq empty vale-report.json 2>/dev/null; then
+    echo "❌ Error: Vale did not produce valid JSON output"
+    echo ""
+    echo "Vale output:"
+    cat vale-report.json
+    exit 1
+fi
+
+echo "================================================"
+echo "📝 Vale Report - $(date '+%Y-%m-%d')"
+echo "================================================"
+echo ""
+
+WARNINGS=$(jq '[.[] | .[] | select(.Severity == "warning")] | length' vale-report.json)
+SUGGESTIONS=$(jq '[.[] | .[] | select(.Severity == "suggestion")] | length' vale-report.json)
+
+echo "⚠️  Warnings: $WARNINGS"
+echo "💡 Suggestions: $SUGGESTIONS"
+echo ""
+
+echo "📋 Top Warning Rules:"
+jq -r '[.[] | .[] | select(.Severity == "warning") | .Check] | group_by(.) | map({rule: .[0], count: length}) | sort_by(-.count) | .[:5] | .[] | "\(.count)\t\(.rule)"' vale-report.json | column -t -s $'\t'
+echo ""
+
+echo "📁 Top Files to Fix:"
+jq -r 'to_entries | map({file: .key, count: [.value[] | select(.Severity == "warning")] | length}) | map(select(.count > 0)) | sort_by(-.count) | .[:15] | .[] | "\(.count)\t\(.file)"' vale-report.json | column -t -s $'\t'
+echo ""
+
+echo "================================================"
+echo "✅ To fix a file:"
+echo "   vale docs/path/to/file.md"
+echo "   vim docs/path/to/file.md"
+echo "================================================"
\ No newline at end of file
diff --git a/styles/ClickHouse/CodeblockFences.yml b/styles/ClickHouse/CodeblockFences.yml
index 9c21a792b01..defad6de9a6 100644
--- a/styles/ClickHouse/CodeblockFences.yml
+++ b/styles/ClickHouse/CodeblockFences.yml
@@ -6,7 +6,7 @@ extends: existence
 message: "Instead of '%s' for the code block, use yaml, ruby, plaintext, markdown, javascript, shell, go, python, dockerfile, or typescript."
 link: https://docs.gitlab.com/development/documentation/styleguide/#code-blocks
 vocab: false
-level: warning
+level: suggestion
 scope: raw
 raw:
   - '\`\`\`(yml|rb|text|md|bash|sh\n|js\n|golang\n|py\n|docker\n|ts|irb)'
diff --git a/styles/ClickHouse/FutureTense.yml b/styles/ClickHouse/FutureTense.yml
index 6982a3f1f1b..ad0711ae2d8 100644
--- a/styles/ClickHouse/FutureTense.yml
+++ b/styles/ClickHouse/FutureTense.yml
@@ -8,7 +8,7 @@ message: "Instead of future tense '%s', use present tense."
 ignorecase: true
 nonword: true
 vocab: false
-level: warning
+level: suggestion
 link: https://docs.gitlab.com/development/documentation/styleguide/word_list/#future-tense
 tokens:
   - (going to|will|won't)[ \n:]\w*
diff --git a/styles/ClickHouse/Uppercase.yml b/styles/ClickHouse/Uppercase.yml
index 1aaedf19000..8350fe13a58 100644
--- a/styles/ClickHouse/Uppercase.yml
+++ b/styles/ClickHouse/Uppercase.yml
@@ -13,6 +13,7 @@ first: '\b([A-Z]{3,5})\b'
 second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)'
 # ... with the exception of these:
 exceptions:
+  - ACH
   - ACL
   - AJAX
   - ALL
@@ -163,6 +164,7 @@ exceptions:
   - OTP
   - OWASP
   - PAT
+  - PAYG
   - PCI-DSS
   - PDF
   - PEM
@@ -255,6 +257,7 @@ exceptions:
   - URI
   - URL
   - USB
+  - USD
   - UTC
   - UTF
   - UUID

From f971dd7d2c2e0619990f453dccf52b59442f7e90 Mon Sep 17 00:00:00 2001
From: Dominic Tran <dominic.tran@clickhouse.com>
Date: Thu, 20 Nov 2025 13:49:37 -0600
Subject: [PATCH 2/2] removing AI slop emojis

---
 scripts/vale/vale-report.sh | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/scripts/vale/vale-report.sh b/scripts/vale/vale-report.sh
index cbdb9a880eb..3cd1907c05a 100755
--- a/scripts/vale/vale-report.sh
+++ b/scripts/vale/vale-report.sh
@@ -7,7 +7,7 @@ vale docs/ \
 
 # Check if vale-report.json is valid JSON
 if ! jq empty vale-report.json 2>/dev/null; then
-    echo "❌ Error: Vale did not produce valid JSON output"
+    echo "Error: Vale did not produce valid JSON output"
     echo ""
     echo "Vale output:"
     cat vale-report.json
@@ -15,27 +15,27 @@ if ! jq empty vale-report.json 2>/dev/null; then
 fi
 
 echo "================================================"
-echo "📝 Vale Report - $(date '+%Y-%m-%d')"
+echo "Vale Report - $(date '+%Y-%m-%d')"
 echo "================================================"
 echo ""
 
 WARNINGS=$(jq '[.[] | .[] | select(.Severity == "warning")] | length' vale-report.json)
 SUGGESTIONS=$(jq '[.[] | .[] | select(.Severity == "suggestion")] | length' vale-report.json)
 
-echo "⚠️  Warnings: $WARNINGS"
-echo "💡 Suggestions: $SUGGESTIONS"
+echo "Warnings: $WARNINGS"
+echo "Suggestions: $SUGGESTIONS"
 echo ""
 
-echo "📋 Top Warning Rules:"
+echo "Top Warning Rules:"
 jq -r '[.[] | .[] | select(.Severity == "warning") | .Check] | group_by(.) | map({rule: .[0], count: length}) | sort_by(-.count) | .[:5] | .[] | "\(.count)\t\(.rule)"' vale-report.json | column -t -s $'\t'
 echo ""
 
-echo "📁 Top Files to Fix:"
+echo "Top Files to Fix:"
 jq -r 'to_entries | map({file: .key, count: [.value[] | select(.Severity == "warning")] | length}) | map(select(.count > 0)) | sort_by(-.count) | .[:15] | .[] | "\(.count)\t\(.file)"' vale-report.json | column -t -s $'\t'
 echo ""
 
 echo "================================================"
-echo "✅ To fix a file:"
+echo "To fix a file:"
 echo "   vale docs/path/to/file.md"
 echo "   vim docs/path/to/file.md"
-echo "================================================"
\ No newline at end of file
+echo "================================================"