SurfSense/PRE_COMMIT.md

Pre-commit Hooks for SurfSense Contributors

Welcome to SurfSense! As an open-source project, we use pre-commit hooks to maintain code quality, security, and consistency across our multi-component codebase. This guide will help you set up and work with our pre-commit configuration.

🚀 What is Pre-commit?

Pre-commit is a framework for managing multi-language pre-commit hooks. It runs automatically before each commit to catch issues early, ensuring high code quality and consistency across the project.

📁 Project Structure

SurfSense consists of three main components:

• surfsense_backend/ - Python backend API
• surfsense_web/ - Next.js web application
• surfsense_browser_extension/ - TypeScript browser extension

🛠 Installation

Prerequisites

• Python 3.8 or higher
• Node.js 18+ and pnpm (for frontend components)
• Git

Install Pre-commit

# Install pre-commit globally
pip install pre-commit

# Or using your preferred package manager
# pipx install pre-commit  # Recommended for isolation

Setup Pre-commit Hooks

1. Clone the repository:

   git clone https://github.com/masabinhok/SurfSense.git
   cd SurfSense
   

2. Install the pre-commit hooks:

   pre-commit install
   

3. Install commit message hooks (optional, for conventional commits):

   pre-commit install --hook-type commit-msg
   

🔧 Configuration Files Added

When you install pre-commit, the following files are part of the setup:

• .pre-commit-config.yaml - Main pre-commit configuration
• .secrets.baseline - Baseline file for secret detection (prevents false positives)
• .github/workflows/pre-commit.yml - CI workflow that runs pre-commit on PRs

🎯 What Gets Checked

All Files

• ✅ Trailing whitespace removal
• ✅ YAML, JSON, and TOML validation
• ✅ Large file detection (>10MB)
• ✅ Merge conflict markers
• 🔒 Secret detection using detect-secrets

Python Backend (surfsense_backend/)

• 🐍 Black - Code formatting
• 📦 isort - Import sorting
• ⚡ Ruff - Fast linting and formatting
• 🔍 MyPy - Static type checking
• 🛡️ Bandit - Security vulnerability scanning

Frontend (surfsense_web/ & surfsense_browser_extension/)

• 💅 Prettier - Code formatting
• 🔍 ESLint - Linting (Next.js config)
• 📝 TypeScript - Compilation checks

Commit Messages

• 📝 Commitizen - Conventional commit format validation

🚀 Usage

Normal Workflow

Pre-commit will run automatically when you commit:

git add .
git commit -m "feat: add new feature"
# Pre-commit hooks will run automatically

Manual Execution

Run on staged files only:

pre-commit run

Run on specific files:

pre-commit run --files path/to/file.py path/to/file.ts

Run all hooks on all files:

pre-commit run --all-files

⚠️ Warning: Running --all-files may generate numerous errors as this codebase has existing linting and type issues that are being gradually resolved.

Advanced Commands

Update all hooks to latest versions:

pre-commit autoupdate

Run only specific hooks:

pre-commit run black                    # Run only black
pre-commit run --all-files prettier     # Run prettier on all files

Clean pre-commit cache:

pre-commit clean

🆘 Bypassing Pre-commit (When Necessary)

Sometimes you might need to bypass pre-commit hooks (use sparingly!):

Skip all hooks for one commit:

git commit -m "fix: urgent hotfix" --no-verify

Skip specific hooks:

SKIP=mypy,black git commit -m "feat: work in progress"

Available hook IDs to skip:

• trailing-whitespace, check-yaml, check-json
• detect-secrets
• black, isort, ruff, ruff-format, mypy, bandit
• prettier, eslint
• typescript-check-web, typescript-check-extension
• commitizen

🐛 Common Issues & Solutions

Secret Detection False Positives

If detect-secrets flags legitimate content as secrets:

1. Review the detection - Ensure it's not actually a secret
2. Update baseline:

   detect-secrets scan --baseline .secrets.baseline --update
   git add .secrets.baseline
   

TypeScript/Node.js Issues

Ensure dependencies are installed:

cd surfsense_web && pnpm install
cd surfsense_browser_extension && pnpm install

Python Environment Issues

For Python hooks, ensure you're in the correct environment:

cd surfsense_backend
# If using uv
uv sync
# Or traditional pip
pip install -r requirements.txt

Hook Installation Issues

If hooks aren't running:

pre-commit uninstall
pre-commit install --install-hooks

📊 Performance Tips

• Incremental runs: Pre-commit only runs on changed files by default
• Parallel execution: Many hooks run in parallel for speed
• Caching: Pre-commit caches environments to speed up subsequent runs

🔄 CI Integration

Pre-commit also runs in our GitHub Actions CI pipeline on every PR to main. The CI:

• Runs only on changed files for efficiency
• Provides the same feedback as local pre-commit
• Prevents merging code that doesn't pass quality checks

📋 Best Practices

1. Install pre-commit early in your development setup
2. Fix issues incrementally rather than bypassing hooks
3. Update your branch regularly to avoid conflicts with formatting changes
4. Run --all-files periodically on feature branches (in small chunks)
5. Keep the .secrets.baseline updated when legitimate secrets-like strings are added

💡 Contributing to Pre-commit Config

To modify the pre-commit configuration:

1. Edit .pre-commit-config.yaml
2. Test your changes:

   pre-commit run --all-files  # Test with caution!
   

3. Update the baseline if needed:

   detect-secrets scan --baseline .secrets.baseline --update
   

4. Submit a PR with your changes

🆘 Getting Help

• Pre-commit docs: https://pre-commit.com/
• Project issues: Open an issue on GitHub
• Hook-specific help: Check individual tool documentation (Black, Ruff, ESLint, etc.)

---

Thank you for contributing to SurfSense! 🏄‍♀️ Quality code makes everyone's surfing experience smoother.