@sun-asterisk/sunlint 1.0.5 → 1.0.6

package/README.md

@@ -4,7 +4,7 @@
 
 ## 🎯 **Overview**
 
-Sun Lint is a universal coding standards checker that provides comprehensive code quality and security analysis. Built by Sun* Engineering Team with integrated security rules from OWASP and industry best practices.
+Sun Lint is a universal coding standards checker providing comprehensive code quality and security analysis. Built by Sun* Engineering Team with integrated security rules from OWASP and industry best practices.
 
 ### **✨ Key Features**
 - ✅ **93+ Coding Rules**: Quality, security, and best practices
@@ -12,479 +12,214 @@ Sun Lint is a universal coding standards checker that provides comprehensive cod
 - ✅ **Git Integration**: `--changed-files`, `--staged-files`, `--pr-mode`
 - ✅ **TypeScript Support**: Native TypeScript analysis engine
 - ✅ **CI/CD Ready**: Baseline comparison, fail-on-new-violations
-- ✅ **Multiple Formats**: ESLint, JSON, Summary, Table output
-- ✅ **Team Adoption**: Zero-disruption integration for existing workflows
+- ✅ **Advanced File Targeting**: Include/exclude patterns, language filtering
 
 ### **🚀 Quick Start**
-- ✅ **Run single rule**: `sunlint --rule=C019`
-- ✅ **Run multiple rules**: `sunlint --rules=C019,C006,C021`  
-- ✅ **Run all rules**: `sunlint --all` (93 rules total)
-- ✅ **Run by category**: `sunlint --quality` or `sunlint --security`
-- ✅ **ESLint integration**: `sunlint --all --eslint-integration`
-- ✅ **Git workflow**: `sunlint --all --changed-files`
-
-## 📦 **Installation**
-
-### **Method 1: Global Installation (Recommended)**
 ```bash
-# Install globally for command-line usage - Universal for all languages
+# Install globally
 npm install -g @sun-asterisk/sunlint
 
-# Verify installation
-sunlint --version
-```
-
-*✨ **Why Global?** SunLint supports multiple languages (TypeScript, Dart, Kotlin, Java, Swift, etc.). Global installation provides universal access across all project types.*
-
-### **Method 2: TypeScript Project Integration** 
-For TypeScript-specific projects that prefer project-level dependencies:
-```bash
-# Add to TypeScript project dependencies  
-npm install --save-dev @sun-asterisk/sunlint
+# Basic usage
+sunlint --all --input=src
+sunlint --rules=C019,C006 --input=src
+sunlint --quality --input=src
 
-# Or using yarn
-yarn add --dev @sun-asterisk/sunlint
-```
+# ESLint integration
+sunlint --all --eslint-integration --input=src
 
-**Package.json scripts for TypeScript projects:**
-```json
-{
-  "scripts": {
-    "lint": "sunlint --typescript --input=src",
-    "lint:changed": "sunlint --typescript --changed-files",
-    "lint:eslint-integration": "sunlint --typescript --eslint-integration --input=src"
-  },
-  "devDependencies": {
-    "@sun-asterisk/sunlint": "^1.0.5"
-  }
-}
+# Git integration  
+sunlint --all --changed-files
 ```
 
-### **🌍 Multi-Language Strategy**
-**Future Roadmap**: SunLint will expand to support:
-- ✅ **TypeScript** (Phase 1 - Current)
-- 🔄 **Dart** (Phase 2 - Planned)  
-- 🔄 **Kotlin** (Phase 3 - Planned)
-- 🔄 **Java** (Phase 4 - Planned)
-- 🔄 **Swift** (Phase 5 - Planned)
-
-**Global installation ensures**:
-- ✅ **Cross-project compatibility**: One tool for all languages
-- ✅ **Team standardization**: Consistent tool across different project types  
-- ✅ **CI/CD simplicity**: Single installation for polyglot repositories
+## 📦 **Installation**
 
-### **Method 3: GitHub Package Registry (Private)**
+### **Global Installation (Recommended)**
 ```bash
-# 1. Setup GitHub Package Registry (one-time)
-curl -fsSL https://raw.githubusercontent.com/sun-asterisk/engineer-excellence/main/coding-quality/extensions/sunlint/scripts/setup-github-registry.sh | GITHUB_TOKEN=your_token bash
-
-# 2. Install SunLint globally  
 npm install -g @sun-asterisk/sunlint
-
-# 3. Verify installation
 sunlint --version
 ```
 
-**Manual setup**:
-```bash
-# Configure GitHub Package Registry
-echo "@sun-asterisk:registry=https://npm.pkg.github.com" >> ~/.npmrc
-echo "//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}" >> ~/.npmrc
-
-# Install from GitHub Packages globally
-npm install -g @sun-asterisk/sunlint
-```
-
-### **Method 4: Direct GitHub Release**
+### **Project Installation**
 ```bash
-# Install from GitHub release tarball globally
-npm install -g https://github.com/sun-asterisk/engineer-excellence/releases/download/sunlint-v1.0.5/sunlint-1.0.5.tgz
-
-# Verify installation
-sunlint --version
-```
+npm install --save-dev @sun-asterisk/sunlint
 
-### **Method 5: Development Setup**
-```bash
-# Clone and install for development
-git clone https://github.com/sun-asterisk/engineer-excellence.git
-cd engineer-excellence/coding-quality/extensions/sunlint
-npm install
-npm install -g .
+# Package.json scripts
+{
+  "scripts": {
+    "lint": "sunlint --all --input=src",
+    "lint:changed": "sunlint --all --changed-files"
+  }
+}
 ```
 
-## 🔗 **ESLint Integration** *(New in v1.0.5)*
+## 🔗 **ESLint Integration**
 
-SunLint can seamlessly integrate with existing ESLint configurations, combining both rule sets in a single execution.
+Seamlessly integrate with existing ESLint configurations:
 
-### **For Teams with Existing ESLint**
 ```bash
 # Analyze with both SunLint + existing ESLint rules
 sunlint --all --eslint-integration --input=src
-
-# Works with git integration too
-sunlint --all --eslint-integration --changed-files
-```
-
-### **Configuration**
-```json
-{
-  "sunlint": {
-    "eslintIntegration": {
-      "enabled": true,
-      "mergeRules": true,
-      "preserveUserConfig": true
-    },
-    "rules": {
-      "C006": "warn",
-      "C019": "error"
-    }
-  }
-}
 ```
 
-### **Benefits**
+Benefits:
 - ✅ **No workflow disruption**: Existing ESLint continues working
 - ✅ **Single command**: Execute 93 SunLint + your existing ESLint rules
-- ✅ **Conflict resolution**: Your ESLint rules take precedence
 - ✅ **Combined reporting**: Unified violation tracking
 
-**Example**: Team with 20 existing ESLint rules + 93 SunLint rules = **113 total rules** in single execution!
-
-[📖 **Read Full ESLint Integration Guide**](./docs/ESLINT_INTEGRATION.md)
+## 🔀 **Git Integration**
 
-## 🔀 **Git Integration** *(New in v1.0.5)*
+Optimize CI/CD workflows with Git integration:
 
-SunLint provides powerful Git integration for optimized CI/CD workflows and development processes.
-
-### **Basic Git Commands**
 ```bash
-# Analyze only changed files (vs main branch)
+# Analyze only changed files
 sunlint --all --changed-files
 
-# Analyze only staged files (pre-commit)
+# Pre-commit validation
 sunlint --all --staged-files
 
-# PR mode with custom base branch
-sunlint --all --changed-files --diff-base=origin/develop
-
-# Files changed since specific commit
-sunlint --all --since=abc123
-
 # PR mode with failure only on new violations
 sunlint --all --pr-mode --fail-on-new-violations
 ```
 
-### **CI/CD Integration Examples**
-```bash
-# GitHub Actions - PR check
-sunlint --all --changed-files --diff-base=origin/main --format=summary
-
-# Pre-commit hook
-sunlint --all --staged-files --format=summary --no-ai
+## 🎯 **Advanced File Targeting**
 
-# Release validation
-sunlint --all --since=last-release --format=json --output=quality-report.json
-```
+Powerful file targeting capabilities:
 
-### **Combined Git + ESLint Integration**
 ```bash
-# Ultimate integration: Git + ESLint + SunLint
-sunlint --all --eslint-integration --changed-files --fail-on-new-violations
-```
+# Include specific patterns
+sunlint --all --include="src/**/*.ts,lib/**/*.dart" --input=.
 
-**Benefits**:
-- ✅ **Performance**: Only analyze relevant files
-- ✅ **PR-focused**: Catch issues in changed code  
-- ✅ **Incremental**: Fail only on new violations
-- ✅ **Flexible**: Support multiple Git workflows
+# Exclude patterns  
+sunlint --all --exclude="**/*.test.*,**/*.generated.*" --input=src
 
-## 🎯 **Usage Examples**
-```bash
-# Install for specific project
-npm install https://github.com/sun-asterisk/engineer-excellence/releases/download/sunlint-v1.0.0/sun-sunlint-1.0.0.tgz
+# Language filtering
+sunlint --all --languages=typescript,dart --input=src
 
-# Use with npx
-npx sunlint --quality --input=src
+# Source files only (exclude tests, configs)
+sunlint --all --only-source --input=src
 ```
 
-### **Verify Installation**
-```bash
-sunlint --version
-# Should output: 1.0.0
-
-sunlint --help
-# Shows full command options
-```
+### **Configuration Priority** (Highest to Lowest)
+1. **CLI flags**: `--include`, `--exclude`, `--languages`
+2. **Project config**: `.sunlint.json`
+3. **Package.json**: `"sunlint"` field  
+4. **Default config**: Built-in patterns
 
-## � **TypeScript Support** *(New in v1.0.5)*
+## 📋 **Available Rules**
 
-SunLint provides native TypeScript analysis with dedicated engine and enhanced rule support.
+### **Quality Rules** ✨ (9 rules)
+| Rule ID | Name | Status |
+|---------|------|--------|
+| **C005** | Single Responsibility | ✅ Stable |
+| **C006** | Function Naming | ✅ Stable |
+| **C007** | Comment Quality | ✅ Stable |
+| **C012** | Command Query Separation | ✅ Stable |
+| **C014** | Dependency Injection | ✅ Stable |
+| **C015** | Domain Language | ✅ Stable |
+| **C019** | Log Level Usage | ✅ Stable |
+| **C031** | Validation Separation | ✅ Stable |
+| **C037** | API Response Format | ✅ Stable |
 
-### **TypeScript-specific Commands**
-```bash
-# Force TypeScript engine for all rules
-sunlint --typescript --input=src
+### **Security Rules** 🔒 (43 rules)
+| Rule ID | Name | Status |
+|---------|------|--------|
+| **S005** | No Origin Header Authentication | ✅ Stable |
+| **S008** | Crypto Agility | ✅ Stable |
+| **S012** | No Hardcoded Secrets | ✅ Stable |
+| **S014-S058** | *...40 additional security rules* | ✅ Stable |
 
-# TypeScript with specific rules
-sunlint --typescript --rules=C006,C019,S047 --input=src
-
-# TypeScript + ESLint integration
-sunlint --typescript --eslint-integration --input=src
+## ⚙️ **Configuration**
 
-# TypeScript + Git integration
-sunlint --typescript --changed-files --format=summary
-```
+Create `.sunlint.json` in your project root:
 
-### **Project Integration for TypeScript**
-*Optional: If you prefer project-level dependencies*
+### **Basic Configuration**
 ```json
 {
-  "scripts": {
-    "lint:ts": "sunlint --typescript --input=src",
-    "lint:ts-changed": "sunlint --typescript --changed-files", 
-    "lint:ts-eslint": "sunlint --typescript --eslint-integration --input=src"
-  },
-  "devDependencies": {
-    "@sun-asterisk/sunlint": "^1.0.5",
-    "@typescript-eslint/eslint-plugin": "^6.0.0",
-    "@typescript-eslint/parser": "^6.0.0"
+  "extends": "@sun/sunlint/recommended",
+  "rules": {
+    "C019": "error",
+    "C006": "warn", 
+    "S005": "error"
   }
 }
 ```
 
-*Note: SunLint works equally well with global installation. Project-level dependencies are optional for TypeScript projects.*
-
-### **Features**
-- ✅ **Native AST Analysis**: TypeScript parser integration
-- ✅ **ESLint Bridge**: Seamless integration with existing ESLint rules  
-- ✅ **Type Checking**: Leverage TypeScript compiler for advanced analysis
-- ✅ **Performance**: Optimized for TypeScript codebases
-
-## �📋 **Available Rules**
-
-### **Quality Rules** ✨
-| Rule ID | Name | Category | Languages | Status |
-|---------|------|----------|-----------|--------|
-| **C005** | Single Responsibility | quality | TS, Dart, Kotlin | ✅ Stable |
-| **C006** | Function Naming | quality | TS, Dart, Kotlin | ✅ Stable |
-| **C007** | Comment Quality | quality | TS, Dart, Kotlin | ✅ Stable |
-| **C012** | Command Query Separation | quality | TS, Dart, Kotlin | ✅ Stable |
-| **C014** | Dependency Injection | quality | TS, Dart, Kotlin | ✅ Stable |
-| **C015** | Domain Language | quality | TS, Dart, Kotlin | ✅ Stable |
-| **C019** | Log Level Usage | quality | TS, Dart, Kotlin | ✅ Stable |
-| **C031** | Validation Separation | quality | TS, Dart, Kotlin | ✅ Stable |
-| **C037** | API Response Format | quality | TS, Dart, Kotlin | ✅ Stable |
-
-### **Security Rules** 🔒 *(New in v1.0.4)*
-| Rule ID | Name | Category | Languages | Status |
-|---------|------|----------|-----------|--------|
-| **S005** | No Origin Header Authentication | security | TS, JS | ✅ Stable |
-| **S006** | Activation Recovery Secret Not Plaintext | security | TS, JS | ✅ Stable |
-| **S008** | Crypto Agility | security | TS, JS | ✅ Stable |
-### **Security Rules** 🔒 *(43 rules total)*
-| Rule ID | Name | Category | Languages | Status |
-|---------|------|----------|-----------|--------|
-| **S005** | No Origin Header Authentication | security | TS, JS | ✅ Stable |
-| **S008** | Crypto Agility | security | TS, JS | ✅ Stable |
-| **S012** | No Hardcoded Secrets | security | TS, JS | ✅ Stable |
-| **S014-S058** | *...40 additional security rules* | security | TS, JS | ✅ Stable |
-
-*Complete list available in CHANGELOG.md*
-
-## 🎮 **Usage Examples**
-
-### **Basic Usage**
-```bash
-# Run all rules (93 total: quality + security)
-sunlint --all --typescript --input=src/
-
-# Check specific category
-sunlint --security --typescript --input=src/
-sunlint --quality --typescript --input=src/
-
-# Check specific rules
-sunlint --rules=C019,S005 --typescript --input=src/
-```
-
-### **Complete Analysis** 🎯
-```bash
-# Run all rules (quality + security = 44 rules)
-sunlint --all --typescript --input=src/
-
-# Local development scan
-sunlint --typescript --input=. --format=summary
-
-# Check single file
-sunlint --all --typescript --input=components/Button.tsx
-```
-
-### **CI/CD Integration** 🚀
-```bash
-# Full project scan (main branch)
-sunlint --all --input=. --format=json --output=sunlint-report.json
-
-# Changed files only (PR checks)  
-sunlint --all --changed-files --format=summary
-
-# With ESLint integration
-sunlint --all --eslint-integration --changed-files
-```
-
-## ⚙️ **Configuration**
-
-Create `.sunlint.json` in your project root:
-
+### **Advanced Configuration**
 ```json
 {
   "extends": "@sun/sunlint/recommended",
+  
+  "include": ["src/**", "lib/**"],
+  "exclude": ["**/*.test.*", "**/*.generated.*"],
+  
+  "languages": {
+    "typescript": {
+      "include": ["**/*.ts", "**/*.tsx"],
+      "exclude": ["**/*.d.ts"]
+    }
+  },
+
+  "testPatterns": {
+    "include": ["**/*.test.*", "**/*.spec.*"],
+    "rules": { "C006": "off" }
+  },
+
   "rules": {
     "C019": "error",
     "C006": "warn", 
     "S005": "error"
-  },
-  "categories": ["quality", "security"],
-  "ignorePatterns": ["node_modules/**", "dist/**"]
+  }
 }
 ```
+
+### **Preset Configurations**
+- `@sun/sunlint/recommended` - Balanced rules for all projects
 - `@sun/sunlint/security` - Security-focused rules only
 - `@sun/sunlint/quality` - Quality-focused rules only
+- `@sun/sunlint/beginner` - Gentle introduction for new teams
+- `@sun/sunlint/ci` - Optimized for CI/CD environments
 
-## 📊 **Output Formats**
-
-```bash
-# ESLint-compatible JSON
-sunlint --format=eslint --input=src
-
-# Human-readable summary
-sunlint --format=summary --input=src
-
-# Detailed report
-sunlint --format=detailed --input=src
-
-# GitHub Actions format
-sunlint --format=github --input=src
-```
-
-## 🚀 **CI/CD Strategy & Best Practices**
-
-### **Vấn đề về Performance và Cost**
-
-| Approach | Ưu điểm | Nhược điểm | Khi nào sử dụng |
-|----------|---------|------------|-----------------|
-| **Full Scan** | Phát hiện hết tất cả issues, consistent | Chậm, tốn resource, nhiều noise | Main branch, weekly reports |
-| **Changed Files Only** | Nhanh, relevant, cost-effective | Miss issues từ dependency changes | PR checks, pre-commit |
-| **Baseline Comparison** | Balance giữa performance và coverage | Setup phức tạp hơn | Large projects |
-
-### **Recommended CI/CD Strategy**
-
-## 📊 **Output Formats**
+## 🎮 **Usage Examples**
 
+### **Development**
 ```bash
-# ESLint-compatible JSON
-sunlint --format=eslint --input=src
+# Run all rules
+sunlint --all --input=src
 
-# Human-readable summary  
-sunlint --format=summary --input=src
+# Check specific rules
+sunlint --rules=C019,S005 --input=src
 
-# GitHub Actions format
-sunlint --format=github --input=src
+# ESLint + Git integration
+sunlint --all --eslint-integration --changed-files
 ```
 
-## 🚀 **CI/CD Best Practices**
-
-### **Recommended Strategy**
+### **CI/CD**
 ```bash
-# PR: Check changed files only (fast)
-sunlint --all --changed-files --diff-base=origin/main
+# Full project scan
+sunlint --all --input=. --format=json --output=report.json
 
-# Main branch: Full scan + baseline
-sunlint --all --input=. --save-baseline=baseline.json
-```
-
-**Performance**: Changed files (~10-30s) vs Full scan (~2-5min)
-
-## 🛠 **CI/CD Integration**
-
-**GitHub Actions (PR Mode):**
-```yaml
-name: Code Quality Check
-on:
-  pull_request:
-    branches: [main, develop]
-
-jobs:
-  sunlint:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v3
-      with:
-        fetch-depth: 0  # Fetch full history for diff comparison
-    
-    - name: Setup Node.js
-      uses: actions/setup-node@v3
-      with:
-        node-version: '18'
-    
-    - name: Install SunLint
-**GitHub Actions Example:**
-```yaml
-name: Code Quality Check
-on:
-  pull_request:
-    branches: [main]
-
-jobs:
-  sunlint:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v3
-      with:
-        fetch-depth: 0
-    
-    - name: Setup Node.js
-      uses: actions/setup-node@v3
-      with:
-        node-version: '18'
-    
-    - name: Install SunLint
-      run: npm install -g @sun-asterisk/sunlint
-    
-    - name: Run SunLint on Changed Files
-      run: |
-        sunlint --all --changed-files --diff-base=origin/main \
-        --format=github --fail-on-new-violations
-```
-      with:
-        name: sunlint-baseline
-        path: sunlint-baseline.json
-```
+# PR validation
+sunlint --all --changed-files --fail-on-new-violations
 
-**GitLab CI (PR Mode):**
-```yaml
-sunlint:pr:
-  stage: code-quality
-  rules:
-    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
-  script:
+# Pre-commit hook
+sunlint --all --staged-files --format=summary
 ```
 
 ## 📚 **Documentation**
 
-- **[Full Documentation](docs/)** - Complete guide and advanced features
-- **[AI Analysis Guide](docs/AI.md)** - AI-powered analysis setup
-- **[Debug Guide](docs/DEBUG.md)** - Debugging rules and CLI
+- [ESLint Integration Guide](./docs/ESLINT_INTEGRATION.md)
+- [CI/CD Guide](./docs/CI-CD-GUIDE.md)
+- [Architecture](./docs/ARCHITECTURE.md)
+- [Examples](./examples/README.md)
 
-## 📜 **License**
+## 🤝 **Contributing**
 
-MIT License - see [LICENSE](./LICENSE) for details.
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for development guidelines.
 
-## 🔗 **Links**
+## 📄 **License**
 
-- **Documentation**: [Sun Lint Docs](https://sunlint.docs.sun.com)
-- **Issues**: [GitHub Issues](https://github.com/sun-engineering/sunlint/issues)
-- **Changelog**: [CHANGELOG.md](./CHANGELOG.md)
+MIT License - see [LICENSE](./LICENSE) for details.
 
 ---
 
-**Built with ☀️ by Sun* Engineering Team**
+**Built with ❤️ by Sun* Engineering Team**