rspade_system/app/RSpade/CodeQuality/Support/CLAUDE.md

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

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/JsParsers/CLAUDE.md for detailed RPC pattern documentation.

Js_CodeQuality_Rpc - RPC Server Architecture

Overview

JavaScript linting and this-usage analysis use a long-running Node.js RPC server via Unix socket to avoid spawning thousands of Node processes during code quality checks.

Components

• Js_CodeQuality_Rpc.php - PHP client, manages server lifecycle
• js-code-quality-server.js - Node.js RPC server, processes lint and this-usage analysis requests

Server Lifecycle

1. Lazy start: Server spawns on first lint or analyze_this call 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 linting and this-usage analysis goes through RPC
5. Shutdown: Graceful shutdown when code quality checks complete (registered shutdown handler)

Socket

• Path: storage/rsx-tmp/js-code-quality-server.sock
• Protocol: Line-delimited JSON over Unix domain socket

RPC Methods

• ping → "pong" - Health check
• lint → {file: {status, error}, ...} - Check JavaScript syntax using Babel parser
• analyze_this → {file: {status, violations}, ...} - Analyze 'this' usage patterns using Acorn
• shutdown → Graceful server termination

PHP API

Js_CodeQuality_Rpc::lint($file_path);         // Returns error array or null
Js_CodeQuality_Rpc::analyze_this($file_path); // Returns violations array
Js_CodeQuality_Rpc::start_rpc_server();       // Lazy init, auto-called
Js_CodeQuality_Rpc::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

Both lint and analyze_this have their own caching layers:

• Lint cache: Flag files in storage/rsx-tmp/cache/js-lint-passed/ (mtime-based)
• This-usage cache: JSON files in storage/rsx-tmp/cache/code-quality/js-this/ (mtime-based)

Cache is checked before RPC call - only files with stale cache are sent to the server.

Error Handling

Server failure → fatal error for lint, silent failure for analyze_this.

Performance Impact

Before RPC: Thousands of Node.js process spawns during rsx:check (~20+ seconds on first run) After RPC: Single Node.js process, reused across all operations (~1-2s startup overhead)