@sun-asterisk/sunlint 1.2.2 → 1.3.1

package/docs/ESLINT-INTEGRATION-STRATEGY.md

@@ -1,392 +0,0 @@
-# 🎯 SunLint vs ESLint Integration Strategy Analysis
-
-## 📊 **Current Situation Assessment**
-
-### **Team Assets:**
-- ✅ **29+ mature ESLint custom rules** đã được team phát triển
-- ✅ **Production-ready** codebase với nhiều contributors  
-- ✅ **Comprehensive coverage** for TypeScript
-- ✅ **Established workflow** với ESLint integration
-
-### **SunLint Unique Value:**
-- ✅ **Multi-language support** (TypeScript, Dart, Kotlin)
-- ✅ **AI-powered analysis** capabilities
-- ✅ **Specialized rules** (C019, C029, C031) không có trong ESLint
-- ✅ **CI/CD optimization** features
-
-### **Overlap Analysis:**
-| Rule | ESLint Custom | SunLint | Status |
-|------|---------------|---------|--------|
-| **C003** | ✅ Mature | ❌ Không có | ESLint wins |
-| **C006** | ✅ Mature | ✅ Basic | ESLint better |
-| **C019** | ❌ Không có | ✅ Specialized | SunLint unique |
-| **C029** | ✅ c029, c035 | ✅ Specialized | Both have |
-| **C031** | ❌ Không có | ✅ Specialized | SunLint unique |
-
-## 🎯 **SOLUTION ANALYSIS**
-
-### **Solution 1: Makefile Integration**
-```bash
-# Makefile approach
-.PHONY: lint
-lint: lint-eslint lint-sunlint
-
-lint-eslint:
-	cd coding-quality/config/typescript && ./run.sh
-
-lint-sunlint:  
-	cd coding-quality/extensions/sunlint && node cli.js --all --input=src
-
-lint-report:
-	$(MAKE) lint-eslint --json > eslint-report.json
-	$(MAKE) lint-sunlint --format=json > sunlint-report.json
-	node merge-reports.js eslint-report.json sunlint-report.json
-```
-
-**✅ Pros:**
-- ✅ **Zero migration cost** - giữ nguyên existing work
-- ✅ **Fast implementation** - 1-2 days setup
-- ✅ **Parallel execution** - có thể chạy concurrent
-- ✅ **Tool independence** - mỗi tool độc lập
-- ✅ **Team harmony** - không ảnh hưởng existing work
-
-**❌ Cons:**
-- ❌ **Fragmented results** - cần merge reports
-- ❌ **Duplicated overhead** - chạy 2 tools
-- ❌ **Configuration drift** - 2 sets of configs
-- ❌ **Learning curve** - team cần biết cả 2 tools
-
-**🎯 Score: 7/10** - Good short-term solution
-
----
-
-### **Solution 2: Keep Separate Tools**
-```bash
-# Current approach - no changes
-npm run lint:eslint
-npm run lint:sunlint  
-```
-
-**✅ Pros:**
-- ✅ **No migration cost**
-- ✅ **Maximum flexibility**
-- ✅ **Tool specialization**
-- ✅ **Zero risk**
-
-**❌ Cons:**
-- ❌ **Manual coordination**
-- ❌ **Inconsistent adoption**
-- ❌ **Results fragmentation**
-- ❌ **CI/CD complexity**
-
-**🎯 Score: 5/10** - Status quo, but not scalable
-
----
-
-### **Solution 3A: ESLint Plugin for SunLint**
-```bash
-# Embed ESLint rules into SunLint
-node cli.js --all --include-eslint --input=src
-```
-
-**✅ Pros:**
-- ✅ **Unified command** - single entry point
-- ✅ **Leverage existing rules** - 29+ rules preserved
-- ✅ **Fast to implement** - ESLint integration
-- ✅ **Consistent output** - single report format
-
-**❌ Cons:**
-- ❌ **TypeScript only** - hard to extend to Dart/Kotlin
-- ❌ **ESLint dependency** - adds complexity
-- ❌ **Performance overhead** - running ESLint inside SunLint
-- ❌ **Limited AI integration** - ESLint rules can't use AI
-
-**🎯 Score: 6/10** - Quick fix but not scalable
-
----
-
-### **Solution 3B: Migrate ESLint Rules to SunLint**
-```bash
-# Pure SunLint approach
-node cli.js --all --input=src  # All rules in SunLint
-```
-
-**✅ Pros:**
-- ✅ **Unified architecture** - single system
-- ✅ **Multi-language ready** - Dart, Kotlin support
-- ✅ **AI integration** - all rules can use AI
-- ✅ **Performance optimized** - single pass analysis
-- ✅ **Future-proof** - scalable architecture
-
-**❌ Cons:**
-- ❌ **High migration cost** - 3-6 months effort
-- ❌ **Team disruption** - major workflow change
-- ❌ **Risk of regression** - might miss edge cases
-- ❌ **Doesn't acknowledge team effort** - feels like "starting over"
-
-**🎯 Score: 8/10** - Best long-term but expensive
-
-## 🏆 **RECOMMENDED SOLUTION: Hybrid Evolution Strategy**
-
-### **Phase 1: Immediate Integration (1-2 weeks)**
-```bash
-# Enhanced Makefile + Report Merger
-make lint-all    # Runs both ESLint + SunLint  
-make lint-report # Unified JSON report
-```
-
-**Implementation:**
-```makefile
-# Makefile
-.PHONY: lint-all lint-eslint lint-sunlint lint-report
-
-lint-all: lint-eslint lint-sunlint
-
-lint-eslint:
-	@echo "🔍 Running ESLint analysis..."
-	cd coding-quality/config/typescript && \
-	./run.sh --json --export-json --json-file ../../extensions/sunlint/eslint-results.json $(INPUT)
-
-lint-sunlint:
-	@echo "☀️ Running SunLint analysis..."
-	cd coding-quality/extensions/sunlint && \
-	node cli.js --all --input=$(INPUT) --format=json --output=sunlint-results.json --no-ai
-
-lint-report: lint-all
-	@echo "📊 Generating unified report..."
-	cd coding-quality/extensions/sunlint && \
-	node scripts/merge-reports.js eslint-results.json sunlint-results.json --output=unified-report.json
-	@echo "✅ Unified report: unified-report.json"
-
-# Usage
-INPUT ?= src
-lint: lint-all
-```
-
-### **Phase 2: SunLint ESLint Adapter (1-2 months)**
-```javascript
-// SunLint với ESLint integration
-node cli.js --all --include-eslint --eslint-config=../config/typescript/.eslintrc.cjs --input=src
-```
-
-**Implementation Strategy:**
-1. **ESLint Runner Integration** trong SunLint
-2. **Report normalization** - convert ESLint output to SunLint format
-3. **Unified configuration** - single config controls both
-4. **Gradual migration** - opt-in per rule
-
-### **Phase 3: Selective Migration (3-6 months)**
-```javascript
-// Migrate high-value rules only
-const migrationPriority = {
-  immediate: ['c003', 'c006'], // High overlap with SunLint
-  later: ['c010', 'c013'],     // Complex but valuable  
-  keep_eslint: ['t002', 't003'] // TypeScript-specific
-};
-```
-
-**Migration Strategy:**
-1. **Automated conversion tools** - convert ESLint AST → SunLint patterns
-2. **A/B testing** - run both versions, compare results
-3. **Gradual rollout** - migrate 2-3 rules per sprint
-4. **Team validation** - original authors review migrations
-
-## 🎯 **DETAILED IMPLEMENTATION PLAN**
-
-### **Week 1-2: Quick Win (Makefile + Report Merger)**
-
-#### **Step 1: Enhanced Makefile**
-```makefile
-# coding-quality/Makefile
-include config/typescript/eslint.mk
-include extensions/sunlint/sunlint.mk
-
-.PHONY: install lint lint-quick lint-full ci-lint
-
-install:
-	cd config/typescript && npm install
-	cd extensions/sunlint && npm install
-
-lint-quick: lint-sunlint-changed
-lint-full: lint-eslint lint-sunlint-all  
-lint: lint-full
-
-ci-lint:
-	$(MAKE) lint-full INPUT=src FORMAT=github
-	node scripts/ci-report.js
-
-# Development shortcuts
-lint-staged:
-	$(MAKE) lint-sunlint-staged
-	
-lint-pr: 
-	$(MAKE) lint-sunlint-changed BASE=origin/main
-```
-
-#### **Step 2: Report Merger Script**
-```javascript
-// scripts/merge-reports.js
-const fs = require('fs');
-const path = require('path');
-
-class ReportMerger {
-  mergeReports(eslintReport, sunlintReport) {
-    return {
-      tools: {
-        eslint: this.normalizeESLintReport(eslintReport),
-        sunlint: this.normalizeSunLintReport(sunlintReport)
-      },
-      summary: this.generateSummary(eslintReport, sunlintReport),
-      violations: this.mergeViolations(eslintReport, sunlintReport),
-      metadata: {
-        timestamp: new Date().toISOString(),
-        tools_version: {
-          eslint: this.getESLintVersion(),
-          sunlint: this.getSunLintVersion()
-        }
-      }
-    };
-  }
-
-  generateSummary(eslint, sunlint) {
-    return {
-      total_files: this.getTotalFiles(eslint, sunlint),
-      total_violations: this.getTotalViolations(eslint, sunlint),
-      by_severity: this.mergeSeverities(eslint, sunlint),
-      by_tool: {
-        eslint: this.getToolSummary(eslint),
-        sunlint: this.getToolSummary(sunlint)
-      }
-    };
-  }
-}
-```
-
-### **Month 1-2: ESLint Integration**
-
-#### **Step 1: SunLint ESLint Adapter**
-```javascript
-// core/eslint-adapter.js
-class ESLintAdapter {
-  constructor(eslintConfigPath) {
-    this.eslintConfigPath = eslintConfigPath;
-    this.eslint = require('eslint');
-  }
-
-  async runESLintRules(files, options) {
-    const engine = new this.eslint.ESLint({
-      configFile: this.eslintConfigPath,
-      useEslintrc: false
-    });
-
-    const results = await engine.lintFiles(files);
-    return this.convertToSunLintFormat(results);
-  }
-
-  convertToSunLintFormat(eslintResults) {
-    return eslintResults.map(result => ({
-      file: result.filePath,
-      violations: result.messages.map(msg => ({
-        ruleId: `eslint/${msg.ruleId}`,
-        line: msg.line,
-        column: msg.column,
-        message: msg.message,
-        severity: this.mapSeverity(msg.severity),
-        source: 'eslint'
-      }))
-    }));
-  }
-}
-```
-
-#### **Step 2: Enhanced CLI Options**
-```javascript
-// cli.js enhancements
-program
-  .option('--include-eslint', 'Include ESLint custom rules')
-  .option('--eslint-config <path>', 'ESLint config file path')
-  .option('--eslint-only', 'Run only ESLint rules')
-  .option('--sunlint-only', 'Run only SunLint rules')
-  .option('--tool-comparison', 'Run both tools and compare results');
-```
-
-### **Month 3-6: Selective Migration**
-
-#### **Migration Priority Matrix:**
-```javascript
-const migrationPlan = {
-  // High priority - good candidates for migration
-  immediate: {
-    'c003': {
-      reason: 'Variable naming - core feature',
-      complexity: 'medium',
-      ai_potential: 'high',
-      estimated_effort: '1 week'
-    },
-    'c006': {
-      reason: 'Function naming - already exists in SunLint',
-      complexity: 'low', 
-      ai_potential: 'medium',
-      estimated_effort: '3 days'
-    }
-  },
-  
-  // Medium priority - valuable but complex
-  later: {
-    'c010': {
-      reason: 'Block nesting - architectural rule',
-      complexity: 'high',
-      ai_potential: 'high', 
-      estimated_effort: '2 weeks'
-    },
-    'c013': {
-      reason: 'Dead code - useful across languages',
-      complexity: 'high',
-      ai_potential: 'very_high',
-      estimated_effort: '3 weeks'
-    }
-  },
-  
-  // Keep in ESLint - TypeScript specific
-  keep_eslint: {
-    't002': { reason: 'Interface prefix - TS specific syntax' },
-    't003': { reason: 'TS ignore reason - TS compiler specific' },
-    't004': { reason: 'Interface public only - TS type system' }
-  }
-};
-```
-
-## 📊 **COST-BENEFIT ANALYSIS**
-
-| Solution | Implementation Time | Maintenance Cost | Team Disruption | Long-term Value |
-|----------|-------------------|------------------|-----------------|-----------------|
-| **Makefile** | 1-2 weeks | Low | Minimal | Medium |
-| **ESLint Integration** | 1-2 months | Medium | Low | High |
-| **Full Migration** | 3-6 months | Low | High | Very High |
-| **Hybrid Evolution** | 3-4 months total | Medium | Gradual | Very High |
-
-## 🎯 **FINAL RECOMMENDATION**
-
-### **🏆 Choose: Hybrid Evolution Strategy**
-
-**Rationale:**
-1. **Preserves team effort** - ESLint rules remain valuable
-2. **Immediate benefits** - unified reporting in weeks  
-3. **Future flexibility** - gradual migration path
-4. **Risk mitigation** - incremental changes
-5. **Team buy-in** - respects existing work
-
-**Success Metrics:**
-- ✅ **Week 2**: Unified report generation  
-- ✅ **Month 1**: Single command execution
-- ✅ **Month 2**: ESLint integration in SunLint
-- ✅ **Month 6**: 50% rules migrated to SunLint
-- ✅ **Year 1**: Multi-language support with migrated rules
-
-**Key Decision Factors:**
-- ✅ **Team productivity** > tool purity
-- ✅ **Incremental value** > big bang approach  
-- ✅ **Respect existing work** > reinvent everything
-- ✅ **Multi-language future** > TypeScript-only optimization
-
-This strategy acknowledges your team's investment while building toward a unified, scalable future! 🚀

package/docs/FUTURE_PACKAGES.md

@@ -1,83 +0,0 @@
-# Future SunLint Package Strategy
-
-## Core Packages
-
-### @sun-asterisk/sunlint (Core)
-- Size: ~235KB
-- Features: Basic JS/TS heuristic analysis
-- Dependencies: @babel/parser, espree
-- Target: Minimal setup, basic quality checks
-
-### @sun-asterisk/sunlint-typescript 
-- Size: ~2MB
-- Features: Full TypeScript analysis with AST
-- Dependencies: Core + @typescript-eslint/parser, typescript
-- Target: TypeScript projects
-
-### @sun-asterisk/sunlint-full
-- Size: ~10MB  
-- Features: Complete ESLint integration, all parsers
-- Dependencies: Core + all ESLint ecosystem
-- Target: Full-featured analysis
-
-## Language Extensions
-
-### @sun-asterisk/sunlint-dart
-- Dart-specific rules and analysis
-- Dependencies: dart_analyzer, dart tools
-
-### @sun-asterisk/sunlint-python
-- Python-specific rules
-- Dependencies: pylint, autopep8, mypy
-
-### @sun-asterisk/sunlint-go
-- Go-specific analysis
-- Dependencies: staticcheck, golint
-
-## Feature Extensions
-
-### @sun-asterisk/sunlint-ai
-- AI-powered code analysis
-- Dependencies: OpenAI API, Claude API
-
-### @sun-asterisk/sunlint-security
-- Advanced security scanning
-- Dependencies: semgrep, snyk, security plugins
-
-## Installation Examples
-
-```bash
-# Basic usage
-npm install @sun-asterisk/sunlint --save-dev
-
-# TypeScript project
-npm install @sun-asterisk/sunlint-typescript --save-dev
-
-# Multi-language project
-npm install @sun-asterisk/sunlint @sun-asterisk/sunlint-dart @sun-asterisk/sunlint-python --save-dev
-
-# Enterprise setup with all features
-npm install @sun-asterisk/sunlint-full @sun-asterisk/sunlint-ai @sun-asterisk/sunlint-security --save-dev
-```
-
-## Configuration
-
-### Package-based auto-detection
-```json
-// .sunlint.json
-{
-  "extends": ["auto-detect-packages"],  // Automatically use installed packages
-  "rules": {
-    "C010": "error"
-  }
-}
-```
-
-### Smart recommendations
-```bash
-# When SunLint detects TypeScript files but no TS package
-npx sunlint --all
-# Output: 
-# 💡 TypeScript files detected. For better analysis:
-# npm install @sun-asterisk/sunlint-typescript --save-dev
-```

package/docs/HEURISTIC_VS_AI.md

@@ -1,113 +0,0 @@
-# 🎯 Heuristic vs AI Analysis Guide
-
-## Quick Commands
-
-### 🔍 **Heuristic Mode (Fast & Accurate)**
-```bash
-# Force heuristic analysis (ignore config)
-node cli.js --rule=C019 --input=src --no-ai
-
-# Disable in config file
-# In .sunlint.json: "ai": { "enabled": false }
-```
-
-### 🤖 **AI Mode (Context-Aware)**
-```bash
-# Force AI analysis (with API key)
-export OPENAI_API_KEY="your-key"
-node cli.js --rule=C019 --input=src --ai
-
-# Enable in config file  
-# In .sunlint.json: "ai": { "enabled": true }
-```
-
-## Performance Comparison
-
-| Mode | Speed | Accuracy | Cost | Use Case |
-|------|-------|----------|------|----------|
-| **Heuristic** | ⚡ ~100ms | 95%+ | Free | Daily development |
-| **AI** | 🐌 ~20-30s | 98%+ | $0.001/file | Complex analysis |
-
-## Configuration Priority
-
-1. **CLI flags** (highest priority)
-   - `--ai` → Force enable AI
-   - `--no-ai` → Force disable AI
-
-2. **Config file** (.sunlint.json)
-   ```json
-   {
-     "ai": {
-       "enabled": true/false,
-       "provider": "openai",
-       "model": "gpt-4o-mini"
-     }
-   }
-   ```
-
-3. **Default** → Heuristic mode
-
-## Use Cases
-
-### ✅ **Use Heuristic When:**
-- Daily code reviews
-- CI/CD pipelines
-- Quick local checks
-- Large codebases
-- Limited internet/API quotas
-
-### ✅ **Use AI When:**
-- Complex rule violations
-- Need context understanding
-- Training new developers
-- Quality audits
-- Unusual code patterns
-
-## Debug Commands
-
-```bash
-# Check which mode is active
-node cli.js --rule=C019 --input=src --debug
-
-# Look for these outputs:
-# Heuristic: "🔍 Running pattern analysis"
-# AI: "🤖 AI analysis enabled" + "🎯 AI found X violations"
-```
-
-## Troubleshooting
-
-### AI Not Working?
-1. Check API key: `echo $OPENAI_API_KEY`
-2. Use `--ai --debug` to see errors
-3. Verify config: `"ai": { "enabled": true }`
-
-### Heuristic Not Working?
-1. Use `--no-ai --debug`
-2. Check output for "🔍 Running pattern analysis"
-
-## Best Practices
-
-1. **Development**: Use `--no-ai` for speed
-2. **CI/CD**: Use heuristic mode by default
-3. **Code Review**: Use AI for complex cases
-4. **Training**: Use AI mode to understand violations better
-
-## Example Workflows
-
-### Daily Development
-```bash
-# Quick check before commit
-node cli.js --quality --input=src --no-ai
-```
-
-### Code Review
-```bash
-# Deep analysis with AI
-node cli.js --quality --input=src --ai --format=summary
-```
-
-### CI Pipeline
-```bash
-# Fast, reliable heuristic
-node cli.js --all --input=src --no-ai --format=json
-```

package/docs/PRODUCTION_DEPLOYMENT_ANALYSIS.md

@@ -1,112 +0,0 @@
-# Production Deployment Analysis - SunLint Size Impact
-
-## 🔍 **Câu hỏi từ Developer:**
-*"Công việc trên có phải là phổ biến không, tức là khi deploy thông thường có làm các công việc đó không?"*
-
-## 📊 **Thực tế Deployment Phổ Biến**
-
-### ✅ **THỰC TẾ 1: DevDependencies tự động bị loại trừ**
-
-**Hầu hết deployment platforms tự động loại trừ devDependencies:**
-
-| Platform | Auto-exclude devDependencies | Command |
-|----------|------------------------------|---------|
-| **Heroku** | ✅ | `npm install --production` |
-| **Vercel** | ✅ | `npm ci --production` |
-| **Netlify** | ✅ | `npm install --production` |
-| **Docker** | ✅ | `RUN npm ci --only=production` |
-| **AWS Lambda** | ✅ | `npm install --production` |
-| **Google Cloud** | ✅ | `npm ci --production` |
-
-### ✅ **THỰC TẾ 2: Build process tự nhiên**
-
-**Typical CI/CD pipeline:**
-```bash
-# Development
-npm install              # Cài tất cả (bao gồm SunLint)
-npm run lint            # SunLint chạy để check code
-npm run test            # Tests chạy
-npm run build           # Build production bundle
-
-# Production deployment
-npm ci --production     # CHỈ cài runtime dependencies
-# SunLint tự động bị loại trừ!
-```
-
-### ✅ **THỰC TẾ 3: Docker multistage builds**
-
-**Phổ biến nhất - Docker multistage:**
-```dockerfile
-# Build stage
-FROM node:18 AS builder
-COPY package*.json ./
-RUN npm install        # Cài tất cả, kể cả SunLint
-COPY . .
-RUN npm run build      # SunLint chạy trong quá trình build
-
-# Production stage  
-FROM node:18-alpine AS production
-COPY package*.json ./
-RUN npm ci --production --silent  # CHỈ runtime deps
-COPY --from=builder /app/dist ./dist
-# SunLint không có trong production image!
-```
-
-## 🎯 **Kết luận về SunLint**
-
-### **TẠI SAO SUNLINT AN TOÀN 100%:**
-
-1. **DevDependency by design** - SunLint được thiết kế như linting tool
-2. **Industry standard** - Tất cả linting tools đều hoạt động như vậy
-3. **Automatic exclusion** - Deployment platforms tự động loại trừ
-4. **Zero production footprint** - Không code SunLint nào trong runtime
-
-### **SO SÁNH VỚI CÔNG CỤ KHÁC:**
-
-| Tool | Size | Production Impact | Usage Pattern |
-|------|------|-------------------|---------------|
-| **ESLint** | ~500KB | ❌ (nếu sai cách) | DevDependency ✅ |
-| **SunLint** | **241KB** | ✅ **KHÔNG** | DevDependency ✅ |
-| **Prettier** | ~300KB | ❌ (nếu sai cách) | DevDependency ✅ |
-| **TypeScript** | ~60MB | ❌ (nếu sai cách) | DevDependency ✅ |
-
-## 📈 **Best Practices Verification**
-
-### **✅ ĐÚNG CÁCH (99% cases):**
-```json
-{
-  "devDependencies": {
-    "@sun-asterisk/sunlint": "^1.1.4",
-    "eslint": "^8.57.1",
-    "prettier": "^3.0.0"
-  },
-  "dependencies": {
-    "express": "^4.18.0"  // Chỉ runtime deps
-  }
-}
-```
-
-### **❌ SAI CÁCH (hiếm, chỉ newbie):**
-```json
-{
-  "dependencies": {
-    "@sun-asterisk/sunlint": "^1.1.4",  // ❌ Sai!
-    "express": "^4.18.0"
-  }
-}
-```
-
-## 🚀 **Tóm tắt**
-
-**CÂU TRẢ LỜI:** Các công việc này **HOÀN TOÀN PHỔ BIẾN** và **TỰ ĐỘNG** trong production deployment:
-
-1. ✅ **DevDependencies tự động bị loại trừ** - Industry standard
-2. ✅ **Build tools chỉ chạy development time** - Normal practice  
-3. ✅ **Production chỉ có runtime code** - Security best practice
-4. ✅ **SunLint = 0KB trong production** - Guaranteed
-
-**Developer không cần lo lắng về size impact của SunLint!**
-
----
-*Generated on: 2025-07-24*
-*SunLint Version: 1.1.4*