Code Churn Warning

Code Churn Warning is a VS Code extension that helps you identify and reduce code churn by warning you when you edit code you recently modified.

🎯 What is Code Churn?

Code churn refers to the practice of frequently modifying the same lines of code within a short period. High code churn can indicate:

• Incomplete initial implementation
• Unclear requirements
• Design issues
• Technical debt

This extension helps you become aware of code churn patterns in your workflow.

✨ Features

• 🔍 Automatic Detection: Analyzes your code changes using Git blame
• ⚠️ Visual Warnings: Shows warnings as diagnostics and/or decorations
• 📊 Configurable Threshold: Customize the time threshold (default: 21 days / 3 weeks)
• 🎨 Multiple Display Modes: Choose between diagnostics, decorations, or both
• 💡 Hover Information: View commit details on hover
• 🔗 Open in Browser: Click to view commits on GitHub, GitLab, Bitbucket, or Azure DevOps
• ⚡ Performance Optimized: Smart caching with debouncing and LRU eviction
• 🔒 Privacy First: All analysis is done locally, no data is sent externally

📦 Installation

From VS Code Marketplace

1. Open VS Code
2. Press Ctrl+P (or Cmd+P on macOS)
3. Type ext install your-publisher-name.code-churn-warning
4. Press Enter

From VSIX File

1. Download the .vsix file from Releases
2. Open VS Code
3. Press Ctrl+Shift+P (or Cmd+Shift+P on macOS)
4. Type Install from VSIX
5. Select the downloaded .vsix file

Development Mode

git clone https://github.com/your-username/code-churn-warning.git
cd code-churn-warning
npm install
npm run compile
# Press F5 in VS Code to start debugging

🚀 Usage

Once installed, the extension automatically analyzes your files when you open or edit them in a Git repository.

Commands

• Code Churn: Toggle Warnings (churn.toggle): Enable/disable churn warnings
• Code Churn: Clear Cache (churn.clearCache): Clear the blame cache
• Code Churn: Open Commit in Browser (churn.openCommit): Open commit in your Git hosting provider

Status Bar

The status bar shows the number of churn warnings in the current file. Click it to toggle warnings on/off.

⚙️ Configuration

Open VS Code settings (Ctrl+, or Cmd+,) and search for "churn":

churn.enabled

• Type: boolean
• Default: true
• Description: Enable/disable code churn warnings

churn.thresholdDays

• Type: number
• Default: 21 (3 weeks)
• Range: 1-365
• Description: Number of days after which editing your own code triggers a warning

churn.showAs

• Type: string
• Options: diagnostic, decoration, both
• Default: both
• Description: How to display churn warnings
  • diagnostic: Show as problems in the Problems panel
  • decoration: Show as gutter icons and background highlights
  • both: Show both diagnostics and decorations

churn.checkOnSaveOnly

• Type: boolean
• Default: true (recommended)
• Description: Only check for churn when saving files. When enabled, warnings appear only after you save a file, reducing visual noise. Set to false for real-time warnings as you type.

churn.ignoredGlobs

• Type: array
• Default: ["**/node_modules/**", "**/dist/**", "**/build/**", "**/*.min.js", "**/*.generated.*"]
• Description: Glob patterns for files to ignore

churn.cacheTTLSeconds

• Type: number
• Default: 300 (5 minutes)
• Range: 0-3600
• Description: Cache TTL for git blame results (in seconds)

churn.authorMatch

• Type: string
• Options: email, name, both
• Default: email
• Description: How to match the current user with commit authors
  • email: Match by email address only
  • name: Match by author name only
  • both: Match by both email and name

churn.debug

• Type: boolean
• Default: false
• Description: Enable debug logging to output channel

churn.telemetry

• Type: boolean
• Default: false
• Description: Enable anonymous usage telemetry (opt-in, minimal data)

🔒 Privacy & Security

• Local Analysis Only: All code analysis is performed locally on your machine
• No Code Transmission: Your source code and line contents are never sent externally
• Minimal Telemetry: Telemetry is disabled by default and requires explicit opt-in
• Open Source: Full source code is available for review

🌐 Supported Git Hosting Providers

The extension can open commits in your browser for the following providers:

• GitHub
• GitLab
• Bitbucket
• Azure DevOps

🛠️ Development

Prerequisites

• Node.js 20.x or later
• VS Code 1.85.0 or later
• Git

Building

npm install
npm run compile

Running Tests

# Run all tests
npm test

# Run only unit tests
npm run test:unit

# Run with watch mode
npm run watch

Linting & Formatting

# Run ESLint
npm run lint

# Fix ESLint issues
npm run lint:fix

# Check formatting
npm run format:check

# Format code
npm run format

Packaging

# Create .vsix package
npm run package

📝 Publishing

Prerequisites

1. Create a publisher account on VS Code Marketplace
2. Generate a Personal Access Token (PAT) from Azure DevOps
3. (Optional) Create an account on Open VSX

Manual Publishing

# Publish to VS Code Marketplace
npx @vscode/vsce publish --pat YOUR_VSCE_TOKEN

# Publish to Open VSX
npx ovsx publish *.vsix -p YOUR_OPEN_VSX_TOKEN

Automated Publishing (CI/CD)

The extension uses GitHub Actions for automated publishing:

1. Set up secrets in your GitHub repository:

   • VSCE_TOKEN: Your VS Code Marketplace PAT
   • OPEN_VSX_TOKEN: Your Open VSX access token (optional)

2. Create a new tag and push:

   git tag v1.0.0
   git push origin v1.0.0
   

3. GitHub Actions will automatically:

   • Run tests
   • Build the extension
   • Publish to VS Code Marketplace
   • Publish to Open VSX (if configured)
   • Create a GitHub release with the .vsix file

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

Reporting Issues

Please use the GitHub Issues page to report bugs or request features.

Pull Requests

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• VS Code Extension API documentation
• Git blame functionality
• The open-source community

📞 Support

• Documentation: GitHub Wiki
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Made with ❤️ for better code quality