bash-explainer 0.1.1 → 0.2.0

package/README.md

@@ -46,11 +46,68 @@ 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` (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 and Python. 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' },
+  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