crowd-funder-for-time-pwa/README-BUILD-GUARD.md

Build Architecture Guard - Husky Implementation

Overview

The Build Architecture Guard protects your build system by enforcing documentation requirements through Git hooks. When you modify build-critical files, the system automatically blocks commits/pushes until you update BUILDING.md.

🎯 Why Husky-Only?

Advantages:

• ✅ Immediate feedback - Hooks run before commit/push
• ✅ Works everywhere - No server-side CI/CD required
• ✅ Simple setup - One tool, one configuration
• ✅ Fast execution - No network delays or server queues
• ✅ Offline support - Works without internet connection

Trade-offs:

• ⚠️ Can be bypassed - git commit --no-verify or git push --no-verify
• ⚠️ Developer discipline - Relies on team following the rules

🏗️ Architecture

Developer Workflow:
1. Modify build files (scripts/, vite.config.*, etc.)
2. Try to commit → Husky pre-commit hook runs
3. Guard script checks if BUILDING.md was updated
4. ✅ Commit succeeds if docs updated
5. ❌ Commit blocked if docs missing

🚀 Quick Start

1. Install Dependencies

npm install
npm run prepare  # Sets up Husky hooks

2. Test the System

# Modify a build file without updating BUILDING.md
echo "# test" >> scripts/test.sh

# Try to commit (should be blocked)
git add scripts/test.sh
git commit -m "test: add build script"
# ❌ Hook blocks commit with helpful message

3. Fix and Retry

# Update BUILDING.md with your changes
echo "## New Build Script" >> BUILDING.md
echo "Added test.sh for testing purposes" >> BUILDING.md

# Now commit should succeed
git add BUILDING.md
git commit -m "feat: add test build script with docs"
# ✅ Commit succeeds

🔧 How It Works

Pre-commit Hook (.husky/pre-commit)

• When: Every git commit
• What: Runs ./scripts/build-arch-guard.sh --staged
• Result: Blocks commit if build files changed without BUILDING.md update

Pre-push Hook (.husky/pre-push)

• When: Every git push
• What: Runs ./scripts/build-arch-guard.sh --range
• Result: Blocks push if commits contain undocumented build changes

Guard Script (scripts/build-arch-guard.sh)

• Detects: Changes to build-sensitive file patterns
• Validates: BUILDING.md was updated alongside changes
• Reports: Clear error messages with guidance

📁 Protected File Patterns

The guard script monitors these paths for changes:

Build Configuration:
├── vite.config.*          # Vite configuration
├── capacitor.config.ts    # Capacitor configuration
├── package.json           # Package configuration
├── package-lock.json      # Lock files
├── yarn.lock
└── pnpm-lock.yaml

Build Scripts:
├── scripts/**             # All build and automation scripts
├── electron/**            # Electron build files
├── android/**             # Android build configuration
├── ios/**                 # iOS build configuration
├── sw_scripts/**          # Service worker scripts
└── sw_combine.js          # Service worker combination

Deployment:
├── Dockerfile             # Docker configuration
└── docker/**              # Docker services

🎭 Usage Scenarios

Scenario 1: Adding a New Build Script

# ❌ This will be blocked
echo '#!/bin/bash' > scripts/new-build.sh
git add scripts/new-build.sh
git commit -m "feat: add new build script"
# Hook blocks: "Build-sensitive files changed but BUILDING.md not updated"

# ✅ This will succeed
echo '#!/bin/bash' > scripts/new-build.sh
echo '## New Build Script' >> BUILDING.md
echo 'Added new-build.sh for feature X' >> BUILDING.md
git add scripts/new-build.sh BUILDING.md
git commit -m "feat: add new build script with docs"
# ✅ Commit succeeds

Scenario 2: Updating Vite Configuration

# ❌ This will be blocked
echo 'export default { newOption: true }' >> vite.config.ts
git add vite.config.ts
git commit -m "config: add new vite option"
# Hook blocks: "Build-sensitive files changed but BUILDING.md not updated"

# ✅ This will succeed
echo 'export default { newOption: true }' >> vite.config.ts
echo '### New Vite Option' >> BUILDING.md
echo 'Added newOption for improved performance' >> BUILDING.md
git add vite.config.ts BUILDING.md
git commit -m "config: add new vite option with docs"
# ✅ Commit succeeds

🚨 Emergency Bypass

⚠️ Use sparingly and only for emergencies:

# Skip pre-commit hook
git commit -m "emergency: critical fix" --no-verify

# Skip pre-push hook  
git push --no-verify

# Remember to update BUILDING.md later!

🔍 Troubleshooting

Hooks Not Running

# Reinstall hooks
npm run prepare

# Check hook files exist and are executable
ls -la .husky/
chmod +x .husky/*

# Verify Git hooks path
git config core.hooksPath
# Should show: .husky

Guard Script Issues

# Test guard script manually
./scripts/build-arch-guard.sh --help

# Check script permissions
chmod +x scripts/build-arch-guard.sh

# Test with specific files
./scripts/build-arch-guard.sh --staged

False Positives

# If guard blocks legitimate changes, check:
# 1. Are you modifying a protected file pattern?
# 2. Did you update BUILDING.md?
# 3. Is BUILDING.md staged for commit?

# View what the guard sees
git diff --name-only --cached

📋 Best Practices

For Developers

1. Update BUILDING.md first - Document changes before implementing
2. Test locally - Run ./scripts/build-arch-guard.sh --staged before committing
3. Use descriptive commits - Include context about build changes
4. Don't bypass lightly - Only use --no-verify for true emergencies

For Teams

1. Document the system - Ensure everyone understands the guard
2. Review BUILDING.md updates - Verify documentation quality
3. Monitor bypass usage - Track when hooks are skipped
4. Regular audits - Check that BUILDING.md stays current

For Maintainers

1. Update protected patterns - Modify scripts/build-arch-guard.sh as needed
2. Monitor effectiveness - Track how often the guard catches issues
3. Team training - Help developers understand the system
4. Continuous improvement - Refine patterns and error messages

🔄 Customization

Adding New Protected Paths

Edit scripts/build-arch-guard.sh:

SENSITIVE=(
  # ... existing patterns ...
  "new-pattern/**"        # Add your new pattern
  "*.config.js"           # Add file extensions
)

Modifying Error Messages

Edit the guard script to customize:

• Error message content
• File pattern matching
• Documentation requirements
• Bypass instructions

Adding New Validation Rules

Extend the guard script to check for:

• Specific file content patterns
• Required documentation sections
• Commit message formats
• Branch naming conventions

📚 Integration with PR Template

The pull_request_template.md works with this system by:

• Guiding developers through required documentation
• Ensuring consistency across all build changes
• Providing checklist for comprehensive updates
• Supporting L1/L2/L3 change classification

🎯 Success Metrics

Track the effectiveness of your Build Architecture Guard:

• Hook execution rate - How often hooks run successfully
• Bypass frequency - How often --no-verify is used
• Documentation quality - BUILDING.md stays current
• Build failures - Fewer issues from undocumented changes
• Team adoption - Developers follow the process

---

Status: Active protection system Architecture: Client-side Git hooks only Dependencies: Husky, Git, Bash Maintainer: Development team Related: pull_request_template.md, scripts/build-arch-guard.sh