feat: add Vale linting for generated Markdown

.github/workflows/validation.yml

@@ -99,6 +99,14 @@ jobs:
       - name: Generate SDK for ${{ matrix.sdk }}
         run: php example.php ${{ matrix.sdk }} ${{ matrix.platform }}
 
+      - name: Setup Vale
+        uses: errata-ai/setup-vale@v3
+        with:
+          version: '3.20.0'
+
+      - name: Validate Markdown with Vale
+        run: vale examples/${{ matrix.sdk }}
+
       - name: Verify generated SDK is idempotent
         if: matrix.sdk == 'zed-extension' || matrix.sdk == 'cli'
         run: |

.vale.ini

@@ -0,0 +1,38 @@
+StylesPath = .vale/styles
+
+MinAlertLevel = warning
+
+Packages = Google
+
+[*.md]
+BasedOnStyles = Google, Appwrite
+
+# Ignore code blocks entirely
+TokenIgnores = (\x60\x60\x60[\s\S]*?\x60\x60\x60)
+
+# Ignore inline code
+TokenIgnores = (\x60[^\x60]+\x60)
+
+# Suppress rules for generated API documentation
+# These come from the OpenAPI spec and cannot be changed at template level
+[examples/**/docs/**/*.md]
+Google.Will = NO
+Google.WordListCase = NO
+Google.WordList = NO
+Google.Latin = NO
+Google.Ordinal = NO
+Google.Units = NO
+Google.Colons = NO
+Google.EmDash = NO
+Google.We = NO
+Google.FirstPerson = NO
+Google.OxfordComma = NO
+Google.Headings = NO
+Google.Quotes = NO
+Google.Spacing = NO
+Google.Ellipses = NO
+
+# README files: SDK names are proper nouns and should not be lowercased
+[examples/**/README.md]
+Google.Headings = NO
+Google.We = NO

.vale/styles/Appwrite/Terms.yml

@@ -0,0 +1,9 @@
+---
+extends: existence
+message: "Use 'test' instead of 'spec'."
+level: warning
+ignorecase: true
+tokens:
+  - spec
+  - specs
+---

.vale/styles/Google/AMPM.yml

@@ -0,0 +1,9 @@
+extends: existence
+message: "Use 'AM' or 'PM' (preceded by a space)."
+link: "https://developers.google.com/style/word-list"
+level: error
+nonword: true
+tokens:
+  - '\d{1,2}[AP]M\b'
+  - '\d{1,2} ?[ap]m\b'
+  - '\d{1,2} ?[aApP]\.[mM]\.'

.vale/styles/Google/Acronyms.yml

@@ -0,0 +1,64 @@
+extends: conditional
+message: "Spell out '%s', if it's unfamiliar to the audience."
+link: 'https://developers.google.com/style/abbreviations'
+level: suggestion
+ignorecase: false
+# Ensures that the existence of 'first' implies the existence of 'second'.
+first: '\b([A-Z]{3,5})\b'
+second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)'
+# ... with the exception of these:
+exceptions:
+  - API
+  - ASP
+  - CLI
+  - CPU
+  - CSS
+  - CSV
+  - DEBUG
+  - DOM
+  - DPI
+  - FAQ
+  - GCC
+  - GDB
+  - GET
+  - GPU
+  - GTK
+  - GUI
+  - HTML
+  - HTTP
+  - HTTPS
+  - IDE
+  - JAR
+  - JSON
+  - JSX
+  - LESS
+  - LLDB
+  - NET
+  - NOTE
+  - NVDA
+  - OSS
+  - PATH
+  - PDF
+  - PHP
+  - POST
+  - RAM
+  - REPL
+  - RSA
+  - SCM
+  - SCSS
+  - SDK
+  - SQL
+  - SSH
+  - SSL
+  - SVG
+  - TBD
+  - TCP
+  - TODO
+  - URI
+  - URL
+  - USB
+  - UTF
+  - XML
+  - XSS
+  - YAML
+  - ZIP

.vale/styles/Google/Anthropomorphism.yml

@@ -0,0 +1,12 @@
+extends: existence
+message: "Don't attribute human qualities to software or hardware ('%s')."
+link: https://developers.google.com/style/anthropomorphism
+level: suggestion
+ignorecase: true
+# Limited to the two verbs the guide itself names. Broader lists (wants, knows,
+# thinks) can't tell a software subject from a human one: on a 950-file corpus
+# they produced 8 false positives ('the customer wants', 'your audience knows')
+# for every 2 real ones.
+tokens:
+  - sees
+  - tells

.vale/styles/Google/Colons.yml

@@ -0,0 +1,13 @@
+extends: existence
+message: "'%s' should be in lowercase."
+link: 'https://developers.google.com/style/colons'
+level: warning
+scope: sentence
+# The match is the word itself, not ': X', and `nonword` is off. Both are
+# required for a project Vocab to work: Vale compares accept.txt entries
+# against the matched text, and `nonword: true` opts out of that entirely.
+# So a proper noun after a colon can be exempted by adding it to accept.txt.
+# The guide's other exemption, notice labels, is handled by the lookbehinds;
+# headings are already excluded by `scope: sentence`. See issue #20.
+tokens:
+  - '(?<!Note: )(?<!Caution: )(?<!Warning: )(?<!Success: )(?<=:\s)[A-Z]\w+'

.vale/styles/Google/Contractions.yml

@@ -0,0 +1,30 @@
+extends: substitution
+message: "Use '%s' instead of '%s'."
+link: 'https://developers.google.com/style/contractions'
+level: suggestion
+ignorecase: true
+action:
+  name: replace
+swap:
+  are not: aren't
+  cannot: can't
+  could not: couldn't
+  did not: didn't
+  do not: don't
+  does not: doesn't
+  has not: hasn't
+  have not: haven't
+  how is: how's
+  is not: isn't
+  it is: it's
+  should not: shouldn't
+  that is: that's
+  they are: they're
+  was not: wasn't
+  we are: we're
+  we have: we've
+  were not: weren't
+  what is: what's
+  when is: when's
+  where is: where's
+  will not: won't

.vale/styles/Google/DateFormat.yml

@@ -0,0 +1,9 @@
+extends: existence
+message: "Use 'July 31, 2016' format, not '%s'."
+link: 'https://developers.google.com/style/dates-times'
+ignorecase: true
+level: error
+nonword: true
+tokens:
+  - '\d{1,2}(?:\.|/)\d{1,2}(?:\.|/)\d{4}'
+  - '\d{1,2} (?:Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)?|May|Jun(?:e)?|Jul(?:y)?|Aug(?:ust)?|Sep(?:tember)?|Oct(?:ober)?|Nov(?:ember)?|Dec(?:ember)?) \d{4}'

.vale/styles/Google/Ellipses.yml

@@ -0,0 +1,9 @@
+extends: existence
+message: "In general, don't use an ellipsis."
+link: 'https://developers.google.com/style/ellipses'
+nonword: true
+level: warning
+action:
+  name: remove
+tokens:
+  - '\.\.\.'

.vale/styles/Google/EmDash.yml

@@ -0,0 +1,13 @@
+extends: existence
+message: "Don't put a space before or after a dash."
+link: "https://developers.google.com/style/dashes"
+nonword: true
+level: error
+action:
+  name: edit
+  params:
+    - trim
+    - " "
+tokens:
+  - '\s[—–]\s'
+

.vale/styles/Google/ExcessiveClaims.yml

@@ -0,0 +1,14 @@
+extends: existence
+message: "Avoid the unverifiable claim '%s'."
+link: https://developers.google.com/style/excessive-claims
+level: suggestion
+ignorecase: true
+# The guide also names 'never', 'always', and 'ensure', but in technical writing
+# those are usually legitimate instructions ('never commit secrets') rather than
+# product claims: they accounted for 125 of 142 hits on a 950-file corpus.
+# 'best practices' is a fixed term, not a superlative.
+tokens:
+  - 'best(?! practices?)'
+  - simplest
+  - fastest
+  - guarantees?

.vale/styles/Google/Exclamation.yml

@@ -0,0 +1,12 @@
+extends: existence
+message: "Don't use exclamation points in text."
+link: "https://developers.google.com/style/exclamation-points"
+nonword: true
+level: error
+action:
+  name: edit
+  params:
+    - trim_right
+    - "!"
+tokens:
+  - '\w+!(?:\s|$)'

.vale/styles/Google/FirstPerson.yml

@@ -0,0 +1,15 @@
+extends: existence
+message: "Avoid first-person pronouns such as '%s'."
+link: 'https://developers.google.com/style/pronouns#personal-pronouns'
+ignorecase: true
+level: warning
+# The 'I' tokens use lookaround rather than consuming the surrounding
+# whitespace. Matching ' I ' made the alert span cover both spaces, which shows
+# up as a too-wide underline in editors, and read as "such as ' I '". Dropping
+# `nonword` also lets a project Vocab apply, which it can't when set. See PR #50.
+tokens:
+  - '(?<=^|\s)I(?=[\s,])'
+  - "\\bI'm\\b"
+  - \bme\b
+  - \bmy\b
+  - \bmine\b

.vale/styles/Google/Gender.yml

@@ -0,0 +1,9 @@
+extends: existence
+message: "Don't use '%s' as a gender-neutral pronoun."
+link: 'https://developers.google.com/style/pronouns#gender-neutral-pronouns'
+level: error
+ignorecase: true
+tokens:
+  - he/she
+  - s/he
+  - \(s\)he

.vale/styles/Google/GenderBias.yml

@@ -0,0 +1,43 @@
+extends: substitution
+message: "Consider using '%s' instead of '%s'."
+ignorecase: true
+link: "https://developers.google.com/style/inclusive-documentation"
+level: error
+action:
+  name: replace
+swap:
+  (?:alumna|alumnus): graduate
+  (?:alumnae|alumni): graduates
+  air(?:m[ae]n|wom[ae]n): pilot(s)
+  anchor(?:m[ae]n|wom[ae]n): anchor(s)
+  authoress: author
+  camera(?:m[ae]n|wom[ae]n): camera operator(s)
+  door(?:m[ae]|wom[ae]n): concierge(s)
+  draft(?:m[ae]n|wom[ae]n): drafter(s)
+  fire(?:m[ae]n|wom[ae]n): firefighter(s)
+  fisher(?:m[ae]n|wom[ae]n): fisher(s)
+  fresh(?:m[ae]n|wom[ae]n): first-year student(s)
+  garbage(?:m[ae]n|wom[ae]n): waste collector(s)
+  lady lawyer: lawyer
+  ladylike: courteous
+  mail(?:m[ae]n|wom[ae]n): mail carriers
+  man and wife: husband and wife
+  man enough: strong enough
+  mankind: human kind|humanity
+  manmade: manufactured
+  manpower: personnel
+  middle(?:m[ae]n|wom[ae]n): intermediary
+  news(?:m[ae]n|wom[ae]n): journalist(s)
+  ombuds(?:man|woman): ombuds
+  oneupmanship: upstaging
+  poetess: poet
+  police(?:m[ae]n|wom[ae]n): police officer(s)
+  repair(?:m[ae]n|wom[ae]n): technician(s)
+  sales(?:m[ae]n|wom[ae]n): salesperson or sales people
+  service(?:m[ae]n|wom[ae]n): soldier(s)
+  steward(?:ess)?: flight attendant
+  tribes(?:m[ae]n|wom[ae]n): tribe member(s)
+  waitress: waiter
+  woman doctor: doctor
+  woman scientist[s]?: scientist(s)
+  work(?:m[ae]n|wom[ae]n): worker(s)

.vale/styles/Google/HeadingPunctuation.yml

@@ -0,0 +1,13 @@
+extends: existence
+message: "Don't put a period at the end of a heading."
+link: "https://developers.google.com/style/capitalization#capitalization-in-titles-and-headings"
+nonword: true
+level: warning
+scope: heading
+action:
+  name: edit
+  params:
+    - trim_right
+    - "."
+tokens:
+  - '[a-z0-9][.]\s*$'

.vale/styles/Google/Headings.yml

@@ -0,0 +1,32 @@
+extends: capitalization
+message: "'%s' should use sentence-style capitalization."
+link: "https://developers.google.com/style/capitalization#capitalization-in-titles-and-headings"
+level: warning
+scope: heading
+match: $sentence
+# No `indicators: [":"]` here. That makes Vale require a capital after a colon,
+# which is the Microsoft convention this rule was originally copied from. This
+# guide says the opposite: "the first word after a colon is generally
+# lowercase" (developers.google.com/style/colons), and Colons.yml enforces
+# exactly that. See issue #58.
+exceptions:
+  - Azure
+  - CLI
+  - Cosmos
+  - Docker
+  - Emmet
+  - gRPC
+  - I
+  - Kubernetes
+  - Linux
+  - macOS
+  - Marketplace
+  - MongoDB
+  - REPL
+  - Studio
+  - TypeScript
+  - URLs
+  - Visual
+  - VS
+  - Windows
+  - JSON

.vale/styles/Google/Jargon.yml

@@ -0,0 +1,13 @@
+extends: existence
+message: "Avoid the jargon '%s'."
+link: https://developers.google.com/style/jargon
+level: suggestion
+ignorecase: true
+# The guide also cites 'solution', 'support', and 'workload' as overloaded
+# terms, but those have ordinary technical meanings and accounted for every hit
+# on a 950-file corpus, so only the unambiguous figurative terms are listed.
+tokens:
+  - break-glass
+  - camel ?case
+  - out-of-the-box
+  - swim ?lane