# Code Quality Support Classes

## FileSanitizer - RPC Server Architecture

### Overview
JavaScript sanitization uses long-running Node.js RPC server via Unix socket to avoid spawning 1000+ Node processes during manifest build.

### Components
- `FileSanitizer.php` - PHP client, manages server lifecycle
- `js-sanitizer-server.js` - Node.js RPC server, processes batch sanitization requests
- `js-sanitizer.js` - Legacy single-file sanitizer (kept in `/bin/` for compatibility)

### Server Lifecycle
1. **Lazy start:** Server spawns on first JS file sanitization during code quality checks
2. **Startup:** Checks for stale socket, force-kills if found, starts fresh server
3. **Wait:** Polls socket with ping (50ms intervals, 10s max), fatal error if timeout
4. **Usage:** All JS sanitization during checks goes through RPC
5. **Shutdown:** Graceful shutdown when code quality checks complete (registered shutdown handler)

### Socket
- **Path:** `storage/rsx-tmp/js-sanitizer-server.sock`
- **Protocol:** Line-delimited JSON over Unix domain socket

### RPC Methods
- `ping` → `"pong"` - Health check
- `sanitize` → `{file: {status, sanitized, original_lines}, ...}` - Batch sanitize multiple files
- `shutdown` → Graceful server termination

### PHP API
```php
FileSanitizer::sanitize_javascript($file_path);  // Auto-starts RPC server, uses cache
FileSanitizer::start_rpc_server();               // Lazy init, auto-called
FileSanitizer::stop_rpc_server($force);          // Clean shutdown
```

### Force Parameter
`stop_rpc_server($force = false)`:
- `false` (default): Send shutdown command, return immediately
- `true`: Send shutdown + wait + SIGTERM if needed (used for stale server cleanup)

### Cache Integration
Cache checked before RPC call - only files with stale cache sent to server for sanitization. Cache directory: `storage/rsx-tmp/cache/js-sanitized/`

### Error Handling
Server failure → fatal error (no fallback). Server must start or code quality check fails.

### Sanitization Process
1. **Remove comments:** Uses `decomment` npm package to strip comments while preserving line numbers
2. **Replace string contents:** Parses with Acorn AST parser, replaces string literal contents with spaces
3. **Preserve structure:** Maintains line/column positions for accurate violation reporting

### Performance Impact
Before RPC: 900+ Node.js process spawns during manifest build (~30-60s overhead)
After RPC: Single Node.js process, reused across all sanitizations (~1-2s startup overhead)

### Parallel to JS Parser
This architecture mirrors the JS parser RPC server pattern. See `/app/RSpade/Core/JavaScript/CLAUDE.md` for detailed RPC pattern documentation.