Monorepo Consistency Bot

Detect and fix environment variable drift across monorepo services using the OpenAI Codex SDK.

Problem

Large monorepos with multiple services often have environment variable drift:

• Services use different names for the same config (DATABASE_URL vs DB_URL)
• Variables documented in root .env.example missing in service-specific files
• Docker Compose files reference undocumented environment variables
• Inconsistent naming patterns across services

Solution

This tool uses Codex to analyze your monorepo and detect these inconsistencies automatically.

Installation

npm install
npm run build

Usage

Check the test fixture (demo)

npm run check

Check your own monorepo

# Text output (default)
node dist/index.js /path/to/your/monorepo

# JSON output
node dist/index.js /path/to/your/monorepo --json

# No color output
node dist/index.js /path/to/your/monorepo --no-color

CLI Options

• --json - Output results in JSON format
• --no-color - Disable colored output

Example Output

Text Format (Default)

🔍 Scanning monorepo at: /path/to/monorepo

📋 Analysis Results:

Environment Variable Drift Detected:

1. MISSING VARIABLES
   - service-a/.env.example: Missing WORKER_CONCURRENCY (exists in root)
   - service-b/.env.example: Missing SENTRY_DSN, WORKER_CONCURRENCY (exist in root)

2. NAMING INCONSISTENCIES
   - REDIS configuration: root and service-b use REDIS_URL, but service-a uses REDIS_HOST + REDIS_PORT
     → Suggested fix: Standardize on REDIS_URL
   
   - Database configuration: root and service-a use DATABASE_URL, but service-b uses DB_URL
     → Suggested fix: Rename DB_URL to DATABASE_URL in service-b
   
   - API keys: service-a uses API_KEY, service-b uses SECRET_KEY
     → Suggested fix: Clarify if these are different secrets or standardize naming

3. UNDOCUMENTED VARIABLES
   - EXTRA_VAR in docker-compose.yml (service-b) not documented in any .env.example

JSON Format

{
  "success": true,
  "output": "Environment Variable Drift Detected...",
  "threadId": "thread_abc123"
}

Development

# Build TypeScript
npm run build

# Watch mode for development
npm run dev

# Type checking
npm run typecheck

Testing

# Run all tests
npm test

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage

# Integration tests only
npm run test:integration

The project includes a test fixture with intentional drift to validate detection.

How It Works

1. Codex scans all .env.example files and docker-compose.yml in your monorepo
2. Extracts and compares environment variable names across services
3. Identifies missing variables, naming inconsistencies, and undocumented variables
4. Provides specific file paths and actionable recommendations

Test Fixture Details

The fixtures/test-monorepo includes:

• Root .env.example with standard variables
• service-a with Redis split into HOST/PORT instead of URL
• service-b with renamed DB_URL and missing SENTRY_DSN
• docker-compose.yml with an undocumented EXTRA_VAR

Expected issues documented in fixtures/test-monorepo/expected-issues.json.

TypeScript Support

The project is fully written in TypeScript with:

• Strict type checking enabled
• Custom error types for better error handling
• Type definitions for all functions and interfaces
• Full IDE autocomplete support

Error Handling

The tool includes specific error types:

• ConfigurationError - Issues with Codex SDK initialization
• CodexError - Errors during analysis
• AnalysisError - General analysis failures

All errors are properly typed and include helpful messages.

Roadmap

• Phase 1: Read-only drift detection
• TypeScript migration with improved types
• CLI improvements with colors and JSON output
• Unit tests with vitest
• Phase 2: Auto-generate PR to fix drift
• Phase 3: Add checks for logging patterns, error handling
• Phase 4: CI integration that fails on drift

License

MIT