@sebastienrousseau/dotfiles 0.2.518 → 0.2.520

package/scripts/qa/check-version-consistency.sh

@@ -1,124 +1,12 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 #
-# Verify that every "live" version reference matches the canonical
-# version in .chezmoidata.toml. The intent is to catch drift between
-# the source-of-truth and the human-visible surfaces (CLI banner, man
-# page, badge URL, etc.) BEFORE it ships.
+# Compatibility wrapper. The canonical name for this gate is
+# `scripts/verify-release-versions` (the name the repository standard
+# uses); this path is kept so existing callers — the `version-consistency`
+# pre-commit hook, older docs, muscle memory — keep working.
 #
-# Historical references (CHANGELOG entries, audit-doc closed-cycle
-# tables, roadmap docs that mention previous versions) are NOT
-# checked — they are intentionally pinned to the version they
-# describe.
-#
-# Usage:
-#   scripts/qa/check-version-consistency.sh           # verify
-#   scripts/qa/check-version-consistency.sh --fix     # auto-fix
-#   scripts/qa/check-version-consistency.sh --quiet   # rc-only
-#
-# Exit codes:
-#   0  every live reference matches
-#   1  drift detected (with diff printed unless --quiet)
-#   2  bad usage / missing canonical version
-
+# Do not add logic here. Edit scripts/verify-release-versions.
 set -euo pipefail
-
-REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
-cd "$REPO_ROOT"
-
-# ── Parse flags ─────────────────────────────────────────────────────────
-fix=0
-quiet=0
-for arg in "$@"; do
-  case "$arg" in
-    --fix) fix=1 ;;
-    --quiet | -q) quiet=1 ;;
-    -h | --help)
-      sed -n '2,21p' "$0"
-      exit 0
-      ;;
-    *)
-      echo "unknown flag: $arg" >&2
-      exit 2
-      ;;
-  esac
-done
-
-_log() { ((quiet)) || printf '%s\n' "$*"; }
-_err() { printf 'check-version-consistency: %s\n' "$*" >&2; }
-
-# ── Canonical version ──────────────────────────────────────────────────
-canonical="$(grep -E '^dotfiles_version[[:space:]]*=' defaults/.chezmoidata.toml |
-  head -1 | sed -E 's/.*"([^"]+)".*/\1/')"
-
-if [[ -z "$canonical" ]]; then
-  _err 'failed to read dotfiles_version from defaults/.chezmoidata.toml'
-  exit 2
-fi
-_log "canonical: $canonical (defaults/.chezmoidata.toml)"
-
-# ── Per-file expected-substring map ────────────────────────────────────
-# Each entry: PATH|MATCH_PATTERN|EXPECTED_STRING
-# MATCH_PATTERN is a fixed substring to grep for on the file to
-# locate the version-bearing line; we then verify it contains the
-# expected substring rendered with $canonical. version-sync.sh
-# already handles many files (it reads package.json as source);
-# this list captures the surfaces version-sync.sh historically
-# missed — bento.sh banner, man-page header, dispatcher header.
-specs=(
-  "package.json|\"version\"|\"version\": \"${canonical}\""
-  "bin/dot|^VERSION=|VERSION=\"${canonical}\""
-  "bin/dot|^# Dotfiles CLI Entry Point - v|# Dotfiles CLI Entry Point - v${canonical}"
-  "share/man/man1/dot.1|^.TH DOT 1|dotfiles v${canonical}"
-  "lib/dot/bento.sh|D O T F I L E S|[v${canonical}]"
-  "README.md|img.shields.io/badge/Version|Version-v${canonical}-blue"
-  "CLAUDE.md|^Chezmoi-managed dotfiles|Version \`${canonical}\`"
-  "AGENTS.md|^Chezmoi-managed dotfiles|Version \`${canonical}\`"
-)
-
-drift=0
-for spec in "${specs[@]}"; do
-  IFS='|' read -r path pattern expected <<<"$spec"
-  if [[ ! -f "$path" ]]; then
-    _err "MISSING: $path (declared in spec list)"
-    drift=$((drift + 1))
-    continue
-  fi
-  line="$(grep -E "$pattern" "$path" | head -1 || true)"
-  if [[ -z "$line" ]]; then
-    _err "PATTERN NOT FOUND: '$pattern' in $path"
-    drift=$((drift + 1))
-    continue
-  fi
-  if [[ "$line" != *"$expected"* ]]; then
-    _err "DRIFT in $path"
-    _err "  found:    $line"
-    _err "  expected: contains '$expected'"
-    drift=$((drift + 1))
-    if ((fix)); then
-      # Auto-fix: only safe when the file contains a previous v0.X.YYY
-      # we can sed-replace. Skip otherwise.
-      old="$(printf '%s' "$line" | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' | head -1)"
-      if [[ -n "$old" ]] && [[ "$old" != "v${canonical}" ]]; then
-        sed -i.bak "s|${old}|v${canonical}|g" "$path" && rm -f "$path.bak"
-        _log "  fixed:  $path  ($old → v${canonical})"
-      fi
-    fi
-  fi
-done
-
-if ((drift > 0)); then
-  if ((fix)); then
-    _log ""
-    _log "Auto-fixed where safe. Re-run without --fix to verify."
-  else
-    _log ""
-    _log "Tip: rerun with --fix to auto-correct (only safe substitutions)."
-    _log "     For non-trivial drift, edit the file manually then re-run."
-  fi
-  exit 1
-fi
-
-_log "all $((${#specs[@]})) live version surfaces match $canonical"
-exit 0
+exec bash "$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)/scripts/verify-release-versions" "$@"

package/scripts/qa/coverage-baseline.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 set -euo pipefail
 

package/scripts/qa/docs-coverage.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 set -euo pipefail
 
@@ -10,7 +10,7 @@ DOT_CLI="$REPO_ROOT/bin/dot"
 UTILS_DOC="$REPO_ROOT/docs/reference/UTILS.md"
 AI_DOC="$REPO_ROOT/docs/AI.md"
 SCRIPTS_DOC="$REPO_ROOT/docs/reference/SCRIPTS.md"
-ARCH_DOC="$REPO_ROOT/docs/architecture/ARCHITECTURE.md"
+ARCH_DOC="$REPO_ROOT/docs/ARCHITECTURE.md"
 FUNCTION_GROUPS_JSON="$REPO_ROOT/defaults/.chezmoitemplates/functions/groups.json"
 MIN_DOCS_COVERAGE="${MIN_DOCS_COVERAGE:-100}"
 
@@ -104,7 +104,13 @@ main() {
   check_ai_provider_docs
   check_utility_docs
   check_function_group_docs
-  report_coverage
+  # Capture the coverage threshold verdict — without this the final
+  # `printf PASS...` overwrites report_coverage's exit code and CI
+  # never sees a coverage regression.
+  if ! report_coverage; then
+    printf 'FAIL: docs coverage below MIN_DOCS_COVERAGE=%s%%\n' "$MIN_DOCS_COVERAGE" >&2
+    return 1
+  fi
 
   printf 'PASS: public dot commands, utility entrypoints, AI providers, and function groups are documented at or above the required threshold\n'
 }

package/scripts/qa/examples-coverage.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # =============================================================================
 # examples-coverage.sh — enforce that every core feature domain ships a

package/scripts/qa/reliability-audit.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 set -euo pipefail
 

package/scripts/qa/scorecard-snapshot.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 #
 # Fetch the current OpenSSF Scorecard result and refresh the

package/scripts/qa/traceability-coverage.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 set -euo pipefail
 
@@ -109,7 +109,14 @@ main() {
     } | sort -u
   )
 
-  report_traceability
+  # Capture report_traceability's exit — without this the trailing
+  # `printf PASS...` returns 0 and overwrites the awk threshold verdict,
+  # so a below-threshold run silently exits 0 (same bug as docs-coverage.sh).
+  if ! report_traceability; then
+    printf 'FAIL: traceability coverage below MIN_TRACEABILITY_COVERAGE=%s%%\n' \
+      "$MIN_TRACEABILITY_COVERAGE" >&2
+    return 1
+  fi
 
   printf 'PASS: core internal behaviors have implementation, test, and documentation traceability at or above the required threshold\n'
 }

package/scripts/qa/validate-examples.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 set -euo pipefail
 
@@ -7,16 +7,74 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 EXAMPLES_DIR="$REPO_ROOT/examples"
 
+# Per-example wall-clock budget. Bounding each example individually means one
+# slow or hanging example is reported by name instead of silently consuming the
+# whole script's budget and surfacing as an opaque rc=124 from the caller.
+EXAMPLE_TIMEOUT="${EXAMPLE_TIMEOUT:-60}"
+
+usage() {
+  cat <<'USAGE'
+Usage: validate-examples.sh [--help]
+
+Runs every executable example in examples/ and fails if any of them fails or
+exceeds the per-example timeout.
+
+Environment:
+  EXAMPLE_TIMEOUT   Per-example timeout in seconds (default: 60). Set to 0 to
+                    disable the timeout.
+USAGE
+}
+
+# Parse arguments before doing any work. Previously this script ignored its
+# arguments entirely, so `--help` silently executed the whole examples suite —
+# which meant asking for help ran a multi-minute job.
+case "${1:-}" in
+  -h | --help)
+    usage
+    exit 0
+    ;;
+  "") ;;
+  *)
+    printf 'Unknown option: %s\n\n' "$1" >&2
+    usage >&2
+    exit 2
+    ;;
+esac
+
 if [ ! -d "$EXAMPLES_DIR" ]; then
   echo "No examples directory found: $EXAMPLES_DIR" >&2
   exit 1
 fi
 
+# Resolve a timeout binary. GNU coreutils ships `timeout`; on macOS it is
+# `gtimeout` when coreutils is installed. Without either, run unbounded rather
+# than failing outright.
+timeout_cmd=()
+if [ "$EXAMPLE_TIMEOUT" != "0" ]; then
+  if command -v timeout >/dev/null 2>&1; then
+    timeout_cmd=(timeout --kill-after=5 "$EXAMPLE_TIMEOUT")
+  elif command -v gtimeout >/dev/null 2>&1; then
+    timeout_cmd=(gtimeout --kill-after=5 "$EXAMPLE_TIMEOUT")
+  else
+    printf 'warning: no timeout binary found; examples run unbounded\n' >&2
+  fi
+fi
+
 found=0
+failed=0
 while IFS= read -r -d '' example; do
   found=1
-  printf 'Running example: %s\n' "$(basename "$example")"
-  bash "$example"
+  name="$(basename "$example")"
+  printf 'Running example: %s\n' "$name"
+  rc=0
+  "${timeout_cmd[@]+"${timeout_cmd[@]}"}" bash "$example" </dev/null || rc=$?
+  if [ "$rc" -eq 124 ]; then
+    printf 'FAIL: %s exceeded the %ss timeout\n' "$name" "$EXAMPLE_TIMEOUT" >&2
+    failed=$((failed + 1))
+  elif [ "$rc" -ne 0 ]; then
+    printf 'FAIL: %s exited %s\n' "$name" "$rc" >&2
+    failed=$((failed + 1))
+  fi
 done < <(find "$EXAMPLES_DIR" -maxdepth 1 -type f -name "*.sh" -print0 | sort -z)
 
 if [ "$found" -eq 0 ]; then
@@ -24,4 +82,9 @@ if [ "$found" -eq 0 ]; then
   exit 1
 fi
 
+if [ "$failed" -ne 0 ]; then
+  printf '%s example(s) failed.\n' "$failed" >&2
+  exit 1
+fi
+
 printf 'Examples passed.\n'

package/scripts/qa/wsl-contract.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 set -euo pipefail
 

package/scripts/secrets/age-init.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 set -euo pipefail
 

package/scripts/secrets/create-secrets-file.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 set -euo pipefail
 

package/scripts/secrets/encrypt-ssh-key.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 set -euo pipefail
 

package/scripts/security/backup.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 ## Create compressed backup of home directory.
 ##

package/scripts/security/check-disclosure-key-expiry.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 #
 # scripts/security/check-disclosure-key-expiry.sh

package/scripts/security/dns-doh.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 set -euo pipefail
 

package/scripts/security/encryption-check.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 set -euo pipefail