@kabran-tecnologia/kabran-config 1.10.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kabran-tecnologia/kabran-config",
-  "version": "1.10.0",
+  "version": "2.0.0",
   "description": "Shared quality configurations, enforcement scripts, and CI/CD tooling for Kabran projects",
   "author": "Kabran",
   "license": "MIT",
@@ -9,6 +9,7 @@
     "access": "public"
   },
   "bin": {
+    "kabran": "src/cli/kabran.mjs",
     "kabran-setup": "src/scripts/setup.mjs",
     "kabran-ci": "src/scripts/ci/ci-runner.sh",
     "kabran-pr-comment": "src/scripts/pr-quality-comment.mjs",
@@ -16,6 +17,11 @@
     "kabran-coverage": "src/scripts/traceability/coverage-report.sh"
   },
   "exports": {
+    "./core/config-loader": "./src/core/config-loader.mjs",
+    "./cli/commands/check": "./src/cli/commands/check.mjs",
+    "./cli/commands/test": "./src/cli/commands/test.mjs",
+    "./cli/commands/ci": "./src/cli/commands/ci.mjs",
+    "./cli/commands/build": "./src/cli/commands/build.mjs",
     "./eslint": "./src/eslint.mjs",
     "./eslint/node": "./src/eslint-node.mjs",
     "./eslint/react": "./src/eslint-react.mjs",

package/src/cli/commands/build.mjs

@@ -0,0 +1,54 @@
+/**
+ * Build Command
+ *
+ * Runs the project build process.
+ *
+ * @module cli/commands/build
+ */
+
+import {spawn} from 'node:child_process';
+
+/**
+ * Run a shell command and return exit code
+ * @param {string} cmd - Command to run
+ * @returns {Promise<number>} Exit code
+ */
+function runCommand(cmd) {
+  return new Promise(resolve => {
+    const proc = spawn('sh', ['-c', cmd], {stdio: 'inherit'});
+    proc.on('close', code => resolve(code ?? 0));
+    proc.on('error', () => resolve(1));
+  });
+}
+
+/**
+ * Run the build process
+ * @param {object} config - Project configuration from kabran.config.mjs
+ * @param {string[]} _args - CLI arguments (unused for now)
+ * @returns {Promise<number>} Exit code (0 = success, 1 = failure)
+ */
+export async function runBuild(config, _args) {
+  const buildConfig = config.build;
+
+  if (!buildConfig?.command) {
+    console.log('\n[Build] Skipped (not configured)');
+    console.log('   Add build.command to kabran.config.mjs to enable');
+    return 0;
+  }
+
+  console.log('='.repeat(50));
+  console.log('Running build');
+  console.log('='.repeat(50));
+
+  console.log(`\n[Build] ${buildConfig.command}`);
+  const code = await runCommand(buildConfig.command);
+
+  console.log('\n' + '-'.repeat(50));
+  if (code === 0) {
+    console.log('Build: PASSED');
+  } else {
+    console.log('Build: FAILED');
+  }
+
+  return code;
+}

package/src/cli/commands/check.mjs

@@ -0,0 +1,107 @@
+/**
+ * Check Command (L1 - Base of Quality Pyramid)
+ *
+ * Runs static analysis checks:
+ * - Lint (ESLint)
+ * - Types (TypeScript)
+ * - Format (Prettier)
+ * - Validators (README, ENV, Quality Standard)
+ *
+ * @module cli/commands/check
+ */
+
+import {spawn} from 'node:child_process';
+import {validateReadme} from '../../scripts/readme-validator.mjs';
+import {validateEnv} from '../../scripts/env-validator.mjs';
+import {validate as validateQuality} from '../../scripts/quality-standard-validator.mjs';
+
+/**
+ * Run a shell command and return exit code
+ * @param {string} name - Step name for display
+ * @param {string} cmd - Command to run
+ * @returns {Promise<number>} Exit code
+ */
+function runCommand(name, cmd) {
+  return new Promise(resolve => {
+    console.log(`\n[${name}] ${cmd}`);
+    const proc = spawn('sh', ['-c', cmd], {stdio: 'inherit'});
+    proc.on('close', code => resolve(code ?? 0));
+    proc.on('error', () => resolve(1));
+  });
+}
+
+/**
+ * Run L1 checks (static analysis)
+ * @param {object} config - Project configuration from kabran.config.mjs
+ * @param {string[]} args - CLI arguments
+ * @returns {Promise<number>} Exit code (0 = success, 1 = failure)
+ */
+export async function runCheck(config, args) {
+  const fix = args.includes('--fix');
+  let failed = 0;
+
+  console.log('='.repeat(50));
+  console.log('Running L1 checks (Static Analysis)');
+  console.log('='.repeat(50));
+
+  // 1. Lint
+  if (config.check?.lint) {
+    const cmd = fix ? `${config.check.lint} --fix` : config.check.lint;
+    const code = await runCommand('Lint', cmd);
+    if (code !== 0) failed++;
+  } else {
+    console.log('\n[Lint] Skipped (not configured)');
+  }
+
+  // 2. Types
+  if (config.check?.types) {
+    const code = await runCommand('Types', config.check.types);
+    if (code !== 0) failed++;
+  } else {
+    console.log('\n[Types] Skipped (not configured)');
+  }
+
+  // 3. Format
+  if (config.check?.format) {
+    const cmd = fix ? config.check.format.replace('--check', '--write') : config.check.format;
+    const code = await runCommand('Format', cmd);
+    if (code !== 0) failed++;
+  } else {
+    console.log('\n[Format] Skipped (not configured)');
+  }
+
+  // 4. Validators
+  console.log('\n' + '='.repeat(50));
+  console.log('Running validators');
+  console.log('='.repeat(50));
+
+  // README validator
+  console.log('\n--- README Validator ---');
+  const readme = await validateReadme(process.cwd(), true);
+  console.log(`Result: ${readme.valid ? 'PASS' : 'FAIL'}`);
+  if (!readme.valid) failed++;
+
+  // ENV validator
+  console.log('\n--- ENV Validator ---');
+  const env = await validateEnv(process.cwd(), true);
+  console.log(`Result: ${env.valid ? 'PASS' : 'FAIL'}`);
+  if (!env.valid) failed++;
+
+  // Quality Standard validator
+  console.log('\n--- Quality Standard Validator ---');
+  const quality = await validateQuality(process.cwd(), true);
+  console.log(`Result: ${quality.valid ? 'PASS' : 'FAIL'}`);
+  if (!quality.valid) failed++;
+
+  // Summary
+  console.log('\n' + '='.repeat(50));
+  if (failed === 0) {
+    console.log('L1 checks: PASSED');
+    console.log('='.repeat(50));
+    return 0;
+  } else {
+    console.log(`L1 checks: FAILED (${failed} error${failed > 1 ? 's' : ''})`);
+    console.log('='.repeat(50));
+    return 1;
+  }
+}

package/src/cli/commands/ci.mjs

@@ -0,0 +1,109 @@
+/**
+ * CI Command - Full Pipeline Execution
+ *
+ * Runs the complete CI pipeline with configurable steps.
+ * Default steps: check → test:unit → test:integration → build
+ *
+ * @module cli/commands/ci
+ */
+
+import {runCheck} from './check.mjs';
+import {runTest} from './test.mjs';
+import {runBuild} from './build.mjs';
+
+/**
+ * Run the full CI pipeline
+ * @param {object} config - Project configuration from kabran.config.mjs
+ * @param {string[]} args - CLI arguments
+ * @returns {Promise<number>} Exit code (0 = success, 1 = failure)
+ */
+export async function runCI(config, args) {
+  // Get pipeline steps from config or use defaults
+  const steps = config.ci?.steps || ['check', 'test:unit', 'build'];
+
+  console.log('╔' + '═'.repeat(50) + '╗');
+  console.log('║' + '         KABRAN CI PIPELINE'.padEnd(50) + '║');
+  console.log('╚' + '═'.repeat(50) + '╝');
+  console.log();
+  console.log(`Steps: ${steps.join(' → ')}`);
+  console.log();
+
+  const startTime = Date.now();
+  const results = [];
+
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    const stepNum = i + 1;
+
+    console.log();
+    console.log('┌' + '─'.repeat(50) + '┐');
+    console.log(`│ Step ${stepNum}/${steps.length}: ${step.padEnd(42)}│`);
+    console.log('└' + '─'.repeat(50) + '┘');
+
+    const stepStart = Date.now();
+    let code = 0;
+
+    try {
+      if (step === 'check') {
+        code = await runCheck(config, []);
+      } else if (step.startsWith('test:')) {
+        const level = step.replace('test:', '');
+        code = await runTest(level, config, []);
+      } else if (step === 'test') {
+        code = await runTest('all', config, []);
+      } else if (step === 'build') {
+        code = await runBuild(config, []);
+      } else {
+        console.error(`Unknown step: ${step}`);
+        code = 1;
+      }
+    } catch (error) {
+      console.error(`Step "${step}" threw error: ${error.message}`);
+      code = 1;
+    }
+
+    const stepDuration = ((Date.now() - stepStart) / 1000).toFixed(2);
+    results.push({step, code, duration: stepDuration});
+
+    if (code !== 0) {
+      console.log();
+      console.log('╔' + '═'.repeat(50) + '╗');
+      console.log('║' + `  PIPELINE FAILED at step: ${step}`.padEnd(50) + '║');
+      console.log('╚' + '═'.repeat(50) + '╝');
+      console.log();
+      printSummary(results, startTime);
+      return 1;
+    }
+  }
+
+  // Success
+  console.log();
+  console.log('╔' + '═'.repeat(50) + '╗');
+  console.log('║' + '  PIPELINE COMPLETED SUCCESSFULLY'.padEnd(50) + '║');
+  console.log('╚' + '═'.repeat(50) + '╝');
+  console.log();
+  printSummary(results, startTime);
+
+  return 0;
+}
+
+/**
+ * Print pipeline execution summary
+ * @param {Array<{step: string, code: number, duration: string}>} results - Step results
+ * @param {number} startTime - Pipeline start timestamp
+ */
+function printSummary(results, startTime) {
+  const totalDuration = ((Date.now() - startTime) / 1000).toFixed(2);
+
+  console.log('Summary:');
+  console.log('─'.repeat(50));
+
+  for (const {step, code, duration} of results) {
+    const status = code === 0 ? '✓ PASS' : '✗ FAIL';
+    console.log(`  ${status}  ${step.padEnd(25)} ${duration}s`);
+  }
+
+  console.log('─'.repeat(50));
+  console.log(`  Total time: ${totalDuration}s`);
+  console.log();
+}

package/src/cli/commands/test.mjs

@@ -0,0 +1,133 @@
+/**
+ * Test Command (L2-L4 of Quality Pyramid)
+ *
+ * Runs tests at different levels:
+ * - L2: Unit tests
+ * - L3: Integration tests
+ * - L4: E2E tests
+ *
+ * @module cli/commands/test
+ */
+
+import {spawn} from 'node:child_process';
+
+/**
+ * Run a shell command and return exit code
+ * @param {string} cmd - Command to run
+ * @returns {Promise<number>} Exit code
+ */
+function runCommand(cmd) {
+  return new Promise(resolve => {
+    const proc = spawn('sh', ['-c', cmd], {stdio: 'inherit'});
+    proc.on('close', code => resolve(code ?? 0));
+    proc.on('error', () => resolve(1));
+  });
+}
+
+/**
+ * Get pyramid level number from test type
+ * @param {string} level - Test level (unit, integration, e2e)
+ * @returns {string} Level number
+ */
+function levelNumber(level) {
+  return {unit: '2', integration: '3', e2e: '4'}[level] || '?';
+}
+
+/**
+ * Run tests at specified level
+ * @param {string} level - Test level (unit, integration, e2e, all)
+ * @param {object} config - Project configuration from kabran.config.mjs
+ * @param {string[]} args - CLI arguments
+ * @returns {Promise<number>} Exit code (0 = success, 1 = failure)
+ */
+export async function runTest(level, config, args) {
+  const watch = args.includes('--watch');
+  const coverage = args.includes('--coverage');
+
+  // Run all tests (unit + integration)
+  if (level === 'all') {
+    console.log('='.repeat(50));
+    console.log('Running all tests (L2 + L3)');
+    console.log('='.repeat(50));
+
+    let failed = 0;
+
+    // Run unit tests
+    const unitCode = await runTest('unit', config, args);
+    if (unitCode !== 0) failed++;
+
+    // Run integration tests
+    const integrationCode = await runTest('integration', config, args);
+    if (integrationCode !== 0) failed++;
+
+    console.log('\n' + '='.repeat(50));
+    if (failed === 0) {
+      console.log('All tests: PASSED');
+    } else {
+      console.log(`All tests: FAILED (${failed} level${failed > 1 ? 's' : ''} failed)`);
+    }
+    console.log('='.repeat(50));
+
+    return failed > 0 ? 1 : 0;
+  }
+
+  // Get test configuration for this level
+  const testConfig = config.test?.[level];
+
+  if (!testConfig) {
+    console.log(`\n[test:${level}] Skipped (not configured)`);
+    return 0;
+  }
+
+  console.log('\n' + '='.repeat(50));
+  console.log(`Running L${levelNumber(level)} tests: ${level}`);
+  if (testConfig.doppler) {
+    console.log('[Doppler] Secrets injection enabled');
+  }
+  console.log('='.repeat(50));
+
+  // Setup phase (if defined)
+  if (testConfig.setup) {
+    console.log(`\n[Setup] ${testConfig.setup}`);
+    const setupCode = await runCommand(testConfig.setup);
+    if (setupCode !== 0) {
+      console.error('Setup failed');
+      return 1;
+    }
+  }
+
+  // Build test command with options
+  let cmd = testConfig.command;
+
+  if (watch && !cmd.includes('--watch')) {
+    cmd += ' --watch';
+  }
+
+  if (coverage && !cmd.includes('--coverage')) {
+    cmd += ' --coverage';
+
+    // Add coverage threshold if configured
+    if (testConfig.coverage?.threshold) {
+      cmd += ` --coverage.thresholds.statements=${testConfig.coverage.threshold}`;
+    }
+  }
+
+  console.log(`\n[Test] ${cmd}`);
+  const testCode = await runCommand(cmd);
+
+  // Teardown phase (if defined, always run even if tests fail)
+  if (testConfig.teardown) {
+    console.log(`\n[Teardown] ${testConfig.teardown}`);
+    await runCommand(testConfig.teardown);
+  }
+
+  // Result
+  console.log('\n' + '-'.repeat(50));
+  if (testCode === 0) {
+    console.log(`L${levelNumber(level)} tests (${level}): PASSED`);
+  } else {
+    console.log(`L${levelNumber(level)} tests (${level}): FAILED`);
+  }
+
+  return testCode;
+}

package/src/cli/kabran.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+
+/**
+ * Kabran CLI - Unified command runner organized by quality pyramid levels
+ *
+ * L1 (Base): Static analysis - lint, types, format, validators
+ * L2: Unit tests
+ * L3: Integration tests
+ * L4: E2E tests
+ *
+ * Usage:
+ *   kabran <command> [options]
+ *
+ * Commands:
+ *   check              Run L1 checks (lint, types, format, validators)
+ *   test:unit          Run L2 unit tests
+ *   test:integration   Run L3 integration tests
+ *   test:e2e           Run L4 E2E tests
+ *   test               Run L2 + L3 tests
+ *   ci                 Run full CI pipeline
+ *   build              Run build
+ */
+
+import {loadConfig} from '../core/config-loader.mjs';
+import {runCheck} from './commands/check.mjs';
+import {runTest} from './commands/test.mjs';
+import {runCI} from './commands/ci.mjs';
+import {runBuild} from './commands/build.mjs';
+
+const VERSION = '1.0.0';
+
+/**
+ * Show help message
+ */
+function showHelp() {
+  console.log(`
+kabran - Unified quality CLI for Kabran projects
+
+Usage: kabran <command> [options]
+
+Commands:
+  check              Run L1 checks (lint, types, format, validators)
+  test:unit          Run L2 unit tests
+  test:integration   Run L3 integration tests
+  test:e2e           Run L4 E2E tests
+  test               Run L2 + L3 tests
+  ci                 Run full CI pipeline
+  build              Run build
+
+Options:
+  --fix              Auto-fix issues (check command)
+  --watch            Watch mode (test commands)
+  --coverage         Generate coverage report
+  --help, -h         Show this help
+  --version, -v      Show version
+
+Quality Pyramid:
+                  /\\
+                 /  \\
+                / L4  \\          kabran test:e2e
+               /       \\
+              /__________\\
+             /            \\
+            /      L3      \\     kabran test:integration
+           /                \\
+          /__________________\\
+         /                    \\
+        /         L2           \\   kabran test:unit
+       /                        \\
+      /__________________________\\
+     /                            \\
+    /            L1                \\  kabran check
+   /                                \\
+  /__________________________________\\
+
+Examples:
+  kabran check              # Run lint, types, format, validators
+  kabran check --fix        # Run checks with auto-fix
+  kabran test:unit          # Run unit tests
+  kabran test --coverage    # Run all tests with coverage
+  kabran ci                 # Run full CI pipeline
+`);
+}
+
+/**
+ * Show version
+ */
+function showVersion() {
+  console.log(`kabran v${VERSION}`);
+}
+
+/**
+ * Main CLI entry point
+ */
+async function main() {
+  const [command, ...args] = process.argv.slice(2);
+
+  // Handle help and version flags
+  if (!command || command === '--help' || command === '-h') {
+    showHelp();
+    process.exit(0);
+  }
+
+  if (command === '--version' || command === '-v') {
+    showVersion();
+    process.exit(0);
+  }
+
+  // Load project configuration
+  let config;
+  try {
+    config = await loadConfig();
+  } catch (error) {
+    console.error(`Failed to load config: ${error.message}`);
+    process.exit(1);
+  }
+
+  // Command routing
+  const commands = {
+    check: () => runCheck(config, args),
+    'test:unit': () => runTest('unit', config, args),
+    'test:integration': () => runTest('integration', config, args),
+    'test:e2e': () => runTest('e2e', config, args),
+    test: () => runTest('all', config, args),
+    ci: () => runCI(config, args),
+    build: () => runBuild(config, args),
+  };
+
+  if (commands[command]) {
+    try {
+      const exitCode = await commands[command]();
+      process.exit(exitCode);
+    } catch (error) {
+      console.error(`Command failed: ${error.message}`);
+      process.exit(1);
+    }
+  } else {
+    console.error(`Unknown command: ${command}`);
+    console.error('Run "kabran --help" for available commands.');
+    process.exit(1);
+  }
+}
+
+main();