bash-explainer 0.8.0 → 0.9.1

package/README.md

@@ -1,5 +1,7 @@
 # bash-explainer
 
+[![npm](https://img.shields.io/npm/v/bash-explainer?label=npm)](https://www.npmjs.com/package/bash-explainer)
+
 Explains shell scripts line by line in the terminal — every command, option, redirection and `${…}` — with worked examples, and points out common pitfalls (unquoted variables, `x = 1`, `for f in $(ls)`…). The command-line companion of the [Bash Explainer](https://marketplace.visualstudio.com/items?itemName=shun-fujioka.bash-explainer) VS Code extension, with the same explanations.
 
 **Offline by design:** no network, no AI, no telemetry. English and Japanese.
@@ -20,7 +22,7 @@ $ npx bash-explainer --no-examples -e 'tar -czf backup.tgz -C src .'
 
 ## Installation
 
-Requires Node.js 18 or later. The parser is WebAssembly, so there are no native dependencies: it runs wherever Node.js does.
+Requires Node.js 18 or later. The parser is plain JavaScript, so there are no native dependencies: it runs wherever Node.js does.
 
 - **Without installing:** `npx bash-explainer <file>` fetches the package on first use.
 - **Installed:** `npm install --global bash-explainer`, then `bash-explainer <file>`. Use this when you run it often, or from an editor.
@@ -42,11 +44,13 @@ bash-explainer --check install.sh     # constructs its shell (#!/bin/sh: dash…
 | --- | --- |
 | `-e`, `--command <text>` | explain this command line |
 | `-l`, `--line <n>[-<m>]` | only these lines |
-| `--check` | report constructs the script's shell lacks, and other risks (script injection in GitHub Actions, Docker `RUN` pipes without `pipefail`…); exit 1 if there is a warning |
+| `--check` | report constructs the script's shell lacks, other risks (script injection in GitHub Actions, Docker `RUN` pipes without `pipefail`…) and the pitfalls of a script (`x = 1`, `rm -rf $DIR/*`…); exit 1 if there is a warning, other than on a pitfall |
+| `--strict` | with `--check`, also exit 1 if there is a warning on a pitfall |
 | `--shell <name>` | the script's shell: `bash`, `sh`, `dash`, `ash`, `yash`, `ksh`, `mksh`, `zsh` (default: from the shebang or the file name) |
+| `--bash-version <v>` | the bash release to explain for: `5.2` (default) or `5.3`; constructs of a later release are explained as it runs them, and `--check` warns about them |
 | `--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) |
+| `--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). A symbolic link at the last part of the path is refused |
 | `--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)) |
@@ -60,11 +64,21 @@ In the text output, a construct is labelled with its keywords and a placeholder
 
 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.
+`--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 (a warning is a `warning` result, information a `note`).
+
+The pitfalls of a shell script are problems too, with their own codes: a warning for what breaks the script, information for the rest. They make `--check` fail only with `--strict`, so a CI that passed before keeps passing; turn them off with `--set diagnostics.pitfalls=false`.
+
+```text
+$ bash-explainer --check deploy.sh
+deploy.sh:2:10: warning: Pitfall: the output of $(ls …) is split on spaces and newlines, so file names with spaces break. Use a glob, as in for f in *.txt [for-over-ls-output]
+deploy.sh:4:1: warning: Pitfall: x =… runs a command named x; it is not an assignment. Write x=… with no spaces around = [assignment-with-spaces]
+$ echo $?
+0
+```
 
 ## 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 } }`):
+The tool takes the settings of the VS Code extension that have a meaning in a terminal: `language`, `notes.idioms`, `notes.pitfalls`, `notes.basis`, `shell`, `bashVersion`, `yq.flavor`, `diagnostics.ignore`, `diagnostics.embedded`, `diagnostics.pitfalls`, `examples.enabled`, `examples.disabled` and `customCommands` (see [Settings](https://github.com/sf624/bash-explainer/blob/v0.9.1/README.md#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
 {
@@ -89,7 +103,7 @@ The file is the one given with `--config`, else the one in `$BASH_EXPLAINER_CONF
 1. the defaults,
 2. the settings file,
 3. `--set`,
-4. `--lang`, `--shell` and `--no-examples`.
+4. `--lang`, `--shell`, `--bash-version` and `--no-examples`.
 
 `--print-config` prints the settings in effect, as JSON that can be saved as a settings file:
 
@@ -99,6 +113,7 @@ $ bash-explainer --set shell=dash --print-config
   "bashExplainer.language": "auto",
   "bashExplainer.notes.idioms": true,
   "bashExplainer.notes.pitfalls": true,
+  "bashExplainer.notes.basis": true,
   "bashExplainer.shell": "dash",
   …
 }
@@ -108,7 +123,7 @@ With `language` set to `auto` (the default), the language follows `LC_ALL`, `LC_
 
 ## In CI (GitHub Actions)
 
-The repository is also a GitHub Action, which runs this tool at its own version:
+The repository is also a GitHub Action, which installs this tool at its own version in a directory of its own, outside the checked-out repository, and runs it there on your files. The registry is the one your workflow or machine configures (`setup-node`'s `registry-url`, `npm_config_registry`, your user's npm settings); npm settings kept in the repository do not apply to it:
 
 ```yaml
 - uses: actions/checkout@v5
@@ -119,13 +134,13 @@ The repository is also a GitHub Action, which runs this tool at its own version:
 
 `@v0` follows the latest 0.x release. To stay on one version, use its tag (`@v0.2.0`); to be sure the code cannot change, its commit SHA (`@<sha> # v0.2.0`), which Dependabot can keep up to date.
 
-![Warnings from the action on a pull request's diff](https://raw.githubusercontent.com/sf624/bash-explainer/main/images/action-annotations.png)
+![Warnings from the action on a pull request's diff](https://raw.githubusercontent.com/sf624/bash-explainer/v0.9.1/images/action-annotations.png)
 
-Warnings appear on the pull request's diff, and fail the step (`fail-on-warning: 'false'` keeps it green). The inputs: `files` (bash globs; default `**/*.sh`), `shell` (default: from each script), `fail-on-warning`, `sarif` (also write a SARIF file, for `github/codeql-action/upload-sarif`) and `package` (another npm package spec to run). The output `warnings` is the number of warnings. In other CI systems, run `npx bash-explainer --check <files>` and use the exit status.
+Warnings appear on the pull request's diff, and fail the step (`fail-on-warning: 'false'` keeps it green); the pitfalls appear too, but fail it only with `strict: 'true'`. The inputs: `files` (bash globs; default `**/*.sh`; a file whose real path is outside the workspace is skipped with a notice), `shell` (default: from each script), `bash-version` (`5.2` or `5.3`, the bash release that bash scripts are checked for; default `5.2`, where `${ cmd; }` is a warning), `fail-on-warning`, `strict` (also fail on a warning on a pitfall; default `'false'`), `sarif` (also write a SARIF file, for `github/codeql-action/upload-sarif`; a path in the workspace or the runner's temp directory must stay there when its symbolic links are followed) and `package` (another npm package spec to run; a relative path is relative to the workspace; install scripts do not run, except that npm prepares a package from git). The outputs: `warnings`, the number of warnings that fail the step (those on pitfalls only with `strict`), and `pitfalls`, the number of pitfalls (warnings and notices). The annotations of pitfalls are titled `Bash Explainer (pitfall): <code>`, and those that fail the step come first, since GitHub shows only the first annotations of a step. `strict` needs a tool with `--strict`, and `bash-version` one with `--bash-version`: with a `package` pin to an older one, the step fails and says so. In other CI systems, run `npx bash-explainer --check <files>` and use the exit status.
 
 ## 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. 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.
+`bash-explainer --lsp` is a Language Server on standard input and output: hover a word for what it is, followed by the explanation of its whole line, see a hint after a command name that does not run what it suggests (inlay hints), 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`.
 
@@ -160,12 +175,12 @@ language-servers = ["bash-language-server", "bash-explainer"]
   (add-to-list 'eglot-server-programs '((sh-mode bash-ts-mode) . ("bash-explainer" "--lsp"))))
 ```
 
-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`).
+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`, `notes.basis`, `shell`, `bashVersion`, `yq.flavor`, `diagnostics.enabled`, `diagnostics.ignore`, `diagnostics.embedded`, `diagnostics.pitfalls`, `examples.enabled`, `examples.disabled`, `examples.inHover`, `hover.enabled`, `hover.maxDepth`, `hints.names`, `hints.deadCode`, `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
 
-Everything runs in the Node.js process: the tool contains no code that opens a network connection or starts a process, which a test checks on every change. See [Privacy](https://github.com/sf624/bash-explainer#privacy).
+Everything runs in the Node.js process: the tool contains no code that opens a network connection or starts a process, which a test checks on every change. See [Privacy](https://github.com/sf624/bash-explainer/blob/v0.9.1/README.md#privacy).
 
 ## License
 
-[MIT](LICENSE). Third-party components: [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+[MIT](https://github.com/sf624/bash-explainer/blob/v0.9.1/LICENSE). Third-party components: [THIRD_PARTY_NOTICES.md](https://github.com/sf624/bash-explainer/blob/v0.9.1/THIRD_PARTY_NOTICES.md).

package/THIRD_PARTY_NOTICES.md

@@ -1,6 +1,6 @@
 # Third-party notices
 
-Bash Explainer includes the following third-party software (ISC, MIT). Their license texts are reproduced below.
+Bash Explainer includes the following third-party software and artwork (CC-BY-4.0, ISC, MIT). Their license texts, and for the artwork under CC BY 4.0 the attribution it asks for, are reproduced below.
 
 <!-- Generated by `npm run notices` (scripts/notices.ts) from what the builds include. A test fails when this file is out of date. -->
 
@@ -9,6 +9,8 @@ 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.1 | ISC | bundled into `dist/extension.js`; bundled into `dist/web/extension.js` |
+| [@vscode/codicons](https://github.com/microsoft/vscode-codicons) | 0.0.46-24 | CC-BY-4.0 | icons copied into `media/icons.js` |
+| [microsoft/vscode](https://github.com/microsoft/vscode) | 1.143.1 | MIT | the token colours of the default colour themes copied into `src/ui/vscodeThemes.json`, bundled into `dist/extension.js` and `dist/web/extension.js` |
 
 ## In the web version
 
@@ -25,6 +27,7 @@ Bash Explainer includes the following third-party software (ISC, MIT). Their lic
 | [@lezer/common](https://code.haverbeke.berlin/lezer/common) | 1.5.3 | MIT | bundled into `app.js` |
 | [@lezer/highlight](https://code.haverbeke.berlin/lezer/highlight) | 1.2.5 | MIT | bundled into `app.js` |
 | [@marijn/find-cluster-break](https://code.haverbeke.berlin/marijn/find-cluster-break) | 1.0.4 | MIT | bundled into `app.js` |
+| [@vscode/codicons](https://github.com/microsoft/vscode-codicons) | 0.0.46-24 | CC-BY-4.0 | icons copied into `icons.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` |
 | [w3c-keyname](https://github.com/marijnh/w3c-keyname#readme) | 2.2.8 | MIT | bundled into `app.js` |
@@ -135,6 +138,23 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 ```
 
+### @vscode/codicons
+
+```text
+Codicons (the icons of Visual Studio Code)
+Copyright (c) Microsoft Corporation. https://github.com/microsoft/vscode-codicons
+
+The icons are licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0):
+https://creativecommons.org/licenses/by/4.0/legalcode
+
+Bash Explainer copies eleven of the icons (collapse-all, expand-all, copy, book, arrow-left, gear,
+chevron-down, list-tree, comment-discussion, warning, info) from src/icons/*.svg of @vscode/codicons
+0.0.46-24, unmodified, as SVG path data drawn in the theme's colours, in the header of the extension's
+panel, in the top bar and the hover cards of the web page and beside the notes of an explanation.
+The licensor offers the icons as-is and makes no representations or warranties of any kind concerning
+them (Section 5 of the license).
+```
+
 ### crelt
 
 ```text
@@ -159,6 +179,39 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 ```
 
+### microsoft/vscode
+
+```text
+Bash Explainer copies the token colours of VS Code's default colour themes (extensions/theme-defaults/themes/*.json
+of VS Code 1.143.1: the TextMate rules that give a foreground, the semantic token colours and the includes) into
+src/ui/vscodeThemes.json (scripts/vscode-themes.ts), for its panel in a remote window, where an extension cannot
+read the themes. They are under the license of the repository:
+
+MIT License
+
+Copyright (c) 2015 - present Microsoft Corporation
+
+All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
 ### style-mod
 
 ```text