🎨 ZSHAND Style Guide¶

# ✅ Good: Use shared functions
stderr_error "Configuration file not found: $config_file"
stderr_warn "Falling back to default settings"

# ❌ Bad: Raw echo to stderr
echo "ERROR: file not found" >&2

# ✅ Good: Assert before use
if assert_dir_exists "$ZSHAND/core" "Core directory"; then
    source "$ZSHAND/core/02_vars.zsh"
fi

if assert_function_exists "zprime"; then
    zprime
fi

# ❌ Bad: Silent failure
[[ -d "$ZSHAND/core" ]] && source "$ZSHAND/core/02_vars.zsh"

# ✅ Good: Check and degrade
my_function() {
    (( $+commands[jq] )) || {
        stderr_warn "jq not installed. Install: pacman -S jq"
        return 1
    }
    # ... proceed with jq
}

# ❌ Bad: Assume deps exist
my_function() {
    jq '.key' "$file"  # Crashes if jq missing
}

# ✅ Good: Explicit local
my_function() {
    local cache_dir="${ZSHAND_CACHE_DIR}"
    local -a files=("$cache_dir"/*.zsh(N))
    local -A timings=()
}

# ❌ Bad: Implicit globals (leak into caller)
my_function() {
    cache_dir="${ZSHAND_CACHE_DIR}"
    files=("$cache_dir"/*.zsh(N))
}

# ✅ Good: Explicit global declaration
typeset -g _zshand_full_bundle_loaded=0
typeset -gA _zshand_timings

# ❌ Bad: Implicit global (confusing in function context)
_zshand_full_bundle_loaded=0

# ✅ Good: Builtins
local basename="${path:t}"       # basename
local dirname="${path:h}"        # dirname
local extension="${file:e}"      # extension
local no_ext="${file:r}"         # remove extension
local absolute="${file:A}"       # absolute path

# ❌ Bad: Subprocesses
local basename="$(basename "$path")"
local dirname="$(dirname "$path")"

# ✅ Good: Double-bracket test (zsh native)
[[ -f "$file" ]] && source "$file"
[[ -z "$var" ]] && var="default"

# ✅ Good: Arithmetic evaluation
(( ZSHAND_DEBUG )) && print "debug info"
(( $+commands[jq] )) || return 1
(( $+functions[zprime] )) && zprime

# ❌ Bad: Single-bracket test (POSIX, slower)
[ -f "$file" ] && source "$file"

# ✅ Good: Glob with nullglob qualifier
local -a files=("$dir"/*.zsh(N.))    # (N) = no error if empty, (.) = files only

# ✅ Good: Sorted glob with numeric sort
for f in "$dir"/*.zsh(nN.); do       # (n) = numeric sort
    source "$f"
done

# ❌ Bad: Bare glob (errors on empty match)
for f in "$dir"/*.zsh; do
    source "$f"
done

# ✅ Good: Parameter expansion with default
local cache="${ZSHAND_CACHE_DIR:-${XDG_CACHE_HOME:-$HOME/.cache}/zshand}"

# ✅ Good: Colon-equals for set-if-unset
: ${ZSHAND_PERF_BUDGET:=100}

# ❌ Bad: Explicit if/else for defaults
if [[ -z "$ZSHAND_CACHE_DIR" ]]; then
    local cache="$HOME/.cache/zshand"
else
    local cache="$ZSHAND_CACHE_DIR"
fi

# ✅ Always quote variable expansions in arguments
source "$ZSHAND/core/02_vars.zsh"
[[ -f "$config_file" ]]
print -P "%F{green}$message%f"

# ✅ Exception: Arithmetic context (no quotes needed)
(( ZSHAND_DEBUG ))
(( $+commands[jq] ))

# ❌ Bad: Unquoted variables (word splitting risk)
source $ZSHAND/core/02_vars.zsh
[[ -f $config_file ]]

# ── SECTION NAME ──────────────────────────────────────────────────────────────
# Description of what this section does.

# ✅ Good: Explain WHY, not WHAT
local -gU path  # Enforce unique entries to keep lookups fast

# ✅ Good: Explain zsh-specific idioms
[[ ${arr[(ie)$item]} -le ${#arr} ]]  # (ie) = exact case-insensitive search

# ❌ Bad: Restate the obvious
local count=0  # Set count to 0

# TODO: Add spec for ZSHAND_PROFILE_VERBOSE=1 output differences
# FIXME: This breaks when path contains newlines
# HACK: Workaround for zsh 5.0 compatibility (remove after 5.2+ minimum)

# ✅ Good: Secure file permissions
chmod 600 "$ZSHAND_CONFIG_DIR/secrets.zsh"

# ✅ Good: Never log secrets
_zrun --quiet "action" "description"  # Telemetry without secrets

# ❌ Bad: Echo secrets to log
echo "API_KEY=$API_KEY" >> "$LOG_DIR/debug.log"

# ✅ Good: Validate before use
[[ -z "$1" ]] && { stderr_error "Missing argument"; return 1 }
[[ -d "$1" ]] || { stderr_error "Not a directory: $1"; return 1 }

# ✅ Good: Quote everything in eval-adjacent contexts
local cmd="${1:?Command required}"

# ✅ Preferred: Use IO library functions
stderr_error "Something failed"       # Red error to stderr
stderr_warn "Something suspicious"    # Yellow warning to stderr
echo_info "Processing..."            # Blue info to stdout
echo_ok "Done"                       # Green success to stdout

# ✅ Rich output functions
az_banner "Module Title"              # Double-border title banner
az_header "Section"                   # Bold section header
az_divider                            # Horizontal line
az_step 1 5 "Installing packages"    # Step counter [1/5]
az_done "Complete!"                   # Green completion banner
az_note "Important: Install fonts"    # Callout box

# ✅ Interactive functions
az_spin "Compiling..." zcompile f.zsh # Spinner with ✓/✗
az_confirm "Continue?" && echo "yes"  # Y/N prompt
selected=$(az_choose "A" "B" "C")    # Selection menu

# ❌ Avoid: Raw print -P for simple error/warn/info/ok messages
print -P "%F{red}ERROR: $message%f" >&2    # Use stderr_error instead
print -P "%F{yellow}Warning: $msg%f" >&2   # Use stderr_warn instead

# ✅ Acceptable: Complex dashboard display with multiple colors and variables
print -P "  %F{cyan}System:%f  Arch (%F{yellow}${session_type}%f) | Up: ${uptime}"
print -P "  %F{green}%3d. [✓]%f ${path_entry}"

# ✅ Acceptable: Interactive prompts with colored inline text
print -Pn "%F{cyan}󰃢 Continue? (y/n):%f "

# ✅ Acceptable: Template code written to files
cat <<EOF > "$file"
  print -P "󰄬 Executing ${name}..."
EOF