forked from trent_larson/crowd-funder-for-time-pwa
feat(guard): enhance build architecture guard with Android protection and feedback system
- Add Android-specific build validation for asset management and API routing - Implement feedback collection system for continuous guard improvement - Enhance sensitive path detection to include capacitor-assets.config.json and resources/ - Add Android change detection with specific testing guidance - Integrate feedback analysis command for maintainer insights - Update guard rules to reflect enhanced Android build system complexity The guard now protects sophisticated Android build features including asset validation, resource generation, and platform-specific API routing while collecting usage data for continuous improvement.
This commit is contained in:
Matthew Raymer
@@ -7,7 +7,7 @@ alwaysApply: false
|
||||
# Build Architecture Guard Directive
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: 2025-08-20
|
||||
**Date**: 2025-08-22
|
||||
**Status**: 🎯 **ACTIVE** - Build system protection guidelines
|
||||
|
||||
## Purpose
|
||||
@@ -17,6 +17,8 @@ could break the multi-platform build pipeline, deployment processes, or
|
||||
development workflow. This directive ensures all build system modifications
|
||||
follow proper review, testing, and documentation procedures.
|
||||
|
||||
**Note**: Recent Android build system enhancements (2025-08-22) include sophisticated asset validation, platform-specific API routing, and automatic resource regeneration. These features require enhanced testing and validation procedures.
|
||||
|
||||
## Protected Architecture Components
|
||||
|
||||
### Core Build Infrastructure
|
||||
@@ -29,6 +31,14 @@ follow proper review, testing, and documentation procedures.
|
||||
- **Docker Configuration**: `Dockerfile`, `docker-compose.yml`
|
||||
- **Environment Files**: `.env.*`, `.nvmrc`, `.node-version`
|
||||
|
||||
### Android-Specific Build Validation
|
||||
|
||||
- **Asset Validation Scripts**: `validate_android_assets()` function and resource checking
|
||||
- **Resource Generation**: `capacitor-assets` integration and verification
|
||||
- **Platform-Specific IP Handling**: Android emulator vs physical device API routing
|
||||
- **Build Mode Validation**: Development/test/production mode handling
|
||||
- **Resource Fallback Logic**: Automatic regeneration of missing Android resources
|
||||
|
||||
### Critical Build Dependencies
|
||||
|
||||
- **Build Tools**: Vite, Capacitor, Electron, Android SDK, Xcode
|
||||
@@ -54,6 +64,9 @@ follow proper review, testing, and documentation procedures.
|
||||
- Environment variable changes
|
||||
- Dependency version updates
|
||||
- Platform-specific optimizations
|
||||
- **Build script argument parsing**: New flag handling (--api-ip, --auto-run, --deploy)
|
||||
- **Platform-specific environment overrides**: Android API server IP customization
|
||||
- **Asset regeneration logic**: Automatic fallback for missing Android resources
|
||||
|
||||
**Process**: Code review + platform testing + documentation update
|
||||
|
||||
@@ -115,6 +128,12 @@ follow proper review, testing, and documentation procedures.
|
||||
- **Android**: `npm run build:android:test` or `:prod` - confirm assets copied
|
||||
- **iOS**: `npm run build:ios:test` or `:prod` - verify build succeeds
|
||||
|
||||
### Android Platform (Enhanced)
|
||||
- **Development Mode**: `npm run build:android --dev` - verify 10.0.2.2 API routing
|
||||
- **Custom IP Mode**: `npm run build:android --dev --api-ip 192.168.1.100` - verify custom IP
|
||||
- **Asset Validation**: `npm run build:android --assets` - verify resource generation
|
||||
- **Deploy Mode**: `npm run build:android --deploy` - verify device deployment
|
||||
|
||||
### Desktop Platform
|
||||
|
||||
- **Electron**: `npm run build:electron:dev` and packaging for target OS
|
||||
@@ -194,6 +213,16 @@ follow proper review, testing, and documentation procedures.
|
||||
- **Trigger**: New base image, build args
|
||||
- **Validation**: Build image locally; run container; list produced `/dist`
|
||||
|
||||
### Android Asset Management
|
||||
- **Trigger**: Changes to `validate_android_assets()` function or resource paths
|
||||
- **Validation**: Run `npm run build:android --assets` and verify all mipmap/drawable resources
|
||||
- **Risk**: Missing splash screens or app icons causing build failures
|
||||
|
||||
### Android API Routing
|
||||
- **Trigger**: Changes to Android-specific API server IP logic
|
||||
- **Validation**: Test both emulator (10.0.2.2) and custom IP modes
|
||||
- **Risk**: API connectivity failures on different device types
|
||||
|
||||
### Signing/Notarization
|
||||
|
||||
- **Trigger**: Cert path/profiles
|
||||
@@ -226,6 +255,13 @@ follow proper review, testing, and documentation procedures.
|
||||
- **Desktop**: `npm run build:electron:dev` and packaging commands
|
||||
- **Clean**: Run relevant `clean:*` scripts and verify re-build works
|
||||
|
||||
### Android-Specific Rollback Verification
|
||||
- **Asset Generation**: `npm run build:android --assets` - verify resources regenerate
|
||||
- **API Routing**: Test both `--dev` and `--dev --api-ip <custom>` modes
|
||||
- **Resource Validation**: Check `android/app/src/main/res/` for all required assets
|
||||
- **Build Modes**: Verify development, test, and production modes all work
|
||||
- **Resource Fallback**: Confirm missing resources trigger automatic regeneration
|
||||
|
||||
## ADR Trigger List
|
||||
|
||||
Raise an ADR when you propose any of:
|
||||
@@ -236,6 +272,10 @@ Raise an ADR when you propose any of:
|
||||
- **New service worker assembly** strategy or cache policy
|
||||
- **New Docker base** or multi-stage pipeline
|
||||
- **Relocation of build outputs** or directory conventions
|
||||
- **New Android build modes** or argument parsing logic
|
||||
- **Changes to asset validation** or resource generation strategy
|
||||
- **Modifications to platform-specific API routing** (Android emulator vs physical)
|
||||
- **New Android deployment strategies** or device management
|
||||
|
||||
**ADR must include**: motivation, alternatives, risks, validation plan, rollback,
|
||||
doc diffs.
|
||||
@@ -285,6 +325,44 @@ Raise an ADR when you propose any of:
|
||||
- [ ] **Team Review**: Have appropriate stakeholders been consulted?
|
||||
- [ ] **CI/CD**: Will this pass the build pipeline?
|
||||
|
||||
## Continuous Improvement & Feedback
|
||||
|
||||
### Feedback Collection
|
||||
|
||||
The Build Architecture Guard system includes feedback mechanisms to continuously improve its effectiveness:
|
||||
|
||||
- **User Feedback**: Script includes feedback prompts for guard improvements
|
||||
- **Pattern Analysis**: Monitor which file patterns trigger false positives/negatives
|
||||
- **Documentation Gaps**: Track which changes lack proper documentation
|
||||
- **Testing Effectiveness**: Measure how often guard catches actual issues
|
||||
|
||||
### Feedback Integration Process
|
||||
|
||||
1. **Collect Feedback**: Monitor guard execution logs and user reports
|
||||
2. **Analyze Patterns**: Identify common false positives or missed patterns
|
||||
3. **Update Rules**: Modify `build_architecture_guard.mdc` based on feedback
|
||||
4. **Enhance Script**: Update `build-arch-guard.sh` with new validations
|
||||
5. **Test Changes**: Verify guard improvements don't introduce new issues
|
||||
6. **Document Updates**: Update guard documentation with new patterns
|
||||
|
||||
### Feedback Categories
|
||||
|
||||
- **False Positives**: Files flagged as sensitive that shouldn't be
|
||||
- **False Negatives**: Sensitive files that weren't caught
|
||||
- **Missing Patterns**: New file types that should be protected
|
||||
- **Overly Strict**: Patterns that are too restrictive
|
||||
- **Documentation Gaps**: Missing guidance for specific change types
|
||||
- **Testing Improvements**: Better validation procedures
|
||||
|
||||
### Feedback Reporting
|
||||
|
||||
When reporting guard issues, include:
|
||||
- **File patterns** that triggered false positives/negatives
|
||||
- **Build system changes** that weren't properly caught
|
||||
- **Documentation gaps** in current guard rules
|
||||
- **Testing procedures** that could be improved
|
||||
- **User experience** issues with guard enforcement
|
||||
|
||||
---
|
||||
|
||||
**Status**: Active build system protection
|
||||
@@ -292,4 +370,4 @@ Raise an ADR when you propose any of:
|
||||
**Estimated Effort**: Ongoing vigilance
|
||||
**Dependencies**: All build system components
|
||||
**Stakeholders**: Development team, DevOps, Platform owners
|
||||
**Next Review**: 2025-09-20
|
||||
**Next Review**: 2025-09-22
|
||||
|
||||
3
.gitignore
vendored
3
.gitignore
vendored
@@ -51,6 +51,9 @@ vendor/
|
||||
# Build logs
|
||||
build_logs/
|
||||
|
||||
# Guard feedback logs (for continuous improvement analysis)
|
||||
.guard-feedback.log
|
||||
|
||||
# PWA icon files generated by capacitor-assets
|
||||
icons
|
||||
|
||||
|
||||
27
BUILDING.md
27
BUILDING.md
@@ -88,6 +88,7 @@ The Build Architecture Guard protects your build system by enforcing documentati
|
||||
- **Protected Files**: Build scripts, config files, and platform-specific code
|
||||
- **Documentation Requirement**: `BUILDING.md` must be updated alongside build changes
|
||||
- **Automatic Enforcement**: Git hooks prevent commits without proper documentation
|
||||
- **Feedback Collection**: Continuously improves through usage pattern analysis
|
||||
|
||||
#### Protected File Patterns
|
||||
|
||||
@@ -98,14 +99,29 @@ The guard monitors these sensitive paths:
|
||||
- `android/**` - Android platform code
|
||||
- `ios/**` - iOS platform code
|
||||
- `capacitor.config.ts` - Mobile configuration
|
||||
- `capacitor-assets.config.json` - Android asset configuration
|
||||
- `resources/**` - Source assets for Android resource generation
|
||||
- `package.json` - Dependencies and scripts
|
||||
|
||||
#### Enhanced Android Protection
|
||||
|
||||
The guard now provides enhanced protection for Android build system changes:
|
||||
|
||||
- **Asset Validation**: Protects `validate_android_assets()` function and resource paths
|
||||
- **Resource Generation**: Monitors `capacitor-assets` integration and verification
|
||||
- **API Routing**: Protects platform-specific IP handling (emulator vs physical device)
|
||||
- **Build Modes**: Validates development/test/production mode handling
|
||||
- **Resource Fallback**: Protects automatic regeneration of missing Android resources
|
||||
|
||||
#### Using the Guard
|
||||
|
||||
```bash
|
||||
# Test the guard locally
|
||||
./scripts/build-arch-guard.sh --staged
|
||||
|
||||
# Analyze guard effectiveness (for maintainers)
|
||||
./scripts/build-arch-guard.sh --feedback
|
||||
|
||||
# Bypass for emergency commits (use sparingly)
|
||||
git commit --no-verify
|
||||
|
||||
@@ -124,7 +140,16 @@ chmod +x scripts/build-arch-guard.sh
|
||||
./scripts/build-arch-guard.sh --help
|
||||
```
|
||||
|
||||
**Note**: The guard is active and will block commits that modify build files without updating `BUILDING.md`.
|
||||
#### Feedback and Continuous Improvement
|
||||
|
||||
The guard system includes feedback mechanisms for continuous improvement:
|
||||
|
||||
- **Automatic Logging**: All guard executions are logged for analysis
|
||||
- **Pattern Analysis**: Identifies false positives/negatives and missing patterns
|
||||
- **Maintainer Insights**: Use `--feedback` command to analyze guard effectiveness
|
||||
- **Continuous Updates**: Guard rules and patterns are updated based on feedback
|
||||
|
||||
**Note**: The guard is active and will block commits that modify build files without updating `BUILDING.md`. Recent enhancements provide better Android build system protection and feedback collection for continuous improvement.
|
||||
|
||||
### Environment Configuration
|
||||
|
||||
|
||||
@@ -3,8 +3,10 @@
|
||||
# Build Architecture Guard Script
|
||||
#
|
||||
# Author: Matthew Raymer
|
||||
# Date: 2025-08-20
|
||||
# Date: 2025-08-22
|
||||
# Purpose: Protects build-critical files by requiring BUILDING.md updates
|
||||
# Enhanced to protect Android build system including asset validation,
|
||||
# API routing, and resource generation logic
|
||||
#
|
||||
# Usage:
|
||||
# ./scripts/build-arch-guard.sh --staged # Check staged files (pre-commit)
|
||||
@@ -26,14 +28,19 @@ SENSITIVE=(
|
||||
"Dockerfile"
|
||||
"docker/**"
|
||||
"capacitor.config.ts"
|
||||
"capacitor-assets.config.json" # Critical for Android assets
|
||||
"package.json"
|
||||
"package-lock.json"
|
||||
"yarn.lock"
|
||||
"pnpm-lock.yaml"
|
||||
"resources/**" # Source assets for Android
|
||||
)
|
||||
|
||||
# Documentation files that must be updated alongside sensitive changes
|
||||
DOCS_REQUIRED=("BUILDING.md")
|
||||
DOCS_REQUIRED=(
|
||||
"BUILDING.md"
|
||||
"doc/README-BUILD-GUARD.md" # Guard documentation
|
||||
)
|
||||
|
||||
# Colors for output
|
||||
RED='\033[0;31m'
|
||||
@@ -103,6 +110,137 @@ check_docs_updated() {
|
||||
return 1
|
||||
}
|
||||
|
||||
# Check if Android build system was modified
|
||||
check_android_build_changes() {
|
||||
local changed_files=("$@")
|
||||
|
||||
for file in "${changed_files[@]}"; do
|
||||
if [[ "$file" =~ ^android/ ]] || [[ "$file" =~ ^scripts/build-android\.sh$ ]]; then
|
||||
return 0
|
||||
fi
|
||||
done
|
||||
return 1
|
||||
}
|
||||
|
||||
# Check if asset configuration was modified
|
||||
check_asset_config_changes() {
|
||||
local changed_files=("$@")
|
||||
|
||||
for file in "${changed_files[@]}"; do
|
||||
if [[ "$file" =~ ^capacitor-assets\.config\.json$ ]] || [[ "$file" =~ ^resources/ ]]; then
|
||||
return 0
|
||||
fi
|
||||
done
|
||||
return 1
|
||||
}
|
||||
|
||||
# Enhanced validation for Android changes
|
||||
validate_android_changes() {
|
||||
local changed_files=("$@")
|
||||
|
||||
if check_android_build_changes "${changed_files[@]}"; then
|
||||
log_warn "Android build system changes detected!"
|
||||
echo
|
||||
echo "Android build system changes require enhanced validation:"
|
||||
echo " - Test asset generation: npm run build:android --assets"
|
||||
echo " - Test API routing modes: --dev and --dev --api-ip <custom>"
|
||||
echo " - Verify resource fallback mechanisms"
|
||||
echo " - Test across development/test/production modes"
|
||||
echo
|
||||
echo "Please ensure BUILDING.md includes Android-specific testing procedures."
|
||||
echo
|
||||
fi
|
||||
|
||||
if check_asset_config_changes "${changed_files[@]}"; then
|
||||
log_warn "Asset configuration changes detected!"
|
||||
echo
|
||||
echo "Asset configuration changes require validation:"
|
||||
echo " - Test asset generation across all platforms"
|
||||
echo " - Verify resource files are properly created"
|
||||
echo " - Test asset validation scripts"
|
||||
echo
|
||||
fi
|
||||
}
|
||||
|
||||
# Feedback collection for continuous improvement
|
||||
collect_feedback_data() {
|
||||
local mode="$1"
|
||||
local sensitive_touched=("${@:2}")
|
||||
local timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
|
||||
|
||||
# Create feedback log entry
|
||||
local feedback_log=".guard-feedback.log"
|
||||
echo "[$timestamp] Guard execution: $mode" >> "$feedback_log"
|
||||
echo " Sensitive files: ${sensitive_touched[*]}" >> "$feedback_log"
|
||||
|
||||
# Log Android-specific changes for analysis
|
||||
if check_android_build_changes "${sensitive_touched[@]}"; then
|
||||
echo " Android changes detected" >> "$feedback_log"
|
||||
fi
|
||||
|
||||
# Log asset configuration changes for analysis
|
||||
if check_asset_config_changes "${sensitive_touched[@]}"; then
|
||||
echo " Asset config changes detected" >> "$feedback_log"
|
||||
fi
|
||||
|
||||
echo "" >> "$feedback_log"
|
||||
}
|
||||
|
||||
# Enhanced error handling with Android-specific guidance
|
||||
handle_documentation_error() {
|
||||
local sensitive_touched=("$@")
|
||||
|
||||
log_error "Build-sensitive files changed but BUILDING.md was not updated!"
|
||||
echo
|
||||
echo "The following build-sensitive files were modified:"
|
||||
for file in "${sensitive_touched[@]}"; do
|
||||
echo " - $file"
|
||||
done
|
||||
echo
|
||||
echo "When modifying build-critical files, you must also update BUILDING.md"
|
||||
echo "to document any changes to the build process."
|
||||
echo
|
||||
|
||||
# Add Android-specific guidance
|
||||
if check_android_build_changes "${sensitive_touched[@]}"; then
|
||||
echo "⚠️ ANDROID BUILD SYSTEM CHANGES DETECTED ⚠️"
|
||||
echo "Android changes require enhanced documentation including:"
|
||||
echo " - Asset validation procedures"
|
||||
echo " - API routing configuration"
|
||||
echo " - Resource generation testing"
|
||||
echo " - Platform-specific build modes"
|
||||
echo
|
||||
fi
|
||||
|
||||
if check_asset_config_changes "${sensitive_touched[@]}"; then
|
||||
echo "🎨 ASSET CONFIGURATION CHANGES DETECTED 🎨"
|
||||
echo "Asset changes require documentation including:"
|
||||
echo " - Asset generation procedures"
|
||||
echo " - Resource validation steps"
|
||||
echo " - Platform-specific asset requirements"
|
||||
echo
|
||||
fi
|
||||
|
||||
echo "Please:"
|
||||
echo " 1. Update BUILDING.md with relevant changes"
|
||||
echo " 2. Stage the BUILDING.md changes: git add BUILDING.md"
|
||||
echo " 3. Retry your commit/push"
|
||||
echo
|
||||
echo "💡 Feedback: If this guard is too strict or missing patterns,"
|
||||
echo " please report to the development team for continuous improvement."
|
||||
echo
|
||||
echo "📊 Feedback Categories:"
|
||||
echo " - False positives (files flagged that shouldn't be)"
|
||||
echo " - False negatives (sensitive files not caught)"
|
||||
echo " - Missing patterns (new file types to protect)"
|
||||
echo " - Overly strict (patterns too restrictive)"
|
||||
echo " - Documentation gaps (missing guidance)"
|
||||
echo " - Testing improvements (better procedures)"
|
||||
echo
|
||||
echo "📝 Report feedback to: Development team with specific examples"
|
||||
echo
|
||||
}
|
||||
|
||||
# Main guard logic
|
||||
main() {
|
||||
local mode="${1:-}"
|
||||
@@ -143,26 +281,19 @@ main() {
|
||||
echo " - $file"
|
||||
done
|
||||
|
||||
# Enhanced validation for Android changes
|
||||
validate_android_changes "${changed_files[@]}"
|
||||
|
||||
# Collect feedback data for continuous improvement
|
||||
collect_feedback_data "$mode" "${sensitive_touched[@]}"
|
||||
|
||||
# Check if required documentation was updated
|
||||
if check_docs_updated "${changed_files[@]}"; then
|
||||
log_success "BUILDING.md updated alongside build changes, guard check passed"
|
||||
exit 0
|
||||
else
|
||||
log_error "Build-sensitive files changed but BUILDING.md was not updated!"
|
||||
echo
|
||||
echo "The following build-sensitive files were modified:"
|
||||
for file in "${sensitive_touched[@]}"; do
|
||||
echo " - $file"
|
||||
done
|
||||
echo
|
||||
echo "When modifying build-critical files, you must also update BUILDING.md"
|
||||
echo "to document any changes to the build process."
|
||||
echo
|
||||
echo "Please:"
|
||||
echo " 1. Update BUILDING.md with relevant changes"
|
||||
echo " 2. Stage the BUILDING.md changes: git add BUILDING.md"
|
||||
echo " 3. Retry your commit/push"
|
||||
echo
|
||||
# Enhanced error handling with Android-specific guidance
|
||||
handle_documentation_error "${sensitive_touched[@]}"
|
||||
exit 2
|
||||
fi
|
||||
}
|
||||
@@ -179,11 +310,45 @@ if [[ "${1:-}" =~ ^(-h|--help)$ ]]; then
|
||||
echo " --range [RANGE] Check git range (for pre-push hook)"
|
||||
echo " Default range: HEAD~1..HEAD"
|
||||
echo " (no args) Check working directory changes"
|
||||
echo " --feedback Show feedback analysis (for maintainers)"
|
||||
echo
|
||||
echo "Examples:"
|
||||
echo " $0 --staged # Pre-commit check"
|
||||
echo " $0 --range origin/main..HEAD # Pre-push check"
|
||||
echo " $0 # Working directory check"
|
||||
echo " $0 --feedback # Analyze guard effectiveness"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Handle feedback analysis
|
||||
if [[ "${1:-}" == "--feedback" ]]; then
|
||||
if [[ -f ".guard-feedback.log" ]]; then
|
||||
echo "Build Architecture Guard Feedback Analysis"
|
||||
echo "=========================================="
|
||||
echo
|
||||
echo "Recent guard executions:"
|
||||
echo
|
||||
tail -20 ".guard-feedback.log" | while IFS= read -r line; do
|
||||
if [[ "$line" =~ ^\[ ]]; then
|
||||
echo "📅 $line"
|
||||
elif [[ "$line" =~ ^\s*Sensitive\ files: ]]; then
|
||||
echo "🔍 $line"
|
||||
elif [[ "$line" =~ ^\s*Android\ changes ]]; then
|
||||
echo "🤖 $line"
|
||||
elif [[ "$line" =~ ^\s*Asset\ config ]]; then
|
||||
echo "🎨 $line"
|
||||
elif [[ "$line" =~ ^\s*$ ]]; then
|
||||
echo ""
|
||||
else
|
||||
echo " $line"
|
||||
fi
|
||||
done
|
||||
echo
|
||||
echo "💡 Use this data to improve guard patterns and documentation"
|
||||
echo "📊 Total executions: $(grep -c "Guard execution" .guard-feedback.log 2>/dev/null || echo "0")"
|
||||
else
|
||||
echo "No feedback data available yet. Run the guard to collect data."
|
||||
fi
|
||||
exit 0
|
||||
fi
|
||||
|
||||
|
||||
Reference in New Issue
Block a user