@sebastienrousseau/dotfiles 0.2.500 → 0.2.501

package/scripts/ci/run-coverage.sh

@@ -0,0 +1,362 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+# =============================================================================
+# run-coverage.sh — Bash code-coverage runner using pure xtrace
+# instrumentation. Emits lcov.info at $COVERAGE_OUT.
+#
+# Why pure xtrace (not kcov):
+#   kcov v43 on Ubuntu 24.04 + bash 5.2 won't emit bash-script
+#   coverage in either mode: without bash-dbgsym it captures nothing,
+#   and with bash-dbgsym it captures bash's *C-binary* internals
+#   (ctype.h, stdio.h) instead of the .sh file lines we care about.
+#   We bypass kcov entirely by using bash's own xtrace mechanism:
+#
+#     PS4='+:${LINENO}:${BASH_SOURCE}:'   # encode line + file in trace
+#     BASH_ENV=/setup-that-runs-set-x      # turn on xtrace in every
+#                                          # non-interactive bash, so
+#                                          # children inherit tracing
+#     bash test.sh 2>traces/test.trace     # capture lines per test
+#
+#   Then we parse all traces with regex and write lcov.info. This is
+#   the same mechanism bashcov uses, minus the Ruby runtime.
+#
+# Linux + macOS both work (macOS bash 3.2 supports BASH_XTRACEFD as
+# well — verified locally on bash 5.3 via Homebrew). The pre-commit
+# hook in this repo can invoke this on any platform.
+#
+# Closes the runner half of #856 / Slice 1 of #883.
+# =============================================================================
+
+set -uo pipefail
+
+REPO_ROOT="${REPO_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+TESTS_DIR="${TESTS_DIR:-$REPO_ROOT/tests}"
+COVERAGE_DIR="${COVERAGE_DIR:-$REPO_ROOT/coverage}"
+COVERAGE_OUT="${COVERAGE_OUT:-$COVERAGE_DIR/lcov.info}"
+MIN_COVERAGE_PCT="${MIN_COVERAGE_PCT:-0}" # initial floor; tighten per slice
+COV_INCLUDE_DIRS="${COV_INCLUDE_DIRS:-$REPO_ROOT/scripts:$REPO_ROOT/dot_local/bin:$REPO_ROOT/.chezmoitemplates/functions}"
+JOBS="${JOBS:-$(nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || echo 4)}"
+COV_TEST_TIMEOUT="${COV_TEST_TIMEOUT:-60}"
+
+mkdir -p "$COVERAGE_DIR"
+trace_dir="$COVERAGE_DIR/traces"
+rm -rf "$trace_dir"
+mkdir -p "$trace_dir"
+
+# -----------------------------------------------------------------------------
+# BASH_ENV setup file: enables xtrace in every non-interactive bash that
+# inherits it. Child processes spawned via `bash $SCRIPT` get their own
+# tracing turned on automatically.
+# -----------------------------------------------------------------------------
+bash_env="$COVERAGE_DIR/_cov_bashenv.sh"
+cat >"$bash_env" <<'SETUP'
+# coverage runtime — enable xtrace, define PS4 with file+line markers.
+# `${BASH_SOURCE:-}` (not `${BASH_SOURCE}`) prevents PS4 evaluation
+# from failing under `set -u`: at the top level of a `bash -c`
+# script, BASH_SOURCE[0] is unbound; an unguarded expansion under
+# `set -u` aborts the shell, taking out any test that sources a
+# `set -euo pipefail` library file.
+set -x
+PS4='+@COV@:${LINENO}:${BASH_SOURCE:-}:@ '
+SETUP
+
+# Sanity-probe: run one trivial script through the pipeline so a
+# subsequent failure of the real sweep can be diagnosed quickly.
+probe_target="$COVERAGE_DIR/_probe_target.sh"
+cat >"$probe_target" <<'PROBE'
+#!/usr/bin/env bash
+set -uo pipefail
+echo "probe-line-a"
+x=1; y=2
+echo "probe-sum=$((x + y))"
+PROBE
+chmod +x "$probe_target"
+
+PS4='+@COV@:${LINENO}:${BASH_SOURCE}:@ ' \
+  BASH_ENV="$bash_env" \
+  bash "$probe_target" 2>"$trace_dir/_probe.trace" >/dev/null || true
+probe_lines=$(grep -cE "^\+@COV@:[0-9]+:.*${probe_target}:@" "$trace_dir/_probe.trace" 2>/dev/null || echo 0)
+echo "probe: ${probe_lines} traced lines from ${probe_target}" >&2
+if [[ "$probe_lines" -eq 0 ]]; then
+  echo "::error::xtrace probe captured no lines — coverage mechanism broken" >&2
+  exit 2
+fi
+
+# -----------------------------------------------------------------------------
+# Collect test files (mirror tests/framework/test_runner.sh discovery).
+# -----------------------------------------------------------------------------
+mapfile -t test_files < <(find "$TESTS_DIR/unit" -name 'test_*.sh' -type f | sort)
+
+if [[ "${#test_files[@]}" -eq 0 ]]; then
+  echo "::error::no unit test files discovered under $TESTS_DIR/unit" >&2
+  exit 1
+fi
+
+echo "Tracing ${#test_files[@]} test files (parallel × $JOBS, timeout ${COV_TEST_TIMEOUT}s/test)..." >&2
+
+# -----------------------------------------------------------------------------
+# Worker function — runs one test under xtrace, captures stderr.
+# -----------------------------------------------------------------------------
+# shellcheck disable=SC2329  # called indirectly via xargs subshell
+run_one() {
+  local f="$1"
+  local trace
+  trace="$COV_TRACE_DIR/$(basename "$f" .sh).trace"
+  PS4='+@COV@:${LINENO}:${BASH_SOURCE}:@ ' \
+    BASH_ENV="$COV_BASH_ENV" \
+    timeout --kill-after=5 "$COV_TEST_TIMEOUT" \
+    bash "$f" 2>"$trace" >/dev/null || true
+}
+
+export COV_TRACE_DIR="$trace_dir"
+export COV_BASH_ENV="$bash_env"
+export COV_TEST_TIMEOUT
+export -f run_one
+
+start_ts=$(date +%s)
+printf '%s\n' "${test_files[@]}" |
+  xargs -I{} -n1 -P"$JOBS" bash -c 'run_one "$@"' _ {} ||
+  true
+elapsed=$(($(date +%s) - start_ts))
+echo "trace phase done in ${elapsed}s" >&2
+
+# -----------------------------------------------------------------------------
+# Aggregate trace files → lcov.info.
+# -----------------------------------------------------------------------------
+python3 - "$COVERAGE_OUT" "$trace_dir" "$REPO_ROOT" "$COV_INCLUDE_DIRS" <<'PY'
+"""Aggregate bash xtrace output into lcov.info."""
+import os
+import re
+import sys
+from collections import defaultdict
+from pathlib import Path
+
+out_path, trace_dir, repo_root, include_dirs_spec = sys.argv[1:5]
+include_dirs = [Path(p).resolve() for p in include_dirs_spec.split(":") if p]
+trace_dir = Path(trace_dir)
+repo_root = Path(repo_root).resolve()
+
+# Pattern: +@COV@:<lineno>:<source>:@
+hit_re = re.compile(r"^\+@COV@:(\d+):([^:]+):@")
+
+# files[abs_path][line] = total hits
+files = defaultdict(lambda: defaultdict(int))
+
+def in_includes(path: Path) -> bool:
+    try:
+        rp = path.resolve()
+    except (OSError, RuntimeError):
+        return False
+    for inc in include_dirs:
+        try:
+            rp.relative_to(inc)
+            return True
+        except ValueError:
+            continue
+    return False
+
+# Parse every trace file. Each trace can be MBs; iterate line by line.
+for trace_path in sorted(trace_dir.glob("*.trace")):
+    try:
+        with open(trace_path, "r", errors="replace") as f:
+            for line in f:
+                m = hit_re.match(line)
+                if not m:
+                    continue
+                lineno = int(m.group(1))
+                src = m.group(2).strip()
+                if not src or src == "main":
+                    continue
+                src_path = Path(src)
+                if not src_path.is_absolute():
+                    src_path = (repo_root / src_path)
+                # Always resolve so `..`-style paths from inside
+                # `commands/foo.sh` sourcing `../lib/log.sh` collapse
+                # to the same canonical SF: key as a direct hit on
+                # `lib/log.sh`. Without this we get three SF: blocks
+                # for one file and the denominator inflates.
+                try:
+                    src_path = src_path.resolve()
+                except (OSError, RuntimeError):
+                    pass
+                if not in_includes(src_path):
+                    continue
+                files[str(src_path)][lineno] += 1
+    except OSError as e:
+        print(f"warn: read error {trace_path}: {e}", file=sys.stderr)
+
+# Sweep through include-dirs and add executable lines for files we never
+# touched, so lcov coverage % reflects total source surface, not just
+# touched files.
+ws_re = re.compile(r"^\s*$")
+comment_re = re.compile(r"^\s*#")
+shebang_re = re.compile(r"^\s*#!")
+
+def executable_lines(path: Path):
+    """Lines that bash xtrace can plausibly emit.
+
+    Excludes:
+      - blanks / shebangs / comments (already)
+      - structural-only keywords (`fi`, `done`, `else`, `esac`, `then`,
+        `do`, `in`, bare `{`/`}` braces) — these are syntax, not
+        commands; xtrace never traces them
+      - heredoc body lines (between `<<EOF` and `EOF`) — content, not
+        executed
+      - `case` pattern labels (`foo)`) — the matched body executes,
+        not the pattern itself
+
+    This matches what `bash -x` actually produces a `+`-prefixed
+    line for, so the denominator reflects measurable lines.
+
+    Honor LCOV_EXCL_LINE / LCOV_EXCL_START / LCOV_EXCL_STOP markers
+    so authors can exempt genuinely unreachable lines (platform-
+    gated branches, root-only paths, dead-code stubs).
+    """
+    import re as _re
+    structural = _re.compile(
+        r"^\s*("
+        r"fi|done|else|elif|esac|then|do|in|"
+        r"\}|\{|"
+        r"\)\s*;?;?\s*$|"        # bare `)` (case pattern close)
+        r";;\s*$"                # `;;` case-clause terminator
+        r")\s*(#.*)?$"
+    )
+    case_pattern = _re.compile(r"^\s*[a-zA-Z0-9_\*\?\[\|/\-\.+]+\)\s*(#.*)?$")
+    heredoc_open = _re.compile(r"<<-?\s*[\"\']?([A-Za-z_][A-Za-z0-9_]*)[\"\']?")
+    excl_line = _re.compile(r"#\s*LCOV_EXCL_LINE")
+    excl_start = _re.compile(r"#\s*LCOV_EXCL_START")
+    excl_stop = _re.compile(r"#\s*LCOV_EXCL_STOP")
+    # Scripts that explicitly turn off xtrace can't be measured by
+    # this mechanism — the bash runtime simply stops emitting trace
+    # records. Treat everything after `set +x` / `set +o xtrace`
+    # as excluded so it doesn't sink the denominator.
+    xtrace_off = _re.compile(r"^\s*set\s+(\+x|\+o\s+xtrace)\b")
+
+    try:
+        with open(path, "r", errors="replace") as f:
+            text = f.read().splitlines()
+    except OSError:
+        return []
+
+    out = []
+    in_heredoc = None  # the terminator we're waiting for
+    excluding = False
+    xtrace_disabled = False
+    for i, line in enumerate(text, 1):
+        # LCOV_EXCL handling
+        if excl_start.search(line):
+            excluding = True
+            continue
+        if excl_stop.search(line):
+            excluding = False
+            continue
+        if excluding:
+            continue
+        if excl_line.search(line):
+            continue
+
+        # Once a script disables xtrace, no further lines can be
+        # measured by this mechanism — drop them from the denominator.
+        if xtrace_disabled:
+            continue
+        if xtrace_off.match(line):
+            xtrace_disabled = True
+            continue
+
+        # Heredoc body — track and skip
+        if in_heredoc is not None:
+            if line.strip() == in_heredoc:
+                in_heredoc = None
+            continue
+        hd = heredoc_open.search(line)
+        if hd and not comment_re.match(line):
+            in_heredoc = hd.group(1)
+
+        if not line or ws_re.match(line):
+            continue
+        if shebang_re.match(line):
+            continue
+        if comment_re.match(line):
+            continue
+        if structural.match(line):
+            continue
+        if case_pattern.match(line):
+            continue
+        out.append(i)
+    return out
+
+for inc in include_dirs:
+    if not inc.exists():
+        continue
+    for path in inc.rglob("*.sh"):
+        ap = str(path.resolve())
+        existing = files[ap]  # creates the entry on touch
+        for ln in executable_lines(path):
+            if ln not in existing:
+                existing[ln] = 0
+    for path in inc.rglob("*"):
+        # also include shebanged shell scripts without .sh
+        if path.is_file() and not path.suffix and path.stat().st_size > 0:
+            try:
+                with open(path, "r", errors="replace") as f:
+                    first = f.readline()
+            except OSError:
+                continue
+            if first.startswith("#!") and ("bash" in first or "sh" in first):
+                ap = str(path.resolve())
+                existing = files[ap]
+                for ln in executable_lines(path):
+                    if ln not in existing:
+                        existing[ln] = 0
+
+# Emit lcov.info
+with open(out_path, "w") as out:
+    for filename in sorted(files):
+        out.write(f"SF:{filename}\n")
+        for ln in sorted(files[filename]):
+            out.write(f"DA:{ln},{files[filename][ln]}\n")
+        out.write("end_of_record\n")
+
+# Summary
+total_files = len(files)
+total_lines = sum(len(lines) for lines in files.values())
+covered = sum(1 for lines in files.values() for h in lines.values() if h > 0)
+pct = (covered * 100.0 / total_lines) if total_lines else 0.0
+print(f"Aggregated: {total_files} files, {covered}/{total_lines} lines = {pct:.2f}%",
+      file=sys.stderr)
+PY
+
+if [[ ! -s "$COVERAGE_OUT" ]]; then
+  echo "::error::failed to produce lcov.info — aggregator wrote empty file." >&2
+  exit 1
+fi
+
+# -----------------------------------------------------------------------------
+# Threshold check.
+# -----------------------------------------------------------------------------
+summary=$(
+  python3 - "$COVERAGE_OUT" <<'PY'
+import sys
+total = covered = 0
+with open(sys.argv[1]) as f:
+    for line in f:
+        if line.startswith("DA:"):
+            _, rest = line.split(":", 1)
+            _, hits = rest.strip().split(",")
+            total += 1
+            if int(hits) > 0:
+                covered += 1
+pct = (covered * 100.0 / total) if total else 0.0
+print(f"{covered} {total} {pct:.2f}")
+PY
+)
+read -r covered total pct <<<"$summary"
+echo "Coverage: ${covered}/${total} lines = ${pct}% (output: $COVERAGE_OUT)"
+
+below=$(awk -v p="$pct" -v t="$MIN_COVERAGE_PCT" 'BEGIN{print (p+0 < t+0) ? "1" : "0"}')
+if [[ "$below" == "1" ]]; then
+  echo "::error::coverage ${pct}% is below the floor ${MIN_COVERAGE_PCT}%" >&2
+  exit 1
+fi
+
+exit 0

package/scripts/ci/validate-chezmoidata.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+# Validate .chezmoidata.toml against config/chezmoidata.schema.json via taplo.
+#
+# Usage:
+#   bash scripts/ci/validate-chezmoidata.sh
+#
+# In CI the workflow installs taplo before invoking this script. Locally,
+# install via: cargo install --locked taplo-cli  (or `brew install taplo`).
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$REPO_ROOT"
+
+if ! command -v taplo >/dev/null 2>&1; then
+  echo "error: taplo not found in PATH" >&2
+  echo "  install: cargo install --locked taplo-cli" >&2
+  echo "      or: brew install taplo" >&2
+  exit 127
+fi
+
+# `taplo check` reads .taplo.toml at the repo root, applies the schema
+# rule, and reports schema violations + TOML syntax errors.
+taplo check

package/scripts/diagnostics/doctor.sh

@@ -387,6 +387,49 @@ else
   _fail "dot" "not found in PATH"
 fi
 
+# --- Pre-push audit bypass log (closes #871) ---
+_section "Pre-Push Audit Bypass"
+
+bypass_log="${XDG_STATE_HOME:-$HOME/.local/state}/dotfiles/audit-bypass.log"
+if [[ -s "$bypass_log" ]]; then
+  # Count entries in the last 7 days (timestamps are ISO-8601 UTC).
+  seven_days_ago=$(date -u -v-7d +%Y-%m-%dT00:00:00Z 2>/dev/null ||
+    date -u -d '7 days ago' +%Y-%m-%dT00:00:00Z 2>/dev/null ||
+    echo "1970-01-01T00:00:00Z")
+  recent=$(awk -v cutoff="$seven_days_ago" '$1 >= cutoff' "$bypass_log" | wc -l | tr -d ' ')
+  if ((recent > 0)); then
+    _warn "audit bypass" "$recent push(es) bypassed in last 7 days — see $(pretty_path "$bypass_log")"
+  else
+    _ok "audit bypass" "log exists; no recent entries (last 7d)"
+  fi
+else
+  _ok "audit bypass" "clean — no pre-push audits bypassed"
+fi
+
+# --- Atuin history-filter (closes #872) ---
+_section "Atuin History Filter"
+
+atuin_cfg="$HOME/.config/atuin/config.toml"
+if [[ ! -f "$atuin_cfg" ]]; then
+  _warn "atuin config" "not found at $(pretty_path "$atuin_cfg")"
+else
+  if grep -Eq "^history_filter[[:space:]]*=" "$atuin_cfg"; then
+    pattern_count=$(awk '
+      /^history_filter[[:space:]]*=[[:space:]]*\[/ { inside = 1; next }
+      inside && /^\]/                              { inside = 0 }
+      inside && /^[[:space:]]*"/                   { count++ }
+      END                                          { print count + 0 }
+    ' "$atuin_cfg")
+    if ((pattern_count >= 10)); then
+      _ok "history_filter" "$pattern_count patterns (chezmoi-managed)"
+    else
+      _warn "history_filter" "$pattern_count patterns (expected ≥10 from secrets-patterns.toml)"
+    fi
+  else
+    _fail "history_filter" "no history_filter block in $(pretty_path "$atuin_cfg") — secrets may leak into shell history"
+  fi
+fi
+
 # --- Topgrade Integration ---
 _section "Topgrade Integration"
 
@@ -472,10 +515,12 @@ fi
 # --- Performance ---
 _section "Performance"
 
-# Check shell cache freshness — stale caches force runtime regeneration
+cache_base="${XDG_CACHE_HOME:-$HOME/.cache}"
+
+# 1. Shell cache freshness for tools the project already wraps in _cached_eval.
+# Stale caches force runtime regeneration on next shell start.
 stale_caches=0
 stale_tools=""
-cache_base="${XDG_CACHE_HOME:-$HOME/.cache}"
 for tool in mise starship zoxide atuin fzf direnv; do
   tool_bin="$(command -v "$tool" 2>/dev/null || true)"
   [[ -n "$tool_bin" ]] || continue
@@ -486,22 +531,98 @@ for tool in mise starship zoxide atuin fzf direnv; do
     esac
     if [[ ! -f "$cache_file" ]] || [[ "$tool_bin" -nt "$cache_file" ]]; then
       stale_caches=$((stale_caches + 1))
-      # Track unique tool names for the summary
       case "$stale_tools" in
         *"$tool"*) ;;
         *) stale_tools="${stale_tools:+$stale_tools, }$tool" ;;
       esac
-      break # one stale shell is enough to flag the tool
+      break
     fi
   done
 done
-
 if [[ $stale_caches -eq 0 ]]; then
   _ok "shell caches" "fresh"
 else
   _warn "shell caches" "stale ($stale_tools) — run dot prewarm"
 fi
 
+# 2. Slow-init tools that are present but NOT wrapped in _cached_eval.
+# Each of these runs uncached on every shell start; common offenders eat
+# 100-500ms apiece on a populated dev machine.
+unwrapped=""
+for tool in nvm fnm pyenv rbenv jenv asdf sdkman conda kubectl helm gh cargo pnpm yarn thefuck broot mcfly; do
+  command -v "$tool" >/dev/null 2>&1 || continue
+  found=0
+  for shell_dir in zsh bash fish; do
+    case "$shell_dir" in
+      fish) [[ -f "$cache_base/$shell_dir/${tool}-init.fish" ]] && found=1 ;;
+      *) [[ -f "$cache_base/$shell_dir/${tool}-init.$shell_dir" ]] && found=1 ;;
+    esac
+    ((found == 1)) && break
+  done
+  ((found == 0)) && unwrapped="${unwrapped:+$unwrapped, }$tool"
+done
+if [[ -z "$unwrapped" ]]; then
+  _ok "uncached slow-init tools" "none detected"
+else
+  _warn "uncached slow-init tools" "$unwrapped — consider wrapping in _cached_eval"
+fi
+
+# 3. Zsh completion dump health. compinit is usually the single biggest
+# cost on a zsh startup; a stale or uncompiled .zcompdump compounds it.
+if command -v zsh >/dev/null 2>&1; then
+  zcompdump="${HOME}/.zcompdump"
+  if [[ -f "$zcompdump" ]]; then
+    dump_mtime=$(stat -c %Y "$zcompdump" 2>/dev/null || stat -f %m "$zcompdump" 2>/dev/null || echo 0)
+    age_days=$((($(date +%s) - dump_mtime) / 86400))
+    if ((age_days > 7)); then
+      _warn ".zcompdump" "${age_days}d old — refresh: rm ~/.zcompdump* && zsh -ic exit"
+    else
+      _ok ".zcompdump" "fresh (${age_days}d)"
+    fi
+    if [[ ! -f "${zcompdump}.zwc" ]]; then
+      _warn ".zcompdump.zwc" "missing — completion init slower than necessary"
+    fi
+  fi
+fi
+
+# 4. PATH length. Each entry is searched on every command resolution;
+# >40 entries is noticeably slow on cold-cache filesystems.
+path_count=$(printf '%s' "${PATH:-}" | tr ':' '\n' | grep -c . || true)
+if [[ "$path_count" -le 40 ]]; then
+  _ok "PATH length" "$path_count entries"
+elif [[ "$path_count" -le 80 ]]; then
+  _warn "PATH length" "$path_count entries — consider pruning"
+else
+  _fail "PATH length" "$path_count entries — likely slowing every command"
+fi
+
+# 5. Shell coverage. Surface installed shells that the project's caching
+# infrastructure (zsh/bash/fish) doesn't currently maintain caches for.
+shells_unmanaged=""
+for sh in nu pwsh; do
+  command -v "$sh" >/dev/null 2>&1 && shells_unmanaged="${shells_unmanaged:+$shells_unmanaged, }$sh"
+done
+if [[ -z "$shells_unmanaged" ]]; then
+  _ok "shell coverage" "all installed shells (zsh/bash/fish) are managed"
+else
+  _warn "shell coverage" "$shells_unmanaged installed — startup not measured by dot perf"
+fi
+
+# 6. Zsh hook count. Heavy precmd/preexec functions compound per-prompt.
+# Probe an interactive zsh with a hard timeout so a broken zshrc doesn't
+# stall doctor; skip cleanly if the probe fails.
+if command -v zsh >/dev/null 2>&1 && command -v timeout >/dev/null 2>&1; then
+  hook_counts=$(timeout 5 zsh -i -c 'echo "$#precmd_functions $#preexec_functions"' 2>/dev/null || echo "")
+  if [[ -n "$hook_counts" ]]; then
+    read -r precmd_n preexec_n <<<"$hook_counts"
+    if [[ "${precmd_n:-0}" -le 5 && "${preexec_n:-0}" -le 5 ]]; then
+      _ok "zsh hooks" "precmd=$precmd_n preexec=$preexec_n"
+    else
+      _warn "zsh hooks" "precmd=$precmd_n preexec=$preexec_n — heavy per-prompt work"
+    fi
+  fi
+fi
+
 if command -v hyperfine >/dev/null 2>&1; then
   if bash "$SCRIPT_DIR/../../tests/performance/bench.sh" 2>/dev/null; then
     _ok "startup latency" "within target thresholds"
@@ -512,6 +633,53 @@ else
   _warn "hyperfine" "missing (benchmark skipped)"
 fi
 
+# 7. Baseline check + top-3 slowest tools from EVALCACHE_TIMING.
+# Closes part of #863. Reads the same baseline file `dot perf` writes,
+# and the same eval-timings.jsonl _cached_eval populates. Skipped
+# silently when either file is absent (first-run state).
+baseline_file="$cache_base/dotfiles/perf-baseline.json"
+if [[ -s "$baseline_file" ]] && command -v python3 >/dev/null 2>&1; then
+  baseline_age_days=$(python3 -c '
+import json, sys, datetime
+try:
+    d = json.load(open(sys.argv[1]))
+    rec = d.get("recorded_at", "")
+    if not rec: print(-1); sys.exit(0)
+    rec = rec.replace("Z", "+00:00")
+    age = (datetime.datetime.now(datetime.timezone.utc) - datetime.datetime.fromisoformat(rec)).days
+    print(age)
+except Exception:
+    print(-1)
+' "$baseline_file" 2>/dev/null)
+  if [[ "$baseline_age_days" -ge 0 ]]; then
+    _ok "perf baseline" "recorded ${baseline_age_days}d ago — run \`dot perf\` to compare"
+  fi
+fi
+
+timings_file="${XDG_STATE_HOME:-$HOME/.local/state}/dotfiles/eval-timings.jsonl"
+if [[ -s "$timings_file" ]] && command -v python3 >/dev/null 2>&1; then
+  top_tools=$(python3 -c '
+import json, sys
+from collections import defaultdict
+samples = defaultdict(list)
+try:
+    for line in open(sys.argv[1]):
+        try:
+            ev = json.loads(line)
+            ms = int(ev.get("ms", 0) or 0)
+            samples[ev.get("label", "?")].append(ms)
+        except Exception:
+            pass
+    rows = sorted(samples.items(), key=lambda kv: sum(kv[1]) // max(len(kv[1]), 1), reverse=True)[:3]
+    print(", ".join(f"{lbl}({sum(v)//max(len(v),1)}ms)" for lbl, v in rows))
+except Exception:
+    pass
+' "$timings_file" 2>/dev/null)
+  if [[ -n "$top_tools" ]]; then
+    _ok "perf top-tools" "$top_tools"
+  fi
+fi
+
 # --- Summary ---
 dot_log info "doctor_complete" "errors=$Errors" "warnings=$Warnings"
 dot_metric "doctor_errors" "$Errors" "count"