bash-explainer 0.9.0 → 0.10.0

package/README.md

@@ -44,13 +44,14 @@ 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, 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 |
+| `--check` | report errors (lines that fail every time, such as `[` without `]`, `x = 1`, `echo $((09))`, `#!/usr/bin/env bash -e`, a syntax error in a plain script, and constructs the script's shell lacks; nothing is reported after a command that surely stops the script, such as `exit 0` or `exec` with a command. What says the shell reads the text wrongly (`x = 1`, a syntax error) is a warning, which only `--strict` fails on, after a command that only may stop it (`source`, `trap`, an `exit` in a function), and in a file only its name says is a script, or standard input with no first line; no syntax error is reported in a host file or in a file not surely a script), other risks (script injection in GitHub Actions, Docker `RUN` pipes without `pipefail`…) and the pitfalls of a script (`rm -rf $DIR/*`, `curl … | sh`…); exit 1 if there is an error |
+| `--strict` | with `--check`, also exit 1 if there is a warning |
+| `--counts <file>` | with `--check`, also append the numbers of problems to the file as `name=value` lines (`errors`, `warnings`, `infos`, `pitfalls`, and `failing`: those that make the exit status 1), as `$GITHUB_OUTPUT` reads them. A symbolic link at the last part of the path is refused. Here `warnings` counts the problems at warning level; the GitHub Action's `warnings` output keeps its old meaning, the problems that fail the step, which is `failing` here |
 | `--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,25 +61,30 @@ bash-explainer --check install.sh     # constructs its shell (#!/bin/sh: dash…
 | `--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) |
 
+The exit status is 0; with `--check`, 1 if a problem fails the check; and 2 if the tool could not run (a usage error, a file it cannot read). It is also 2 after a bug of the tool on a line, and for a file nested too deep to read: the output still has what it could say, the other files too, and standard error tells which.
+
 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 (a warning is a `warning` result, information a `note`).
+`--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 (an error is an `error` result, a warning a `warning`, 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`.
+Problems have three levels: an error (red) for a line that fails every time as written, a warning (yellow) for damage that cannot be undone under some values, and information (blue) for what goes wrong only with some values or on some systems. `--check` fails on every error, on a warning only with `--strict`, and never on information. The pitfalls of a shell script are problems too, with their own codes; turn them off with `--set diagnostics.pitfalls=false` (the errors stay). The severity names the level, so a problem's text has no "Error:" of its own; a pitfall keeps its word ("Pitfall:", "Caveat:").
 
 ```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]
+deploy.sh:3:1: error: [ has no ] as its last argument, so it fails when it runs, without evaluating the condition ([: missing ']', status 2). This is not a syntax error but an error of the command [ at run time [bracket-missing-close]
+deploy.sh:4:1: warning: Pitfall: x =… runs a command named x; it is not an assignment. Write x=1 with no spaces around = [assignment-with-spaces]
+deploy.sh:5:1: info: Caveat: without -r, backslashes in the input are taken as escapes and lost. Usually write read -r [read-without-r]
 $ echo $?
-0
+1
 ```
 
+In the explanation, a note starts with the mark and the word of its level, in its colour: `ⓧ Error:` in red, `⚠ Pitfall:` in yellow, `ⓘ Caveat:` in blue, and a plain fact's `ℹ`, dim. Errors come first.
+
 ## Settings
 
-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.0/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 } }`):
+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.10.0/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
 {
@@ -123,7 +129,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
@@ -134,9 +140,9 @@ 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/v0.9.0/images/action-annotations.png)
+![Warnings from the action on a pull request's diff](https://raw.githubusercontent.com/sf624/bash-explainer/v0.10.0/images/action-annotations.png)
 
-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`), `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`) and `package` (another npm package spec to run). 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.
+Problems appear on the pull request's diff. Errors fail the step (`fail-on-warning: 'false'` keeps it green, errors too); warnings fail it only with `strict: 'true'`. So by default a construct the script's shell lacks fails the step only where it surely fails: what the shell refuses while it reads the file (`a=(1)`, `<<<`, also in a function never called), and a command it surely gets to. In a function, in a branch, or after a command that may stop the script (`. ./lib`, an `exit` in a function), it may never run, so it is a warning: `strict: 'true'` is what catches a bashism there. 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 an error), `fail-on-warning`, `strict` (also fail on a warning; 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: `errors`, the number of errors; `warnings`, the number of problems that fail the step (the errors, and with `strict` the warnings); and `pitfalls`, the number of pitfalls (warnings and notices; an error is none). The counts come from the tool's `--counts`; with an older tool, `errors` is 0. 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)
 
@@ -179,8 +185,8 @@ Settings: the keys of the VS Code extension's settings that have a meaning here,
 
 ## 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.0/README.md#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.10.0/README.md#privacy).
 
 ## License
 
-[MIT](https://github.com/sf624/bash-explainer/blob/v0.9.0/LICENSE). Third-party components: [THIRD_PARTY_NOTICES.md](https://github.com/sf624/bash-explainer/blob/v0.9.0/THIRD_PARTY_NOTICES.md).
+[MIT](https://github.com/sf624/bash-explainer/blob/v0.10.0/LICENSE). Third-party components: [THIRD_PARTY_NOTICES.md](https://github.com/sf624/bash-explainer/blob/v0.10.0/THIRD_PARTY_NOTICES.md).

package/THIRD_PARTY_NOTICES.md

@@ -8,7 +8,7 @@ Bash Explainer includes the following third-party software and artwork (CC-BY-4.
 
 | 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` |
+| [unbash](https://github.com/webpro-nl/unbash) | 6.0.3 | 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` |
 
@@ -16,14 +16,14 @@ Bash Explainer includes the following third-party software and artwork (CC-BY-4.
 
 | Component | Version | License | Included as |
 | --- | --- | --- | --- |
-| [unbash](https://github.com/webpro-nl/unbash) | 6.0.1 | ISC | bundled into `app.js` |
+| [unbash](https://github.com/webpro-nl/unbash) | 6.0.3 | 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` |
 | [@codemirror/lint](https://code.haverbeke.berlin/codemirror/lint) | 6.9.7 | MIT | bundled into `app.js` |
 | [@codemirror/state](https://code.haverbeke.berlin/codemirror/state) | 6.7.6 | MIT | bundled into `app.js` |
 | [@codemirror/streamparser](https://code.haverbeke.berlin/codemirror/streamparser) | 6.0.0 | MIT | bundled into `app.js` |
-| [@codemirror/view](https://code.haverbeke.berlin/codemirror/view) | 6.43.14 | MIT | bundled into `app.js` |
+| [@codemirror/view](https://code.haverbeke.berlin/codemirror/view) | 6.43.15 | MIT | bundled into `app.js` |
 | [@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` |
@@ -36,7 +36,7 @@ Bash Explainer includes the following third-party software and artwork (CC-BY-4.
 
 | Component | Version | License | Included as |
 | --- | --- | --- | --- |
-| [unbash](https://github.com/webpro-nl/unbash) | 6.0.1 | ISC | bundled into `dist/cli.js` |
+| [unbash](https://github.com/webpro-nl/unbash) | 6.0.3 | ISC | bundled into `dist/cli.js` |
 
 ## License texts
 
@@ -147,8 +147,8 @@ Copyright (c) Microsoft Corporation. https://github.com/microsoft/vscode-codicon
 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
+Bash Explainer copies twelve of the icons (collapse-all, expand-all, copy, book, arrow-left, gear,
+chevron-down, list-tree, comment-discussion, error, 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