@sebastienrousseau/dotfiles 0.2.508 → 0.2.511

package/scripts/qa/examples-coverage.sh

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2015-2026 Sebastien Rousseau
+# =============================================================================
+# examples-coverage.sh — enforce that every core feature domain ships a
+# runnable example under examples/. Mirrors scripts/qa/docs-coverage.sh:
+# it is a *coverage contract*, not a linter. Threshold defaults to 100%.
+#
+# A feature domain is "covered" when examples/example-<domain>.sh exists.
+# Keep REQUIRED_AREAS in lockstep with the feature surface — adding a major
+# user-facing capability (a new `dot` subsystem) means adding its example.
+# =============================================================================
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="${REPO_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
+EXAMPLES_DIR="$REPO_ROOT/examples"
+DOT_CLI="$REPO_ROOT/bin/dot"
+MIN_EXAMPLES_COVERAGE="${MIN_EXAMPLES_COVERAGE:-100}"
+
+# Public commands/subcommands, extracted from bin/dot's _dot_help_specs — the
+# same source scripts/qa/docs-coverage.sh uses, so docs and examples stay in
+# lockstep at the command granularity.
+extract_public_commands() {
+  awk -F'|' '
+    /_dot_help_specs\(\)/ { in_func=1; next }
+    in_func && /cat <<'\''EOF'\''/ { in_block=1; next }
+    in_block && /^EOF$/ { exit }
+    in_block && NF>=2 { print $2 }
+  ' "$DOT_CLI"
+}
+
+# Core feature domains that must each have examples/example-<area>.sh.
+REQUIRED_AREAS=(
+  ai-patterns
+  cli-utilities
+  coverage-gate
+  diagnostics
+  dot-commands
+  functions
+  fleet
+  git-hooks
+  install-uninstall
+  ops
+  platform-contract
+  qa
+  secrets
+  security
+  test-suite
+  testing-framework
+  theme
+)
+
+total=0
+covered=0
+missing=()
+
+# --- Check 1: every feature domain has a dedicated example file. ---
+for area in "${REQUIRED_AREAS[@]}"; do
+  total=$((total + 1))
+  if [ -f "$EXAMPLES_DIR/example-$area.sh" ]; then
+    covered=$((covered + 1))
+  else
+    missing+=("domain:$area")
+  fi
+done
+
+# --- Check 2: every public command/subcommand is referenced in an example. ---
+while IFS= read -r cmd; do
+  [ -n "$cmd" ] || continue
+  total=$((total + 1))
+  # "dot <cmd>" followed by a non-identifier char (or EOL) — avoids matching
+  # `dot ai` against `dot ai-query`, and matches printf '...\n'-terminated refs.
+  if grep -rqE "dot ${cmd}([^A-Za-z0-9_-]|\$)" "$EXAMPLES_DIR" 2>/dev/null; then
+    covered=$((covered + 1))
+  else
+    missing+=("cmd:$cmd")
+  fi
+done < <(extract_public_commands | sort -u)
+
+pct="$(awk -v c="$covered" -v t="$total" \
+  'BEGIN{if(t==0){print "0.00"}else{printf "%.2f", (100*c/t)}}')"
+printf 'Examples coverage: %s/%s (%s%%)\n' "$covered" "$total" "$pct"
+printf 'Threshold: %s%%\n' "$MIN_EXAMPLES_COVERAGE"
+if [ "${#missing[@]}" -gt 0 ]; then
+  printf 'Missing coverage for: %s\n' "${missing[*]}" >&2
+fi
+
+if awk -v p="$pct" -v min="$MIN_EXAMPLES_COVERAGE" 'BEGIN{exit !(p+0 >= min+0)}'; then
+  printf 'PASS: every feature domain and every public command has an example.\n'
+  exit 0
+fi
+printf 'FAIL: examples coverage %s%% is below the %s%% threshold.\n' "$pct" "$MIN_EXAMPLES_COVERAGE" >&2
+exit 1

package/scripts/tools/detect-collisions.py

@@ -8,7 +8,25 @@ import os
 import re
 import sys
 
-BASE_DIR = os.path.expanduser("~/.dotfiles/.chezmoitemplates")
+# Post-Phase-4b (v0.2.503): chezmoi source is under the subdir
+# named in .chezmoiroot (typically "defaults/"). Prefer the
+# descended path; fall back to the old top-level layout for
+# backwards compatibility.
+_DOTFILES_ROOT = os.path.expanduser("~/.dotfiles")
+_CHEZMOIROOT_FILE = os.path.join(_DOTFILES_ROOT, ".chezmoiroot")
+
+
+def _resolve_chezmoi_root() -> str:
+    if os.path.isfile(_CHEZMOIROOT_FILE):
+        with open(_CHEZMOIROOT_FILE, "r", encoding="utf-8") as _f:
+            sub = _f.read().strip()
+        cand = os.path.join(_DOTFILES_ROOT, sub)
+        if os.path.isdir(cand):
+            return cand
+    return _DOTFILES_ROOT
+
+
+BASE_DIR = os.path.join(_resolve_chezmoi_root(), ".chezmoitemplates")
 ALIASES_DIR = os.path.join(BASE_DIR, "aliases")
 FUNCTIONS_DIR = os.path.join(BASE_DIR, "functions")
 

package/scripts/version-sync.sh

@@ -78,6 +78,19 @@ EXCLUDE_FILES=(
   # CI_COMPOSITES.md cites third-party action versions (e.g. v5.0.5),
   # not dotfiles_version. False-positive pattern match.
   "docs/operations/CI_COMPOSITES.md"
+
+  # Living roadmap: references branch names / target versions
+  # (e.g. feature-branch names like feat/v0.2.X, phase milestones)
+  # that are NOT the current dotfiles_version. Auto-syncing
+  # rewrites them incorrectly.
+  "docs/operations/ARCHITECTURE_ROADMAP.md"
+
+  # Dated release write-ups: each article records the release it
+  # shipped in (e.g. "shipped in v0.2.510" + a link to that release
+  # tag). Those refs are historical fact, not current-version claims —
+  # bumping them would falsify the history.
+  "docs/articles/2026-07-05-fish-startup-abbr.md"
+  "docs/articles/2026-07-05-master-to-main-rename-runbook.md"
 )
 
 # shellcheck source=../lib/dot/ui.sh
@@ -180,6 +193,16 @@ find_version_files() {
   echo "docs/reference/FEATURES.md" >>"$temp_file"
   echo "docs/COPYRIGHT" >>"$temp_file"
 
+  # Non-markdown and hidden-directory surfaces rg's `--type md` scan above
+  # cannot reach: a shell script, and READMEs under the dotfile-hidden
+  # `.chezmoitemplates/` tree (rg skips dot-dirs without --hidden). These
+  # carry "current version" stamps that check-version-consistency.sh and
+  # the test_version_consistency unit test enforce, so keep them in sync.
+  echo "scripts/git-hooks/pre-commit-audit.sh" >>"$temp_file"
+  echo "defaults/.chezmoitemplates/README.md" >>"$temp_file"
+  echo "defaults/.chezmoitemplates/functions/README.md" >>"$temp_file"
+  echo "defaults/.chezmoitemplates/aliases/README.md" >>"$temp_file"
+
   # Remove duplicates and filter existing files
   sort -u "$temp_file" | while IFS= read -r file; do
     if [[ -f "$file" ]]; then
@@ -257,8 +280,11 @@ update_version_references() {
     temp_file=$(umask 077 && mktemp)
     cp "$file" "$temp_file"
 
-    # Update various version reference patterns
-    case "$(basename "$file")" in
+    # Update various version reference patterns. Match on the full repo
+    # path (not basename) so the root README's badge rules don't also
+    # capture other README.md files (e.g. the .chezmoitemplates READMEs),
+    # which carry a `(vX.Y.Z)` stamp handled by the generic case below.
+    case "$file" in
       "README.md")
         # Update badge and release link versions.
         sed_in_place "$temp_file" \
@@ -266,6 +292,14 @@ update_version_references() {
           -e "s|/releases/tag/v$SED_VERSION_PATTERN|/releases/tag/v$target_version|g" \
           -e "s|/dotfiles/v$SED_VERSION_PATTERN/|/dotfiles/v$target_version/|g"
         ;;
+      "scripts/git-hooks/pre-commit-audit.sh")
+        # "vX.Y.Z standards maintained" banner. Matched explicitly with a
+        # portable pattern — the generic `\bvX.Y.Z\b` rule below relies on
+        # GNU `\b`, which BSD/macOS sed does not support, so a local
+        # `version-sync` run would otherwise leave this script stale.
+        sed_in_place "$temp_file" \
+          -e "s|v$SED_VERSION_PATTERN standards maintained|v$target_version standards maintained|g"
+        ;;
       *)
         # Update explicit markdown version labels, backticks, and parentheses.
         # Skip lines containing MILESTONE.

package/docs/_config.yml

@@ -1,59 +0,0 @@
-title: ".dotfiles"
-description: "Cross-platform, signed, local-first dotfiles for macOS, Linux, and WSL — published at doc.dotfiles.io."
-url: "https://doc.dotfiles.io"
-baseurl: ""
-
-# Jekyll renders this site from docs/ — see .github/workflows/pages.yml.
-# Theme is the GitHub-hosted Cayman skin (zero-Gemfile setup); switch to
-# `remote_theme: just-the-docs/just-the-docs` later if a richer
-# navigation/search UX is wanted (requires plugin allowlist update on
-# GH Pages side).
-theme: jekyll-theme-cayman
-
-plugins:
-  - jekyll-relative-links
-  - jekyll-seo-tag
-  - jekyll-sitemap
-  - jekyll-redirect-from
-  # Renders `README.md` as the directory index where present (matches
-  # the GitHub-browse experience for users coming from the repo links
-  # in docs/index.md).
-  - jekyll-readme-index
-
-relative_links:
-  enabled: true
-  collections: true
-
-# Treat *.md as pages so cross-page links work without trailing-slash
-# kludges; include CNAME so the published artifact preserves it across
-# workflow deploys.
-include:
-  - CNAME
-  - .well-known
-
-exclude:
-  - "*.tmpl"
-  - "manual/_toc.yml"
-  - "scripts/"
-  - "Gemfile"
-  - "Gemfile.lock"
-  - "vendor/"
-
-markdown: kramdown
-kramdown:
-  input: GFM
-  syntax_highlighter: rouge
-  hard_wrap: false
-
-# Many of our docs include chezmoi/Go-template snippets like
-# `{{ .variable }}` inside fenced code blocks. Liquid runs BEFORE
-# kramdown sees those fences and would try to resolve the placeholders
-# as Liquid expressions (silently dropping them from the output). Each
-# .md file therefore carries explicit `render_with_liquid: false` in
-# its frontmatter — a site-wide default in this block was not honored
-# reliably, so we keep the kill-switch per-page instead.
-defaults:
-  - scope:
-      path: ""
-    values:
-      layout: default