🩺 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!

$3

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

$3

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

$3

- ✅ 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

``bash


Global installation (recommended)

npm install -g electron-channel-doctor

Or use with npx (no installation needed)

npx electron-channel-doctor
`

---

🩺 Script Doctor Usage

$3

`bash

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
`

$3


`bash

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
`

$3

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)
`bash


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)
`bash


⚠️ 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:
`javascript
// 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
`bash
$ 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.
`

$3


`bash

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

$3

`bash

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)

`bash


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

$3

Your codebase might have:
`javascript
// 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 /
`

$3


`javascript
// 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

$3


`bash

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"
`

$3

Create .channel-doctor.json:
`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

$3

`yaml
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
`

$3


`json
{
\"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

`javascript
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

$3

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

$3

- ⚡ 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

$3

- 🧠 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

$3

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

`javascript
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
});
`

$3

`javascript
// 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
`

$3

`javascript
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();
`

$3

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

`javascript
// 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');
});
});
`

$3

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

`javascript
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

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

---

📋 Roadmap

$3

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

$3

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

$3

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

$3

- [ ] 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!