klubhaus-doorbell/libraries/FastLED/docs/javascript-linting.md

FastLED JavaScript Linting & Type Safety Strategy

📊 Current Status

Codebase Overview

• 8 JavaScript files in src/platforms/wasm/
• 5,713 lines of code total
• 714 lines average per file
• Comprehensive JSDoc coverage (100% of files documented)
• Modern JavaScript features (ES2022, async/await, classes)

Current Linting Configuration

• Fast Node.js + ESLint linting with critical issue detection
• Speed-optimized approach - fast linting or no linting at all
• Critical runtime issues only - no style enforcement
• Browser environment compatibility (DOM, WebAssembly, Web Audio API)

🎯 Fast-Only Linting Strategy

Current Configuration (Critical Issues Only)

The fast linter only checks for critical runtime issues:

• no-debugger - Prevents debugger statements in production
• no-eval - Prevents eval() security vulnerabilities

No style enforcement - focuses on critical issues only for maximum speed.

Performance Results

• JavaScript linting: ~0.9 seconds (53x faster than previous solution)
• Total lint time: ~1.6 seconds (Python + C++ + JavaScript)

Philosophy: Fast Only

JavaScript linting follows a "fast only" policy:

• ✅ Fast linting available: Uses Node.js + ESLint (~0.9 seconds)
• ⚠️ Fast linting unavailable: Skips JavaScript linting entirely
• ❌ No slow fallback: Fast linting or no linting at all

🛠️ Available Tools

Setup (Automatic)

Fast JavaScript linting is automatically installed during project setup:

# Installs everything including fast JS linting
./install

# Or manually install just JavaScript linting
uv run ci/setup-js-linting-fast.py

Direct Linting Commands

# Fast JavaScript linting (recommended)
bash .cache/js-tools/lint-js-fast

# Full project linting (includes JavaScript when available)
bash lint

Enhancement Analysis Script

# Comprehensive codebase analysis
uv run scripts/enhance-js-typing.py --approach summary

# Detailed linting issue breakdown
uv run scripts/enhance-js-typing.py --approach linting

# Performance issue identification
uv run scripts/enhance-js-typing.py --approach performance

# Add JSDoc type annotations to file
uv run scripts/enhance-js-typing.py --approach types --file src/platforms/wasm/compiler/index.js

# Generate ESLint configuration variants
uv run scripts/enhance-js-typing.py --approach configs

📈 Configuration Variants

Current Configuration (Fast & Minimal)

module.exports = {
  env: {
    browser: true,
    es2022: true,
    worker: true
  },
  parserOptions: {
    ecmaVersion: 2022,
    sourceType: "module"
  },
  rules: {
    // Only critical runtime issues
    "no-debugger": "error",
    "no-eval": "error"
  }
};

Strict Configuration (Available via configs script)

module.exports = {
  env: {
    browser: true,
    es2022: true,
    worker: true
  },
  parserOptions: {
    ecmaVersion: 2022,
    sourceType: "module"
  },
  rules: {
    // Critical issues
    "no-debugger": "error",
    "no-eval": "error",
    // Code quality
    "eqeqeq": "error",
    "prefer-const": "error",
    "no-var": "error",
    "no-await-in-loop": "error",
    "guard-for-in": "error",
    "camelcase": "warn",
    "default-param-last": "warn"
  }
};

🚀 Implementation Roadmap

Immediate Actions (Week 1)

1. Use fast linting - Integrated into bash lint by default
2. Fix critical issues - Only debugger and eval() usage
3. Document changes - Update code comments

Short-term Goals (Month 1)

1. Add @ts-check to one file as pilot
2. Enhance JSDoc for complex functions
3. Create type definitions for WebAssembly interfaces
4. Set up CI integration for automatic linting

Long-term Vision (Quarter 1)

1. Gradual enhancement - Add more rules incrementally
2. Performance optimization - Identify and fix await-in-loop issues
3. Type safety - Comprehensive JSDoc annotations
4. Automated enforcement - CI/CD integration

🔧 Troubleshooting

Fast Linting Not Available

If you see "JavaScript linting tools not found":

# Install fast linting
uv run ci/setup-js-linting-fast.py

# Verify installation
bash .cache/js-tools/lint-js-fast

Performance Issues

If linting is slow:

• Fast linting should complete in ~0.9 seconds
• If slower, check Node.js installation in .js-tools/
• Consider regenerating setup: rm -rf .js-tools && uv run ci/setup-js-linting-fast.py

Configuration Issues

If linting fails:

• Check ESLint configuration: .js-tools/.eslintrc.js
• Verify Node.js modules: .js-tools/node_modules/.bin/eslint
• Test manually: bash .cache/js-tools/lint-js-fast

📝 Files Created

The fast linting setup creates:

• .js-tools/node/ - Node.js binary
• .js-tools/node_modules/ - ESLint installation
• .js-tools/.eslintrc.js - ESLint configuration
• .js-tools/package.json - Node.js package definition
• .cache/js-tools/lint-js-fast - Fast linting script

🎯 Best Practices

1. Use bash lint for comprehensive project linting
2. Fix critical issues immediately - debugger and eval() usage
3. Use enhancement script for deeper analysis
4. Add JSDoc gradually - enhance type safety over time
5. Test before committing - ensure linting passes