Update Vale guidelines checker and fix issues (#570)

* updated vale
* fix Vale issues
* exclude vale style dirs from lint checks

Signed-off-by: Nicolas MASSART <[email protected]>

.circleci/config.yml

@@ -11,6 +11,29 @@ executors:
     docker:
       - image: circleci/buildpack-deps:buster-scm
 
+commands:
+  install_node:
+    description: "Install Node dependencies"
+    steps:
+      - restore_cache:
+          keys:
+            - deps-{{ checksum "package-lock.json" }}
+      - run:
+          name: update-npm
+          command: 'sudo npm install -g npm@latest'
+      - run:
+          name: Install dependencies
+          command: |
+            npm ci
+
+  save_node_cache:
+    description: "Save Node dependencies"
+    steps:
+      - save_cache:
+          paths:
+            - ./node_modules
+          key: deps-{{ checksum "package-lock.json" }}
+
 jobs:
   dco:
     executor: shell_executor
@@ -65,11 +88,11 @@ jobs:
       - run:
           name: Install dependencies
           command: |
-            curl -sfL https://install.goreleaser.com/github.com/ValeLint/vale.sh | sh -s v1.7.1
+            curl -sfL https://install.goreleaser.com/github.com/ValeLint/vale.sh | sh -s v2.6.6
       - run:
           name: Run Vale
           command: |
-            ./bin/vale --config ./CI/vale_styles/.vale.ini --glob='*.{md}' . | tee ./vale.out
+            ./bin/vale --config ./CI/vale/.vale.ini --glob='*.{md}' . | tee ./vale.out
       - store_artifacts:
           path: ./vale.out
           destination: ./vale.out
@@ -78,24 +101,12 @@ jobs:
     executor: node_executor
     steps:
       - checkout
-      - run:
-          name: update-npm
-          command: 'sudo npm install -g npm@latest'
-      - restore_cache:
-          keys:
-            - deps-{{ checksum "package-lock.json" }}
-      - run:
-          name: Install dependencies
-          command: |
-            npm ci
+      - install_node
       - run:
           name: Run markdown link checker
           command: |
             npm run test:links
-      - save_cache:
-          paths:
-            - ./node_modules
-          key: deps-{{ checksum "package-lock.json" }}
+      - save_node_cache
       - store_artifacts:
           path: ./linkchecker.out
           destination: linkchecker.out
@@ -104,13 +115,7 @@ jobs:
     executor: node_executor
     steps:
       - checkout
-      - restore_cache:
-          keys:
-            - deps-{{ checksum "package-lock.json" }}
-      - run:
-          name: Install dependencies
-          command: |
-            npm ci
+      - install_node
       - run:
           shell: /bin/bash #this is a non breaking command so it will always return success
           name: Run Markdownlint info checks
@@ -120,10 +125,7 @@ jobs:
           name: Run Markdownlint
           command: |
             npm run test:markdown
-      - save_cache:
-          paths:
-            - ./node_modules
-          key: deps-{{ checksum "package-lock.json" }}
+      - save_node_cache
       - store_artifacts:
           path: ./markdownlint.out
           destination: ./markdownlint.out

.github/pull_request_template.md

@@ -37,7 +37,7 @@ see #{your issue number} -->
 - [ ] Python dependencies
 - [ ] Node dependencies and JavaScript
 - [ ] ReadTheDocs configuration
-- [ ] Github integration
+- [ ] GitHub integration
 
 ## Testing
 

.markdownlintignore

@@ -0,0 +1,2 @@
+# these files are copied from the Vale style repositories
+CI/vale/vale_styles/*/*.md

CI/scripts/README.md

@@ -10,12 +10,12 @@ work to the GitHub repositories.
 
 ## Running the scripts
 
-Go to the besu-doc project root directory and run one of the following scripts:
+Go to the `besu-doc` project root directory and run one of the following scripts:
 
 * `CI/scripts/test_build.sh` runs the doc build with MkDocs.
 * `CI/scripts/test_guidelines.sh` tests the doc with Vale and our custom rules.
 * `CI/scripts/test_links.sh` tests the internal and external links in the doc. If a link is
-  incorrect or the targeted web page is unavailable (for external sites), the test will fail and
+  incorrect or the targeted Web page is unavailable (for external sites), the test will fail and
   display the faulty link.
 * `CI/scripts/test_markdown_syntax.sh` tests the Markdown syntax for issues. Sometimes they are not visible
   but making sure the markdown is correct helps to make it readable and bug free.

CI/vale_styles/.vale.ini → CI/vale/.vale.ini

@@ -1,12 +1,16 @@
-# Example Vale config file (`.vale.ini` or `_vale.ini`)
+# Vale configuration
 
-# Core settings
+# Styles directory
+# See vale_styles/README.md file for details and licencing information
 StylesPath = vale_styles
 
+# Here's were we define the exceptions to use in *all*
+# `BasedOnStyles`.
+Vocab = Besu
+
 # The minimum alert level to display (suggestion, warning, or error).
-#
 # CI builds will only fail on error-level alerts.
-MinAlertLevel = warning
+MinAlertLevel = error
 
 # The "formats" section allows you to associate an "unknown" format
 # with one of Vale's supported formats.
@@ -16,15 +20,12 @@ mdx = md
 # Global settings (applied to every syntax)
 [*]
 # List of styles to load
-BasedOnStyles = proselint, write-good, Joblint, Microsoft, Besu
+BasedOnStyles = Vale, proselint, write-good, Microsoft, Besu
 # Style.Rule = {YES, NO} to enable or disable a specific rule
-vale.Editorializing = YES
-vale.Redundancy = YES
-vale.Repetition = YES
-vale.GenderBias = YES
 
 Microsoft.Contractions = NO
 Microsoft.GeneralURL = NO
+# Microsoft.Acronyms is replaced by Besu list
 Microsoft.Acronyms = NO
 Microsoft.Quotes = suggestion
 Microsoft.We = suggestion
@@ -35,6 +36,10 @@ write-good.Weasel = NO
 
 proselint.Hyperbole = warning
 
-[common/CLA.md]
 # Disable guidelines check for this file as it's legal jargon
+[CODE_OF_CONDUCT.md]
+BasedOnStyles =
+
+[CI/vale/vale_styles/*.md]
+# Disable guidelines check for this dir as it contains imported styles
 BasedOnStyles =

CI/vale_styles/Besu/Acronyms.yml → CI/vale/vale_styles/Besu/Acronyms.yml

@@ -8,6 +8,7 @@ second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)'
 # ... with the exception of these:
 exceptions:
   - API
+  - AWS
   - CLA
   - CLI
   - CPU
@@ -25,12 +26,16 @@ exceptions:
   - IBFT
   - IBFT2
   - IDE
+  - IPC
   - JAR
   - JDK
   - JRE
   - JSON
+  - JVM
+  - P2P
   - PATH
   - PIP
+  - PBFT
   - POA
   - POS
   - POST
@@ -49,7 +54,9 @@ exceptions:
   - TOML
   - URI
   - URL
+  - VM
+  - WAR
   - WEI
   - XML
   - YAML
-  - ZIP
+  - ZIP

CI/vale/vale_styles/Besu/Headings.yml

@@ -0,0 +1,45 @@
+extends: capitalization
+message: "'%s' should use sentence-style capitalization."
+link: 'https://docs.microsoft.com/en-us/style-guide/capitalization'
+level: suggestion
+scope: heading
+match: $sentence
+indicators:
+  - ':'
+exceptions:
+  - Besu
+  - EthSigner
+  - GoQuorum
+  - Quorum
+  - Orion
+  - Hyperledger
+  - PegaSys
+  - Consensys
+  - Ethereum
+  - ETH
+  - TOML
+  - YAML
+  - YML
+  - JSON
+  - RPC
+  - Hashicorp
+  - Vault
+  - Azure
+  - CLI
+  - Code
+  - Cosmos
+  - Docker
+  - Emmet
+  - I
+  - Kubernetes
+  - Linux
+  - macOS
+  - Marketplace
+  - MongoDB
+  - REPL
+  - Studio
+  - TypeScript
+  - URLs
+  - Visual
+  - VS
+  - Windows

CI/vale/vale_styles/Besu/Latin.yml

@@ -0,0 +1,8 @@
+extends: substitution
+message: "Prefer English '%s' over Latin '%s' term."
+level: error
+ignorecase: true
+action:
+  name: replace
+swap:
+  de facto: default

CI/vale_styles/Microsoft/Accessibility.yml → CI/vale/vale_styles/Microsoft/Accessibility.yml

@@ -1,6 +1,6 @@
 extends: existence
-message: "Don’t use language ('%s') that defines people by their disability."
-link: 'https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/bits-bytes-terms'
+message: "Don't use language (such as '%s') that defines people by their disability."
+link: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/accessibility-terms
 level: suggestion
 ignorecase: true
 tokens:

CI/vale_styles/Microsoft/Acronyms.yml → CI/vale/vale_styles/Microsoft/Acronyms.yml

@@ -1,6 +1,6 @@
 extends: conditional
 message: "'%s' has no definition."
-link: 'https://docs.microsoft.com/en-us/style-guide/acronyms'
+link: https://docs.microsoft.com/en-us/style-guide/acronyms
 level: suggestion
 ignorecase: false
 # Ensures that the existence of 'first' implies the existence of 'second'.

CI/vale_styles/Microsoft/Adverbs.yml → CI/vale/vale_styles/Microsoft/Adverbs.yml

@@ -3,6 +3,8 @@ message: "Consider removing '%s'."
 link: https://docs.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences
 ignorecase: true
 level: warning
+action:
+  name: remove
 tokens:
   - abnormally
   - absentmindedly

CI/vale/vale_styles/Microsoft/Auto.yml

@@ -0,0 +1,11 @@
+extends: existence
+message: "In general, don't hyphenate '%s'."
+link: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/auto
+ignorecase: true
+level: error
+action:
+  name: convert
+  params:
+    - simple
+tokens:
+  - 'auto-\w+'

CI/vale_styles/Microsoft/Avoid.yml → CI/vale/vale_styles/Microsoft/Avoid.yml

@@ -1,17 +1,18 @@
 extends: existence
-message: Don't use '%s'.
+message: "Don't use '%s'."
 link: https://docs.microsoft.com/en-us/style-guide
 ignorecase: true
 level: error
 tokens:
+  - abortion
   - and so on
   - and/or
   - app developer
+  - app(?:lication)? file
   - application developer
   - application program
   - applications developer
-  - app(?:lication)? file
   - as well as
   - ask
   - backbone
-  - abortion
+  - backend

CI/vale/vale_styles/Microsoft/Backend.yml

@@ -0,0 +1,12 @@
+extends: substitution
+message: "Use '%s' instead of '%s'."
+level: warning
+link: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/b/back-end
+# Use 'back end' (noun) or 'back-end' (adj).
+pos: 'back-end/NN|backend/(?:JJ|NN)|back/\w+ end/JJ|back/(?:JJ|RB) end/\w+'
+ignorecase: true
+action:
+  name: replace
+swap:
+  back-end: back end
+  back end: back-end