@kabran-tecnologia/kabran-config 1.6.0 → 1.7.0

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

@@ -34,8 +34,14 @@ import {
   calculateExecutionStats,
   countIssues,
   extractComponents,
+  getTraceId,
+  buildTelemetryExtension,
 } from './ci-result-utils.mjs'
 
+// History and trends imports
+import { loadHistory, addToHistory, saveHistory } from './ci-result-history.mjs'
+import { calculateTrends } from './ci-result-trends.mjs'
+
 // Validator imports
 import { getLicenseCheckResult } from './license-check.mjs'
 import { getReadmeCheckResult } from './readme-validator.mjs'
@@ -132,6 +138,7 @@ async function runValidators(projectRoot, options = {}) {
  * @param {Object} input.project - Project information
  * @param {Object} input.metadata - Additional metadata
  * @param {Object} input.validators - Validator results (from runValidators)
+ * @param {Object} input.trends - Pre-calculated trends (optional)
  * @returns {Object} CI result object
  */
 export function generateCiResult(input) {
@@ -143,6 +150,7 @@ export function generateCiResult(input) {
     metadata = {},
     issues = [],
     validators = {},
+    trends = null,
   } = input
 
   const now = new Date().toISOString()
@@ -169,19 +177,36 @@ export function generateCiResult(input) {
   // Determine exit code
   const exitCode = executionStats.steps_failed > 0 ? 1 : 0
 
+  // Get trace ID if available
+  const traceId = getTraceId()
+
+  // Build meta object
+  const meta = {
+    generated_at: now,
+    generator: getGeneratorVersion(),
+    run_id: generateRunId(),
+    trigger: detectTrigger(),
+    branch: getGitBranch(),
+    commit: getGitCommit(),
+  }
+
+  // Add trace_id if available
+  if (traceId) {
+    meta.trace_id = traceId
+  }
+
+  // Build extensions with telemetry if trace_id exists
+  const extensions = { ...(metadata.extensions || {}) }
+  if (traceId) {
+    extensions.telemetry = buildTelemetryExtension(traceId)
+  }
+
   // Build result object
   const result = {
     $schema: 'https://kabran.dev/schemas/ci-result.v2.json',
     version: '1.0.0',
 
-    meta: {
-      generated_at: now,
-      generator: getGeneratorVersion(),
-      run_id: generateRunId(),
-      trigger: detectTrigger(),
-      branch: getGitBranch(),
-      commit: getGitCommit(),
-    },
+    meta,
 
     project: {
       name: project.name || 'unknown',
@@ -216,7 +241,12 @@ export function generateCiResult(input) {
     checks,
     issues,
     errors,
-    extensions: metadata.extensions || {},
+    extensions,
+  }
+
+  // Add trends if provided
+  if (trends) {
+    result.trends = trends
   }
 
   return result
@@ -236,6 +266,10 @@ function parseArgs(args) {
     skipReadme: false,
     skipEnv: false,
     skipQualityStandard: false,
+    trackHistory: false,
+    historyFile: null,
+    maxHistoryEntries: 30,
+    calculateTrends: false,
   }
 
   for (let i = 0; i < args.length; i++) {
@@ -259,6 +293,16 @@ function parseArgs(args) {
       options.skipEnv = true
     } else if (arg === '--skip-quality-standard') {
       options.skipQualityStandard = true
+    } else if (arg === '--track-history') {
+      options.trackHistory = true
+    } else if (arg === '--history-file') {
+      options.historyFile = args[++i]
+      options.trackHistory = true
+    } else if (arg === '--max-history') {
+      options.maxHistoryEntries = parseInt(args[++i], 10) || 30
+    } else if (arg === '--calculate-trends') {
+      options.calculateTrends = true
+      options.trackHistory = true
     } else if (arg === '--help' || arg === '-h') {
       console.log(`
 Usage: generate-ci-result.mjs [options]
@@ -273,6 +317,10 @@ Options:
   --skip-readme             Skip README check when running validators
   --skip-env                Skip env check when running validators
   --skip-quality-standard   Skip quality-standard check when running validators
+  --track-history           Track result in history file (max 30 entries)
+  --history-file <file>     Custom history file path (default: docs/quality/ci-result-history.json)
+  --max-history <n>         Maximum history entries to keep (default: 30)
+  --calculate-trends        Calculate and include trends from history
   -h, --help                Show this help message
 
 Input format:
@@ -362,15 +410,35 @@ async function main() {
       })
     }
 
+    // Determine paths
+    const outputPath = options.output || resolve(options.projectRoot, 'docs/quality/ci-result.json')
+    const historyPath = options.historyFile || resolve(options.projectRoot, 'docs/quality/ci-result-history.json')
+
+    // Load history and calculate trends if requested
+    let history = null
+    if (options.trackHistory || options.calculateTrends) {
+      history = loadHistory(historyPath)
+
+      // Calculate trends if requested
+      if (options.calculateTrends && history.entries.length > 0) {
+        input.trends = calculateTrends(history.entries)
+      }
+    }
+
     // Generate result
     const result = generateCiResult(input)
 
+    // Update history with new result
+    if (options.trackHistory && history) {
+      addToHistory(result, history)
+      saveHistory(history, historyPath, options.maxHistoryEntries)
+      console.log(`History updated: ${historyPath} (${history.entries.length} entries)`)
+    }
+
     // Output
     if (options.stdout) {
       console.log(JSON.stringify(result, null, 2))
     } else {
-      const outputPath = options.output || resolve(options.projectRoot, 'docs/quality/ci-result.json')
-
       // Ensure directory exists
       mkdirSync(dirname(outputPath), { recursive: true })
 

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

@@ -142,12 +142,48 @@ export function generateComment(comparison, current, baseline) {
     }
   }
 
+  // Trends section (if available)
+  if (current.trends && current.trends.data?.total_runs > 1) {
+    lines.push(`### 📈 Trends`)
+    lines.push('')
+    lines.push(`| Metric | Direction | Change (7d) | Avg (30d) |`)
+    lines.push(`|--------|-----------|-------------|-----------|`)
+
+    const scoreTrend = current.trends.score
+    if (scoreTrend) {
+      const dirEmoji = scoreTrend.direction === 'improving' ? '📈' : scoreTrend.direction === 'degrading' ? '📉' : '➡️'
+      lines.push(`| Score | ${dirEmoji} ${scoreTrend.direction} | ${scoreTrend.change_7d !== null ? formatDiff(scoreTrend.change_7d) : 'N/A'} | ${scoreTrend.avg_30d || 'N/A'} |`)
+    }
+
+    const perfTrend = current.trends.performance
+    if (perfTrend && perfTrend.avg_30d) {
+      const dirEmoji = perfTrend.direction === 'improving' ? '📈' : perfTrend.direction === 'degrading' ? '📉' : '➡️'
+      const change7d = perfTrend.change_7d !== null ? `${(perfTrend.change_7d / 1000).toFixed(1)}s` : 'N/A'
+      lines.push(`| Duration | ${dirEmoji} ${perfTrend.direction} | ${change7d} | ${(perfTrend.avg_30d / 1000).toFixed(1)}s |`)
+    }
+
+    lines.push('')
+    lines.push(`<sub>Based on ${current.trends.data.total_runs} runs</sub>`)
+    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'}`)
+
+  // Add trace link if available
+  if (current.meta?.trace_id) {
+    const traceUrl = current.extensions?.telemetry?.trace_url
+    if (traceUrl) {
+      lines.push(` | 🔍 [Trace](${traceUrl})`)
+    } else {
+      lines.push(` | 🔍 Trace: ${current.meta.trace_id}`)
+    }
+  }
+
   lines.push(`</sub>`)
 
   return lines.join('\n')

package/src/scripts/setup.mjs

@@ -79,6 +79,7 @@ export function parseArgs(args) {
     skipQualityStandard: false,
     syncWorkflows: false,
     syncHusky: false,
+    telemetryEnv: false,
     force: false,
     dryRun: false,
     help: false,
@@ -97,6 +98,8 @@ export function parseArgs(args) {
       options.syncWorkflows = true;
     } else if (arg === '--sync-husky') {
       options.syncHusky = true;
+    } else if (arg === '--telemetry-env') {
+      options.telemetryEnv = true;
     } else if (arg === '--force') {
       options.force = true;
     } else if (arg === '--dry-run') {
@@ -132,6 +135,7 @@ ${colors.yellow}OPTIONS:${colors.reset}
   --skip-quality-standard Don't create quality-standard.md
   --sync-workflows        Overwrite existing workflow files
   --sync-husky            Overwrite existing husky hooks
+  --telemetry-env         Generate .env.example with telemetry variables
   --force                 Overwrite all existing files
   --dry-run               Preview changes without modifying files
   --help, -h              Show this help message
@@ -146,6 +150,9 @@ ${colors.yellow}EXAMPLES:${colors.reset}
   # Update workflows only
   npx kabran-setup --sync-workflows
 
+  # Generate telemetry .env.example
+  npx kabran-setup --telemetry-env
+
   # Preview changes without modifying
   npx kabran-setup --dry-run
 
@@ -547,6 +554,79 @@ export function setupQualityStandard(projectDir, templatesDir, options) {
   return results;
 }
 
+/**
+ * Setup telemetry .env.example
+ * @param {string} projectDir - Project directory
+ * @param {string} templatesDir - Templates directory
+ * @param {object} options - Setup options
+ * @returns {object} Results
+ */
+export function setupTelemetryEnv(projectDir, templatesDir, options) {
+  const {force = false, dryRun = false} = options;
+
+  const results = {
+    created: 0,
+    overwritten: 0,
+    skipped: 0,
+  };
+
+  logInfo('Setting up telemetry .env.example...');
+
+  const src = join(templatesDir, 'telemetry', '.env.telemetry.example');
+  const dest = join(projectDir, '.env.example');
+
+  // Check if source template exists
+  if (!existsSync(src)) {
+    logWarn('Template not found: templates/telemetry/.env.telemetry.example');
+    return results;
+  }
+
+  // Check if destination exists
+  const destExists = existsSync(dest);
+
+  if (destExists && !force) {
+    // If .env.example exists, append telemetry section if not present
+    const existingContent = readFileSync(dest, 'utf-8');
+
+    if (existingContent.includes('Kabran Telemetry Configuration')) {
+      if (dryRun) {
+        logDry('Would skip .env.example (telemetry section already present)');
+      } else {
+        logSkip('.env.example (telemetry section already present)');
+      }
+      results.skipped = 1;
+      return results;
+    }
+
+    // Append telemetry section
+    const telemetryContent = readFileSync(src, 'utf-8');
+
+    if (dryRun) {
+      logDry('Would append telemetry section to .env.example');
+      results.overwritten = 1;
+      return results;
+    }
+
+    const newContent = existingContent.trimEnd() + '\n\n' + telemetryContent;
+    writeFileSync(dest, newContent, 'utf-8');
+    logSuccess('Appended telemetry section to: .env.example');
+    results.overwritten = 1;
+    return results;
+  }
+
+  const status = copyFile(src, dest, {overwrite: force, dryRun});
+
+  if (status === 'created' || status === 'would_create') {
+    results.created = 1;
+  } else if (status === 'overwritten' || status === 'would_overwrite') {
+    results.overwritten = 1;
+  } else {
+    results.skipped = 1;
+  }
+
+  return results;
+}
+
 /**
  * Run setup
  * @param {string} projectDir - Project directory
@@ -561,6 +641,7 @@ export function runSetup(projectDir, options) {
     husky: {created: 0, overwritten: 0, skipped: 0},
     configs: {created: 0, overwritten: 0, skipped: 0},
     qualityStandard: {created: 0, overwritten: 0, skipped: 0},
+    telemetryEnv: {created: 0, overwritten: 0, skipped: 0},
   };
 
   console.log('');
@@ -592,11 +673,17 @@ export function runSetup(projectDir, options) {
   }
 
   // Setup quality-standard.md (unless skipped or in sync mode)
-  if (!options.skipQualityStandard && !isSyncMode) {
+  if (!options.skipQualityStandard && !isSyncMode && !options.telemetryEnv) {
     summary.qualityStandard = setupQualityStandard(projectDir, templatesDir, options);
     console.log('');
   }
 
+  // Setup telemetry .env.example (only when explicitly requested)
+  if (options.telemetryEnv) {
+    summary.telemetryEnv = setupTelemetryEnv(projectDir, templatesDir, options);
+    console.log('');
+  }
+
   return summary;
 }
 
@@ -609,10 +696,10 @@ export function printSummary(summary) {
   console.log(`${colors.cyan}=== Setup Summary ===${colors.reset}`);
 
   const total = {
-    created: summary.workflows.created + summary.husky.created + summary.configs.created + summary.qualityStandard.created,
+    created: summary.workflows.created + summary.husky.created + summary.configs.created + summary.qualityStandard.created + summary.telemetryEnv.created,
     overwritten:
-      summary.workflows.overwritten + summary.husky.overwritten + summary.configs.overwritten + summary.qualityStandard.overwritten,
-    skipped: summary.workflows.skipped + summary.husky.skipped + summary.configs.skipped + summary.qualityStandard.skipped,
+      summary.workflows.overwritten + summary.husky.overwritten + summary.configs.overwritten + summary.qualityStandard.overwritten + summary.telemetryEnv.overwritten,
+    skipped: summary.workflows.skipped + summary.husky.skipped + summary.configs.skipped + summary.qualityStandard.skipped + summary.telemetryEnv.skipped,
   };
 
   if (total.created > 0) {