@principal-ai/subsystems-core 0.29.0

package/dist/discovery/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/discovery/types.ts"],"names":[],"mappings":"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"}

package/dist/discovery/types.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Type definitions for canvas and execution file discovery
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/discovery/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/discovery/types.ts"],"names":[],"mappings":";AAAA;;GAEG"}

package/dist/events/EventsCanvasValidator.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Events Canvas Validator
+ *
+ * Validates that a .events.canvas file properly documents event namespaces
+ * and their events, with correct namespace extraction and node structure.
+ */
+import type { FileSystemAdapter } from '@principal-ai/repository-abstraction';
+import type { ExtendedCanvas } from '../types/canvas';
+/**
+ * Event namespace node structure
+ */
+export interface EventNamespaceNode {
+    id: string;
+    type: 'event-namespace';
+    namespace: {
+        name: string;
+        description: string;
+        /**
+         * Optional source paths that define this component's code location.
+         * Each entry may be a folder (covers all descendants) or a specific file.
+         * When present, events in this namespace may only be emitted from files
+         * covered by one of these paths. Namespaces without `paths` remain
+         * unenforced — enforcement is opt-in per namespace.
+         *
+         * Multiple entries are valid for cases like generated code, platform-split
+         * implementations, or migration periods. The validator warns when
+         * `paths.length > 1` to prompt authors to confirm the multi-location
+         * is intentional.
+         */
+        paths?: string[];
+        events: Array<{
+            name: string;
+            severity?: 'INFO' | 'WARN' | 'ERROR';
+            description?: string;
+            attributes?: Record<string, {
+                type: string;
+                required?: boolean;
+                description?: string;
+            }>;
+        }>;
+    };
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    color?: string;
+}
+/**
+ * Events canvas validation context
+ */
+export interface EventsCanvasValidationContext {
+    /** The events canvas (if found) */
+    eventsCanvas?: ExtendedCanvas;
+    /** Path to the events canvas file */
+    eventsCanvasPath?: string;
+    /** Base path for resolving relative paths */
+    basePath: string;
+    /** Optional: Workflow files to validate against */
+    workflowFiles?: Array<{
+        path: string;
+        events: string[];
+    }>;
+}
+/**
+ * Events canvas validation violation
+ */
+export interface EventsCanvasViolation {
+    /** Rule ID that detected this violation */
+    ruleId: string;
+    /** Severity level */
+    severity: 'error' | 'warn';
+    /** File path where violation occurred */
+    file: string;
+    /** JSON path within file (optional) */
+    path?: string;
+    /** Human-readable description of what's wrong */
+    message: string;
+    /** Why this matters */
+    impact: string;
+    /** How to fix it */
+    suggestion: string;
+}
+/**
+ * Events canvas validation result
+ */
+export interface EventsCanvasValidationResult {
+    /** Whether validation passed (no errors) */
+    valid: boolean;
+    /** List of violations found */
+    violations: EventsCanvasViolation[];
+    /** Coverage metrics */
+    metrics: {
+        /** Total unique namespaces found */
+        totalNamespaces: number;
+        /** Namespaces with nodes */
+        documentedNamespaces: string[];
+        /** Namespaces missing nodes */
+        missingNamespaces: string[];
+        /** Total events across all namespaces */
+        totalEvents: number;
+        /** Events properly registered in namespace nodes */
+        registeredEvents: string[];
+        /** Events not in any namespace node */
+        unregisteredEvents: string[];
+    };
+}
+/**
+ * Validates events canvas files
+ */
+export declare class EventsCanvasValidator {
+    private fsAdapter;
+    constructor(fsAdapter: FileSystemAdapter);
+    /**
+     * Extract namespace from event name (all segments except last)
+     *
+     * @example
+     * extractNamespace('validation.started') // 'validation'
+     * extractNamespace('file.read.complete') // 'file.read'
+     * extractNamespace('error') // null (invalid, needs at least 2 segments)
+     */
+    private extractNamespace;
+    /**
+     * Check if a node is an event-namespace node
+     */
+    private isEventNamespaceNode;
+    /**
+     * Extract all events from namespace nodes
+     */
+    private extractEventsFromCanvas;
+    /**
+     * Build a map of event name → expected namespace
+     */
+    private buildEventNamespaceMap;
+    /**
+     * Validate an events canvas
+     */
+    validate(context: EventsCanvasValidationContext): Promise<EventsCanvasValidationResult>;
+}
+//# sourceMappingURL=EventsCanvasValidator.d.ts.map

package/dist/events/EventsCanvasValidator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventsCanvasValidator.d.ts","sourceRoot":"","sources":["../../src/events/EventsCanvasValidator.ts"],"names":[],"mappings":"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"}

package/dist/events/EventsCanvasValidator.js

@@ -0,0 +1,281 @@
+"use strict";
+/**
+ * Events Canvas Validator
+ *
+ * Validates that a .events.canvas file properly documents event namespaces
+ * and their events, with correct namespace extraction and node structure.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventsCanvasValidator = void 0;
+const path_helpers_1 = require("./path-helpers");
+/**
+ * Validates events canvas files
+ */
+class EventsCanvasValidator {
+    constructor(fsAdapter) {
+        this.fsAdapter = fsAdapter;
+    }
+    /**
+     * Extract namespace from event name (all segments except last)
+     *
+     * @example
+     * extractNamespace('validation.started') // 'validation'
+     * extractNamespace('file.read.complete') // 'file.read'
+     * extractNamespace('error') // null (invalid, needs at least 2 segments)
+     */
+    extractNamespace(eventName) {
+        const segments = eventName.split('.');
+        if (segments.length < 2) {
+            return null; // Invalid event name
+        }
+        return segments.slice(0, -1).join('.');
+    }
+    /**
+     * Check if a node is an event-namespace node
+     */
+    isEventNamespaceNode(node) {
+        return node?.type === 'event-namespace' &&
+            node?.namespace?.name !== undefined;
+    }
+    /**
+     * Extract all events from namespace nodes
+     */
+    extractEventsFromCanvas(canvas) {
+        const namespaceEvents = new Map();
+        for (const node of canvas.nodes || []) {
+            if (this.isEventNamespaceNode(node)) {
+                const namespaceNode = node;
+                const namespace = namespaceNode.namespace.name;
+                const events = new Set();
+                for (const event of namespaceNode.namespace.events || []) {
+                    events.add(event.name);
+                }
+                namespaceEvents.set(namespace, events);
+            }
+        }
+        return namespaceEvents;
+    }
+    /**
+     * Build a map of event name → expected namespace
+     */
+    buildEventNamespaceMap(namespaceEvents) {
+        const eventNamespaceMap = new Map();
+        for (const [namespace, events] of namespaceEvents) {
+            for (const eventName of events) {
+                const extractedNamespace = this.extractNamespace(eventName);
+                eventNamespaceMap.set(eventName, extractedNamespace || '');
+            }
+        }
+        return eventNamespaceMap;
+    }
+    /**
+     * Validate an events canvas
+     */
+    async validate(context) {
+        const violations = [];
+        const { eventsCanvas, eventsCanvasPath, basePath } = context;
+        // Initialize metrics
+        const metrics = {
+            totalNamespaces: 0,
+            documentedNamespaces: [],
+            missingNamespaces: [],
+            totalEvents: 0,
+            registeredEvents: [],
+            unregisteredEvents: [],
+        };
+        // Check if canvas exists
+        if (!eventsCanvas) {
+            violations.push({
+                ruleId: 'events-canvas-required',
+                severity: 'error',
+                file: eventsCanvasPath || '.principal-views/cli.events.canvas',
+                message: 'Events canvas is required for documenting event namespaces',
+                impact: 'Cannot validate event structure or namespace organization',
+                suggestion: 'Create an events canvas with event-namespace nodes for each namespace',
+            });
+            return {
+                valid: false,
+                violations,
+                metrics,
+            };
+        }
+        // Extract namespace nodes and events
+        const namespaceEvents = this.extractEventsFromCanvas(eventsCanvas);
+        const namespaceNodes = new Set(namespaceEvents.keys());
+        metrics.documentedNamespaces = Array.from(namespaceNodes);
+        metrics.totalNamespaces = namespaceNodes.size;
+        // Collect all event names and their extracted namespaces
+        const allEvents = new Set();
+        const eventToExtractedNamespace = new Map();
+        const extractedNamespaces = new Set();
+        for (const [namespace, events] of namespaceEvents) {
+            for (const eventName of events) {
+                allEvents.add(eventName);
+                metrics.totalEvents++;
+                // Extract namespace from event name
+                const extractedNamespace = this.extractNamespace(eventName);
+                if (!extractedNamespace) {
+                    violations.push({
+                        ruleId: 'events-invalid-event-name',
+                        severity: 'error',
+                        file: eventsCanvasPath || '.principal-views/cli.events.canvas',
+                        path: `nodes[].namespace.events[name="${eventName}"]`,
+                        message: `Event name "${eventName}" is invalid (must have at least 2 segments)`,
+                        impact: 'Event name does not follow {namespace}.{action} convention',
+                        suggestion: `Rename to follow pattern like "${namespace}.${eventName}"`,
+                    });
+                    continue;
+                }
+                eventToExtractedNamespace.set(eventName, extractedNamespace);
+                extractedNamespaces.add(extractedNamespace);
+                // Check namespace consistency: extracted namespace should match the node it's in
+                if (extractedNamespace !== namespace) {
+                    violations.push({
+                        ruleId: 'events-namespace-mismatch',
+                        severity: 'error',
+                        file: eventsCanvasPath || '.principal-views/cli.events.canvas',
+                        path: `nodes[namespace.name="${namespace}"].namespace.events[name="${eventName}"]`,
+                        message: `Event "${eventName}" is in wrong namespace node (expected: "${extractedNamespace}", actual: "${namespace}")`,
+                        impact: 'Event is incorrectly organized, making namespace structure confusing',
+                        suggestion: `Move event "${eventName}" to namespace node "${extractedNamespace}"`,
+                    });
+                }
+                else {
+                    metrics.registeredEvents.push(eventName);
+                }
+            }
+        }
+        // Check for missing namespace nodes
+        for (const namespace of extractedNamespaces) {
+            if (!namespaceNodes.has(namespace)) {
+                metrics.missingNamespaces.push(namespace);
+                violations.push({
+                    ruleId: 'events-namespace-node-missing',
+                    severity: 'error',
+                    file: eventsCanvasPath || '.principal-views/cli.events.canvas',
+                    message: `Namespace "${namespace}" is missing a node in the canvas`,
+                    impact: 'Cannot visualize or document this namespace group',
+                    suggestion: `Add a node with type: "event-namespace" and namespace.name: "${namespace}"`,
+                });
+            }
+        }
+        // Validate namespace nodes have descriptions
+        for (const node of eventsCanvas.nodes || []) {
+            if (this.isEventNamespaceNode(node)) {
+                const namespaceNode = node;
+                if (!namespaceNode.namespace.description) {
+                    violations.push({
+                        ruleId: 'events-namespace-missing-description',
+                        severity: 'warn',
+                        file: eventsCanvasPath || '.principal-views/cli.events.canvas',
+                        path: `nodes[id="${namespaceNode.id}"].namespace`,
+                        message: `Namespace "${namespaceNode.namespace.name}" is missing a description`,
+                        impact: 'Namespace purpose is undocumented',
+                        suggestion: 'Add a description field explaining what events this namespace contains',
+                    });
+                }
+                // Validate each event has description and severity
+                for (const event of namespaceNode.namespace.events || []) {
+                    if (!event.description) {
+                        violations.push({
+                            ruleId: 'events-event-missing-description',
+                            severity: 'warn',
+                            file: eventsCanvasPath || '.principal-views/cli.events.canvas',
+                            path: `nodes[id="${namespaceNode.id}"].namespace.events[name="${event.name}"]`,
+                            message: `Event "${event.name}" is missing a description`,
+                            impact: 'Event purpose is undocumented',
+                            suggestion: 'Add a description field explaining when/why this event is emitted',
+                        });
+                    }
+                    if (!event.severity) {
+                        violations.push({
+                            ruleId: 'events-event-missing-severity',
+                            severity: 'warn',
+                            file: eventsCanvasPath || '.principal-views/cli.events.canvas',
+                            path: `nodes[id="${namespaceNode.id}"].namespace.events[name="${event.name}"]`,
+                            message: `Event "${event.name}" is missing a severity level`,
+                            impact: 'Cannot determine event criticality',
+                            suggestion: 'Add severity field with value: "INFO", "WARN", or "ERROR"',
+                        });
+                    }
+                }
+            }
+        }
+        // Validate namespace paths (optional field — enforcement is opt-in per namespace).
+        // Collects declared paths across namespaces to check for cross-namespace overlap.
+        const declaredPaths = [];
+        for (const node of eventsCanvas.nodes || []) {
+            if (!this.isEventNamespaceNode(node))
+                continue;
+            const namespaceNode = node;
+            const paths = namespaceNode.namespace.paths;
+            if (!paths || paths.length === 0)
+                continue;
+            // Warn when a namespace declares more than one path — prompt author to
+            // confirm the multi-location is intentional (generated code, platform
+            // splits, migration) rather than an accidental sprawl.
+            if (paths.length > 1) {
+                violations.push({
+                    ruleId: 'events-namespace-multiple-paths',
+                    severity: 'warn',
+                    file: eventsCanvasPath || '.principal-views/cli.events.canvas',
+                    path: `nodes[id="${namespaceNode.id}"].namespace.paths`,
+                    message: `Namespace "${namespaceNode.namespace.name}" declares ${paths.length} paths`,
+                    impact: 'Multiple paths can indicate legitimate cases (generated code, platform splits, migration) but often signal that the namespace should be split',
+                    suggestion: 'Confirm the multi-location is intentional. Otherwise consider splitting the namespace or grouping the code under a single parent folder.',
+                });
+            }
+            for (const p of paths) {
+                declaredPaths.push({
+                    namespace: namespaceNode.namespace.name,
+                    nodeId: namespaceNode.id,
+                    path: p,
+                });
+                // Warn when a declared path does not exist relative to the repo root.
+                const resolved = this.fsAdapter.join(basePath, p);
+                if (!(await this.fsAdapter.exists(resolved))) {
+                    violations.push({
+                        ruleId: 'events-namespace-paths-missing',
+                        severity: 'warn',
+                        file: eventsCanvasPath || '.principal-views/cli.events.canvas',
+                        path: `nodes[id="${namespaceNode.id}"].namespace.paths`,
+                        message: `Path "${p}" declared by namespace "${namespaceNode.namespace.name}" does not exist`,
+                        impact: 'Events emitted under this namespace cannot be validated against a real code location',
+                        suggestion: 'Verify the path exists relative to the repository root, or remove it from the namespace declaration.',
+                    });
+                }
+            }
+        }
+        // Cross-namespace overlap check. Parent-child nesting is a valid partition
+        // (longest-prefix wins at runtime); any other overlap makes namespace
+        // ownership of a file ambiguous.
+        for (let i = 0; i < declaredPaths.length; i++) {
+            for (let j = i + 1; j < declaredPaths.length; j++) {
+                const a = declaredPaths[i];
+                const b = declaredPaths[j];
+                if (a.namespace === b.namespace)
+                    continue;
+                const relationship = (0, path_helpers_1.pathsOverlap)(a.path, b.path);
+                if (relationship === 'conflict') {
+                    violations.push({
+                        ruleId: 'events-namespace-paths-overlap',
+                        severity: 'error',
+                        file: eventsCanvasPath || '.principal-views/cli.events.canvas',
+                        message: `Paths overlap between namespaces "${a.namespace}" ("${a.path}") and "${b.namespace}" ("${b.path}")`,
+                        impact: 'A file covered by two namespaces makes namespace ownership ambiguous',
+                        suggestion: 'Separate the paths so they are disjoint, or restructure as parent/child namespaces (e.g., "workflow" covering "src/workflow" and "workflow.scenarios" covering "src/workflow/scenarios").',
+                    });
+                }
+            }
+        }
+        metrics.totalNamespaces = extractedNamespaces.size;
+        const errors = violations.filter(v => v.severity === 'error');
+        return {
+            valid: errors.length === 0,
+            violations,
+            metrics,
+        };
+    }
+}
+exports.EventsCanvasValidator = EventsCanvasValidator;
+//# sourceMappingURL=EventsCanvasValidator.js.map

package/dist/events/EventsCanvasValidator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventsCanvasValidator.js","sourceRoot":"","sources":["../../src/events/EventsCanvasValidator.ts"],"names":[],"mappings":"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"}

package/dist/events/NamespacePathIndex.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Namespace Path Index
+ *
+ * Maps (scope, filepath) to the event-namespace that owns the file, using the
+ * `paths` field declared on `event-namespace` nodes.
+ *
+ * Resolution uses the longest-prefix partitioning rule: when multiple
+ * namespaces within a scope have paths that cover the same file, the one
+ * whose matched path is the most specific (longest after normalization) wins.
+ * This naturally supports nested namespaces such as `workflow` and
+ * `workflow.scenarios`, where the child claims its subtree without stealing
+ * the parent's.
+ *
+ * Pure/browser-safe — no filesystem access, just string comparison.
+ */
+/**
+ * One declared namespace/paths tuple, tagged with the scope it belongs to.
+ * Multiple entries may share the same scope (different namespaces in the
+ * same events canvas) or the same namespace across scopes (no cross-scope
+ * conflict — resolution is scoped).
+ */
+export interface NamespacePathEntry {
+    scope: string;
+    namespace: string;
+    paths: string[];
+    /** Optional — useful for surfacing where a match came from in diagnostics. */
+    sourceCanvasPath?: string;
+}
+/**
+ * Result of resolving a file against the index.
+ */
+export interface NamespacePathMatch {
+    /** The winning entry (by longest-prefix). */
+    entry: NamespacePathEntry;
+    /** Which of the entry's paths covered the file — the one that won. */
+    matchedPath: string;
+}
+export declare class NamespacePathIndex {
+    private entries;
+    /** Register a single namespace/paths entry. */
+    add(entry: NamespacePathEntry): void;
+    /** Register many entries at once. */
+    addAll(entries: readonly NamespacePathEntry[]): void;
+    /**
+     * Resolve a filepath to its owning namespace within a scope.
+     * Returns null if no entry in that scope has a path covering the file.
+     */
+    resolve(scope: string, filepath: string): NamespacePathMatch | null;
+    /** All entries registered under the given scope (for diagnostics). */
+    getScopeEntries(scope: string): readonly NamespacePathEntry[];
+    /**
+     * Look up the entry for a specific (scope, namespace) pair. Returns null
+     * when the namespace isn't registered — either because its events-canvas
+     * node omits `paths` (opt-out of enforcement) or because no such namespace
+     * is declared at all.
+     */
+    getEntry(scope: string, namespace: string): NamespacePathEntry | null;
+    /** All scopes present in the index. */
+    getScopes(): readonly string[];
+}
+//# sourceMappingURL=NamespacePathIndex.d.ts.map

package/dist/events/NamespacePathIndex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NamespacePathIndex.d.ts","sourceRoot":"","sources":["../../src/events/NamespacePathIndex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,8EAA8E;IAC9E,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,6CAA6C;IAC7C,KAAK,EAAE,kBAAkB,CAAC;IAC1B,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,OAAO,CAA4B;IAE3C,+CAA+C;IAC/C,GAAG,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI;IAIpC,qCAAqC;IACrC,MAAM,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,GAAG,IAAI;IAIpD;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI;IAmBnE,sEAAsE;IACtE,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,kBAAkB,EAAE;IAI7D;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI;IAMrE,uCAAuC;IACvC,SAAS,IAAI,SAAS,MAAM,EAAE;CAG/B"}

package/dist/events/NamespacePathIndex.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Namespace Path Index
+ *
+ * Maps (scope, filepath) to the event-namespace that owns the file, using the
+ * `paths` field declared on `event-namespace` nodes.
+ *
+ * Resolution uses the longest-prefix partitioning rule: when multiple
+ * namespaces within a scope have paths that cover the same file, the one
+ * whose matched path is the most specific (longest after normalization) wins.
+ * This naturally supports nested namespaces such as `workflow` and
+ * `workflow.scenarios`, where the child claims its subtree without stealing
+ * the parent's.
+ *
+ * Pure/browser-safe — no filesystem access, just string comparison.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NamespacePathIndex = void 0;
+const path_helpers_1 = require("./path-helpers");
+class NamespacePathIndex {
+    constructor() {
+        this.entries = [];
+    }
+    /** Register a single namespace/paths entry. */
+    add(entry) {
+        this.entries.push(entry);
+    }
+    /** Register many entries at once. */
+    addAll(entries) {
+        for (const e of entries)
+            this.add(e);
+    }
+    /**
+     * Resolve a filepath to its owning namespace within a scope.
+     * Returns null if no entry in that scope has a path covering the file.
+     */
+    resolve(scope, filepath) {
+        const normalizedFile = (0, path_helpers_1.normalizePath)(filepath);
+        let best = null;
+        for (const entry of this.entries) {
+            if (entry.scope !== scope)
+                continue;
+            for (const declared of entry.paths) {
+                if (!(0, path_helpers_1.pathCovers)(declared, normalizedFile))
+                    continue;
+                const normalizedDeclared = (0, path_helpers_1.normalizePath)(declared);
+                const length = normalizedDeclared.length;
+                if (best === null || length > best.length) {
+                    best = { entry, matchedPath: declared, length };
+                }
+            }
+        }
+        return best ? { entry: best.entry, matchedPath: best.matchedPath } : null;
+    }
+    /** All entries registered under the given scope (for diagnostics). */
+    getScopeEntries(scope) {
+        return this.entries.filter((e) => e.scope === scope);
+    }
+    /**
+     * Look up the entry for a specific (scope, namespace) pair. Returns null
+     * when the namespace isn't registered — either because its events-canvas
+     * node omits `paths` (opt-out of enforcement) or because no such namespace
+     * is declared at all.
+     */
+    getEntry(scope, namespace) {
+        return this.entries.find((e) => e.scope === scope && e.namespace === namespace) ?? null;
+    }
+    /** All scopes present in the index. */
+    getScopes() {
+        return Array.from(new Set(this.entries.map((e) => e.scope)));
+    }
+}
+exports.NamespacePathIndex = NamespacePathIndex;
+//# sourceMappingURL=NamespacePathIndex.js.map

package/dist/events/NamespacePathIndex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NamespacePathIndex.js","sourceRoot":"","sources":["../../src/events/NamespacePathIndex.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;AAEH,iDAA2D;AA0B3D,MAAa,kBAAkB;IAA/B;QACU,YAAO,GAAyB,EAAE,CAAC;IAwD7C,CAAC;IAtDC,+CAA+C;IAC/C,GAAG,CAAC,KAAyB;QAC3B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IAED,qCAAqC;IACrC,MAAM,CAAC,OAAsC;QAC3C,KAAK,MAAM,CAAC,IAAI,OAAO;YAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACvC,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,KAAa,EAAE,QAAgB;QACrC,MAAM,cAAc,GAAG,IAAA,4BAAa,EAAC,QAAQ,CAAC,CAAC;QAC/C,IAAI,IAAI,GAA8E,IAAI,CAAC;QAE3F,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,OAAO,EAAE;YAChC,IAAI,KAAK,CAAC,KAAK,KAAK,KAAK;gBAAE,SAAS;YACpC,KAAK,MAAM,QAAQ,IAAI,KAAK,CAAC,KAAK,EAAE;gBAClC,IAAI,CAAC,IAAA,yBAAU,EAAC,QAAQ,EAAE,cAAc,CAAC;oBAAE,SAAS;gBACpD,MAAM,kBAAkB,GAAG,IAAA,4BAAa,EAAC,QAAQ,CAAC,CAAC;gBACnD,MAAM,MAAM,GAAG,kBAAkB,CAAC,MAAM,CAAC;gBACzC,IAAI,IAAI,KAAK,IAAI,IAAI,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE;oBACzC,IAAI,GAAG,EAAE,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;iBACjD;aACF;SACF;QAED,OAAO,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5E,CAAC;IAED,sEAAsE;IACtE,eAAe,CAAC,KAAa;QAC3B,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;IACvD,CAAC;IAED;;;;;OAKG;IACH,QAAQ,CAAC,KAAa,EAAE,SAAiB;QACvC,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CACtB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,IAAI,CAAC,CAAC,SAAS,KAAK,SAAS,CACtD,IAAI,IAAI,CAAC;IACZ,CAAC;IAED,uCAAuC;IACvC,SAAS;QACP,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC/D,CAAC;CACF;AAzDD,gDAyDC"}