@sun-asterisk/sunlint 1.3.10 → 1.3.12

package/CHANGELOG.md

@@ -2,7 +2,105 @@
 
 ---
 
-## 🔧 **v1.3.9 - File Targeting Regression Fix (October 2, 2025)**
+## � **v1.4.0 - Quality Scoring & Summary Reports (October 7, 2025)**
+
+**Release Date**: October 7, 2025  
+**Type**: Major Feature Release  
+**Branch**: `fix.sunlint.cli_options`
+
+### ✨ **Major Features**
+
+#### **Quality Scoring System** 🎯
+- **NEW**: Automated quality score calculation (0-100) based on violations, LOC, and rules checked
+- **NEW**: Grade system (A+ to F) for easy quality interpretation
+- **Formula**: `Score = 100 - (errors × 5 + warnings × 1) × (1000 / LOC) + (rules × 0.5)`
+- **Normalization**: Violations normalized per 1000 lines of code (KLOC)
+- **Bonus System**: Up to 10 points bonus for comprehensive rule coverage
+
+#### **Summary Report Generation** 📊
+- **NEW**: `--output-summary <file>` option for API-compatible JSON summary reports
+- **Format**: Direct dashboard API compatibility - **no transformation needed!**
+- **Git Integration**: Auto-detects complete repository and commit information
+  - Repository: URL, name, project path (mono-repo support)
+  - Commit: hash, message, author name, author email
+  - PR tracking: Automatic PR number extraction from commit messages/branch names
+- **Environment Variables**: Full GitHub Actions support
+  - `GITHUB_REPOSITORY`, `GITHUB_REF_NAME`, `GITHUB_SHA`
+  - `GITHUB_EVENT_PATH` for commit details
+  - Automatic fallback to git commands if env vars unavailable
+- **Mono-Repo Support**: Automatic `project_path` detection for multi-project repositories
+- **Violation Summary**: Aggregated violations by rule with count and severity
+- **Metrics**: LOC, files analyzed, violations per KLOC, errors/warnings breakdown
+- **API-Ready**: Flat structure format ready for direct POST to dashboard APIs
+
+#### **New Services** 🛠️
+- **ScoringService**: Calculate quality scores with customizable weights
+  - Error penalty: -5 points
+  - Warning penalty: -1 point
+  - Rule bonus: +0.5 points (max 10)
+  - LOC normalization factor: 0.001
+- **SummaryReportService**: Generate and save summary reports
+  - Git information extraction
+  - Violation aggregation by rule
+  - Text summary formatting for console
+
+### 🔧 **CLI Enhancements**
+- **FIXED**: Default semantic analysis now enabled for heuristic engine
+  - Removed default `'0'` from `--max-semantic-files` option
+  - ts-morph now works by default without explicit `--max-semantic-files=-1`
+- **ENHANCED**: Display message now shows "TypeScript/JavaScript files (TS/TSX/JS/JSX)"
+  - Previously only showed "TS/JS files" causing confusion about TSX support
+- **IMPROVED**: Semantic engine disabled message now more informative
+  - Clarifies when analysis is explicitly disabled vs. using default
+
+### 📝 **Documentation**
+- **NEW**: `docs/QUALITY_SCORING_GUIDE.md` - Comprehensive scoring guide
+  - Scoring formula explanation
+  - Grade scale interpretation
+  - CI/CD integration examples (GitHub Actions, GitLab CI)
+  - Dashboard integration patterns
+  - Quality gate setup
+  - Trending analysis examples
+- **NEW**: `examples/github-actions-quality-check.yml` - GitHub Actions workflow template
+- **UPDATED**: README.md with Quality Scoring section
+
+### 🎯 **Use Cases**
+- **CI/CD Integration**: Automated quality gates in pipelines
+- **Management Dashboards**: Summary reports for project quality tracking
+- **Quality Trending**: Track quality metrics over time
+- **PR Comments**: Automated quality feedback on pull requests
+- **Slack Notifications**: Quality score alerts to team channels
+
+### 📊 **Example Output**
+```json
+{
+  "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, "severity": "warning" }
+    ]
+  }
+}
+```
+
+### 🔗 **Related Issues**
+- Fixed semantic engine requiring explicit CLI options for ts-morph
+- Enhanced TSX file visibility in console output
+- Improved default configuration for heuristic engine
+
+---
+
+## �🔧 **v1.3.9 - File Targeting Regression Fix (October 2, 2025)**
 
 **Release Date**: October 2, 2025  
 **Type**: Bug Fix  

package/README.md

@@ -17,6 +17,8 @@ Sun Lint is a universal coding standards checker providing comprehensive code qu
 - ✅ **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**
 
@@ -64,8 +66,68 @@ 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**
+```bash
+# 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**
+```json
+{
+  "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](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)**

package/core/cli-action-handler.js

@@ -85,7 +85,8 @@ class CliActionHandler {
       // Output results
       await this.outputService.outputResults(results, this.options, { 
         duration,
-        rulesRun: rulesToRun.length 
+        rulesRun: rulesToRun.length,
+        rulesChecked: rulesToRun.length
       });
 
       // Exit with appropriate code
@@ -295,6 +296,34 @@ class CliActionHandler {
       }
     }
 
+    // Validate upload-report option - requires output-summary to be set
+    if (this.options.uploadReport !== undefined) {
+      if (!this.options.outputSummary) {
+        throw new Error(
+          chalk.red(`❌ --upload-report requires --output-summary to be specified\n`) +
+          chalk.gray('Example: sunlint --all --output-summary=report.json --upload-report --input=src')
+        );
+      }
+      
+      // Set default URL if no URL provided (when uploadReport is true)
+      if (typeof this.options.uploadReport === 'boolean' || !this.options.uploadReport) {
+        this.options.uploadReport = 'https://coding-standards-report.sun-asterisk.vn/api/reports';
+        if (this.options.verbose) {
+          console.log(chalk.gray(`ℹ️  Using default upload URL: ${this.options.uploadReport}`));
+        }
+      }
+      
+      // Basic URL validation
+      try {
+        new URL(this.options.uploadReport);
+      } catch (error) {
+        throw new Error(
+          chalk.red(`❌ Invalid upload URL format: ${this.options.uploadReport}\n`) +
+          chalk.gray('Please provide a valid HTTP/HTTPS URL')
+        );
+      }
+    }
+
     // Priority 1: CLI --input parameter (highest priority)
     if (this.options.input) {
       // Validate CLI input path exists

package/core/cli-program.js

@@ -34,6 +34,8 @@ function createCliProgram() {
     .option('-i, --input <path>', 'Input file or directory to analyze (REQUIRED)')
     .option('-f, --format <format>', 'Output format (eslint,json,summary,table)', 'eslint')
     .option('-o, --output <file>', 'Output file path')
+    .option('--output-summary <file>', 'Output summary report file path (JSON format for CI/CD)')
+    .option('--upload-report [url]', 'Upload summary report to API endpoint after analysis (default: Sun* Coding Standards API)')
     .option('--config <file>', 'Configuration file path (default: auto-discover)');
 
   // File targeting options
@@ -129,6 +131,8 @@ CI/CD Integration:
   $ sunlint --all --changed-files --diff-base=origin/main --fail-on-new-violations
   $ sunlint --all --staged-files --format=summary
   $ sunlint --all --pr-mode --diff-base=origin/main
+  $ sunlint --all --output-summary=report.json --upload-report
+  $ sunlint --all --output-summary=report.json --upload-report=https://custom-api.com/reports
 
 ESLint Integration:
   $ sunlint --typescript --eslint-integration --input=src

package/core/output-service.js

@@ -1,14 +1,20 @@
 /**
  * Output Service
- * Following Rule C005: Single responsibility - handle output operations
  */
 
 const fs = require('fs');
 const path = require('path');
 const chalk = require('chalk');
+const ScoringService = require('./scoring-service');
+const SummaryReportService = require('./summary-report-service');
+const UploadService = require('./upload-service');
 
 class OutputService {
-  constructor() {}
+  constructor() {
+    this.scoringService = new ScoringService();
+    this.summaryReportService = new SummaryReportService();
+    this.uploadService = new UploadService();
+  }
 
   async outputResults(results, options, metadata = {}) {
     // Generate report based on format
@@ -27,12 +33,91 @@ class OutputService {
       console.log(chalk.green(`📄 Report saved to: ${options.output}`));
     }
 
+    // Summary report output (new feature for CI/CD)
+    if (options.outputSummary) {
+      const summaryReport = this.generateAndSaveSummaryReport(
+        report.violations,
+        results,
+        options,
+        metadata
+      );
+      console.log(chalk.green(`📊 Summary report saved to: ${options.outputSummary}`));
+      
+      // Display summary in console
+      if (!options.quiet) {
+        console.log(this.summaryReportService.formatTextSummary(summaryReport));
+      }
+
+      // Upload report if upload URL is provided
+      if (options.uploadReport) {
+        await this.handleUploadReport(options.outputSummary, options.uploadReport, options);
+      }
+    }
+
     // Summary (skip for JSON format)
     if (!options.quiet && options.format !== 'json') {
       console.log(report.summary);
     }
   }
 
+  generateAndSaveSummaryReport(violations, results, options, metadata) {
+    const totalFiles = results.filesAnalyzed || results.summary?.totalFiles || results.totalFiles || results.fileCount || 0;
+    
+    // Calculate LOC
+    let loc = 0;
+    if (options.input) {
+      const inputPaths = Array.isArray(options.input) ? options.input : [options.input];
+      for (const inputPath of inputPaths) {
+        if (fs.existsSync(inputPath)) {
+          const stat = fs.statSync(inputPath);
+          if (stat.isDirectory()) {
+            loc += this.scoringService.calculateDirectoryLOC(inputPath);
+          } else {
+            loc += this.scoringService.calculateLOC([inputPath]);
+          }
+        }
+      }
+    }
+
+    // Count violations
+    const errorCount = violations.filter(v => v.severity === 'error').length;
+    const warningCount = violations.filter(v => v.severity === 'warning').length;
+
+    // Get number of rules checked - use metadata first, then parse from options
+    let rulesChecked = metadata.rulesChecked;
+    if (!rulesChecked && options.rule) {
+      rulesChecked = typeof options.rule === 'string' 
+        ? options.rule.split(',').filter(r => r.trim()).length 
+        : Array.isArray(options.rule) 
+          ? options.rule.length 
+          : 1;
+    }
+    rulesChecked = rulesChecked || 1;
+
+    // Calculate score
+    const scoringSummary = this.scoringService.generateScoringSummary({
+      errorCount,
+      warningCount,
+      rulesChecked,
+      loc
+    });
+
+    // Generate and save summary report
+    const summaryReport = this.summaryReportService.saveSummaryReport(
+      violations,
+      scoringSummary,
+      options.outputSummary,
+      {
+        cwd: process.cwd(),
+        filesAnalyzed: totalFiles,
+        duration: metadata.duration,
+        version: metadata.version || '1.3.12'
+      }
+    );
+
+    return summaryReport;
+  }
+
   generateReport(results, metadata, options = {}) {
     const allViolations = [];
     let totalFiles = results.filesAnalyzed || results.summary?.totalFiles || results.totalFiles || results.fileCount || 0;
@@ -98,7 +183,8 @@ class OutputService {
     return {
       formatted,
       summary,
-      raw
+      raw,
+      violations: allViolations  // Add violations for summary report
     };
   }
 
@@ -244,6 +330,77 @@ class OutputService {
 
     return jsonResults;
   }
+
+  /**
+   * Handle uploading report to API endpoint
+   */
+  async handleUploadReport(filePath, apiUrl, options = {}) {
+    try {
+      if (!filePath) {
+        throw new Error('Summary report file path is required for upload');
+      }
+
+      if (!apiUrl) {
+        throw new Error('API URL is required for upload');
+      }
+
+      // Check if curl is available
+      if (!this.uploadService.checkCurlAvailability()) {
+        console.warn(chalk.yellow('⚠️  curl is not available. Skipping report upload.'));
+        return;
+      }
+
+      // Validate API endpoint if not in quiet mode
+      if (!options.quiet) {
+        console.log(chalk.blue('🔍 Checking API endpoint accessibility...'));
+        const endpointCheck = await this.uploadService.validateApiEndpoint(apiUrl, {
+          timeout: options.uploadTimeout || 10
+        });
+        
+        if (!endpointCheck.accessible) {
+          console.warn(chalk.yellow(`⚠️  API endpoint may not be accessible: ${endpointCheck.error}`));
+          console.warn(chalk.yellow('Proceeding with upload attempt...'));
+        }
+      }
+
+      // Upload the report
+      const uploadResult = await this.uploadService.uploadReportToApi(filePath, apiUrl, {
+        timeout: options.uploadTimeout || 30,
+        verbose: options.verbose,
+        debug: options.debug
+      });
+
+      if (uploadResult.success) {
+        if (!options.quiet) {
+          console.log(chalk.green(`✅ Report successfully uploaded to: ${apiUrl}`));
+          if (uploadResult.statusCode) {
+            console.log(chalk.green(`📡 HTTP Status: ${uploadResult.statusCode}`));
+          }
+        }
+      } else {
+        console.warn(chalk.yellow(`⚠️  Failed to upload report: ${uploadResult.error}`));
+        
+        if (options.verbose && uploadResult.errorContext) {
+          console.warn('Upload error details:', uploadResult.errorContext);
+        }
+      }
+
+      return uploadResult;
+
+    } catch (error) {
+      console.error(chalk.red('❌ Upload process failed:'), error.message);
+      
+      if (options.debug) {
+        console.error('Upload error stack:', error.stack);
+      }
+      
+      // Don't throw error to prevent interrupting the main analysis flow
+      return {
+        success: false,
+        error: error.message
+      };
+    }
+  }
 }
 
 module.exports = OutputService;

package/core/scoring-service.js

@@ -0,0 +1,169 @@
+/**
+ * Scoring Service
+ * Calculate quality score based on violations, rules, and LOC
+ * Following Rule C005: Single responsibility - handle scoring operations
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+class ScoringService {
+  constructor() {
+    // Scoring weights
+    this.weights = {
+      errorPenalty: 5,      // Each error reduces score by 5 points
+      warningPenalty: 1,    // Each warning reduces score by 1 point
+      ruleBonus: 0.5,       // Bonus for each rule checked
+      locFactor: 0.001      // Factor for normalizing by LOC
+    };
+  }
+
+  /**
+   * Calculate quality score
+   * Score formula: 100 - (errorCount * 5 + warningCount * 1) * (1000 / LOC) + (rulesChecked * 0.5)
+   * 
+   * @param {Object} params
+   * @param {number} params.errorCount - Number of errors found
+   * @param {number} params.warningCount - Number of warnings found
+   * @param {number} params.rulesChecked - Number of rules checked
+   * @param {number} params.loc - Total lines of code
+   * @returns {number} Score between 0-100
+   */
+  calculateScore({ errorCount, warningCount, rulesChecked, loc }) {
+    // Base score starts at 100
+    let score = 100;
+
+    // Calculate violations penalty
+    const totalPenalty = (errorCount * this.weights.errorPenalty) + 
+                        (warningCount * this.weights.warningPenalty);
+
+    // Normalize penalty by LOC (per 1000 lines)
+    const locNormalization = loc > 0 ? 1000 / loc : 1;
+    const normalizedPenalty = totalPenalty * locNormalization;
+
+    // Apply penalty
+    score -= normalizedPenalty;
+
+    // Add bonus for rules checked (more rules = more thorough check)
+    const ruleBonus = Math.min(rulesChecked * this.weights.ruleBonus, 10); // Max 10 points bonus
+    score += ruleBonus;
+
+    // Ensure score is between 0-100
+    score = Math.max(0, Math.min(100, score));
+
+    // Round to 1 decimal place
+    return Math.round(score * 10) / 10;
+  }
+
+  /**
+   * Calculate Lines of Code (LOC) for given files
+   * @param {string[]} files - Array of file paths
+   * @returns {number} Total lines of code
+   */
+  calculateLOC(files) {
+    let totalLines = 0;
+
+    for (const file of files) {
+      try {
+        if (fs.existsSync(file)) {
+          const content = fs.readFileSync(file, 'utf8');
+          const lines = content.split('\n').length;
+          totalLines += lines;
+        }
+      } catch (error) {
+        // Ignore files that can't be read
+        console.warn(`Warning: Could not read file ${file}`);
+      }
+    }
+
+    return totalLines;
+  }
+
+  /**
+   * Calculate LOC for a directory
+   * @param {string} directory - Directory path
+   * @param {string[]} extensions - File extensions to include (e.g., ['.ts', '.tsx', '.js', '.jsx'])
+   * @returns {number} Total lines of code
+   */
+  calculateDirectoryLOC(directory, extensions = ['.ts', '.tsx', '.js', '.jsx']) {
+    let totalLines = 0;
+
+    const processDirectory = (dir) => {
+      try {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+        for (const entry of entries) {
+          const fullPath = path.join(dir, entry.name);
+
+          if (entry.isDirectory()) {
+            // Skip common directories
+            if (!['node_modules', '.git', 'dist', 'build', 'coverage'].includes(entry.name)) {
+              processDirectory(fullPath);
+            }
+          } else if (entry.isFile()) {
+            const ext = path.extname(entry.name);
+            if (extensions.includes(ext)) {
+              try {
+                const content = fs.readFileSync(fullPath, 'utf8');
+                totalLines += content.split('\n').length;
+              } catch (error) {
+                // Ignore files that can't be read
+              }
+            }
+          }
+        }
+      } catch (error) {
+        // Ignore directories that can't be read
+      }
+    };
+
+    if (fs.existsSync(directory)) {
+      processDirectory(directory);
+    }
+
+    return totalLines;
+  }
+
+  /**
+   * Get score grade based on score value
+   * @param {number} score - Score value (0-100)
+   * @returns {string} Grade (A+, A, B+, B, C+, C, D, F)
+   */
+  getGrade(score) {
+    if (score >= 95) return 'A+';
+    if (score >= 90) return 'A';
+    if (score >= 85) return 'B+';
+    if (score >= 80) return 'B';
+    if (score >= 75) return 'C+';
+    if (score >= 70) return 'C';
+    if (score >= 60) return 'D';
+    return 'F';
+  }
+
+  /**
+   * Generate scoring summary
+   * @param {Object} params
+   * @returns {Object} Scoring summary with score, grade, and metrics
+   */
+  generateScoringSummary(params) {
+    const score = this.calculateScore(params);
+    const grade = this.getGrade(score);
+
+    return {
+      score,
+      grade,
+      metrics: {
+        errors: params.errorCount,
+        warnings: params.warningCount,
+        rulesChecked: params.rulesChecked,
+        linesOfCode: params.loc,
+        violationsPerKLOC: params.loc > 0 
+          ? Math.round(((params.errorCount + params.warningCount) / params.loc * 1000) * 10) / 10
+          : 0
+      }
+    };
+  }
+}
+
+module.exports = ScoringService;