@thebassclef/lite 1.0.3 → 1.1.0

package/dist/lite/lib/source-graph-walker.sh

@@ -0,0 +1,277 @@
+#!/usr/bin/env bash
+# tier: lite
+# install-class: dual
+#
+# lib/source-graph-walker.sh — walks source-graph closure from a seed hook
+#
+# @pattern patterns/code/gof/composite.md
+# Traverses a tree of file references (source + dot-source + glob-source).
+#
+# @pattern patterns/code/ousterhout/deep-module.md
+# Narrow interface — walk_source_dependents(hook_path) hides ref extraction +
+# path resolution + fixed-point iteration + glob expansion inside the module.
+#
+# Contract (Hoare):
+# - Precondition: hook_path exists and is readable
+# - Postcondition (success): stdout is newline-separated list of ABSENT
+#   dependents (empty means all dependents resolve) + exit 0
+# - Postcondition (failure): non-zero exit + stderr names the reason
+# - Silent-fail per ADR-050 R7 on file-read errors
+#
+# @luminary vaughn-vernon (anticorruption layer between wired hook set
+#                          and actual dependency graph)
+#
+# Per docs/decompositions/2026-09-15-install-class-dispatch.md
+# Per goal docs/iteration-bets/2026-09-14c-install-class-dispatch-plus-walker-runtime.md
+#
+# NOTE: This IS the single walker implementation. `scripts/build-adopter-tree.sh`
+# sources this lib at build time (retired its copy at goal 2026-09-14c Step 5.0
+# per #1663 + ADR-058 c5). `lib/hook-installer.sh` sources it at install time
+# via `install_by_class`. One implementation, three callers (build script,
+# install-time lib, tests). See architecture/reviews/2026-09-15.md F2.
+
+set -euo pipefail
+
+# REPO_ROOT — inferred from lib/ location if unset
+if [ -z "${REPO_ROOT:-}" ]; then
+  REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+fi
+
+# Per-process walker cache — O-F2 cure (2026-09-15c architect-review).
+# Ousterhout ch. 8 (Pull Complexity Downward) — callers stay simple; the
+# lib absorbs the "run once per hook per process" decision. First call
+# for a hook path runs the real walker; later calls return cached
+# result. Cache holds OK paths only — failed walks re-run each time (rare
+# case; not worth caching). Cache file is per-process; trap EXIT cleans up.
+_SGW_CACHE=""
+
+_sgw_init_cache() {
+  if [ -z "${_SGW_CACHE:-}" ]; then
+    _SGW_CACHE=$(mktemp -t bassclef-sgw.XXXXXX 2>/dev/null || echo "")
+    if [ -n "$_SGW_CACHE" ]; then
+      # shellcheck disable=SC2064  # expand $_SGW_CACHE at trap-set time
+      trap "[ -f '$_SGW_CACHE' ] && rm -f '$_SGW_CACHE'" EXIT
+    fi
+  fi
+}
+
+# Extract every .sh literal ref from a shell file — the walker's resolve
+# step filters to only paths that map to real files, so false-positive
+# extractions are cheap.
+_sgw_extract_all_refs() {
+  local file="$1"
+
+  # 1. Every .sh literal in the file (quoted or path-shaped), from non-comment lines
+  grep -vE '^[[:space:]]*#' "$file" 2>/dev/null | \
+    grep -oE '"[^"]+\.sh"|'"'"'[^'"'"']+\.sh'"'"'|\$\{[^}]+\}/[^"'"'"'[:space:]]+\.sh|[$][A-Za-z_][A-Za-z0-9_]*/[^"'"'"'[:space:]]+\.sh|(\./|\.\./|/)[^"'"'"'[:space:]$]+\.sh' 2>/dev/null | \
+    tr -d '"'"'"'"' | \
+    sort -u
+
+  # 2. Glob-source patterns — for loops iterating dir/*.sh
+  grep -oE 'for[[:space:]]+[[:alnum:]_]+[[:space:]]+in[[:space:]]+[^;$]+/\*\.sh' "$file" 2>/dev/null | \
+    sed -E 's/.*[[:space:]]+in[[:space:]]+([^*]+)\*\.sh/\1__GLOB__/' 2>/dev/null
+}
+
+# Resolve a raw ref to an absolute repo path. Empty on unresolvable OR
+# when the resolved path does not exist. Substitutes common bassclef vars.
+_sgw_resolve_ref_in_repo() {
+  local src_file="$1"
+  local ref="$2"
+
+  local src_dir
+  src_dir="$(dirname "$src_file")"
+
+  local resolved="$ref"
+  resolved="${resolved//\$SCRIPT_DIR/$src_dir}"
+  resolved="${resolved//\$\{SCRIPT_DIR\}/$src_dir}"
+  resolved="${resolved//\$\{SCRIPT_DIR:-.\}/$src_dir}"
+  resolved="${resolved//\$CWD/$REPO_ROOT}"
+  resolved="${resolved//\$\{CWD\}/$REPO_ROOT}"
+  resolved="${resolved//\$BASSCLEF_DIR/$REPO_ROOT}"
+  resolved="${resolved//\$\{BASSCLEF_DIR\}/$REPO_ROOT}"
+  resolved="${resolved//\$\{BASSCLEF_DIR:-\}/$REPO_ROOT}"
+  resolved="${resolved//\$\{BASSCLEF_DIR:-.\}/$REPO_ROOT}"
+  resolved="${resolved//\$REPO_ROOT/$REPO_ROOT}"
+  resolved="${resolved//\$\{REPO_ROOT\}/$REPO_ROOT}"
+  resolved="${resolved//\$HOME/$REPO_ROOT}"
+  resolved="${resolved//\$\{HOME\}/$REPO_ROOT}"
+  resolved="${resolved//\$\{HOME:-/\}/$REPO_ROOT}"
+  resolved="${resolved//\$\{HOME_OVERRIDE:-\$\{HOME:-/\}\}/$REPO_ROOT}"
+
+  # Handle __GLOB__ marker (dir with trailing slash) BEFORE the $-check
+  if echo "$resolved" | grep -q '__GLOB__$'; then
+    local dir="${resolved%__GLOB__}"
+    dir="${dir%/}"
+    local normalized_dir
+    normalized_dir="$(cd "$dir" 2>/dev/null && pwd)" || {
+      echo ""
+      return 0
+    }
+    echo "${normalized_dir}/__GLOB__"
+    return 0
+  fi
+
+  # If still has unresolved variables, fall back to suffix extraction
+  if echo "$resolved" | grep -qE '\$'; then
+    local suffix
+    suffix="$(echo "$resolved" | grep -oE '(/lib/|/hooks/(_lib/)?)[[:alnum:]_-]+\.sh$' | head -1)"
+    if [ -n "$suffix" ]; then
+      resolved="${REPO_ROOT}${suffix}"
+    else
+      echo ""
+      return 0
+    fi
+  fi
+
+  if [ "${resolved:0:1}" != "/" ]; then
+    resolved="${REPO_ROOT}/${resolved}"
+  fi
+
+  # Normalize the path; only if the file exists
+  local normalized
+  normalized="$(cd "$(dirname "$resolved")" 2>/dev/null && pwd)/$(basename "$resolved")" || {
+    echo ""
+    return 0
+  }
+
+  if [ ! -f "$normalized" ]; then
+    echo ""
+    return 0
+  fi
+
+  echo "$normalized"
+}
+
+# Walk the source-graph closure from a seed file set. Returns every file
+# reachable from the seeds via source/dot-source/bash-invoke/glob-source.
+# Fixed-point iteration using a temp file for O(1) seen-lookup.
+# Explicit cleanup at every return path (no RETURN trap — bad interaction
+# with subshell + set -e).
+_sgw_walk_source_closure() {
+  local seen_file
+  seen_file="$(mktemp -t bassclef-sgw-seen.XXXXXX)"
+
+  local -a queue
+  # Guard against empty $@ under set -u (bash 3.2)
+  if [ $# -gt 0 ]; then
+    queue=("$@")
+  else
+    queue=()
+  fi
+
+  while [ "${#queue[@]}" -gt 0 ]; do
+    local current="${queue[0]}"
+    # Shift front — safe under bash 3.2
+    if [ "${#queue[@]}" -gt 1 ]; then
+      queue=("${queue[@]:1}")
+    else
+      queue=()
+    fi
+    [ -z "$current" ] && continue
+
+    # Skip if already seen
+    if grep -qFx "$current" "$seen_file" 2>/dev/null; then
+      continue
+    fi
+    echo "$current" >> "$seen_file"
+
+    # If __GLOB__ marker — expand to all *.sh in dir and enqueue each
+    if [ "${current: -8}" = "__GLOB__" ]; then
+      local dir="${current%__GLOB__}"
+      dir="${dir%/}"
+      if [ -d "$dir" ]; then
+        while IFS= read -r f; do
+          queue+=("$f")
+        done < <(find "$dir" -maxdepth 1 -name '*.sh' -type f)
+      fi
+      continue
+    fi
+
+    [ ! -f "$current" ] && continue
+
+    while IFS= read -r ref; do
+      [ -z "$ref" ] && continue
+      local resolved
+      resolved="$(_sgw_resolve_ref_in_repo "$current" "$ref")"
+      if [ -n "$resolved" ] && ! grep -qFx "$resolved" "$seen_file" 2>/dev/null; then
+        queue+=("$resolved")
+      fi
+    done < <(_sgw_extract_all_refs "$current")
+  done
+
+  # Emit seen paths (real files; skip glob markers)
+  grep -v '__GLOB__$' "$seen_file" 2>/dev/null | sort -u
+
+  # Explicit cleanup (no RETURN trap)
+  rm -f "$seen_file"
+}
+
+# Public: walk_source_dependents(hook_path)
+#
+# Returns newline-separated list of MISSING dependents (files the hook
+# references via source/bash-invoke that don't exist on disk). Empty
+# output means all dependents resolve. Non-zero exit means the hook
+# itself is unreadable OR the graph traversal errored.
+walk_source_dependents() {
+  local hook_path="$1"
+
+  if [ ! -f "$hook_path" ] || [ ! -r "$hook_path" ]; then
+    echo "walk_source_dependents: hook_path not readable: $hook_path" >&2
+    return 1
+  fi
+
+  # Cache check — O-F2 cure. Return cached OK result without re-scanning.
+  _sgw_init_cache
+  if [ -n "$_SGW_CACHE" ] && grep -qFx "$hook_path" "$_SGW_CACHE" 2>/dev/null; then
+    return 0
+  fi
+
+  # Scan direct references from the hook file (non-recursive; check each
+  # direct dependent's existence). Full closure walk is available via
+  # _sgw_walk_source_closure for callers that need it (e.g., build script).
+  local missing=()
+  local ref resolved
+  while IFS= read -r ref; do
+    [ -z "$ref" ] && continue
+    resolved="$(_sgw_resolve_ref_in_repo "$hook_path" "$ref")"
+    if [ -z "$resolved" ]; then
+      # Try to extract the raw ref path for the missing report
+      local raw_path
+      raw_path=$(echo "$ref" | tr -d '"'"'"'"')
+      # Skip refs with unresolvable vars (runtime-fetched paths per ADR-050)
+      if echo "$raw_path" | grep -qE '\$'; then
+        continue
+      fi
+      # Skip glob markers
+      if echo "$raw_path" | grep -q '__GLOB__$'; then
+        continue
+      fi
+      # Skip refs that map to non-repo absolute paths (runtime env only)
+      if [ "${raw_path:0:1}" = "/" ] && [ ! -f "$raw_path" ]; then
+        # Ref that starts with / but doesn't exist — this IS a missing dependent
+        missing+=("$raw_path")
+      fi
+    fi
+  done < <(_sgw_extract_all_refs "$hook_path")
+
+  if [ ${#missing[@]} -gt 0 ]; then
+    printf '%s\n' "${missing[@]}"
+    return 1
+  fi
+
+  # Cache write — store OK path so later calls return fast.
+  if [ -n "$_SGW_CACHE" ]; then
+    echo "$hook_path" >> "$_SGW_CACHE" 2>/dev/null || true
+  fi
+  return 0
+}
+
+# Public: walk_source_closure(seed_files...) — full transitive closure
+# Callers that need the transitive dependency set (build script) use this.
+walk_source_closure() {
+  _sgw_walk_source_closure "$@"
+}
+
+# Export for callers
+export -f walk_source_dependents 2>/dev/null || true
+export -f walk_source_closure 2>/dev/null || true