From 9f2ef24b2b499d8255897adabc5946e349db939d Mon Sep 17 00:00:00 2001 From: Matthew Raymer Date: Fri, 22 Aug 2025 08:43:21 +0000 Subject: [PATCH] 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. --- .../architecture/build_architecture_guard.mdc | 82 +++++++- .gitignore | 3 + BUILDING.md | 27 ++- scripts/build-arch-guard.sh | 199 ++++++++++++++++-- 4 files changed, 291 insertions(+), 20 deletions(-) diff --git a/.cursor/rules/architecture/build_architecture_guard.mdc b/.cursor/rules/architecture/build_architecture_guard.mdc index 651a12d5..dbd3cf76 100644 --- a/.cursor/rules/architecture/build_architecture_guard.mdc +++ b/.cursor/rules/architecture/build_architecture_guard.mdc @@ -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 ` 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 diff --git a/.gitignore b/.gitignore index fe26f10c..bd97efcc 100644 --- a/.gitignore +++ b/.gitignore @@ -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 diff --git a/BUILDING.md b/BUILDING.md index a54742f6..8cf98f80 100644 --- a/BUILDING.md +++ b/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 diff --git a/scripts/build-arch-guard.sh b/scripts/build-arch-guard.sh index 153382c6..f61fa8d1 100755 --- a/scripts/build-arch-guard.sh +++ b/scripts/build-arch-guard.sh @@ -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 " + 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