@kabran-tecnologia/kabran-config 1.5.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kabran-tecnologia/kabran-config",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Shared quality configurations, enforcement scripts, and CI/CD tooling for Kabran projects",
   "author": "Kabran",
   "license": "MIT",
@@ -9,7 +9,9 @@
     "access": "public"
   },
   "bin": {
-    "kabran-setup": "src/scripts/setup.mjs"
+    "kabran-setup": "src/scripts/setup.mjs",
+    "kabran-ci": "src/scripts/ci/ci-runner.sh",
+    "kabran-pr-comment": "src/scripts/pr-quality-comment.mjs"
   },
   "exports": {
     "./eslint": "./src/eslint.mjs",
@@ -31,6 +33,7 @@
     "./scripts/quality-standard-validator": "./src/scripts/quality-standard-validator.mjs",
     "./scripts/generate-ci-result": "./src/scripts/generate-ci-result.mjs",
     "./scripts/ci-result-utils": "./src/scripts/ci-result-utils.mjs",
+    "./scripts/pr-quality-comment": "./src/scripts/pr-quality-comment.mjs",
     "./schemas/ci-result": "./src/schemas/ci-result.v2.schema.json"
   },
   "files": [

package/src/scripts/ci/ci-core.sh

@@ -163,6 +163,37 @@ check_dependencies() {
   return 0
 }
 
+# ==============================================================================
+# Scope Filtering
+# ==============================================================================
+
+# Check if a component should be executed based on CI_SCOPE
+# Usage: should_run_component "component_name"
+# Returns: 0 if should run, 1 if should skip
+should_run_component() {
+  local component="${1:-}"
+  local scope="${CI_SCOPE:-all}"
+
+  # Always run if scope is "all"
+  if [ "$scope" = "all" ]; then
+    return 0
+  fi
+
+  # Run if no component specified (global steps)
+  if [ -z "$component" ]; then
+    return 0
+  fi
+
+  # Run if component matches scope
+  if [ "$component" = "$scope" ]; then
+    return 0
+  fi
+
+  # Skip otherwise
+  log_debug "Skipping $component (scope: $scope)"
+  return 1
+}
+
 # ==============================================================================
 # Step Execution
 # ==============================================================================
@@ -178,6 +209,29 @@ run_step() {
   local category="${5:-custom}"
   local log_file="/tmp/ci_${name}.log"
 
+  # Check if this step should run based on scope
+  if ! should_run_component "$component"; then
+    # Record skipped step
+    local step_json
+    step_json=$(jq -n \
+      --arg name "$name" \
+      --arg component "$component" \
+      --arg category "$category" \
+      '{
+        name: $name,
+        status: "skip",
+        exit_code: 0,
+        duration_ms: 0,
+        duration_human: "0ms",
+        category: $category,
+        skip_reason: "scope_filter"
+      } + (if $component != "" then {component: $component} else {} end)'
+    )
+    STEP_RESULTS+=("$step_json")
+    log_info "Skipping: $name (out of scope)"
+    return 0
+  fi
+
   # Capture start time (milliseconds since epoch)
   local start_time
   start_time=$(date +%s%3N 2>/dev/null || echo $(($(date +%s) * 1000)))
@@ -375,6 +429,9 @@ export_ci_data() {
   # Create output directory
   mkdir -p "$(dirname "$output_file")"
 
+  # Get scope
+  local scope="${CI_SCOPE:-all}"
+
   # Generate intermediate data file for Node.js generator
   jq -n \
     --argjson steps "$steps_json" \
@@ -383,6 +440,7 @@ export_ci_data() {
     --arg started_at "$started_at" \
     --arg finished_at "$now" \
     --arg project_name "$project_name" \
+    --arg scope "$scope" \
     '{
       steps: $steps,
       errors: $errors,
@@ -393,6 +451,9 @@ export_ci_data() {
       },
       project: {
         name: $project_name
+      },
+      metadata: {
+        scope: $scope
       }
     }' > "$output_file"
 

package/src/scripts/ci/ci-runner.sh

@@ -27,6 +27,7 @@ OUTPUT_FILE_V2="${CI_OUTPUT_FILE_V2:-docs/quality/ci-result.json}"
 VERBOSE="${CI_VERBOSE:-false}"
 PROJECT_ROOT="${PROJECT_ROOT:-$(pwd)}"
 USE_V2="${CI_USE_V2:-true}"
+CI_SCOPE="${CI_SCOPE:-all}"  # Scope filter: "all" or component name (e.g., "app", "website")
 
 # Track errors (reinitialize to avoid issues with sourced scripts)
 ERRORS=()
@@ -80,6 +81,9 @@ fi
 log_info "Starting Kabran CI - $PROJECT_NAME"
 log_info "Working directory: $PROJECT_ROOT"
 log_info "CI Core Version: $CI_CORE_VERSION"
+if [ "$CI_SCOPE" != "all" ]; then
+  log_info "Scope: $CI_SCOPE (filtered)"
+fi
 echo ""
 
 # Start timing

package/src/scripts/ci-result-utils.mjs

@@ -305,6 +305,125 @@ export function extractComponents(steps) {
   return Array.from(components).sort()
 }
 
+/**
+ * Aggregate coverage data from multiple test steps
+ *
+ * @param {Array} steps - Array of step results with coverage data
+ * @returns {Object|null} Aggregated coverage or null if no coverage data
+ */
+export function aggregateCoverage(steps) {
+  const coverageData = []
+
+  for (const step of steps) {
+    if (step.output?.coverage) {
+      coverageData.push({
+        component: step.component || 'default',
+        coverage: step.output.coverage,
+        tests: {
+          passed: step.output.passed || 0,
+          failed: step.output.failed || 0,
+          skipped: step.output.skipped || 0,
+        },
+      })
+    }
+  }
+
+  if (coverageData.length === 0) {
+    return null
+  }
+
+  // Calculate weighted average based on test count
+  let totalTests = 0
+  let weightedLines = 0
+  let weightedBranches = 0
+  let weightedFunctions = 0
+  let weightedStatements = 0
+
+  const byComponent = {}
+
+  for (const data of coverageData) {
+    const testCount = data.tests.passed + data.tests.failed
+    totalTests += testCount
+
+    const cov = data.coverage
+    if (cov.lines !== undefined) weightedLines += cov.lines * testCount
+    if (cov.branches !== undefined) weightedBranches += cov.branches * testCount
+    if (cov.functions !== undefined) weightedFunctions += cov.functions * testCount
+    if (cov.statements !== undefined) weightedStatements += cov.statements * testCount
+
+    byComponent[data.component] = {
+      ...data.coverage,
+      tests: data.tests,
+    }
+  }
+
+  // Calculate averages
+  const avgLines = totalTests > 0 ? Math.round((weightedLines / totalTests) * 10) / 10 : 0
+  const avgBranches = totalTests > 0 ? Math.round((weightedBranches / totalTests) * 10) / 10 : 0
+  const avgFunctions = totalTests > 0 ? Math.round((weightedFunctions / totalTests) * 10) / 10 : 0
+  const avgStatements = totalTests > 0 ? Math.round((weightedStatements / totalTests) * 10) / 10 : 0
+
+  return {
+    lines: avgLines,
+    branches: avgBranches,
+    functions: avgFunctions,
+    statements: avgStatements,
+    by_component: byComponent,
+  }
+}
+
+/**
+ * Compare two CI results and calculate diff
+ *
+ * @param {Object} current - Current CI result
+ * @param {Object} baseline - Baseline CI result (e.g., from main branch)
+ * @returns {Object} Comparison result with diffs
+ */
+export function compareCiResults(current, baseline) {
+  const scoreDiff = current.summary.score - baseline.summary.score
+  const issuesDiff = current.summary.total_issues - baseline.summary.total_issues
+  const blockingDiff = current.summary.blocking - baseline.summary.blocking
+
+  // Determine trend
+  let trend = 'stable'
+  if (scoreDiff > 5) trend = 'improving'
+  else if (scoreDiff < -5) trend = 'degrading'
+
+  // Compare coverage if available
+  let coverageDiff = null
+  if (current.checks?.test?.coverage && baseline.checks?.test?.coverage) {
+    coverageDiff = {
+      lines: (current.checks.test.coverage.lines || 0) - (baseline.checks.test.coverage.lines || 0),
+      branches: (current.checks.test.coverage.branches || 0) - (baseline.checks.test.coverage.branches || 0),
+      functions: (current.checks.test.coverage.functions || 0) - (baseline.checks.test.coverage.functions || 0),
+    }
+  }
+
+  return {
+    trend,
+    score: {
+      current: current.summary.score,
+      baseline: baseline.summary.score,
+      diff: scoreDiff,
+    },
+    issues: {
+      current: current.summary.total_issues,
+      baseline: baseline.summary.total_issues,
+      diff: issuesDiff,
+    },
+    blocking: {
+      current: current.summary.blocking,
+      baseline: baseline.summary.blocking,
+      diff: blockingDiff,
+    },
+    coverage: coverageDiff,
+    status: {
+      current: current.summary.status,
+      baseline: baseline.summary.status,
+    },
+  }
+}
+
 /**
  * Create a minimal valid CI result object
  *

package/src/scripts/pr-quality-comment.mjs

@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+
+/**
+ * PR Quality Comment Generator
+ *
+ * Generates a formatted PR comment comparing CI results between
+ * the current branch and a baseline (typically main).
+ *
+ * Usage:
+ *   node pr-quality-comment.mjs --current ci-result.json --baseline main-ci-result.json
+ *   node pr-quality-comment.mjs --current ci-result.json --baseline-branch main
+ *
+ * Output: Markdown formatted comment to stdout
+ *
+ * @module pr-quality-comment
+ */
+
+import { readFileSync, existsSync } from 'node:fs'
+import { execSync } from 'node:child_process'
+import { compareCiResults } from './ci-result-utils.mjs'
+
+/**
+ * Get trend emoji
+ * @param {'improving'|'stable'|'degrading'} trend
+ * @returns {string} Emoji
+ */
+function getTrendEmoji(trend) {
+  switch (trend) {
+    case 'improving': return '📈'
+    case 'degrading': return '📉'
+    default: return '➡️'
+  }
+}
+
+/**
+ * Get status emoji
+ * @param {'passing'|'degraded'|'failing'} status
+ * @returns {string} Emoji
+ */
+function getStatusEmoji(status) {
+  switch (status) {
+    case 'passing': return '✅'
+    case 'degraded': return '⚠️'
+    case 'failing': return '❌'
+    default: return '❓'
+  }
+}
+
+/**
+ * Format diff with sign and color indicator
+ * @param {number} diff - Difference value
+ * @param {boolean} inverted - Whether positive is bad (for issues)
+ * @returns {string} Formatted diff string
+ */
+function formatDiff(diff, inverted = false) {
+  if (diff === 0) return '='
+  const sign = diff > 0 ? '+' : ''
+  const indicator = inverted
+    ? (diff > 0 ? '🔴' : '🟢')
+    : (diff > 0 ? '🟢' : '🔴')
+  return `${sign}${diff} ${indicator}`
+}
+
+/**
+ * Generate markdown comment from comparison
+ * @param {Object} comparison - Comparison result from compareCiResults
+ * @param {Object} current - Current CI result
+ * @param {Object} baseline - Baseline CI result
+ * @returns {string} Markdown formatted comment
+ */
+export function generateComment(comparison, current, baseline) {
+  const lines = []
+
+  // Header
+  lines.push(`## ${getTrendEmoji(comparison.trend)} Quality Report`)
+  lines.push('')
+
+  // Status summary
+  const currentStatus = `${getStatusEmoji(comparison.status.current)} ${comparison.status.current}`
+  const baselineStatus = `${getStatusEmoji(comparison.status.baseline)} ${comparison.status.baseline}`
+
+  lines.push(`| Metric | Current | Baseline | Diff |`)
+  lines.push(`|--------|---------|----------|------|`)
+  lines.push(`| **Status** | ${currentStatus} | ${baselineStatus} | - |`)
+  lines.push(`| **Score** | ${comparison.score.current} | ${comparison.score.baseline} | ${formatDiff(comparison.score.diff)} |`)
+  lines.push(`| **Issues** | ${comparison.issues.current} | ${comparison.issues.baseline} | ${formatDiff(comparison.issues.diff, true)} |`)
+  lines.push(`| **Blocking** | ${comparison.blocking.current} | ${comparison.blocking.baseline} | ${formatDiff(comparison.blocking.diff, true)} |`)
+  lines.push('')
+
+  // Coverage section (if available)
+  if (comparison.coverage) {
+    lines.push(`### 📊 Coverage`)
+    lines.push('')
+    lines.push(`| Type | Current | Baseline | Diff |`)
+    lines.push(`|------|---------|----------|------|`)
+
+    const currentCov = current.checks?.test?.coverage || {}
+    const baselineCov = baseline.checks?.test?.coverage || {}
+
+    if (comparison.coverage.lines !== null) {
+      lines.push(`| Lines | ${currentCov.lines || 0}% | ${baselineCov.lines || 0}% | ${formatDiff(comparison.coverage.lines)} |`)
+    }
+    if (comparison.coverage.branches !== null) {
+      lines.push(`| Branches | ${currentCov.branches || 0}% | ${baselineCov.branches || 0}% | ${formatDiff(comparison.coverage.branches)} |`)
+    }
+    if (comparison.coverage.functions !== null) {
+      lines.push(`| Functions | ${currentCov.functions || 0}% | ${baselineCov.functions || 0}% | ${formatDiff(comparison.coverage.functions)} |`)
+    }
+    lines.push('')
+  }
+
+  // Checks summary
+  if (current.checks && Object.keys(current.checks).length > 0) {
+    lines.push(`### 🔍 Checks`)
+    lines.push('')
+    lines.push(`| Check | Status | Errors | Warnings |`)
+    lines.push(`|-------|--------|--------|----------|`)
+
+    for (const [name, check] of Object.entries(current.checks)) {
+      const emoji = getStatusEmoji(check.status)
+      lines.push(`| ${name} | ${emoji} ${check.status} | ${check.errors || 0} | ${check.warnings || 0} |`)
+    }
+    lines.push('')
+  }
+
+  // New issues (if any)
+  if (current.issues && current.issues.length > 0) {
+    const newIssues = current.issues.filter(i => i.severity === 'error')
+    if (newIssues.length > 0) {
+      lines.push(`### ⚠️ Blocking Issues`)
+      lines.push('')
+      for (const issue of newIssues.slice(0, 5)) {
+        lines.push(`- \`${issue.rule || issue.id}\`: ${issue.message}`)
+        if (issue.file) {
+          lines.push(`  - 📁 ${issue.file}${issue.line ? `:${issue.line}` : ''}`)
+        }
+      }
+      if (newIssues.length > 5) {
+        lines.push(`- ... and ${newIssues.length - 5} more`)
+      }
+      lines.push('')
+    }
+  }
+
+  // Timing info
+  lines.push(`---`)
+  lines.push(`<sub>`)
+  lines.push(`⏱️ Duration: ${current.timing?.total_human || 'N/A'} | `)
+  lines.push(`🔀 Branch: ${current.meta?.branch || 'N/A'} | `)
+  lines.push(`📝 Commit: ${current.meta?.commit || 'N/A'}`)
+  lines.push(`</sub>`)
+
+  return lines.join('\n')
+}
+
+/**
+ * Fetch baseline CI result from another branch
+ * @param {string} branch - Branch name
+ * @param {string} filePath - Path to ci-result.json in repo
+ * @returns {Object|null} CI result or null
+ */
+export function fetchBaselineFromBranch(branch, filePath = 'docs/quality/ci-result.json') {
+  try {
+    const content = execSync(`git show ${branch}:${filePath}`, {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+    return JSON.parse(content)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Parse command line arguments
+ */
+function parseArgs(args) {
+  const options = {
+    current: null,
+    baseline: null,
+    baselineBranch: null,
+    output: 'stdout',
+  }
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+
+    if (arg === '--current' || arg === '-c') {
+      options.current = args[++i]
+    } else if (arg === '--baseline' || arg === '-b') {
+      options.baseline = args[++i]
+    } else if (arg === '--baseline-branch') {
+      options.baselineBranch = args[++i]
+    } else if (arg === '--output' || arg === '-o') {
+      options.output = args[++i]
+    } else if (arg === '--help' || arg === '-h') {
+      console.log(`
+Usage: pr-quality-comment.mjs [options]
+
+Options:
+  -c, --current <file>        Current CI result JSON file (required)
+  -b, --baseline <file>       Baseline CI result JSON file
+  --baseline-branch <branch>  Fetch baseline from git branch
+  -o, --output <file>         Output file (default: stdout)
+  -h, --help                  Show this help message
+
+Examples:
+  # Compare with file
+  node pr-quality-comment.mjs -c ci-result.json -b main-ci-result.json
+
+  # Compare with main branch
+  node pr-quality-comment.mjs -c ci-result.json --baseline-branch main
+`)
+      process.exit(0)
+    }
+  }
+
+  return options
+}
+
+/**
+ * Main entry point
+ */
+async function main() {
+  const args = process.argv.slice(2)
+  const options = parseArgs(args)
+
+  // Validate current file
+  if (!options.current) {
+    console.error('Error: --current is required')
+    process.exit(1)
+  }
+
+  if (!existsSync(options.current)) {
+    console.error(`Error: Current file not found: ${options.current}`)
+    process.exit(1)
+  }
+
+  // Load current result
+  const current = JSON.parse(readFileSync(options.current, 'utf8'))
+
+  // Load baseline result
+  let baseline = null
+  if (options.baseline) {
+    if (!existsSync(options.baseline)) {
+      console.error(`Error: Baseline file not found: ${options.baseline}`)
+      process.exit(1)
+    }
+    baseline = JSON.parse(readFileSync(options.baseline, 'utf8'))
+  } else if (options.baselineBranch) {
+    baseline = fetchBaselineFromBranch(options.baselineBranch)
+    if (!baseline) {
+      console.error(`Warning: Could not fetch baseline from branch ${options.baselineBranch}`)
+      // Create a minimal baseline for first PR
+      baseline = {
+        summary: { score: 100, total_issues: 0, blocking: 0, status: 'passing' },
+        checks: {},
+      }
+    }
+  } else {
+    // No baseline provided, create empty comparison
+    baseline = {
+      summary: { score: 100, total_issues: 0, blocking: 0, status: 'passing' },
+      checks: {},
+    }
+  }
+
+  // Generate comparison
+  const comparison = compareCiResults(current, baseline)
+
+  // Generate comment
+  const comment = generateComment(comparison, current, baseline)
+
+  // Output
+  if (options.output === 'stdout') {
+    console.log(comment)
+  } else {
+    const { writeFileSync } = await import('node:fs')
+    writeFileSync(options.output, comment)
+    console.log(`Comment written to: ${options.output}`)
+  }
+}
+
+// Run if called directly
+import { fileURLToPath } from 'node:url'
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main()
+}
+
+export { generateComment as default, fetchBaselineFromBranch }

package/templates/.github/workflows/ci-quality.yml

@@ -0,0 +1,111 @@
+# Kabran CI Quality Workflow
+#
+# This workflow runs the Kabran CI pipeline and posts quality reports to PRs.
+#
+# Usage:
+#   Copy this file to your project's .github/workflows/ directory.
+#   Customize the ci-config.sh to define your project's CI steps.
+#
+# Requirements:
+#   - scripts/ci-config.sh with PROJECT_NAME, PM, and ci_steps() defined
+#   - @kabran-tecnologia/kabran-config installed as dev dependency
+
+name: CI Quality
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# Cancel in-progress runs for the same branch
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  ci:
+    name: CI Pipeline
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      pull-requests: write  # Required for PR comments
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Full history for baseline comparison
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run CI Pipeline
+        id: ci
+        env:
+          CI_USE_V2: 'true'
+          CI_OUTPUT_FILE_V2: 'docs/quality/ci-result.json'
+          # CI_SCOPE: 'all'  # Uncomment and set to filter by component
+        run: |
+          # Run CI using kabran-config runner
+          npx kabran-ci || exit_code=$?
+
+          # Ensure ci-result.json exists
+          if [ -f "docs/quality/ci-result.json" ]; then
+            echo "ci_result_exists=true" >> $GITHUB_OUTPUT
+          else
+            echo "ci_result_exists=false" >> $GITHUB_OUTPUT
+          fi
+
+          exit ${exit_code:-0}
+
+      - name: Generate PR Comment
+        if: github.event_name == 'pull_request' && steps.ci.outputs.ci_result_exists == 'true'
+        id: comment
+        run: |
+          # Generate quality comparison comment
+          npx kabran-pr-comment \
+            --current docs/quality/ci-result.json \
+            --baseline-branch ${{ github.base_ref }} \
+            --output /tmp/pr-comment.md || true
+
+          if [ -f "/tmp/pr-comment.md" ]; then
+            echo "comment_exists=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Post PR Comment
+        if: github.event_name == 'pull_request' && steps.comment.outputs.comment_exists == 'true'
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          header: kabran-quality
+          path: /tmp/pr-comment.md
+
+      - name: Upload CI Result
+        if: always() && steps.ci.outputs.ci_result_exists == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: ci-result
+          path: docs/quality/ci-result.json
+          retention-days: 30
+
+      - name: Commit CI Result (main only)
+        if: github.ref == 'refs/heads/main' && github.event_name == 'push' && steps.ci.outputs.ci_result_exists == 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          # Only commit if there are changes
+          if git diff --quiet docs/quality/ci-result.json; then
+            echo "No changes to ci-result.json"
+          else
+            git add docs/quality/ci-result.json
+            git commit -m "chore(ci): update ci-result.json [skip ci]"
+            git push
+          fi