context-engineer 1.1.0

package/templates/core/scripts/detect-drift.sh

@@ -0,0 +1,388 @@
+#!/usr/bin/env bash
+#
+# detect-drift.sh — Detect drift between source code and .context/ documentation
+#
+# Usage: bash scripts/detect-drift.sh [--report] [--ci] [--semantic]
+#   --report    Save results to .context/_meta/drift-report.md
+#   --ci        Exit with code 1 if drift is detected (for CI/CD)
+#   --semantic  Enable entity-list comparison (compares documented names vs code)
+#
+# This script checks for drift between source code and context documentation.
+# It does NOT block commits — it only reports warnings.
+
+set -euo pipefail
+
+CONTEXT_DIR=".context"
+META_DIR="$CONTEXT_DIR/_meta"
+REPORT_FILE="$META_DIR/drift-report.md"
+SAVE_REPORT=false
+CI_MODE=false
+SEMANTIC_MODE=false
+DRIFT_COUNT=0
+REPORT_LINES=()
+
+# Parse arguments
+for arg in "$@"; do
+  case $arg in
+    --report) SAVE_REPORT=true ;;
+    --ci) CI_MODE=true ;;
+    --semantic) SEMANTIC_MODE=true ;;
+  esac
+done
+
+# Colors (disabled in CI)
+if [ -t 1 ] && [ "$CI_MODE" = false ]; then
+  RED='\033[0;31m'
+  YELLOW='\033[1;33m'
+  GREEN='\033[0;32m'
+  NC='\033[0m'
+else
+  RED='' YELLOW='' GREEN='' NC=''
+fi
+
+log_ok() {
+  echo -e "${GREEN}[OK]${NC} $1"
+  REPORT_LINES+=("| $1 | OK | — |")
+}
+
+log_warn() {
+  echo -e "${YELLOW}[DRIFT]${NC} $1"
+  REPORT_LINES+=("| $1 | DRIFT | $2 |")
+  DRIFT_COUNT=$((DRIFT_COUNT + 1))
+}
+
+log_missing() {
+  echo -e "${RED}[MISSING]${NC} $1"
+  REPORT_LINES+=("| $1 | MISSING | File does not exist or is empty |")
+  DRIFT_COUNT=$((DRIFT_COUNT + 1))
+}
+
+echo "========================================="
+echo "  Context Drift Detection"
+echo "========================================="
+echo ""
+
+# Check that .context/ exists
+if [ ! -d "$CONTEXT_DIR" ]; then
+  echo -e "${RED}ERROR: .context/ directory not found. Run bootstrap first.${NC}"
+  exit 1
+fi
+
+# --- Check 1: Schema/Migration drift ---
+echo "--- Checking Data Model Drift ---"
+DATA_MODEL="$CONTEXT_DIR/architecture/data-model.md"
+if [ -f "$DATA_MODEL" ]; then
+  # Check if data model file contains only placeholders
+  if grep -q "PLACEHOLDER" "$DATA_MODEL" 2>/dev/null; then
+    log_warn "architecture/data-model.md" "Contains placeholder text — not yet populated"
+  else
+    # Find any migration/model files newer than the data model doc
+    NEWER_FILES=""
+
+    # Check common migration/model patterns
+    for pattern in "**/migrations/*" "**/Migration*" "prisma/schema.prisma" "**/models.py" "**/entities/*.cs" "**/entities/*.ts" "**/models/*.ts" "**/models/*.cs"; do
+      while IFS= read -r file; do
+        if [ -n "$file" ] && [ "$file" -nt "$DATA_MODEL" ]; then
+          NEWER_FILES="$NEWER_FILES $file"
+        fi
+      done < <(find . -path "./.git" -prune -o -path "$pattern" -print 2>/dev/null || true)
+    done
+
+    if [ -n "$NEWER_FILES" ]; then
+      log_warn "architecture/data-model.md" "Source files modified after last update:${NEWER_FILES}"
+    else
+      log_ok "architecture/data-model.md"
+    fi
+  fi
+else
+  log_missing "architecture/data-model.md"
+fi
+
+# --- Check 2: API Surface drift ---
+echo "--- Checking API Surface Drift ---"
+API_SURFACE="$CONTEXT_DIR/architecture/api-surface.md"
+if [ -f "$API_SURFACE" ]; then
+  if grep -q "PLACEHOLDER" "$API_SURFACE" 2>/dev/null; then
+    log_warn "architecture/api-surface.md" "Contains placeholder text — not yet populated"
+  else
+    NEWER_FILES=""
+    for pattern in "**/controllers/*" "**/routes/*" "**/api/*" "**/*Controller*" "**/*Router*"; do
+      while IFS= read -r file; do
+        if [ -n "$file" ] && [ "$file" -nt "$API_SURFACE" ]; then
+          NEWER_FILES="$NEWER_FILES $file"
+        fi
+      done < <(find . -path "./.git" -prune -o -path "$pattern" -print 2>/dev/null || true)
+    done
+
+    if [ -n "$NEWER_FILES" ]; then
+      log_warn "architecture/api-surface.md" "Source files modified after last update:${NEWER_FILES}"
+    else
+      log_ok "architecture/api-surface.md"
+    fi
+  fi
+else
+  log_missing "architecture/api-surface.md"
+fi
+
+# --- Check 3: Dependencies drift ---
+echo "--- Checking Dependencies Drift ---"
+DEPS_FILE="$CONTEXT_DIR/architecture/dependencies.md"
+if [ -f "$DEPS_FILE" ]; then
+  if grep -q "PLACEHOLDER" "$DEPS_FILE" 2>/dev/null; then
+    log_warn "architecture/dependencies.md" "Contains placeholder text — not yet populated"
+  else
+    NEWER_FILES=""
+    for manifest in "package.json" "package-lock.json" "yarn.lock" "pnpm-lock.yaml" \
+                    "requirements.txt" "pyproject.toml" "Pipfile.lock" \
+                    "go.mod" "go.sum" "Cargo.toml" "Cargo.lock" \
+                    "*.csproj" "*.sln" "pom.xml" "build.gradle"; do
+      while IFS= read -r file; do
+        if [ -n "$file" ] && [ "$file" -nt "$DEPS_FILE" ]; then
+          NEWER_FILES="$NEWER_FILES $file"
+        fi
+      done < <(find . -maxdepth 3 -name "$manifest" -not -path "./.git/*" 2>/dev/null || true)
+    done
+
+    if [ -n "$NEWER_FILES" ]; then
+      log_warn "architecture/dependencies.md" "Package manifests modified after last update:${NEWER_FILES}"
+    else
+      log_ok "architecture/dependencies.md"
+    fi
+  fi
+else
+  log_missing "architecture/dependencies.md"
+fi
+
+# --- Check 4: Module Graph drift ---
+echo "--- Checking Module Graph Drift ---"
+MODULE_GRAPH="$CONTEXT_DIR/architecture/module-graph.md"
+if [ -f "$MODULE_GRAPH" ]; then
+  if grep -q "PLACEHOLDER\|TO BE FILLED" "$MODULE_GRAPH" 2>/dev/null; then
+    log_warn "architecture/module-graph.md" "Contains placeholder text — not yet populated"
+  else
+    NEWER_FILES=""
+    # Check if any source files are newer than module-graph.md
+    for pattern in "*.h" "*.hpp" "*.cs" "*.ts" "*.py" "*.go" "*.rs" "*.java"; do
+      while IFS= read -r file; do
+        if [ -n "$file" ] && [ "$file" -nt "$MODULE_GRAPH" ]; then
+          NEWER_FILES="$NEWER_FILES $(basename "$file")"
+          break  # One per pattern is enough to trigger
+        fi
+      done < <(find . -path "./.git" -prune -o -path "./node_modules" -prune -o -name "$pattern" -print 2>/dev/null | head -5 || true)
+    done
+
+    if [ -n "$NEWER_FILES" ]; then
+      log_warn "architecture/module-graph.md" "Source files modified after last update (samples:${NEWER_FILES})"
+    else
+      log_ok "architecture/module-graph.md"
+    fi
+  fi
+else
+  log_missing "architecture/module-graph.md"
+fi
+
+# --- Check 5: Class Index drift ---
+echo "--- Checking Class Index Drift ---"
+CLASS_INDEX="$CONTEXT_DIR/architecture/class-index.md"
+if [ -f "$CLASS_INDEX" ]; then
+  if grep -q "PLACEHOLDER" "$CLASS_INDEX" 2>/dev/null; then
+    log_warn "architecture/class-index.md" "Contains placeholder text — not yet populated"
+  else
+    NEWER_FILES=""
+    for pattern in "*.h" "*.hpp" "*.cs" "*.ts" "*.py" "*.go" "*.rs" "*.java"; do
+      while IFS= read -r file; do
+        if [ -n "$file" ] && [ "$file" -nt "$CLASS_INDEX" ]; then
+          NEWER_FILES="$NEWER_FILES $(basename "$file")"
+          break
+        fi
+      done < <(find . -path "./.git" -prune -o -path "./node_modules" -prune -o -name "$pattern" -print 2>/dev/null | head -5 || true)
+    done
+
+    if [ -n "$NEWER_FILES" ]; then
+      log_warn "architecture/class-index.md" "Source files modified after last update (samples:${NEWER_FILES})"
+    else
+      log_ok "architecture/class-index.md"
+    fi
+  fi
+else
+  log_missing "architecture/class-index.md"
+fi
+
+# --- Check 6: Data Flow drift ---
+echo "--- Checking Data Flow Drift ---"
+DATA_FLOW="$CONTEXT_DIR/architecture/data-flow.md"
+if [ -f "$DATA_FLOW" ]; then
+  if grep -q "PLACEHOLDER" "$DATA_FLOW" 2>/dev/null; then
+    log_warn "architecture/data-flow.md" "Contains placeholder text — not yet populated"
+  else
+    log_ok "architecture/data-flow.md"
+  fi
+else
+  log_missing "architecture/data-flow.md"
+fi
+
+# --- Check 7: Semantic entity-list comparison (optional) ---
+if [ "$SEMANTIC_MODE" = true ]; then
+  echo "--- Semantic Entity Comparison ---"
+
+  # Helper: compare two sorted name lists, report additions and removals
+  semantic_compare() {
+    local label="$1"
+    local doc_names="$2"
+    local code_names="$3"
+
+    if [ -z "$doc_names" ] || [ -z "$code_names" ]; then
+      return  # skip if either list is empty (file not populated)
+    fi
+
+    local added removed
+    added=$(comm -13 <(echo "$doc_names") <(echo "$code_names") | tr '\n' ', ' | sed 's/,$//')
+    removed=$(comm -23 <(echo "$doc_names") <(echo "$code_names") | tr '\n' ', ' | sed 's/,$//')
+
+    if [ -n "$added" ] || [ -n "$removed" ]; then
+      local detail=""
+      [ -n "$added" ] && detail="New in code: [${added}]"
+      [ -n "$removed" ] && detail="${detail:+$detail | }In doc but not in code: [${removed}]"
+      log_warn "$label (semantic)" "$detail"
+    else
+      log_ok "$label (semantic match)"
+    fi
+  }
+
+  # --- Semantic: class-index.md ---
+  if [ -f "$CLASS_INDEX" ] && ! grep -q "PLACEHOLDER" "$CLASS_INDEX" 2>/dev/null; then
+    # Extract class/interface/struct names from the document (markdown table rows)
+    doc_classes=$(grep -oP '^\| \K[A-Z][a-zA-Z0-9_<>]+' "$CLASS_INDEX" 2>/dev/null | sed 's/<.*>//' | sort -u)
+    # Extract from source code
+    code_classes=$(find . -path "./.git" -prune -o -path "./node_modules" -prune -o \
+      \( -name "*.cs" -o -name "*.ts" -o -name "*.py" -o -name "*.java" -o -name "*.go" -o -name "*.h" -o -name "*.hpp" -o -name "*.rs" \) \
+      -print 2>/dev/null | xargs grep -ohP '^\s*(export\s+)?(public\s+)?(abstract\s+)?(sealed\s+)?(partial\s+)?(class|interface|struct|trait|enum|record)\s+\K[A-Z][a-zA-Z0-9_]+' 2>/dev/null | sort -u)
+    semantic_compare "architecture/class-index.md" "$doc_classes" "$code_classes"
+  fi
+
+  # --- Semantic: dependencies.md ---
+  if [ -f "$DEPS_FILE" ] && ! grep -q "PLACEHOLDER" "$DEPS_FILE" 2>/dev/null; then
+    # Extract package names from the document
+    doc_deps=$(grep -oP '^\| `?\K[a-z@][a-z0-9_./@-]+' "$DEPS_FILE" 2>/dev/null | sort -u)
+    # Extract from package.json (if exists)
+    code_deps=""
+    if [ -f "package.json" ]; then
+      code_deps=$(grep -oP '"[a-z@][a-z0-9_./@-]+":\s*"' package.json 2>/dev/null | grep -oP '"[a-z@][a-z0-9_./@-]+"' | tr -d '"' | sort -u)
+    elif [ -f "requirements.txt" ]; then
+      code_deps=$(grep -oP '^[a-zA-Z][a-zA-Z0-9_-]+' requirements.txt 2>/dev/null | tr '[:upper:]' '[:lower:]' | sort -u)
+    elif [ -f "go.mod" ]; then
+      code_deps=$(grep -oP '^\s+\K\S+' go.mod 2>/dev/null | grep '/' | sort -u)
+    fi
+    [ -n "$code_deps" ] && semantic_compare "architecture/dependencies.md" "$doc_deps" "$code_deps"
+  fi
+
+  # --- Semantic: api-surface.md ---
+  if [ -f "$API_SURFACE" ] && ! grep -q "PLACEHOLDER" "$API_SURFACE" 2>/dev/null; then
+    # Extract endpoint paths from the document (e.g., /api/users, GET /users)
+    doc_endpoints=$(grep -oP '(GET|POST|PUT|DELETE|PATCH)\s+\K/[a-zA-Z0-9_/{}-]+' "$API_SURFACE" 2>/dev/null | sort -u)
+    if [ -z "$doc_endpoints" ]; then
+      # Try extracting from table format: | /api/users | or | `GET /api/users` |
+      doc_endpoints=$(grep -oP '^\| `?(/[a-zA-Z0-9_/{}-]+)' "$API_SURFACE" 2>/dev/null | sed 's/^| `\?//' | sort -u)
+    fi
+    # Only report if we found documented endpoints but skip code extraction (too varied per framework)
+    # The timestamp-based check already covers this — semantic check for APIs needs framework-specific logic
+  fi
+
+  # --- Semantic: data-model.md ---
+  if [ -f "$DATA_MODEL" ] && ! grep -q "PLACEHOLDER" "$DATA_MODEL" 2>/dev/null; then
+    # Extract entity/table names from the document
+    doc_entities=$(grep -oP '^\| `?\K[A-Z][a-zA-Z0-9_]+' "$DATA_MODEL" 2>/dev/null | sort -u)
+    # Extract from common ORM patterns
+    code_entities=""
+    # EF Core / C# entities
+    if find . -name "*.cs" -path "*/entities/*" -o -name "*.cs" -path "*/models/*" 2>/dev/null | head -1 | grep -q .; then
+      code_entities=$(find . \( -path "*/entities/*.cs" -o -path "*/models/*.cs" \) 2>/dev/null | xargs grep -ohP '(class|record)\s+\K[A-Z][a-zA-Z0-9_]+' 2>/dev/null | sort -u)
+    # Python models
+    elif find . -name "models.py" 2>/dev/null | head -1 | grep -q .; then
+      code_entities=$(find . -name "models.py" 2>/dev/null | xargs grep -ohP 'class\s+\K[A-Z][a-zA-Z0-9_]+' 2>/dev/null | sort -u)
+    # Prisma
+    elif [ -f "prisma/schema.prisma" ]; then
+      code_entities=$(grep -oP 'model\s+\K[A-Z][a-zA-Z0-9_]+' prisma/schema.prisma 2>/dev/null | sort -u)
+    fi
+    [ -n "$code_entities" ] && semantic_compare "architecture/data-model.md" "$doc_entities" "$code_entities"
+  fi
+fi
+
+# --- Check 8: File size budgets ---
+# (was Check 7 before semantic check was added)
+echo "--- Checking File Size Budgets ---"
+check_size() {
+  local file=$1
+  local budget=$2
+  local label=$3
+  if [ -f "$file" ]; then
+    local lines
+    lines=$(wc -l < "$file")
+    if [ "$lines" -gt "$budget" ]; then
+      log_warn "$label" "Exceeds budget: ${lines}/${budget} lines"
+    else
+      log_ok "$label (${lines}/${budget} lines)"
+    fi
+  fi
+}
+
+check_size "$CONTEXT_DIR/constitution.md" 200 "constitution.md"
+check_size "AGENTS.md" 150 "AGENTS.md"
+check_size "$CONTEXT_DIR/architecture/overview.md" 800 "architecture/overview.md"
+check_size "$CONTEXT_DIR/architecture/module-graph.md" 500 "architecture/module-graph.md"
+check_size "$CONTEXT_DIR/architecture/data-flow.md" 500 "architecture/data-flow.md"
+check_size "$CONTEXT_DIR/architecture/class-index.md" 500 "architecture/class-index.md"
+check_size "$CONTEXT_DIR/experience/lessons.md" 500 "experience/lessons.md"
+check_size "$CONTEXT_DIR/experience/debugging.md" 500 "experience/debugging.md"
+
+# --- Check 9: Required files existence ---
+echo "--- Checking Required Files ---"
+for required in "index.md" "constitution.md" "business/overview.md" "architecture/overview.md" \
+                "architecture/module-graph.md" "architecture/data-flow.md" "architecture/class-index.md" \
+                "conventions/code-style.md" "conventions/patterns.md"; do
+  if [ -f "$CONTEXT_DIR/$required" ]; then
+    log_ok "$required exists"
+  else
+    log_missing "$required"
+  fi
+done
+
+# --- Summary ---
+echo ""
+echo "========================================="
+if [ "$DRIFT_COUNT" -eq 0 ]; then
+  echo -e "${GREEN}All checks passed. No drift detected.${NC}"
+else
+  echo -e "${YELLOW}${DRIFT_COUNT} issue(s) detected.${NC}"
+fi
+echo "========================================="
+
+# --- Save report ---
+if [ "$SAVE_REPORT" = true ]; then
+  {
+    echo "# Drift Detection Report"
+    echo ""
+    echo "<!-- AUTO-GENERATED by scripts/detect-drift.sh -->"
+    echo "<!-- generated-at: $(date -u +%Y-%m-%dT%H:%M:%SZ) -->"
+    echo ""
+    if [ "$DRIFT_COUNT" -eq 0 ]; then
+      echo "## Status: All Clear"
+    else
+      echo "## Status: ${DRIFT_COUNT} issue(s) detected"
+    fi
+    echo ""
+    echo "| File | Status | Details |"
+    echo "|------|--------|---------|"
+    for line in "${REPORT_LINES[@]}"; do
+      echo "$line"
+    done
+  } > "$REPORT_FILE"
+  echo "Report saved to $REPORT_FILE"
+fi
+
+# --- CI mode exit code ---
+if [ "$CI_MODE" = true ] && [ "$DRIFT_COUNT" -gt 0 ]; then
+  exit 1
+fi
+
+exit 0