@sun-asterisk/sunlint 1.2.2 → 1.3.1

package/docs/CONSTANTS-ARCHITECTURE.md

@@ -0,0 +1,288 @@
+# SunLint Constants Architecture
+
+## Overview
+
+SunLint now uses a centralized constants sub-package located at `core/constants/` to manage all constants and configuration values. This improves code organization, maintainability, and extensibility.
+
+## Structure
+
+```
+core/
+  constants/
+    categories.js    # Category-principle mappings and functions
+    defaults.js      # Default configurations and values  
+    engines.js       # Engine capabilities and configurations
+    rules.js         # Rule-related constants and utilities
+    index.js         # Barrel export for all constants
+```
+
+## Migration Guide
+
+### Before (Old approach)
+```javascript
+// Scattered constants across multiple files
+const { getValidCategories } = require('./core/category-constants');
+const defaultRules = ['C006', 'C019']; // Hardcoded in various files
+const SUPPORTED_ENGINES = { /* scattered */ };
+```
+
+### After (New centralized approach)
+```javascript
+// Option 1: Import specific module
+const { getValidCategories } = require('./core/constants/categories');
+const { getDefaultRuleSet } = require('./core/constants/defaults');
+const { SUPPORTED_ENGINES } = require('./core/constants/engines');
+
+// Option 2: Import from barrel export
+const { 
+  getValidCategories, 
+  getDefaultRuleSet, 
+  SUPPORTED_ENGINES 
+} = require('./core/constants');
+
+// Option 3: Import entire module
+const constants = require('./core/constants');
+const categories = constants.getValidCategories();
+```
+
+## Modules
+
+### 1. Categories (`core/constants/categories.js`)
+
+**Purpose**: Category-principle mappings, validation, and normalization.
+
+**Key Exports**:
+```javascript
+// Constants
+SUNLINT_PRINCIPLES       // Object with all principle constants
+CATEGORY_PRINCIPLE_MAP   // Category to principle mapping
+CATEGORY_DESCRIPTIONS    // Human-readable descriptions
+
+// Functions
+getValidCategories()     // Get all valid categories
+getCategoryPrinciples(category)  // Get principles for category
+isValidCategory(category)        // Validate category
+normalizeCategory(category)      // Normalize and validate
+getCategoryStats()              // Get statistics
+```
+
+**Example Usage**:
+```javascript
+const { getValidCategories, normalizeCategory } = require('./core/constants/categories');
+
+const validCategories = getValidCategories();
+// ['security', 'quality', 'performance', ...]
+
+const normalized = normalizeCategory('QUALITY');
+// 'quality'
+```
+
+### 2. Defaults (`core/constants/defaults.js`)
+
+**Purpose**: Default configurations, rule sets, and standard values.
+
+**Key Exports**:
+```javascript
+// Constants
+DEFAULT_RULE_SETS        // Predefined rule sets (MINIMAL, ESSENTIAL, etc.)
+DEFAULT_CONFIG          // Default configuration object
+DEFAULT_SEVERITIES      // Severity levels
+DEFAULT_TIMEOUTS        // Timeout configurations
+DEFAULT_LIMITS          // File size and processing limits
+
+// Functions
+getDefaultRuleSet(name)     // Get predefined rule set
+getDefaultConfig(overrides) // Get configuration with overrides
+getLanguageExtensions(lang) // Get file extensions for language
+isFileSizeValid(size)      // Check file size limits
+```
+
+**Example Usage**:
+```javascript
+const { getDefaultRuleSet, getDefaultConfig } = require('./core/constants/defaults');
+
+const essentialRules = getDefaultRuleSet('ESSENTIAL');
+// ['C001', 'C002', 'C003', ...]
+
+const config = getDefaultConfig({ verbose: true });
+// { verbose: true, useRegistry: true, ... }
+```
+
+### 3. Engines (`core/constants/engines.js`)
+
+**Purpose**: Engine capabilities, configurations, and language support.
+
+**Key Exports**:
+```javascript
+// Constants
+SUPPORTED_ENGINES       // Object with all supported engines
+ENGINE_CAPABILITIES     // Engine features and language support
+ENGINE_MODES           // Execution modes (sequential, parallel, etc.)
+ENGINE_PERFORMANCE     // Performance characteristics
+
+// Functions
+getEngineLanguages(engine)      // Get supported languages
+getEnginesForLanguage(language) // Get engines for language
+getRecommendedEngine(language)  // Get best engine for language
+isLanguageSupported(engine, lang) // Check support
+getEnginePerformance(engine)    // Get performance info
+```
+
+**Example Usage**:
+```javascript
+const { getEnginesForLanguage, getRecommendedEngine } = require('./core/constants/engines');
+
+const jsEngines = getEnginesForLanguage('javascript');
+// [{ name: 'heuristic', priority: 1, features: [...] }, ...]
+
+const recommended = getRecommendedEngine('typescript');
+// 'heuristic'
+```
+
+### 4. Rules (`core/constants/rules.js`)
+
+**Purpose**: Rule-related constants, metadata, and utilities.
+
+**Key Exports**:
+```javascript
+// Constants
+RULE_SEVERITIES         // Severity levels (ERROR, WARNING, etc.)
+RULE_STATUS            // Execution status values
+RULE_TYPES             // Analysis types (HEURISTIC, AST, etc.)
+RULE_SCOPES            // Operation scopes (FILE, PROJECT, etc.)
+RULE_LANGUAGE_PATTERNS // Regex patterns for rule IDs
+RULE_TIMEOUTS          // Timeout values by rule type
+
+// Functions
+getLanguageFromRuleId(ruleId)   // Extract language from rule ID
+isValidRuleId(ruleId)          // Validate rule ID format
+getRuleTimeout(type)           // Get timeout for rule type
+getDefaultRuleMetadata(overrides) // Get rule metadata template
+isValidSeverity(severity)      // Validate severity level
+```
+
+**Example Usage**:
+```javascript
+const { getLanguageFromRuleId, isValidRuleId } = require('./core/constants/rules');
+
+const language = getLanguageFromRuleId('C001');
+// 'common'
+
+const isValid = isValidRuleId('CUSTOM_RULE');
+// true
+```
+
+## Backward Compatibility
+
+The following files are maintained for backward compatibility but are deprecated:
+
+- `core/category-constants.js` - Proxies to `core/constants/categories.js`
+- `core/categories.js` - Proxies to `core/constants/categories.js`
+
+**Migration Path**:
+1. Update imports to use `core/constants/*` directly
+2. Replace deprecated file imports gradually
+3. Legacy files will be removed in future versions
+
+## Benefits
+
+### 1. **Better Organization**
+- Related constants grouped together
+- Clear separation of concerns
+- Easier to locate and modify constants
+
+### 2. **Improved Maintainability**
+- Single source of truth for each type of constant
+- Centralized documentation and examples
+- Easier to add new constants or modify existing ones
+
+### 3. **Enhanced Extensibility**
+- Modular structure supports new constant types
+- Barrel export provides flexible import options
+- Framework for adding new engines, rules, categories
+
+### 4. **Developer Experience**
+- Clearer imports with specific module names
+- Better IDE support and autocomplete
+- Self-documenting code structure
+
+## Best Practices
+
+### 1. **Import Strategy**
+```javascript
+// ✅ Good: Import specific functions
+const { getValidCategories, normalizeCategory } = require('./core/constants/categories');
+
+// ✅ Good: Import from barrel for multiple modules
+const { getValidCategories, getDefaultRuleSet } = require('./core/constants');
+
+// ❌ Avoid: Importing entire modules unnecessarily
+const allConstants = require('./core/constants');
+```
+
+### 2. **Adding New Constants**
+```javascript
+// Add to appropriate module (e.g., categories.js)
+const NEW_CATEGORY_FEATURE = 'new-feature';
+
+// Export in module
+module.exports = {
+  NEW_CATEGORY_FEATURE,
+  // ... other exports
+};
+
+// Update barrel export (index.js) if needed
+```
+
+### 3. **Extending Functionality**
+```javascript
+// Add utility functions to appropriate modules
+function getAdvancedCategoryInfo(category) {
+  // Implementation
+}
+
+// Export with other functions
+module.exports = {
+  // ... existing exports
+  getAdvancedCategoryInfo
+};
+```
+
+## Testing
+
+Each constants module includes comprehensive tests:
+
+```bash
+# Test entire constants structure
+node test-constants-structure.js
+
+# Test backward compatibility
+node test-centralized-categories.js
+```
+
+## Future Enhancements
+
+### Planned Features
+1. **Dynamic Configuration Loading** - Load constants from external files
+2. **Environment-specific Constants** - Different values for dev/prod
+3. **Validation Schemas** - JSON Schema validation for all constants
+4. **Hot Reloading** - Update constants without restarting
+
+### Extension Points
+- Add new constant modules (e.g., `integrations.js`, `plugins.js`)
+- Extend barrel export for new modules
+- Add validation functions for new constant types
+
+---
+
+## Quick Reference
+
+| Module | Purpose | Key Functions |
+|--------|---------|---------------|
+| `categories.js` | Category management | `getValidCategories()`, `normalizeCategory()` |
+| `defaults.js` | Default values | `getDefaultConfig()`, `getDefaultRuleSet()` |
+| `engines.js` | Engine configuration | `getEnginesForLanguage()`, `getRecommendedEngine()` |
+| `rules.js` | Rule utilities | `getLanguageFromRuleId()`, `isValidRuleId()` |
+| `index.js` | Barrel export | All functions from all modules |
+
+For detailed API documentation, see the JSDoc comments in each module file.

package/docs/LARGE-PROJECT-GUIDE.md

@@ -0,0 +1,324 @@
+# 🏗️ Large Project Analysis Guide
+
+> **For projects with 1000+ files**: Complete strategies to optimize SunLint performance while maintaining comprehensive analysis coverage.
+
+## 📊 Overview
+
+SunLint uses **semantic analysis** for advanced rules like `C047` (retry pattern detection). For large projects, you can control the scope of semantic analysis to balance accuracy vs performance.
+
+### 🎯 Key Benefits
+
+- **Configurable file limits**: Control memory usage and analysis time
+- **Smart defaults**: Automatic optimization for different project sizes  
+- **Multiple strategies**: Choose the best approach for your workflow
+- **Full coverage options**: Ensure no violations are missed
+
+## ⚙️ Configuration Options
+
+### CLI Option: `--max-semantic-files`
+
+Controls how many files are loaded for semantic analysis:
+
+```bash
+# Default behavior (auto-detect)
+node cli.js --all --input=.
+
+# Conservative analysis (500 files)
+node cli.js --all --input=. --max-semantic-files=500
+
+# Balanced analysis (1000 files - default)  
+node cli.js --all --input=. --max-semantic-files=1000
+
+# Comprehensive analysis (2000 files)
+node cli.js --all --input=. --max-semantic-files=2000
+
+# Unlimited analysis (all files)
+node cli.js --all --input=. --max-semantic-files=-1
+
+# Disable semantic analysis (heuristic only)
+node cli.js --all --input=. --max-semantic-files=0
+```
+
+### 📋 Recommended Limits by Project Size
+
+| Project Size | Files Count | Recommended Limit | Memory Usage | Analysis Time |
+|-------------|-------------|-------------------|--------------|---------------|
+| **Small** | < 100 files | `0` (all files) | Low | Fast |
+| **Medium** | 100-500 files | `500` | Medium | Medium |
+| **Large** | 500-2000 files | `1000` ⭐ | Medium-High | Medium |
+| **Enterprise** | 2000-5000 files | `1500` | High | Slow |
+| **Massive** | 5000+ files | `500-1000` | Controlled | Reasonable |
+
+⭐ **Default recommended setting**
+
+## 🚀 Analysis Strategies
+
+### Strategy 1: Incremental Development
+
+Perfect for daily development work:
+
+```bash
+# Focus on changed files only (fastest)
+node cli.js --all --changed-files --max-semantic-files=300 --format=summary
+
+# Target specific modules  
+node cli.js --all --input=src/auth --max-semantic-files=1000 --format=summary
+node cli.js --all --input=src/api --max-semantic-files=1000 --format=summary
+
+# Use file patterns to focus on critical code
+node cli.js --all --include="src/**/*.ts" --exclude="**/*.test.*" --max-semantic-files=1500
+```
+
+### Strategy 2: CI/CD Pipeline Optimization
+
+Optimize for different CI stages:
+
+```bash
+# PR checks: Fast semantic analysis
+node cli.js --all --changed-files --max-semantic-files=300 --format=github --no-ai
+
+# Nightly builds: Medium coverage  
+node cli.js --all --input=. --max-semantic-files=1000 --format=json --output=nightly.json
+
+# Weekly reports: Comprehensive analysis
+node cli.js --all --input=. --max-semantic-files=-1 --format=detailed --output=weekly.json
+
+# Release validation: Full coverage with baseline
+node cli.js --all --input=. --max-semantic-files=2000 --baseline=last-release.json
+```
+
+### Strategy 3: Rule-Based Prioritization
+
+Different limits for different rule types:
+
+```bash
+# Phase 1: Critical security (fast heuristic rules)
+node cli.js --security --input=. --max-semantic-files=0 --format=summary
+
+# Phase 2: Code quality basics
+node cli.js --rules=C006,C019,C029 --input=. --max-semantic-files=500 --format=summary
+
+# Phase 3: Advanced semantic rules (targeted)
+node cli.js --rules=C047 --input=src --max-semantic-files=1000 --format=summary
+
+# Phase 4: Full comprehensive scan
+node cli.js --all --input=. --max-semantic-files=-1 --format=detailed
+```
+
+### Strategy 4: Monorepo Management
+
+For large monorepos with multiple packages:
+
+```bash
+# Analyze each package separately
+for package in packages/*/; do
+  node cli.js --all --input="$package" --max-semantic-files=1000 \
+    --format=json --output="${package//\//-}-report.json"
+done
+
+# Focus on core packages first
+node cli.js --all --input=packages/core --max-semantic-files=2000 --format=summary
+node cli.js --all --input=packages/api --max-semantic-files=1500 --format=summary
+node cli.js --all --input=packages/ui --max-semantic-files=1000 --format=summary
+
+# Changed files across the entire monorepo
+node cli.js --all --changed-files --max-semantic-files=500 --format=summary
+```
+
+## 📈 Performance Monitoring
+
+### Memory & Time Tracking
+
+```bash
+# Monitor performance with different limits
+time node cli.js --all --input=. --max-semantic-files=500 --format=summary
+time node cli.js --all --input=. --max-semantic-files=1000 --format=summary  
+time node cli.js --all --input=. --max-semantic-files=2000 --format=summary
+
+# Memory-conscious analysis for CI
+node cli.js --all --input=. --max-semantic-files=300 --max-concurrent=2 --format=summary
+
+# Debug file loading behavior
+node cli.js --all --input=. --max-semantic-files=1000 --verbose --debug
+```
+
+### Coverage Analysis
+
+Check what percentage of your project is being analyzed:
+
+```bash
+# Show file loading statistics
+node cli.js --all --input=. --max-semantic-files=1000 --verbose --format=summary
+
+# Compare different limits
+node cli.js --all --input=. --max-semantic-files=500 --verbose --dry-run
+node cli.js --all --input=. --max-semantic-files=1000 --verbose --dry-run
+node cli.js --all --input=. --max-semantic-files=-1 --verbose --dry-run
+```
+
+## 🎛️ Configuration Files
+
+### sunlint.config.json
+
+Create a configuration file for consistent settings:
+
+```json
+{
+  "performance": {
+    "maxSemanticFiles": 1000,
+    "maxConcurrentRules": 5,
+    "timeoutMs": 30000
+  },
+  "input": ["src", "lib"],
+  "exclude": [
+    "**/*.test.*",
+    "**/*.d.ts", 
+    "**/generated/**"
+  ],
+  "output": {
+    "format": "summary"
+  },
+  "engines": {
+    "semantic": {
+      "enabled": true,
+      "fileLimit": 1000
+    }
+  }
+}
+```
+
+### Environment-Specific Configs
+
+Different configs for different environments:
+
+```bash
+# Development (fast feedback)
+cp config/sunlint.dev.json sunlint.config.json
+node cli.js --all --input=.
+
+# CI (balanced coverage)  
+cp config/sunlint.ci.json sunlint.config.json
+node cli.js --all --changed-files
+
+# Release (comprehensive)
+cp config/sunlint.release.json sunlint.config.json  
+node cli.js --all --input=.
+```
+
+## 💡 Best Practices
+
+### 1. Start Conservative, Scale Up
+
+```bash
+# Begin with conservative limits
+node cli.js --all --input=. --max-semantic-files=500 --format=summary
+
+# Gradually increase if performance allows
+node cli.js --all --input=. --max-semantic-files=1000 --format=summary
+node cli.js --all --input=. --max-semantic-files=1500 --format=summary
+```
+
+### 2. Use Different Limits for Different Contexts
+
+```bash
+# Daily development: Focus on changed files
+alias sunlint-dev="node cli.js --all --changed-files --max-semantic-files=300"
+
+# Code review: Medium coverage
+alias sunlint-review="node cli.js --all --changed-files --max-semantic-files=500"
+
+# Release preparation: Full coverage
+alias sunlint-release="node cli.js --all --input=. --max-semantic-files=-1"
+```
+
+### 3. Monitor and Adjust
+
+Track your analysis performance over time:
+
+```bash
+# Create performance baseline
+echo "Project size: $(find . -name '*.ts' -o -name '*.js' | wc -l) files"
+time node cli.js --all --input=. --max-semantic-files=1000 --format=summary
+
+# Adjust based on CI constraints
+if [[ $CI_MEMORY_LIMIT -lt 4096 ]]; then
+  SEMANTIC_LIMIT=500
+else
+  SEMANTIC_LIMIT=1000
+fi
+
+node cli.js --all --input=. --max-semantic-files=$SEMANTIC_LIMIT --format=summary
+```
+
+### 4. Combine with File Targeting
+
+Use semantic limits together with file patterns:
+
+```bash
+# Focus semantic analysis on source files only
+node cli.js --all --include="src/**/*.ts" --exclude="**/*.test.*" --max-semantic-files=1500
+
+# Analyze tests separately with lower limits
+node cli.js --all --include="**/*.test.*" --max-semantic-files=500
+
+# Target critical modules with higher limits
+node cli.js --all --input=src/security --max-semantic-files=2000
+node cli.js --all --input=src/api --max-semantic-files=1500
+```
+
+## 🔍 Troubleshooting
+
+### Memory Issues
+
+If you encounter out-of-memory errors:
+
+```bash
+# Reduce semantic file limit
+node cli.js --all --input=. --max-semantic-files=500
+
+# Disable semantic analysis completely
+node cli.js --all --input=. --max-semantic-files=0
+
+# Reduce concurrent rules
+node cli.js --all --input=. --max-semantic-files=1000 --max-concurrent=2
+```
+
+### Slow Analysis
+
+If analysis takes too long:
+
+```bash
+# Use incremental analysis
+node cli.js --all --changed-files --max-semantic-files=300
+
+# Focus on specific directories
+node cli.js --all --input=src/critical --max-semantic-files=1000
+
+# Use timeout limits
+node cli.js --all --input=. --max-semantic-files=1000 --timeout=60000
+```
+
+### Missed Violations
+
+If you suspect violations are being missed:
+
+```bash
+# Run comprehensive analysis periodically
+node cli.js --all --input=. --max-semantic-files=-1 --format=detailed
+
+# Compare different limits
+node cli.js --all --input=. --max-semantic-files=1000 --output=report-1k.json
+node cli.js --all --input=. --max-semantic-files=-1 --output=report-full.json
+diff report-1k.json report-full.json
+```
+
+## 📚 Related Documentation
+
+- [Command Examples](./COMMAND-EXAMPLES.md) - Complete CLI usage examples
+- [Configuration Guide](./CONFIGURATION.md) - Detailed configuration options
+- [CI/CD Guide](./CI-CD-GUIDE.md) - Integration with CI/CD pipelines
+- [Architecture](./ARCHITECTURE.md) - Technical implementation details
+
+---
+
+**💡 Pro Tip**: For projects with 2000+ files, consider breaking analysis into modules and running them in parallel, rather than analyzing everything at once.