.shellcheckrc

# ShellCheck configuration — repo-agnostic shell-quality ruleset.
# ShellCheck searches for this file from each script's directory upward; CI
# points at this root-canonical file explicitly with --rcfile.
#
# Ref: https://github.com/koalaman/shellcheck/wiki/Optional
# Targets ShellCheck 0.11.0+.
#
# Optional checks are selectively enabled — NOT enable=all. The ShellCheck wiki
# warns against enable=all: "optional checks are more subjective rather than
# more comprehensive, and may conflict with each other".

# Default shell dialect — scripts target bash.
shell=bash

# Resolve `source`d files at lint time (no remote fetch; analysis only).
external-sources=true

# Look for sourced files relative to the script's directory.
source-path=SCRIPTDIR

# --- Optional checks (selectively enabled) ---

# Suggest a default *) case in case statements — catches missing fallthrough.
enable=add-default-case

# Suggest [ a -ne b ] over [ ! a -eq b ] — reduces cognitive load.
enable=avoid-negated-conditions

# Suggest explicit [ -n "$var" ] over [ "$var" ] — clarity of intent.
enable=avoid-nullary-conditions

# Notify when set -e is suppressed during function invocation in conditionals —
# catches the bash trap where errexit silently stops working inside if/while/&&/||.
# Ref: https://github.com/koalaman/shellcheck/wiki/SC2310
enable=check-set-e-suppressed

# Warn on unassigned uppercase variables — catches typos in UPPER_SNAKE globals.
enable=check-unassigned-uppercase

# Suggest command -v over which — POSIX standard, more reliable.
enable=deprecate-which

# Require [[ ]] over [ ] in bash (SC2292). A script that intentionally uses
# [ ] (for POSIX-style graceful degradation) opts out per-file with
# `# shellcheck disable=SC2292` (disable directives take SC codes, not names).
enable=require-double-brackets

# Re-enable useless-use-of-cat — was default before 0.11.0, now optional.
enable=useless-use-of-cat

# --- NOT enabled (with rationale) ---

# check-extra-masked-returns (SC2312): too noisy for pipe chains and command
#   substitutions that intentionally capture output; deliberate `2>/dev/null ||
#   true` patterns would fire on every `var=$(cmd)`.

# quote-safe-variables (SC2248): conflicts with require-variable-braces (SC2250)
#   — one wants "$var", the other ${var}; together they demand "${var}"
#   everywhere. SC2086 (default, non-optional) already catches dangerous unquoted
#   expansions.

# require-variable-braces (SC2250): too verbose — $var is clear in most contexts;
#   ${var} is only needed when concatenating adjacent characters (${var}_suffix).