# 🚀 @decido/logger

> **Ecosistema Decido OS** — Registro de eventos estructurado isomórfico, telemetría reactiva mediante sensores y protección de datos sensibles con cumplimiento estricto de políticas de seguridad.

Este módulo provee un sistema de registro de eventos de alta ingeniería para **Decido OS**, permitiendo a las aplicaciones capturar, estructurar y despachar logs a nivel de consola (Browser/Server) y suscriptores de eventos personalizados. Incorpora sensores de telemetría asíncronos y una capa inteligente de redacción de datos privados (PII) adaptada a cada nivel de seguridad.

---

## 📦 Instalación

Para aprovisionar este módulo dentro de las áreas del monorepo o consumirlo externamente:

```bash
pnpm add @decido/logger
```

---

## 🏗️ Arquitectura de Telemetría

El flujo de registro de eventos y telemetría de `@decido/logger` se procesa bajo el siguiente ciclo asíncrono y de privacidad:

```mermaid
graph TD
    A[Invocación de Sensor / Log] --> B{Filtro por Categorías}
    B -->|Excluido| Z[Fin del Evento]
    B -->|Permitido| C{Redactor de PII}
    C -->|Nivel de Seguridad Tier| D[Redactar Passwords/Secrets/Tokens]
    D --> E{Verificación de Throttling & Muestreo}
    E -->|Descartado| Z
    E -->|Aprobado| F[Isomorfismo de Consola]
    F -->|Browser| G[Formateador de Estilos CSS]
    F -->|Node Server| H[Formateador de Estilos ANSI]
    G --> I[Despacho a Suscriptores]
    H --> I
    I --> J[Ejecución de Callbacks de Telemetría]
```

---

## 🔧 Especificación de APIs Principales

| API / Método / Tipo | Tipo | Descripción |
| :--- | :--- | :--- |
| `Logger` | `Class` | Instancia principal del sistema de logging estructurado. |
| `probe(id, data, options)` | `Function` | Registra una métrica o lectura puntual de telemetría en un sensor. |
| `probeStart(id, options)` | `Function` | Inicia una medición asíncrona de telemetría y rendimiento, devolviendo una función para finalizar y reportar el ciclo. |
| `SecurityTier` | `Enum / Type` | Define los niveles de seguridad (`'debug' \| 'standard' \| 'maximum'`) que controlan las políticas de redacción de PII, muestreo y throttling. |
| `addLogsSubscriber(callback)` | `Function` | Registra un listener personalizado para capturar eventos de log y métricas en tiempo real. |
| `removeLogsSubscriber(callback)`| `Function` | Remueve un listener previamente registrado para evitar fugas de memoria. |
| `clearAllLogsSubscribers()` | `Function` | Vacía por completo la pila de suscriptores activos. |

---

## 💡 Ejemplos de Consumo Práctico

### 1. Inicialización y Registro Isomórfico

El logger adapta dinámicamente su formato visual dependiendo de si se ejecuta en el navegador (usando estilos CSS nativos en consola) o en la terminal del servidor (usando códigos de escape ANSI).

```typescript
import { Logger } from '@decido/logger';

const logger = new Logger({
  categories: ['AUTH', 'DB'],
  excludeCategories: ['SPAM'],
  isBrowser: typeof window !== 'undefined'
});

// Logs estructurados con categorías
logger.info('DB', 'Conexión a base de datos establecida exitosamente', { host: 'localhost', port: 5432 });
logger.warn('AUTH', 'Intento de inicio de sesión sospechoso detectado', { userId: 9928 });
```

### 2. Telemetría Asíncrona Avanzada (`probe` y `probeStart`)

Los sensores de telemetría permiten auditar eventos y medir el rendimiento de operaciones complejas, aplicando automáticamente políticas de muestreo (`sampling`) y de limitación de frecuencia (`throttling`).

```typescript
import { probe, probeStart } from '@decido/logger';

// 1. Registro de métrica puntual con Sensor de Telemetría
probe('user_signup', { userId: 452 }, {
  level: 'info',
  security: 'standard'
});

// 2. Medición de rendimiento asíncrono
const endProbe = probeStart('api_request_duration', {
  level: 'debug',
  security: 'debug',
  sampleRate: 1.0 // Registrar el 100% de las muestras en modo depuración
});

try {
  await executeDatabaseQuery();
} finally {
  // Finaliza la medición, calculando automáticamente la duración en milisegundos
  endProbe({ status: 'success' });
}
```

### 3. Redacción Inteligente de Datos Sensibles (PII)

El sistema de seguridad analiza los payloads de forma recursiva y redacta campos altamente confidenciales (como contraseñas, secretos, tokens, credenciales) de acuerdo al `SecurityTier` activo. Lo hace de forma segura **conservando intactos** los tipos y prototipos complejos de JavaScript/TypeScript.

```typescript
import { probe } from '@decido/logger';

const payload = {
  user: {
    username: 'julio_decido',
    password: 'superSecretPassword123', // Será redactado de forma segura
    geminiApiKey: 'AIzaSyExampleGeminiToken' // Será redactado de forma segura
  },
  meta: {
    createdAt: new Date(), // SE CONSERVA como instancia de Date
    validationRegex: /[a-z]+/g, // SE CONSERVA como RegExp
    errorDetails: new Error('Fallo crítico de conexión') // SE CONSERVA como Error
  }
};

// Emisión bajo nivel de seguridad Máximo (Maximum)
probe('user_login_attempt', payload, {
  security: 'maximum'
});

// Salida emitida de forma interna (el password y api key se reemplazan por '[REDACTED]'):
// {
//   user: { username: 'julio_decido', password: '[REDACTED]', geminiApiKey: '[REDACTED]' },
//   meta: { createdAt: Date, validationRegex: RegExp, errorDetails: Error }
// }
```

### 4. Suscriptores de Eventos y Callbacks Personalizados

Perfecto para canalizar métricas hacia paneles reactivos o tableros visuales de Decido OS en tiempo real.

```typescript
import { addLogsSubscriber, removeLogsSubscriber } from '@decido/logger';

const mySubscriber = (event) => {
  console.log(`[Dashboard Sync] Evento recibido: ${event.message}`, event.payload);
};

// Suscribirse a la cola
addLogsSubscriber(mySubscriber);

// ... operaciones de logging ...

// Desuscribirse para prevenir Memory Leaks
removeLogsSubscriber(mySubscriber);
```

---

## 🛡️ Robustez y Suite de Pruebas

Este paquete cuenta con un blindaje del **100% de cobertura absoluta** en sentencias, ramas, funciones y líneas, certificado bajo **Vitest**.

### Ejecución de Pruebas Unitarias

Para correr las pruebas unitarias y verificar el cumplimiento de cobertura localmente:

```bash
# Correr tests unitarios
pnpm --filter @decido/logger test

# Correr tests con reporte detallado de cobertura
pnpm --filter @decido/logger test:coverage
```

### Directrices de Cobertura Estricta (`vitest.config.ts`)

La compilación y validación del paquete exige un umbral del 100% en todas sus métricas. Cualquier modificación de código requiere la adición correspondiente de aserciones de pruebas unitarias para mantener este estándar libre de regresiones.