@gspothq/cli 0.1.1 → 0.2.0

package/configurations/language/bash/manifest.toml

@@ -1,8 +1,9 @@
 allowed_words = ["Bash", "ShellCheck", "tree-sitter"]
+
 [configuration]
-title = "Bash, zsh, and Bats scripts"
+description = "Shell scripts, hooks, and task files: ShellCheck, shfmt, a syntax check, and the structure rules for shell."
 suggests = []
-description = "Shell scripts, hooks and task files: ShellCheck, shfmt, a syntax pass, and the structure rules for shell."
+title = "Bash, zsh, and Bats scripts"
 
 [detect]
 extensions = [".sh", ".bash", ".zsh", ".bats"]
@@ -12,250 +13,168 @@ shebangs = ["shell"]
 extensions = [".sh", ".bash", ".zsh", ".bats"]
 tags = ["shebang:shell"]
 
+[[naming.override]]
+allowed_names = ["IFS", "OPTARG", "OPTIND", "EUID", "UID", "PPID", "RANDOM", "SECONDS", "LINENO", "BASH_SOURCE", "BASH_REMATCH", "BASH_VERSION", "BASH_VERSINFO", "FUNCNAME", "PIPESTATUS", "REPLY", "CDPATH", "OLDPWD", "SHLVL", "HOSTNAME", "OSTYPE", "MACHTYPE", "COLUMNS", "LINES"]
+categories = ["variables"]
+languages = ["bash"]
+paths = ["**"]
+reason = "The shell defines these variable names."
+
+[[naming.override]]
+categories = ["functions", "variables", "constants", "methods", "attributes"]
+ignored_prefix = "^_+"
+languages = ["bash"]
+paths = ["**"]
+reason = "A leading underscore marks a private shell declaration."
+
 [[tool]]
+apt = "shellcheck"
+brew = "shellcheck"
+github = { name = "koalaman/shellcheck", version = "v0.11.0" }
+mise = "shellcheck"
 name = "shellcheck"
 refused_options = [
     { paths = ["enable", "disable"], message = "ShellCheck rule selection comes from level recommended or all and gspot ignore. Remove enable and disable from tools.shellcheck.extra.value." },
 ]
+replace = [".shellcheckrc"]
 rule_url = "https://www.shellcheck.net/wiki/{rule}"
+scoop = "shellcheck"
 suppression = { marker = "\\bshellcheck +disable=", reason = "# ?reason: (?<reason>\\S.*)" }
 version = "0.11.0"
-mise = "shellcheck"
-brew = "shellcheck"
-apt = "shellcheck"
 winget = "koalaman.shellcheck"
-scoop = "shellcheck"
-github = { name = "koalaman/shellcheck", version = "v0.11.0" }
-[[tool.replace]]
-file = ".shellcheckrc"
-shared = false
 
 [[tool]]
+brew = "shfmt"
+github = { name = "mvdan/sh", version = "v3.12.0" }
+mise = "shfmt"
 name = "shfmt"
+scoop = "shfmt"
 version = "3.12.0"
-mise = "shfmt"
-brew = "shfmt"
 winget = "mvdan.shfmt"
-scoop = "shfmt"
-github = { name = "mvdan/sh", version = "v3.12.0" }
-
-[[tool]]
-name = "bash"
-min_version = "4.4"
-install_hint = "install Bash 4.4 or newer, such as with brew install bash on macOS"
-system = true
-version_command = ["--version"]
-version_pattern = "version (\\d+\\.\\d+(?:\\.\\d+)?)"
 
 [[tool]]
 name = "zsh"
 system = true
 
-[[tool]]
-name = "bats"
-system = true
-
 [[tool_file]]
+per_scope = true
 target = ".gspot/config/shellcheckrc"
 tool = "shellcheck"
-rule_keys = ["enable", "disable"]
-per_scope = true
 
-[[check]]
-name = "bash-syntax"
-example = "In `greet.sh`, `if then` has no condition. Use a real test: `if [ -f \"$file\" ]; then printf \"%s\\n\" \"$file\"; fi`, then rerun the syntax check."
-level = "recommended"
-stage = "commit"
-command = ["bash", "-n", "{file}"]
-files = { tags = ["bash"] }
-output = { format = "regex", pattern = "^.*: line (?<line>\\d+): (?<message>.*)$" }
-summary = "Checks that Bash scripts parse before running them."
-why = "A script with a syntax error stops at the broken line, sometimes after it has already done half its work."
-help = "Open the file at the line bash names and fix the quoting, bracket, or keyword it complains about."
+[[tool_file]]
+per_scope = true
+target = ".gspot/config/semgrep/bash.yml"
+tool = "semgrep"
+when = { configuration = "security" }
 
 [[check]]
-name = "zsh-syntax"
-example = "In a Zsh script, `if then` has no condition. Use a real test: `if [[ -f \"$file\" ]]; then print -r -- \"$file\"; fi`, then rerun with Zsh installed."
-level = "recommended"
-stage = "commit"
 command = ["zsh", "-n", "{file}"]
+example = "In a Zsh script, `if then` has no condition. Write a real test, such as `if [[ -f \"$file\" ]]; then print -r -- \"$file\"; fi`."
 files = { tags = ["zsh"] }
-output = { format = "regex", pattern = "^(?<file>[^:]+):(?<line>\\d+):\\s*(?<message>.*)$" }
-summary = "Checks Zsh syntax with the Zsh interpreter."
-why = "Zsh syntax differs from Bash, so a Bash parser rejects valid Zsh programs."
-help = "Fix the syntax at the line Zsh reports. Install zsh when the command is missing."
-
-[[check]]
-name = "bats-syntax"
-example = "In a `.bats` file, an unterminated `@test \"greeting\" {` block fails parsing. Complete the test body and close it with `}` before rerunning with Bats installed."
+help = "Fix the syntax at the line Zsh reports. Install zsh when the system lacks it."
 level = "recommended"
+name = "zsh-syntax"
+output = { format = "regex", pattern = "^(?<file>[^:]+):(?<line>\\d+):\\s*(?<message>.*)$" }
 stage = "commit"
-command = ["bats", "--count", "{file}"]
-# Bats parses the file with the bash on PATH, and under Bash 3.2 it passes a file that does not parse.
-tool = ["bats", "bash"]
-files = { tags = ["bats"] }
-output = { format = "regex", pattern = "^# (?<file>[^:]+): line (?<line>\\d+): (?<message>.*)$" }
-summary = "Parses Bats test files while counting their test cases."
-why = "Bats test declarations need the Bats parser before Bash can read them."
-help = "Fix the syntax reported by Bats. Install bats-core when the command is missing."
+summary = "Checks the syntax of Zsh scripts with `zsh -n`."
+why = "Zsh syntax differs from Bash, so a Bash parser rejects valid Zsh programs."
 
 [[check]]
-name = "shellcheck"
-example = "In a Bash script, `printf \"%s\\n\" $name` reports SC2086 because the expansion permits word splitting and globbing. Use `printf \"%s\\n\" \"$name\"` to pass the value as one argument."
-level = "recommended"
-stage = "commit"
-files = { tags = ["bash", "sh", "bats"] }
 command = ["shellcheck", "--rcfile", "{tool_file:shellcheckrc}", "--severity=style", "--check-sourced", "--format=gcc", "{files}"]
+example = "In a Bash script, `printf \"%s\\n\" $name` reports SC2086 because the expansion permits word splitting and globbing. Use `printf \"%s\\n\" \"$name\"` to pass the value as one argument."
 exit_codes = [1]
+files = { tags = ["bash", "sh", "bats"] }
+help = "Read the SC code in the finding; `gspot explain shellcheck/SC2086` links to its page. Turn one code off with `gspot ignore bash/shellcheck --rule SC2086 --reason \"<why>\"`."
+level = "recommended"
+name = "shellcheck"
 output = { format = "regex", pattern = "^(?<file>[^:]+):(?<line>\\d+):(?<column>\\d+): (?:note|warning|error|style): (?<message>.*?) \\[(?<rule>SC\\d+)\\]$" }
-summary = "Runs ShellCheck over shell scripts and sourced files, adding stable optional ShellCheck rules at level all."
-why = "ShellCheck catches the quoting, globbing and exit-status mistakes that make shell scripts fail on the one input nobody tested."
-help = "Read the SC code in the finding; gspot explain shellcheck/SC2086 links to its page. Turn one code off with gspot ignore bash/shellcheck --rule SC2086 --reason \"`<why>`\"."
+stage = "commit"
+summary = "Runs ShellCheck over shell scripts and sourced files, with its stable optional rules at level all."
+why = "ShellCheck catches the quoting, globbing, and exit-status mistakes that make a script fail on the one input nobody tested."
 
 [[check]]
-name = "shfmt"
-example = "In a script, `if true;then echo hello;fi` differs from shfmt output. Run the configured formatter to add the required spacing and block layout, then rerun the check."
-level = "recommended"
-stage = "commit"
-files = { tags = ["bash", "sh", "bats"] }
 command = ["shfmt", "-d", "-i", "{indent}", "-ci", "-s", "{files}"]
+example = "`if true;then echo hello;fi` differs from the shfmt output. Run `gspot check --fix` to add the spacing and line breaks."
+files = { tags = ["bash", "sh", "bats"] }
 fix = ["shfmt", "-w", "-i", "{indent}", "-ci", "-s", "{files}"]
+help = "Run `gspot check --fix` to format every script, or `shfmt -w` on one file."
+level = "recommended"
+name = "shfmt"
 output = { format = "regex", pattern = "^(?:--- )?(?<file>.+?)(?:\\.orig$|:(?<line>\\d+):(?<column>\\d+): (?<message>.+)$)", message = "This script is not formatted the way shfmt formats it.", fixable = "^--- " }
-summary = "Checks that every shell script is formatted the way shfmt formats it."
+stage = "commit"
+summary = "Checks that every shell script matches the shfmt output."
 why = "One formatter means diffs show what changed, not how someone's editor indents."
-help = "Run gspot check --fix to format every script, or shfmt -w on one file."
 
 [[check]]
-name = "script-layout"
-example = "An executable Bash script without `set -euo pipefail` reports a strict-mode finding. Put strict mode before the first command and, when the script defines functions, call the documented `main` function last."
+example = "An executable Bash script without `set -euo pipefail` reports a finding. Put that line before the first command, and when the script defines functions, call `main` last."
+help = "Open with the shebang and run `set -euo pipefail` first. When an executable defines functions, end it with a call to main."
 level = "all"
+name = "script-layout"
 stage = "commit"
-summary = "Checks the contract every Bash script keeps: the shebang, strict mode, a main called last when functions are defined, declarative libraries, cleaned-up temporary files."
-why = "A script that skips strict mode or hides its runtime fails on the machine where it matters, silently."
-help = "Open with the shebang and run set -euo pipefail first. When an executable defines functions, end it with a call to main."
+summary = "Checks each Bash script for a shebang, strict mode, a final `main` call when it defines functions, declarative libraries, and removed temporary files."
+why = "A script that skips strict mode or hides its runtime fails silently on the machine that matters."
 
 [[check]]
-name = "doc-comments"
-example = "A function `_quiet() { printf \"%s\\n\" \"Hello\"; }` without a preceding description reports a missing comment. Add `# _quiet: prints a greeting.` immediately above the function. Other structural checks still apply."
+example = "`_quiet() { printf \"%s\\n\" \"Hello\"; }` with no comment above it reports a finding. Add `# _quiet: prints a greeting.` on the line above."
+help = "Write \"# name: what it does\" above the function; when it carries doc sections, keep Globals, Arguments, Outputs, and Returns in that order."
 level = "all"
+name = "doc-comments"
 stage = "commit"
-summary = "Checks that every shell function announces itself in a comment above it that says more than its name."
-why = "A function with no summary makes the reader run it in their head; a vague summary is a summary nobody will trust."
-help = "Write \"# name: what it does\" above the function; when it carries doc sections, keep Globals, Arguments, Outputs, Returns in that order."
+summary = "Checks that each shell function has a comment above it that says more than its name."
+why = "Without a summary, the reader must trace the function in their head, and nobody trusts a vague one."
 
 [[check]]
-name = "unused-functions"
-example = "A private shell function `_orphan` that no script calls reports an unused-function finding. Delete the unused definition. If an external hook requires the function, record that contract with `gspot ignore` and a reason."
+example = "A private function `_orphan` that no script calls reports a finding. Delete it, or record a hook that needs it with `gspot ignore` and a reason."
+help = "Delete the function. For a required hook entry point, run `gspot ignore bash/unused-functions --paths <file> --reason <why>`."
 level = "recommended"
-stage = "commit"
+name = "unused-functions"
 runs = "scope"
+stage = "commit"
 summary = "Finds shell functions no script in the scope calls."
-why = "ShellCheck checks one file; this check follows calls across every script in the scope."
-help = "Delete the function. For a required hook entry point, run `gspot ignore bash/unused-functions --paths <file> --reason <why>`."
+why = "ShellCheck works on one file at a time, while this check follows calls across the whole scope."
 
 [[check]]
-name = "unread-arguments"
-example = "A call `_deaf one two` whose function never reads positional arguments reports dead parameters. If both arguments are unnecessary, remove them from the call. Otherwise read and use the arguments in the function."
+example = "`_deaf one two` reports dead parameters when `_deaf` never reads its arguments. Drop them from the call, or use them in the function."
+help = "Read the argument in the function, or drop it from every call."
 level = "recommended"
-stage = "commit"
+name = "unread-arguments"
 runs = "scope"
-summary = "Finds shell functions called with arguments they never read."
-why = "A caller that passes an argument expects it to affect the result. An unread argument misleads the caller."
-help = "Read the argument in the function, or drop it from every call."
-
-[[check]]
-name = "source-order"
-example = "A block of `source` lines that is not ordered shortest first reports the sorted order. Reorder the lines."
-level = "all"
 stage = "commit"
-summary = "Checks that the source statements of a block go shortest first, alphabetically among lines of one length."
-why = "One order for every block means a reader never searches it."
-help = "Reorder the source statements shortest first."
+summary = "Finds shell functions called with arguments they never read."
+why = "An unread argument misleads the caller, who expects it to change the result."
 
 [[check]]
-name = "private-prefix"
-example = "A function `build_it` called only from its own script reports a missing private prefix. Rename it `_build_it` and update each local call. A function called from another script keeps its public name."
+example = "A function over `limits.bash.function_lines` reports `function-lines` with the count and the limit. Split it by job."
+help = "Split the script or the function, or raise the named limits.bash setting with a reason."
 level = "all"
-stage = "commit"
-runs = "scope"
-summary = "Checks that a shell function no other file calls starts with an underscore, and that an underscore function is not called from outside."
-why = "The underscore tells a reader what the file publishes without reading every caller."
-help = "Rename the function with a leading underscore, or drop the underscore when another file calls it."
-
-[[check]]
 name = "function-size"
-example = "A function over `limits.bash.function_lines`, `limits.bash.branches`, `limits.bash.nesting`, or `limits.bash.assignments` reports the count and the ceiling under `function-lines`, `branches`, `nesting`, or `assignments`. Split the function by the job, then rerun."
-level = "all"
 stage = "commit"
 summary = "Checks every shell function against the size ceilings: code lines, branches, nesting, and assignments."
-why = "A long script holds more than one job, and a function with many branches or assignments is several functions with one name."
-help = "Split the script or the function, or raise the named limits.bash setting with a reason."
+why = "A long script holds more than one job, and many branches or assignments hide several functions under one name."
 
 [[check]]
-name = "wrappers"
-example = "A short launcher containing only `exec bash scripts/build.sh` reports a forwarding-wrapper finding. Invoke `scripts/build.sh` directly and remove the redundant launcher."
+example = "A launcher that holds only `exec bash scripts/build.sh` reports a finding. Call `scripts/build.sh` directly, and delete the launcher."
+help = "Call the target script directly and delete the redundant launcher or alias."
 level = "all"
+name = "forwarders"
 stage = "commit"
 summary = "Finds forwarding wrappers and compatibility aliases in shell scripts."
-why = "A wrapper is a second entry point that drifts from the first."
-help = "Call the target script directly and delete the redundant launcher or alias."
+why = "A wrapper adds a second entry point, and the two drift apart."
 
 [[check]]
-name = "inline-scripts"
 example = "A shell heredoc containing a Python program reports embedded code. Move the program into a `.py` file and invoke that file from the shell script."
-level = "all"
-stage = "commit"
-summary = "Finds inline Python, Node, and generated-script heredocs in shell scripts."
-why = "Code inside a heredoc is checked by nothing."
 help = "Move the embedded code into its own file and run that."
-
-[[check]]
-name = "ssh-blocks"
-example = "An anonymous SSH heredoc reports a remote-block finding. Move the remote operation into a named function with a comment that explains its purpose, then invoke that function through the supported remote call."
-level = "all"
-stage = "commit"
-summary = "Checks that ssh heredocs are documented."
-why = "A remote command block with no name is the hardest thing in a script to test or reuse."
-help = "Move the block into a named function and write \"# name: what it does\" above it."
-
-[[check]]
-name = "variable-defaults"
-example = "A default such as `${PORT:-8080}` outside a declared configuration owner reports a misplaced default. Set the default in a path listed in `architecture.roles.env` and consume the configured value elsewhere."
-level = "all"
-stage = "commit"
-summary = "Finds variable defaults of the form name:-value outside the configuration owners."
-why = "A default set in three places is three settings with one name."
-help = "Set the default in a configuration owner named under architecture.roles.env and read the variable everywhere else."
-
-[[check]]
-name = "include-guards"
-example = "A sourced configuration owner without a load guard reports a guard finding. Begin it with `[[ -n ${APP_CONFIG_READY:-} ]] && return 0`, followed by `readonly APP_CONFIG_READY=1`, before declaring its configuration."
 level = "all"
+name = "inline-scripts"
 stage = "commit"
-runs = "scope"
-summary = "Checks that each script in architecture.roles.env starts with an include guard of its own."
-why = "A configuration file sourced twice runs its side effects twice."
-help = "Open the owner with [[ -n ${NAME_READY:-} ]] && return 0 and then readonly NAME_READY=1, with a guard name no other owner uses."
+summary = "Finds inline Python, Node, and generated-script heredocs in shell scripts."
+why = "No check reads code inside a heredoc."
 
 [[check]]
-name = "safety"
-example = "A `killall worker` command reports broad-kill. Target the specific process, or ignore that rule for the owning script with a reason."
+example = "`killall worker` reports `broad-kill`. Stop the one process by its ID, or ignore the rule for that script with a reason."
+help = "Handle the failure. For required cleanup, use `gspot ignore bash/safety` with `--rule`, `--paths`, and `--reason`."
 level = "recommended"
+name = "safety"
 stage = "commit"
-summary = "Finds broad process kills and recursive deletes, except traps that remove mktemp paths. At all, it also reports discarded failures."
-why = "Each of these is a way a script destroys something it did not mean to and says nothing."
-help = "Handle the failure. For required cleanup, use gspot ignore bash/safety with --rule, --paths and --reason."
-
-[[naming.override]]
-paths = ["**"]
-languages = ["bash"]
-categories = ["variables"]
-allowed_names = ["IFS", "OPTARG", "OPTIND", "EUID", "UID", "PPID", "RANDOM", "SECONDS", "LINENO", "BASH_SOURCE", "BASH_REMATCH", "BASH_VERSION", "BASH_VERSINFO", "FUNCNAME", "PIPESTATUS", "REPLY", "CDPATH", "OLDPWD", "SHLVL", "HOSTNAME", "OSTYPE", "MACHTYPE", "COLUMNS", "LINES"]
-reason = "The shell defines these variable names."
-
-[[naming.override]]
-paths = ["**"]
-languages = ["bash"]
-categories = ["functions", "variables", "constants", "methods", "attributes"]
-ignored_prefix = "^_+"
-reason = "A leading underscore marks a private shell declaration."
+summary = "Finds broad process kills and recursive deletes, except traps that remove mktemp paths. At level all, also reports discarded failures."
+why = "Each of these lets a script silently destroy something by mistake."

package/configurations/language/bash/rules/BASH.md

@@ -1,17 +1,18 @@
 # Bash
 
+Read this rule when you write or change a shell script.
+
 ## Bash scope
 
 <!-- level: all -->
 
-Bash orchestrates commands as glue code and does not build application logic. Prefer
-small scripts with explicit inputs, explicit outputs, and clear failure behavior.
+Use Bash as glue code that runs commands, not for application logic. Prefer
+small scripts with explicit inputs and outputs and clear failure behavior.
 Treat every path, argument, environment value, command output, and user input as unsafe until
 quoted, validated, or parsed by a structured tool. A script that builds, deploys, deletes, or
 publishes artifacts makes its inputs, effects, and failure behavior explicit.
 
-`set -euo pipefail` does not replace checks around dangerous commands. Keep CI YAML and package
-scripts short. Put longer logic in a script file the checks can lint.
+`set -euo pipefail` does not replace checks around dangerous commands.
 
 ## Bash tasks
 
@@ -20,7 +21,7 @@ scripts short. Put longer logic in a script file the checks can lint.
 Use Bash when the script mostly calls other command-line tools or wires together
 installation, lint, build, runtime, publication, or cleanup steps. Use it to validate the
 environment and dispatch to project commands, or for file movement, process checks,
-and retry loops. Do not use Bash for business logic or complex text parsing. Do not use it
+and retry loops. Do not use Bash for complex text parsing. Do not use it
 for JSON, YAML, XML, or HTML transformations beyond extraction with a dedicated
 parser. Large mutable data structures, long-lived daemons, high-performance work,
 security-sensitive parsing of untrusted input, and behavior that needs typed contracts belong
@@ -40,22 +41,22 @@ for cleanup that can run safely on the relevant exit path.
 
 <!-- level: all -->
 
-An executable script finishes with a meaningful status: a final diagnostic command, a false
-condition, or an optional cleanup check must not become the script status by accident. Use
+End an executable script with a meaningful status. A final message, a false condition, or an
+optional cleanup check must not set the exit status by accident. Use
 an explicit `exit 0` only when the final command's status differs from the program result and
 prior checks establish success.
 
 ## Options
 
-Use `errexit` as a backstop rather than control flow: it has exceptions in
-conditionals, pipelines, command substitutions, subshells, and functions, so `cd`, `rm`,
-check builds, publishing, uploads, and destructive commands explicitly. Do not toggle
+Use `errexit` as a backstop, not as control flow. It does not stop the script inside conditionals, pipelines,
+command substitutions, subshells, and some functions. Check the status of `cd`, `rm`, builds, publishing, uploads,
+and destructive commands explicitly. Do not toggle
 options around a small operation without restoring the prior state. Do not change `IFS` as a
 strict-mode ritual; set it locally where reading or joining data requires it. Keep `set -x`
 out of committed code.
 
-A function called in
-`if`, `while`, `&&`, or `||` writes its checks inside because `errexit` does not stop it there:
+Put explicit checks inside a function called in `if`, `while`, `&&`, or `||`, because `errexit`
+does not stop it there:
 
 ```bash
 # cleanup: Removes the contents of the target directory.
@@ -67,16 +68,16 @@ cleanup() {
 }
 ```
 
-Process substitution hides producer failures; when the producer matters, write to a checked
-temporary file, use `PIPESTATUS`, or call the producer separately. Under `pipefail`, short
-readers such as `head` and `grep -q` can make the producer see SIGPIPE and fail the pipeline;
-consume input predictably or handle the known status. Under `nounset`, use `${name:-}` where
+Process substitution hides producer failures. When the producer status matters, write to a checked
+temporary file, use `PIPESTATUS`, or call it separately. Under `pipefail`, short
+readers such as `head` and `grep -q` can make the producer receive SIGPIPE and fail the pipeline.
+Consume input predictably or handle the known status. Under `nounset`, use `${name:-}` where
 the public interface accepts an unset variable and `${name:?message}` for a required value at a clear
 boundary. Use `${1:-}` where callers can omit an argument.
 
 ## Output, logging, and errors
 
-Write diagnostics with `printf`, not `echo`. Return or exit with the intended status: printing
+Write messages with `printf`, not `echo`. Return or exit with the intended status: printing
 an error does not make a command fail.
 
 ```bash
@@ -104,3 +105,64 @@ log_status() {
 
 A public, sourced, complex, or risky function carries the full header with `Globals`,
 `Arguments`, `Outputs`, and `Returns` sections.
+
+## Naming
+
+### Bash case rules
+
+<!-- level: all -->
+
+- Executable scripts use `.sh` when invoked through a task runner or build
+  rules.
+- Omit the extension on an executable script only when users invoke it
+  as a command on `PATH`.
+- Give sourced libraries the `.sh` extension and no executable permission.
+- Numbered pipeline steps use `NN-description.sh`, such as `01-install.sh`; the naming check strips
+  the numeric prefix before it matches the stem.
+- Functions and mutable variables use `lower_snake_case`.
+- Use `::` in package-like function prefixes only when a script family already
+  follows that convention.
+
+| Avoid              | Prefer                     | Meaning              |
+| ------------------ | -------------------------- | -------------------- |
+| `DeployScript.sh`  | `deploy-api.sh`            | API deployment.      |
+| `deploy_script.sh` | `upload-storage-assets.sh` | Storage upload.      |
+| `helpers.sh`       | `archive-reports`          | A command on `PATH`. |
+
+Name a deployment function `deploy_api` and its local target
+`target_environment`.
+
+### Bash variables
+
+<!-- level: all -->
+
+- Name each loop variable after its item.
+- Name a temporary path after what it holds, such as `download_file` or `work_dir`; `tmp` and
+  `temp` say nothing.
+- Avoid vague names when the domain has a term.
+- Avoid reserved and special shell names for unrelated values.
+
+Use `migration_file` when iterating migration paths and `report_output` for
+captured report text. Check the report command's exit status before printing
+the captured output. A loop variable such as `i` does not describe a file.
+
+### Bash functions
+
+<!-- level: all -->
+
+- Give a function with side effects a verb-phrase name.
+- Name a function that writes to `stdout` for the data it prints.
+- Do not name scripts or functions after shell builtins or common commands.
+- Do not make function names so generic that logs and stack traces lose context.
+
+Name a port validator `validate_port`. Avoid `test`, which shadows a shell builtin, and
+generic names such as `run` or `process`.
+
+### Files
+
+<!-- level: all -->
+
+- Put a related script family in its own subfolder, and give its files role names such as
+  `main.sh`, `state.sh`, `query.sh`, or `report.sh`.
+- Hook families may use a dynamic shared prefix when an external interface owns those
+  filenames.

package/configurations/language/bash/rules/LANGUAGE.md

@@ -1,18 +1,20 @@
 # Bash Language
 
+Read this rule when you write Bash functions, variables, quoting, or loops.
+
 ## Functions
 
-Declare function-local variables with `local`, and separate the declaration from a command
-substitution assignment when the exit code matters, because `local`, `declare`, `readonly`,
-and `export` report their own status rather than the substitution's:
+Declare function-local variables with `local`. When the exit code of a command substitution
+matters, assign it apart from the declaration: `local`, `declare`, `readonly`, and `export`
+report their own status:
 
 ```bash
 local output
 output="$(some_command)" || return 1
 ```
 
-Preserve the documented status contract: a predicate may use status 1 for false, kept
-distinct from an execution error. At level `all`, every executable defines `main` and calls it last.
+Preserve the documented status contract: a predicate may return 1 for false, distinct from an
+execution error.
 
 ```bash
 # report_unreadable_files: Reports each unreadable input and fails if any input is unreadable.
@@ -35,16 +37,18 @@ report_unreadable_files() {
 
 <!-- level: all -->
 
-Use `name() { ... }` for a function that runs in the caller's shell, and a subshell body,
-`name() ( ... )`, for deliberate isolation of the caller's state and traps.
+Use `name() { ... }` for a function that runs in the current shell, and a subshell body,
+`name() ( ... )`, to isolate state and traps from the caller on purpose.
+
+Every executable defines `main` and calls it last.
 
 ## Variables and constants
 
 Mark constants `readonly` immediately after assignment, and
-`export` only what child processes need. Never casually overwrite `PATH`, `HOME`, `IFS`,
-`CDPATH`, `SHELL`, `PWD`, or `BASH_ENV`, and never export `CDPATH`.
+`export` only what child processes need. Do not overwrite `PATH`, `HOME`, `IFS`, `CDPATH`,
+`SHELL`, `PWD`, or `BASH_ENV` without a clear need. Never export `CDPATH`.
 
-Compute a directory constant with `CDPATH='' cd -- <path> && pwd -P` and carries a failure path, `|| exit 1` in an
+Compute a folder constant with `CDPATH='' cd -- <path> && pwd -P` and add a failure path: `|| exit 1` in an
 entrypoint and `|| return 1` in a library. Use `$HOME`, not a quoted `~`, inside paths, and
 assign a home-relative value before exporting it. Quote array elements passed to `unset -v`.
 
@@ -57,9 +61,9 @@ export PROJECT_ROOT
 
 ## Quoting and expansion
 
-Forward arguments with `"$@"`, and use `$*` only to join arguments into one string on
-purpose. Single quotes hold literals and double quotes hold expansions. Command substitution
-output never supplies an unquoted argument list, and word splitting never parses data. Use functions,
+Forward arguments with `"$@"`, and use `$*` only to join them into one string on
+purpose. Use single quotes for literals, double for expansions. Command substitution
+output never supplies an unquoted argument list. Word splitting never parses data. Use functions,
 not aliases. Parameter expansion replaces external tools for string work:
 
 ```bash
@@ -70,7 +74,7 @@ base="${filename%.tar.gz}"
 ## Arrays and argument lists
 
 Command arguments live in arrays, expanded with `"${array[@]}"` and never populated from raw
-`$(...)`. Read lines with a `while read` loop or `readarray`, and read filenames from `NUL`-delimited streams:
+`$(...)`. Read lines with a `while read` loop or `readarray`, and filenames from `NUL`-delimited streams:
 
 ```bash
 declare -a archive_args
@@ -86,9 +90,9 @@ Do not use arrays to imitate nested data structures. A need for those structures
 
 ## Conditionals and arithmetic
 
-`[[ ... ]]` holds string, pattern, and file tests. `==` compares for equality with a quoted
-right-hand side when the value may hold glob characters, and an unquoted right-hand side only
-for pattern matching. Store a regular expression in a variable and use it
+`[[ ... ]]` holds string, pattern, and file tests. With `==`, quote the right-hand side to
+compare equality when the value may hold glob characters, and leave it unquoted only for
+pattern matching. Store a regular expression in a variable and use it
 unquoted with `=~`. `-z` and `-n` test for emptiness. Numeric comparisons live in `(( ... ))` after validation of untrusted numbers; `<` and
 `>` inside `[[ ... ]]` compare strings.
 
@@ -104,8 +108,8 @@ zero, so under `errexit` increment with `retry_count=$(( retry_count + 1 ))`. Un
 strings never enter `(( ... ))`, `$(( ... ))`, `[[ value -gt n ]]`, array indices, or
 arithmetic `for` expressions: validate with a pattern first. `10#${value}` converts unsigned
 base-10 strings; a signed value needs `$(( ${value%%[!+-]*}10#${value#[-+]} ))`. Call `date`
-once when several fields describe one instant, and compute a redirection path before the
-command when the path expression mutates a variable.
+once when several fields describe one instant. Compute a redirection path before the command
+when its expression mutates a variable.
 
 ```bash
 if [[ ! "${port}" =~ ^[0-9]{1,5}$ ]]; then
@@ -142,8 +146,8 @@ done <"${file_list}"
 `IFS= read -r` prevents trimming and backslash handling. Do not save and restore `IFS` with
 `old_ifs="${IFS}"`, which loses the distinction between unset and empty; use a function-local
 `IFS` or a subshell. `read` treats `IFS` as a terminator, so a controlled delimited line
-keeps its trailing empty field only with an appended delimiter. Parse general CSV with
-application code with a real parser, never `IFS=, read`.
+keeps its trailing empty field only with an appended delimiter. Parse general CSV in
+application code with a real parser, never with `IFS=, read`.
 
 ```bash
 # join_path_parts: Joins the arguments with slashes.
@@ -155,10 +159,10 @@ join_path_parts() {
 
 ## Paths, globs, and file names
 
-Quote paths, put `--` before path arguments where the command supports it, prefer globs with
+Quote paths, put `--` before them where the command supports it, prefer globs with
 an explicit prefix such as `./*.sql`, and never filter filenames with `grep`. Filenames can
 hold spaces, newlines, quotes, brackets, and leading dashes. Never assume the current
-directory; compute it, and check `cd` explicitly. A broken symlink needs `-L` beside `-e`
+folder; compute it, and check `cd` explicitly. A broken symlink needs `-L` beside `-e`
 when existence matters, and a basename pattern reads `"${path##*/}"`. Handle the no-match
 glob deliberately, either with `[[ -e ${file} ]] || continue` or with `nullglob` scoped to a
 subshell:
@@ -190,9 +194,9 @@ content="${content_with_sentinel%x}"
 
 ## Pipelines and redirection
 
-Read `PIPESTATUS` immediately when individual statuses matter. Order redirections to show the intent, `>file 2>&1`, and never close a standard descriptor as a shortcut for `/dev/null`. A
-pipeline never reads from and writes to the same file; rewrite a file through a
-temporary file and an atomic rename. Parallel `xargs` jobs do not produce ordered, unmixed
+Read `PIPESTATUS` immediately when individual statuses matter. Order redirections to show the intent, `>file 2>&1`, and never close a standard descriptor as a shortcut for `/dev/null`. Never
+read from and write to the same file in one pipeline. Rewrite it through a temporary file
+and an atomic rename. Parallel `xargs` jobs do not produce ordered, unmixed
 output: write per-job files and combine them, or use a tool that serializes. Check a command
 directly or capture its status in a named variable rather than `(( ! $? )) || die`.