crowd-funder-for-time-pwa/scripts/git-hooks/README.md

TimeSafari Git Hooks

This directory contains custom Git hooks for the TimeSafari project.

Debug Code Checker Hook

Overview

The pre-commit hook automatically checks for debug code when committing to protected branches (master, main, production, release). This prevents debug statements from accidentally reaching production code.

How It Works

1. Branch Detection: Only runs on protected branches (configurable)
2. File Filtering: Automatically skips test files, scripts, and documentation
3. Pattern Matching: Detects common debug patterns using regex
4. Commit Prevention: Blocks commits containing debug code

Protected Branches (Default)

• master
• main
• production
• release
• stable

Debug Patterns Detected

• Console statements: console.log, console.debug, console.error
• Template debug: Debug:, debug: in Vue templates
• Debug constants: DEBUG_, debug_ variables
• HTML debug: <!-- debug comments
• Debug attributes: debug="true" attributes
• Vue debug: v-if="debug", v-show="debug"
• Debug TODOs: TODO debug, FIXME debug

Files Automatically Skipped

• Test files: *.test.js, *.spec.ts, *.test.vue
• Scripts: scripts/ directory
• Test directories: test-* directories
• Documentation: docs/, *.md, *.txt
• Config files: *.json, *.yml, *.yaml
• IDE files: .cursor/ directory

Configuration

Edit .git/hooks/debug-checker.config to customize:

• Protected branches
• Debug patterns
• Skip patterns
• Logging level

Testing the Hook

Run the test script to verify the hook works:

./scripts/test-debug-hook.sh

Manual Testing

1. Make changes to a file with debug code
2. Stage the file: git add <filename>
3. Try to commit: git commit -m 'test'
4. Hook should prevent commit if debug code is found

Bypassing the Hook (Emergency)

If you absolutely need to commit debug code to a protected branch:

git commit --no-verify -m "emergency: debug code needed"

⚠️ Warning: This bypasses all pre-commit hooks. Use sparingly and only in emergencies.

Troubleshooting

Hook not running

• Ensure the hook is executable: chmod +x .git/hooks/pre-commit
• Check if you're on a protected branch
• Verify the hook file exists and has correct permissions

False positives

• Add legitimate debug patterns to skip patterns in config
• Use proper logging levels (logger.info, logger.debug) instead of console
• Move debug code to feature branches first

Hook too strict

• Modify debug patterns in config file
• Add more file types to skip patterns
• Adjust protected branch list

Best Practices

1. Use feature branches for development with debug code
2. Use proper logging instead of console statements
3. Test thoroughly before merging to protected branches
4. Review commits to ensure no debug code slips through
5. Keep config updated as project needs change

Integration with CI/CD

This hook works locally. For CI/CD pipelines, consider:

• Running the same checks in your build process
• Adding ESLint rules for console statements
• Using TypeScript strict mode
• Adding debug code detection to PR checks

Support

If you encounter issues:

1. Check the hook output for specific error messages
2. Verify your branch is in the protected list
3. Review the configuration file
4. Test with the provided test script
5. Check file permissions and git setup