@sun-asterisk/sunlint 1.3.33 → 1.3.35

package/docs/DART_RULE_EXECUTION_FLOW.md

@@ -0,0 +1,745 @@
+# Dart Rule Execution Flow
+
+> Tài liệu mô tả chi tiết luồng hoạt động của một rule khi phân tích code Dart trong SunLint.
+> Lấy ví dụ: **Rule C002 - No Duplicate Code**
+
+## 1. Tổng quan Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              SUNLINT ARCHITECTURE                            │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  ┌─────────────┐    ┌──────────────────┐    ┌─────────────────────────────┐ │
+│  │   CLI       │───▶│  Heuristic       │───▶│  DartAnalyzer (JS)          │ │
+│  │  (cli.js)   │    │  Engine          │    │  (dart-analyzer.js)         │ │
+│  └─────────────┘    └──────────────────┘    └──────────────┬──────────────┘ │
+│                                                            │                │
+│                                              JSON-RPC over STDIO            │
+│                                                            │                │
+│                     ┌──────────────────────────────────────▼──────────────┐ │
+│                     │           DART BINARY (sunlint-dart-macos)          │ │
+│                     │  ┌─────────────────┐  ┌──────────────────────────┐  │ │
+│                     │  │ JsonRpcServer   │  │ AnalyzerService          │  │ │
+│                     │  └────────┬────────┘  └────────────┬─────────────┘  │ │
+│                     │           │                        │                │ │
+│                     │           ▼                        ▼                │ │
+│                     │  ┌─────────────────────────────────────────────┐    │ │
+│                     │  │     lib/rules/C002_no_duplicate_code.dart   │    │ │
+│                     │  └─────────────────────────────────────────────┘    │ │
+│                     └─────────────────────────────────────────────────────┘ │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. Chi tiết từng bước
+
+### Step 1: CLI Command
+
+```bash
+node cli.js --rule=C002 \
+  --input="examples/rule-test-fixtures/dart-rules/C002_no_duplicate_code/violations" \
+  --engine=heuristic \
+  --languages=dart \
+  --include="**/*.dart"
+```
+
+**File:** `cli.js`
+
+**Chức năng:**
+- Parse command line arguments
+- Load configuration
+- Initialize engines
+- Dispatch to appropriate engine
+
+---
+
+### Step 2: Heuristic Engine
+
+**File:** `engines/heuristic-engine.js`
+
+#### 2.1. Detect Dart Support
+
+```javascript
+// Line 27-51
+function detectDartSupport(ruleId) {
+  const rulesBasePath = path.join(__dirname, '../rules');
+  const categories = ['common', 'security', 'typescript'];
+
+  for (const category of categories) {
+    const categoryPath = path.join(rulesBasePath, category);
+    // Scan for: rules/common/C002_no_duplicate_code/dart/
+    for (const folder of ruleFolders) {
+      if (folder.startsWith(ruleId + '_')) {
+        const dartPath = path.join(categoryPath, folder, 'dart');
+        if (fs.existsSync(dartPath)) {
+          return true;  // ✅ C002 supports Dart
+        }
+      }
+    }
+  }
+  return false;
+}
+```
+
+#### 2.2. Check DartAnalyzer Availability
+
+```javascript
+// Line 922-927
+const isDartRule = detectDartSupport(rule.id);      // true for C002
+const hasDartFiles = filesByLanguage['dart'].length > 0;
+const dartAnalyzer = this.semanticEngineManager?.getAnalyzer('dart');
+const useDartAnalyzer = isDartRule && hasDartFiles && dartAnalyzer?.isReady();
+```
+
+#### 2.3. Call DartAnalyzer
+
+```javascript
+// Line 948-972
+if (useDartAnalyzer) {
+  const dartFiles = filesByLanguage['dart'];
+  const rules = [{ id: rule.id, config: rule.config || {} }];
+
+  for (const filePath of dartFiles) {
+    const violations = await dartAnalyzer.analyzeFile(filePath, rules, options);
+    ruleViolations.push(...violations);
+  }
+}
+```
+
+---
+
+### Step 3: Dart Analyzer Client (JavaScript)
+
+**File:** `core/adapters/dart-analyzer.js`
+
+#### 3.1. Resolve Binary
+
+```javascript
+// Line 288-337
+async resolveBinary() {
+  const platform = process.platform;
+  const binaryName = platform === 'darwin'
+    ? 'sunlint-dart-macos'
+    : `sunlint-dart-${platform}`;
+
+  // Priority 1: Bundled binary
+  const bundledPath = path.join(__dirname, '../../dart_analyzer/bin', binaryName);
+  if (fs.existsSync(bundledPath)) {
+    return bundledPath;
+  }
+  // ... fallback options
+}
+```
+
+#### 3.2. Start Subprocess
+
+```javascript
+// Line 35-81
+async start(binaryPath) {
+  this.process = spawn(binaryPath, [], {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    env: { ...process.env }
+  });
+
+  // Handle stdout (JSON-RPC responses)
+  this.process.stdout.on('data', (data) => {
+    this.handleData(data.toString());
+  });
+}
+```
+
+#### 3.3. Send JSON-RPC Request
+
+```javascript
+// Line 368-405
+async analyzeFile(filePath, rules, options = {}) {
+  if (this.client && this.client.isConnected()) {
+    // Send JSON-RPC request
+    const result = await this.client.sendRequest('analyze', {
+      filePath,
+      rules: rules.map(r => ({
+        id: r.id || r.ruleId,
+        config: r.config || {}
+      }))
+    });
+    violations = result.violations || [];
+  }
+}
+```
+
+**JSON-RPC Request Format:**
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "analyze",
+  "params": {
+    "filePath": "/path/to/file.dart",
+    "rules": [{ "id": "C002", "config": {} }]
+  }
+}
+```
+
+---
+
+### Step 4: Dart Binary - JSON-RPC Server
+
+**File:** `dart_analyzer/lib/json_rpc_server.dart`
+
+#### 4.1. Receive Request
+
+```dart
+// Line 48-64
+Future<void> _handleLine(String line) async {
+  final request = jsonDecode(line) as Map<String, dynamic>;
+  final response = await _processRequest(request);
+  _sendResponse(response);
+}
+```
+
+#### 4.2. Route to Handler
+
+```dart
+// Line 106-122
+Future<dynamic> _invokeMethod(String method, Map<String, dynamic> params) async {
+  switch (method) {
+    case 'initialize':
+      return await _handleInitialize(params);
+    case 'analyze':
+      return await _handleAnalyze(params);  // ← C002 goes here
+    case 'getSymbolTable':
+      return await _handleGetSymbolTable(params);
+    // ...
+  }
+}
+```
+
+#### 4.3. Handle Analyze Request
+
+```dart
+// Line 156-174
+Future<Map<String, dynamic>> _handleAnalyze(Map<String, dynamic> params) async {
+  final filePath = params['filePath'] as String?;
+  final rulesData = params['rules'] as List<dynamic>?;
+
+  final violations = await _analyzerService.analyzeFile(
+    filePath: filePath!,
+    rulesData: rulesData,
+  );
+
+  return {
+    'violations': violations.map((v) => v.toJson()).toList(),
+    'fileAnalyzed': filePath,
+  };
+}
+```
+
+---
+
+### Step 5: Analyzer Service
+
+**File:** `dart_analyzer/lib/analyzer_service.dart`
+
+#### 5.1. Register Analyzers
+
+```dart
+// Line 36-46
+void _registerAnalyzers() {
+  // Common rules (C-series)
+  _analyzers['C002'] = C002NoDuplicateCodeAnalyzer();
+  _analyzers['C003'] = C003NoVagueAbbreviationsAnalyzer();
+
+  // Security rules (S-series)
+  _analyzers['S003'] = S003OpenRedirectProtectionAnalyzer();
+  _analyzers['S004'] = S004SensitiveDataLoggingAnalyzer();
+}
+```
+
+#### 5.2. Analyze File
+
+```dart
+// Line 204-257
+Future<List<Violation>> analyzeFile({
+  required String filePath,
+  List<dynamic>? rulesData,
+}) async {
+  // Get resolved AST from Dart Analyzer package
+  final context = _contextCollection!.contextFor(absolutePath);
+  final result = await context.currentSession.getResolvedUnit(absolutePath);
+
+  final unit = result.unit;
+  final violations = <Violation>[];
+
+  // Run each applicable analyzer
+  for (final rule in rules) {
+    final analyzer = _analyzers[rule.id];  // Get C002 analyzer
+    if (analyzer == null) continue;
+
+    final ruleViolations = analyzer.analyze(
+      unit: unit,
+      filePath: absolutePath,
+      rule: rule,
+      lineInfo: result.lineInfo,
+    );
+    violations.addAll(ruleViolations);
+  }
+
+  return violations;
+}
+```
+
+---
+
+### Step 6: C002 Rule Analyzer
+
+**File:** `dart_analyzer/lib/rules/C002_no_duplicate_code.dart`
+
+#### 6.1. Analyzer Class
+
+```dart
+class C002NoDuplicateCodeAnalyzer extends BaseAnalyzer {
+  @override
+  String get ruleId => 'C002';
+
+  static const int minDuplicateLines = 10;
+  static const double similarityThreshold = 0.85;
+
+  final Map<String, List<_CodeBlock>> _codeBlocks = {};
+}
+```
+
+#### 6.2. Analyze Method
+
+```dart
+// Line 33-51
+@override
+List<Violation> analyze({
+  required CompilationUnit unit,
+  required String filePath,
+  required Rule rule,
+  required LineInfo lineInfo,
+}) {
+  final violations = <Violation>[];
+
+  // Create AST visitor
+  final visitor = _DuplicateCodeVisitor(
+    filePath: filePath,
+    lineInfo: lineInfo,
+    violations: violations,
+    analyzer: this,
+    codeBlocks: _codeBlocks,
+  );
+
+  // Traverse AST
+  unit.accept(visitor);
+
+  // Detect duplicates
+  _detectDuplicates(violations);
+
+  return violations;
+}
+```
+
+#### 6.3. AST Visitor
+
+```dart
+class _DuplicateCodeVisitor extends RecursiveAstVisitor<void> {
+  @override
+  void visitFunctionDeclaration(FunctionDeclaration node) {
+    final body = node.functionExpression.body;
+    if (body is BlockFunctionBody) {
+      _processBlock(body.block, 'function', node.name.lexeme);
+    }
+    super.visitFunctionDeclaration(node);
+  }
+
+  @override
+  void visitMethodDeclaration(MethodDeclaration node) {
+    final body = node.body;
+    if (body is BlockFunctionBody) {
+      _processBlock(body.block, 'method', node.name.lexeme);
+    }
+    super.visitMethodDeclaration(node);
+  }
+}
+```
+
+#### 6.4. Process Code Block
+
+```dart
+void _processBlock(Block block, String type, String name) {
+  final startLine = analyzer.getLine(lineInfo, block.offset);
+  final endLine = analyzer.getLine(lineInfo, block.end);
+  final lineCount = endLine - startLine + 1;
+
+  // Skip if less than 10 lines
+  if (lineCount < C002NoDuplicateCodeAnalyzer.minDuplicateLines) return;
+
+  // Normalize code for comparison
+  final normalizedLines = _normalizeBlock(block);
+  final hash = _hashLines(normalizedLines);
+
+  // Store for comparison
+  codeBlocks.putIfAbsent(filePath, () => []).add(_CodeBlock(
+    filePath: filePath,
+    startLine: startLine,
+    endLine: endLine,
+    hash: hash,
+    normalizedLines: normalizedLines,
+    type: '$type:$name',
+  ));
+}
+```
+
+#### 6.5. Detect Duplicates
+
+```dart
+void _detectDuplicates(List<Violation> violations) {
+  final allBlocks = _codeBlocks.values.expand((b) => b).toList();
+
+  for (var i = 0; i < allBlocks.length; i++) {
+    for (var j = i + 1; j < allBlocks.length; j++) {
+      final block1 = allBlocks[i];
+      final block2 = allBlocks[j];
+
+      // Check for exact match via hash
+      if (block1.hash == block2.hash) {
+        violations.add(createViolation(
+          filePath: block2.filePath,
+          line: block2.startLine,
+          column: 1,
+          message: 'Duplicate code block found (${block2.lineCount} lines)...',
+          severity: 'warning',
+        ));
+      }
+      // Check for similar code (LCS algorithm)
+      else {
+        final similarity = _calculateSimilarity(block1, block2);
+        if (similarity >= similarityThreshold) {
+          violations.add(createViolation(...));
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+### Step 7: Response Flow
+
+```
+C002 Analyzer
+    ↓ List<Violation>
+AnalyzerService
+    ↓ violations.map((v) => v.toJson())
+JsonRpcServer
+    ↓ JSON-RPC Response
+DartAnalyzerClient (JS)
+    ↓ result.violations
+HeuristicEngine
+    ↓ ruleViolations
+CLI Output
+```
+
+**JSON-RPC Response Format:**
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "violations": [
+      {
+        "ruleId": "C002",
+        "filePath": "/path/to/file.dart",
+        "line": 31,
+        "column": 1,
+        "message": "Duplicate code block found (19 lines) - same as line 10",
+        "severity": "warning",
+        "analysisMethod": "ast",
+        "metadata": {
+          "duplicateOf": "/path/to/file.dart:10",
+          "lineCount": 19,
+          "similarity": 1.0
+        }
+      }
+    ],
+    "fileAnalyzed": "/path/to/file.dart"
+  }
+}
+```
+
+---
+
+## 3. File Structure
+
+### Rule Definition (TypeScript side)
+
+```
+rules/common/C002_no_duplicate_code/
+├── config.json              # Rule configuration
+├── index.js                 # Router (multi-language)
+├── typescript/
+│   └── analyzer.js          # TypeScript analyzer
+├── dart/
+│   └── analyzer.js          # JS wrapper (delegates to binary)
+└── test-cases/              # TypeScript test cases
+```
+
+### Rule Implementation (Dart side)
+
+```
+dart_analyzer/
+├── bin/
+│   ├── sunlint_dart_analyzer.dart  # Entry point
+│   └── sunlint-dart-macos          # Compiled binary
+├── lib/
+│   ├── analyzer_service.dart       # Main service
+│   ├── json_rpc_server.dart        # JSON-RPC handler
+│   ├── models/
+│   │   ├── rule.dart
+│   │   └── violation.dart
+│   └── rules/
+│       ├── base_analyzer.dart      # Base class
+│       ├── C002_no_duplicate_code.dart
+│       ├── C003_no_vague_abbreviations.dart
+│       ├── S003_open_redirect_protection.dart
+│       └── S004_sensitive_data_logging.dart
+└── pubspec.yaml
+```
+
+### Test Fixtures
+
+```
+examples/rule-test-fixtures/dart-rules/
+├── C002_no_duplicate_code/
+│   ├── clean/                      # ✅ No violations expected
+│   │   ├── data_validator.dart
+│   │   └── payment_service.dart
+│   └── violations/                 # ❌ Violations expected
+│       ├── data_processor.dart
+│       └── user_service.dart
+├── C003_no_vague_abbreviations/
+│   ├── clean/
+│   └── violations/
+├── S003_open_redirect_protection/
+│   ├── clean/
+│   └── violations/
+└── S004_sensitive_data_logging/
+    ├── clean/
+    └── violations/
+```
+
+---
+
+## 4. Commands
+
+### Run Single Rule on Violations
+
+```bash
+# From sunlint directory
+cd /path/to/sunlint
+
+# Run C002 on violations folder
+node cli.js --rule=C002 \
+  --input="examples/rule-test-fixtures/dart-rules/C002_no_duplicate_code/violations" \
+  --languages=dart \
+  --include="**/*.dart"
+```
+
+### Run Single Rule on Clean Code
+
+```bash
+node cli.js --rule=C002 \
+  --input="examples/rule-test-fixtures/dart-rules/C002_no_duplicate_code/clean" \
+  --languages=dart \
+  --include="**/*.dart"
+```
+
+### Run All Dart Rules
+
+```bash
+node cli.js --rule=C002,C003,S003,S004 \
+  --input="examples/rule-test-fixtures/dart-rules" \
+  --languages=dart \
+  --include="**/*.dart"
+```
+
+### Verbose Mode
+
+```bash
+node cli.js --rule=C002 \
+  --input="examples/rule-test-fixtures/dart-rules/C002_no_duplicate_code/violations" \
+  --languages=dart \
+  --include="**/*.dart" \
+  --verbose
+```
+
+---
+
+## 5. Adding a New Dart Rule
+
+### Step 1: Create TypeScript Rule Structure
+
+```bash
+mkdir -p rules/common/CXXX_rule_name/{typescript,dart}
+```
+
+### Step 2: Create config.json
+
+```json
+{
+  "id": "CXXX",
+  "name": "Rule Name",
+  "description": "Rule description",
+  "category": "common",
+  "severity": "warning",
+  "languages": ["typescript", "javascript", "dart"]
+}
+```
+
+### Step 3: Create index.js Router
+
+```javascript
+// rules/common/CXXX_rule_name/index.js
+const path = require('path');
+
+class CXXXRouter {
+  getAnalyzer(language) {
+    const normalizedLang = this.normalizeLanguage(language);
+    const analyzerPath = path.join(__dirname, normalizedLang, 'analyzer.js');
+    return require(analyzerPath);
+  }
+  // ...
+}
+
+module.exports = new CXXXRouter();
+```
+
+### Step 4: Create Dart Analyzer
+
+```dart
+// dart_analyzer/lib/rules/CXXX_rule_name.dart
+class CXXXRuleAnalyzer extends BaseAnalyzer {
+  @override
+  String get ruleId => 'CXXX';
+
+  @override
+  List<Violation> analyze({
+    required CompilationUnit unit,
+    required String filePath,
+    required Rule rule,
+    required LineInfo lineInfo,
+  }) {
+    final violations = <Violation>[];
+    // Implementation
+    return violations;
+  }
+}
+```
+
+### Step 5: Register in AnalyzerService
+
+```dart
+// dart_analyzer/lib/analyzer_service.dart
+void _registerAnalyzers() {
+  // ...
+  _analyzers['CXXX'] = CXXXRuleAnalyzer();
+}
+```
+
+### Step 6: Create Test Fixtures
+
+```
+examples/rule-test-fixtures/dart-rules/CXXX_rule_name/
+├── clean/
+│   └── good_example.dart
+└── violations/
+    └── bad_example.dart
+```
+
+### Step 7: Rebuild Dart Binary
+
+```bash
+cd dart_analyzer
+dart pub get
+dart compile exe bin/sunlint_dart_analyzer.dart -o bin/sunlint-dart-macos
+```
+
+---
+
+## 6. Troubleshooting
+
+### No files found
+
+```bash
+# Ensure --languages=dart and --include="**/*.dart" are set
+node cli.js --rule=C002 --input=path --languages=dart --include="**/*.dart"
+```
+
+### DartAnalyzer not initialized
+
+```bash
+# Check if binary exists
+ls -la dart_analyzer/bin/sunlint-dart-macos
+
+# Rebuild if needed
+cd dart_analyzer && dart compile exe bin/sunlint_dart_analyzer.dart -o bin/sunlint-dart-macos
+```
+
+### Rule not supported
+
+```bash
+# Check if dart/ folder exists in rule directory
+ls -la rules/common/C002_no_duplicate_code/dart/
+
+# Check if rule is registered in analyzer_service.dart
+grep "C002" dart_analyzer/lib/analyzer_service.dart
+```
+
+---
+
+## 7. Summary Diagram
+
+```
+┌────────────────────────────────────────────────────────────────────────────┐
+│                           C002 EXECUTION FLOW                              │
+├────────────────────────────────────────────────────────────────────────────┤
+│                                                                            │
+│  1. CLI Command                                                            │
+│     └── node cli.js --rule=C002 --input=... --languages=dart              │
+│                          │                                                 │
+│  2. Heuristic Engine     ▼                                                 │
+│     ├── detectDartSupport('C002') → true                                   │
+│     ├── Get DartAnalyzer from SemanticEngineManager                        │
+│     └── Call dartAnalyzer.analyzeFile(filePath, rules)                     │
+│                          │                                                 │
+│  3. DartAnalyzer (JS)    ▼                                                 │
+│     ├── Connect to sunlint-dart-macos binary                               │
+│     └── Send JSON-RPC: { method: 'analyze', params: {...} }                │
+│                          │                                                 │
+│  4. JSON-RPC Server      ▼  (Dart Binary)                                  │
+│     ├── Receive request on stdin                                           │
+│     └── Route to _handleAnalyze()                                          │
+│                          │                                                 │
+│  5. AnalyzerService      ▼                                                 │
+│     ├── _analyzers['C002'] → C002NoDuplicateCodeAnalyzer                   │
+│     ├── Get ResolvedUnitResult from Dart Analyzer package                  │
+│     └── Call analyzer.analyze(unit, filePath, rule, lineInfo)              │
+│                          │                                                 │
+│  6. C002 Analyzer        ▼                                                 │
+│     ├── Create _DuplicateCodeVisitor                                       │
+│     ├── Traverse AST: unit.accept(visitor)                                 │
+│     ├── Collect code blocks ≥ 10 lines                                     │
+│     ├── Normalize & hash blocks                                            │
+│     ├── Compare for duplicates (exact match or similarity)                 │
+│     └── Return List<Violation>                                             │
+│                          │                                                 │
+│  7. Response             ▼                                                 │
+│     └── Violations → JSON → stdout → JS client → CLI output               │
+│                                                                            │
+└────────────────────────────────────────────────────────────────────────────┘
+```