bash-explainer 0.1.1 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # bash-explainer
 
-Explains shell scripts line by line in the terminal — every command, option, redirection and `${…}` — with worked examples. 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.
+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.
 
@@ -34,7 +34,7 @@ bash-explainer deploy.sh:12           # one line (or deploy.sh:12-20)
 bash-explainer -e 'cmd 2>&1 > out'    # a command line
 cat deploy.sh | bash-explainer -      # standard input
 bash-explainer Dockerfile             # the shell code in Dockerfiles, Makefiles, CI YAML,
-                                      # package.json, Markdown and Python
+                                      # Jenkinsfiles, package.json, Markdown and Python
 bash-explainer --check install.sh     # constructs its shell (#!/bin/sh: dash…) lacks
 ```
 
@@ -44,13 +44,70 @@ bash-explainer --check install.sh     # constructs its shell (#!/bin/sh: dash…
 | `-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 |
 | `--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` (default: from 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`) |
-| `--format <format>` | `text`, `markdown` or `json` |
+| `--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 |
+| `--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) |
 
-`--check` prints problems as compilers do (`file:line:column: warning: … [code]`), so editors and CI can pick them up.
+`--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.
+
+## In CI (GitHub Actions)
+
+The repository is also a GitHub Action, which runs this tool at its own version:
+
+```yaml
+- uses: actions/checkout@v5
+- uses: sf624/bash-explainer@v0
+  with:
+    files: '**/*.sh Dockerfile .github/workflows/*.yml'
+```
+
+`@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 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.
+
+## 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.
+
+Install it with `npm install --global bash-explainer` (see [Installation](#installation)), so the editor does not wait for `npx`.
+
+**Neovim** (0.11 or later), in `init.lua`:
+
+```lua
+vim.lsp.config('bash_explainer', {
+  cmd = { 'bash-explainer', '--lsp' },
+  filetypes = { 'sh', 'bash', 'zsh', 'dockerfile', 'make', 'yaml', 'groovy' },
+  root_markers = { '.git' },
+  -- init_options = { language = 'ja', shell = 'dash' },
+})
+vim.lsp.enable('bash_explainer')
+```
+
+**Helix**, in `languages.toml`:
+
+```toml
+[language-server.bash-explainer]
+command = "bash-explainer"
+args = ["--lsp"]
+
+[[language]]
+name = "bash"
+language-servers = ["bash-language-server", "bash-explainer"]
+```
+
+**Emacs** (Eglot, one server per mode):
+
+```elisp
+(with-eval-after-load 'eglot
+  (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).
 
 ## Privacy
 

package/THIRD_PARTY_NOTICES.md

@@ -8,8 +8,8 @@ Bash Explainer includes the following third-party software (MIT). Their license
 
 | Component | Version | License | Included as |
 | --- | --- | --- | --- |
-| [tree-sitter-bash](https://github.com/tree-sitter/tree-sitter-bash) | 0.23.3 | MIT | `dist/tree-sitter-bash.wasm` |
-| [web-tree-sitter](https://github.com/tree-sitter/tree-sitter/tree/master/lib/binding_web) | 0.22.6 | MIT | bundled into `dist/extension.js`; bundled into `dist/web/extension.js`; `dist/tree-sitter.wasm` |
+| [tree-sitter-bash](https://github.com/tree-sitter/tree-sitter-bash) | 0.25.1 | MIT | `dist/tree-sitter-bash.wasm` |
+| [web-tree-sitter](https://github.com/tree-sitter/tree-sitter) | 0.27.0 | MIT | bundled into `dist/extension.js`; bundled into `dist/web/extension.js`; `dist/web-tree-sitter.wasm` |
 
 ## In the web version
 
@@ -26,16 +26,16 @@ Bash Explainer includes the following third-party software (MIT). Their license
 | [@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` |
-| [tree-sitter-bash](https://github.com/tree-sitter/tree-sitter-bash) | 0.23.3 | MIT | `tree-sitter-bash.wasm` |
+| [tree-sitter-bash](https://github.com/tree-sitter/tree-sitter-bash) | 0.25.1 | MIT | `tree-sitter-bash.wasm` |
 | [w3c-keyname](https://github.com/marijnh/w3c-keyname#readme) | 2.2.8 | MIT | bundled into `app.js` |
-| [web-tree-sitter](https://github.com/tree-sitter/tree-sitter/tree/master/lib/binding_web) | 0.22.6 | MIT | bundled into `app.js`; `tree-sitter.wasm` |
+| [web-tree-sitter](https://github.com/tree-sitter/tree-sitter) | 0.27.0 | MIT | bundled into `app.js`; `web-tree-sitter.wasm` |
 
 ## In the command-line tool (npm package bash-explainer)
 
 | Component | Version | License | Included as |
 | --- | --- | --- | --- |
-| [tree-sitter-bash](https://github.com/tree-sitter/tree-sitter-bash) | 0.23.3 | MIT | `dist/tree-sitter-bash.wasm` |
-| [web-tree-sitter](https://github.com/tree-sitter/tree-sitter/tree/master/lib/binding_web) | 0.22.6 | MIT | bundled into `dist/cli.js`; `dist/tree-sitter.wasm` |
+| [tree-sitter-bash](https://github.com/tree-sitter/tree-sitter-bash) | 0.25.1 | MIT | `dist/tree-sitter-bash.wasm` |
+| [web-tree-sitter](https://github.com/tree-sitter/tree-sitter) | 0.27.0 | MIT | bundled into `dist/cli.js`; `dist/web-tree-sitter.wasm` |
 
 ## License texts
 
@@ -220,7 +220,7 @@ THE SOFTWARE.
 ```text
 The MIT License (MIT)
 
-Copyright (c) 2018-2024 Max Brunsfeld
+Copyright (c) 2018 Max Brunsfeld
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal