☀️ Sun Lint - Universal Coding Standards

Multi-rule, Multi-language Code Quality & Security Analysis Tool with ESLint Integration

🎯 Overview

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

• ✅ 256+ Coding Rules: Quality (161), Security (70), Performance (25)
• ✅ Unified Architecture: Same adapter pattern for CLI and VSCode extension
• ✅ Multi-Engine Support: Heuristic v4.0 (244 rules) + ESLint (17 rules) + AI (256 rules)
• ✅ Performance Optimized: Auto file limits, memory management, GitHub Actions ready
• ✅ Built-in AST Analysis: JavaScript/TypeScript parsing out of the box
• ✅ Git Integration: --changed-files, --staged-files, --pr-mode
• ✅ TypeScript Support: Native TypeScript 5.8+ analysis with smart memory limits
• ✅ Zero Config: Works immediately after npm install
• ✅ CI/CD Ready: Baseline comparison, fail-on-new-violations, timeout protection
• ✅ Advanced File Targeting: Include/exclude patterns, language filtering
• ✅ Quality Scoring System: Automated quality score (0-100) with grade (A+ to F)
• ✅ Summary Reports: JSON format for CI/CD dashboards and management reports

🏗️ Architecture

SunLint uses a unified adapter pattern ensuring consistency between CLI and VSCode extension:

┌─────────────────┬─────────────────┐
│   CLI Tools     │ VSCode Extension│
├─────────────────┼─────────────────┤
│ SunlintRule     │ RuleReader      │
│ Adapter         │ Service         │
├─────────────────┴─────────────────┤
│     Rule Sources & Engines        │
│ • Registry (auto-generated)       │
│ • Origin Rules (markdown)         │
│ • Heuristic Engine (244 rules)    │
│ • ESLint Engine (17 rules)        │
│ • OpenAI Engine (256 rules)       │
└───────────────────────────────────┘

Benefits:

• No Rule Model Duplication: Single source of truth
• Extensible: Easy to add new engines or rule sources
• Performance: 0.07ms average per rule query
• AI Integration: Consistent OpenAI context from origin-rules

🚀 Quick Start

# Install
npm install -g @sun-asterisk/sunlint

# Basic usage - works immediately!
sunlint --all
sunlint --rules=C019,C006

# With input specification  
sunlint --all --input=src
sunlint --rules=C019,C006 --input=src
sunlint --quality --input=src
sunlint --security --input=src

# ESLint integration (requires eslint dependency)
sunlint --rules=C010,C006 --eslint-integration --input=src

# Git integration  
sunlint --all --changed-files

# Quality scoring and summary report (for CI/CD)
sunlint --all --input=src --output-summary=quality-report.json

📊 Quality Scoring & Summary Reports 🆕

Generate comprehensive quality reports with automated scoring for CI/CD integration and management dashboards.

Features

• Quality Score (0-100): Calculated based on violations, LOC, and rules checked
• Grade System: A+ to F grade for easy interpretation
• JSON Format: Ready for CI/CD pipelines and dashboard integration
• Git Integration: Automatically includes repository info, branch, and commit hash
• Metrics: Violations per KLOC, errors/warnings count, LOC analysis

Quick Usage

# Generate summary report
sunlint --all --input=src --output-summary=quality.json

# Both detailed and summary reports
sunlint --all --input=src --output=detailed.txt --output-summary=quality.json

# In GitHub Actions (auto-detects git info)
sunlint --all --input=src --output-summary=quality.json

Example Output

{
  "quality": {
    "score": 92.6,
    "grade": "A",
    "metrics": {
      "errors": 0,
      "warnings": 39,
      "linesOfCode": 4954,
      "violationsPerKLOC": 7.9
    }
  },
  "violations": {
    "total": 39,
    "by_rule": [
      { "rule_code": "C065", "count": 39 }
    ]
  },
  "repository": {
    "repository_url": "https://github.com/org/repo",
    "branch": "main",
    "commit_hash": "abc123"
  }
}

📚 Full Documentation: See docs/QUALITY_SCORING_GUIDE.md for:

• Scoring formula and interpretation
• CI/CD integration examples (GitHub Actions, GitLab CI)
• Dashboard integration
• Quality gate setup
• Trending analysis

📦 Installation

Global Installation (Recommended)

npm install -g @sun-asterisk/sunlint
sunlint --version

Project Installation

npm install --save-dev @sun-asterisk/sunlint

✅ Works immediately with JavaScript analysis using built-in AST parsers (@babel/parser, espree)

Enhanced TypeScript Support

For advanced TypeScript analysis with ESLint integration:

npm install --save-dev @sun-asterisk/sunlint eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin typescript

Full ESLint Integration Support

For complete ESLint integration with import analysis:

npm install --save-dev @sun-asterisk/sunlint eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint-plugin-import typescript

What's Included by Default

• ✅ JavaScript Analysis: High-accuracy AST analysis out of the box
• ✅ Basic TypeScript: Works with built-in Babel parser
• ✅ 256+ Rules: All quality and security rules available
• ✅ Heuristic Engine: Pattern-based analysis for all languages

Optional Dependencies (Install as needed)

# For ESLint engine integration
npm install eslint --save-dev

# For import/module analysis (recommended with ESLint)
npm install eslint-plugin-import --save-dev

# For enhanced TypeScript analysis  
npm install @typescript-eslint/parser @typescript-eslint/eslint-plugin --save-dev

# For TypeScript compiler integration
npm install typescript --save-dev

# For import/module analysis (recommended)
npm install eslint-plugin-import --save-dev

Quick setup for TypeScript projects:

npm install --save-dev @sun-asterisk/sunlint eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint-plugin-import typescript

💡 Note: SunLint gracefully handles missing dependencies. Install only what your project needs. See docs/DEPENDENCIES.md for detailed guidance.

Package.json scripts

{
  "scripts": {
    "lint": "sunlint --all --input=src",
    "lint:changed": "sunlint --all --changed-files",
    "lint:typescript": "sunlint --all --input=src",
    "lint:eslint-integration": "sunlint --all --eslint-integration --input=src"
  },
  "devDependencies": {
    "@sun-asterisk/sunlint": "^1.2.0"
  }
}

For TypeScript projects, add:

{
  "devDependencies": {
    "@sun-asterisk/sunlint": "^1.2.0",
    "eslint": "^8.50.0",
    "@typescript-eslint/parser": "^7.2.0",
    "@typescript-eslint/eslint-plugin": "^7.18.0",
    "eslint-plugin-import": "^2.32.0",
    "typescript": "^5.0.0"
  }
}

🔗 Multi-Engine Architecture

SunLint automatically selects the best engine for each rule, providing comprehensive coverage:

Engine Coverage & Performance

# Show engine compatibility for specific rules
sunlint --show-engines --rules=C010,R001,S005

# Use specific engine
sunlint --engine=heuristic --rules=C010,C020 --input=src
sunlint --engine=eslint --rules=R001,R006 --input=src  
sunlint --engine=openai --rules=C010,S001 --input=src

Engine Stats:

• Heuristic Engine: 244/256 rules (95.3%) - Fast, universal
• ESLint Engine: 17/256 rules (6.6%) - JavaScript/TypeScript focused
• OpenAI Engine: 256/256 rules (100%) - Context-aware analysis

ESLint Integration

Seamlessly integrate with existing ESLint configurations:

# Analyze with both SunLint + existing ESLint rules  
sunlint --all --eslint-integration --input=src

# Mix ESLint and heuristic engines based on rule compatibility
sunlint --rules=C010,C006 --eslint-integration --input=src

✅ Current Status:

• ✅ Multi-engine orchestration: Rules automatically routed to optimal engine
• ✅ ESLint v8/v9 compatibility: Production-ready with both major versions
• ✅ TypeScript support: Full TS/TSX parsing with custom rule implementation
• ✅ Custom rule integration: 17+ SunLint custom rules via ESLint engine
• ✅ Smart fallback: Automatic engine fallback for maximum rule coverage
• ✅ Production tested: Successfully processes real projects with mixed violations

Benefits:

• ✅ No workflow disruption: Existing ESLint continues working
• ✅ Engine flexibility: Automatic best-engine selection per rule
• ✅ Combined reporting: Unified violation tracking from multiple engines
• ✅ Adapter Pattern: Same rule access layer as VSCode extension

🔀 Git Integration

Optimize CI/CD workflows with Git integration:

# Analyze only changed files
sunlint --all --changed-files

# Pre-commit validation
sunlint --all --staged-files

# PR mode with failure only on new violations
sunlint --all --pr-mode --fail-on-new-violations

🎯 Advanced File Targeting

Powerful file targeting capabilities:

# Include specific patterns
sunlint --all --include="src/**/*.ts,lib/**/*.dart" --input=.

# Exclude patterns  
sunlint --all --exclude="**/*.test.*,**/*.generated.*" --input=src

# Language filtering
sunlint --all --languages=typescript,dart --input=src

# Source files only (exclude tests, configs)
sunlint --all --only-source --input=src

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

📋 Available Rules

Quality Rules ✨ (30 rules)

| Rule ID | Name | Status | |---------|------|--------| | C002 | No Duplicate Code | ✅ Stable | | C003 | No Vague Abbreviations | ✅ Stable | | C006 | Function Naming Convention | ✅ Stable | | C010 | Limit Block Nesting | ✅ Stable | | C013 | No Dead Code | ✅ Stable | | C014 | Dependency Injection | ✅ Stable | | C017 | Limit Constructor Logic | ✅ Stable | | C018 | No Generic Throw | ✅ Stable | | C019 | Log Level Usage | ✅ Stable | | C023 | No Duplicate Variable Names | ✅ Stable | | C029 | Catch Block Logging | ✅ Stable | | C030 | Use Custom Error Classes | ✅ Stable | | C031 | Validation Separation | ✅ Stable | | C041 | No Hardcoded Config | ✅ Stable | | C042 | Boolean Name Prefix | ✅ Stable | | C043 | No Console or Print | ✅ Stable | | C047 | No Duplicate Retry Logic | ✅ Stable | | C075 | Explicit Function Return Types | ✅ Stable | | T002-T021 | TypeScript-specific rules | ✅ Stable |

Security Rules 🔒 (47 rules)

| Rule ID | Name | Status | |---------|------|--------| | S001 | Fail Securely Access Control | ✅ Stable | | S002 | Prevent IDOR Vulnerabilities | ✅ Stable | | S003 | URL Redirect Validation | ✅ Stable | | S005 | No Origin Header Authentication | ✅ Stable | | S006 | Activation Recovery Not Plaintext | ✅ Stable | | S007 | Secure OTP Storage | ✅ Stable | | S008 | Crypto Agility | ✅ Stable | | S009 | No Insecure Crypto | ✅ Stable | | S010 | Secure Random Generation | ✅ Stable | | S011 | Secure UUID Generation | ✅ Stable | | S012 | No Hardcoded Secrets | ✅ Stable | | S013 | Always Use TLS | ✅ Stable | | S014 | Secure TLS Version | ✅ Stable | | S015 | Valid TLS Certificate | ✅ Stable | | S016-S058 | ...Additional security rules | ✅ Stable |

⚙️ Configuration

Create .sunlint.json in your project root:

Quick Start Configuration

{
  "extends": "@sun/sunlint/recommended",
  "input": ["src"],
  "exclude": ["**/*.test.*", "**/*.generated.*"],
  "rules": {
    "C019": "error",
    "C006": "warn", 
    "S005": "error"
  }
}

Available Presets

• @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

Full Configuration Reference

📖 View Complete Configuration Guide

Complete reference with all available options:

• File targeting (include, exclude, languages)
• Rule configurations with detailed descriptions
• Git integration settings (changedFiles, baseline)
• ESLint integration options
• Performance and caching settings
• CI/CD optimizations

🚨 MIGRATION NOTE: ignorePatterns is deprecated. Use exclude instead. Run npx sunlint migrate-config to auto-migrate.

🎮 Usage Examples

Development

# Quick start - works immediately
npm install --save-dev @sun-asterisk/sunlint
npx sunlint --all --input=src

# Check specific rules
sunlint --rules=C019,S005 --input=src

# ESLint integration (requires eslint dependency)
npm install --save-dev eslint
sunlint --all --eslint-integration --changed-files

TypeScript Projects

# Enhanced TypeScript setup
npm install --save-dev @sun-asterisk/sunlint eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin typescript

# Full TypeScript analysis
sunlint --all --input=src
sunlint --all --eslint-integration --input=src

CI/CD

# Full project scan
sunlint --all --input=. --format=json --output=report.json

# PR validation
sunlint --all --changed-files --fail-on-new-violations

# Pre-commit hook  
sunlint --all --staged-files --format=summary

Testing & Debugging

# Test adapter performance and coverage
sunlint --test-adapter

# Show detailed engine information
sunlint --show-engines --verbose

# Debug rule selection process
sunlint --rules=C010,R001 --verbose --debug

# Validate configuration
sunlint --validate-config .sunlint.json

📚 Documentation

• Configuration Guide - Complete config options with examples
• Performance & File Limits - Understanding --max-files vs --max-semantic-files
• ESLint Integration Guide
• CI/CD Guide
• Architecture
• Examples

🤝 Contributing

See CONTRIBUTING.md for development guidelines.

📄 License

MIT License - see LICENSE for details.

Built with ❤️ by Sun Engineering Team*