@sun-asterisk/sunlint 1.0.7 → 1.1.4

package/docs/DEBUG.md

@@ -0,0 +1,86 @@
+# 🐛 Debugging Sunlint
+
+## Quick Start
+
+### Debug Configurations Available
+
+1. **Debug Sunlint CLI** - Debug the main CLI with quality rules
+2. **Debug Sunlint - Single Rule** - Debug a specific rule (C006)
+3. **Debug Sunlint - Multiple Rules** - Debug multiple rules with JSON output
+4. **Debug Sunlint - Custom Input** - Debug with custom input path and format
+5. **Debug Rule Analyzer - C006** - Debug the function naming analyzer
+6. **Debug Rule Analyzer - C019** - Debug the log level analyzer
+7. **Debug Rule Analyzer - C029** - Debug the catch block analyzer
+
+### How to Debug
+
+1. **Open VS Code** in the sunlint folder
+2. **Press F5** or go to `Run and Debug` panel
+3. **Select a configuration** from the dropdown
+4. **Click Start Debugging** (green play button)
+
+### Tasks Available
+
+- **Sunlint: Run Quality Check** - Run quality analysis (Ctrl+Shift+P → Tasks: Run Task)
+- **Sunlint: Run Single Rule** - Run a specific rule 
+- **Sunlint: Run All Rules** - Run all rules with JSON output
+- **Sunlint: Demo Script** - Run the demo script
+- **Sunlint: Install Dependencies** - Install npm dependencies
+- **Sunlint: Validate Registry** - Validate the rules registry
+
+### Breakpoints
+
+Set breakpoints in:
+- **cli.js** - Main CLI logic
+- **core/multi-rule-runner.js** - Rule execution
+- **core/config-manager.js** - Configuration loading
+- **core/report-generator.js** - Report generation
+- **rules/*/analyzer.js** - Individual rule analyzers
+
+### Debug Environment
+
+- **NODE_ENV** is set to `development`
+- **Console** output goes to integrated terminal
+- **Skip Files** configured to ignore Node.js internals
+- **Problem Matcher** configured to parse sunlint output
+
+### Configuration Files
+
+- **launch.json** - Debug configurations
+- **tasks.json** - Build and test tasks
+- **settings.json** - VS Code workspace settings
+- **extensions.json** - Recommended extensions
+- **sunlint-schema.json** - JSON schema for .sunlint.json files
+
+### Tips
+
+1. **Use breakpoints** in analyzer files to debug rule logic
+2. **Check Variables panel** to inspect rule results
+3. **Use Debug Console** to test expressions
+4. **Watch expressions** for complex debugging
+5. **Step through code** to understand execution flow
+
+### Common Debug Scenarios
+
+#### Debug Rule Not Working
+1. Set breakpoint in rule analyzer
+2. Use "Debug Rule Analyzer - C006" configuration
+3. Check if rule is properly detecting violations
+
+#### Debug CLI Arguments
+1. Set breakpoint in cli.js
+2. Use "Debug Sunlint CLI" configuration  
+3. Check if arguments are parsed correctly
+
+#### Debug Report Generation
+1. Set breakpoint in report-generator.js
+2. Use any CLI debug configuration
+3. Check if violations are formatted correctly
+
+### JSON Schema Support
+
+The workspace includes JSON schema for `.sunlint.json` files, providing:
+- **IntelliSense** for configuration options
+- **Validation** of configuration values
+- **Hover documentation** for properties
+- **Auto-completion** for rule IDs and values

package/docs/DEPENDENCIES.md

@@ -0,0 +1,90 @@
+# Installing SunLint Dependencies
+
+SunLint is designed to work immediately after installation with built-in JavaScript/TypeScript analysis capabilities. Additional dependencies are only needed for enhanced features.
+
+## Core Installation
+
+```bash
+npm install @sun-asterisk/sunlint --save-dev
+```
+
+**✅ What you get immediately:**
+- High-accuracy JavaScript analysis (AST-based)
+- Basic TypeScript analysis (Babel parser)
+- All 97+ quality and security rules
+- Heuristic analysis for all supported languages
+
+## Enhanced Features
+
+### For ESLint Integration
+
+If you want to combine SunLint with ESLint rules and ecosystem:
+
+```bash
+npm install eslint --save-dev
+```
+
+### For Advanced TypeScript Analysis
+
+For enhanced TypeScript parsing and ESLint TypeScript rules:
+
+```bash
+npm install @typescript-eslint/eslint-plugin @typescript-eslint/parser --save-dev
+```
+
+### For TypeScript Projects (Complete Setup)
+
+For full TypeScript development support:
+
+```bash
+npm install eslint typescript @typescript-eslint/eslint-plugin @typescript-eslint/parser --save-dev
+```
+
+## Installation Examples
+
+### Minimal Setup (JavaScript projects)
+```bash
+npm install @sun-asterisk/sunlint --save-dev
+npx sunlint --all --input=src  # ✅ Works immediately
+```
+
+### TypeScript Projects
+```bash
+npm install @sun-asterisk/sunlint eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin typescript --save-dev
+npx sunlint --all --input=src  # ✅ Full TypeScript support
+```
+
+### ESLint Integration
+```bash
+npm install @sun-asterisk/sunlint eslint --save-dev
+npx sunlint --all --eslint-integration --input=src  # ✅ Combined analysis
+```
+
+## What happens without optional dependencies?
+
+- **Without ESLint**: SunLint uses heuristic engine only (still very capable)
+- **Without TypeScript parsers**: Falls back to Babel parser (good coverage)
+- **Without TypeScript compiler**: Basic type checking only
+
+**SunLint always provides analysis results** - dependencies only enhance capabilities.
+
+## Built-in vs Optional Parsers
+
+### ✅ Built-in (Always Available)
+- **@babel/parser**: JavaScript + basic TypeScript support
+- **espree**: ECMAScript parsing for compatibility
+
+### 🔄 Optional (Install as needed)  
+- **@typescript-eslint/parser**: Advanced TypeScript features
+- **@typescript-eslint/eslint-plugin**: TypeScript-specific rules
+- **eslint**: ESLint engine integration
+- **typescript**: TypeScript compiler integration
+
+## Dependency Check
+
+Run any SunLint command to see recommendations for your project:
+
+```bash
+npx sunlint --help
+# Automatically detects project type and suggests relevant dependencies
+```

package/docs/DEPLOYMENT-STRATEGIES.md

@@ -0,0 +1,270 @@
+# SunLint Deployment Strategies
+
+This document outlines different deployment strategies for SunLint, demonstrating the modular approach that allows selective inclusion/exclusion of features.
+
+## Overview
+
+SunLint supports flexible deployment strategies through its modular architecture:
+
+- **Core Features**: Always included (heuristic regex, ESLint integration)
+- **AST Enhancement**: Optional Tree-sitter modules for improved accuracy
+- **Language-Specific**: Can include/exclude language-specific parsers
+- **AI Features**: Optional OpenAI integration
+
+## Deployment Strategies
+
+### 1. Full Distribution (Development/Enterprise)
+
+**Target**: Development teams, enterprise installations
+**Size**: Large (~50MB+ with all AST parsers)
+**Accuracy**: Highest
+
+```bash
+# Include everything
+npm install sunlint
+
+# Available engines: eslint, heuristic (with AST), openai
+sunlint --rule=C010 --engine=heuristic src/
+# Uses AST when available, falls back to regex
+```
+
+**Files Included**:
+```
+sunlint/
+├── engines/
+│   ├── eslint-engine.js        ✅ ESLint integration
+│   ├── heuristic-engine.js     ✅ Enhanced with AST
+│   └── openai-engine.js        ✅ AI-powered analysis
+├── core/ast-modules/           ✅ Full AST support
+│   ├── parsers/
+│   │   ├── javascript-parser.js   ✅ JS AST
+│   │   ├── typescript-parser.js   ✅ TS AST  
+│   │   ├── dart-parser.js         ✅ Dart AST
+│   │   ├── java-parser.js         ✅ Java AST
+│   │   └── ...                    ✅ All languages
+│   └── package.json               ✅ Tree-sitter deps
+└── ...
+```
+
+### 2. TypeScript-Only Distribution
+
+**Target**: TypeScript-only projects, Next.js, React
+**Size**: Medium (~15MB)
+**Accuracy**: High for TS/JS, regex for others
+
+```bash
+# Build script for TypeScript distribution
+npm run build:typescript
+
+# Available engines: eslint, heuristic (TS/JS AST only)
+sunlint --rule=C010 --engine=heuristic src/
+# Uses AST for .ts/.js files, regex for others
+```
+
+**Build Process**:
+```bash
+#!/bin/bash
+# build-typescript.sh
+
+# Copy base files
+cp -r engines/ dist/
+cp -r rules/ dist/
+cp -r core/ dist/
+
+# Keep only TypeScript/JavaScript AST parsers
+mkdir -p dist/core/ast-modules/parsers/
+cp core/ast-modules/index.js dist/core/ast-modules/
+cp core/ast-modules/base-parser.js dist/core/ast-modules/
+cp core/ast-modules/parsers/javascript-parser.js dist/core/ast-modules/parsers/
+cp core/ast-modules/parsers/typescript-parser.js dist/core/ast-modules/parsers/
+
+# Update package.json to include only JS/TS Tree-sitter deps
+cat > dist/core/ast-modules/package.json << 'EOF'
+{
+  "name": "@sunlint/ast-typescript",
+  "dependencies": {
+    "tree-sitter": "^0.20.0",
+    "tree-sitter-javascript": "^0.20.0", 
+    "tree-sitter-typescript": "^0.20.0"
+  }
+}
+EOF
+
+# Remove OpenAI engine for smaller bundle
+rm dist/engines/openai-engine.js
+
+npm pack dist/
+```
+
+### 3. Minimal Distribution (Regex-Only)
+
+**Target**: CI/CD, embedded systems, minimal installs
+**Size**: Small (~2MB)
+**Accuracy**: Basic regex patterns only
+
+```bash
+# Build script for minimal distribution
+npm run build:minimal
+
+# Available engines: eslint, heuristic (regex-only)
+sunlint --rule=C010 --engine=heuristic src/
+# Uses only regex patterns, no AST enhancement
+```
+
+**Build Process**:
+```bash
+#!/bin/bash
+# build-minimal.sh
+
+# Copy only essential files
+cp -r engines/ dist/
+cp -r rules/ dist/
+cp -r core/ dist/
+
+# Remove entire AST modules directory
+rm -rf dist/core/ast-modules/
+
+# Remove OpenAI engine
+rm dist/engines/openai-engine.js
+
+# Update heuristic engine to not reference AST modules
+sed -i 's/const ASTModuleRegistry = require.*//g' dist/engines/heuristic-engine.js
+sed -i 's/this.astRegistry = ASTModuleRegistry;//g' dist/engines/heuristic-engine.js
+
+npm pack dist/
+```
+
+### 4. Language-Specific Distributions
+
+**Example: Java-Only Distribution**
+
+```bash
+#!/bin/bash
+# build-java.sh
+
+# Base files
+cp -r engines/ dist/
+cp -r rules/ dist/
+cp -r core/ dist/
+
+# Keep only Java AST parser
+mkdir -p dist/core/ast-modules/parsers/
+cp core/ast-modules/index.js dist/core/ast-modules/
+cp core/ast-modules/base-parser.js dist/core/ast-modules/
+cp core/ast-modules/parsers/java-parser.js dist/core/ast-modules/parsers/
+
+# Java-specific package.json
+cat > dist/core/ast-modules/package.json << 'EOF'
+{
+  "name": "@sunlint/ast-java",
+  "dependencies": {
+    "tree-sitter": "^0.20.0",
+    "tree-sitter-java": "^0.20.0"
+  }
+}
+EOF
+
+# Remove ESLint engine (Java doesn't need it)
+rm dist/engines/eslint-engine.js
+
+# Update engine registry
+cat > dist/config/engines/engines.json << 'EOF'
+{
+  "engines": {
+    "heuristic": {
+      "enabled": true,
+      "path": "./engines/heuristic-engine.js",
+      "version": "2.0",
+      "supportedLanguages": ["java"],
+      "priority": 1,
+      "description": "Enhanced Java analyzer with AST support"
+    }
+  },
+  "defaultEngines": ["heuristic"],
+  "fallbackEngine": "heuristic"
+}
+EOF
+
+npm pack dist/
+```
+
+## Runtime Behavior
+
+### With AST Support Available
+```bash
+$ sunlint --rule=C010 --engine=heuristic --debug src/
+🌳 [AST-Enhanced] Analyzing C010 for typescript with AST support  
+🌳 [AST-Enhanced] Found 12 violations via AST, 3 via regex
+✅ heuristic: 15 violations found
+```
+
+### AST Support Not Available (Fallback)
+```bash
+$ sunlint --rule=C010 --engine=heuristic --debug src/
+⚠️ Tree-sitter TypeScript parser not available, falling back to regex
+✅ heuristic: 8 violations found
+```
+
+### Minimal Installation
+```bash
+$ sunlint --rule=C010 --engine=heuristic --debug src/
+# No AST warnings - AST modules not included
+✅ heuristic: 8 violations found
+```
+
+## Package.json Configurations
+
+### Full Distribution
+```json
+{
+  "name": "sunlint",
+  "dependencies": {
+    "minimatch": "^9.0.0",
+    "eslint": "^8.0.0"
+  },
+  "optionalDependencies": {
+    "tree-sitter": "^0.20.0",
+    "tree-sitter-javascript": "^0.20.0",
+    "tree-sitter-typescript": "^0.20.0",
+    "tree-sitter-dart": "^0.1.0",
+    "tree-sitter-java": "^0.20.0",
+    "tree-sitter-kotlin": "^0.3.0",
+    "tree-sitter-swift": "^0.4.0",
+    "tree-sitter-python": "^0.20.0",
+    "tree-sitter-go": "^0.20.0",
+    "tree-sitter-rust": "^0.20.0"
+  }
+}
+```
+
+### TypeScript-Only Distribution
+```json
+{
+  "name": "@sunlint/typescript",
+  "dependencies": {
+    "minimatch": "^9.0.0",
+    "eslint": "^8.0.0",
+    "tree-sitter": "^0.20.0",
+    "tree-sitter-javascript": "^0.20.0",
+    "tree-sitter-typescript": "^0.20.0"
+  }
+}
+```
+
+### Minimal Distribution
+```json
+{
+  "name": "@sunlint/minimal",
+  "dependencies": {
+    "minimatch": "^9.0.0"
+  }
+}
+```
+
+## Benefits
+
+1. **Flexibility**: Choose the right distribution for your needs
+2. **Performance**: Smaller bundles load faster, fewer dependencies to install
+3. **Compatibility**: Minimal distribution works everywhere, enhanced versions provide better accuracy
+4. **Gradual Adoption**: Start with minimal, upgrade to AST-enhanced when needed
+5. **Deployment Options**: Different distributions for different environments (CI vs development)

package/docs/DISTRIBUTION.md

@@ -0,0 +1,153 @@
+# 🚀 SunLint Distribution & Installation Guide
+
+## 🎯 **Problem:** 
+- Cần `cd extensions/sunlint` mỗi lần chạy
+- Muốn cài đặt dễ dàng nhưng giữ tính bảo mật (private)
+- Sử dụng từ bất kỳ directory nào
+
+## ✅ **Solutions Ranking:**
+
+### **🥇 Option 1: NPM Private Package (RECOMMENDED)**
+
+#### **Setup (Company Admin - một lần):**
+```bash
+# 1. Setup package.json for global install
+cd extensions/sunlint
+npm pack  # Tạo @sun-sunlint-1.0.0.tgz
+
+# 2. Store trong internal file server hoặc private npm registry
+# Hoặc upload lên GitHub Packages (private)
+```
+
+#### **Installation (Dev - một lần):**
+```bash
+# Cách 1: Từ file
+npm install -g /path/to/@sun-sunlint-1.0.0.tgz
+
+# Cách 2: Từ private GitHub (yêu cầu GitHub token)
+npm install -g git+https://github.com/your-company/sunlint.git
+
+# Cách 3: Từ GitHub Packages (private npm registry)
+npm login --registry=https://npm.pkg.github.com
+npm install -g @your-company/sunlint --registry=https://npm.pkg.github.com
+```
+
+#### **Usage (Dev - hàng ngày):**
+```bash
+# Từ bất kỳ directory nào
+sunlint --typescript --input src --all
+sunlint --typescript --input src --rule C006
+sunlint --typescript --input src --quality --format json
+```
+
+---
+
+### **🥈 Option 2: Shell Script/Alias (SIMPLE)**
+
+#### **Setup (Dev - một lần):**
+```bash
+# Tạo global command
+sudo cat > /usr/local/bin/sunlint << 'EOF'
+#!/bin/bash
+SUNLINT_DIR="/Users/bach.ngoc.hoai/Docs/ee/coding-quality/extensions/sunlint"
+cd "$SUNLINT_DIR" && node cli.js "$@"
+EOF
+
+sudo chmod +x /usr/local/bin/sunlint
+```
+
+#### **Usage (Dev - hàng ngày):**
+```bash
+# Từ bất kỳ directory nào
+sunlint --typescript --input src --all
+```
+
+---
+
+### **🥉 Option 3: Project-Level NPM Scripts**
+
+#### **Setup (Per Project):**
+```json
+// package.json của mỗi project
+{
+  "scripts": {
+    "lint": "node /path/to/sunlint/cli.js --typescript --input src --all",
+    "lint:ci": "node /path/to/sunlint/cli.js --typescript --input src --all --format json",
+    "lint:single": "node /path/to/sunlint/cli.js --typescript --input",
+    "lint:quality": "node /path/to/sunlint/cli.js --typescript --input src --quality"
+  }
+}
+```
+
+#### **Usage:**
+```bash
+npm run lint
+npm run lint:ci
+npm run lint:single -- src/specific-file.ts
+```
+
+---
+
+## 🏢 **Enterprise Recommendations:**
+
+### **For CI/CD (Production):**
+```yaml
+# GitHub Actions
+- name: Install SunLint
+  run: npm install -g /shared/tools/@sun-sunlint-1.0.0.tgz
+  
+- name: Run Code Quality Check
+  run: sunlint --typescript --input src --all --format json
+```
+
+### **For Development (Local):**
+```bash
+# One-time setup script cho dev team
+#!/bin/bash
+echo "Installing SunLint..."
+npm install -g /shared/tools/@sun-sunlint-1.0.0.tgz
+echo "SunLint installed! Usage: sunlint --help"
+```
+
+### **For VS Code Integration (Future):**
+```json
+// .vscode/settings.json
+{
+  "sunlint.executablePath": "sunlint",
+  "sunlint.autoRun": "onSave",
+  "sunlint.format": "eslint"
+}
+```
+
+---
+
+## 🎯 **Immediate Action Plan:**
+
+### **Phase 1: Quick Fix (This Week)**
+Implement **Option 2 (Shell Script)**:
+1. Tạo shell script cho dev team
+2. Add vào onboarding documentation
+3. Test trên CI environment
+
+### **Phase 2: Professional (Next Sprint)**  
+Implement **Option 1 (NPM Package)**:
+1. Setup private npm registry hoặc GitHub Packages
+2. Create installation documentation
+3. Migrate existing projects
+
+### **Phase 3: IDE Integration (Future)**
+1. VS Code extension
+2. IntelliJ plugin  
+3. Auto-formatting on save
+
+---
+
+## ✅ **Benefits Matrix:**
+
+| Solution | Setup Effort | Usage Simplicity | CI/CD Ready | Maintenance |
+|----------|--------------|------------------|-------------|-------------|
+| NPM Package | High | Excellent | Excellent | Low |
+| Shell Script | Low | Good | Good | Medium |
+| NPM Scripts | Medium | Good | Excellent | High |
+
+**Recommendation: Start with Shell Script (quick), then migrate to NPM Package (professional).**