@sun-asterisk/sunlint 1.0.7 → 1.1.4

package/docs/FUTURE_PACKAGES.md

@@ -0,0 +1,83 @@
+# 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

@@ -0,0 +1,113 @@
+# 🎯 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

@@ -0,0 +1,112 @@
+# 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*

package/docs/PRODUCTION_SIZE_IMPACT.md

@@ -0,0 +1,183 @@
+# 📦 SunLint Production Size Impact Analysis
+
+## Tóm tắt cho Leadership
+
+**KẾT LUẬN: SunLint KHÔNG làm tăng size production khi sử dụng đúng cách.**
+
+## Chi tiết phân tích
+
+### 1. Package Size của SunLint
+
+```bash
+SunLint package size: 241.6 kB
+SunLint unpacked size: 1.1 MB
+Total files: 214
+```
+
+### 2. Test Production Impact
+
+Chúng tôi đã tạo một project test để kiểm tra impact thực tế:
+
+| Giai đoạn | Size | Ghi chú |
+|-----------|------|---------|
+| Project ban đầu | 8.0K | Chỉ có package.json và .gitignore |
+| Sau khi cài SunLint (devDependency) | 88M | Bao gồm tất cả devDependencies |
+| Production bundle (dist/) | 4.0K | Code production thực tế |
+| Sau npm prune --production | 156K | Đã xóa tất cả devDependencies |
+
+### 3. Khuyến nghị sử dụng trong Production
+
+#### ✅ ĐÚNG CÁCH (Production-friendly):
+
+```json
+{
+  "devDependencies": {
+    "@sun-asterisk/sunlint": "^1.1.4"
+  }
+}
+```
+
+**Lợi ích:**
+- ✅ Không ảnh hưởng size production bundle
+- ✅ Chỉ cài khi development (`npm install`)
+- ✅ Tự động loại trừ khỏi production (`npm prune --production`)
+- ✅ CI/CD có thể dùng để check code quality
+
+#### ❌ SAI CÁCH (Không khuyến nghị):
+
+```json
+{
+  "dependencies": {
+    "@sun-asterisk/sunlint": "^1.1.4"
+  }
+}
+```
+
+**Vấn đề:**
+- ❌ Tăng 1.1MB cho production bundle
+- ❌ Không cần thiết cho runtime
+- ❌ Làm chậm deployment
+
+### 4. Deployment Strategies
+
+#### Option 1: Development Only (Khuyến nghị)
+```bash
+# Development
+npm install
+
+# Production build
+npm run build
+npm prune --production
+# → SunLint sẽ bị xóa hoàn toàn
+```
+
+#### Option 2: CI/CD Pipeline
+```yaml
+# .github/workflows/ci.yml
+- name: Install deps
+  run: npm ci
+- name: Run SunLint
+  run: npx sunlint --quality --input=src
+- name: Build production
+  run: npm run build
+- name: Remove dev deps
+  run: npm prune --production
+```
+
+#### Option 3: Docker Multi-stage
+```dockerfile
+# Development stage với SunLint
+FROM node:18 as dev
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npx sunlint --all --input=src
+
+# Production stage KHÔNG có SunLint
+FROM node:18-alpine as prod
+COPY package*.json ./
+RUN npm ci --only=production
+COPY dist/ ./dist/
+```
+
+### 5. So sánh với các tools khác
+
+| Tool | Package Size | Production Impact | Use Case |
+|------|-------------|-------------------|-----------|
+| ESLint | ~500KB | ❌ Nếu để dependencies | Development only |
+| Prettier | ~200KB | ❌ Nếu để dependencies | Development only |
+| **SunLint** | **241KB** | **✅ KHÔNG (devDep)** | **Development + CI/CD** |
+| TypeScript | ~60MB | ❌ Nếu để dependencies | Development only |
+
+### 6. Best Practices cho Teams
+
+#### Developers:
+```bash
+# Local development
+npm install          # Cài tất cả deps (bao gồm SunLint)
+npx sunlint --quality --input=src
+
+# Pre-commit hook
+npx sunlint --changed-files
+```
+
+#### CI/CD:
+```bash
+# Build pipeline
+npm ci                       # Cài tất cả deps
+npx sunlint --all --input=src  # Quality check
+npm run build                # Build production
+npm prune --production       # Xóa devDeps
+```
+
+#### Production:
+```bash
+# Server deployment
+npm ci --only=production     # Chỉ cài production deps
+# → SunLint sẽ KHÔNG được cài
+```
+
+### 7. Monitoring & Verification
+
+#### Verify production size:
+```bash
+# Trước deploy
+du -sh node_modules
+du -sh dist/
+
+# Kiểm tra không có SunLint
+ls node_modules | grep sunlint  # Không có kết quả = OK
+```
+
+#### Bundle size monitoring:
+```bash
+# Add to package.json
+{
+  "scripts": {
+    "analyze-bundle": "du -sh dist/ && echo 'Production bundle size'",
+    "verify-prod": "npm ls --production --depth=0"
+  }
+}
+```
+
+## Kết luận
+
+### ✅ AN TOÀN cho Production:
+- SunLint được thiết kế như devDependency
+- Không ảnh hưởng size production bundle khi sử dụng đúng
+- Có thể tích hợp vào CI/CD mà không ảnh hưởng deployment
+
+### 📊 Số liệu cụ thể:
+- **Development**: +88MB (chỉ khi dev)
+- **Production**: +0KB (khi dùng đúng cách)
+- **CI/CD**: Impact chỉ ở build time, không ở runtime
+
+### 🚀 Khuyến nghị:
+1. **Luôn cài như devDependency**
+2. **Sử dụng trong CI/CD pipeline**
+3. **npm prune --production trước deploy**
+4. **Monitor bundle size định kỳ**
+
+---
+
+*Tài liệu này được cập nhật cho SunLint v1.1.4 - July 2025*

package/docs/README.md

@@ -0,0 +1,32 @@
+# 📚 Sunlint Documentation
+
+## Quick Links
+
+- **[AI Features](AI.md)** - AI-powered analysis guide
+- **[Debug Guide](DEBUG.md)** - How to debug rules and CLI
+- **[Architecture](ARCHITECTURE.md)** - System architecture and modular design
+- **[Distribution](DISTRIBUTION.md)** - Installation and deployment methods
+
+## Development Guides
+
+- **[Folder Structure](FOLDER_STRUCTURE.md)** - Project organization
+- **[ESLint Integration Strategy](ESLINT-INTEGRATION-STRATEGY.md)** - ESLint vs SunLint strategy
+- **[CI/CD Guide](CI-CD-GUIDE.md)** - Continuous integration setup
+- **[Command Examples](COMMAND-EXAMPLES.md)** - CLI usage examples
+
+## Performance & Analysis
+
+- **[Heuristic vs AI](HEURISTIC_VS_AI.md)** - Performance comparison guide
+- **[Rule Responsibility Matrix](RULE-RESPONSIBILITY-MATRIX.md)** - Rules mapping and coverage
+
+## Main Documentation
+
+- **[README.md](../README.md)** - Main project documentation
+- **[CONTRIBUTING.md](../CONTRIBUTING.md)** - Contribution guidelines
+- **[CHANGELOG.md](../CHANGELOG.md)** - Version history
+- **[LICENSE](../LICENSE)** - License information
+
+## Configuration
+
+- **[.sunlint-simple.json](../.sunlint-simple.json)** - Simple configuration example
+- **[sunlint.config.json](../sunlint.config.json)** - Full configuration with all features