🩺 Electron Channel Doctor - The Ultimate Script Doctor

Advanced Code Housekeeping & Surgical Cleanup Tool
Plus: Automate Electron IPC invoke channel management & Security Vulnerability Detection

🚀 What Makes This Special?

What started as a simple IPC channel manager has evolved into a comprehensive code housekeeping powerhouse that can perform surgical code cleanup with precision, now with advanced security vulnerability detection!

🩺 Script Doctor - Advanced Code Surgery

Automatically detect and surgically remove:

• 🔪 Unused Functions - Dead functions cluttering your codebase
• 📦 Unused Imports - ES6/CommonJS imports that serve no purpose
• 🎨 Unused CSS Classes - Styles that aren't used anywhere
• 💀 Dead Code Paths - Unreachable code after returns/throws
• 🔄 Duplicate Code - Repeated blocks that should be refactored
• 🔥 Complex Functions - Functions that need breaking down

Get instant insights:

• 🏥 Health Score (0-100) for your entire codebase
• 📊 Bundle Size Estimation - See how much weight you can lose
• 📋 Safe Backups - Automatic backups before any surgery
• 🎯 Actionable Recommendations - Know exactly what to do next

🔒 NEW: Security Vulnerability Detection

Protect your Electron app from critical security issues:

• 🚨 Context Isolation Bypass - Detect attempts to break security boundaries
• 🛡️ Dangerous API Exposure - Find Node.js APIs exposed to renderer
• ⚠️ Unvalidated IPC Handlers - Catch injection vulnerabilities
• 🔓 Insecure Configuration - nodeIntegration, webSecurity issues
• 🔑 Sensitive Data Leaks - Passwords, tokens, API keys in IPC
• 📡 Sender Validation - Missing frame/sender verification (CVE-2022-29247)

Based on 2024 security research and real CVEs:

• CVE-2024-39698 - Code signature validation bypass
• CVE-2022-29247 - IPC access without proper validation
• And many more Electron-specific vulnerabilities

🔧 Bonus: Electron IPC Channel Management

• ✅ Auto-detect electronAPI.invoke() calls in your code
• 🔍 Validate against preload.js whitelist
• 🚨 Prevent "Invalid invoke channel" errors
• 🛠️ Auto-fix missing channels with backups

📦 Installation

# Global installation (recommended)
npm install -g electron-channel-doctor

# Or use with npx (no installation needed)
npx electron-channel-doctor

🩺 Script Doctor Usage

Get a Health Checkup

# Comprehensive health analysis
electron-channel-doctor health

# Focus on specific file types
electron-channel-doctor health --source "src/**/*.js" --css "styles/**/*.css"

# Get detailed verbose output
electron-channel-doctor health --verbose

# Export as JSON for CI/CD
electron-channel-doctor health --json > health-report.json

Example Output:

🩺 Script Doctor: Performing comprehensive health checkup...

🏥 Overall Health Score: 67/100

📊 Code Health Summary:
   Unused Functions: 12
   Unused Imports: 8
   Unused CSS Classes: 23
   Dead Code Paths: 3
   Duplicate Code Blocks: 2
   Complex Functions: 5
   Missing IPC Channels: 1
   Unused IPC Channels: 4

💡 Recommendations:
   🚨 Remove 12 unused functions to reduce bundle size
   ⚠️ Code health needs improvement. Consider running surgery.

🎯 Recommended Next Steps:
   1. Run surgical cleanup
      Command: npx electron-channel-doctor surgery
      Automatically remove unused code with backup

Perform Code Surgery

# Full surgical cleanup (with automatic backup)
electron-channel-doctor surgery

# See what would be removed (dry run)
electron-channel-doctor surgery --dry-run

# Selective surgery (only specific operations)
electron-channel-doctor surgery --operations "unused-functions,unused-imports"

# Disable backup (NOT recommended)
electron-channel-doctor surgery --no-backup

# Verbose surgery with detailed output
electron-channel-doctor surgery --verbose

🛡️ NEW: Safe Mode vs Legacy Mode

Version 2.3.0+ introduces Safe Mode - a complete rewrite of the code modification engine that uses AST-based transformations instead of regex patterns.

Safe Mode (Default - Recommended)

# Safe mode is ON by default
electron-channel-doctor surgery

# Explicitly enable safe mode features
electron-channel-doctor surgery --conservative --max-changes 10

Safe Mode Features:

• ✅ AST-based modifications - Understands JavaScript syntax properly
• ✅ Syntax validation - Every change is validated before saving
• ✅ Conservative changes - Skips risky modifications
• ✅ Change limits - Max 10 changes per file by default
• ✅ Detailed error reporting - Know exactly what went wrong
• ✅ Safety score - Track how safe your surgery was

Legacy Mode (Dangerous - Not Recommended)

# ⚠️ WARNING: May break your code!
electron-channel-doctor surgery --no-safe-mode

# Disable ALL safety features (VERY DANGEROUS!)
electron-channel-doctor surgery --no-safe-mode --no-backup --no-validate-syntax

Legacy Mode Issues:

• ❌ Regex-based - Can't understand JavaScript syntax
• ❌ No validation - May create syntax errors
• ❌ Aggressive - Can destroy code structure
• ❌ No safety nets - You're on your own

Example of Legacy Mode Destruction:

// BEFORE (Working code)
const logger = require('../../utils/debugLogger');
return number.toString().padStart(2, '0');

// AFTER (Broken by legacy mode)
const logger = require('../../utils/debugLogger'function showTwoDigits(number) {
return number.toString().padStart(2, '0'}

Safe Mode in Action

$ electron-channel-doctor surgery --dry-run

🏥 Script Doctor: Preparing for surgical code cleanup...

🛡️  Using SAFE MODE with:
   ✅ AST-based modifications
   ✅ Syntax validation
   ✅ Conservative changes
   ✅ Automatic backups

🔍 Safe Surgery Preview:

📊 Expected Results:
   Files to be analyzed: 45
   Files to be modified: 12
   Syntax errors prevented: 3
   Safety score: 95/100

⚠️  Potential Issues:
   - src/utils/helpers.js: Parse error: Unexpected token (Skipping file)
   - src/legacy/old-code.js: Too many changes needed (15 > 10 limit)

💡 Run without --dry-run to perform actual surgery

Example Surgery Output:

🏥 Script Doctor: Preparing for surgical code cleanup...

📋 Created backup in: .electron-channel-doctor-backups/backup-2024-01-15T10-30-00
🔧 Run 'sh .electron-channel-doctor-backups/backup-2024-01-15T10-30-00/RESTORE.sh' to restore if needed

🔪 Removing 12 unused functions...
📦 Removing 8 unused imports...
🎨 Removing 23 unused CSS classes...
💀 Removing 3 dead code paths...

🎉 Surgery completed successfully!

📊 Surgery Statistics:
   Files Modified: 15
   Lines Removed: 247
   Functions Removed: 12
   Imports Removed: 8
   CSS Classes Removed: 23
   Dead Code Removed: 3
   Estimated Bundle Size Reduction: 8.7 KB

⚠️ Post-Surgery Recommendations:
   🧪 Run your test suite to ensure no functionality was broken
   🏗️ Test your build process to verify everything still works
   🚀 Bundle size reduced by ~8.7 KB! Consider measuring actual improvement.

Generate Detailed Reports

# Generate JSON health report
electron-channel-doctor report --format json --output health-report.json

# Generate Markdown report  
electron-channel-doctor report --format markdown --output HEALTH.md

# Output to console
electron-channel-doctor report

🔒 Security Analysis

Scan for Security Vulnerabilities

# Full security scan with all vulnerability types
electron-channel-doctor security

# Verbose output showing all issues (including low severity)
electron-channel-doctor security --verbose

# Export security report
electron-channel-doctor security --output security-report.json

# Custom file patterns
electron-channel-doctor security \
  --main "main.js,electron/**/*.js" \
  --renderer "src/**/*.js,renderer/**/*.js" \
  --preload "preload.js"

Example Security Scan Output:

🔒 Security Analyzer: Scanning for Electron IPC vulnerabilities...

🛡️  Security Score: 45/100

📊 Vulnerability Summary:
   🚨 Critical: 3
   ⚠️  High: 2
   ⚡ Medium: 4
   💡 Low: 1

🚨 CRITICAL Vulnerabilities:

   [insecure-node-integration] nodeIntegration enabled - major security risk
   File: main.js (line 12)
   Fix: Set nodeIntegration: false and use contextBridge
   Reference: Enables attacks like CVE-2022-29247

   [missing-context-bridge] Preload script not using contextBridge API
   File: preload.js
   Fix: Use contextBridge.exposeInMainWorld for secure IPC

   [dangerous-api-exposure] IPC handler 'file-operation' exposes dangerous API: fs
   File: main.js (line 45)
   Fix: Never expose Node.js system APIs directly via IPC
   Reference: Common attack vector in Electron apps

⚠️  HIGH Vulnerabilities:

   [unvalidated-ipc-handler] IPC handler 'get-user-data' lacks input validation
   File: main.js (line 67)
   Fix: Add input validation to prevent injection attacks
   Reference: Related to CVE-2022-29247

🛡️  Security Recommendations:

   🚨 Fix critical vulnerabilities immediately
      Critical vulnerabilities can lead to RCE or data theft

   🚨 Disable nodeIntegration and enable contextIsolation
      This is the most important security configuration

📚 Security Resources:
   • https://www.electronjs.org/docs/latest/tutorial/security
   • https://github.com/electron/electron/security/advisories
   • OWASP Electron Security Guidelines

🔧 IPC Channel Management (Bonus Feature)

# Check for IPC channel issues
electron-channel-doctor check

# Auto-fix missing channels  
electron-channel-doctor fix

# List all channels
electron-channel-doctor list

# See what would be fixed (dry run)
electron-channel-doctor fix --dry-run

🎯 Real-World Examples

Before Script Doctor

Your codebase might have:

// unused-helper.js - ENTIRE FILE UNUSED
function calculateTax(amount) { return amount * 0.1; }
function formatCurrency(num) { return '$' + num; }

// main.js  
import { calculateTax, formatCurrency } from './unused-helper.js';
import { moment } from 'moment'; // UNUSED IMPORT

function processOrder(order) {
    // Dead code after return
    return order.total;
    console.log('This never executes'); // DEAD CODE
    
    const tax = calculateTax(order.total); // UNREACHABLE
}

// Duplicate code block in multiple files
if (user.isLoggedIn && user.hasPermission) {
    showDashboard();
    updateUserActivity();
    logAnalytics('dashboard_view');
}

// styles.css
.old-button { color: red; } /* UNUSED CSS CLASS */
.deprecated-modal { display: none; } /* UNUSED CSS CLASS */

After Script Doctor Surgery

// unused-helper.js - FILE REMOVED ENTIRELY ✂️

// main.js  
function processOrder(order) {
    return order.total; // Clean and simple!
}

// Duplicate code extracted to reusable function ✨
function showUserDashboard(user) {
    if (user.isLoggedIn && user.hasPermission) {
        showDashboard();
        updateUserActivity(); 
        logAnalytics('dashboard_view');
    }
}

// styles.css - UNUSED CLASSES REMOVED ✂️
/* Only the CSS you actually use remains */

Result:

• 🎯 Cleaner codebase with only code that serves a purpose
• 📦 Smaller bundle size - faster loading times
• 🐛 Fewer potential bugs - less code to maintain
• 🔍 Easier debugging - no distractions from dead code

🏥 Health Scoring System

Your project gets a 0-100 health score based on:

| Score Range | Health Status | Meaning | |-------------|---------------|---------| | 90-100 | 🎉 Excellent | Professional-grade codebase | | 70-89 | 👍 Good | Minor improvements needed | | 50-69 | ⚠️ Needs Work | Surgery recommended | | 0-49 | 🚨 Critical | Immediate attention required |

Scoring factors:

• Unused Functions: -2 points each (max -20)
• Unused Imports: -1 point each (max -10)
• Dead Code Paths: -3 points each (max -15)
• Duplicate Code: -2 points each (max -10)
• Complexity Issues: -1 point each (max -15)
• IPC Channel Issues: -1 to -2 points each (max -20)
• 🔒 Security Vulnerabilities (NEW):
  • Critical: -10 points each (max -30)
  • High: -5 points each (max -20)
  • Medium: -2 points each (max -10)
  • Low: -0.5 points each (max -5)

⚙️ Configuration Options

Command Line Options

# Custom file patterns
electron-channel-doctor health \
  --source "src/**/*.{js,jsx,ts,tsx}" \
  --css "styles/**/*.{css,scss,sass}" \
  --html "templates/**/*.html"

# Custom preload path (for IPC features)
electron-channel-doctor health --preload "main/preload.js"

# Control backup behavior
electron-channel-doctor surgery --no-backup  # DANGEROUS!

# Selective operations  
electron-channel-doctor surgery --operations "unused-functions,dead-code-paths"

Configuration File

Create .channel-doctor.json:

{
  \"preloadPath\": \"electron/preload.js\",
  \"jsPattern\": \"src/**/*.{js,jsx,ts,tsx}\",
  \"cssPattern\": \"styles/**/*.{css,scss,sass}\",
  \"htmlPattern\": \"templates/**/*.html\",
  \"ignorePatterns\": [
    \"**/node_modules/**\",
    \"**/dist/**\",
    \"**/test/**\",
    \"**/*.min.js\"
  ]
}

🔄 CI/CD Integration

GitHub Actions

name: Code Health Check
on: [push, pull_request]

jobs:
  health-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm install -g electron-channel-doctor
      
      # Health check (fails if score < 70)
      - run: |
          SCORE=$(electron-channel-doctor health --json | jq '.healthScore')
          echo \"Health Score: $SCORE\"
          if [ \"$SCORE\" -lt 70 ]; then
            echo \"❌ Health score too low: $SCORE/100\"
            exit 1
          fi
      
      # Generate and upload health report
      - run: electron-channel-doctor report --format markdown --output HEALTH.md
      - uses: actions/upload-artifact@v3
        with:
          name: health-report
          path: HEALTH.md

npm scripts

{
  \"scripts\": {
    \"health\": \"electron-channel-doctor health\",
    \"security\": \"electron-channel-doctor security\",
    \"surgery\": \"electron-channel-doctor surgery --dry-run\",
    \"cleanup\": \"electron-channel-doctor surgery\",
    \"health-report\": \"electron-channel-doctor report --format markdown --output HEALTH.md\",
    \"security-report\": \"electron-channel-doctor security --output security-report.json\",
    \"precommit\": \"electron-channel-doctor health --json | jq -e '.healthScore >= 70'\",
    \"security-check\": \"electron-channel-doctor security --json | jq -e '.summary.critical == 0'\"
  }
}

🛠️ API Usage

const { 
  ChannelDoctor, 
  UnusedCodeDetector, 
  CodeSurgeon,
  SafeCodeSurgeon,  // NEW: AST-based safe surgeon
  SecurityAnalyzer,
  checkHealth,
  performSurgery,
  generateHealthReport,
  analyzeSecurity
} = require('electron-channel-doctor');

// Quick health check
const healthReport = await checkHealth({
  jsPattern: 'src/**/*.js',
  cssPattern: 'styles/**/*.css'
});

console.log(`Health Score: ${healthReport.healthScore}/100`);

// Perform surgery (uses Safe Mode by default)
if (healthReport.healthScore < 70) {
  const surgeryReport = await performSurgery({
    safeMode: true, // Default: true
    validateSyntax: true, // Default: true
    conservative: true, // Default: true
    maxChangesPerFile: 10, // Default: 10
    operations: ['unused-functions', 'unused-imports']
  });
  
  console.log(`Removed ${surgeryReport.summary.totalLinesRemoved} lines`);
  console.log(`Safety score: ${surgeryReport.summary.safetyScore}/100`);
}

// Direct usage of SafeCodeSurgeon (NEW)
const safeSurgeon = new SafeCodeSurgeon({
  projectRoot: process.cwd(),
  dryRun: false,
  validateSyntax: true,
  conservative: true,
  maxChangesPerFile: 5,
  verbose: true
});

const analysisReport = await doctor.performHealthCheckup();
const safeReport = await safeSurgeon.performSafeSurgery(analysisReport);

if (safeReport.errors.length > 0) {
  console.error('Some files could not be safely modified:');
  safeReport.errors.forEach(err => {
    console.error(`- ${err.file}: ${err.error}`);
  });
}

// Security analysis
const securityReport = await analyzeSecurity({
  mainProcess: ['main.js', 'electron/**/*.js'],
  rendererProcess: ['src/**/*.js', 'renderer/**/*.js']
});

if (securityReport.summary.critical > 0) {
  console.error('Critical security vulnerabilities found!');
  process.exit(1);
}

// Advanced usage with custom configuration
const doctor = new ChannelDoctor({
  jsPattern: 'src/**/*.{js,tsx}',
  verbose: true
});

const analysis = await doctor.performHealthCheckup();

// Choose between safe and legacy surgery
const surgery = await doctor.performCodeSurgery({
  safeMode: true, // Use AST-based safe mode (recommended)
  // safeMode: false, // Use regex-based legacy mode (dangerous)
});

const security = await doctor.analyzeSecurityVulnerabilities();

🌟 Success Stories

"Reduced our bundle size by 15% in one command!"
- React developer who used Script Doctor on a legacy codebase

"Found 47 unused functions we didn't even know existed"
- Team lead who ran health check on 6-month-old project

"The health scoring system helps us maintain code quality over time"
- DevOps engineer using it in CI/CD pipeline

🔐 Safety Features

Automatic Backups

• 📋 Complete backup of all modified files before surgery
• 📅 Timestamped folders for easy identification
• 🔧 One-click restore script included
• 💾 Backup location clearly displayed

Safe Defaults

• ⚡ Dry run mode available for all operations
• 🔒 Safe mode enabled by default (creates backups)
• 🎯 Selective operations - choose what to clean
• 📊 Verbose logging to see exactly what's happening

Smart Detection

• 🧠 Context-aware - understands usage patterns
• 🔍 Cross-file analysis - tracks usage across your entire codebase
• 🛡️ False positive prevention - conservative approach to avoid breaking code
• 📝 Infrastructure preservation - keeps essential utility functions

👩‍💻 For Developers: Architecture & Testing

Dependency Injection Pattern

As of version 2.2.1, Electron Channel Doctor uses a dependency injection pattern for file system operations, making it highly testable and maintainable:

const { ChannelDoctor, FileSystem, MockFileSystem } = require('electron-channel-doctor');

// Production usage (uses real file system)
const doctor = new ChannelDoctor({
  projectRoot: '/path/to/project',
  jsPattern: 'src/**/*.js'
});

// Testing usage (uses mock file system)
const mockFiles = {
  '/test/project/src/app.js': `electronAPI.invoke('test-channel');`,
  '/test/project/electron/preload.js': `const validInvokeChannels = ['test-channel'];`
};

const testDoctor = new ChannelDoctor({
  projectRoot: '/test/project',
  fs: new MockFileSystem(mockFiles)  // Inject mock file system
});

FileSystem Abstraction

// Real file system (default)
const fs = new FileSystem();
await fs.readFile('/path/to/file.js');
const files = fs.findFiles('src/**/*.js', '/project/root', ['node_modules/**']);

// Mock file system (for testing)
const mockFs = new MockFileSystem({
  '/project/src/app.js': 'console.log("Hello World");',
  '/project/src/utils.js': 'export const helper = () => {};'
});
await mockFs.readFile('/project/src/app.js'); // Returns mock content
const files = mockFs.findFiles('src/**/*.js', '/project'); // Returns matching mock files

Advanced API Usage with Dependency Injection

const { 
  ChannelDoctor, 
  SecurityAnalyzer, 
  UnusedCodeDetector,
  MockFileSystem 
} = require('electron-channel-doctor');

// Create custom file system for testing
const mockFiles = {
  '/project/main.js': `
    const { BrowserWindow } = require('electron');
    const win = new BrowserWindow({
      webPreferences: { nodeIntegration: true } // Security issue!
    });
  `,
  '/project/src/app.js': `
    electronAPI.invoke('get-user-data');
    electronAPI.invoke('missing-channel');
  `,
  '/project/electron/preload.js': `
    const { contextBridge } = require('electron');
    const validInvokeChannels = ['get-user-data'];
  `
};

// All analyzers support dependency injection
const mockFs = new MockFileSystem(mockFiles);

const channelAnalysis = await new ChannelDoctor({
  projectRoot: '/project',
  fs: mockFs
}).analyze();

const securityAnalysis = await new SecurityAnalyzer({
  projectRoot: '/project',
  fs: mockFs
}).analyze();

const unusedCodeAnalysis = await new UnusedCodeDetector({
  projectRoot: '/project', 
  fs: mockFs
}).analyzeProject();

Testing Your Own Extensions

If you're building on top of Electron Channel Doctor, you can easily test your extensions:

// test/my-extension.test.js
const { MockFileSystem } = require('electron-channel-doctor');

describe('My Extension', () => {
  test('should detect custom patterns', async () => {
    const mockFiles = {
      '/project/custom.js': 'myCustomAPI.call("test");'
    };
    
    const mockFs = new MockFileSystem(mockFiles);
    const result = await myExtension.analyze({
      projectRoot: '/project',
      fs: mockFs  // Use mock instead of real file system
    });
    
    expect(result.patterns).toContain('test');
  });
});

MockFileSystem Features

The MockFileSystem class provides comprehensive file system mocking:

• Glob Pattern Support: Handles **/*.js, src/**/*.{js,ts}, etc.
• Path Resolution: Correctly resolves relative and absolute paths
• File Reading: Returns mock content for specified files
• Directory Traversal: Simulates real directory structures
• Error Simulation: Can simulate file not found and permission errors

const mockFs = new MockFileSystem({
  '/project/src/app.js': 'console.log("app");',
  '/project/src/utils/helper.js': 'export const help = () => {};',
  '/project/test/app.test.js': 'describe("app", () => {});'
});

// Supports complex glob patterns
const jsFiles = mockFs.findFiles('src/**/*.js', '/project');
// Returns: ['/project/src/app.js', '/project/src/utils/helper.js']

const allFiles = mockFs.findFiles('**/*.{js,ts}', '/project', ['test/**']);
// Returns: ['/project/src/app.js', '/project/src/utils/helper.js']
// (excludes test directory)

🤝 Contributing

We welcome contributions! This tool has huge potential for expansion:

Ideas for contributors:

• 🔌 ESLint plugin integration
• 📝 TypeScript support improvements
• 🎨 SCSS/SASS advanced parsing
• 🔧 Framework-specific optimizations (React, Vue, Angular)
• 📊 More analysis types (security, performance, accessibility)
• 🌐 Web app version for online analysis

git clone https://github.com/LFarmbot/electron-channel-doctor.git
cd electron-channel-doctor
npm install
npm test

📋 Roadmap

Phase 1: Core Surgery ✅

• [x] Unused function detection & removal
• [x] Unused import cleanup
• [x] CSS class analysis
• [x] Dead code path removal
• [x] Health scoring system

Phase 2: Advanced Analysis 🔄

• [x] Security analysis - detect vulnerable patterns ✅
• [ ] Performance analysis - identify bottlenecks
• [ ] Accessibility analysis - find a11y issues
• [ ] SEO analysis - optimize meta tags & structure

Phase 3: Ecosystem Integration 📋

• [ ] VS Code extension - real-time health monitoring
• [ ] ESLint plugin - prevent issues before they happen
• [ ] Webpack plugin - build-time optimization
• [ ] GitHub App - automatic PR analysis

Phase 4: Advanced Surgery 📋

• [ ] Refactoring suggestions - automated code improvements
• [ ] Design pattern detection - suggest better architectures
• [ ] Dependency optimization - remove unused npm packages
• [ ] Bundle analysis - deep bundle size optimization

📄 License

MIT License - see LICENSE file for details.

❤️ Made for Developers, by Developers

This tool was born from real frustration with messy codebases and the manual work of cleaning them up. We believe every developer deserves:

• 🎯 Clean, maintainable code that's easy to work with
• 📦 Optimized bundles that load fast for users
• 🔍 Insight into code health without manual analysis
• 🛠️ Automated tools that save time and prevent errors

Found this helpful? ⭐ Star the repo and share with your team!

🩺 Keep your code healthy - your future self will thank you!