ContractGuard 🛡️
Professional drift detection for config, environment, API, and route contracts.
Detect contract drift before it breaks production. Automatically identify inconsistencies in your configuration files, environment variables, API routes, and code references with actionable recommendations.
Features
✨ Environment Variable Drift Detection
- Detects inconsistencies between
.env, .env.production, .env.development files
- Identifies missing or extra variables
- Prevents runtime errors from configuration mismatches
🔗 Configuration Contract Validation
- Scans for multiple
package.json files and config inconsistencies
- Validates configuration file presence and completeness
- Helps maintain consistent settings across your project
🛣️ Route & API Endpoint Checks
- Detects route/API definition files
- Identifies potential route mismatches
- Ensures API contract consistency
⚠️ Stale Reference Warnings
- Finds TODO, FIXME, and XXX comments
- Identifies outdated code references
- Helps reduce technical debt
📊 Professional Results Dashboard
- Health score (0-100) with color-coded status
- Detailed statistics and metrics
- Grouped issues by severity and type
- Actionable recommendations for each issue
📤 Multiple Export Formats
- JSON - for automation and CI/CD integration
- CSV - for spreadsheet analysis
- HTML - professional reports for stakeholders
Installation
- Open VS Code
- Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
- Search for "ContractGuard"
- Click Install
Quick Start
- Open a project folder in VS Code
- Press Ctrl+Shift+D (Cmd+Shift+D on Mac) to open drift scan
- Click "Run Drift Scan" button
- Review the results with health score, statistics, and issues
- Export results in JSON, CSV, or HTML format
Commands
| Command |
Shortcut |
Description |
| ContractGuard: Show Drift Scan |
Ctrl+Shift+D |
Open the main drift scan panel |
| ContractGuard: Quick Scan |
Ctrl+Shift+Alt+D |
Run a quick scan with notifications |
| ContractGuard: Export Results |
Command Palette |
Export latest scan results |
How It Works
Environment Variable Scanning
- Reads all
.env* files in your project
- Compares variables across different environment files
- Detects missing variables that should be consistent
- Alerts on extra variables that may indicate drift
Configuration Analysis
- Searches for
package.json, tsconfig.json, .env.example files
- Detects multiple configuration files that suggest inconsistency
- Validates configuration presence and structure
Route & API Detection
- Scans common route/API patterns
- Identifies route definition files for analysis
- Checks for consistency in API definitions
Code Quality Checks
- Searches for TODO, FIXME, and XXX comments
- Identifies potential stale code references
- Helps track and reduce technical debt
Results Dashboard
Health Score
- 80+: Excellent ✓ - Keep it up!
- 60-79: Good - Minor improvements needed
- 40-59: Fair - Address warnings
- 0-39: Critical - Immediate action required
Statistics
- Total issues found
- Breakdown by severity (Errors, Warnings, Info)
- Issues by category (Environment, Config, Routes, References)
- Number of files affected
Issues & Recommendations
Each issue includes:
- Type: Category of the issue
- Severity: Error, Warning, or Info
- Message: What was detected
- Details: Specific information
- Recommendation: How to fix it
JSON Export
Perfect for automation and CI/CD pipelines.
CSV Export
Great for spreadsheet analysis and reporting.
HTML Export
Professional report for sharing with stakeholders.
Tips & Best Practices
Prevent Environment Drift
- Use
.env.example as your source of truth
- Add new variables to all environment files simultaneously
- Document required variables and their purposes
- Run ContractGuard in your CI/CD pipeline
Maintain Configuration Consistency
- Keep a single
package.json at project root (unless monorepo)
- Use configuration management tools for consistency
- Document all configuration requirements
- Review configuration regularly with your team
Reduce Technical Debt
- Convert TODO/FIXME comments to GitHub issues
- Schedule regular technical debt reviews
- Address warnings before they become errors
- Export reports to track improvement over time
Requirements
- VS Code 1.89.0 or higher
- Node.js projects (or any project with config/env files)
License
MIT License - see LICENSE file for details
Made with ❤️ to prevent production breaking changes
Usage
- Open a project
- Run ContractGuard: Show Drift Scan
- Review warnings
License
MIT
