@kabran-tecnologia/kabran-config 1.9.0 → 1.12.0

package/src/scripts/quality-standard-validator.mjs

@@ -16,6 +16,10 @@
 
 import {existsSync, readFileSync} from 'node:fs';
 import {join} from 'node:path';
+import {loadConfig, DEFAULTS} from '../core/config-loader.mjs';
+
+// Default path for backwards compatibility
+export const DEFAULT_STANDARD_PATH = DEFAULTS.quality.standardPath;
 
 /**
  * Required sections that must be present in quality-standard.md
@@ -33,10 +37,11 @@ export const REQUIRED_FRONTMATTER = ['title', 'type', 'status'];
 /**
  * Find quality-standard.md file in the project
  * @param {string} cwd - Current working directory
+ * @param {string} [standardPath] - Path to quality standard file (relative to cwd)
  * @returns {{exists: boolean, path?: string} | null} File info or null
  */
-export function findQualityStandard(cwd = process.cwd()) {
-  const expectedPath = join(cwd, 'docs', 'quality', '001-quality-standard.md');
+export function findQualityStandard(cwd = process.cwd(), standardPath = DEFAULT_STANDARD_PATH) {
+  const expectedPath = join(cwd, standardPath);
 
   if (existsSync(expectedPath)) {
     return {
@@ -183,26 +188,30 @@ export function compareOverrides(documented, code) {
  * Validate quality-standard.md
  * @param {string} cwd - Current working directory
  * @param {boolean} silent - Suppress console output (for testing)
- * @returns {{valid: boolean, errors: string[], warnings: string[]}} Validation result
+ * @returns {Promise<{valid: boolean, errors: string[], warnings: string[]}>} Validation result
  */
-export function validate(cwd = process.cwd(), silent = false) {
+export async function validate(cwd = process.cwd(), silent = false) {
   const log = silent ? () => {} : console.log.bind(console);
   const error = silent ? () => {} : console.error.bind(console);
 
   const errors = [];
   const warnings = [];
 
+  // Load project config
+  const config = await loadConfig(cwd);
+  const standardPath = config.quality.standardPath;
+
   log('');
   log('Validating Quality Standard...');
   log('='.repeat(50));
 
   // 1. Check file exists
-  const fileInfo = findQualityStandard(cwd);
+  const fileInfo = findQualityStandard(cwd, standardPath);
 
   if (!fileInfo) {
-    errors.push('Missing required file: docs/quality/001-quality-standard.md');
+    errors.push(`Missing required file: ${standardPath}`);
     error('');
-    error('ERROR: Missing required file: docs/quality/001-quality-standard.md');
+    error(`ERROR: Missing required file: ${standardPath}`);
     error('');
     error('Run "npx kabran-setup" to create it, or create manually.');
     log('='.repeat(50));
@@ -210,7 +219,7 @@ export function validate(cwd = process.cwd(), silent = false) {
   }
 
   log('');
-  log('File: docs/quality/001-quality-standard.md');
+  log(`File: ${standardPath}`);
   log('  Status: Found');
 
   // 2. Read and parse content
@@ -317,10 +326,12 @@ export function validate(cwd = process.cwd(), silent = false) {
 /**
  * Get quality standard validation result in ci-result.json format
  * @param {string} [cwd] - Directory to validate (defaults to process.cwd())
- * @returns {Object} Check result for ci-result.json
+ * @returns {Promise<Object>} Check result for ci-result.json
  */
-export function getQualityStandardCheckResult(cwd = process.cwd()) {
-  const fileInfo = findQualityStandard(cwd);
+export async function getQualityStandardCheckResult(cwd = process.cwd()) {
+  const config = await loadConfig(cwd);
+  const standardPath = config.quality.standardPath;
+  const fileInfo = findQualityStandard(cwd, standardPath);
 
   if (!fileInfo) {
     return {
@@ -372,11 +383,11 @@ if (isMainModule) {
     const cwd = args.find(a => !a.startsWith('--')) || process.cwd();
 
     if (jsonOutput) {
-      const result = getQualityStandardCheckResult(cwd);
+      const result = await getQualityStandardCheckResult(cwd);
       console.log(JSON.stringify(result, null, 2));
       process.exit(result.status === 'fail' ? 1 : 0);
     } else {
-      const result = validate(cwd);
+      const result = await validate(cwd);
       process.exit(result.valid ? 0 : 1);
     }
   } catch (err) {

package/src/scripts/readme-validator.mjs

@@ -16,21 +16,27 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import {loadConfig, DEFAULTS} from '../core/config-loader.mjs';
 
-// Required sections (blocking if missing)
+/**
+ * Build section patterns from config array.
+ * @param {string[]} sections - Section names
+ * @returns {Array<{pattern: RegExp, name: string}>}
+ */
+function buildSectionPatterns(sections) {
+  return sections.map(name => ({
+    pattern: new RegExp(`^##\\s+${name}`, 'mi'),
+    name,
+  }));
+}
+
+// Default sections for backwards compatibility (used when importing directly)
 export const REQUIRED_SECTIONS = [
   {pattern: /^#\s+.+/m, name: 'Project Title (# Heading)'},
-  {pattern: /^##\s+Installation/mi, name: 'Installation'},
-  {pattern: /^##\s+Usage/mi, name: 'Usage'},
-  {pattern: /^##\s+License/mi, name: 'License'},
+  ...buildSectionPatterns(DEFAULTS.readme.required),
 ];
 
-// Recommended sections (warnings only)
-export const RECOMMENDED_SECTIONS = [
-  {pattern: /^##\s+Development/mi, name: 'Development'},
-  {pattern: /^##\s+Contributing/mi, name: 'Contributing'},
-  {pattern: /^##\s+Testing/mi, name: 'Testing'},
-];
+export const RECOMMENDED_SECTIONS = buildSectionPatterns(DEFAULTS.readme.recommended);
 
 /**
  * Find README.md in directory
@@ -64,9 +70,9 @@ export function checkSection(content, section) {
  * Main validation function
  * @param {string} [cwd] - Directory to validate (defaults to process.cwd())
  * @param {boolean} [silent] - Suppress console output
- * @returns {{valid: boolean, errors: string[], warnings: string[]}}
+ * @returns {Promise<{valid: boolean, errors: string[], warnings: string[]}>}
  */
-export function validateReadme(cwd = process.cwd(), silent = false) {
+export async function validateReadme(cwd = process.cwd(), silent = false) {
   const log = silent ? () => {} : console.log.bind(console);
   const error = silent ? () => {} : console.error.bind(console);
 
@@ -75,6 +81,16 @@ export function validateReadme(cwd = process.cwd(), silent = false) {
   const errors = [];
   const warnings = [];
 
+  // Load project config
+  const config = await loadConfig(cwd);
+
+  // Build section patterns from config
+  const requiredSections = [
+    {pattern: /^#\s+.+/m, name: 'Project Title (# Heading)'},
+    ...buildSectionPatterns(config.readme.required),
+  ];
+  const recommendedSections = buildSectionPatterns(config.readme.recommended);
+
   // Check if README exists
   const readme = findReadme(cwd);
   if (!readme) {
@@ -90,7 +106,7 @@ export function validateReadme(cwd = process.cwd(), silent = false) {
 
   // Check required sections
   log('Checking required sections:');
-  for (const section of REQUIRED_SECTIONS) {
+  for (const section of requiredSections) {
     const exists = checkSection(content, section);
     if (exists) {
       log(`  OK ${section.name}`);
@@ -102,7 +118,7 @@ export function validateReadme(cwd = process.cwd(), silent = false) {
 
   // Check recommended sections
   log('\nChecking recommended sections:');
-  for (const section of RECOMMENDED_SECTIONS) {
+  for (const section of recommendedSections) {
     const exists = checkSection(content, section);
     if (exists) {
       log(`  OK ${section.name}`);
@@ -134,10 +150,10 @@ export function validateReadme(cwd = process.cwd(), silent = false) {
 /**
  * Get README validation result in ci-result.json format
  * @param {string} [cwd] - Directory to validate (defaults to process.cwd())
- * @returns {Object} Check result for ci-result.json
+ * @returns {Promise<Object>} Check result for ci-result.json
  */
-export function getReadmeCheckResult(cwd = process.cwd()) {
-  const result = validateReadme(cwd, true);
+export async function getReadmeCheckResult(cwd = process.cwd()) {
+  const result = await validateReadme(cwd, true);
 
   // Determine status
   let status = 'pass';
@@ -169,11 +185,11 @@ if (isMainModule) {
     const cwd = args.find(a => !a.startsWith('--')) || process.cwd();
 
     if (jsonOutput) {
-      const result = getReadmeCheckResult(cwd);
+      const result = await getReadmeCheckResult(cwd);
       console.log(JSON.stringify(result, null, 2));
       process.exit(result.status === 'fail' ? 1 : 0);
     } else {
-      const result = validateReadme(cwd);
+      const result = await validateReadme(cwd);
       process.exit(result.valid ? 0 : 1);
     }
   } catch (err) {

package/src/scripts/traceability/coverage-report.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # ==============================================================================
 # Kabran Traceability Coverage Report
-# Part of @kabran-owner/kabran-config
+# Part of @kabran-tecnologia/kabran-config
 # Implements PROP-006: JSDoc Traceability Tags
 #
 # Generates a report of spec coverage in the codebase.

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

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # ==============================================================================
 # Kabran Traceability Core - Shared Functions
-# Part of @kabran-owner/kabran-config
+# Part of @kabran-tecnologia/kabran-config
 # Implements PROP-006: JSDoc Traceability Tags
 # ==============================================================================
 

package/src/scripts/traceability/validate-traceability.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # ==============================================================================
 # Kabran Traceability Validator
-# Part of @kabran-owner/kabran-config
+# Part of @kabran-tecnologia/kabran-config
 # Implements PROP-006: JSDoc Traceability Tags
 #
 # Validates FORMAT of traceability tags (not presence).

package/src/telemetry/README.md

@@ -161,8 +161,8 @@ SERVICE_VERSION=1.0.0                # Service version (default: 1.0.0)
 ENVIRONMENT=production               # Environment name (default: from NODE_ENV)
 OTEL_NAMESPACE=kabran                # Service namespace (default: kabran)
 
-# OTLP Exporter
-OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.kabran.com.br  # Collector endpoint
+# OTLP Exporter (REQUIRED)
+OTEL_EXPORTER_OTLP_ENDPOINT=https://your-otel-collector.example.com  # Your collector endpoint
 OTEL_EXPORTER_OTLP_TIMEOUT=10000     # Export timeout in ms (default: 10000)
 
 # Sampling
@@ -188,7 +188,7 @@ initTelemetry({
   // Optional (all have sensible defaults)
   serviceVersion: '1.0.0',
   environment: 'production',
-  endpoint: 'https://otel.kabran.com.br',
+  endpoint: process.env.OTEL_ENDPOINT, // Required - set via env var
   sampleRate: 0.1,
   enabled: true,
 
@@ -292,20 +292,20 @@ import {
 } from '@kabran-tecnologia/kabran-config/telemetry/shared'
 ```
 
-## Integration with Kosmos Observability
+## Integration with Observability Stack
 
-This package is designed to work with the Kosmos observability stack:
+This package is designed to work with standard observability stacks:
 
-- **Traces** → Grafana Tempo
+- **Traces** → Grafana Tempo, Jaeger, or any OTLP-compatible backend
 - **Logs** → Grafana Loki (via stdout/Promtail or direct export)
-- **Metrics** → Prometheus (planned, see [GAP-006])
+- **Metrics** → Prometheus (planned)
 
-Default endpoint: `https://otel.kabran.com.br`
+**Note:** You must configure `OTEL_ENDPOINT` to point to your OTLP collector.
 
 ### Viewing Traces
 
-1. Open Grafana at your Kosmos instance
-2. Go to Explore → Select Tempo
+1. Open your observability dashboard (e.g., Grafana)
+2. Go to Explore → Select your trace backend (Tempo, Jaeger, etc.)
 3. Search by service name or trace ID
 
 ## Best Practices
@@ -404,4 +404,4 @@ initTelemetry({
 
 - [OpenTelemetry JavaScript](https://opentelemetry.io/docs/languages/js/)
 - [W3C Trace Context](https://www.w3.org/TR/trace-context/)
-- [Kosmos Observability Stack](https://github.com/kabran-owner/kosmos/tree/main/services/observability)
+- [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/)

package/src/telemetry/config/defaults.mjs

@@ -76,9 +76,10 @@ function parseIgnorePaths(value) {
 
 /**
  * Default OTLP endpoint
- * Override: OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_ENDPOINT
+ * REQUIRED: Set via OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_ENDPOINT
+ * No default is provided - users must configure their own collector endpoint
  */
-export const DEFAULT_ENDPOINT = 'https://otel.kabran.com.br'
+export const DEFAULT_ENDPOINT = null
 
 /**
  * Default OTLP traces path
@@ -107,12 +108,9 @@ export const DEFAULT_NAMESPACE = 'kabran'
 /**
  * Default CORS URLs for trace header propagation
  * Override: OTEL_PROPAGATE_TRACE_HEADER_CORS_URLS (comma-separated regex patterns)
+ * Only localhost is included by default - configure additional domains via env var
  */
-export const DEFAULT_CORS_URLS = [
-  /.*\.supabase\.co/,
-  /.*\.kabran\.com\.br/,
-  /localhost/,
-]
+export const DEFAULT_CORS_URLS = [/localhost/]
 
 /**
  * Default instrumentation options

package/src/telemetry/shared/types.d.ts

@@ -21,7 +21,7 @@ export interface TelemetryConfig {
   /** Deployment environment (default: from NODE_ENV or 'development') */
   environment?: string
 
-  /** OTLP endpoint URL (default: 'https://otel.kabran.com.br') */
+  /** OTLP endpoint URL (required - set via OTEL_ENDPOINT env var) */
   endpoint?: string
 
   /** Sampling rate 0.0-1.0 (default: 0.1) */

package/templates/config/kabran.config.mjs

@@ -0,0 +1,53 @@
+/**
+ * Kabran Configuration File
+ *
+ * This file customizes the behavior of kabran-config validators and tools.
+ * All settings are optional - defaults are applied for any missing values.
+ *
+ * @see https://github.com/kabran-owner/kabran-config
+ */
+
+/** @type {import('@kabran-tecnologia/kabran-config/core/config-loader').KabranConfig} */
+export default {
+  /**
+   * README Validator Configuration
+   *
+   * Customize which sections are required and recommended in your README.md
+   */
+  readme: {
+    // Sections that MUST be present (validation fails if missing)
+    required: ['Installation', 'Usage', 'License'],
+
+    // Sections that SHOULD be present (warning if missing)
+    recommended: ['Development', 'Testing', 'Contributing'],
+  },
+
+  /**
+   * Environment Validator Configuration
+   *
+   * Customize how environment variable usage is detected
+   */
+  env: {
+    // Require .env.example file if env vars are detected
+    requireExample: true,
+
+    // Patterns to search for when detecting env var usage
+    detectPatterns: [
+      'process.env',      // Node.js
+      'import.meta.env',  // Vite/ESM
+      'Deno.env',         // Deno
+      'os.getenv',        // Python
+      '$_ENV',            // PHP
+    ],
+  },
+
+  /**
+   * Quality Standard Validator Configuration
+   *
+   * Customize the location of your quality standard documentation
+   */
+  quality: {
+    // Path to quality standard file (relative to project root)
+    standardPath: 'docs/quality/001-quality-standard.md',
+  },
+};