@kabran-tecnologia/kabran-config 1.9.0 → 1.12.0

package/src/core/config-loader.mjs

@@ -0,0 +1,154 @@
+/**
+ * Kabran Config Loader
+ *
+ * Loads project configuration from kabran.config.mjs/js/json with fallback to defaults.
+ * Enables projects to customize validator behavior without modifying kabran-config.
+ *
+ * @module config-loader
+ */
+
+import {existsSync} from 'node:fs';
+import {readFile} from 'node:fs/promises';
+import {join} from 'node:path';
+import {pathToFileURL} from 'node:url';
+
+/**
+ * Default configuration values.
+ * These match the current hardcoded values in validators to ensure backwards compatibility.
+ */
+export const DEFAULTS = {
+  readme: {
+    required: ['Installation', 'Usage', 'License'],
+    recommended: ['Development', 'Testing', 'Contributing'],
+  },
+  env: {
+    requireExample: true,
+    detectPatterns: ['process.env', 'import.meta.env', 'Deno.env', 'os.getenv', '$_ENV'],
+  },
+  quality: {
+    standardPath: 'docs/quality/001-quality-standard.md',
+  },
+};
+
+/**
+ * Configuration file names to search for, in priority order.
+ */
+const CONFIG_FILES = ['kabran.config.mjs', 'kabran.config.js', 'kabran.config.json'];
+
+/**
+ * Deep merge two objects. Arrays are replaced, not merged.
+ * @param {object} target - Base object
+ * @param {object} source - Object to merge in
+ * @returns {object} Merged object
+ */
+function deepMerge(target, source) {
+  const result = {...target};
+
+  for (const key of Object.keys(source)) {
+    const sourceValue = source[key];
+    const targetValue = target[key];
+
+    if (sourceValue === null || sourceValue === undefined) {
+      continue;
+    }
+
+    if (
+      typeof sourceValue === 'object' &&
+      !Array.isArray(sourceValue) &&
+      typeof targetValue === 'object' &&
+      !Array.isArray(targetValue)
+    ) {
+      result[key] = deepMerge(targetValue, sourceValue);
+    } else {
+      result[key] = sourceValue;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Load JSON configuration file.
+ * @param {string} configPath - Path to JSON config file
+ * @returns {Promise<object>} Parsed configuration
+ */
+async function loadJsonConfig(configPath) {
+  const content = await readFile(configPath, 'utf-8');
+  return JSON.parse(content);
+}
+
+/**
+ * Load JavaScript/ESM configuration file.
+ * @param {string} configPath - Path to JS/MJS config file
+ * @returns {Promise<object>} Parsed configuration
+ */
+async function loadJsConfig(configPath) {
+  const configUrl = pathToFileURL(configPath).href;
+  const module = await import(configUrl);
+  return module.default || module;
+}
+
+/**
+ * Load project configuration with fallback to defaults.
+ *
+ * Searches for configuration files in order:
+ * 1. kabran.config.mjs
+ * 2. kabran.config.js
+ * 3. kabran.config.json
+ *
+ * If no config file is found, returns DEFAULTS.
+ *
+ * @param {string} [cwd=process.cwd()] - Directory to search for config
+ * @returns {Promise<object>} Merged configuration
+ *
+ * @example
+ * const config = await loadConfig();
+ * console.log(config.readme.required); // ['Installation', 'Usage', 'License']
+ *
+ * @example
+ * // With custom config in kabran.config.mjs:
+ * // export default { readme: { required: ['Setup', 'API'] } }
+ * const config = await loadConfig('/path/to/project');
+ * console.log(config.readme.required); // ['Setup', 'API']
+ */
+export async function loadConfig(cwd = process.cwd()) {
+  for (const fileName of CONFIG_FILES) {
+    const configPath = join(cwd, fileName);
+
+    if (existsSync(configPath)) {
+      try {
+        let projectConfig;
+
+        if (fileName.endsWith('.json')) {
+          projectConfig = await loadJsonConfig(configPath);
+        } else {
+          projectConfig = await loadJsConfig(configPath);
+        }
+
+        return deepMerge(DEFAULTS, projectConfig);
+      } catch (error) {
+        // Log warning but continue with defaults
+        console.warn(`Warning: Failed to load ${fileName}: ${error.message}`);
+      }
+    }
+  }
+
+  return DEFAULTS;
+}
+
+/**
+ * Check if a config file exists in the given directory.
+ * @param {string} [cwd=process.cwd()] - Directory to check
+ * @returns {{exists: boolean, path?: string, name?: string}} Config file info
+ */
+export function findConfigFile(cwd = process.cwd()) {
+  for (const fileName of CONFIG_FILES) {
+    const configPath = join(cwd, fileName);
+
+    if (existsSync(configPath)) {
+      return {exists: true, path: configPath, name: fileName};
+    }
+  }
+
+  return {exists: false};
+}

package/src/schemas/ci-result.v2.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://kabran.dev/schemas/ci-result.v2.json",
+  "$id": "ci-result.v2.json",
   "title": "CI Result Schema v2",
   "description": "Unified schema for CI/CD results with quality metrics, timing, and observability data",
   "type": "object",

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

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # ==============================================================================
 # Kabran CI Core - Shared Functions
-# Part of @kabran-owner/kabran-config
+# Part of @kabran-tecnologia/kabran-config
 # ==============================================================================
 
 # Version
@@ -590,6 +590,279 @@ export_ci_data() {
   log_debug "CI data exported to: $output_file"
 }
 
+# ==============================================================================
+# OpenTelemetry Metrics Export
+# ==============================================================================
+
+# Export CI metrics to OTel Collector via OTLP HTTP
+# Usage: export_ci_metrics_to_otel "$CI_DATA_FILE"
+# Environment: OTEL_ENDPOINT must be set (e.g., http://localhost:4318)
+# Returns: 0 on success, 1 on failure (but never fails the build due to || true usage)
+export_ci_metrics_to_otel() {
+  local ci_data_file="${1:-}"
+
+  # Check if OTEL_ENDPOINT is configured
+  if [ -z "${OTEL_ENDPOINT:-}" ]; then
+    log_debug "OTEL_ENDPOINT not set, skipping metrics export"
+    return 0
+  fi
+
+  # Validate input file
+  if [ -z "$ci_data_file" ] || [ ! -f "$ci_data_file" ]; then
+    log_warn "CI data file not found: $ci_data_file"
+    return 1
+  fi
+
+  # Check for curl
+  if ! command -v curl &>/dev/null; then
+    log_warn "curl not available, skipping OTel metrics export"
+    return 1
+  fi
+
+  log_info "Exporting CI metrics to OTel Collector..."
+  log_debug "  Endpoint: $OTEL_ENDPOINT"
+  log_debug "  Data file: $ci_data_file"
+
+  # Extract metrics from CI data
+  local total_ms steps_json project_name trace_id ci_passed
+  total_ms=$(jq -r '.timing.total_ms // 0' "$ci_data_file" 2>/dev/null)
+  steps_json=$(jq -c '.steps // []' "$ci_data_file" 2>/dev/null)
+  project_name=$(jq -r '.project.name // "unknown"' "$ci_data_file" 2>/dev/null)
+  trace_id=$(jq -r '.trace_context.trace_id // ""' "$ci_data_file" 2>/dev/null)
+
+  # Determine overall status
+  local failed_count
+  failed_count=$(echo "$steps_json" | jq '[.[] | select(.status == "fail")] | length' 2>/dev/null || echo "0")
+  if [ "$failed_count" -gt 0 ]; then
+    ci_passed="false"
+  else
+    ci_passed="true"
+  fi
+
+  # Get timestamp in nanoseconds (Unix epoch)
+  local timestamp_ns
+  timestamp_ns=$(date +%s)000000000
+
+  # Build OTLP metrics payload
+  local otlp_payload
+  otlp_payload=$(build_otlp_metrics_payload \
+    "$project_name" \
+    "$total_ms" \
+    "$ci_passed" \
+    "$steps_json" \
+    "$timestamp_ns" \
+    "$trace_id")
+
+  if [ -z "$otlp_payload" ] || [ "$otlp_payload" = "null" ]; then
+    log_warn "Failed to build OTLP payload"
+    return 1
+  fi
+
+  # Send to OTel Collector with aggressive timeouts
+  # --connect-timeout 1: max 1 second to establish connection
+  # --max-time 5: max 5 seconds total for the request
+  # -f: fail silently on HTTP errors
+  local otel_metrics_endpoint="${OTEL_ENDPOINT}/v1/metrics"
+
+  log_debug "Sending metrics to: $otel_metrics_endpoint"
+
+  local http_code
+  http_code=$(curl -s -o /dev/null -w "%{http_code}" \
+    --connect-timeout 1 \
+    --max-time 5 \
+    -X POST \
+    -H "Content-Type: application/json" \
+    -d "$otlp_payload" \
+    "$otel_metrics_endpoint" 2>/dev/null) || {
+      log_warn "Failed to send metrics to OTel Collector (connection error)"
+      return 1
+    }
+
+  if [ "$http_code" -ge 200 ] && [ "$http_code" -lt 300 ]; then
+    log_success "CI metrics exported to OTel Collector (HTTP $http_code)"
+    return 0
+  else
+    log_warn "OTel Collector returned HTTP $http_code"
+    return 1
+  fi
+}
+
+# Build OTLP JSON payload for metrics
+# Usage: build_otlp_metrics_payload "$project" "$duration_ms" "$passed" "$steps_json" "$timestamp_ns" "$trace_id"
+build_otlp_metrics_payload() {
+  local project="$1"
+  local duration_ms="$2"
+  local passed="$3"
+  local steps_json="$4"
+  local timestamp_ns="$5"
+  local trace_id="${6:-}"
+
+  # Service attributes
+  local service_name="ci-runner"
+  local service_version="${CI_CORE_VERSION:-unknown}"
+
+  # Count steps by status
+  local pass_count fail_count skip_count
+  pass_count=$(echo "$steps_json" | jq '[.[] | select(.status == "pass")] | length' 2>/dev/null || echo "0")
+  fail_count=$(echo "$steps_json" | jq '[.[] | select(.status == "fail")] | length' 2>/dev/null || echo "0")
+  skip_count=$(echo "$steps_json" | jq '[.[] | select(.status == "skip")] | length' 2>/dev/null || echo "0")
+
+  # Build step duration data points
+  local step_duration_points
+  step_duration_points=$(echo "$steps_json" | jq -c --arg ts "$timestamp_ns" '
+    [.[] | select(.status != "skip") | {
+      attributes: ([
+        {key: "step.name", value: {stringValue: .name}},
+        {key: "step.category", value: {stringValue: (.category // "custom")}},
+        {key: "step.status", value: {stringValue: .status}}
+      ] + (if (.component // "") != "" then [{key: "step.component", value: {stringValue: .component}}] else [] end)),
+      startTimeUnixNano: $ts,
+      timeUnixNano: $ts,
+      asDouble: .duration_ms
+    }]
+  ' 2>/dev/null || echo "[]")
+
+  # Build resource attributes (conditionally include trace_id)
+  local resource_attributes
+  if [ -n "$trace_id" ]; then
+    resource_attributes=$(jq -n \
+      --arg service_name "$service_name" \
+      --arg service_version "$service_version" \
+      --arg project "$project" \
+      --arg trace_id "$trace_id" \
+      '[
+        {key: "service.name", value: {stringValue: $service_name}},
+        {key: "service.version", value: {stringValue: $service_version}},
+        {key: "project.name", value: {stringValue: $project}},
+        {key: "trace.id", value: {stringValue: $trace_id}}
+      ]')
+  else
+    resource_attributes=$(jq -n \
+      --arg service_name "$service_name" \
+      --arg service_version "$service_version" \
+      --arg project "$project" \
+      '[
+        {key: "service.name", value: {stringValue: $service_name}},
+        {key: "service.version", value: {stringValue: $service_version}},
+        {key: "project.name", value: {stringValue: $project}}
+      ]')
+  fi
+
+  # Determine status string
+  local status_str="fail"
+  if [ "$passed" = "true" ]; then
+    status_str="pass"
+  fi
+
+  # Build the full OTLP payload
+  jq -n \
+    --arg service_version "$service_version" \
+    --arg project "$project" \
+    --arg timestamp_ns "$timestamp_ns" \
+    --arg status_str "$status_str" \
+    --argjson duration_ms "$duration_ms" \
+    --argjson pass_count "$pass_count" \
+    --argjson fail_count "$fail_count" \
+    --argjson skip_count "$skip_count" \
+    --argjson step_duration_points "$step_duration_points" \
+    --argjson resource_attributes "$resource_attributes" \
+    '{
+      resourceMetrics: [{
+        resource: {
+          attributes: $resource_attributes
+        },
+        scopeMetrics: [{
+          scope: {
+            name: "kabran-config/ci-runner",
+            version: $service_version
+          },
+          metrics: [
+            {
+              name: "ci.build.duration",
+              description: "Total duration of CI build in milliseconds",
+              unit: "ms",
+              gauge: {
+                dataPoints: [{
+                  attributes: [
+                    {key: "project", value: {stringValue: $project}},
+                    {key: "status", value: {stringValue: $status_str}}
+                  ],
+                  startTimeUnixNano: $timestamp_ns,
+                  timeUnixNano: $timestamp_ns,
+                  asDouble: $duration_ms
+                }]
+              }
+            },
+            {
+              name: "ci.build.status",
+              description: "CI build status counter (1 = occurrence)",
+              unit: "1",
+              sum: {
+                dataPoints: [{
+                  attributes: [
+                    {key: "project", value: {stringValue: $project}},
+                    {key: "status", value: {stringValue: $status_str}}
+                  ],
+                  startTimeUnixNano: $timestamp_ns,
+                  timeUnixNano: $timestamp_ns,
+                  asInt: "1"
+                }],
+                aggregationTemporality: 2,
+                isMonotonic: true
+              }
+            },
+            {
+              name: "ci.step.count",
+              description: "Count of CI steps by status",
+              unit: "1",
+              sum: {
+                dataPoints: [
+                  {
+                    attributes: [
+                      {key: "project", value: {stringValue: $project}},
+                      {key: "status", value: {stringValue: "pass"}}
+                    ],
+                    startTimeUnixNano: $timestamp_ns,
+                    timeUnixNano: $timestamp_ns,
+                    asInt: ($pass_count | tostring)
+                  },
+                  {
+                    attributes: [
+                      {key: "project", value: {stringValue: $project}},
+                      {key: "status", value: {stringValue: "fail"}}
+                    ],
+                    startTimeUnixNano: $timestamp_ns,
+                    timeUnixNano: $timestamp_ns,
+                    asInt: ($fail_count | tostring)
+                  },
+                  {
+                    attributes: [
+                      {key: "project", value: {stringValue: $project}},
+                      {key: "status", value: {stringValue: "skip"}}
+                    ],
+                    startTimeUnixNano: $timestamp_ns,
+                    timeUnixNano: $timestamp_ns,
+                    asInt: ($skip_count | tostring)
+                  }
+                ],
+                aggregationTemporality: 2,
+                isMonotonic: false
+              }
+            },
+            {
+              name: "ci.step.duration",
+              description: "Duration of individual CI steps in milliseconds",
+              unit: "ms",
+              gauge: {
+                dataPoints: $step_duration_points
+              }
+            }
+          ]
+        }]
+      }]
+    }'
+}
+
 # ==============================================================================
 # JSON Output Generation
 # ==============================================================================

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

@@ -31,6 +31,7 @@ Environment Variables:
   CI_OUTPUT_FILE      Output file for legacy v1 format
   CI_OUTPUT_FILE_V2   Output file for v2 format (default: docs/quality/ci-result.json)
   CI_CONFIG_FILE      Path to project ci-config.sh
+  OTEL_ENDPOINT       OTel Collector endpoint for metrics export (e.g., http://localhost:4318)
 
 Examples:
   # Run all steps
@@ -232,6 +233,14 @@ if [ "$USE_V2" = "true" ]; then
     generate_ci_json "$OUTPUT_FILE" "$CI_PASSED" "$FAILED" "$PROJECT_NAME" "$METADATA"
   fi
 
+  # ==============================================================================
+  # Export Metrics to OTel Collector (if configured)
+  # ==============================================================================
+  # Fail-safe: telemetry failures NEVER fail the build (RN-01)
+  if [ -n "${OTEL_ENDPOINT:-}" ]; then
+    export_ci_metrics_to_otel "$INTERMEDIATE_FILE" || true
+  fi
+
   # Cleanup
   rm -f "$INTERMEDIATE_FILE"
 else

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

@@ -51,7 +51,7 @@ export function extractHistoryEntry(result) {
 export function loadHistory(filePath) {
   if (!existsSync(filePath)) {
     return {
-      $schema: 'https://kabran.dev/schemas/ci-result-history.json',
+      $schema: 'ci-result-history.json',
       version: '1.0.0',
       meta: {
         created_at: new Date().toISOString(),
@@ -75,7 +75,7 @@ export function loadHistory(filePath) {
   } catch (error) {
     // If file is corrupted, start fresh
     return {
-      $schema: 'https://kabran.dev/schemas/ci-result-history.json',
+      $schema: 'ci-result-history.json',
       version: '1.0.0',
       meta: {
         created_at: new Date().toISOString(),

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

@@ -436,7 +436,7 @@ export function createMinimalResult({ projectName, passed = true }) {
   const now = new Date().toISOString()
 
   return {
-    $schema: 'https://kabran.dev/schemas/ci-result.v2.json',
+    $schema: 'ci-result.v2.json',
     version: '1.0.0',
     meta: {
       generated_at: now,

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

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # ==============================================================================
 # Kabran Deploy Core - Shared Functions
-# Part of @kabran-owner/kabran-config
+# Part of @kabran-tecnologia/kabran-config
 # ==============================================================================
 
 # ==============================================================================

package/src/scripts/env-validator.mjs

@@ -18,9 +18,13 @@ import {exec} from 'node:child_process';
 import {promisify} from 'node:util';
 import fs from 'node:fs';
 import path from 'node:path';
+import {loadConfig, DEFAULTS} from '../core/config-loader.mjs';
 
 const execAsync = promisify(exec);
 
+// Default patterns for backwards compatibility
+export const DEFAULT_DETECT_PATTERNS = DEFAULTS.env.detectPatterns;
+
 /**
  * Check if .env file is tracked in git (CRITICAL SECURITY ISSUE)
  * @param {string} [cwd] - Directory to check (defaults to process.cwd())
@@ -40,17 +44,10 @@ export async function checkEnvInGit(cwd = process.cwd()) {
 /**
  * Detect if project uses environment variables
  * @param {string} [cwd] - Directory to check (defaults to process.cwd())
+ * @param {string[]} [patterns] - Patterns to search for (defaults to config patterns)
  * @returns {Promise<{usesEnv: boolean, files: string[]}>}
  */
-export async function detectEnvUsage(cwd = process.cwd()) {
-  const patterns = [
-    'process.env',      // Node.js
-    'os.getenv',        // Python
-    'import.meta.env',  // Vite/ESM
-    'Deno.env',         // Deno
-    '$_ENV',            // PHP
-  ];
-
+export async function detectEnvUsage(cwd = process.cwd(), patterns = DEFAULT_DETECT_PATTERNS) {
   const extensions = ['js', 'ts', 'jsx', 'tsx', 'mjs', 'cjs', 'py', 'php'];
   const extensionPattern = extensions.join(',');
 
@@ -157,6 +154,9 @@ export async function validateEnv(cwd = process.cwd(), silent = false) {
   const errors = [];
   const warnings = [];
 
+  // Load project config
+  const config = await loadConfig(cwd);
+
   // CRITICAL: Check if .env is committed to git
   log('Checking for .env in git...');
   const envInGit = await checkEnvInGit(cwd);
@@ -171,7 +171,7 @@ export async function validateEnv(cwd = process.cwd(), silent = false) {
 
   // Detect if project uses environment variables
   log('Detecting environment variable usage...');
-  const {usesEnv, files} = await detectEnvUsage(cwd);
+  const {usesEnv, files} = await detectEnvUsage(cwd, config.env.detectPatterns);
 
   if (!usesEnv) {
     log('  No environment variable usage detected');
@@ -236,9 +236,10 @@ export async function validateEnv(cwd = process.cwd(), silent = false) {
  * @returns {Promise<Object>} Check result for ci-result.json
  */
 export async function getEnvCheckResult(cwd = process.cwd()) {
+  const config = await loadConfig(cwd);
   const envInGit = await checkEnvInGit(cwd);
   const envExample = checkEnvExampleExists(cwd);
-  const {usesEnv} = await detectEnvUsage(cwd);
+  const {usesEnv} = await detectEnvUsage(cwd, config.env.detectPatterns);
 
   let undocumented = [];
   if (envExample.exists) {

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

@@ -103,7 +103,7 @@ async function runValidators(projectRoot, options = {}) {
 
   if (!options.skipReadme) {
     try {
-      results.readme = getReadmeCheckResult(projectRoot)
+      results.readme = await getReadmeCheckResult(projectRoot)
     } catch (err) {
       results.readme = { status: 'fail', error: err.message }
     }
@@ -119,7 +119,7 @@ async function runValidators(projectRoot, options = {}) {
 
   if (!options.skipQualityStandard) {
     try {
-      results.quality_standard = getQualityStandardCheckResult(projectRoot)
+      results.quality_standard = await getQualityStandardCheckResult(projectRoot)
     } catch (err) {
       results.quality_standard = { status: 'fail', error: err.message }
     }
@@ -216,7 +216,7 @@ export function generateCiResult(input) {
 
   // Build result object
   const result = {
-    $schema: 'https://kabran.dev/schemas/ci-result.v2.json',
+    $schema: 'ci-result.v2.json',
     version: '1.0.0',
 
     meta,