@sun-asterisk/sunlint

# Dart Language Support - Implementation Summary ## Overview This document describes the implementation of Dart language support in SunLint. The implementation follows the plan outlined in `DART_SUPPORT_PLAN.md` and maintains full backward compatibility with TypeScript/JavaScript analysis. ## Architecture ``` ┌─────────────────────────────────────────────────────────────────┐ │ SunLint CLI (TypeScript) │ │ - Config Management │ │ - File Targeting │ │ - Analysis Orchestration │ │ - Report Generation │ └────────┬────────────────────────────────────────────────────────┘ │ ├─► SemanticEngineManager (NEW) │ ├── TypeScriptAnalyzer (wrapper around SemanticEngine) │ │ └─ For .ts, .tsx, .js, .jsx files │ │ │ └── DartAnalyzer (NEW) │ └─ For .dart files │ └─ JSON-RPC subprocess (when binary available) │ └─ Regex fallback mode (when binary not available) │ └─► HeuristicEngine ├── Uses SemanticEngineManager for multi-language support └── Falls back to legacy SemanticEngine for TypeScript ``` ## Implemented Components ### 1. Core Interfaces #### `core/interfaces/language-analyzer.interface.js` - `ILanguageAnalyzer` - Abstract base class for all language analyzers - `LanguageAnalyzerRegistry` - Manages registration and lookup of analyzers - `getRegistry()` - Singleton accessor for the registry Key methods: - `initialize(config)` - Initialize the analyzer - `analyzeFile(filePath, rules, options)` - Analyze a single file - `getSymbolTable(filePath)` - Get symbol table for semantic analysis - `supportsFile(filePath)` - Check if file is supported ### 2. Semantic Engine Manager #### `core/semantic-engine-manager.js` - `SemanticEngineManager` - Coordinates multiple language analyzers - `getManager(options)` - Singleton accessor - `resetManager()` - Reset singleton (for testing) Key methods: - `registerAnalyzer(analyzer)` - Register a language analyzer - `initialize(projectPath, targetFiles)` - Initialize all analyzers - `getSymbolTable(filePath)` - Route to appropriate analyzer - `analyzeFile/analyzeFiles()` - Analyze files with correct analyzer - `groupFilesByAnalyzer(files)` - Group files by their analyzer ### 3. Language Analyzers #### `core/adapters/typescript-analyzer.js` - Wraps existing `SemanticEngine` (ts-morph) - Supports: `.ts`, `.tsx`, `.js`, `.jsx`, `.mts`, `.cts`, `.mjs`, `.cjs` - Full backward compatibility with existing semantic rules #### `core/adapters/dart-analyzer.js` - New Dart language analyzer - Supports: `.dart` - Two operation modes: 1. **Binary mode**: Communicates with Dart analyzer binary via JSON-RPC 2. **Fallback mode**: Uses regex-based analysis when binary not available Binary resolution priority: 1. Bundled binary: `bin/sunlint-dart-{platform}` 2. Cached binary: `~/.sunlint/bin/sunlint-dart-{platform}` 3. Dart SDK: `dart pub global run` (future) 4. Fallback: Regex-based analysis Built-in Dart patterns: - `N001` - Naming conventions (UpperCamelCase for classes, lowerCamelCase for variables) - `E001` - Empty catch blocks - `S003` - Sensitive data in print statements - `S022` - String interpolation (potential XSS) ### 4. Analyzer Registration #### `core/adapters/index.js` - `registerBuiltInAnalyzers(options)` - Register all built-in analyzers - `getSupportedLanguages()` - Get list of supported languages - `getAnalyzerClass(language)` - Get analyzer class for a language ### 5. Heuristic Engine Updates #### `engines/heuristic-engine.js` Updated to support multi-language analysis: ```javascript // Constructor additions this.semanticEngineManager = null; // initializeSymbolTable() changes - Register built-in analyzers - Initialize SemanticEngineManager - Keep legacy SemanticEngine for backward compatibility // New methods getSemanticEngineManager() - Get the manager instance getLanguageAnalyzer(language) - Get specific analyzer getSymbolTableForFile(filePath) - Route to correct analyzer // Cleanup - Cleanup SemanticEngineManager - Cleanup legacy SemanticEngine ``` ## File Targeting The `FileTargetingService` already supports Dart files: - Extension: `.dart` - Excluded patterns: `*.g.dart`, `*.freezed.dart`, `*.mocks.dart` (generated files) ## Usage ### CLI Usage ```bash # Analyze Dart files sunlint --input="lib/" --include="**/*.dart" # Analyze mixed project (TypeScript + Dart) sunlint --input="src/" --include="**/*.{ts,tsx,dart}" # With verbose output sunlint --input="lib/" --include="**/*.dart" --verbose ``` ### Programmatic Usage ```javascript const { getManager } = require('sunlint/core/semantic-engine-manager'); const { registerBuiltInAnalyzers } = require('sunlint/core/adapters'); // Register analyzers registerBuiltInAnalyzers({ verbose: true }); // Get manager const manager = getManager(); // Initialize await manager.initialize('/path/to/project', targetFiles); // Get symbol table for any file type const symbolTable = await manager.getSymbolTable('/path/to/file.dart'); // Analyze files const violations = await manager.analyzeFile(filePath, rules, options); ``` ## Testing Run unit tests: ```bash node test/unit/dart-support.test.js ``` Test coverage: - ✅ ILanguageAnalyzer interface abstraction - ✅ TypeScriptAnalyzer creation and file support - ✅ DartAnalyzer creation and file support - ✅ LanguageAnalyzerRegistry registration and lookup - ✅ SemanticEngineManager initialization - ✅ File grouping by analyzer - ✅ DartAnalyzer regex patterns - ✅ DartAnalyzer basic symbol table extraction ## Backward Compatibility All existing functionality is preserved: - ✅ TypeScript/JavaScript analysis works unchanged - ✅ Existing semantic rules work unchanged - ✅ Configuration format unchanged - ✅ CLI options unchanged - ✅ Report format unchanged ## Future Work (Phase 2-6) ### Phase 2: Dart Analyzer Binary - Create Dart project with JSON-RPC server - Implement full AST analysis - Cross-compile for Linux, macOS, Windows ### Phase 3-4: Build & Distribution - GitHub Actions for binary compilation - npm package with embedded binaries - Post-install verification ### Phase 5: Dart Rules Priority rules to port: - C001 - High Cyclomatic Complexity - C002 - Duplicate Code Detection - C008 - Deep Nesting - N001 - Naming Convention Violations - E001 - Missing Error Handling ### Phase 6: Documentation - Dart-specific user guide - Flutter project examples - CI/CD integration examples ## Files Created/Modified ### New Files - `core/interfaces/language-analyzer.interface.js` - `core/semantic-engine-manager.js` - `core/adapters/typescript-analyzer.js` - `core/adapters/dart-analyzer.js` - `core/adapters/index.js` - `test/unit/dart-support.test.js` - `test/dart-fixtures/sample.dart` - `docs/DART_SUPPORT_IMPLEMENTATION.md` ### Modified Files - `engines/heuristic-engine.js` - Added imports for multi-language support - Added `semanticEngineManager` property - Updated `initializeSymbolTable()` to use SemanticEngineManager - Added helper methods: `getSemanticEngineManager()`, `getLanguageAnalyzer()`, `getSymbolTableForFile()` - Updated `cleanup()` to dispose managers ## Verification ```bash # Verify TypeScript still works node cli.js --rule=S003 --input="./core" --include="**/*.js" --engine=heuristic --max-files=5 # Verify Dart support node cli.js --rule=N001 --input="./test/dart-fixtures" --include="**/*.dart" --verbose # Run unit tests node test/unit/dart-support.test.js ``` All verifications pass successfully.