bcs

#!/usr/bin/env bash
# SPDX-License-Identifier: GPL-3.0-or-later
#shellcheck disable=SC2015
# bcs - Bash Coding Standard CLI toolkit
# Six subcommands for viewing, generating, and checking compliance with the Bash Coding Standard.
set -euo pipefail
shopt -s inherit_errexit extglob nullglob

declare -rx PATH="$HOME"/.local/bin:/usr/local/bin:/usr/bin:/bin

# Script metadata
declare -r VERSION=2.0.1
#shellcheck disable=SC2155
declare -r SCRIPT_PATH=$(realpath -- "$0")
declare -r SCRIPT_DIR=${SCRIPT_PATH%/*} SCRIPT_NAME=${SCRIPT_PATH##*/}

# Global variables
declare -ar BCS_SEARCH_PATHS=(
  "$SCRIPT_DIR"/data
  "${SCRIPT_DIR%/bin}/share/yatti/BCS/data"
  "${PREFIX:-/usr/local}"/share/yatti/BCS/data
  /usr/share/yatti/BCS/data
)

declare -ar VALID_EFFORTS=(low medium high max)
declare -ar VALID_TEMPLATES=(minimal basic complete library)
declare -ar VALID_TIERS=(core recommended style disabled)
declare -ar VALID_TIER_FILTERS=(core recommended style)

# Rule tier map: BCS#### -> default tier (loaded from section bodies)
declare -A BCS_TIERS=()
# Policy overrides: BCS#### -> override tier (loaded from policy.conf cascade)
declare -A BCS_POLICY=()
declare -i _TIERS_LOADED=0 _POLICY_LOADED=0

# Model-tier to concrete API model mapping per backend
declare -A ANTHROPIC_MODELS=([fast]=claude-haiku-4-5 [balanced]=claude-sonnet-4-6 [thorough]=claude-opus-4-6)
declare -A OLLAMA_MODELS=([fast]=qwen3.5:9b [balanced]=qwen3.5:14b [thorough]=qwen3.5:14b)
declare -A GOOGLE_MODELS=([fast]=gemini-2.5-flash-lite [balanced]=gemini-2.5-flash [thorough]=gemini-2.5-pro)
declare -A OPENAI_MODELS=([fast]=gpt-4.1-mini [balanced]=gpt-5.4-mini [thorough]=gpt-5.4)

# Effort-level to max output tokens mapping for API backends
declare -A EFFORT_TOKENS=([low]=4000 [medium]=8000 [high]=32000 [max]=64000)

# ---- Messaging System ----
declare -i VERBOSE=1 DEBUG=0

if [[ -t 1 && -t 2 ]]; then
  declare -r RED=$'\033[0;31m' GREEN=$'\033[0;32m' YELLOW=$'\033[0;33m' \
             CYAN=$'\033[0;36m' BOLD=$'\033[1m' NC=$'\033[0m'
else
  declare -r RED='' GREEN='' YELLOW='' CYAN='' BOLD='' NC=''
fi

_msg() { >&2 printf "$SCRIPT_NAME: $1 %s\n" "${@:2}"; }
error()   { _msg "$RED✗$NC" "$@"; }
die()     { (($# < 2)) || error "${@:2}"; exit "${1:-0}"; }
warn()    { _msg "$YELLOW▲$NC" "$@"; }
vecho()   { ((VERBOSE)) || return 0; _msg '' "$@"; }
info()    { ((VERBOSE)) || return 0; _msg "$CYAN◉$NC" "$@"; }
success() { ((VERBOSE)) || return 0; _msg "$GREEN✓$NC" "$@"; }
debug()   { ((DEBUG)) || return 0; _msg "${RED}DEBUG$NC" "$@"; }

noarg()   { (($# > 1)) || die 22 "Option ${1@Q} requires an argument"; }

# ---- Configuration and Globals ----

# Load all conf files (cascade: system first, user overrides system)
# Emit bcs.conf cascade paths (system first, user last).
# Extracted as a helper so tests can override it.
_conf_search_paths() {
  printf '%s\n' \
    /etc/"$SCRIPT_NAME".conf \
    /etc/"$SCRIPT_NAME"/"$SCRIPT_NAME".conf \
    /usr/local/etc/"$SCRIPT_NAME"/"$SCRIPT_NAME".conf \
    "${XDG_CONFIG_HOME:-$HOME/.config}"/"$SCRIPT_NAME"/"$SCRIPT_NAME".conf
}

read_conf() {
  local -- conf_file mode
  local -i loaded=0
  local -a search_paths=()
  readarray -t search_paths < <(_conf_search_paths)
  for conf_file in "${search_paths[@]}"; do
    [[ -f $conf_file ]] || continue
    # The file is sourced as shell, so loose permissions are an RCE surface.
    # Policy:
    #   - world-writable  -> die 13  (no legitimate setup; always compromise risk)
    #   - group-writable  -> warn    (contextual; may be legitimate in admin groups)
    #   - owner-only      -> silent
    # Octal digit without write bit: 0, 1, 4, 5. With write bit: 2, 3, 6, 7.
    # The ?([0-7]) prefix handles modes with setuid/setgid/sticky bits (e.g. 4755).
    mode=$(stat -c '%a' "$conf_file" 2>/dev/null) ||:
    case $mode in
      ''|?([0-7])[0-7][0145][0145])
        : ;; # stat failed, or safe perms
      ?([0-7])[0-7][0-7][2367])
        die 13 "$conf_file: world-writable (mode $mode) -- refusing to source as shell; run: chmod o-w ${conf_file@Q}" ;;
      *)
        warn "$conf_file: group-writable mode $mode -- file is sourced as shell; chmod g-w recommended" ;;
    esac
    #shellcheck source=/dev/null
    source "$conf_file"
    loaded+=1
  done
  ((loaded))
}

# Help functions

show_main_help() {
  cat <<HELP
${BOLD}bcs$NC $VERSION - Bash Coding Standard CLI toolkit

${BOLD}Usage:$NC $SCRIPT_NAME [COMMAND] [OPTIONS]

${BOLD}Commands:$NC
  display     View the standard document (default)
  template    Generate a BCS-compliant script template
  check       AI-powered compliance checking
  codes       List all BCS rule codes
  generate    Regenerate standard from section files
  help        Show help for a command

${BOLD}Global Options:$NC
  -v, --verbose   Verbose output (default)
  -q, --quiet     No verbose output
  -V, --version   Show version $VERSION
  -h, --help      Show this help

${BOLD}Examples:$NC
  $SCRIPT_NAME                           View the standard
  $SCRIPT_NAME template -t complete      Generate a complete template
  $SCRIPT_NAME check myscript.sh         Check script compliance
  $SCRIPT_NAME codes                     List all BCS rule codes
  $SCRIPT_NAME help template             Help for template command

${BOLD}Customisation:$NC
  policy.conf             Override any rule's tier (system/user/repo cascade)
  BCS9800-BCS9899         Reserved namespace for site-local user rules
                          (data/98-user.md, data/98-user.d/*.md)
  See ${BOLD}$SCRIPT_NAME help codes$NC for policy syntax and user-rule format.
HELP
}

show_display_help() {
  cat <<HELP
${BOLD}bcs display$NC - View the Bash Coding Standard

${BOLD}Usage:$NC $SCRIPT_NAME [display] [OPTIONS]

${BOLD}Options:$NC
  -c, --cat       Plain text output (no formatting)
  -f, --file      Show full path to the standard document
  -S, --symlink   Symlink BASH-CODING-STANDARD.md into current directory
  -v, --verbose   Show info messages (${BOLD}default$NC)
  -q, --quiet     Suppress info messages
  -h, --help      Show this help

When stdout is a terminal and md2ansi is available, the standard is
displayed with ANSI formatting piped through less. Otherwise, plain
text output is used.
HELP
}

show_template_help() {
  cat <<HELP
${BOLD}bcs template$NC - Generate BCS-compliant script templates

${BOLD}Usage:$NC $SCRIPT_NAME template [OPTIONS]

${BOLD}Options:$NC
  -t, --type TYPE       Template type (minimal, ${BOLD}basic$NC, complete, library)
                        (default: basic)
  -n, --name NAME       Script name for placeholders
  -d, --desc TEXT       Script description
  -V, --version VER     Version string (default: ${BOLD}1.0.0$NC)
  -o, --output FILE     Output file (default: ${BOLD}stdout$NC)
  -x, --executable      Make output file executable
  -f, --force           Overwrite existing files
  -v, --verbose         Show info messages (${BOLD}default$NC)
  -q, --quiet           Suppress info messages
  -h, --help            Show this help

${BOLD}Template Types:$NC
  minimal     Bare essentials (~16 lines)
  basic       Standard with metadata (~26 lines)
  complete    Full toolkit with all utilities (~119 lines)
  library     Sourceable library pattern (~40 lines)

${BOLD}Examples:$NC
  $SCRIPT_NAME template -t minimal
  $SCRIPT_NAME template -t complete -n deploy -d 'Deploy script' -o deploy.sh -x
  $SCRIPT_NAME template -t library -n auth -o lib-auth.sh
HELP
}

show_check_help() {
  cat <<HELP
${BOLD}bcs check$NC - AI-powered BCS compliance checking

${BOLD}Usage:$NC $SCRIPT_NAME check [OPTIONS] SCRIPT

${BOLD}Options:$NC
  -m, --model MODEL       Quality tier or model name (${BOLD}balanced$NC, fast, thorough, or direct)
  -e, --effort LEVEL      Analysis depth (${BOLD}medium$NC, low, high, max)
  -s, --strict            Treat warnings as violations
  -S, --no-strict         Don't treat warnings as violations (${BOLD}default$NC)
      --shellcheck        Prepend shellcheck --format=json -x output to LLM context (${BOLD}default$NC)
      --no-shellcheck     Skip shellcheck static-analysis context
  -T, --tier TIER         Report only findings at this tier (core|recommended|style)
  -M, --min-tier TIER     Report findings at this tier or higher severity
  -j, --json              Emit findings as a single JSON object on stdout
                          (shellcheck --format=json1-compatible envelope)
  -D, --debug             Announce raw-response dump path on success;
                          dump is always written and auto-announced on failure
  -v, --verbose           Show info messages (${BOLD}default$NC)
  -q, --quiet             Suppress info messages
  -h, --help              Show this help

${BOLD}Raw Response Dump:$NC
  Every API response is saved to \${XDG_STATE_HOME:-~/.local/state}/bcs/last-response.txt
  (or /tmp/bcs-last-response.XXXXXX via mktemp if no state dir). On failure or
  --debug, the path is printed to stderr so you can inspect the raw JSON
  without re-running the check. The Claude Code CLI backend does not dump --
  it returns text directly, not JSON.

${BOLD}Model selection:$NC
  The -m value determines which backend handles the check:

    fast|balanced|thorough        Probe available backends (claude, ollama,
                                  anthropic, openai, google) and use the first
                                  reachable one with that tier's default model.
    claude-*                      Anthropic API (e.g. claude-opus-4-6)
    gemini-*                      Google Gemini API (e.g. gemini-2.5-pro)
    gpt-* | o[0-9]*               OpenAI API (e.g. gpt-5.4, o3-mini)
    claude-code                   Claude Code CLI at the balanced tier
    claude-code:<tier-or-model>   Claude Code CLI with specific tier/model
    (anything else)               Local Ollama (e.g. minimax-m2:cloud)

  Note: Ollama models named 'claude-*', 'gemini-*', 'gpt-*' or 'o[0-9]*' are
  unreachable through -m — rename the local model if you need to target it.

${BOLD}Effort Levels:$NC
  low         Clear violations only (fast, concise)
  medium      Violations and significant warnings
  high        All violations and warnings (thorough)
  max         Exhaustive line-by-line audit

${BOLD}Tiers & Severity:$NC
  Rules carry a ${BOLD}**Tier:**$NC field. The check command maps tier to severity:
    core        -> [ERROR]  (non-zero exit when any [ERROR] found)
    recommended -> [WARN]
    style       -> [WARN]
    disabled    -> not reported

  Use ${BOLD}-T core$NC for CI gates (fail only on core violations) or
  ${BOLD}-M recommended$NC to skip style findings during development.

${BOLD}Policy Overrides:$NC
  Place ${BOLD}policy.conf$NC at any of these cascading locations (later wins):
    /etc/bcs/policy.conf                        (system)
    \${XDG_CONFIG_HOME:-~/.config}/bcs/policy.conf (user)
    .bcs/policy.conf                            (project / repo-local)
  Syntax: ${BOLD}BCS#### = core|recommended|style|disabled$NC
  See ${BOLD}bcs.policy.sample$NC in the BCS source tree for examples.

${BOLD}User Rules:$NC
  Custom rules may be added in BCS9800-BCS9899 space via:
    \$BCS_DATA/98-user.md         (single file)
    \$BCS_DATA/98-user.d/*.md     (drop-in directory)
  Either may be symlinks to user-owned files. User rules are included in the
  generated BASH-CODING-STANDARD.md and respected by bcs check / bcs codes.

${BOLD}Configuration:$NC
  Config files are sourced as bash in cascade order (later overrides earlier):
    /etc/bcs.conf                (system — flat file)
    /etc/bcs/bcs.conf            (system — directory)
    /usr/local/etc/bcs/bcs.conf  (local install)
    ~/.config/bcs/bcs.conf       (user — XDG standard)
  Any file may set a subset of values; unset keys inherit from earlier layers.
  CLI flags override config file settings; config overrides env vars.

${BOLD}Environment / Config Variables:$NC
  BCS_MODEL           Default quality tier or model name (overridden by -m)
  BCS_EFFORT          Default analysis depth (overridden by -e)
  BCS_STRICT          Treat warnings as violations: 0 or 1
  BCS_TIER            Default --tier filter (core|recommended|style)
  BCS_MIN_TIER        Default --min-tier filter (core|recommended|style)
  BCS_DEBUG           Default --debug (0 or 1); announces raw-response dump path
  BCS_JSON            Default --json (0 or 1); structured JSON output on stdout
  BCS_SHELLCHECK      Prepend shellcheck --format=json -x as static-analysis context (0 or 1; default 1)
  BCS_OLLAMA_MODEL    Override Ollama model (supports :cloud tags, e.g. minimax-m2:cloud)
  BCS_ANTHROPIC_MODEL Override Anthropic model selection
  BCS_GOOGLE_MODEL    Override Google model selection
  BCS_OPENAI_MODEL    Override OpenAI model selection
  OLLAMA_HOST         Ollama server address (default: localhost:11434)
  ANTHROPIC_API_KEY   Anthropic API key (for anthropic backend)
  GOOGLE_API_KEY      Google API key (for google backend)
  GEMINI_API_KEY      Alternative Google key (GOOGLE_API_KEY takes priority)
  OPENAI_API_KEY      OpenAI API key (for openai backend)

${BOLD}Inline suppression:$NC
  #bcscheck disable=BCS0606  # Suppress a rule for the next line or block

${BOLD}JSON Output:$NC
  With ${BOLD}-j/--json$NC, stdout contains a single JSON object shaped like:
    { "source": "bcs", "meta": { ... }, "comments": [ ... ] }
  The schema mirrors ${BOLD}shellcheck --format=json1$NC so existing tooling can
  consume findings with minimal adjustment. Info messages still go to stderr
  when verbose. Exit code 5 is returned if the LLM produced invalid JSON
  (the raw response is preserved in \$BCS_RESPONSE_DUMP for inspection).

${BOLD}Examples:$NC
  $SCRIPT_NAME check myscript.sh
  $SCRIPT_NAME check -m minimax-m2:cloud myscript.sh
  $SCRIPT_NAME check --effort high --strict deploy.sh
  $SCRIPT_NAME check -m claude-code:thorough -e max deploy.sh
  $SCRIPT_NAME check -j myscript.sh | jq '.comments[]'
HELP
}

show_codes_help() {
  cat <<HELP
${BOLD}bcs codes$NC - List all BCS rule codes

${BOLD}Usage:$NC $SCRIPT_NAME codes [OPTIONS]

${BOLD}Options:$NC
  -T, --tier TIER         Show only rules at this tier (core|recommended|style|disabled)
  -E, --explain BCS####   Print the full body of a single rule and exit
  -p, --plain             Omit tier decoration (just "BCS#### Title")
  -x, --exclude-disabled  Skip rules that have been disabled via policy.conf
  -h, --help              Show this help

Lists all BCS rule codes and titles extracted from section files and any
user rules (98-user.md, 98-user.d/*.md). Each code is decorated with its
effective tier (default from the rule body, overridden by policy.conf).

Use ${BOLD}--explain$NC to drill into a specific rule after a failed ${BOLD}bcs check$NC run --
prints the full rule body (heading, tier, rationale, examples).

${BOLD}Example Output:$NC
  BCS0101 [core] Strict Mode
  BCS0102 [recommended] Shebang
  BCS0107 [style] Function Organization
  [...]

${BOLD}Explain a rule:$NC
  $SCRIPT_NAME codes -E BCS0606           # Print BCS0606 rule body
  $SCRIPT_NAME codes --explain BCS0101    # Same; long form
HELP
}

show_generate_help() {
  cat <<HELP
${BOLD}bcs generate$NC - Regenerate BASH-CODING-STANDARD.md from section files

${BOLD}Usage:$NC $SCRIPT_NAME generate [OPTIONS]

${BOLD}Options:$NC
  -o, --output FILE   Output file (default: ${BOLD}data/BASH-CODING-STANDARD.md$NC)
  -v, --verbose       Show info messages (${BOLD}default$NC)
  -q, --quiet         Suppress info messages
  -h, --help          Show this help

Concatenates all data/[0-9]*.md section files into a single
BASH-CODING-STANDARD.md document.

User rules in data/98-user.md and data/98-user.d/*.md are spliced into
the output after section 12, before the coda. These files may be symlinks
to user-owned rule files outside the BCS tree.
HELP
}

# ---- Helpers: paths, tiers, policy ----

# Find BASH-CODING-STANDARD.md using FHS-compliant search
_find_bcs_md() {
  local -- path
  for path in "${BCS_SEARCH_PATHS[@]}"; do
    if [[ -f $path/BASH-CODING-STANDARD.md ]]; then
      echo "$path"/BASH-CODING-STANDARD.md
      return 0
    fi
  done
  return 1
}

# Find data directory containing section files
_find_data_dir() {
  local -- path
  for path in "${BCS_SEARCH_PATHS[@]}"; do
    if [[ -d $path ]]; then
      echo "$path"
      return 0
    fi
  done
  return 1
}

# Find md2ansi for formatted output
_find_md2ansi() {
  local -a search_paths=(
    "$SCRIPT_DIR"/examples/md2ansi
    "$SCRIPT_DIR"/lib/md2ansi
  )
  local -- path
  for path in "${search_paths[@]}"; do
    [[ -x $path ]] && { echo "$path"; return 0; } ||:
  done
  command -v md2ansi 2>/dev/null # Falls through to PATH search; non-zero = not found
}

# Tier & policy loading

# Scan section files and populate BCS_TIERS from **Tier:** lines.
# Tier markers live in rule bodies, one line each. Section overview
# headings (BCS##00, e.g. BCS0100) carry no **Tier:** field and are
# silently skipped, leaving BCS_TIERS keyed only by enforceable rules.
_load_tiers() {
  ((_TIERS_LOADED)) && return 0
  local -- data_dir
  data_dir=$(_find_data_dir) || return 1
  local -- current_code='' line
  local -a files=("$data_dir"/[0-9]*.md)
  [[ -d $data_dir/98-user.d ]] && files+=("$data_dir"/98-user.d/*.md) ||:
  while IFS= read -r line; do
    if [[ $line =~ ^##[[:space:]]+(BCS[0-9]+)[[:space:]] ]]; then
      current_code=${BASH_REMATCH[1]}
    elif [[ -n $current_code && $line =~ ^\*\*Tier:\*\*[[:space:]]+([a-z]+) ]]; then
      BCS_TIERS[$current_code]=${BASH_REMATCH[1]}
      current_code=''
    fi
  done < <(cat "${files[@]}" 2>/dev/null ||:)
  _TIERS_LOADED=1
}

# Emit policy.conf cascade paths (system first, project-local last).
# Extracted as a helper so tests can override it.
_policy_search_paths() {
  printf '%s\n' \
    /etc/bcs/policy.conf \
    "${XDG_CONFIG_HOME:-$HOME/.config}"/bcs/policy.conf \
    .bcs/policy.conf
}

# Load policy.conf cascade (system -> user -> project; later wins).
# Policy files are parsed line-by-line -- NEVER sourced as shell.
_load_policy() {
  ((_POLICY_LOADED)) && return 0
  local -a search_paths=()
  readarray -t search_paths < <(_policy_search_paths)
  local -- path line code tier
  local -i lineno
  for path in "${search_paths[@]}"; do
    [[ -f $path && -r $path ]] || continue
    lineno=0
    while IFS= read -r line; do
      lineno+=1
      line=${line%%\#*}                         # strip comments
      line=${line#"${line%%[![:space:]]*}"}     # ltrim
      line=${line%"${line##*[![:space:]]}"}     # rtrim
      [[ -n $line ]] || continue
      if [[ $line =~ ^(BCS[0-9]+)[[:space:]]*=[[:space:]]*([a-z]+)$ ]]; then
        code=${BASH_REMATCH[1]}
        tier=${BASH_REMATCH[2]}
        if [[ " ${VALID_TIERS[*]} " == *" $tier "* ]]; then
          BCS_POLICY[$code]=$tier
        else
          warn "$path:$lineno: invalid tier ${tier@Q} (valid: ${VALID_TIERS[*]})"
        fi
      else
        warn "$path:$lineno: malformed policy line ${line@Q}"
      fi
    done < "$path"
  done
  _POLICY_LOADED=1
}

# Effective tier for a BCS code (policy override wins over default).
# Returns empty string for codes with no tier (section overviews).
_effective_tier() {
  local -- code=$1
  _load_tiers
  _load_policy
  if [[ -n ${BCS_POLICY[$code]:-} ]]; then
    echo "${BCS_POLICY[$code]}"
  else
    echo "${BCS_TIERS[$code]:-}"
  fi
}

# Emit a markdown policy-override block for inclusion in LLM prompts.
# Produces no output when no overrides are defined.
_policy_summary() {
  _load_policy
  ((${#BCS_POLICY[@]})) || return 0
  local -- code
  printf '\n=== POLICY OVERRIDES ===\n'
  printf 'Apply these overrides to the rule tiers defined in the standard:\n'
  while IFS= read -r code; do
    printf -- '- %s: tier = %s\n' "$code" "${BCS_POLICY[$code]}"
  done < <(printf '%s\n' "${!BCS_POLICY[@]}" | sort)
  printf '\nWhen determining severity, use the OVERRIDE tier, not the default.\n'
  printf 'Rules with override tier = "disabled" must NOT be reported.\n'
}

# ---- LLM backends ----

# Dump the raw HTTP response body to $BCS_RESPONSE_DUMP if set.
# cmd_check sets this to a file path so that empty/malformed results
# can be diagnosed without re-running the check.
_dump_response() {
  [[ -n ${BCS_RESPONSE_DUMP:-} ]] || return 0
  printf '%s\n' "$1" > "$BCS_RESPONSE_DUMP" 2>/dev/null ||:
}

# ---- JSON output helpers ----

# Strip optional markdown code fences from an LLM response. Used by JSON
# mode for backends without native JSON-mode parameters (Anthropic Messages
# API, Claude Code CLI). Removes ``` or ```json at start and ``` at end,
# plus surrounding whitespace.
_strip_json_fences() {
  local -- s=$1
  s=${s#"${s%%[![:space:]]*}"}
  s=${s%"${s##*[![:space:]]}"}
  [[ $s != '```'* ]] || { s=${s#'```'}; s=${s#json}; s=${s#$'\n'}; }
  [[ $s != *'```' ]] || { s=${s%'```'}; s=${s%$'\n'}; }
  s=${s#"${s%%[![:space:]]*}"}
  s=${s%"${s##*[![:space:]]}"}
  printf '%s' "$s"
}

# Validate a bare JSON array of findings and wrap it in the top-level
# envelope with meta fields. Emits the final JSON object on stdout.
# Returns non-zero and emits nothing on validation failure.
#
# Arguments:
#   $1 raw LLM response (may include fences)
#   $2 absolute script path
#   $3 backend name
#   $4 model name (resolved)
#   $5 effort level
#   $6 strict (0|1)
#   $7 elapsed seconds
_render_json_output() {
  local -- raw=$1 script_file=$2 backend=$3 model=$4 effort=$5
  local -- strict=$6 elapsed_s=$7
  local -- cleaned arr
  cleaned=$(_strip_json_fences "$raw")
  [[ -n $cleaned ]] || return 1
  # Normalize to a bare array. OpenAI's json_object mode requires the
  # top level be an object, so models often wrap the array as
  # {"findings": [...]} or similar. Accept either form.
  if jq -e 'type == "array"' <<< "$cleaned" &>/dev/null; then
    arr=$cleaned
  elif jq -e 'type == "object"' <<< "$cleaned" &>/dev/null; then
    arr=$(jq -c '(.findings // .comments // .violations // .results // empty)
                 | select(type == "array")' <<< "$cleaned" 2>/dev/null) ||:
    [[ -n $arr ]] || return 1
  else
    return 1
  fi
  # Validate every element has the required finding keys.
  jq -e 'all(.[]; type == "object"
           and has("line") and has("level") and has("bcsCode"))' \
    <<< "$arr" &>/dev/null || return 1
  local -- strict_bool
  ((strict)) && strict_bool=true || strict_bool=false
  jq -n \
    --arg tool 'bcs' \
    --arg version "$VERSION" \
    --arg file "$script_file" \
    --arg backend "$backend" \
    --arg model "$model" \
    --arg effort "$effort" \
    --argjson strict "$strict_bool" \
    --argjson elapsed_s "$elapsed_s" \
    --argjson comments "$arr" \
    '{source: "bcs",
      meta: {tool: $tool, version: $version, file: $file, backend: $backend,
             model: $model, effort: $effort, strict: $strict, elapsed_s: $elapsed_s},
      comments: ($comments | map(. + {file: $file,
                                       column: (.column // 1),
                                       endLine: (.endLine // .line),
                                       endColumn: (.endColumn // 1),
                                       fix: null,
                                       fixSuggestion: (.fixSuggestion // "")}))}' \
    || return 1
}

# Auto-detect available LLM backend (claude → ollama → anthropic → openai → google)
# The Claude Code CLI wins first when available: it runs locally like ollama
# but without needing a model server, and avoids spending API credits on
# unconfigured default invocations.
_detect_backend() {
  command -v claude &>/dev/null && { echo claude; return 0; } ||:
  local -- host=${OLLAMA_HOST:-localhost:11434}
  curl -sf --connect-timeout 2 http://"$host"/api/tags &>/dev/null && { echo ollama; return 0; } ||:
  [[ -n ${ANTHROPIC_API_KEY:-} ]] && { echo anthropic; return 0; } ||:
  [[ -n ${OPENAI_API_KEY:-} ]] && { echo openai; return 0; } ||:
  [[ -n ${GOOGLE_API_KEY:-${GEMINI_API_KEY:-}} ]] && { echo google; return 0; } ||:
  return 1
}

# Sniff backend from a direct model name. Used by cmd_check() whenever the
# user passes a concrete model ID rather than a tier keyword.
# Matches vendor prefixes; anything unrecognised falls back to ollama.
#
# ▲ LOAD-BEARING CASE ORDER ▲
# The `claude-code*` case MUST precede `claude-*`. If reordered, the
# claude-code sentinel routes to the Anthropic Messages API instead of
# the Claude Code CLI -- silently, with no error -- because `claude-*`
# also matches `claude-code`. Do not reorder these cases.
_sniff_backend() {
  case $1 in
    claude|claude:*|claude-code|claude-code:*)
                      echo claude ;;
    claude-*)         echo anthropic ;;
    gemini-*)         echo google ;;
    gpt-*|o[0-9]*)    echo openai ;;
    *)                echo ollama ;;
  esac
}

# Run shellcheck over the script-under-check and return its JSON report.
# Never aborts the caller: missing binary or parse failure emits empty output
# so cmd_check() can proceed without static-analysis context.
_run_shellcheck() {
  local -- file=$1 json=''
  local -i rc=0
  command -v shellcheck &>/dev/null || {
    info 'shellcheck not in PATH; skipping static-analysis context'
    return 0
  }
  # exit 0 = clean, 1 = findings present (both fine); >=2 = parse failure.
  # Capture rc via fallback so set -e does not trip on the expected exit 1.
  json=$(shellcheck --format=json -x -- "$file" 2>/dev/null) || rc=$?
  ((rc <= 1)) || { warn "shellcheck failed (exit $rc); continuing without context"; return 0; }
  printf '%s\n' "$json"
}

# Wrap a shellcheck JSON report in a markdown block suitable for prepending
# to the LLM user prompt. Returns empty string when the report is empty or
# `[]` so clean scripts never contribute an empty section to the prompt.
_render_shellcheck_block() {
  local -- json=$1
  [[ -z $json || $json == '[]' ]] && return 0
  cat <<MD
## Static analysis context (shellcheck --format=json -x)

The following findings come from a deterministic static analyser. Use
them as supporting context for your BCS review; do not re-emit them as
BCS findings unless they map to a specific BCS rule.

\`\`\`json
$json
\`\`\`
MD
}

# LLM backend: Anthropic Messages API
_llm_anthropic() {
  local -- model=$1 effort=$2 sys=$3 usr=$4
  [[ -n ${ANTHROPIC_API_KEY:-} ]] || die 18 'ANTHROPIC_API_KEY not set'
  local -- api_model=${BCS_ANTHROPIC_MODEL:-${ANTHROPIC_MODELS[$model]:-$model}}
  local -i max_tokens=${EFFORT_TOKENS[$effort]}

  # Anthropic Messages API has no native JSON-mode flag; rely on prompt
  # discipline plus _strip_json_fences fallback applied by cmd_check.
  local -- payload
  payload=$(jq -n \
    --arg model "$api_model" \
    --argjson max_tokens "$max_tokens" \
    --arg system "$sys" \
    --arg user "$usr" \
    '{model: $model, max_tokens: $max_tokens, system: $system,
      messages: [{role: "user", content: $user}]}') || die 1 'Failed to build JSON payload'

  local -- raw body
  local -i http_code
  raw=$(curl -s --max-time 300 -w $'\n%{http_code}' \
    -H 'Content-Type: application/json' \
    -H 'x-api-key: '"$ANTHROPIC_API_KEY" \
    -H 'anthropic-version: 2023-06-01' \
    -d @- \
    'https://api.anthropic.com/v1/messages' <<< "$payload") || die 5 'Anthropic API connection failed'
  http_code=${raw##*$'\n'}
  body=${raw%$'\n'"$http_code"}
  _dump_response "$body"
  if ! ((http_code >= 200 && http_code < 300)); then
    local -- errmsg
    errmsg=$(jq -r '.error.message // empty' <<< "$body" 2>/dev/null) ||:
    die 5 "Anthropic API error (HTTP $http_code)" ${errmsg:+"$errmsg"}
  fi

  jq -r '.content[0].text // empty' <<< "$body"
  echo "___TOKENS___ $(jq -r '"in=\(.usage.input_tokens // 0) out=\(.usage.output_tokens // 0)"' <<< "$body")"
}

# LLM backend: Ollama chat API
_llm_ollama() {
  local -- model=$1 effort=$2 sys=$3 usr=$4
  local -- ollama_model=${BCS_OLLAMA_MODEL:-${OLLAMA_MODELS[$model]:-$model}}
  local -- ollama_host=${OLLAMA_HOST:-localhost:11434}
  local -i num_predict=${EFFORT_TOKENS[$effort]}

  # Native JSON mode via "format": "json" (supported by qwen2.5+, llama3.1+,
  # gemma2+). When BCS_JSON_MODE=1, forces the model to emit only valid JSON.
  local -- payload
  if ((${BCS_JSON_MODE:-0})); then
    payload=$(jq -n \
      --arg model "$ollama_model" \
      --argjson num_predict "$num_predict" \
      --arg system "$sys" \
      --arg user "$usr" \
      '{model: $model, stream: false, format: "json",
        options: {num_predict: $num_predict},
        messages: [{role: "system", content: $system}, {role: "user", content: $user}]}') \
      || die 1 'Failed to build JSON payload'
  else
    payload=$(jq -n \
      --arg model "$ollama_model" \
      --argjson num_predict "$num_predict" \
      --arg system "$sys" \
      --arg user "$usr" \
      '{model: $model, stream: false, options: {num_predict: $num_predict},
        messages: [{role: "system", content: $system}, {role: "user", content: $user}]}') \
      || die 1 'Failed to build JSON payload'
  fi

  local -- raw body
  local -i http_code
  raw=$(curl -s --max-time 600 -w $'\n%{http_code}' \
    -H 'Content-Type: application/json' \
    -d @- \
    "http://$ollama_host/api/chat" <<< "$payload") || die 5 'Ollama API connection failed'
  http_code=${raw##*$'\n'}
  body=${raw%$'\n'"$http_code"}
  _dump_response "$body"
  if ! ((http_code >= 200 && http_code < 300)); then
    local -- errmsg
    errmsg=$(jq -r '.error // empty' <<< "$body" 2>/dev/null) ||:
    die 5 "Ollama API error (HTTP $http_code)" ${errmsg:+"$errmsg"}
  fi

  local -- content
  content=$(jq -r '.message.content // empty' <<< "$body")
  # Strip <think>...</think> tags from qwen3 models
  [[ $content != *'</think>'* ]] || { content=${content##*</think>}; content=${content#$'\n'}; }
  echo "$content"
  echo "___TOKENS___ $(jq -r '"in=\(.prompt_eval_count // 0) out=\(.eval_count // 0)"' <<< "$body")"
}

# LLM backend: OpenAI chat completions API
_llm_openai() {
  local -- model=$1 effort=$2 sys=$3 usr=$4
  [[ -n ${OPENAI_API_KEY:-} ]] || die 18 'OPENAI_API_KEY not set'
  local -- api_model=${BCS_OPENAI_MODEL:-${OPENAI_MODELS[$model]:-$model}}
  local -i max_tokens=${EFFORT_TOKENS[$effort]}

  # Native JSON mode via response_format:{type:"json_object"} (GPT-4+).
  # Forces the model to emit only valid JSON. System/user prompt must
  # mention "JSON" somewhere -- our JSON-mode prompt satisfies that.
  local -- payload
  if ((${BCS_JSON_MODE:-0})); then
    payload=$(jq -n \
      --arg model "$api_model" \
      --argjson max_tokens "$max_tokens" \
      --arg system "$sys" \
      --arg user "$usr" \
      '{model: $model, max_completion_tokens: $max_tokens,
        response_format: {type: "json_object"},
        messages: [{role: "system", content: $system}, {role: "user", content: $user}]}') \
      || die 1 'Failed to build JSON payload'
  else
    payload=$(jq -n \
      --arg model "$api_model" \
      --argjson max_tokens "$max_tokens" \
      --arg system "$sys" \
      --arg user "$usr" \
      '{model: $model, max_completion_tokens: $max_tokens,
        messages: [{role: "system", content: $system}, {role: "user", content: $user}]}') \
      || die 1 'Failed to build JSON payload'
  fi

  local -- raw body
  local -i http_code
  raw=$(curl -s --max-time 300 -w $'\n%{http_code}' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer '"$OPENAI_API_KEY" \
    -d @- \
    'https://api.openai.com/v1/chat/completions' <<< "$payload") || die 5 'OpenAI API connection failed'
  http_code=${raw##*$'\n'}
  body=${raw%$'\n'"$http_code"}
  _dump_response "$body"
  if ! ((http_code >= 200 && http_code < 300)); then
    local -- errmsg
    errmsg=$(jq -r '.error.message // empty' <<< "$body" 2>/dev/null) ||:
    die 5 "OpenAI API error (HTTP $http_code)" ${errmsg:+"$errmsg"}
  fi

  jq -r '.choices[0].message.content // empty' <<< "$body"
  echo "___TOKENS___ $(jq -r '"in=\(.usage.prompt_tokens // 0) out=\(.usage.completion_tokens // 0)"' <<< "$body")"
}

# LLM backend: Google Gemini API
_llm_google() {
  local -- model=$1 effort=$2 sys=$3 usr=$4
  local -- api_key=${GOOGLE_API_KEY:-${GEMINI_API_KEY:-}}
  [[ -n $api_key ]] || die 18 'GOOGLE_API_KEY or GEMINI_API_KEY not set'
  local -- api_model=${BCS_GOOGLE_MODEL:-${GOOGLE_MODELS[$model]:-$model}}
  local -i max_tokens=${EFFORT_TOKENS[$effort]}

  # Native JSON mode via generationConfig.response_mime_type. Gemini 1.5+
  # supports "application/json" to force a structured-output response.
  local -- payload
  if ((${BCS_JSON_MODE:-0})); then
    payload=$(jq -n \
      --argjson max_tokens "$max_tokens" \
      --arg system "$sys" \
      --arg user "$usr" \
      '{systemInstruction: {parts: [{text: $system}]},
        contents: [{role: "user", parts: [{text: $user}]}],
        generationConfig: {maxOutputTokens: $max_tokens,
                           response_mime_type: "application/json"}}') \
      || die 1 'Failed to build JSON payload'
  else
    payload=$(jq -n \
      --argjson max_tokens "$max_tokens" \
      --arg system "$sys" \
      --arg user "$usr" \
      '{systemInstruction: {parts: [{text: $system}]},
        contents: [{role: "user", parts: [{text: $user}]}],
        generationConfig: {maxOutputTokens: $max_tokens}}') \
      || die 1 'Failed to build JSON payload'
  fi

  local -- url=https://generativelanguage.googleapis.com/v1beta/models/"$api_model":generateContent
  local -- raw body
  local -i http_code
  raw=$(curl -s --max-time 300 -w $'\n%{http_code}' \
    -H 'Content-Type: application/json' \
    -H 'x-goog-api-key: '"$api_key" \
    -d @- \
    "$url" <<< "$payload") || die 5 'Google API connection failed'
  http_code=${raw##*$'\n'}
  body=${raw%$'\n'"$http_code"}
  _dump_response "$body"
  if ! ((http_code >= 200 && http_code < 300)); then
    local -- errmsg
    errmsg=$(jq -r '.error.message // empty' <<< "$body" 2>/dev/null) ||:
    die 5 "Google API error (HTTP $http_code)" ${errmsg:+"$errmsg"}
  fi

  jq -r '.candidates[0].content.parts[0].text // empty' <<< "$body"
  local -- tkn
  tkn=$(jq -r \
    '"in=\(.usageMetadata.promptTokenCount // 0) out=\(.usageMetadata.candidatesTokenCount // 0)"' \
    <<< "$body")
  echo "___TOKENS___ $tkn"
}

# LLM backend: Claude Code CLI. Builds the prompt with @file references
# (resolved by the CLI itself) rather than inlining the standard or script,
# and runs `claude -p` from a clean temp dir with bypassPermissions.
_llm_claude_cli() {
  local -- model=$1 effort=$2 bcs_file=$3 script_file=$4
  local -i strict=$5
  local -- tier_instr=${6:-} filter_instr=${7:-} policy_text=${8:-}
  local -- shellcheck_block=${9:-}
  command -v claude &>/dev/null || die 18 'Claude CLI required for claude backend'

  model=${BCS_ANTHROPIC_MODEL:-${ANTHROPIC_MODELS[$model]:-$model}}

  local -- prompt
  if ((${BCS_JSON_MODE:-0})); then
    prompt="You are a Bash script compliance validator emitting structured JSON output.

Analyze @$script_file against the Bash Coding Standard defined in @$bcs_file.

$tier_instr

Level mapping for JSON output:
- Tier \"core\"        -> level \"error\"
- Tier \"recommended\" -> level \"warning\"
- Tier \"style\"       -> level \"warning\"
- Tier \"disabled\"    -> OMIT entirely

Respect inline suppression: \`#bcscheck disable=BCSxxxx\` exempts the next line/block.

Return a JSON array of finding objects. Each finding object has this shape:
  {
    \"line\": <1-indexed integer>,
    \"endLine\": <1-indexed integer, same as line if single-line>,
    \"level\": \"error\" | \"warning\" | \"info\",
    \"code\": <integer, BCS code without the BCS prefix (e.g. 101 for BCS0101)>,
    \"bcsCode\": \"BCS####\",
    \"tier\": \"core\" | \"recommended\" | \"style\",
    \"message\": \"<one sentence describing the violation>\",
    \"fixSuggestion\": \"<human-readable remediation advice>\"
  }

Example of a valid response (one finding):
[
  {
    \"line\": 4,
    \"endLine\": 4,
    \"level\": \"error\",
    \"code\": 101,
    \"bcsCode\": \"BCS0101\",
    \"tier\": \"core\",
    \"message\": \"Missing set -euo pipefail strict mode declaration.\",
    \"fixSuggestion\": \"Add 'set -euo pipefail' and 'shopt -s inherit_errexit' right after the shebang.\"
  }
]

Return ONLY the JSON array. No markdown code fences. No commentary. No preamble.
If there are no findings, return []."
  else
    prompt="You are a Bash script compliance validator.

Analyze @$script_file against the Bash Coding Standard defined in @$bcs_file.

$tier_instr

For each finding, report:
- The BCS code (e.g., BCS0101)
- The rule's tier (core, recommended, style)
- Severity: [ERROR] for core-tier violations, [WARN] for recommended/style
- The specific line(s) affected
- What is wrong and how to fix it

At the end, provide a summary table: | BCS Code | Tier | Severity | Line(s) | Description |.

Respect inline suppression: eg, #bcscheck disable=BCS0101 exempts the next line/block."
  fi

  [[ -z $filter_instr ]] || prompt+=$'\n\n'"$filter_instr"
  [[ -z $policy_text ]] || prompt+=$'\n'"$policy_text"
  [[ -z $shellcheck_block ]] || prompt+=$'\n\n'"$shellcheck_block"
  if ((strict)); then
    if ((${BCS_JSON_MODE:-0})); then
      prompt+=$'\n\nSTRICT MODE: Map recommended/style violations to level "error" instead of "warning".'
    else
      prompt+=$'\n\nSTRICT MODE: Treat all warnings as [ERROR].'
    fi
  fi

  # cd to clean temp dir -- prevents claude from loading local CLAUDE.md
  local -- check_dir
  check_dir=$(mktemp -d -t 'bcs-XXXXX') || die 1 'Failed to create temp dir'
  #bcscheck disable=BCS0603
  #shellcheck disable=SC2064
  trap "cd '$PWD' 2>/dev/null; rm -rf '$check_dir'" RETURN
  cd "$check_dir"
  [[ ! -d /run/user/"$EUID" ]] || declare -x TMPDIR=/run/user/"$EUID"

  local -a claude_args=(--model "$model" --permission-mode bypassPermissions)
  [[ -z $effort ]] || claude_args+=(--effort "$effort")

  #shellcheck disable=SC1007
  CLAUDECODE= claude "${claude_args[@]}" -p "$prompt" 2>/dev/null
}

# ---- Subcommands ----

# Subcommand: display

cmd_display() {
  local -i force_cat=0
  local -- bcs_file

  while (($#)); do case $1 in
    -c|--cat)     force_cat=1 ;;
    -f|--file)    _find_bcs_md || die 3 'BASH-CODING-STANDARD.md not found'; return 0 ;;
    -S|--symlink) bcs_file=$(_find_bcs_md) || die 3 'BASH-CODING-STANDARD.md not found'
                  ln -sf "$bcs_file" .
                  info "Symlinked BASH-CODING-STANDARD.md → $bcs_file"
                  return 0
                  ;;
    -v|--verbose) VERBOSE=1 ;;
    -q|--quiet)   VERBOSE=0 ;;
    -h|--help)    show_display_help; return 0 ;;
    --)           shift; break ;;
    -[cfSvqh]?*)  set -- "${1:0:2}" "-${1:2}" "${@:2}"; continue ;;
    -*)           die 22 "Invalid option ${1@Q}" ;;
    *)            die 2 "Unexpected argument ${1@Q}" ;;
  esac; shift; done

  bcs_file=$(_find_bcs_md) || die 3 'BASH-CODING-STANDARD.md not found'

  if ((force_cat)); then
    cat -- "$bcs_file"
    return 0
  fi

  # Try md2ansi for formatted output if terminal
  if [[ -t 1 ]]; then
    local -- md2ansi_cmd
    md2ansi_cmd=$(_find_md2ansi) || md2ansi_cmd=''
    if [[ -n $md2ansi_cmd ]]; then
      "$md2ansi_cmd" -- "$bcs_file" | less -FXRS
      return 0
    fi
  fi

  # Fallback to plain cat
  cat -- "$bcs_file"
}

# Subcommand: template

cmd_template() {
  local -- template_type=basic
  local -- script_name=''
  local -- description='Script description'
  local -- version='1.0.0'
  local -- output_file=''
  local -i make_executable=0
  local -i force_overwrite=0

  while (($#)); do case $1 in
    -t|--type)       noarg "$@"; shift; template_type=$1
                     [[ " ${VALID_TEMPLATES[*]} " == *" $template_type "* ]] || \
                       die 22 "Invalid template type ${template_type@Q} (valid: minimal, basic, complete, library)"
                     ;;
    -n|--name)       noarg "$@"; shift; script_name=$1 ;;
    -d|--desc)       noarg "$@"; shift; description=$1 ;;
    #bcscheck disable=BCS0806
    -V|--version)    noarg "$@"; shift; version=$1 ;;
    -o|--output)     noarg "$@"; shift; output_file=$1 ;;
    -x|--executable) make_executable=1 ;;
    -f|--force)      force_overwrite=1 ;;
    -v|--verbose)    VERBOSE=1 ;;
    -q|--quiet)      VERBOSE=0 ;;
    -h|--help)       show_template_help; return 0 ;;
    --)              shift; break ;;
    -[tndVoxfvqh]?*) set -- "${1:0:2}" "-${1:2}" "${@:2}"; continue ;;
    -*)              die 22 "Invalid option ${1@Q}" ;;
    *)               die 2 "Unexpected argument ${1@Q}" ;;
  esac; shift; done

  # Determine script name from output file if not specified
  if [[ -z $script_name ]]; then
    if [[ -n $output_file ]]; then
      script_name=${output_file##*/}; script_name=${script_name%.sh}
    else
      script_name=script
    fi
  fi

  # Find template file
  local -- data_dir
  data_dir=$(_find_data_dir) || die 3 'Data directory not found'
  local -- template_file="${data_dir%/data}"/examples/templates/"$template_type".sh.template
  [[ -f $template_file ]] || die 3 "Template not found ${template_file@Q}"

  # Check output file
  if [[ -n $output_file && -f $output_file ]] && ! ((force_overwrite)); then
    die 22 "Output file already exists ${output_file@Q} (use -f to overwrite)"
  fi

  # Read and substitute placeholders
  local -- content
  content=$(< "$template_file")
  content=${content//\{\{NAME\}\}/$script_name}
  content=${content//\{\{DESCRIPTION\}\}/$description}
  content=${content//\{\{VERSION\}\}/$version}

  # Write output
  if [[ -n $output_file ]]; then
    printf '%s\n' "$content" > "$output_file"
    info "Generated $template_type template ${output_file@Q}"
    if ((make_executable)); then
      chmod +x "$output_file"
      info "Made executable ${output_file@Q}"
    fi
  else
    printf '%s\n' "$content"
  fi
}

# Subcommand: check

cmd_check() {
  local -- script_file='' model=${BCS_MODEL:-balanced} effort=${BCS_EFFORT:-medium}
  local -i strict=${BCS_STRICT:-0} debug=${BCS_DEBUG:-0} json_output=${BCS_JSON:-0}
  local -i shellcheck_ctx=${BCS_SHELLCHECK:-1}
  local -ar onoff=(off on)
  local -- backend=''
  local -- tier_filter=${BCS_TIER:-} min_tier_filter=${BCS_MIN_TIER:-}

  while (($#)); do case $1 in
    -m|--model)     noarg "$@"; shift; model=$1 ;;
    -e|--effort)    noarg "$@"; shift; effort=$1
                    [[ " ${VALID_EFFORTS[*]} " == *" $effort "* ]] || die 22 "Invalid effort ${effort@Q}"
                    ;;
    -s|--strict)    strict=1 ;;
    -S|--no-strict) strict=0 ;;
    --shellcheck)    shellcheck_ctx=1 ;;
    --no-shellcheck) shellcheck_ctx=0 ;;
    -T|--tier)      noarg "$@"; shift; tier_filter=$1
                    [[ " ${VALID_TIER_FILTERS[*]} " == *" $tier_filter "* ]] \
                      || die 22 "Invalid tier ${tier_filter@Q} (valid: ${VALID_TIER_FILTERS[*]})"
                    ;;
    -M|--min-tier)  noarg "$@"; shift; min_tier_filter=$1
                    [[ " ${VALID_TIER_FILTERS[*]} " == *" $min_tier_filter "* ]] \
                      || die 22 "Invalid tier ${min_tier_filter@Q} (valid: ${VALID_TIER_FILTERS[*]})"
                    ;;
    -j|--json)      json_output=1 ;;
    -D|--debug)     debug=1 ;;
    -v|--verbose)   VERBOSE=1 ;;
    -q|--quiet)     VERBOSE=0 ;;
    -h|--help)      show_check_help; return 0 ;;
    --)             shift; [[ -n ${1:-} ]] && { script_file=$1; shift; }; break ;;
    -[mesSTMDvqhj]?*) set -- "${1:0:2}" "-${1:2}" "${@:2}"; continue ;;
    -*)             die 22 "Invalid option ${1@Q}" ;;
    *)              [[ -z $script_file ]] || die 2 'Only one script file allowed'
                    script_file=$1
                    ;;
  esac; shift; done

  [[ -n $script_file ]] || die 2 'No script file specified'
  [[ -f $script_file ]] || die 3 "Script not found ${script_file@Q}"
  [[ -r $script_file ]] || die 13 "Cannot read ${script_file@Q}"
  script_file=$(realpath -e -- "$script_file")

  # Static-analysis context: run shellcheck up front so its JSON report can
  # be prepended to the LLM prompt. Silently skipped when disabled, when the
  # binary is missing, or when shellcheck fails to parse the script.
  local -- shellcheck_block=''
  if ((shellcheck_ctx)); then
    local -- sc_json=''
    sc_json=$(_run_shellcheck "$script_file") ||:
    shellcheck_block=$(_render_shellcheck_block "$sc_json") ||:
  fi

  # Resolve backend from model name alone.
  #
  #   fast|balanced|thorough    -> probe available backends
  #   claude-code[:tier|model]  -> Claude Code CLI; strip sentinel prefix
  #   anything else             -> sniff vendor prefix
  #
  if [[ $model == @(fast|balanced|thorough) ]]; then
    backend=$(_detect_backend) \
      || die 18 'No LLM backend available (start Ollama, set ANTHROPIC_API_KEY/OPENAI_API_KEY, or install claude CLI)'
  else
    backend=$(_sniff_backend "$model")
    # Strip the claude-code sentinel so _llm_claude_cli sees a resolvable
    # tier keyword or direct model ID, not the sentinel itself.
    case $model in
      claude-code|claude-code:)  model=balanced ;;
      claude-code:*)             model=${model#claude-code:} ;;
    esac
    info "Backend ${backend@Q} inferred from model ${model@Q}"
  fi

  # Verify curl+jq+nl for API backends. `nl` produces the numbered-line
  # user message; without it the API receives an empty prompt and returns
  # confused output -- the failure surfaces at the API layer, not the
  # actual cause.
  if [[ $backend != claude ]]; then
    local -- dep
    for dep in curl jq nl; do
      command -v "$dep" &>/dev/null || die 18 "Required tool: ${dep@Q}"
    done
  fi

  # Find the standard document
  local -- bcs_file
  bcs_file=$(_find_bcs_md) || die 3 'BASH-CODING-STANDARD.md not found'

  local -- check_cmd="bcs check --model ${model@Q} --effort ${effort@Q}"
  check_cmd+=" --strict ${onoff[strict]@Q} ${script_file@Q}"
  ((!VERBOSE)) || info "Checking ${script_file@Q} against BCS (backend=$backend)..." "$check_cmd"

  # Set up raw-response dump path. Always written; only announced on
  # failure or when --debug is set. Lets users diagnose empty/malformed
  # responses without re-running the check.
  local -- state_dir=${XDG_STATE_HOME:-$HOME/.local/state}/bcs
  mkdir -p "$state_dir" 2>/dev/null ||:
  if [[ -d $state_dir && -w $state_dir ]]; then
    export BCS_RESPONSE_DUMP="$state_dir"/last-response.txt
  else
    BCS_RESPONSE_DUMP=$(mktemp /tmp/bcs-last-response.XXXXXX) \
      || die 1 'Failed to create response dump file in /tmp'
    export BCS_RESPONSE_DUMP
  fi

  local -- result
  local -i exit_code=0
  SECONDS=0

  # Build tier/severity instructions once -- reused by both backends
  local -- tier_instr='' filter_instr='' policy_text
  tier_instr='Severity mapping (use the **Tier:** field on each rule):
- **Tier: core** violation -> label as [ERROR]
- **Tier: recommended** or **Tier: style** violation -> label as [WARN]
- **Tier: disabled** rules -> NEVER report; skip entirely
- Rules with no **Tier:** field (section overviews) -> not enforceable; do not report'

  if [[ -n $tier_filter ]]; then
    filter_instr="FILTER: Only report findings for rules at tier ${tier_filter@Q}. Omit all others."
  elif [[ -n $min_tier_filter ]]; then
    case $min_tier_filter in
      core)        filter_instr="FILTER: Only report findings for rules at tier 'core'. Omit 'recommended' and 'style'." ;;
      recommended) filter_instr="FILTER: Only report findings for rules at tier 'core' or 'recommended'. Omit 'style'." ;;
      style)       : ;;  # report all
      *)           : ;;  # unreachable: validated at -M parse time
    esac
  fi

  policy_text=$(_policy_summary)

  # Export JSON-mode switch for backends. Each _llm_* function reads this
  # env var to flip native JSON-mode payload fields (OpenAI response_format,
  # Google response_mime_type, Ollama format) and the claude-cli prompt
  # template. Backends without native JSON mode (Anthropic, Claude CLI)
  # rely on prompt discipline plus _strip_json_fences as a fallback.
  export BCS_JSON_MODE=$json_output

  if [[ $backend == claude ]]; then
    result=$(_llm_claude_cli "$model" "$effort" "$bcs_file" "$script_file" "$strict" \
               "$tier_instr" "$filter_instr" "$policy_text" "$shellcheck_block") || exit_code=$?
  else
    # Build prompts for API backends
    local -- sys_prompt usr_prompt numbered_script effort_guidance
    sys_prompt=$(< "$bcs_file")
    [[ -z $policy_text ]] || sys_prompt+=$'\n'"$policy_text"

    # Prepend line numbers so the model can reference lines accurately
    numbered_script=$(nl -ba -w4 -s': ' -- "$script_file")

    # Effort-level-specific guidance
    case $effort in
      low)    effort_guidance='Report only clear VIOLATION findings. Be concise.' ;;
      medium) effort_guidance='Report VIOLATIONs and significant WARNINGs.' ;;
      high)   effort_guidance='Report all VIOLATIONs and WARNINGs. Be thorough.' ;;
      max)    effort_guidance='Exhaustive line-by-line audit. Report every finding.' ;;
      *)      die 1 "Unexpected effort: ${effort@Q}" ;;
    esac

    if ((json_output)); then
      #bcscheck disable=BCS1201 — LLM prompt prose; wrapping degrades instruction quality
      usr_prompt="Analyze the following numbered script against the Bash Coding Standard in your system context.

$tier_instr

Level mapping for JSON output:
- Tier \"core\"        -> level \"error\"
- Tier \"recommended\" -> level \"warning\"
- Tier \"style\"       -> level \"warning\"
- Tier \"disabled\"    -> OMIT entirely

Rules:
- Only report actual deviations. Do NOT report passing rules or retracted findings.
- Only report findings about the script content provided. Do NOT assume project structure.
- BCS0405 precedence: Do NOT flag missing reference-template code (BCS0703, BCS0706, BCS0701) if the script does not use it.
- BCS0606: \`((cond)) && action ||:\` with \`||:\` present is NOT a violation.
- Inline suppression: \`#bcscheck disable=BCSxxxx\` suppresses the next command or block.
- Line numbers are provided -- reference them exactly.

$effort_guidance"
      [[ -z $filter_instr ]] || usr_prompt+=$'\n\n'"$filter_instr"
      ((strict)) && usr_prompt+=$'\n\nSTRICT MODE: Map recommended/style violations to level \"error\" instead of \"warning\".' ||:
      usr_prompt+="

Return a JSON array of finding objects. Each finding object has this shape:
  {
    \"line\": <1-indexed integer>,
    \"endLine\": <1-indexed integer, same as line if single-line>,
    \"level\": \"error\" | \"warning\" | \"info\",
    \"code\": <integer, BCS code without the BCS prefix (e.g. 101 for BCS0101)>,
    \"bcsCode\": \"BCS####\",
    \"tier\": \"core\" | \"recommended\" | \"style\",
    \"message\": \"<one sentence describing the violation>\",
    \"fixSuggestion\": \"<human-readable remediation advice>\"
  }

Example of a valid response (one finding):
[
  {
    \"line\": 4,
    \"endLine\": 4,
    \"level\": \"error\",
    \"code\": 101,
    \"bcsCode\": \"BCS0101\",
    \"tier\": \"core\",
    \"message\": \"Missing set -euo pipefail strict mode declaration.\",
    \"fixSuggestion\": \"Add 'set -euo pipefail' and 'shopt -s inherit_errexit' right after the shebang.\"
  }
]

Return ONLY the JSON array. No markdown code fences. No commentary. No preamble.
If there are no findings, return []."
      [[ -z $shellcheck_block ]] || usr_prompt+=$'\n\n'"$shellcheck_block"
      usr_prompt+="

--- Script to analyze ---
$numbered_script"
    else
      #bcscheck disable=BCS1201 — LLM prompt prose; wrapping degrades instruction quality
      usr_prompt="Analyze the following numbered script against the Bash Coding Standard in your system context.

$tier_instr

Rules:
- Only report actual deviations. Do NOT report passing rules, observations, or findings you then retract. If analysis shows no violation, omit it entirely.
- Only report findings about the script content provided. Do NOT assume anything about project structure, files, or resources you cannot see.
- BCS0405 precedence: Do NOT flag missing functions, variables, or colors from reference templates (BCS0703, BCS0706, BCS0701) if the script does not use them. Unused code must be removed, not added.
- BCS0606: \`((cond)) && action ||:\` with \`||:\` present is acceptable for flag-guarded actions — it is NOT a violation. Only flag if \`||:\` is missing entirely.
- Inline suppression: \`#bcscheck disable=BCSxxxx\` suppresses the next command or block (same scope as shellcheck directives). Do NOT report the suppressed rule for that scope.
- Line numbers are provided -- reference them exactly.

$effort_guidance"
      [[ -z $filter_instr ]] || usr_prompt+=$'\n\n'"$filter_instr"
      ((strict)) && usr_prompt+=$'\n\nSTRICT MODE: Treat all WARNINGs as VIOLATIONs (label as [ERROR]).' ||:
      usr_prompt+="

Format each finding as: [ERROR|WARN] BCSxxxx line N: description, then a fix recommendation.
End with a summary table: | BCS Code | Tier | Severity | Line(s) | Description |"
      [[ -z $shellcheck_block ]] || usr_prompt+=$'\n\n'"$shellcheck_block"
      usr_prompt+="

--- Script to analyze ---
$numbered_script"
    fi

    case $backend in
      anthropic) result=$(_llm_anthropic "$model" "$effort" "$sys_prompt" "$usr_prompt") || exit_code=$? ;;
      google)    result=$(_llm_google "$model" "$effort" "$sys_prompt" "$usr_prompt") || exit_code=$? ;;
      ollama)    result=$(_llm_ollama "$model" "$effort" "$sys_prompt" "$usr_prompt") || exit_code=$? ;;
      openai)    result=$(_llm_openai "$model" "$effort" "$sys_prompt" "$usr_prompt") || exit_code=$? ;;
      *)         die 1 "Unexpected backend: ${backend@Q}" ;;
    esac
  fi

  # Extract token sentinel from result (API backends only)
  local -- _llm_tokens=''
  if [[ $result == *'___TOKENS___ '* ]]; then
    _llm_tokens=${result##*___TOKENS___ }
    result=${result%$'\n___TOKENS___ '*}
  fi

  # Build diagnostic message list. Claude CLI backend does not emit token
  # counts, so suppress the Tokens line entirely when empty or all-zero --
  # avoid printing noise like "Tokens: " or "Tokens: in=0 out=0".
  local -a diag_msgs=()
  if [[ -n $_llm_tokens && $_llm_tokens != 'in=0 out=0' ]]; then
    diag_msgs+=("Tokens: $_llm_tokens")
  fi
  diag_msgs+=("Elapsed: ${SECONDS}s")

  ((!VERBOSE)) || info "${diag_msgs[@]}"

  # Output + severity-based exit
  if ((json_output)); then
    # JSON mode: validate raw array, wrap with envelope, emit on stdout.
    # On validation failure, preserve the raw response in the dump file
    # and exit 5 so CI can surface the problem without re-running.
    if [[ -n $result ]]; then
      local -- json_doc
      if json_doc=$(_render_json_output "$result" "$script_file" "$backend" \
                      "$model" "$effort" "$strict" "$SECONDS" 2>/dev/null); then
        echo "$json_doc"
        if ((exit_code == 0)) && \
           jq -e '.comments[]? | select(.level == "error")' \
               <<< "$json_doc" &>/dev/null; then
          exit_code=1
        fi
      else
        warn 'LLM returned invalid JSON (raw response preserved)'
        # Claude CLI does not dump automatically; overwrite the dump file
        # with the raw result so --debug can surface it uniformly.
        if [[ $backend == claude && -n ${BCS_RESPONSE_DUMP:-} ]]; then
          printf '%s\n' "$result" > "$BCS_RESPONSE_DUMP" 2>/dev/null ||:
        fi
        exit_code=5
      fi
    fi
  else
    [[ -z $result ]] || echo "$result"
    # Severity-based exit: any [ERROR] finding promotes exit code to 1
    if ((exit_code == 0)) && [[ $result == *'[ERROR]'* ]]; then
      exit_code=1
    fi
  fi

  # Diagnostics on failure or debug:
  #   - API backend failed, or
  #   - empty result with non-claude backend (likely parse failure), or
  #   - --debug was requested
  # In these cases, surface the saved raw-response path so the user can
  # diagnose without re-running. Non-API (claude-code CLI) backend does
  # not dump -- it returns text directly, not JSON.
  local -i dump_show=0
  if ((debug)); then
    dump_show=1
  elif ((exit_code != 0)); then
    dump_show=1
  elif [[ -z $result && $backend != claude ]]; then
    dump_show=1
    warn 'LLM returned empty result'
    exit_code=5
  fi
  if ((dump_show)); then
    # Re-emit diagnostics on failure even when non-verbose, plus exit code
    ((VERBOSE)) || >&2 info "${diag_msgs[@]}"
    >&2 info "Exit: $exit_code"
    if [[ $backend != claude && -s ${BCS_RESPONSE_DUMP:-} ]]; then
      >&2 info "Raw response: $BCS_RESPONSE_DUMP"
    fi
  fi
  return "$exit_code"
}

# Subcommand: codes

cmd_codes() {
  local -- tier_filter='' explain_code=''
  local -i show_tier=1 include_disabled=1

  while (($#)); do case $1 in
    -T|--tier)     noarg "$@"; shift; tier_filter=$1
                   [[ " ${VALID_TIERS[*]} " == *" $tier_filter "* ]] \
                     || die 22 "Invalid tier ${tier_filter@Q} (valid: ${VALID_TIERS[*]})"
                   ;;
    -E|--explain)  noarg "$@"; shift; explain_code=${1^^}
                   [[ $explain_code =~ ^BCS[0-9]{4}$ ]] \
                     || die 22 "Invalid code ${explain_code@Q} (expected BCS####)"
                   ;;
    -p|--plain)    show_tier=0 ;;
    -x|--exclude-disabled) include_disabled=0 ;;
    -h|--help)     show_codes_help; return 0 ;;
    -[TEpxh]?*)    set -- "${1:0:2}" "-${1:2}" "${@:2}"; continue ;;
    -*)            die 22 "Invalid option ${1@Q}" ;;
    *)             die 2 "Unexpected argument ${1@Q}" ;;
  esac; shift; done

  local -- data_dir
  data_dir=$(_find_data_dir) || die 3 'Data directory not found'

  # --explain short-circuits: print one rule's body and return
  if [[ -n $explain_code ]]; then
    local -a sources=("$data_dir"/[0-9]*.md)
    [[ -d $data_dir/98-user.d ]] && sources+=("$data_dir"/98-user.d/*.md) ||:
    local -- src found=''
    for src in "${sources[@]}"; do
      [[ -f $src ]] || continue
      if grep -q "^## $explain_code " "$src" 2>/dev/null; then
        found=$src
        break
      fi
    done
    [[ -n $found ]] || die 3 "Rule ${explain_code@Q} not found"
    awk -v code="$explain_code" '
      /^## BCS/ {
        if (printing) exit
        if ($0 ~ "^## "code" ") printing=1
      }
      printing { print }
    ' "$found"
    return 0
  fi

  _load_tiers
  _load_policy

  # Include BCS section files + user rule files
  local -a files=("$data_dir"/[0-9]*.md)
  [[ -d $data_dir/98-user.d ]] && files+=("$data_dir"/98-user.d/*.md) ||:

  # Extract all ## BCS#### headers; decorate with effective tier
  local -- line code title tier
  while IFS= read -r line; do
    if [[ $line =~ ^##\ (BCS[0-9]+)\ (.+)$ ]]; then
      code=${BASH_REMATCH[1]}
      title=${BASH_REMATCH[2]}
      tier=$(_effective_tier "$code")
      [[ -z $tier_filter || $tier == "$tier_filter" ]] || continue
      ((include_disabled)) || [[ $tier != disabled ]] || continue
      if ((show_tier)) && [[ -n $tier ]]; then
        printf '%s [%s] %s\n' "$code" "$tier" "$title"
      else
        printf '%s %s\n' "$code" "$title"
      fi
    fi
  done < <(cat "${files[@]}" 2>/dev/null ||:)
}

# Subcommand: generate

cmd_generate() {
  local -- output_file=''

  while (($#)); do case $1 in
    -o|--output)   noarg "$@"; shift; output_file=$1 ;;
    -v|--verbose)  VERBOSE=1 ;;
    -q|--quiet)    VERBOSE=0 ;;
    -h|--help)     show_generate_help; return 0 ;;
    --)            shift; break ;;
    -[ovqh]?*)     set -- "${1:0:2}" "-${1:2}" "${@:2}"; continue ;;
    -*)            die 22 "Invalid option ${1@Q}" ;;
    *)             die 2 "Unexpected argument ${1@Q}" ;;
  esac; shift; done

  local -- data_dir
  data_dir=$(_find_data_dir) || die 3 'Data directory not found'

  # Default output location
  [[ -n $output_file ]] || output_file="$data_dir"/BASH-CODING-STANDARD.md

  # Build ordered list of section files.
  # Glob picks up 00-index, 01..12, 98-user.md (if present), 99-coda in order.
  # 98-user.d/*.md drop-ins are spliced in after 98-user.md, or before 99-*
  # if 98-user.md does not exist.
  local -a section_files=()
  local -- section_file base f
  for section_file in "$data_dir"/[0-9]*.md; do
    base=${section_file##*/}
    [[ $base == BASH-CODING-STANDARD.md ]] && continue ||:
    section_files+=("$section_file")
  done

  # Splice in 98-user.d/*.md drop-ins at the correct position
  if [[ -d $data_dir/98-user.d ]]; then
    local -a dropins=()
    for f in "$data_dir"/98-user.d/*.md; do
      [[ -f $f ]] && dropins+=("$f") ||:
    done
    if ((${#dropins[@]})); then
      local -a ordered=()
      local -i inserted=0
      # Try to insert right after 98-user.md
      for section_file in "${section_files[@]}"; do
        ordered+=("$section_file")
        base=${section_file##*/}
        if [[ $base == 98-user.md ]] && ! ((inserted)); then
          ordered+=("${dropins[@]}")
          inserted=1
        fi
      done
      # Fallback: insert right before 99-* if no 98-user.md
      if ! ((inserted)); then
        ordered=()
        for section_file in "${section_files[@]}"; do
          base=${section_file##*/}
          if [[ $base == 99-* ]] && ! ((inserted)); then
            ordered+=("${dropins[@]}")
            inserted=1
          fi
          ordered+=("$section_file")
        done
      fi
      # Final fallback: append drop-ins at end
      ((inserted)) || ordered+=("${dropins[@]}")
      section_files=("${ordered[@]}")
    fi
  fi

  ((${#section_files[@]})) || die 3 "No section files found in ${data_dir@Q}"

  info "Generating standard from ${#section_files[@]} section files..."

  # First section's SPDX marker is preserved as the canonical header;
  # strip the marker from every subsequent section to avoid 14 duplicates.
  local -i first=1
  { for section_file in "${section_files[@]}"; do
      if ((first)); then
        first=0
        cat -- "$section_file"
      else
        printf '\n---\n\n'
        sed '/^<!-- SPDX-License-Identifier:/d' "$section_file"
      fi
    done
  } > "$output_file".tmp
  mv -f -- "$output_file".tmp "$output_file"

  # Resolve relative markdown links to absolute paths
  local -- bcs_root
  bcs_root=$(realpath -- "$data_dir/..")
  bcs_root=${bcs_root//\\/\\\\}   # escape backslashes
  bcs_root=${bcs_root//|/\\|}     # escape sed delimiter
  bcs_root=${bcs_root//&/\\&}     # escape sed back-reference
  sed -i "s|](\\.\\.\/|](${bcs_root}/|g" "$output_file" \
    || die 1 "Failed to resolve relative links in ${output_file@Q}"

  # Make it readonly so that users do not confuse this document with the rules sections
  chmod 444 "$output_file"

  local -i line_count
  line_count=$(wc -l < "$output_file")
  success "Generated ${output_file@Q} ($line_count lines)"
}

# Subcommand: help

cmd_help() {
  (($#)) || { show_main_help; return 0; }

  case $1 in
    display)  show_display_help ;;
    template) show_template_help ;;
    check)    show_check_help ;;
    codes)    show_codes_help ;;
    generate) show_generate_help ;;
    help)     show_main_help ;;
    *)        error "Unknown command ${1@Q}"; show_main_help; return 2 ;;
  esac
}

# ---- Main dispatcher ----

main() {
  read_conf ||:

  local -- subcmd=display

  # Prefer GOOGLE_API_KEY over GEMINI_API_KEY; unset GEMINI_API_KEY if both set
  [[ -z ${GOOGLE_API_KEY:-} || -z ${GEMINI_API_KEY:-} ]] || unset GEMINI_API_KEY

  while (($#)); do
    case $1 in
      -V|--version)  printf '%s %s\n' "$SCRIPT_NAME" "$VERSION"; return 0 ;;
      -h|--help)     show_main_help; return 0 ;;
      -v|--verbose)  VERBOSE=1 ;;
      -q|--quiet)    VERBOSE=0 ;;
      --)            shift; break ;;
      -[Vhvq]?*)     set -- "${1:0:2}" "-${1:2}" "${@:2}"; continue ;;
       # Any other options means it's for subcmd 'display'
      -*)            break ;;
      *)             subcmd=${1,,}; shift; break ;;
    esac
    shift
  done

  # Dispatch to subcommand
  case $subcmd in
    display)  cmd_display "$@" ;;
    template) cmd_template "$@" ;;
    check)    cmd_check "$@" ;;
    codes)    cmd_codes "$@" ;;
    generate) cmd_generate "$@" ;;
    help)     cmd_help "$@" ;;
    *)        die 2 "Unknown command ${subcmd@Q}" ;;
  esac
}

# Source guard: test scripts may source this file to access internal
# functions without executing main. When sourced, BASH_SOURCE[0] (this
# file's path) differs from $0 (the sourcing script's path).
[[ ${BASH_SOURCE[0]} != "$0" ]] || main "$@"
#fin