# 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