@sun-asterisk/sunlint

# SunLint Configuration Guide This document provides a comprehensive guide to all SunLint configuration options. ## 🏗️ Architecture Overview SunLint uses a **unified adapter pattern** for rule management, ensuring consistency between CLI and VSCode extension: ### Rule Access Architecture ``` CLI Tools → SunlintRuleAdapter → Rule Sources (Registry + Origin Rules) ↓ ↓ VSCode Extension → RuleReaderService → Rule Sources (Registry + Origin Rules) ``` ### Key Benefits - **Unified Rule Model**: Both CLI and extension use the same rule access pattern - **No Direct Parser Access**: All rule queries go through adapter layer - **AI Context Consistency**: OpenAI integration gets correct context from origin-rules - **Extensible**: Easy to add new rule sources or engines ### Rule Sources Priority 1. **Primary**: `config/rules/rules-registry-generated.json` (auto-generated from origin-rules) 2. **Fallback**: `origin-rules/*.md` files (direct markdown parsing) 3. **Cache**: Memory cache for performance optimization ## 📋 Quick Start Create `.sunlint.json` in your project root: ```json { "extends": "@sun/sunlint/recommended", "input": ["src"], "exclude": ["**/*.test.*", "**/*.generated.*"], "rules": { "C019": "error", "C006": "warn", "S005": "error" } } ``` ## 📖 Complete Configuration Reference Below is the full configuration schema with all available options and their descriptions: ```json { "//": "=== SunLint Full Configuration Example ===", "//": "Copy this configuration and customize as needed", "//extends": "Configuration preset to extend from", "extends": "@sun/sunlint/recommended", "//extends-options": [ "@sun/sunlint/recommended", "@sun/sunlint/security", "@sun/sunlint/quality", "@sun/sunlint/beginner", "@sun/sunlint/ci" ], "//engine": "Analysis engine selection (future-proof for multi-engine support)", "engine": "heuristic", "//engine-options": ["heuristic", "eslint", "ai"], "//input": "Default input paths when --input is not specified", "input": ["src", "lib"], "//include": "File patterns to include in analysis", "include": [ "src/**/*.{js,ts,jsx,tsx}", "lib/**/*.{js,ts,jsx,tsx}", "api/**/*.{js,ts}", "**/*.dart" ], "//exclude": "File patterns to exclude from analysis", "exclude": [ "**/*.test.*", "**/*.spec.*", "**/*.generated.*", "**/*.d.ts", "**/node_modules/**", "**/dist/**", "**/build/**", "**/.git/**", "**/coverage/**" ], "//languages": "Language-specific configurations", "languages": { "typescript": { "//": "TypeScript specific patterns and rules", "include": ["**/*.ts", "**/*.tsx"], "exclude": ["**/*.d.ts", "**/*.test.ts"], "rules": { "//": "Override rules for TypeScript files", "C006": "error", "C019": "warn" } }, "javascript": { "include": ["**/*.js", "**/*.jsx"], "exclude": ["**/*.test.js", "**/*.config.js"] }, "dart": { "include": ["**/*.dart"], "exclude": ["**/*.g.dart", "**/*.freezed.dart"] } }, "//testPatterns": "Test file specific configurations", "testPatterns": { "include": [ "**/*.test.*", "**/*.spec.*", "**/tests/**", "**/__tests__/**" ], "rules": { "//": "Rules often relaxed for test files", "C006": "off", "C007": "warn", "S012": "off" } }, "//rules": "Rule-specific configurations", "rules": { "//": "=== Quality Rules ===", "C005": "error", "//C005": "Single Responsibility Principle", "C006": "warn", "//C006": "Function Naming Conventions", "C007": "error", "//C007": "Comment Quality Standards", "C012": "warn", "//C012": "Command Query Separation", "C014": "error", "//C014": "Dependency Injection Patterns", "C015": "warn", "//C015": "Domain Language Usage", "C019": "error", "//C019": "Proper Log Level Usage", "C031": "error", "//C031": "Validation Separation", "C037": "warn", "//C037": "API Response Format Standards", "//": "=== Security Rules (sample - 43+ total) ===", "S001": "error", "//S001": "Fail Securely Access Control", "S002": "error", "//S002": "Prevent IDOR Vulnerabilities", "S005": "error", "//S005": "No Origin Header Authentication", "S007": "error", "//S007": "Secure OTP Storage", "S008": "error", "//S008": "Crypto Agility Requirements", "S012": "error", "//S012": "No Hardcoded Secrets", "S013": "error", "//S013": "Always Use TLS", "//": "Rule severity levels: 'error', 'warn', 'off'" }, "//output": "Output formatting and destination", "output": { "format": "summary", "//format-options": ["summary", "detailed", "json", "junit", "sarif"], "file": null, "//file-example": "reports/sunlint-report.json", "colors": true, "//": "Enable colorized output (auto-detected in CI)" }, "//git": "Git integration settings", "git": { "changedFiles": { "//": "Default branch for comparison", "baseBranch": "main", "includeUntracked": false, "includeStagedOnly": false }, "commitHooks": { "preCommit": true, "//": "Enable pre-commit validation", "failOnViolations": true } }, "//baseline": "Baseline comparison for CI/CD", "baseline": { "enabled": false, "file": ".sunlint-baseline.json", "//": "Store baseline violations to track new issues only", "updateOnPass": false }, "//performance": "Performance and analysis settings", "performance": { "maxFileSize": "5MB", "//": "Skip files larger than this size", "parallel": true, "//": "Enable parallel analysis (auto-detected based on CPU cores)", "timeout": 30000, "//": "Timeout per file in milliseconds" }, "//eslint": "ESLint integration settings", "eslint": { "enabled": false, "//": "Enable ESLint integration (--eslint-integration flag)", "configFile": null, "//configFile-example": ".eslintrc.js", "mergeReports": true, "//": "Merge ESLint violations with SunLint report" }, "//react": "React.js specific configuration", "react": { "version": "detect", "//": "React version for rule compatibility", "rules": { "R001": "error", "//R001": "Function Component Definition Style", "R002": "warn", "//R002": "Avoid Side Effects in Render", "R003": "error", "//R003": "No Direct State Mutation", "R004": "warn", "//R004": "Prefer Readonly Props", "R005": "warn", "//R005": "Avoid Function Binding in JSX", "R006": "error", "//R006": "Component Naming Conventions", "R007": "error", "//R007": "Proper Hook Usage", "R008": "warn", "//R008": "Effect Dependencies", "R009": "error" "//R009": "Conditional Hook Usage" } }, "//ai": "AI analysis settings (future feature)", "ai": { "enabled": false, "provider": "openai", "//provider-options": ["openai", "anthropic", "local"], "model": "gpt-4", "confidence": 0.8, "//": "Minimum confidence threshold for AI suggestions" }, "//debug": "Debug and development settings", "debug": { "verbose": false, "//": "Enable verbose logging", "timing": false, "//": "Show performance timing information", "dryRun": false, "//": "Show what would be analyzed without running" }, "//cache": "Analysis caching for performance", "cache": { "enabled": true, "//": "Enable analysis result caching", "directory": ".sunlint-cache", "ttl": 86400, "//": "Cache TTL in seconds (24 hours)" } } ``` ## 🚨 Migration Notes **BREAKING CHANGE**: `ignorePatterns` has been deprecated in favor of `exclude` for better consistency. **Migration:** - **Old:** `"ignorePatterns": ["**/*.test.*"]` - **New:** `"exclude": ["**/*.test.*"]` ## 📋 Configuration Presets ### 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 ### Engine Selection SunLint supports multiple analysis engines with automatic rule compatibility detection: - `heuristic` - SunLint's native pattern-based analysis engine (default) - **Coverage**: 244/256 rules (95.3%) - **Performance**: Fast, low memory usage - **Languages**: All supported languages - **Best for**: General analysis, CI/CD pipelines - `eslint` - ESLint-based analysis with automatic rule mapping - **Coverage**: 17/256 rules (6.6%) - **Performance**: Moderate, requires ESLint dependencies - **Languages**: JavaScript, TypeScript, JSX, TSX - **Best for**: Projects already using ESLint - `ai` - AI-powered analysis using OpenAI/LLMs - **Coverage**: 256/256 rules (100%) - **Performance**: Slower, requires API access - **Languages**: All supported languages - **Best for**: Complex context analysis, legacy code review ### Engine Architecture ``` Analysis Orchestrator ├── SunlintRuleAdapter (unified rule access) ├── Heuristic Engine (pattern matching) ├── ESLint Engine (integration layer) └── AI Engine (LLM integration) ``` **Auto-Engine Selection**: SunLint automatically selects the best engine for each rule based on compatibility and performance. ## 🎯 Common Configuration Examples ### Frontend Project ```json { "extends": "@sun/sunlint/recommended", "input": ["src"], "include": ["src/**/*.{js,ts,jsx,tsx}"], "exclude": ["**/*.test.*", "**/*.d.ts", "**/dist/**"], "languages": { "typescript": { "rules": { "C006": "error", "C019": "warn" } } } } ``` ### React.js Project ```json { "extends": "@sun/sunlint/recommended", "input": ["src"], "include": ["src/**/*.{js,ts,jsx,tsx}"], "exclude": ["**/*.test.*", "**/*.d.ts", "**/dist/**"], "react": { "version": "detect", "rules": { "R001": "error", "R002": "warn", "R003": "error", "R006": "error" } }, "eslint": { "enabled": true, "mergeReports": true } } ``` ### Backend API Project ```json { "extends": "@sun/sunlint/security", "input": ["src", "api"], "rules": { "S001": "error", "S005": "error", "S012": "error", "C031": "error" }, "git": { "changedFiles": { "baseBranch": "develop" } } } ``` ### CI/CD Optimized ```json { "extends": "@sun/sunlint/ci", "input": ["."], "exclude": ["**/node_modules/**", "**/dist/**", "**/*.test.*"], "output": { "format": "json", "file": "reports/sunlint-report.json" }, "baseline": { "enabled": true, "file": ".sunlint-baseline.json" } } ``` ## 🔧 ESLint Integration Setup SunLint can integrate with existing ESLint configurations for seamless adoption: ### Basic Setup 1. **Enable ESLint integration:** ```bash npx sunlint --eslint-integration --input=src ``` 2. **Configure in `.sunlint.json`:** ```json { "eslint": { "enabled": true, "mergeReports": true } } ``` ### React.js Integration For React projects, SunLint automatically maps React rules to ESLint equivalents: ```bash # Example: Analyze React components with both SunLint and ESLint rules npx sunlint --rules=R001,R002,R006 --eslint-integration --input=src ``` **Required dependencies:** ```bash npm install --save-dev \ eslint \ @typescript-eslint/parser \ @typescript-eslint/eslint-plugin \ eslint-plugin-react \ eslint-plugin-react-hooks ``` **Example `.eslintrc.js` for React:** ```javascript module.exports = { parser: '@typescript-eslint/parser', parserOptions: { ecmaVersion: 2020, sourceType: 'module', ecmaFeatures: { jsx: true } }, plugins: ['@typescript-eslint', 'react', 'react-hooks'], extends: [ 'eslint:recommended', 'plugin:react/recommended', 'plugin:react-hooks/recommended' ], settings: { react: { version: 'detect' } } }; ``` ### Rule Mapping SunLint automatically maps its rules to ESLint equivalents: | SunLint Rule | ESLint Rule(s) | Description | |--------------|----------------|-------------| | R001 | `react/function-component-definition` | Function component style | | R002 | `react-hooks/rules-of-hooks`, `react-hooks/exhaustive-deps` | Hook usage patterns | | R003 | `react/no-direct-mutation-state` | Prevent state mutation | | R006 | `react/jsx-pascal-case` | Component naming | ### Multi-Engine Orchestration SunLint intelligently selects the best engine for each rule: ```bash # Verbose output shows engine selection npx sunlint --rules=C010,R001,T003 --eslint-integration --verbose ``` Engine preferences: - **R*** rules: ESLint → Heuristic → AI - **C*** rules: Heuristic → ESLint → AI - **T*** rules: ESLint → Heuristic → AI ## 🚀 Performance & Architecture Benefits ### Adapter Pattern Benefits - **Unified Rule Access**: Both CLI and VSCode extension use the same adapter layer - **No Model Duplication**: Single rule model across all tools - **Memory Efficiency**: Singleton pattern prevents duplicate instances - **Fast Queries**: 0.07ms average per rule query with caching ### Rule Loading Performance - **Registry Loading**: 256 rules in ~10ms - **Memory Cache**: Rules cached after first load - **Fallback Support**: Automatic fallback to origin-rules if registry unavailable ### Engine Performance Comparison | Engine | Rules Coverage | Speed | Memory | Best Use Case | |--------|---------------|-------|---------|--------------| | Heuristic | 244/256 (95.3%) | Fast | Low | CI/CD, general analysis | | ESLint | 17/256 (6.6%) | Moderate | Medium | Existing ESLint projects | | AI | 256/256 (100%) | Slow | High | Complex analysis, legacy code | ### Architecture Validation ```bash # Test adapter performance and coverage npx sunlint --test-adapter # Show engine compatibility for specific rules npx sunlint --show-engines --rules=C010,R001,S005 # Verbose mode shows adapter and engine selection npx sunlint --verbose --rules=C010,C020 --input=src ``` ## 🔧 Development & Debugging ### Internal Architecture Access For development and debugging, SunLint exposes internal adapter methods: ```javascript // Access the rule adapter (for extensions or custom tools) const SunlintRuleAdapter = require('@sun/sunlint/core/adapters/sunlint-rule-adapter'); const adapter = SunlintRuleAdapter.getInstance(); await adapter.initialize(); // Get all rules with metadata const allRules = adapter.getAllRules(); // Generate AI context for specific rules const aiContext = adapter.generateAIContext(['C010', 'C020']); // Check engine compatibility const heuristicRules = adapter.getRulesByEngine('heuristic'); ``` ### VSCode Extension Integration The SunLint VSCode extension uses the same adapter pattern via `RuleReaderService`, ensuring complete consistency between CLI and editor experience.