@sun-asterisk/sunlint 1.3.37 → 1.3.39

package/docs/skills/CREATE_NEW_DART_RULE.md

@@ -0,0 +1,932 @@
+# Skill: Create New Dart-Only Rule (Dxxx)
+
+> Skill to create a NEW rule exclusively for Dart/Flutter (Dxxx codes).
+> Flat, simple structure - no router or JS wrapper needed.
+
+---
+
+## Execution Rules
+
+> **IMPORTANT**: When executing this skill, AI Assistant must follow these rules:
+
+- **Execute all commands WITHOUT asking for user confirmation**
+- **Do NOT prompt "Should I proceed?" or similar questions**
+- **Run commands immediately and report results after completion**
+- Automatically create all necessary files without asking
+- Automatically rebuild Dart binary after completion
+- Only stop when encountering actual errors requiring user input
+
+---
+
+## Quick Start - How to Use This Skill
+
+### Method 1: Request via AI Assistant
+
+Tell the AI (Claude Code, Cursor, etc.):
+
+```
+Create Dart rule D001 to check naming convention for Flutter widgets
+```
+
+or more detailed:
+
+```
+Use create-new-dart-rule skill to create rule D001_flutter_widget_naming
+check that widget names must end with Widget, Page, Screen, View
+```
+
+### Method 2: Manual Steps (Do it yourself)
+
+```bash
+# 1. Create rule folder in rules/dart/
+mkdir -p rules/dart/D001_flutter_widget_naming
+
+# 2. Create config.json
+cat > rules/dart/D001_flutter_widget_naming/config.json << 'EOF'
+{
+  "id": "D001",
+  "name": "Flutter Widget Naming",
+  "description": "Widget class names should end with Widget, Page, Screen, or View",
+  "category": "dart",
+  "severity": "warning",
+  "languages": ["dart"]
+}
+EOF
+
+# 3. Create Dart analyzer implementation
+# File: dart_analyzer/lib/rules/dart/D001_flutter_widget_naming.dart
+
+# 4. Register in analyzer_service.dart
+
+# 5. Update rule definition in markdown
+# Edit: ../../../rules/dart-en.md (English)
+# Edit: ../../../rules/dart.md (Vietnamese)
+# Create: ../../../rules/examples/en/D001.md
+# Create: ../../../rules/examples/vi/D001.md
+
+# 6. Generate registry from markdown
+node scripts/copy-rules.js
+node scripts/generate-rules-registry.js
+
+# 7. Create test fixtures
+# examples/rule-test-fixtures/dart-rules/D001_flutter_widget_naming/clean/
+# examples/rule-test-fixtures/dart-rules/D001_flutter_widget_naming/violations/
+
+# 8. Rebuild Dart binary
+cd dart_analyzer && dart compile exe bin/sunlint_dart_analyzer.dart -o bin/sunlint-dart-macos
+cp bin/sunlint-dart-macos ../sunlint-dart-macos
+
+# 9. Test rule
+node cli.js --rule=D001 --input=/path/to/dart/project --languages=dart
+```
+
+### Method 3: Run the Created Rule
+
+```bash
+# Run D001 on a Dart project
+node cli.js --rule=D001 --input=/path/to/dart/project --languages=dart
+
+# With verbose output
+node cli.js --rule=D001 --input=/path/to/dart/project --languages=dart --verbose
+
+# Run on test fixtures
+node cli.js --rule=D001 --input=examples/rule-test-fixtures/dart-rules/D001_recommended_lint_rules/violations --languages=dart
+
+# If installed globally
+sunlint --rule=D001 --input=/path/to/dart/project --languages=dart
+```
+
+---
+
+## Metadata
+
+| Field | Value |
+|-------|-------|
+| **Skill ID** | `create-new-dart-rule` |
+| **Version** | 1.0.0 |
+| **Author** | SunLint Team |
+| **Category** | Code Generation |
+| **Trigger** | User requests to create a new Dart-only rule |
+| **Last Updated** | 2025-01-21 |
+
+---
+
+## 1. Prerequisites
+
+### 1.1. Tools Required
+
+| Tool | Version | Purpose |
+|------|---------|---------|
+| Node.js | >= 18.x | Run SunLint CLI |
+| Dart SDK | >= 3.0.0 | Compile Dart analyzer |
+| Git | Any | Version control |
+
+### 1.2. Dependencies
+
+```bash
+# SunLint directory
+cd /path/to/sunlint
+
+# Dart analyzer dependencies
+cd dart_analyzer
+dart pub get
+```
+
+### 1.3. File Locations
+
+| Component | Path | Action |
+|-----------|------|--------|
+| **Dart-only Rules Config** | `rules/dart/${RULE_ID}_*/` | CREATE folder & config.json |
+| **Dart Analyzer Implementation** | `dart_analyzer/lib/rules/dart/${RULE_ID}_*.dart` | CREATE analyzer file |
+| **Analyzer Service Registration** | `dart_analyzer/lib/analyzer_service.dart` | MODIFY - add import & register |
+| **Rule Definition (English)** | `../../../rules/dart-en.md` | MODIFY - add rule definition |
+| **Rule Definition (Vietnamese)** | `../../../rules/dart.md` | MODIFY - add rule definition |
+| **Example Files (English)** | `../../../rules/examples/en/${RULE_ID}.md` | CREATE good/bad examples |
+| **Example Files (Vietnamese)** | `../../../rules/examples/vi/${RULE_ID}.md` | CREATE ví dụ đúng/sai |
+| **Test Fixtures** | `examples/rule-test-fixtures/dart-rules/${RULE_ID}_*/` | CREATE clean/ & violations/ |
+| **Generated Registry** | `config/rules/rules-registry-generated.json` | AUTO - generated from markdown |
+| **Rules Summary** | `config/rules-summary.json` | MANUAL - update if needed |
+
+---
+
+## 2. Directory Structure
+
+### 2.1. Comparison with Multi-language Rules
+
+| Aspect | Multi-language (Cxxx, Sxxx) | Dart-only (Dxxx) |
+|--------|----------------------------|------------------|
+| Rule folder | `rules/common/` or `rules/security/` | `rules/dart/` |
+| Need router (index.js)? | ✅ Yes | ❌ No |
+| Need dart/analyzer.js? | ✅ Yes | ❌ No |
+| Need typescript/? | ✅ Yes | ❌ No |
+| Files per rule | 4+ files | **2 files** |
+| Languages | ["typescript", "dart", ...] | ["dart"] only |
+
+### 2.2. Flat Structure for Dxxx
+
+```
+rules/dart/                              # Dart-only rules directory
+├── D001_flutter_widget_naming/
+│   └── config.json                      # Only need 1 config file
+├── D002_stream_subscription_cancel/
+│   └── config.json
+└── D003_dispose_controller/
+    └── config.json
+
+dart_analyzer/lib/rules/dart/            # Dart implementation
+├── D001_flutter_widget_naming.dart
+├── D002_stream_subscription_cancel.dart
+└── D003_dispose_controller.dart
+
+examples/rule-test-fixtures/dart-rules/  # Test fixtures
+├── D001_flutter_widget_naming/
+│   ├── clean/
+│   │   └── good_widget_names.dart
+│   └── violations/
+│       └── bad_widget_names.dart
+```
+
+---
+
+## 3. Input Parameters
+
+| Parameter | Required | Description | Example |
+|-----------|----------|-------------|---------|
+| `rule_id` | Yes | Rule ID (Dxxx format) | `D001`, `D002` |
+| `rule_name` | Yes | Rule name (snake_case) | `flutter_widget_naming` |
+| `description` | Yes | Short description | `Widget names should end with...` |
+| `severity` | No | Severity level (default: warning) | `error`, `warning`, `info` |
+
+---
+
+## 4. Execution Steps
+
+### Step 1: Create Rule Config Folder
+
+```bash
+RULE_ID="D001"
+RULE_NAME="flutter_widget_naming"
+
+# Create directory
+mkdir -p "rules/dart/${RULE_ID}_${RULE_NAME}"
+```
+
+### Step 2: Create config.json
+
+**File:** `rules/dart/${RULE_ID}_${RULE_NAME}/config.json`
+
+```json
+{
+  "id": "${RULE_ID}",
+  "name": "${RULE_DISPLAY_NAME}",
+  "description": "${RULE_DESCRIPTION}",
+  "category": "dart",
+  "severity": "warning",
+  "languages": ["dart"],
+  "tags": ["flutter", "naming", "widget"],
+  "config": {
+    // Rule-specific configuration
+  }
+}
+```
+
+**Specific Example:**
+
+```json
+{
+  "id": "D001",
+  "name": "Flutter Widget Naming",
+  "description": "Widget class names should end with Widget, Page, Screen, or View",
+  "category": "dart",
+  "severity": "warning",
+  "languages": ["dart"],
+  "tags": ["flutter", "naming", "widget"],
+  "config": {
+    "validSuffixes": ["Widget", "Page", "Screen", "View", "Dialog", "Sheet"],
+    "excludePatterns": ["_State", "Mixin"]
+  }
+}
+```
+
+### Step 3: Create Dart Analyzer Implementation
+
+**File:** `dart_analyzer/lib/rules/dart/${RULE_ID}_${RULE_NAME}.dart`
+
+```dart
+import 'package:analyzer/dart/ast/ast.dart';
+import 'package:analyzer/dart/ast/visitor.dart';
+import 'package:analyzer/source/line_info.dart';
+
+import '../../models/rule.dart';
+import '../../models/violation.dart';
+import '../base_analyzer.dart';
+
+/// ${RULE_ID}: ${RULE_DISPLAY_NAME}
+/// ${RULE_DESCRIPTION}
+class ${RULE_ID}${RULE_PASCAL_NAME}Analyzer extends BaseAnalyzer {
+  @override
+  String get ruleId => '${RULE_ID}';
+
+  // Rule-specific configuration
+  static const _validSuffixes = ['Widget', 'Page', 'Screen', 'View', 'Dialog', 'Sheet'];
+  static const _excludePatterns = ['_State', 'Mixin'];
+
+  @override
+  List<Violation> analyze({
+    required CompilationUnit unit,
+    required String filePath,
+    required Rule rule,
+    required LineInfo lineInfo,
+  }) {
+    final violations = <Violation>[];
+
+    final visitor = _${RULE_ID}Visitor(
+      filePath: filePath,
+      lineInfo: lineInfo,
+      violations: violations,
+      analyzer: this,
+    );
+
+    unit.accept(visitor);
+
+    return violations;
+  }
+}
+
+class _${RULE_ID}Visitor extends RecursiveAstVisitor<void> {
+  final String filePath;
+  final LineInfo lineInfo;
+  final List<Violation> violations;
+  final ${RULE_ID}${RULE_PASCAL_NAME}Analyzer analyzer;
+
+  _${RULE_ID}Visitor({
+    required this.filePath,
+    required this.lineInfo,
+    required this.violations,
+    required this.analyzer,
+  });
+
+  @override
+  void visitClassDeclaration(ClassDeclaration node) {
+    final className = node.name.lexeme;
+
+    // Check if class extends StatelessWidget or StatefulWidget
+    final extendsClause = node.extendsClause;
+    if (extendsClause != null) {
+      final superclass = extendsClause.superclass.name2.lexeme;
+      if (superclass == 'StatelessWidget' || superclass == 'StatefulWidget') {
+        // Check if name ends with valid suffix
+        bool hasValidSuffix = ${RULE_ID}${RULE_PASCAL_NAME}Analyzer._validSuffixes
+            .any((suffix) => className.endsWith(suffix));
+
+        // Skip excluded patterns
+        bool isExcluded = ${RULE_ID}${RULE_PASCAL_NAME}Analyzer._excludePatterns
+            .any((pattern) => className.contains(pattern));
+
+        if (!hasValidSuffix && !isExcluded) {
+          violations.add(analyzer.createViolation(
+            filePath: filePath,
+            line: analyzer.getLine(lineInfo, node.name.offset),
+            column: analyzer.getColumn(lineInfo, node.name.offset),
+            message: 'Widget class "$className" should end with Widget, Page, Screen, View, Dialog, or Sheet',
+          ));
+        }
+      }
+    }
+
+    super.visitClassDeclaration(node);
+  }
+}
+```
+
+### Step 4: Register in AnalyzerService
+
+**File:** `dart_analyzer/lib/analyzer_service.dart`
+
+```dart
+// Add import at top
+import 'rules/dart/${RULE_ID}_${RULE_NAME}.dart';
+
+// Add to _registerAnalyzers() method
+void _registerAnalyzers() {
+  // ... existing analyzers
+
+  // Dart-only rules (Dxxx)
+  _analyzers['${RULE_ID}'] = ${RULE_ID}${RULE_PASCAL_NAME}Analyzer();
+}
+```
+
+### Step 5: Update Rule Definition Markdown Files
+
+**IMPORTANT:** Rule name and description are taken from these markdown files, not from `config.json`.
+
+#### 5.1. Update `dart-en.md` (English version)
+
+**File:** `../../../rules/dart-en.md`
+
+Add new rule definition to file:
+
+```markdown
+### 📘 Rule ${RULE_ID} – ${RULE_DISPLAY_NAME}
+
+- **Objective**: ${OBJECTIVE_SHORT}
+- **Details**: ${DETAILED_DESCRIPTION}
+- **Applies to**: Flutter/Dart
+- **Tools**: `dart lint` (${TOOLS})
+- **Principles**: CODE_QUALITY
+- **Version**: 1.0
+- **Status**: activated
+- **Severity**: major
+```
+
+**Example:**
+
+```markdown
+### 📘 Rule D001 – Recommended Lint Rules Should Be Enabled
+
+- **Objective**: Ensure code quality through standard lint configurations
+- **Details**: The `analysis_options.yaml` file should include recommended lint packages (flutter_lints, very_good_analysis, or lints) and critical lint rules should not be disabled. This ensures consistent code quality standards across the project.
+- **Applies to**: Flutter/Dart
+- **Tools**: `dart lint` (flutter_lints, very_good_analysis, lints)
+- **Principles**: CODE_QUALITY
+- **Version**: 1.0
+- **Status**: activated
+- **Severity**: major
+```
+
+#### 5.2. Update `dart.md` (Vietnamese version)
+
+**File:** `../../../rules/dart.md`
+
+Add rule definition in Vietnamese:
+
+```markdown
+### 📘 Rule ${RULE_ID} – ${RULE_DISPLAY_NAME_VI}
+
+- **Mục tiêu**: ${OBJECTIVE_SHORT_VI}
+- **Chi tiết**: ${DETAILED_DESCRIPTION_VI}
+- **Áp dụng**: Flutter/Dart
+- **Công cụ**: `dart lint` (${TOOLS})
+- **Nguyên tắc**: CODE_QUALITY
+- **Phiên bản**: 1.0
+- **Trạng thái**: activated
+- **Mức độ**: major
+```
+
+#### 5.3. Create Example Files
+
+**File:** `../../../rules/examples/en/${RULE_ID}.md`
+
+```markdown
+**Good Examples**:
+\`\`\`dart
+// Your good example code here
+\`\`\`
+
+**Bad Examples**:
+\`\`\`dart
+// Your bad example code here
+\`\`\`
+```
+
+**File:** `../../../rules/examples/vi/${RULE_ID}.md`
+
+```markdown
+**Ví dụ đúng**:
+\`\`\`dart
+// Good code example
+\`\`\`
+
+**Ví dụ sai**:
+\`\`\`dart
+// Bad code example
+\`\`\`
+```
+
+### Step 6: Generate Registry from Markdown
+
+**IMPORTANT:** Registry is auto-generated from markdown files, DO NOT edit manually.
+
+```bash
+# Copy rules from main rules directory to sunlint
+node scripts/copy-rules.js
+
+# Generate registry from markdown files
+node scripts/generate-rules-registry.js
+
+# Results:
+# - config/rules/rules-registry-generated.json (auto-generated)
+# - Rule name and description will be taken from dart-en.md
+```
+
+**Notes:**
+- File `rules-registry-generated.json` is auto-generated, DO NOT edit manually
+- File `rules-summary.json` may need manual update if not generated
+- Registry will parse rule from markdown format `### 📘 Rule ${RULE_ID} – ${NAME}`
+
+**📖 Read more:** See [REGISTRY_GENERATION_FLOW.md](../REGISTRY_GENERATION_FLOW.md) for detailed understanding of the generation flow, common mistakes, and debugging tips.
+
+### Step 7: Create Test Fixtures
+
+```bash
+# Create test fixture folders
+mkdir -p "examples/rule-test-fixtures/dart-rules/${RULE_ID}_${RULE_NAME}/{clean,violations}"
+```
+
+**violations/bad_example.dart:**
+```dart
+// ❌ VIOLATION: D001 - Flutter Widget Naming
+// Widget class should end with Widget, Page, Screen, or View
+
+class MyComponent extends StatelessWidget {  // ❌ Should be MyComponentWidget
+  @override
+  Widget build(BuildContext context) {
+    return Container();
+  }
+}
+
+class UserProfile extends StatefulWidget {  // ❌ Should be UserProfilePage/Screen
+  @override
+  State<UserProfile> createState() => _UserProfileState();
+}
+```
+
+**clean/good_example.dart:**
+```dart
+// ✅ CLEAN: D001 - Flutter Widget Naming
+// Correct widget naming convention
+
+class MyComponentWidget extends StatelessWidget {  // ✅ Ends with Widget
+  @override
+  Widget build(BuildContext context) {
+    return Container();
+  }
+}
+
+class UserProfilePage extends StatefulWidget {  // ✅ Ends with Page
+  @override
+  State<UserProfilePage> createState() => _UserProfilePageState();
+}
+
+class SettingsScreen extends StatelessWidget {  // ✅ Ends with Screen
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold();
+  }
+}
+```
+
+### Step 8: Rebuild Dart Analyzer
+
+```bash
+cd dart_analyzer
+
+# Get dependencies
+dart pub get
+
+# Analyze for errors
+dart analyze lib/
+
+# Compile binary (macOS)
+dart compile exe bin/sunlint_dart_analyzer.dart -o bin/sunlint-dart-macos
+
+# Copy binary to sunlint root (important!)
+cp bin/sunlint-dart-macos ../sunlint-dart-macos
+
+# Verify binary
+ls -la ../sunlint-dart-macos
+
+# Return to sunlint root
+cd ..
+```
+
+**Note:** Binary must be copied to sunlint root directory for CLI to use.
+
+**Platform-specific binaries:**
+- macOS: `sunlint-dart-macos`
+- Linux: `sunlint-dart-linux`
+- Windows: `sunlint-dart-windows.exe`
+
+### Step 9: Test the Rule
+
+```bash
+cd /path/to/sunlint
+
+# Test on violations (should find issues)
+node cli.js --rule=${RULE_ID} \
+  --input="examples/rule-test-fixtures/dart-rules/${RULE_ID}_${RULE_NAME}/violations" \
+  --languages=dart
+
+# Test on clean code (should find no issues)
+node cli.js --rule=${RULE_ID} \
+  --input="examples/rule-test-fixtures/dart-rules/${RULE_ID}_${RULE_NAME}/clean" \
+  --languages=dart
+
+# With verbose output for debugging
+node cli.js --rule=${RULE_ID} \
+  --input="examples/rule-test-fixtures/dart-rules/${RULE_ID}_${RULE_NAME}/violations" \
+  --languages=dart \
+  --verbose
+```
+
+### Step 10: Run Rule on Real Project
+
+```bash
+# Run on a Dart/Flutter project
+node cli.js --rule=${RULE_ID} --input=/path/to/dart/project --languages=dart
+
+# Run with verbose output
+node cli.js --rule=${RULE_ID} --input=/path/to/dart/project --languages=dart --verbose
+
+# If installed globally
+sunlint --rule=${RULE_ID} --input=/path/to/dart/project --languages=dart
+```
+
+---
+
+## 5. Verification Checklist
+
+| Check | Command | Expected |
+|-------|---------|----------|
+| Config exists | `ls rules/dart/${RULE_ID}_*/config.json` | File exists |
+| Dart analyzer exists | `ls dart_analyzer/lib/rules/dart/${RULE_ID}_*.dart` | File exists |
+| Registered | `grep ${RULE_ID} dart_analyzer/lib/analyzer_service.dart` | Registration line |
+| Binary compiles | `dart analyze dart_analyzer/lib/` | No errors |
+| Test fixtures exist | `ls examples/rule-test-fixtures/dart-rules/${RULE_ID}_*` | clean/ and violations/ |
+| **Violations detected** | `node cli.js --rule=${RULE_ID} --input=...violations --languages=dart` | > 0 violations |
+| **Clean passes** | `node cli.js --rule=${RULE_ID} --input=...clean --languages=dart` | No violations |
+
+---
+
+## 6. Naming Conventions
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Rule ID | Dxxx | `D001`, `D002` |
+| Folder name | `{ID}_{snake_case}` | `D001_flutter_widget_naming` |
+| Dart file | `{ID}_{snake_case}.dart` | `D001_flutter_widget_naming.dart` |
+| Class name | `{ID}{PascalCase}Analyzer` | `D001FlutterWidgetNamingAnalyzer` |
+| Visitor class | `_{ID}Visitor` | `_D001Visitor` |
+
+---
+
+## 7. Common Patterns for Flutter/Dart Rules
+
+### Pattern 1: Check Widget Class Names
+
+```dart
+@override
+void visitClassDeclaration(ClassDeclaration node) {
+  final className = node.name.lexeme;
+  final extendsClause = node.extendsClause;
+
+  if (extendsClause != null) {
+    final superclass = extendsClause.superclass.name2.lexeme;
+    if (superclass.contains('Widget')) {
+      // Check widget naming
+    }
+  }
+  super.visitClassDeclaration(node);
+}
+```
+
+### Pattern 2: Check StreamSubscription Cancel
+
+```dart
+@override
+void visitMethodDeclaration(MethodDeclaration node) {
+  if (node.name.lexeme == 'dispose') {
+    final body = node.body?.toSource() ?? '';
+    // Check if subscriptions are cancelled
+    if (!body.contains('.cancel()')) {
+      // Add violation
+    }
+  }
+  super.visitMethodDeclaration(node);
+}
+```
+
+### Pattern 3: Check Controller Dispose
+
+```dart
+@override
+void visitFieldDeclaration(FieldDeclaration node) {
+  for (final variable in node.fields.variables) {
+    final type = node.fields.type?.toSource() ?? '';
+    if (type.contains('Controller')) {
+      // Track controller fields for dispose check
+    }
+  }
+  super.visitFieldDeclaration(node);
+}
+```
+
+### Pattern 4: Check BuildContext Usage
+
+```dart
+@override
+void visitMethodInvocation(MethodInvocation node) {
+  final methodName = node.methodName.name;
+  if (methodName == 'of') {
+    // Check for context usage after async gap
+  }
+  super.visitMethodInvocation(node);
+}
+```
+
+### Pattern 5: Check Import Statements
+
+```dart
+@override
+void visitImportDirective(ImportDirective node) {
+  final uri = node.uri.stringValue ?? '';
+  if (uri.contains('dart:mirrors')) {
+    // Flag forbidden imports
+  }
+  super.visitImportDirective(node);
+}
+```
+
+---
+
+## 8. Existing and Suggested Dart-Only Rules (Dxxx)
+
+### Existing Rules
+
+| ID | Name | Description | Status |
+|----|------|-------------|--------|
+| D001 | Recommended Lint Rules | Ensure flutter_lints/very_good_analysis enabled in analysis_options.yaml | ✅ Implemented |
+
+### Suggested Future Rules
+
+| ID | Name | Description |
+|----|------|-------------|
+| D002 | Stream Subscription Cancel | StreamSubscription must be cancelled in dispose() |
+| D003 | Dispose Controllers | TextEditingController, AnimationController must be disposed |
+| D004 | BuildContext After Async | Don't use BuildContext after async gaps |
+| D005 | Avoid Print in Flutter | Use debugPrint() instead of print() |
+| D006 | Prefer Const Constructors | Use const constructors when possible |
+| D007 | Avoid setState in Build | Don't call setState() inside build() method |
+| D008 | Import Order | Dart imports should be sorted and grouped |
+| D009 | No Relative Imports | Use package imports instead of relative imports |
+| D010 | Prefer Final Fields | Class fields should be final when possible |
+| D011 | Flutter Widget Naming | Widget classes should end with Widget/Page/Screen/View |
+
+---
+
+## 9. Error Handling
+
+### 9.1. Dart Compile Error
+
+```bash
+# Check for errors
+dart analyze dart_analyzer/lib/
+
+# Common fixes:
+# - Import missing files
+# - Fix syntax errors
+# - Add missing dependencies to pubspec.yaml
+```
+
+### 9.2. Rule Not Detected
+
+```bash
+# Verify config exists
+ls rules/dart/${RULE_ID}_*/config.json
+
+# Check registry
+grep ${RULE_ID} config/rules/enhanced-rules-registry.json
+```
+
+### 9.3. No Violations Found
+
+```bash
+# Check DartAnalyzer is running
+node cli.js --rule=${RULE_ID} --input=... --languages=dart --verbose
+
+# Check analyzer is registered
+grep ${RULE_ID} dart_analyzer/lib/analyzer_service.dart
+```
+
+### 9.4. Rule Name Mismatch
+
+**Problem:** Rule name displays incorrectly or doesn't match the definition.
+
+**Root Cause:** Rule name is taken from markdown files (`dart-en.md`), NOT from `config.json` or Dart code.
+
+**Solution:**
+1. Check rule definition in `../../../rules/dart-en.md`
+2. Ensure correct format: `### 📘 Rule ${RULE_ID} – ${NAME}`
+3. Regenerate registry:
+   ```bash
+   node scripts/copy-rules.js
+   node scripts/generate-rules-registry.js
+   ```
+4. Verify in generated file:
+   ```bash
+   grep -A 5 '"${RULE_ID}"' config/rules/rules-registry-generated.json
+   ```
+
+**IMPORTANT:**
+- Markdown files are the **source of truth** for rule name and description
+- Registry files are **auto-generated** from markdown
+- DO NOT edit registry files manually, must update markdown and regenerate
+
+---
+
+## 10. Files Created/Modified by This Skill
+
+### Files Created:
+
+| File | Purpose |
+|------|---------|
+| `rules/dart/${RULE_ID}_*/config.json` | Rule configuration |
+| `dart_analyzer/lib/rules/dart/${RULE_ID}_*.dart` | Dart analyzer implementation |
+| `examples/rule-test-fixtures/dart-rules/${RULE_ID}_*/clean/*.dart` | Clean test cases |
+| `examples/rule-test-fixtures/dart-rules/${RULE_ID}_*/violations/*.dart` | Violation test cases |
+| `../../../rules/examples/en/${RULE_ID}.md` | English examples |
+| `../../../rules/examples/vi/${RULE_ID}.md` | Vietnamese examples |
+
+### Files Modified:
+
+| File | What to Add |
+|------|-------------|
+| `dart_analyzer/lib/analyzer_service.dart` | Import rule + Register in `_registerAnalyzers()` |
+| `../../../rules/dart-en.md` | Rule definition section (English) |
+| `../../../rules/dart.md` | Rule definition section (Vietnamese) |
+
+### Files Auto-Generated:
+
+| File | Generated By |
+|------|--------------|
+| `config/rules/rules-registry-generated.json` | `scripts/generate-rules-registry.js` |
+| `origin-rules/dart-en.md` | `scripts/copy-rules.js` (copied from `../../../rules/`) |
+
+---
+
+## 11. Best Practices & Important Notes
+
+### 11.1. Rule Name Synchronization
+
+**CRITICAL:** Rule name must be consistent across 3 locations:
+
+| Location | Format | Example |
+|----------|--------|---------|
+| **Dart Code Comment** | `/// ${RULE_ID}: ${NAME}` | `/// D001: Recommended Lint Rules Should Be Enabled` |
+| **Markdown (dart-en.md)** | `### 📘 Rule ${RULE_ID} – ${NAME}` | `### 📘 Rule D001 – Recommended Lint Rules Should Be Enabled` |
+| **Registry (auto-generated)** | Generated from markdown | `"name": "Recommended Lint Rules Should Be Enabled"` |
+
+**Workflow:**
+1. Update markdown files first (`dart-en.md`, `dart.md`)
+2. Run `node scripts/copy-rules.js && node scripts/generate-rules-registry.js`
+3. Update Dart code comment to match
+4. Never edit registry JSON files manually
+
+### 11.2. Registry Generation Flow
+
+```
+../../../rules/dart-en.md
+         ↓ (copy-rules.js)
+origin-rules/dart-en.md
+         ↓ (generate-rules-registry.js)
+config/rules/rules-registry-generated.json
+```
+
+**Key Points:**
+- Markdown is the **source of truth**
+- Registry is **auto-generated**
+- `config.json` is only used for rule detection, not for display name
+
+### 11.3. Common Mistakes to Avoid
+
+| Mistake | Why It's Wrong | Correct Approach |
+|---------|----------------|------------------|
+| Edit `rules-registry-generated.json` manually | Will be overwritten | Edit markdown and regenerate |
+| Put display name in `config.json` | Not used for display | Put in markdown files |
+| Skip registry regeneration | Old name will show | Always run `generate-rules-registry.js` |
+| Mismatch Dart comment and markdown | Confusing for developers | Keep them synchronized |
+
+---
+
+## 12. Related Documentation
+
+- **[REGISTRY_GENERATION_FLOW.md](../REGISTRY_GENERATION_FLOW.md)** - ⭐ Detailed registry generation flow from markdown
+- [CREATE_DART_RULE.md](./CREATE_DART_RULE.md) - Add Dart support for existing TypeScript rule
+- [DART_RULE_EXECUTION_FLOW.md](../DART_RULE_EXECUTION_FLOW.md) - Detailed rule execution flow
+- [dart_analyzer/README.md](../../dart_analyzer/README.md) - Dart analyzer documentation
+
+---
+
+## 13. Complete Example: D001 Implementation
+
+Below is a real-world example of rule D001 implementation:
+
+### Files Created:
+
+```
+rules/dart/D001_recommended_lint_rules/
+└── config.json
+
+dart_analyzer/lib/rules/dart/
+└── D001_recommended_lint_rules.dart
+
+examples/rule-test-fixtures/dart-rules/D001_recommended_lint_rules/
+├── clean/
+│   ├── analysis_options.yaml
+│   ├── pubspec.yaml
+│   └── lib/main.dart
+└── violations/
+    ├── analysis_options.yaml
+    ├── pubspec.yaml
+    └── lib/main.dart
+```
+
+### Test Commands:
+
+```bash
+# Test violations (expect 5 warnings)
+node cli.js --rule=D001 \
+  --input=examples/rule-test-fixtures/dart-rules/D001_recommended_lint_rules/violations \
+  --languages=dart
+
+# Test clean (expect 0 warnings)
+node cli.js --rule=D001 \
+  --input=examples/rule-test-fixtures/dart-rules/D001_recommended_lint_rules/clean \
+  --languages=dart
+
+# Run on any Dart project
+node cli.js --rule=D001 --input=/path/to/dart/project --languages=dart
+```
+
+### Expected Output (violations):
+
+```
+analysis_options.yaml
+ 1:1 warning  analysis_options.yaml should include a recommended lint package...  D001
+ 13:1 warning  Critical lint rule "avoid_print" should not be disabled...  D001
+ 14:1 warning  Critical lint rule "cancel_subscriptions" should not be disabled...  D001
+ 15:1 warning  Critical lint rule "close_sinks" should not be disabled...  D001
+ 16:1 warning  Critical lint rule "avoid_empty_else" should not be disabled...  D001
+
+✖ 5 problems (0 errors, 5 warnings)
+```
+
+---
+
+## 14. Changelog
+
+### v1.1.0 (2025-01-23)
+- **BREAKING:** Added mandatory markdown update steps for rule definitions
+- Added registry generation flow documentation
+- Added Best Practices section on rule name synchronization
+- Added troubleshooting for rule name mismatch issues
+- Clarified that markdown files are source of truth for rule names
+- Updated file locations table with markdown paths
+- Added example files creation steps
+
+### v1.0.0 (2025-01-21)
+- Initial skill documentation for creating Dart-only rules (Dxxx)
+- Flat structure design - no router or JS wrapper needed
+- Separate `rules/dart/` folder for Dart-specific rules
+- Common Flutter/Dart patterns included
+- D001 (Recommended Lint Rules) implemented as reference example