# 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**

```bash
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

```bash
npm install
npm run prepare  # Sets up Husky hooks
```

### 2. Test the System

```bash
# 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

```bash
# 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:

```text
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

```bash
# ❌ 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

```bash
# ❌ 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:**

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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`:

```bash
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`