ripple-ai-detector/ripple_tech_spec.md

🌊 Ripple AI Bug Detector - Built by an AI that knows its flaws. Catch AI-generated bugs before you commit.

# Ripple Technical Specification for Development

**Version**: 1.0  
**Date**: July 10, 2025  
**Target Audience**: Development Team (Augment Code)  
**Project Duration**: 12-16 weeks  
**Budget**: $25,000 - $40,000

## 1. System Overview

### 1.1 Architecture Overview
```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   CLI Tool      │    │  VS Code Ext    │    │  Web Dashboard  │
│   (Primary)     │    │  (Secondary)    │    │  (Team Features)│
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                    ┌─────────────────┐
                    │   Backend API   │
                    │ (License/Usage) │
                    └─────────────────┘
```

### 1.2 Core Components
1. **CLI Tool** (ripple-validator): Core analysis engine
2. **VS Code Extension**: Optional UI wrapper
3. **Backend API**: License validation and usage tracking
4. **Web Dashboard**: Team management and analytics

## 2. CLI Tool Specification

### 2.1 Technology Stack
- **Runtime**: Node.js 18+ (for ES modules and performance)
- **Language**: TypeScript 5.0+
- **Parser**: Tree-sitter for JavaScript/TypeScript
- **Git Integration**: simple-git library
- **CLI Framework**: commander.js
- **Config Management**: cosmiconfig
- **File System**: fs-extra

### 2.2 Installation & Setup
```bash
# Global installation
npm install -g ripple-validator

# Project initialization
ripple init

# Creates .ripple.config.js with defaults
```

### 2.3 Core Commands

#### 2.3.1 `ripple validate`
```bash
# Validate current git staging area
ripple validate

# Validate specific files
ripple validate src/components/Button.tsx src/utils/helpers.ts

# Validate with AI change detection
ripple validate --ai-changes

# JSON output for CI/CD
ripple validate --format json
```

#### 2.3.2 `ripple hook`
```bash
# Install git pre-commit hook
ripple hook install

# Remove git pre-commit hook
ripple hook remove

# Test hook without committing
ripple hook test
```

#### 2.3.3 `ripple auth`
```bash
# Login with license key
ripple auth login <license-key>

# Check auth status
ripple auth status

# Logout
ripple auth logout
```

### 2.4 Configuration File Structure
```javascript
// .ripple.config.js
module.exports = {
  // Analysis settings
  analysis: {
    // Languages to analyze
    languages: ['javascript', 'typescript'],
    
    // File patterns to include/exclude
    include: ['src/**/*.{js,ts,jsx,tsx}'],
    exclude: ['node_modules/**', 'dist/**', '*.test.{js,ts}'],
    
    // AI change detection sensitivity
    aiDetection: {
      enabled: true,
      sensitivity: 'medium', // low, medium, high
      patterns: [
        'multiple-file-changes',
        'function-signature-changes',
        'import-export-changes'
      ]
    }
  },
  
  // Validation rules
  rules: {
    // Function signature changes
    'function-signature-change': {
      enabled: true,
      severity: 'error'
    },
    
    // Import/export mismatches
    'import-export-mismatch': {
      enabled: true,
      severity: 'error'
    },
    
    // Type system violations
    'type-mismatch': {
      enabled: true,
      severity: 'warning'
    },
    
    // Test coverage gaps
    'test-coverage-gap': {
      enabled: false, // MVP: disabled
      severity: 'warning'
    }
  },
  
  // Team settings (paid plans only)
  team: {
    enabled: false,
    dashboardUrl: null,
    reportingEnabled: false
  }
};
```

### 2.5 Core Analysis Engine

#### 2.5.1 File Structure
```
src/
├── cli/
│   ├── commands/
│   │   ├── validate.ts
│   │   ├── hook.ts
│   │   └── auth.ts
│   └── index.ts
├── analysis/
│   ├── parser.ts          # Tree-sitter integration
│   ├── detector.ts        # AI change detection
│   ├── validator.ts       # Core validation logic
│   └── rules/
│       ├── function-signature.ts
│       ├── import-export.ts
│       └── type-mismatch.ts
├── git/
│   ├── changes.ts         # Git diff analysis
│   ├── hooks.ts           # Git hook management
│   └── staged-files.ts    # Staged file detection
├── config/
│   ├── loader.ts          # Configuration loading
│   └── defaults.ts        # Default configuration
├── auth/
│   ├── license.ts         # License validation
│   └── api-client.ts      # Backend API client
├── output/
│   ├── formatter.ts       # Output formatting
│   └── reporters/
│       ├── console.ts
│       ├── json.ts
│       └── junit.ts
└── utils/
    ├── file-utils.ts
    ├── ast-utils.ts
    └── logger.ts
```

#### 2.5.2 Core Analysis Algorithm
```typescript
// src/analysis/validator.ts
export class RippleValidator {
  async validateChanges(files: string[]): Promise<ValidationResult> {
    const results: ValidationResult = {
      success: true,
      issues: [],
      confidence: 1.0,
      aiGenerated: false
    };
    
    // Step 1: Parse files and build AST
    const asts = await this.parseFiles(files);
    
    // Step 2: Detect if changes are AI-generated
    const aiDetection = await this.detectAIChanges(files, asts);
    results.aiGenerated = aiDetection.isAIGenerated;
    
    // Step 3: Run validation rules
    for (const rule of this.rules) {
      const ruleResults = await rule.validate(asts, files);
      results.issues.push(...ruleResults.issues);
    }
    
    // Step 4: Calculate confidence score
    results.confidence = this.calculateConfidence(results.issues);
    results.success = results.issues.filter(i => i.severity === 'error').length === 0;
    
    return results;
  }
}
```

#### 2.5.3 AI Change Detection Logic
```typescript
// src/analysis/detector.ts
export class AIChangeDetector {
  async detectAIChanges(files: string[], asts: AST[]): Promise<AIDetectionResult> {
    const indicators = [];
    
    // Pattern 1: Multiple files changed simultaneously
    if (files.length > 3) {
      indicators.push({
        type: 'multiple-file-changes',
        confidence: 0.7,
        evidence: `${files.length} files changed in single commit`
      });
    }
    
    // Pattern 2: Function signature changes without caller updates
    const signatureChanges = this.detectSignatureChanges(asts);
    if (signatureChanges.length > 0) {
      indicators.push({
        type: 'function-signature-changes',
        confidence: 0.9,
        evidence: `${signatureChanges.length} function signatures changed`
      });
    }
    
    // Pattern 3: Import/export pattern changes
    const importChanges = this.detectImportChanges(asts);
    if (importChanges.length > 0) {
      indicators.push({
        type: 'import-export-changes',
        confidence: 0.8,
        evidence: `${importChanges.length} import/export statements changed`
      });
    }
    
    // Calculate overall confidence
    const overallConfidence = this.calculateAIConfidence(indicators);
    
    return {
      isAIGenerated: overallConfidence > 0.6,
      confidence: overallConfidence,
      indicators
    };
  }
}
```

### 2.6 Output Formats

#### 2.6.1 Console Output
```
✓ Ripple AI Code Validator

Analyzing 3 files...
⚠️  AI-generated changes detected (87% confidence)

Issues found:
❌ Function signature changed without updating callers
   File: src/utils/helpers.ts:23
   Function: processData(data: string) → processData(data: string, options: Options)
   Affected files: 
   - src/components/DataTable.tsx:45
   - src/pages/Dashboard.tsx:12

⚠️  Import statement may be incorrect
   File: src/components/Button.tsx:1
   Import: import { theme } from '../styles/theme'
   Issue: '../styles/theme' exports 'defaultTheme', not 'theme'

Summary: 1 error, 1 warning
Confidence: 87% this analysis is accurate
Recommendation: Review AI-generated changes before committing
```

#### 2.6.2 JSON Output
```json
{
  "success": false,
  "confidence": 0.87,
  "aiGenerated": true,
  "summary": {
    "errors": 1,
    "warnings": 1,
    "filesAnalyzed": 3
  },
  "issues": [
    {
      "type": "function-signature-change",
      "severity": "error",
      "file": "src/utils/helpers.ts",
      "line": 23,
      "message": "Function signature changed without updating callers",
      "details": {
        "function": "processData",
        "oldSignature": "processData(data: string)",
        "newSignature": "processData(data: string, options: Options)",
        "affectedFiles": [
          "src/components/DataTable.tsx:45",
          "src/pages/Dashboard.tsx:12"
        ]
      }
    }
  ]
}
```

## 3. VS Code Extension Specification

### 3.1 Technology Stack
- **Framework**: VS Code Extension API
- **Language**: TypeScript
- **UI**: WebView API for dashboard
- **Communication**: Child process to CLI tool

### 3.2 Extension Structure
```
vscode-extension/
├── src/
│   ├── extension.ts       # Main extension entry point
│   ├── commands/
│   │   ├── validate.ts    # Validation commands
│   │   └── configure.ts   # Configuration commands
│   ├── providers/
│   │   ├── diagnostics.ts # Problem panel integration
│   │   └── status-bar.ts  # Status bar integration
│   ├── views/
│   │   ├── dashboard.ts   # WebView dashboard
│   │   └── results.ts     # Results panel
│   └── utils/
│       ├── cli-wrapper.ts # CLI tool integration
│       └── config.ts      # Configuration management
├── package.json
└── README.md
```

### 3.3 Extension Features

#### 3.3.1 Commands
```json
{
  "contributes": {
    "commands": [
      {
        "command": "ripple.validate",
        "title": "AI Safety Check",
        "icon": "$(shield)"
      },
      {
        "command": "ripple.validateStaged",
        "title": "Validate Staged Changes"
      },
      {
        "command": "ripple.configure",
        "title": "Configure Ripple"
      }
    ]
  }
}
```

#### 3.3.2 Status Bar Integration
```typescript
// src/providers/status-bar.ts
export class RippleStatusBar {
  private statusBarItem: vscode.StatusBarItem;
  
  updateStatus(result: ValidationResult) {
    if (result.aiGenerated) {
      this.statusBarItem.text = `$(shield) AI Code (${Math.round(result.confidence * 100)}%)`;
      this.statusBarItem.backgroundColor = new vscode.ThemeColor('statusBarItem.warningBackground');
    } else {
      this.statusBarItem.text = `$(check) Code Safe`;
      this.statusBarItem.backgroundColor = undefined;
    }
  }
}
```

#### 3.3.3 Problems Panel Integration
```typescript
// src/providers/diagnostics.ts
export class RippleDiagnostics {
  private diagnosticCollection: vscode.DiagnosticCollection;
  
  updateDiagnostics(results: ValidationResult) {
    this.diagnosticCollection.clear();
    
    results.issues.forEach(issue => {
      const diagnostic = new vscode.Diagnostic(
        new vscode.Range(issue.line - 1, 0, issue.line - 1, 0),
        issue.message,
        issue.severity === 'error' ? vscode.DiagnosticSeverity.Error : vscode.DiagnosticSeverity.Warning
      );
      
      diagnostic.source = 'Ripple AI Validator';
      this.diagnosticCollection.set(vscode.Uri.file(issue.file), [diagnostic]);
    });
  }
}
```

## 4. Backend API Specification

### 4.1 Technology Stack
- **Runtime**: Node.js 18+
- **Framework**: Express.js with TypeScript
- **Database**: PostgreSQL 14+
- **Authentication**: JWT tokens
- **Payment**: Stripe webhooks
- **Deployment**: Docker containers

### 4.2 Database Schema
```sql
-- Users and licensing
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) UNIQUE NOT NULL,
    license_key VARCHAR(255) UNIQUE NOT NULL,
    plan VARCHAR(50) NOT NULL DEFAULT 'free',
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

-- Teams (for team plans)
CREATE TABLE teams (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(255) NOT NULL,
    owner_id UUID REFERENCES users(id),
    plan VARCHAR(50) NOT NULL DEFAULT 'team',
    created_at TIMESTAMP DEFAULT NOW()
);

-- Team memberships
CREATE TABLE team_members (
    team_id UUID REFERENCES teams(id),
    user_id UUID REFERENCES users(id),
    role VARCHAR(50) NOT NULL DEFAULT 'member',
    PRIMARY KEY (team_id, user_id)
);

-- Usage tracking
CREATE TABLE usage_events (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id),
    team_id UUID REFERENCES teams(id),
    event_type VARCHAR(50) NOT NULL, -- 'validation', 'ai_detection', etc.
    file_count INTEGER NOT NULL,
    ai_detected BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMP DEFAULT NOW()
);

-- Stripe customer mapping
CREATE TABLE stripe_customers (
    user_id UUID REFERENCES users(id),
    stripe_customer_id VARCHAR(255) NOT NULL,
    PRIMARY KEY (user_id)
);
```

### 4.3 API Endpoints

#### 4.3.1 Authentication
```typescript
// POST /api/auth/validate-license
{
  "licenseKey": "rpl_1234567890abcdef"
}

// Response
{
  "valid": true,
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "plan": "individual"
  },
  "limits": {
    "validationsPerMonth": 1000,
    "currentUsage": 45
  }
}
```

#### 4.3.2 Usage Tracking
```typescript
// POST /api/usage/track
{
  "licenseKey": "rpl_1234567890abcdef",
  "eventType": "validation",
  "fileCount": 3,
  "aiDetected": true,
  "metadata": {
    "confidence": 0.87,
    "issues": 2
  }
}

// Response
{
  "success": true,
  "remainingUsage": 955
}
```

#### 4.3.3 Team Management
```typescript
// GET /api/teams/{teamId}/dashboard
{
  "team": {
    "id": "uuid",
    "name": "Engineering Team",
    "memberCount": 5
  },
  "usage": {
    "thisMonth": {
      "validations": 234,
      "aiDetections": 67,
      "issuesFound": 12
    },
    "members": [
      {
        "email": "dev1@company.com",
        "validations": 45,
        "aiDetections": 12
      }
    ]
  }
}
```

### 4.4 Payment Integration

#### 4.4.1 Stripe Webhook Handler
```typescript
// POST /api/webhooks/stripe
export const handleStripeWebhook = async (req: Request, res: Response) => {
  const sig = req.headers['stripe-signature'];
  const event = stripe.webhooks.constructEvent(req.body, sig, process.env.STRIPE_WEBHOOK_SECRET);
  
  switch (event.type) {
    case 'customer.subscription.created':
      await activateSubscription(event.data.object);
      break;
    case 'customer.subscription.deleted':
      await deactivateSubscription(event.data.object);
      break;
    case 'invoice.payment_failed':
      await handlePaymentFailure(event.data.object);
      break;
  }
  
  res.json({ received: true });
};
```

## 5. Development Phases

### Phase 1: Core CLI Tool (Weeks 1-6)
**Deliverables**:
- Basic CLI tool with validate command
- Tree-sitter integration for JS/TS parsing
- Git integration for staged file detection
- Function signature change detection
- Import/export mismatch detection
- Console output formatting
- Basic configuration file support

**Acceptance Criteria**:
- Can detect function signature changes with 80%+ accuracy
- Analysis completes in <2 seconds for 10 files
- Integrates with git staging area
- Produces actionable error messages

### Phase 2: AI Detection & Authentication (Weeks 7-10)
**Deliverables**:
- AI change detection algorithm
- License key authentication
- Backend API for license validation
- Usage tracking
- JSON output format
- Git hook installation

**Acceptance Criteria**:
- Can detect AI-generated changes with 70%+ accuracy
- License validation works offline (cached)
- Git hooks prevent commits with errors
- Usage tracking is accurate

### Phase 3: VS Code Extension (Weeks 11-14)
**Deliverables**:
- Basic VS Code extension
- Command integration
- Status bar integration
- Problems panel integration
- Settings UI

**Acceptance Criteria**:
- Extension installs and activates correctly
- Commands work from Command Palette
- Diagnostics appear in Problems panel
- Status bar shows AI detection status

### Phase 4: Team Features & Polish (Weeks 15-16)
**Deliverables**:
- Team management API
- Web dashboard (basic)
- Stripe integration
- Payment webhooks
- Documentation and deployment

**Acceptance Criteria**:
- Team dashboard shows usage statistics
- Payment flow works end-to-end
- All components are deployable
- Documentation is complete

## 6. Testing Strategy

### 6.1 Unit Tests
- **CLI Commands**: Test all command-line interfaces
- **Analysis Engine**: Test each validation rule
- **AI Detection**: Test with known AI-generated code samples
- **Git Integration**: Test with various git scenarios

### 6.2 Integration Tests
- **End-to-End CLI**: Test complete validation workflows
- **API Integration**: Test CLI-to-backend communication
- **VS Code Extension**: Test extension-to-CLI communication
- **Payment Flow**: Test subscription lifecycle

### 6.3 Performance Tests
- **Large Codebases**: Test with 100+ files
- **Analysis Speed**: Ensure <2 second analysis time
- **Memory Usage**: Monitor memory consumption
- **API Latency**: Test backend response times

## 7. Deployment & Infrastructure

### 7.1 CLI Tool Distribution
- **NPM Registry**: Primary distribution channel
- **GitHub Releases**: Binary releases for CI/CD
- **Homebrew**: macOS package manager
- **Chocolatey**: Windows package manager

### 7.2 Backend Deployment
```yaml
# docker-compose.yml
version: '3.8'
services:
  api:
    build: .
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/ripple
      - STRIPE_SECRET_KEY=${STRIPE_SECRET_KEY}
      - JWT_SECRET=${JWT_SECRET}
    depends_on:
      - db
      - redis
  
  db:
    image: postgres:14
    environment:
      - POSTGRES_DB=ripple
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=pass
    volumes:
      - postgres_data:/var/lib/postgresql/data
  
  redis:
    image: redis:7-alpine
    
volumes:
  postgres_data:
```

### 7.3 Monitoring & Logging
- **Application Monitoring**: Sentry for error tracking
- **Performance Monitoring**: New Relic or DataDog
- **Logging**: Structured logging with Winston
- **Health Checks**: HTTP endpoints for service health

## 8. Security Considerations

### 8.1 Code Analysis Security
- **No Code Upload**: All analysis happens locally
- **Metadata Only**: Only usage statistics sent to backend
- **Encrypted Communication**: HTTPS for all API calls
- **License Key Protection**: Store in secure local config

### 8.2 Backend Security
- **JWT Authentication**: Secure token-based auth
- **Rate Limiting**: Prevent API abuse
- **Input Validation**: Validate all incoming data
- **SQL Injection Prevention**: Parameterized queries

## 9. Performance Requirements

### 9.1 CLI Tool Performance
- **Analysis Time**: <2 seconds for 10 files, <5 seconds for 50 files
- **Memory Usage**: <100MB for typical analysis
- **Startup Time**: <500ms for command execution
- **Accuracy**: >80% for function signature detection, >70% for AI detection

### 9.2 Backend Performance
- **API Response Time**: <200ms for license validation
- **Database Query Time**: <100ms for usage tracking
- **Webhook Processing**: <5 seconds for payment webhooks
- **Uptime**: 99.9% availability

## 10. Success Metrics

### 10.1 Technical Metrics
- **False Positive Rate**: <10% for all validations
- **Analysis Accuracy**: >80% for breaking change detection
- **Performance**: Meet all performance requirements
- **Reliability**: <1% CLI tool crash rate

### 10.2 Business Metrics
- **User Adoption**: 100 active users by Month 6
- **Revenue**: $25K MRR by Month 18
- **Retention**: >80% monthly active user retention
- **NPS Score**: >50 for user satisfaction

## 11. Risks & Mitigation

### 11.1 Technical Risks
- **Parser Limitations**: Tree-sitter may not handle all JS/TS syntax
  - *Mitigation*: Comprehensive testing with real codebases
- **AI Detection Accuracy**: May have high false positive rate
  - *Mitigation*: Start with conservative detection, improve with feedback
- **Performance Issues**: Large codebases may be slow
  - *Mitigation*: Implement incremental analysis and caching

### 11.2 Business Risks
- **Market Adoption**: Developers may not adopt the tool
  - *Mitigation*: Focus on community building and free tier
- **Competition**: Existing tools may add similar features
  - *Mitigation*: Focus on AI-specific detection as differentiator
- **Pricing**: May be priced too high for individuals
  - *Mitigation*: Extensive pricing research and A/B testing

---

This technical specification provides the complete blueprint for building Ripple. The modular architecture allows for phased development while maintaining the ability to scale each component independently.