bash-explainer 0.6.0 → 0.8.0

package/README.md

@@ -46,15 +46,66 @@ bash-explainer --check install.sh     # constructs its shell (#!/bin/sh: dash…
 | `--shell <name>` | the script's shell: `bash`, `sh`, `dash`, `ash`, `yash`, `ksh`, `mksh`, `zsh` (default: from the shebang or the file name) |
 | `--kind <kind>` | what the file is: `shell`, `dockerfile`, `makefile`, `yaml`, `npm`, `markdown`, `python`, `jenkinsfile` (default: from the file name) |
 | `--lang <en\|ja>` | language (default: from `LANG`) |
+| `--sarif <file>` | with `--check`, also write the problems to this file as SARIF, whatever `--format` prints (so one run gives annotations and a SARIF file) |
 | `--format <format>` | `text`, `markdown` or `json`; with `--check`, also `github` (annotations in GitHub Actions) or `sarif` (for code scanning) |
 | `--no-examples` | leave out worked examples |
+| `--config <file>` | read the settings from this file (see [Settings](#settings)) |
+| `--no-config` | read no settings file |
+| `--set <key>=<value>` | set one setting, as named in VS Code (`--set shell=dash`, `--set notes.idioms=false`); may be repeated |
+| `--print-config` | print the settings in effect, as JSON |
 | `--lsp` | run as a Language Server on standard input and output (see [In your editor](#in-your-editor-language-server)) |
 | `--color`, `--no-color` | colour the text output (default: when writing to a terminal; `NO_COLOR` turns it off) |
 
 In the text output, a construct is labelled with its keywords and a placeholder for what is left out (`while` *condition* `do` *commands* `done`): the placeholder is in italics and dim with colour, and shown as `‹condition›` without. With `--format json`, `label` is that text and `labelParts` lists the parts (`{ "text": "while" }`, `{ "text": "condition", "placeholder": true }`…).
 
+A row or a note about a part of bash ends with the sections of the GNU Bash Reference Manual it is about: `(Bash manual 3.7.2)` in the text output, links to the sections on gnu.org with `--format markdown`. The numbers are those of the bash 5.2 manual. With `--format json`, a token has them in `refs` (`["3.7.2"]`), and `facts` lists the notes that come from the message catalog, with their `id`, `kind` (`note` or `pitfall`), `text` and `refs`.
+
 `--check` prints problems as compilers do (`file:line:column: warning: … [code]`), so editors and CI can pick them up. With `--format github` they become GitHub Actions annotations, shown on the pull request's diff; with `--format sarif`, a SARIF file for code scanning.
 
+## Settings
+
+The tool takes the settings of the VS Code extension that have a meaning in a terminal: `language`, `notes.idioms`, `notes.pitfalls`, `shell`, `yq.flavor`, `diagnostics.ignore`, `diagnostics.embedded`, `examples.enabled`, `examples.disabled` and `customCommands` (see [Settings](https://github.com/sf624/bash-explainer#settings) for what each one does). They come from a JSON file with the keys of VS Code's `settings.json`, with or without `bashExplainer.`; comments and trailing commas are allowed, and nested objects too (`{ "notes": { "idioms": false } }`):
+
+```jsonc
+{
+  // The shell to check scripts for, whatever their shebang says.
+  "bashExplainer.shell": "sh",
+  "bashExplainer.language": "ja",
+  "bashExplainer.diagnostics.ignore": ["crlf"],
+  "bashExplainer.examples.disabled": ["date"],
+  "bashExplainer.customCommands": {
+    "deploy": {
+      "summary": "Deploy a service to production",
+      "options": [{ "names": ["-n", "--dry-run"], "description": "only show what would happen" }]
+    }
+  }
+}
+```
+
+The file is the one given with `--config`, else the one in `$BASH_EXPLAINER_CONFIG`, else `$XDG_CONFIG_HOME/bash-explainer/settings.json` (`~/.config/bash-explainer/settings.json` when `XDG_CONFIG_HOME` is not set). The last one may be missing; a file named with `--config` or `$BASH_EXPLAINER_CONFIG` must be there, and a file that is not JSON is an error (exit status 2). `--no-config` reads none. An unknown key, or a value of the wrong type, is left out with a warning on standard error. Settings that have a meaning only in VS Code or the Language Server (`hover.enabled`, `panel.autoOpen`…) are accepted and left alone, so the file can be a copy of the editor's settings.
+
+`--set key=value` sets one setting; the value is read as JSON when it is JSON (`false`, `["crlf"]`), else as a string (`dash`). Each source overrides the ones before it:
+
+1. the defaults,
+2. the settings file,
+3. `--set`,
+4. `--lang`, `--shell` and `--no-examples`.
+
+`--print-config` prints the settings in effect, as JSON that can be saved as a settings file:
+
+```console
+$ bash-explainer --set shell=dash --print-config
+{
+  "bashExplainer.language": "auto",
+  "bashExplainer.notes.idioms": true,
+  "bashExplainer.notes.pitfalls": true,
+  "bashExplainer.shell": "dash",
+  …
+}
+```
+
+With `language` set to `auto` (the default), the language follows `LC_ALL`, `LC_MESSAGES` or `LANG`.
+
 ## In CI (GitHub Actions)
 
 The repository is also a GitHub Action, which runs this tool at its own version:
@@ -74,7 +125,7 @@ Warnings appear on the pull request's diff, and fail the step (`fail-on-warning:
 
 ## In your editor (Language Server)
 
-`bash-explainer --lsp` is a Language Server on standard input and output: hover a line for its explanation, and get the warnings with their quick fixes, in any editor that speaks LSP. It handles shell scripts (language IDs `sh`, `bash`, `zsh`, `shellscript`…) and the shell code in Dockerfiles, Makefiles, YAML, `package.json`, Markdown, Python and Jenkinsfiles. It runs next to other servers, such as bash-language-server.
+`bash-explainer --lsp` is a Language Server on standard input and output: hover a line for its explanation, and get the warnings with their quick fixes, in any editor that speaks LSP. With `highlight.enabled` on, it also colours the shell code (semantic tokens, from the same syntax tree as the explanations). It handles shell scripts (language IDs `sh`, `bash`, `zsh`, `shellscript`…) and the shell code in Dockerfiles, Makefiles, YAML, `package.json`, Markdown, Python and Jenkinsfiles. It runs next to other servers, such as bash-language-server.
 
 Install it with `npm install --global bash-explainer` (see [Installation](#installation)), so the editor does not wait for `npx`.
 
@@ -109,7 +160,7 @@ language-servers = ["bash-language-server", "bash-explainer"]
   (add-to-list 'eglot-server-programs '((sh-mode bash-ts-mode) . ("bash-explainer" "--lsp"))))
 ```
 
-Settings, as `initializationOptions` or through `workspace/didChangeConfiguration` (under `bashExplainer`): `language` (`en` or `ja`; default from `LANG`), `shell` (the shell to check for; default: from the file), `examples` (`false` leaves out worked examples).
+Settings: the keys of the VS Code extension's settings that have a meaning here, as `initializationOptions` or through `workspace/didChangeConfiguration`, under `bashExplainer` or not, flat (`"diagnostics.ignore": ["crlf"]`) or nested (`diagnostics = { ignore = { 'crlf' } }`): `language`, `notes.idioms`, `notes.pitfalls`, `shell`, `yq.flavor`, `diagnostics.enabled`, `diagnostics.ignore`, `diagnostics.embedded`, `examples.enabled`, `examples.disabled`, `examples.inHover`, `hover.enabled`, `hover.maxDepth`, `highlight.enabled`, `languages` (more language IDs to read as shell scripts), `embedded.files` and `customCommands`. `examples: false`, as earlier releases read it, still turns the examples off. Under what the editor sends, the server reads the [settings file](#settings) of the command-line tool (also `--lsp --config <file>`). Keys and values it cannot use are reported in the editor's log (`window/logMessage`).
 
 ## Privacy
 

package/THIRD_PARTY_NOTICES.md

@@ -8,12 +8,13 @@ Bash Explainer includes the following third-party software (ISC, MIT). Their lic
 
 | Component | Version | License | Included as |
 | --- | --- | --- | --- |
-| [unbash](https://github.com/webpro-nl/unbash) | 6.0.0 | ISC | bundled into `dist/extension.js`; bundled into `dist/web/extension.js` |
+| [unbash](https://github.com/webpro-nl/unbash) | 6.0.1 | ISC | bundled into `dist/extension.js`; bundled into `dist/web/extension.js` |
 
 ## In the web version
 
 | Component | Version | License | Included as |
 | --- | --- | --- | --- |
+| [unbash](https://github.com/webpro-nl/unbash) | 6.0.1 | ISC | bundled into `app.js` |
 | [@codemirror/commands](https://code.haverbeke.berlin/codemirror/commands) | 6.11.1 | MIT | bundled into `app.js` |
 | [@codemirror/language](https://code.haverbeke.berlin/codemirror/language) | 6.13.1 | MIT | bundled into `app.js` |
 | [@codemirror/legacy-modes](https://code.haverbeke.berlin/codemirror/legacy-modes) | 6.5.5 | MIT | bundled into `app.js` |
@@ -26,17 +27,36 @@ Bash Explainer includes the following third-party software (ISC, MIT). Their lic
 | [@marijn/find-cluster-break](https://code.haverbeke.berlin/marijn/find-cluster-break) | 1.0.4 | MIT | bundled into `app.js` |
 | [crelt](https://code.haverbeke.berlin/marijn/crelt) | 1.0.7 | MIT | bundled into `app.js` |
 | [style-mod](https://code.haverbeke.berlin/marijn/style-mod) | 4.1.4 | MIT | bundled into `app.js` |
-| [unbash](https://github.com/webpro-nl/unbash) | 6.0.0 | ISC | bundled into `app.js` |
 | [w3c-keyname](https://github.com/marijnh/w3c-keyname#readme) | 2.2.8 | MIT | bundled into `app.js` |
 
 ## In the command-line tool (npm package bash-explainer)
 
 | Component | Version | License | Included as |
 | --- | --- | --- | --- |
-| [unbash](https://github.com/webpro-nl/unbash) | 6.0.0 | ISC | bundled into `dist/cli.js` |
+| [unbash](https://github.com/webpro-nl/unbash) | 6.0.1 | ISC | bundled into `dist/cli.js` |
 
 ## License texts
 
+### unbash
+
+```text
+ISC License
+
+Copyright (c) Lars Kappert
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+```
+
 ### @codemirror/commands, @codemirror/language, @codemirror/legacy-modes, @codemirror/lint, @codemirror/state, @codemirror/streamparser, @codemirror/view
 
 ```text
@@ -163,26 +183,6 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 ```
 
-### unbash
-
-```text
-ISC License
-
-Copyright (c) Lars Kappert
-
-Permission to use, copy, modify, and/or distribute this software for any
-purpose with or without fee is hereby granted, provided that the above
-copyright notice and this permission notice appear in all copies.
-
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
-REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
-AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
-INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
-LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
-OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
-PERFORMANCE OF THIS SOFTWARE.
-```
-
 ### w3c-keyname
 
 ```text