Writing Style Linter: Update vale and prevent binary from being published

.prettierignore

@@ -4,4 +4,4 @@ package.json
 .percy.yml
 .cache
 .yarn
-**/vale-styles/Google
+**/styles/Google

packages/writing-style/.gitignore

@@ -1,3 +1,3 @@
 *.zip
 *.tar.gz
-bin/vale*
+vale-*

packages/writing-style/.npmignore

@@ -1,3 +1,3 @@
 *.zip
 *.tar.gz
-bin/vale
+vale-*

packages/writing-style/.vale.ini

@@ -1,4 +1,4 @@
-StylesPath = vale-styles
+StylesPath = styles
 MinAlertLevel = warning # suggestion, warning or error
 # error: You have a real problem and really need to learn this also for other texts you write
 # warning: Style rules that alll authors have to adhere to
@@ -19,7 +19,7 @@ BlockIgnores = (?s) *({%\s*highlight\s+[a-z]*\s*%}.*?{%\s*endhighlight\s*%}), (?
 # enable/disable a rule or change its level.
 
 # Downgrade built-in spellchecker because it's near impossible to maintain all industry and technology
-# terminology here in the central kit repositories 'vale-styles/vocab.txt' file.
+# terminology here in the central kit repositories 'styles/vocab.txt' file.
 # Being a suggestion it can still be called by docs staff to get some feedback.
 Vale.Spelling = suggestion
 

packages/writing-style/README.md

@@ -3,43 +3,51 @@
 This package provides
 
 - commercetools specific writing style and terminology rules for the configurable [vale](https://errata-ai.github.io/vale/) prose linter.
-- the `commercetools-vale` command-line tool which wraps a bundled vale build and calls it using the included writing style and configuration
-- the `commercetools-vale-bin` command is directly calling the current bundled vale binary without passing the commercetools configuration and writing style. The configuration has to be passed separately via vale's `--config` flag.
+- the `commercetools-vale` command-line tool which wraps the vale binary and calls it using the included writing style and configuration
+- the `commercetools-vale-bin` command is directly calling the vale binary without passing the commercetools configuration. The `.vale.ini` configuration location has to be passed separately via vale's `--config` flag.
 
-The base style is the [Google Developer Documentation Style Guide](https://github.com/errata-ai/Google), which is included as a copy (MIT licensed, too) and modified and enriched with commercetools specific rules.
+The base style is the [Google Developer Documentation Style Guide](https://github.com/errata-ai/Google), which is included as a copy (MIT licensed, too) and modified and partially overridden with commercetools specific rules.
 
 The configuration defaults to checking `.md`, `.mdx`, `.txt`, and `.html` files, which can be overridden by calling it with a command-line parameter `commercetools-vale --glob='*.{js,md}' ./path/to/content` passing a list of [supported file format extensions](https://errata-ai.github.io/vale/formats/#formats).
 
-> As of Nov 2019, basing off Google's styles was a pragmatic choice. Other styles like Microsoft's are attractive starting points, too.
+## Automatic vale binary download for the current platform
 
-## Downloading vale binary
+This packages `postinstall` script automatically downloads the appropriate `vale` binary upon installation. This ensures a small package size and no unnecessary binary files in it. Supported platforms are Mac OS (`darwin`), Linux (`linux`), and Windows (`windows`).
 
-This package automatically downloads the appropriate `vale` binary upon installation (running as `postinstall` script). This ensures that the package is kept as small as possible, as the `vale` binary takes up a few megabytes, and the appropriate binary is downloaded according to the operating system (`macOS`, `linux`, `windows`).
-
-## Downloading Google styles
-
-The [Google styles for vale](https://github.com/errata-ai/Google) should not be changed manually, as they are maintained by the Errata-AI team and pulled directly from their repository. To get the latest changes, run the `yarn download:google` command.
-
-## Linter Usage: Standalone command-line
+## Standalone command-line usage
 
 1.  Install the command globally via `yarn global add @commercetools-docs/writing-style` or `npm install -g @commercetools-docs/writing-style`
 1.  Use it by calling `commercetools-vale ./path/to/your/content`
 
 Please don't forget to frequently update the package to get the latest styles.
 
-## Linter Usage: In Editor plugins
+## Usage in the VSCode vale plugin
 
-In addition, you can install a matching editor plugin to get immediate feedback while authoring.
-**If your plugin allows, reconfigure the command from `vale` to `commercetools-vale`**.
+The [vscode-vale plugin](https://marketplace.visualstudio.com/items?itemName=testthedocs.vale) is always passing a `--config` parameter even if none is configured, so you have to separately configure the binary and the config location as follows, for example in a workspace configuration file:
 
-The plugin [for VSCode](https://marketplace.visualstudio.com/items?itemName=testthedocs.vale) does not support such configuration yet.
+```json
+{
+  "settings": {
+    "vscode-vale.path": "${workspaceFolder}/node_modules/.bin/commercetools-vale-bin",
+    "vscode-vale.configPath": "${workspaceFolder}/node_modules/@commercetools-docs/writing-style/.vale.ini"
+  }
+}
+```
 
-## Linter Usage: CI and command-line in Javascript Projects
+## Usage as a `package.json` dependency
 
 1. Add the writing-style package as a development dependency: `yarn add --dev @commercetools-docs/writing-style`
 1. In your project's folder, call it from the command
    line via `npx commercetools-vale ./your/path/to/content` and optionally add vale command-line parameters as needed (for example `--no-wrap` on command-line jobs).
-   - _Tip_: Running it over your complete repository is not a good idea since it checks the complete node_modules folder which takes a long time and is not your content.
+   - _Tip_: Running it over your complete repository is not a good idea since it checks the complete node_modules folder which takes a long time and is not your content, so make sure to pass a relevant file selection
+
+## Updating the Google styles
+
+The [Google styles for vale](https://github.com/errata-ai/Google) should not be changed in this repository as they are maintained by the Errata-AI team and pulled directly from their repository. To get the latest changes, run the `yarn download:google` command.
+
+## Updating the vale version
+
+Update the custom `valeVersion` property in `package.json` and confirm that the artifact naming convention on vale's [GitHub releases page](https://github.com/errata-ai/vale/releases) has not changed.
 
 ## Contributing
 

packages/writing-style/bin/commercetools-vale-bin.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+const run = require('../src/run');
+
+const commandProcess = run(process.argv.slice(2));
+commandProcess.on('close', (code) => {
+  process.exit(code);
+});

packages/writing-style/bin/commercetools-vale.js

@@ -1,25 +1,11 @@
 #!/usr/bin/env node
 
-const os = require('os');
 const path = require('path');
-const shelljs = require('shelljs');
-const { valeVersion } = require('../package.json');
+const run = require('../src/run');
 
-const binaryFileName =
-  os.platform() === 'win32' ? `vale-${valeVersion}.exe` : `vale-${valeVersion}`;
-
-const valeBinary = path.join(__dirname, `./${binaryFileName}`);
 const valeConfig = path.join(__dirname, `../.vale.ini`);
-let params = process.argv.slice(2);
-// simplistic check whether the --config param was passed empty by the VSCode plugin (empty = followed by another flag)
-const configParamPosition = params.findIndex((p) => p === '--config');
-if (
-  params[configParamPosition + 1] &&
-  params[configParamPosition + 1].startsWith('-')
-) {
-  params = params.filter((p) => p !== '--config');
-}
 
-const command = `${valeBinary} --config ${valeConfig} ${params.join(' ')}`;
-const result = shelljs.exec(command);
-process.exit(result.code);
+const commandProcess = run(['--config', valeConfig, ...process.argv.slice(2)]);
+commandProcess.on('close', (code) => {
+  process.exit(code);
+});

packages/writing-style/package.json

@@ -2,7 +2,7 @@
   "name": "@commercetools-docs/writing-style",
   "description": "Wrapped and preconfigured vale linter for the commercetools writing style rules",
   "version": "2.4.0",
-  "valeVersion": "2.1.0",
+  "valeVersion": "2.1.1",
   "license": "MIT",
   "private": false,
   "publishConfig": {
@@ -15,7 +15,7 @@
   },
   "bin": {
     "commercetools-vale": "./bin/commercetools-vale.js",
-    "commercetools-vale-bin": "./bin/vale-2.1.0"
+    "commercetools-vale-bin": "./bin/commercetools-vale-bin.js"
   },
   "scripts": {
     "postinstall": "node scripts/download-vale.js",

packages/writing-style/scripts/download-google-styles.js

@@ -2,7 +2,7 @@ const path = require('path');
 const shelljs = require('shelljs');
 
 const archivePath = path.join(__dirname, '../Google.zip');
-const destPath = path.join(__dirname, '../vale-styles');
+const destPath = path.join(__dirname, '../styles');
 
 shelljs.exec(
   'curl -sLO https://github.com/errata-ai/Google/releases/latest/download/Google.zip'

packages/writing-style/scripts/download-vale.js

@@ -29,7 +29,7 @@ const localBinaryFileName = isWin
   ? `vale-${valeVersion}.exe`
   : `vale-${valeVersion}`;
 const archivePath = path.join(__dirname, `../${archiveName}`);
-const binPath = path.join(__dirname, '../bin');
+const binPath = path.join(__dirname, '../');
 const downloadBinaryPath = path.join(binPath, binaryFileName);
 const destBinaryPath = path.join(binPath, localBinaryFileName);
 

packages/writing-style/scripts/download-writegood-styles.js

@@ -2,7 +2,7 @@ const path = require('path');
 const shelljs = require('shelljs');
 
 const archivePath = path.join(__dirname, '../write-good.zip');
-const destPath = path.join(__dirname, '../vale-styles');
+const destPath = path.join(__dirname, '../styles');
 
 shelljs.exec(
   'curl -sLO https://github.com/errata-ai/write-good/releases/latest/download/write-good.zip'

packages/writing-style/src/run.js

@@ -0,0 +1,18 @@
+const os = require('os');
+const path = require('path');
+const { spawn } = require('child_process');
+const { valeVersion } = require('../package.json');
+
+const binaryFileName =
+  os.platform() === 'win32' ? `vale-${valeVersion}.exe` : `vale-${valeVersion}`;
+
+const valeBinary = path.join(__dirname, `../${binaryFileName}`);
+
+function run(commandArgs) {
+  return spawn(valeBinary, commandArgs, {
+    stdio: 'inherit',
+    windowsHide: true,
+  });
+}
+
+module.exports = run;