Style checking with Vale

.github/workflows/tests.yml

@@ -28,6 +28,11 @@ jobs:
         with:
           node-version: 18
       - run: npm ci
+      - uses: errata-ai/vale-action@reviewdog
+        with:
+          files: docs
+          reporter: github-pr-review
+          filter_mode: added
       - run: npm run test -- --reporter JSON --reporter-option output=mocha.json --filesToCheck=${{ needs.checkChangedFiles.outputs.files }}
         continue-on-error: true
       - uses: dorny/test-reporter@v1

.gitignore

@@ -7,3 +7,10 @@ node_modules
 out
 build
 
+# Vale
+test/styles/*
+!test/styles/Vocab/
+!test/styles/Tezos/
+
+test/styles/Vocab/*
+!test/styles/Vocab/Tezos

.vale.ini

@@ -0,0 +1,14 @@
+# https://vale.sh/docs/topics/config/
+
+StylesPath = test/styles
+
+MinAlertLevel = suggestion
+
+Vocab = Tezos
+
+# Treat mdx files as md files
+[formats]
+mdx = md
+
+[*.{md,mdx}]
+BasedOnStyles = Vale, Tezos

README.md

@@ -40,7 +40,13 @@ Finally, open [http://localhost:3000](http://localhost:3000) in your browser to
 ## Tests
 
 The workflow `.github/workflows/tests.yml` runs automated tests on pull requests.
-To run tests locally, run `npm run test -- --filesToCheck=docs/developing.md,docs/architecture.mdx`, where `--filesToCheck` is a comma-separated list of the MD and MDX files to test.
+It includes these tests:
+
+- Mocha tests that check for broken links to images.
+To run these tests locally, run `npm run test -- --filesToCheck=docs/developing.md,docs/architecture.mdx`, where `--filesToCheck` is a comma-separated list of the MD and MDX files to test.
+
+- Vale tests for style, spelling, and capitalization.
+To run these tests locally, install [Vale](https://vale.sh/) and run `npm run vale`.
 
 Docusaurus automatically checks for broken links and markdown-encoded images when you run `npm run build`.
 

package.json

@@ -10,6 +10,7 @@
     "deploy": "docusaurus deploy",
     "clear": "docusaurus clear",
     "serve": "docusaurus serve",
+    "vale": "vale sync && vale docs/",
     "write-translations": "docusaurus write-translations",
     "write-heading-ids": "docusaurus write-heading-ids",
     "test": "mocha"

test/styles/Tezos/Capitalize.yml

@@ -0,0 +1,7 @@
+extends: substitution
+message: "Always capitalize '%s'"
+level: error
+ignorecase: true
+swap:
+  smart rollup: Smart Rollup
+  smart rollups: Smart Rollups

test/styles/Tezos/DoNotCapitalize.yml

@@ -0,0 +1,8 @@
+extends: existence
+message: "'%s' should only be capitalized when starting a sentence."
+level: error
+nonword: true
+vocab: false
+scope: sentence
+tokens:
+  - (?<=\s)Smart [Cc]contract

test/styles/Tezos/Substitutions.yml

@@ -0,0 +1,8 @@
+extends: substitution
+message: Use '%s' instead of '%s'
+level: warning
+ignorecase: true
+# swap maps tokens in form of bad: good
+swap:
+  l1: layer 1
+  l2: layer 2

test/styles/Tezos/Terms.yml

@@ -0,0 +1,12 @@
+extends: existence
+message: "Do not use the term '%s'"
+level: error
+ignorecase: true
+tokens:
+   - 'official Tezos'
+   - 'official tezos'
+   - 'ICO'
+   - 'investors?'
+   - 'initial coin offering'
+   - 'chapter'
+   - 'article'

test/styles/config/vocabularies/Tezos/accept.txt

@@ -0,0 +1,72 @@
+Airgap
+API
+big_map
+bitwise
+[Bb]lockchains?
+Breitman
+broadcasted
+CameLIGO
+Carthagenet
+Completium
+cooldown
+coroutine
+[Cc]ryptocurrency
+[Cc]ryptocurrencies
+Dailynet
+dApps?
+Data Availability Layer
+Deku
+delegators?
+deserialized?
+destructured?
+Emilion
+Ethereum
+Etherlink
+Explorus
+Flextesa
+Ghostnet
+Grafana
+Grafazos
+JsLIGO
+keypair
+Kukai
+LIGO
+Mainnet
+Merkle
+middleware
+multisig
+Mumbainet
+namespace
+NFT
+Objkt
+OCaml
+[Oo]ff-chain
+[Oo]n-chain
+Oxhead
+Oxhead Alpha
+Que Pasa
+Rollups?
+Sapling
+scriptable
+SDKs?
+SmartPy
+stablecoins?
+substring
+supermajority
+syntax(es)?
+Taqueria
+Taquito
+[Tt]estnet
+tez
+Tezos
+trustlessness
+[Tt]zStats
+Umami
+Unicode
+upvotes
+URIs?
+[Vv]alidators?
+Vite
+VSCode
+Vue
+Weeklynet

test/styles/config/vocabularies/Tezos/reject.txt

@@ -0,0 +1 @@
+crypto