@sun-asterisk/sunlint 1.3.36 → 1.3.38

package/docs/REGISTRY_GENERATION_DIAGRAM.md

@@ -0,0 +1,289 @@
+# Registry Generation - Visual Diagram
+
+> Quick visual reference cho registry generation flow
+
+---
+
+## 🔄 High-Level Overview
+
+```
+    EDIT HERE                AUTO-COPY              AUTO-GENERATE           USED HERE
+        ↓                        ↓                        ↓                     ↓
+┌──────────────┐        ┌──────────────┐        ┌──────────────┐        ┌──────────────┐
+│   Markdown   │   →    │ origin-rules │   →    │   Registry   │   →    │   SunLint    │
+│    Files     │        │   (copies)   │        │     JSON     │        │   CLI/VSCode │
+└──────────────┘        └──────────────┘        └──────────────┘        └──────────────┘
+  dart-en.md           dart-en.md (copy)    rules-registry-    Display rule names
+  common-en.md         common-en.md          generated.json    Show descriptions
+                                                                Run analysis
+```
+
+---
+
+## 📂 Directory Structure
+
+```
+engineer-excellence/
+│
+├── coding-quality/
+│   │
+│   ├── rules/                                    ← 📝 EDIT HERE (Step 1)
+│   │   ├── dart-en.md                           ← Source of Truth
+│   │   ├── dart.md                              ← Vietnamese version
+│   │   ├── common-en.md
+│   │   ├── security-en.md
+│   │   ├── examples/
+│   │   │   ├── en/D001.md                       ← Create examples
+│   │   │   └── vi/D001.md
+│   │   └── ...
+│   │
+│   └── extensions/sunlint/
+│       │
+│       ├── origin-rules/                        ← 📋 AUTO-COPIED (Step 2)
+│       │   ├── dart-en.md                       ← Copy from ../../../rules/
+│       │   ├── common-en.md
+│       │   └── ...
+│       │
+│       ├── config/
+│       │   └── rules/
+│       │       └── rules-registry-generated.json ← 🤖 AUTO-GENERATED (Step 3)
+│       │
+│       └── scripts/
+│           ├── copy-rules.js                    ← Run this first
+│           └── generate-rules-registry.js       ← Then run this
+```
+
+---
+
+## 🔄 Step-by-Step Flow
+
+### Step 1: Edit Markdown (SOURCE OF TRUTH)
+
+```
+📝 Edit: coding-quality/rules/dart-en.md
+
+┌─────────────────────────────────────────────────────────────┐
+│ ### 📘 Rule D001 – Recommended Lint Rules Should Be Enabled │
+│                                                               │
+│ - **Objective**: Ensure code quality...                     │
+│ - **Details**: The `analysis_options.yaml`...               │
+│ - **Applies to**: Flutter/Dart                              │
+│ - **Tools**: `dart lint` (flutter_lints...)                 │
+│ - **Principles**: CODE_QUALITY                              │
+│ - **Version**: 1.0                                          │
+│ - **Status**: activated                                     │
+│ - **Severity**: major                                       │
+└─────────────────────────────────────────────────────────────┘
+                           ↓
+                    This is what users
+                    will see in CLI
+```
+
+### Step 2: Copy Rules Script
+
+```bash
+$ cd coding-quality/extensions/sunlint
+$ node scripts/copy-rules.js
+```
+
+```
+📋 Copy Process:
+
+   Source                           Destination
+      ↓                                  ↓
+../../../rules/                  origin-rules/
+   ├── dart-en.md        →          ├── dart-en.md
+   ├── common-en.md      →          ├── common-en.md
+   ├── security-en.md    →          ├── security-en.md
+   └── ...               →          └── ...
+
+✅ Successfully copied 8 rule files
+```
+
+### Step 3: Generate Registry Script
+
+```bash
+$ node scripts/generate-rules-registry.js
+```
+
+```
+🤖 Generation Process:
+
+   origin-rules/                Parser Logic              config/rules/
+      ↓                              ↓                         ↓
+   dart-en.md          →      Extract:              rules-registry-generated.json
+   common-en.md        →      - Rule ID (D001)             {
+   security-en.md      →      - Name                        "rules": {
+   ...                 →      - Description                   "D001": {
+                              - Tools                            "name": "Recommended...",
+                              - Severity                         "description": "...",
+                              - etc.                             "severity": "major",
+                                                                 ...
+                                                               }
+                                                             }
+                                                           }
+
+✅ Generated registry with 257 rules
+```
+
+### Step 4: Used by SunLint
+
+```
+   config/rules/                UnifiedRuleRegistry           CLI Output
+         ↓                              ↓                         ↓
+rules-registry-                 Loads registry            $ sunlint --rule=D001
+generated.json          →       Finds D001 entry    →
+   {                            Reads:                    D001: Recommended Lint
+     "D001": {                  - name                    Rules Should Be Enabled
+       "name": "...",           - description             ─────────────────────
+       "description": "..."     - severity                analysis_options.yaml
+     }                                                    1:1 warning ...
+   }
+```
+
+---
+
+## 🔁 Complete Cycle with Example
+
+### Scenario: Rename Rule D001
+
+```
+┌─ STEP 1: Edit Markdown ────────────────────────────────────┐
+│                                                              │
+│ $ vim ../../../rules/dart-en.md                             │
+│                                                              │
+│ BEFORE:                                                      │
+│ ### 📘 Rule D001 – Keep parameter names consistent          │
+│                                                              │
+│ AFTER:                                                       │
+│ ### 📘 Rule D001 – Recommended Lint Rules Should Be Enabled │
+│                                                              │
+└──────────────────────────────────────────────────────────────┘
+                           ↓
+┌─ STEP 2: Copy Rules ───────────────────────────────────────┐
+│                                                              │
+│ $ node scripts/copy-rules.js                                │
+│                                                              │
+│ Output:                                                      │
+│ ✅ Copied: dart-en.md                                        │
+│ ✅ Successfully copied 8 rule files                          │
+│                                                              │
+└──────────────────────────────────────────────────────────────┘
+                           ↓
+┌─ STEP 3: Generate Registry ────────────────────────────────┐
+│                                                              │
+│ $ node scripts/generate-rules-registry.js                   │
+│                                                              │
+│ Output:                                                      │
+│ Parsed rule D001: 0 good examples, 0 bad examples          │
+│ ✅ Generated registry with 257 rules                         │
+│                                                              │
+└──────────────────────────────────────────────────────────────┘
+                           ↓
+┌─ STEP 4: Verify ───────────────────────────────────────────┐
+│                                                              │
+│ $ grep -A 3 '"D001"' config/rules/rules-registry-          │
+│   generated.json                                            │
+│                                                              │
+│ Output:                                                      │
+│ "D001": {                                                   │
+│   "name": "Recommended Lint Rules Should Be Enabled",      │
+│   "description": "Ensure code quality...",                 │
+│   ...                                                       │
+│ }                                                           │
+│                                                              │
+└──────────────────────────────────────────────────────────────┘
+                           ↓
+┌─ STEP 5: Test ─────────────────────────────────────────────┐
+│                                                              │
+│ $ node cli.js --rule=D001 --input=./test --languages=dart  │
+│                                                              │
+│ Output shows NEW NAME:                                      │
+│ D001: Recommended Lint Rules Should Be Enabled             │
+│ ─────────────────────────────────────────────────           │
+│ analysis_options.yaml                                       │
+│ 1:1 warning ...                                             │
+│                                                              │
+└──────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## ❌ Wrong Way vs ✅ Right Way
+
+### ❌ WRONG: Edit JSON Directly
+
+```
+┌─ WRONG APPROACH ──────────────────────────────────────────┐
+│                                                             │
+│ $ vim config/rules/rules-registry-generated.json          │
+│                                                             │
+│ Change:                                                     │
+│ "name": "Old Name"                                         │
+│ To:                                                         │
+│ "name": "New Name"                                         │
+│                                                             │
+│ ❌ Problem: Will be overwritten on next generation!        │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### ✅ RIGHT: Edit Markdown → Regenerate
+
+```
+┌─ CORRECT APPROACH ────────────────────────────────────────┐
+│                                                             │
+│ STEP 1: Edit source                                        │
+│ $ vim ../../../rules/dart-en.md                            │
+│ Change: ### 📘 Rule D001 – Old Name                        │
+│ To:     ### 📘 Rule D001 – New Name                        │
+│                                                             │
+│ STEP 2 & 3: Regenerate                                    │
+│ $ node scripts/copy-rules.js                               │
+│ $ node scripts/generate-rules-registry.js                  │
+│                                                             │
+│ ✅ Result: Changes persist, properly tracked in git        │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🎯 Quick Reference Card
+
+```
+╔═══════════════════════════════════════════════════════════╗
+║               REGISTRY GENERATION CHEATSHEET              ║
+╠═══════════════════════════════════════════════════════════╣
+║                                                           ║
+║  📝 To change rule name:                                  ║
+║     1. Edit: ../../../rules/dart-en.md                   ║
+║     2. Run:  node scripts/copy-rules.js                  ║
+║     3. Run:  node scripts/generate-rules-registry.js     ║
+║                                                           ║
+║  🔍 To verify changes:                                    ║
+║     grep '"D001"' config/rules/rules-registry-           ║
+║     generated.json                                        ║
+║                                                           ║
+║  ✅ Files you SHOULD edit:                                ║
+║     - coding-quality/rules/dart-en.md                    ║
+║     - coding-quality/rules/dart.md                       ║
+║     - coding-quality/rules/examples/en/D001.md           ║
+║                                                           ║
+║  ❌ Files you should NEVER edit:                          ║
+║     - origin-rules/*.md (auto-copied)                    ║
+║     - config/rules/rules-registry-generated.json         ║
+║                                                           ║
+║  📖 Read more:                                            ║
+║     docs/REGISTRY_GENERATION_FLOW.md                     ║
+║                                                           ║
+╚═══════════════════════════════════════════════════════════╝
+```
+
+---
+
+## 🔗 Related Documents
+
+- [REGISTRY_GENERATION_FLOW.md](./REGISTRY_GENERATION_FLOW.md) - Detailed explanation
+- [CREATE_NEW_DART_RULE.md](./skills/CREATE_NEW_DART_RULE.md) - How to create rules
+- [PROJECT_STRUCTURE.md](./PROJECT_STRUCTURE.md) - Overall structure