slicejs-web-framework 3.4.4 → 3.5.1

package/Slice/Components/Structural/Controller/Controller.js

@@ -26,6 +26,12 @@ export default class Controller {
       this._pendingBuilds = new Map();
 
       this.idCounter = 0;
+
+      // 🔍 Leak detection (dev-only). App-provided predicates that mark a
+      // detached-but-registered component as intentional (not a leak).
+      this._leakExclusions = [];
+      // Ring buffer of activeComponents.size samples for the growth heuristic.
+      this._growthSamples = [];
    }
 
    /**
@@ -1268,4 +1274,133 @@ export default class Controller {
 
       return count;
    }
+
+   // ============================================================
+   // 🔍 LEAK DETECTION (dev-only)
+   // A component is a candidate leak when it stays registered in
+   // activeComponents while detached from the live DOM and was not
+   // intentionally cached (Route/MultiRoute/Router). Read-only.
+   // ============================================================
+
+   /**
+    * Register a predicate that excludes a detached component from being flagged
+    * as a leak (e.g. caches that intentionally keep instances off-DOM).
+    * @param {(component: HTMLElement) => boolean} predicate
+    */
+   registerLeakExclusion(predicate) {
+      if (typeof predicate === 'function') {
+         this._leakExclusions.push(predicate);
+      }
+   }
+
+   /**
+    * Is this detached component intentionally retained (not a leak)?
+    * @param {HTMLElement} component
+    * @returns {boolean}
+    * @private
+    */
+   _isExcludedOrphan(component) {
+      // (1) Cache-owner marker — Route/MultiRoute flag their cached instances.
+      if (component.__sliceCached === true) return true;
+      // (2) Router-managed instances are reused across navigation by sliceId.
+      if (typeof component.sliceId === 'string' && /^route-/.test(component.sliceId)) return true;
+      // (3) App-provided predicates.
+      for (const predicate of this._leakExclusions) {
+         try {
+            if (predicate(component)) return true;
+         } catch (error) {
+            slice.logger.logError('Controller', 'Leak exclusion predicate threw', error);
+         }
+      }
+      return false;
+   }
+
+   /**
+    * Does an ancestor explain this component's detachment? If so we report only
+    * the detached root, not every descendant of a removed/cached subtree.
+    * @param {HTMLElement} component
+    * @param {Set<string>} detachedIds
+    * @returns {boolean}
+    * @private
+    */
+   _hasDetachedAncestor(component, detachedIds) {
+      let parent = component.parentComponent;
+      while (parent) {
+         if ((parent.sliceId && detachedIds.has(parent.sliceId)) || this._isExcludedOrphan(parent)) {
+            return true;
+         }
+         parent = parent.parentComponent;
+      }
+      return false;
+   }
+
+   /**
+    * Build a human-readable retain path (component → parent → …) for diagnosis.
+    * @param {HTMLElement} component
+    * @returns {string[]}
+    * @private
+    */
+   _retainPath(component) {
+      const path = [];
+      let node = component;
+      let guard = 0;
+      while (node && guard++ < 50) {
+         path.push(`${node.constructor?.name || 'Unknown'}(${node.sliceId || '?'})`);
+         node = node.parentComponent;
+      }
+      return path;
+   }
+
+   /**
+    * Find candidate leaks: components registered in activeComponents but detached
+    * from the live DOM and not intentionally cached. Pure read-only.
+    * @returns {Array<{ sliceId: string, name: string, reason: string, retainPath: string[] }>}
+    */
+   findOrphans() {
+      const detached = [];
+      for (const [sliceId, component] of this.activeComponents) {
+         if (component instanceof HTMLElement && !component.isConnected) {
+            detached.push([sliceId, component]);
+         }
+      }
+
+      const detachedIds = new Set(detached.map(([sliceId]) => sliceId));
+      const orphans = [];
+
+      for (const [sliceId, component] of detached) {
+         if (this._isExcludedOrphan(component)) continue;
+         if (this._hasDetachedAncestor(component, detachedIds)) continue;
+         orphans.push({
+            sliceId,
+            name: component.constructor?.name || 'Unknown',
+            reason: 'registered but detached from DOM without destroy',
+            retainPath: this._retainPath(component)
+         });
+      }
+
+      return orphans;
+   }
+
+   /**
+    * Record an activeComponents.size sample for the monotonic-growth heuristic.
+    * Called by the Leak Inspector on each refresh while it is open.
+    */
+   sampleComponentGrowth() {
+      this._growthSamples.push(this.activeComponents.size);
+      if (this._growthSamples.length > 20) this._growthSamples.shift();
+   }
+
+   /**
+    * Heuristic: has the active component count grown without ever shrinking
+    * across the sampled window? Suggests an accumulation leak.
+    * @returns {boolean}
+    */
+   isGrowthMonotonic() {
+      const samples = this._growthSamples;
+      if (samples.length < 5) return false;
+      for (let i = 1; i < samples.length; i++) {
+         if (samples[i] < samples[i - 1]) return false;
+      }
+      return samples[samples.length - 1] > samples[0];
+   }
 }

package/Slice/Components/Structural/EventManager/EventManager.js

@@ -29,17 +29,224 @@ export default class EventManager {
       // Contador de emits por evento en la sesión actual de grabación
       this.emitCounts = new Map();
 
+      // Atribución de emisores por evento (tracing): Map<eventName, Map<key, { sliceId?, name?, source?, count, lastTs }>>
+      // Se llena solo mientras un debugger está abierto (igual que emitHistory).
+      this.emitters = new Map();
+
       // Flag: solo grabamos cuando algún debugger UI está visible
       this._recording = false;
 
       // Contador para IDs únicos
       this.idCounter = 0;
+
+      // ── Event registry (catálogo declarado vía register()) ──
+      // Map<eventName, { description, payload }>
+      this.registry = new Map();
+      // Validación activa: se enciende al primer register(). En loose mode (sin
+      // registry) NO se advierte nada — comportamiento idéntico al histórico.
+      this._validating = false;
+      // Warn-once: nombres ya advertidos como no declarados (evita spam).
+      this.undeclaredSeen = new Set();
+      // Drift para el debugger: eventos usados (emit/subscribe) pero no declarados.
+      this.undeclared = new Set();
+      // Warn-once: nombres ya advertidos por no tener namespace.
+      this._noNamespaceSeen = new Set();
+
+      // Grafo estático (documentación) generado por `slice types generate`:
+      // { events: { name: { payload, emitters[], listeners[] } }, dynamic: {...} }.
+      // Complementa el tracing observacional (this.emitters / this.emitHistory).
+      this.graph = null;
    }
 
    init() {
       return true;
    }
 
+   // ============================================
+   // REGISTRY - Catálogo de eventos declarados
+   // ============================================
+
+   /**
+    * Declarar un catálogo de eventos. Mergeable: se puede llamar varias veces
+    * desde varios módulos. Enciende la validación dev (warn-on-undeclared).
+    *
+    * Dos formas:
+    *  - register(catalog) con claves planas `'namespace:event'`.
+    *  - register(namespace, catalog) que prefija cada clave con `namespace:`,
+    *    para declarar un grupo sin repetir el prefijo.
+    *
+    * @param {string|Object<string, { description?: string, payload?: object|null }>} namespaceOrCatalog
+    * @param {Object<string, { description?: string, payload?: object|null }>} [maybeCatalog]
+    * @returns {EventManager} this (encadenable)
+    *
+    * @example
+    * slice.events.register({
+    *    'user:login':  { description: 'User logged in', payload: { id: 'number', name: 'string' } },
+    *    'cart:cleared': { description: 'Cart emptied', payload: null },
+    * });
+    *
+    * @example
+    * // Agrupado por namespace
+    * slice.events.register('user', {
+    *    login:  { payload: { id: 'number', name: 'string' } },
+    *    logout: { payload: null },
+    * }); // => 'user:login', 'user:logout'
+    */
+   register(namespaceOrCatalog, maybeCatalog) {
+      let prefix = '';
+      let catalog = namespaceOrCatalog;
+
+      if (typeof namespaceOrCatalog === 'string') {
+         const ns = namespaceOrCatalog.trim();
+         prefix = ns.endsWith(':') ? ns : `${ns}:`;
+         catalog = maybeCatalog;
+      }
+
+      if (!catalog || typeof catalog !== 'object') {
+         slice.logger.logError('EventManager', 'register() requiere un objeto catálogo de eventos');
+         return this;
+      }
+
+      // Al primer register() sembramos los eventos internos del framework para
+      // que nunca disparen falsos warnings, y activamos la validación.
+      if (!this._validating) {
+         this._seedFrameworkEvents();
+         this._validating = true;
+      }
+
+      for (const [key, definition] of Object.entries(catalog)) {
+         const eventName = `${prefix}${key}`;
+         this._warnIfNoNamespace(eventName);
+
+         const entry = {
+            description: definition?.description || '',
+            payload: definition?.payload ?? null,
+         };
+
+         const existing = this.registry.get(eventName);
+         if (existing && JSON.stringify(existing.payload) !== JSON.stringify(entry.payload)) {
+            slice.logger.logWarning(
+               'EventManager',
+               `Evento "${eventName}" redeclarado con un payload distinto; se usa la última definición`
+            );
+         }
+
+         this.registry.set(eventName, entry);
+         // Si estaba marcado como drift, ya no lo está.
+         this.undeclared.delete(eventName);
+         this.undeclaredSeen.delete(eventName);
+      }
+
+      return this;
+   }
+
+   /**
+    * Cargar el grafo estático de eventos (manifest generado por el CLI). Es la capa
+    * de DOCUMENTACIÓN (emisores/oyentes por análisis de código, sin ejecutar), que
+    * complementa el tracing observacional en runtime.
+    * @param {{ events: object, dynamic?: object }} graph
+    * @returns {EventManager} this
+    */
+   loadGraph(graph) {
+      if (graph && typeof graph === 'object' && graph.events) {
+         this.graph = graph;
+      }
+      return this;
+   }
+
+   /**
+    * Emisores conocidos de un evento por análisis estático (documentación).
+    * @param {string} eventName
+    * @returns {Array<{ file: string, line: number, component: string|null }>}
+    */
+   staticEmittersOf(eventName) {
+      return this.graph?.events?.[eventName]?.emitters || [];
+   }
+
+   /**
+    * Oyentes conocidos de un evento por análisis estático (documentación).
+    * @param {string} eventName
+    * @returns {Array<{ file: string, line: number, component: string|null }>}
+    */
+   staticListenersOf(eventName) {
+      return this.graph?.events?.[eventName]?.listeners || [];
+   }
+
+   /**
+    * Namespace de un evento: el segmento antes del primer ':' (o null si no tiene).
+    * @param {string} eventName
+    * @returns {string|null}
+    */
+   namespaceOf(eventName) {
+      const index = typeof eventName === 'string' ? eventName.indexOf(':') : -1;
+      return index > 0 ? eventName.slice(0, index) : null;
+   }
+
+   /**
+    * Sembrar los eventos internos del framework en el registry.
+    * @private
+    */
+   _seedFrameworkEvents() {
+      const framework = {
+         'router:change': { description: 'Router navigated to a new route', payload: null },
+         'context:__created': { description: 'A context was created', payload: { name: 'string', state: 'object' } },
+      };
+      for (const [name, def] of Object.entries(framework)) {
+         if (!this.registry.has(name)) this.registry.set(name, def);
+      }
+   }
+
+   /**
+    * ¿El evento está declarado en el registry?
+    * @param {string} eventName
+    * @returns {boolean}
+    */
+   isDeclared(eventName) {
+      if (this.registry.has(eventName)) return true;
+      // Familia dinámica context:<name> emitida por el ContextManager.
+      if (eventName.startsWith('context:')) return true;
+      return false;
+   }
+
+   /**
+    * Advertir (una sola vez, solo en dev) si el evento no está declarado.
+    * @private
+    */
+   _warnIfUndeclared(eventName) {
+      if (!this._validating) return;
+      if (this.isDeclared(eventName)) return;
+
+      this.undeclared.add(eventName);
+      if (this.undeclaredSeen.has(eventName)) return;
+      this.undeclaredSeen.add(eventName);
+
+      if (!slice.isProduction || !slice.isProduction()) {
+         slice.logger.logWarning(
+            'EventManager',
+            `Undeclared event "${eventName}" — register it via slice.events.register({ '${eventName}': { payload: ... } })`
+         );
+      }
+   }
+
+   /**
+    * Advertir (una sola vez, solo en dev) si el evento no tiene namespace.
+    * Solo activo cuando hay un registry en uso (this._validating).
+    * @private
+    */
+   _warnIfNoNamespace(eventName) {
+      if (!this._validating) return;
+      if (typeof eventName !== 'string' || eventName.includes(':')) return;
+      if (this._noNamespaceSeen.has(eventName)) return;
+      this._noNamespaceSeen.add(eventName);
+
+      if (!slice.isProduction || !slice.isProduction()) {
+         slice.logger.logWarning(
+            'EventManager',
+            `Event "${eventName}" has no namespace — prefer "namespace:${eventName}" (e.g. group it with slice.events.register('app', { ${eventName}: ... })).`
+         );
+      }
+   }
+
    // ============================================
    // API PRINCIPAL
    // ============================================
@@ -68,6 +275,9 @@ export default class EventManager {
          return null;
       }
 
+      this._warnIfUndeclared(eventName);
+      this._warnIfNoNamespace(eventName);
+
       const subscriptionId = `evt_${++this.idCounter}`;
 
       // Crear Map para este evento si no existe
@@ -111,6 +321,7 @@ export default class EventManager {
       this._recording = true;
       this.emitHistory = [];
       this.emitCounts = new Map();
+      this.emitters = new Map();
    }
 
    /**
@@ -126,6 +337,9 @@ export default class EventManager {
          return null;
       }
 
+      this._warnIfUndeclared(eventName);
+      this._warnIfNoNamespace(eventName);
+
       const subscriptionId = `evt_${++this.idCounter}`;
 
       if (!this.subscriptions.has(eventName)) {
@@ -188,13 +402,31 @@ export default class EventManager {
     * slice.events.emit('cart:cleared'); // Sin datos
     */
    emit(eventName, ...args) {
+      // Global (unbound) emit — emitter resolved best-effort from the call stack.
+      this._emitFrom(null, eventName, args);
+   }
+
+   /**
+    * Core emit. `emitter` is the known source ({ sliceId, name }) when emitted via
+    * a bound API, or null for global emits (then a dev stack-trace fallback runs).
+    * @param {{ sliceId?: string, name?: string }|null} emitter
+    * @param {string} eventName
+    * @param {any[]} args
+    * @private
+    */
+   _emitFrom(emitter, eventName, args) {
       slice.logger.info('EventManager', `Emitting "${eventName}"`, args[0] ?? null);
 
-      // Solo grabamos el histórico si algún debugger está abierto
+      this._warnIfUndeclared(eventName);
+      this._warnIfNoNamespace(eventName);
+
+      // Solo grabamos el histórico (y la atribución de emisores) si algún debugger está abierto.
       if (this._recording) {
-         this.emitHistory.push({ eventName, timestamp: Date.now() });
+         const source = emitter || this._captureEmitterSource();
+         this.emitHistory.push({ eventName, timestamp: Date.now(), emitter: source });
          if (this.emitHistory.length > 500) this.emitHistory.shift();
          this.emitCounts.set(eventName, (this.emitCounts.get(eventName) || 0) + 1);
+         this._recordEmitter(eventName, source);
       }
 
       if (!this.subscriptions.has(eventName)) {
@@ -234,6 +466,47 @@ export default class EventManager {
       }
    }
 
+   /**
+    * Aggregate an emitter under an event: who emits, with a count. Powers the
+    * "emitted by" tracing view in the debugger.
+    * @param {{ sliceId?: string, name?: string, source?: string }|null} emitter
+    * @private
+    */
+   _recordEmitter(eventName, emitter) {
+      if (!emitter) return;
+      const key = emitter.sliceId || emitter.source || 'unknown';
+      if (!this.emitters.has(eventName)) this.emitters.set(eventName, new Map());
+      const bucket = this.emitters.get(eventName);
+      const existing = bucket.get(key);
+      if (existing) {
+         existing.count += 1;
+         existing.lastTs = Date.now();
+      } else {
+         bucket.set(key, { ...emitter, count: 1, lastTs: Date.now() });
+      }
+   }
+
+   /**
+    * Best-effort source of a global emit from the call stack (dev only). Returns
+    * { source: 'file.js:line' } or null. Robust: never throws, never runs in prod.
+    * @private
+    */
+   _captureEmitterSource() {
+      if (slice.isProduction && slice.isProduction()) return null;
+      try {
+         const stack = new Error().stack || '';
+         for (const line of stack.split('\n')) {
+            // Skip the Error header and every frame inside this manager.
+            if (line.includes('EventManager.js')) continue;
+            const match = line.match(/([^/\\\s(]+\.js):(\d+):\d+/);
+            if (match) return { source: `${match[1]}:${match[2]}` };
+         }
+      } catch {
+         /* tracing is best-effort */
+      }
+      return null;
+   }
+
    // ============================================
    // BIND - Vinculación a Componente
    // ============================================
@@ -278,10 +551,22 @@ export default class EventManager {
          },
 
          /**
-          * Emitir un evento
+          * Emitir un evento (atribuido a este componente para el tracing).
           */
          emit: (eventName, data) => {
-            self.emit(eventName, data);
+            self._emitFrom(
+               { sliceId: component.sliceId, name: component.constructor?.name || 'Component' },
+               eventName,
+               [data]
+            );
+         },
+
+         /**
+          * Declarar eventos en el registry (passthrough a register()).
+          */
+         register: (namespaceOrCatalog, maybeCatalog) => {
+            self.register(namespaceOrCatalog, maybeCatalog);
+            return self;
          },
       };
    }