@sun-asterisk/sunlint 1.3.37 → 1.3.39

package/docs/REGISTRY_GENERATION_FLOW.md

@@ -0,0 +1,486 @@
+# Registry Generation Flow - SunLint Rules
+
+> **Document này giải thích chi tiết cách SunLint generate rule registry từ markdown files**
+
+---
+
+## 🎯 Core Concept
+
+**QUAN TRỌNG:** Rule names và descriptions trong SunLint được quản lý tập trung tại **markdown files**, KHÔNG phải JSON configs hay source code.
+
+```
+Markdown Files = SOURCE OF TRUTH
+         ↓
+   Auto Generation
+         ↓
+Registry JSON Files
+```
+
+---
+
+## 📊 Luồng Generation Chi Tiết
+
+### 1. Source Files (Markdown)
+
+**Location:** `coding-quality/rules/`
+
+```
+coding-quality/rules/
+├── common-en.md          # Common rules (C001-C076)
+├── dart-en.md            # Dart-specific rules (D001-D025)
+├── security-en.md        # Security rules (S001-S060)
+├── typescript-en.md      # TypeScript rules (T001-T021)
+├── java-en.md            # Java rules (J001-J006)
+├── kotlin-mobile-en.md   # Kotlin rules (K001-K034)
+├── reactjs-en.md         # React rules (R001-R009)
+└── swift-en.md           # Swift rules (SW001-SW035)
+```
+
+**Format trong markdown:**
+
+```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...
+- **Applies to**: Flutter/Dart
+- **Tools**: `dart lint` (flutter_lints, very_good_analysis, lints)
+- **Principles**: CODE_QUALITY
+- **Version**: 1.0
+- **Status**: activated
+- **Severity**: major
+```
+
+### 2. Copy Rules Script
+
+**Script:** `coding-quality/extensions/sunlint/scripts/copy-rules.js`
+
+**Chức năng:**
+- Copy tất cả `*-en.md` files từ `coding-quality/rules/`
+- Đến `coding-quality/extensions/sunlint/origin-rules/`
+- Chỉ copy English versions (`*-en.md`)
+
+**Command:**
+```bash
+cd coding-quality/extensions/sunlint
+node scripts/copy-rules.js
+```
+
+**Output:**
+```
+📋 Copying all rules for packaging...
+Source: /path/to/coding-quality/rules
+Target: /path/to/coding-quality/extensions/sunlint/origin-rules
+✅ Copied: common-en.md
+✅ Copied: dart-en.md
+✅ Copied: security-en.md
+...
+✅ Successfully copied 8 rule files
+```
+
+**Result:**
+```
+coding-quality/extensions/sunlint/origin-rules/
+├── common-en.md          # Copied from ../../../rules/
+├── dart-en.md            # Copied from ../../../rules/
+├── security-en.md        # Copied from ../../../rules/
+└── ...
+```
+
+### 3. Generate Registry Script
+
+**Script:** `coding-quality/extensions/sunlint/scripts/generate-rules-registry.js`
+
+**Chức năng:**
+- Parse tất cả files trong `origin-rules/`
+- Extract rule information từ markdown format
+- Generate JSON registry file
+
+**Parser Logic:**
+
+```javascript
+// Tìm rule header: ### 📘 Rule D001 – Rule Name
+const ruleHeaderRegex = /###\s*📘\s*Rule\s+([A-Z]+\d+)\s*[–-]\s*(.+)/;
+
+// Parse rule properties
+- **Objective**: ${objective}
+- **Details**: ${details}
+- **Applies to**: ${appliesTo}
+- **Tools**: ${tools}
+- **Principles**: ${principles}
+- **Version**: ${version}
+- **Status**: ${status}
+- **Severity**: ${severity}
+```
+
+**Command:**
+```bash
+node scripts/generate-rules-registry.js
+```
+
+**Output:**
+```
+📋 Generating rules registry from origin-rules...
+Found 8 English rule files
+Parsed rule C001: 0 good examples, 0 bad examples, 0 configs
+Parsed rule C002: 0 good examples, 0 bad examples, 0 configs
+...
+Parsed rule D001: 0 good examples, 0 bad examples, 0 configs
+...
+✅ Generated registry with 257 rules
+📁 File: config/rules/rules-registry-generated.json (156.2 KB)
+```
+
+### 4. Generated Registry File
+
+**Output File:** `config/rules/rules-registry-generated.json`
+
+**Structure:**
+
+```json
+{
+  "rules": {
+    "D001": {
+      "name": "Recommended Lint Rules Should Be Enabled",
+      "description": "Ensure code quality through standard lint configurations",
+      "category": "Common",
+      "severity": "major",
+      "languages": ["dart"],
+      "version": "1.0",
+      "status": "activated",
+      "tags": ["Common", "readability", "code-quality"],
+      "tools": ["`dart lint` (flutter_lints, very_good_analysis, lints)"],
+      "framework": "All",
+      "principles": ["CODE_QUALITY"]
+    },
+    "D002": {
+      ...
+    }
+  }
+}
+```
+
+---
+
+## 🔄 Complete Flow Diagram
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Step 1: Markdown Files (SOURCE OF TRUTH)                    │
+│ Location: coding-quality/rules/                             │
+│                                                              │
+│ Files:                                                       │
+│   - common-en.md                                            │
+│   - dart-en.md ← EDIT HERE to change rule names            │
+│   - security-en.md                                          │
+│   - typescript-en.md                                        │
+│   - ...                                                     │
+└──────────────────────┬───────────────────────────────────────┘
+                       │
+                       ↓
+┌──────────────────────────────────────────────────────────────┐
+│ Step 2: Copy Rules Script                                    │
+│ Command: node scripts/copy-rules.js                          │
+│                                                               │
+│ Action:                                                       │
+│   - Copy *-en.md from rules/ to origin-rules/               │
+│   - Only English versions                                    │
+└──────────────────────┬────────────────────────────────────────┘
+                       │
+                       ↓
+┌──────────────────────────────────────────────────────────────┐
+│ Intermediate: origin-rules/                                  │
+│ Location: coding-quality/extensions/sunlint/origin-rules/   │
+│                                                               │
+│ Files: (Copies of source markdown files)                    │
+│   - common-en.md                                            │
+│   - dart-en.md                                              │
+│   - ...                                                     │
+└──────────────────────┬────────────────────────────────────────┘
+                       │
+                       ↓
+┌──────────────────────────────────────────────────────────────┐
+│ Step 3: Generate Registry Script                             │
+│ Command: node scripts/generate-rules-registry.js             │
+│                                                               │
+│ Action:                                                       │
+│   - Parse all *-en.md in origin-rules/                      │
+│   - Extract rule ID, name, description, etc.                │
+│   - Generate JSON structure                                 │
+└──────────────────────┬────────────────────────────────────────┘
+                       │
+                       ↓
+┌──────────────────────────────────────────────────────────────┐
+│ Step 4: Generated Registry (AUTO-GENERATED)                 │
+│ File: config/rules/rules-registry-generated.json            │
+│                                                               │
+│ Content:                                                     │
+│   {                                                          │
+│     "rules": {                                               │
+│       "D001": {                                              │
+│         "name": "Recommended Lint Rules...",                │
+│         "description": "...",                                │
+│         ...                                                  │
+│       }                                                      │
+│     }                                                        │
+│   }                                                          │
+└──────────────────────┬────────────────────────────────────────┘
+                       │
+                       ↓
+┌──────────────────────────────────────────────────────────────┐
+│ Step 5: Used by SunLint CLI & VSCode Extension              │
+│                                                               │
+│ Usage:                                                       │
+│   - UnifiedRuleRegistry loads this JSON                     │
+│   - Displays rule names to users                            │
+│   - Shows descriptions in error messages                    │
+└──────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🛠️ Practical Usage
+
+### When Creating a New Dart Rule
+
+```bash
+# 1. Create rule implementation
+vim dart_analyzer/lib/rules/dart/D026_new_rule.dart
+
+# 2. Register in analyzer service
+vim dart_analyzer/lib/analyzer_service.dart
+
+# 3. UPDATE MARKDOWN FILES (CRITICAL!)
+vim ../../../rules/dart-en.md    # Add rule definition
+vim ../../../rules/dart.md       # Add Vietnamese version
+
+# 4. Create examples
+vim ../../../rules/examples/en/D026.md
+vim ../../../rules/examples/vi/D026.md
+
+# 5. GENERATE REGISTRY (CRITICAL!)
+node scripts/copy-rules.js
+node scripts/generate-rules-registry.js
+
+# 6. 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
+cd ..
+
+# 7. Test
+node cli.js --rule=D026 --input=/path/to/project --languages=dart
+```
+
+### When Updating an Existing Rule Name
+
+```bash
+# 1. UPDATE MARKDOWN FIRST
+vim ../../../rules/dart-en.md
+# Change: ### 📘 Rule D001 – OLD NAME
+# To:     ### 📘 Rule D001 – NEW NAME
+
+vim ../../../rules/dart.md
+# Update Vietnamese version too
+
+# 2. REGENERATE REGISTRY
+node scripts/copy-rules.js
+node scripts/generate-rules-registry.js
+
+# 3. Verify the change
+grep -A 5 '"D001"' config/rules/rules-registry-generated.json
+
+# 4. Update Dart code comment (optional, for consistency)
+vim dart_analyzer/lib/rules/dart/D001_*.dart
+# Update: /// D001: NEW NAME
+
+# 5. Test to see new name
+node cli.js --rule=D001 --input=/path/to/project --languages=dart
+```
+
+---
+
+## 📋 Files Reference
+
+### Source Files (Edit These)
+
+| File | Purpose | When to Edit |
+|------|---------|--------------|
+| `../../../rules/dart-en.md` | Rule definitions (English) | Adding/updating Dart rules |
+| `../../../rules/dart.md` | Rule definitions (Vietnamese) | Adding/updating Dart rules |
+| `../../../rules/common-en.md` | Common rules definitions | Adding/updating common rules |
+| `../../../rules/security-en.md` | Security rules definitions | Adding/updating security rules |
+
+### Intermediate Files (Auto-copied)
+
+| File | Purpose | Generated By |
+|------|---------|--------------|
+| `origin-rules/dart-en.md` | Copied source | `scripts/copy-rules.js` |
+| `origin-rules/common-en.md` | Copied source | `scripts/copy-rules.js` |
+
+### Generated Files (DO NOT EDIT MANUALLY)
+
+| File | Purpose | Generated By |
+|------|---------|--------------|
+| `config/rules/rules-registry-generated.json` | Main registry | `scripts/generate-rules-registry.js` |
+
+### Other Registry Files
+
+| File | Purpose | Notes |
+|------|---------|-------|
+| `config/rules-summary.json` | Summary view | May need manual update if not generated |
+| `config/rules/enhanced-rules-registry.json` | Enhanced registry | Different format, separate system |
+
+---
+
+## ⚠️ Common Mistakes
+
+### ❌ Mistake 1: Edit Registry JSON Directly
+
+```bash
+# WRONG! Will be overwritten
+vim config/rules/rules-registry-generated.json
+# Change: "name": "Old Name"
+# To:     "name": "New Name"
+```
+
+**Why it's wrong:** Next time someone runs `generate-rules-registry.js`, your changes will be lost.
+
+**Correct approach:**
+```bash
+# RIGHT! Edit source markdown
+vim ../../../rules/dart-en.md
+# Then regenerate
+node scripts/copy-rules.js && node scripts/generate-rules-registry.js
+```
+
+### ❌ Mistake 2: Put Display Name in config.json
+
+```json
+// WRONG! Not used for display
+{
+  "id": "D001",
+  "name": "My Display Name",  // ❌ Not read by registry
+  "category": "dart"
+}
+```
+
+**Why it's wrong:** `config.json` is only used for rule detection, not for display names.
+
+**Correct approach:**
+```markdown
+<!-- RIGHT! Put in markdown -->
+### 📘 Rule D001 – My Display Name
+```
+
+### ❌ Mistake 3: Forget to Regenerate Registry
+
+```bash
+# Edit markdown
+vim ../../../rules/dart-en.md
+
+# Test immediately
+node cli.js --rule=D001 --input=...  # ❌ Still shows old name!
+```
+
+**Why it's wrong:** Registry hasn't been regenerated yet.
+
+**Correct approach:**
+```bash
+# Edit markdown
+vim ../../../rules/dart-en.md
+
+# MUST regenerate
+node scripts/copy-rules.js
+node scripts/generate-rules-registry.js
+
+# Now test
+node cli.js --rule=D001 --input=...  # ✅ Shows new name
+```
+
+---
+
+## 🔍 Debugging Registry Issues
+
+### Check if Rule Exists in Registry
+
+```bash
+# Search for rule in generated registry
+grep -A 10 '"D001"' config/rules/rules-registry-generated.json
+```
+
+Expected output:
+```json
+"D001": {
+  "name": "Recommended Lint Rules Should Be Enabled",
+  "description": "Ensure code quality through standard lint configurations",
+  ...
+}
+```
+
+### Check Markdown Format
+
+```bash
+# Check rule definition format in markdown
+grep -A 10 "### 📘 Rule D001" ../../../rules/dart-en.md
+```
+
+Expected format:
+```markdown
+### 📘 Rule D001 – Recommended Lint Rules Should Be Enabled
+
+- **Objective**: ...
+- **Details**: ...
+```
+
+### Verify Copy Step
+
+```bash
+# Check if markdown was copied to origin-rules
+ls -la origin-rules/dart-en.md
+
+# Compare with source
+diff ../../../rules/dart-en.md origin-rules/dart-en.md
+```
+
+Should show no differences (or only whitespace/timestamps).
+
+### Test Registry Parser
+
+```bash
+# Run generator with verbose output
+node scripts/generate-rules-registry.js 2>&1 | grep D001
+```
+
+Expected:
+```
+Parsed rule D001: 0 good examples, 0 bad examples, 0 configs
+```
+
+---
+
+## 📚 Related Documentation
+
+- [CREATE_NEW_DART_RULE.md](./skills/CREATE_NEW_DART_RULE.md) - How to create new Dart rules
+- [PROJECT_STRUCTURE.md](./PROJECT_STRUCTURE.md) - Overall project structure
+- [rules/parser/rule-parser-simple.js](../rules/parser/rule-parser-simple.js) - Parser implementation
+
+---
+
+## 🎓 Key Takeaways
+
+1. **Markdown files** are the single source of truth for rule names and descriptions
+2. **Always regenerate** registry after updating markdown files
+3. **Never edit** `rules-registry-generated.json` manually
+4. **Copy → Generate** is a two-step process that must be done together
+5. **Verify** changes in generated JSON before testing
+
+---
+
+## 📝 Version History
+
+### v1.0.0 (2025-01-23)
+- Initial documentation of registry generation flow
+- Added complete flow diagram
+- Added common mistakes and debugging sections
+- Added practical usage examples