@synapta/skills 0.1.1 → 0.2.0

package/skills/repo-bootstrap/scripts/validate-structure.sh

@@ -0,0 +1,324 @@
+#!/usr/bin/env bash
+# Validate AGENTS.md structure compliance and optionally check freshness
+# Note: -e intentionally omitted - we accumulate errors and report at end
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Default options
+PROJECT_DIR=""
+CHECK_FRESHNESS=false
+VERBOSE=false
+
+# Parse flags
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --check-freshness|-f)
+            CHECK_FRESHNESS=true
+            shift
+            ;;
+        --verbose|-v)
+            VERBOSE=true
+            shift
+            ;;
+        --help|-h)
+            cat <<EOF
+Usage: validate-structure.sh [PROJECT_DIR] [OPTIONS]
+
+Validate AGENTS.md structure compliance and optionally check freshness.
+
+Options:
+  --check-freshness, -f  Also check if files are up to date with git commits
+  --verbose, -v          Show detailed output
+  --help, -h             Show this help message
+
+Examples:
+  validate-structure.sh .                      # Structure check only
+  validate-structure.sh . --check-freshness    # Structure + freshness check
+  validate-structure.sh . -f -v                # Full check with details
+EOF
+            exit 0
+            ;;
+        *)
+            PROJECT_DIR="$1"
+            shift
+            ;;
+    esac
+done
+
+PROJECT_DIR="${PROJECT_DIR:-.}"
+cd "$PROJECT_DIR" || exit 1
+
+ERRORS=0
+WARNINGS=0
+
+error() {
+    echo "❌ ERROR: $*"
+    ((ERRORS+=1))
+}
+
+warning() {
+    echo "⚠️  WARNING: $*"
+    ((WARNINGS+=1))
+}
+
+success() {
+    echo "✅ $*"
+}
+
+info() {
+    echo "ℹ️  $*"
+}
+
+# Check if file has managed header
+check_managed_header() {
+    local file="$1"
+
+    if grep -q "^<!-- Managed by agent:" "$file"; then
+        success "Managed header present: $file"
+        return 0
+    else
+        warning "Missing managed header: $file"
+        return 1
+    fi
+}
+
+# Check if root is thin (≤50 lines or has scope index)
+check_root_is_thin() {
+    local file="$1"
+    local line_count
+    line_count=$(wc -l < "$file")
+
+    if [ "$line_count" -le 50 ]; then
+        success "Root is thin: $line_count lines"
+        return 0
+    elif grep -q "## Index of scoped AGENTS.md" "$file"; then
+        success "Root has scope index (verbose style acceptable)"
+        return 0
+    else
+        error "Root is bloated: $line_count lines and no scope index"
+        return 1
+    fi
+}
+
+# Check if root has precedence statement
+check_precedence_statement() {
+    local file="$1"
+
+    if grep -qi "precedence" "$file" && grep -qi "closest.*AGENTS.md.*wins" "$file"; then
+        success "Precedence statement present"
+        return 0
+    else
+        error "Missing precedence statement in root"
+        return 1
+    fi
+}
+
+# Check if scoped file has all required sections (with alternatives)
+check_scoped_sections() {
+    local file="$1"
+
+    # Each entry: "Display Name|pattern1|pattern2|..."
+    local section_patterns=(
+        "Overview|## Overview"
+        "Setup|## Setup|## Environment|## Prerequisites|## Getting Started|## Workflow files"
+        "Build/Tests|## Build|## Tests|## Running|## Commands|## Common patterns"
+        "Code style|## Code style|## Style|## Conventions|## Workflow conventions"
+        "Security|## Security"
+        "Checklist|## PR|## Commit|## Checklist"
+        "Examples|## Good vs|## Examples|## Bad examples|## Patterns to Follow"
+        "When stuck|## When stuck|## Help|## Resources|## Troubleshooting"
+    )
+
+    local missing=()
+
+    for entry in "${section_patterns[@]}"; do
+        local name="${entry%%|*}"
+        local patterns="${entry#*|}"
+        local found=false
+
+        # Try each pattern
+        IFS='|' read -ra pattern_array <<< "$patterns"
+        for pattern in "${pattern_array[@]}"; do
+            if grep -qi "^$pattern" "$file"; then
+                found=true
+                break
+            fi
+        done
+
+        if [ "$found" = false ]; then
+            missing+=("$name")
+        fi
+    done
+
+    if [ ${#missing[@]} -eq 0 ]; then
+        success "All required sections present: $file"
+        return 0
+    else
+        error "Missing sections in $file: ${missing[*]}"
+        return 1
+    fi
+}
+
+# Check if scope index links work
+check_scope_links() {
+    local root_file="$1"
+
+    if ! grep -q "## Index of scoped AGENTS.md" "$root_file"; then
+        return 0  # No index, skip check
+    fi
+
+    # Extract links from scope index
+    local links
+    links=$(sed -n '/## Index of scoped AGENTS.md/,/^##/p' "$root_file" | grep -o '\./[^)]*AGENTS.md' || true)
+
+    if [ -z "$links" ]; then
+        # Empty scope index with AGENTS-GENERATED markers is valid (placeholder)
+        if grep -q "<!-- AGENTS-GENERATED:START scope-index -->" "$root_file" && \
+           grep -q "<!-- AGENTS-GENERATED:END scope-index -->" "$root_file"; then
+            info "Scope index is empty (placeholder)"
+            return 0
+        fi
+        warning "Scope index present but no links found"
+        return 1
+    fi
+
+    local broken=()
+    while read -r link; do
+        # Remove leading ./
+        local clean_link="${link#./}"
+        local full_path="$PROJECT_DIR/$clean_link"
+
+        if [ ! -f "$full_path" ]; then
+            broken+=("$link")
+        fi
+    done <<< "$links"
+
+    if [ ${#broken[@]} -eq 0 ]; then
+        success "All scope index links work"
+        return 0
+    else
+        error "Broken scope index links: ${broken[*]}"
+        return 1
+    fi
+}
+
+# Check CLAUDE.md symlink exists alongside an AGENTS.md file
+check_claude_symlink() {
+    local agents_file="$1"
+    local dir
+    dir=$(dirname "$agents_file")
+    local claude_file="$dir/CLAUDE.md"
+    local rel_dir="${dir#"$PROJECT_DIR"}"
+    [ -z "$rel_dir" ] && rel_dir="(root)"
+
+    if [ -L "$claude_file" ]; then
+        local target
+        target=$(readlink "$claude_file")
+        if [ "$target" = "AGENTS.md" ]; then
+            success "CLAUDE.md symlink correct: $rel_dir"
+            return 0
+        else
+            error "CLAUDE.md symlink points to '$target', expected 'AGENTS.md': $rel_dir"
+            return 1
+        fi
+    elif [ -f "$claude_file" ]; then
+        warning "CLAUDE.md is a regular file, not a symlink to AGENTS.md: $rel_dir"
+        return 1
+    else
+        error "Missing CLAUDE.md symlink to AGENTS.md: $rel_dir (Claude Code won't read AGENTS.md without it)"
+        return 1
+    fi
+}
+
+# Main validation
+echo "Validating AGENTS.md structure in: $PROJECT_DIR"
+echo ""
+
+# Check root AGENTS.md
+ROOT_FILE="$PROJECT_DIR/AGENTS.md"
+
+if [ ! -f "$ROOT_FILE" ]; then
+    error "Root AGENTS.md not found"
+else
+    echo "=== Root AGENTS.md ==="
+    check_managed_header "$ROOT_FILE"
+    check_root_is_thin "$ROOT_FILE"
+    check_precedence_statement "$ROOT_FILE"
+    check_scope_links "$ROOT_FILE"
+    echo ""
+fi
+
+# Check CLAUDE.md symlinks
+echo "=== CLAUDE.md Symlinks ==="
+ALL_AGENTS_FILES=$(find "$PROJECT_DIR" -name "AGENTS.md" \
+    -not -path "*/references/examples/*" \
+    -not -path "*/examples/*" \
+    -not -path "*/.git/*" \
+    -not -path "*/vendor/*" \
+    -not -path "*/node_modules/*" \
+    2>/dev/null || true)
+
+if [ -n "$ALL_AGENTS_FILES" ]; then
+    while read -r file; do
+        check_claude_symlink "$file"
+    done <<< "$ALL_AGENTS_FILES"
+fi
+echo ""
+
+# Check scoped AGENTS.md files (exclude reference examples)
+SCOPED_FILES=$(find "$PROJECT_DIR" -name "AGENTS.md" \
+    -not -path "$ROOT_FILE" \
+    -not -path "*/references/examples/*" \
+    -not -path "*/examples/*" \
+    -not -path "*/.git/*" \
+    2>/dev/null || true)
+
+if [ -n "$SCOPED_FILES" ]; then
+    echo "=== Scoped AGENTS.md Files ==="
+    while read -r file; do
+        rel_path="${file#"$PROJECT_DIR"/}"
+        echo "Checking: $rel_path"
+        check_managed_header "$file"
+        check_scoped_sections "$file"
+        echo ""
+    done <<< "$SCOPED_FILES"
+fi
+
+# Summary
+echo "=== Structure Validation Summary ==="
+if [ $ERRORS -eq 0 ] && [ $WARNINGS -eq 0 ]; then
+    echo "✅ All structure checks passed!"
+elif [ $ERRORS -eq 0 ]; then
+    echo "⚠️  Structure validation passed with $WARNINGS warning(s)"
+else
+    echo "❌ Structure validation failed with $ERRORS error(s) and $WARNINGS warning(s)"
+fi
+
+# Run freshness check if requested
+if [ "$CHECK_FRESHNESS" = true ]; then
+    echo ""
+    echo "=== Freshness Check ==="
+    FRESHNESS_ARGS=""
+    [ "$VERBOSE" = true ] && FRESHNESS_ARGS="--verbose"
+
+    if "$SCRIPT_DIR/check-freshness.sh" "$PROJECT_DIR" $FRESHNESS_ARGS; then
+        echo "✅ All files are up to date!"
+    else
+        # Freshness issues are warnings, not errors
+        ((WARNINGS+=1))
+    fi
+fi
+
+echo ""
+echo "=== Final Summary ==="
+if [ $ERRORS -eq 0 ] && [ $WARNINGS -eq 0 ]; then
+    echo "✅ All checks passed!"
+    exit 0
+elif [ $ERRORS -eq 0 ]; then
+    echo "⚠️  Passed with $WARNINGS warning(s)"
+    exit 0
+else
+    echo "❌ Failed with $ERRORS error(s) and $WARNINGS warning(s)"
+    exit 1
+fi