@nahisaho/musubix-core 1.0.0

package/dist/utils/logger.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Logger Utility
+ *
+ * Provides structured logging with levels, formatting, and output options
+ *
+ * @packageDocumentation
+ * @module utils/logger
+ *
+ * @see REQ-MNT-001 - Logger
+ * @see DES-MUSUBIX-001 Section 16.1 - Logger Design
+ */
+/**
+ * Log levels
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+/**
+ * Log entry structure
+ */
+export interface LogEntry {
+    timestamp: string;
+    level: LogLevel;
+    message: string;
+    context?: string;
+    data?: Record<string, unknown>;
+    error?: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+}
+/**
+ * Logger configuration
+ */
+export interface LoggerConfig {
+    /** Minimum log level */
+    level: LogLevel;
+    /** Enable console output */
+    console: boolean;
+    /** Enable file output */
+    file: boolean;
+    /** Log file path */
+    filePath?: string;
+    /** Enable JSON format */
+    json: boolean;
+    /** Enable colors in console */
+    colors: boolean;
+    /** Include timestamps */
+    timestamps: boolean;
+    /** Context prefix */
+    context?: string;
+}
+/**
+ * Logger class
+ */
+export declare class Logger {
+    private config;
+    private context;
+    constructor(context?: string, config?: Partial<LoggerConfig>);
+    /**
+     * Create a child logger with additional context
+     */
+    child(context: string): Logger;
+    /**
+     * Update configuration
+     */
+    configure(config: Partial<LoggerConfig>): void;
+    /**
+     * Log debug message
+     */
+    debug(message: string, data?: Record<string, unknown>): void;
+    /**
+     * Log info message
+     */
+    info(message: string, data?: Record<string, unknown>): void;
+    /**
+     * Log warning message
+     */
+    warn(message: string, data?: Record<string, unknown>): void;
+    /**
+     * Log error message
+     */
+    error(message: string, error?: Error, data?: Record<string, unknown>): void;
+    /**
+     * Log fatal message
+     */
+    fatal(message: string, error?: Error, data?: Record<string, unknown>): void;
+    /**
+     * Log with timing
+     */
+    time(label: string): () => void;
+    /**
+     * Core logging method
+     */
+    private log;
+    /**
+     * Write to console
+     */
+    private writeConsole;
+    /**
+     * Write to file
+     */
+    private writeFile;
+    /**
+     * Format entry as JSON
+     */
+    private formatJson;
+    /**
+     * Format entry as text
+     */
+    private formatText;
+}
+/**
+ * Global logger instance
+ */
+export declare const logger: Logger;
+/**
+ * Create a new logger with context
+ */
+export declare function createLogger(context: string, config?: Partial<LoggerConfig>): Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAarE;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,QAAQ,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,KAAK,CAAC,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,wBAAwB;IACxB,KAAK,EAAE,QAAQ,CAAC;IAChB,4BAA4B;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,yBAAyB;IACzB,IAAI,EAAE,OAAO,CAAC;IACd,oBAAoB;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yBAAyB;IACzB,IAAI,EAAE,OAAO,CAAC;IACd,+BAA+B;IAC/B,MAAM,EAAE,OAAO,CAAC;IAChB,yBAAyB;IACzB,UAAU,EAAE,OAAO,CAAC;IACpB,qBAAqB;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AA4BD;;GAEG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,OAAO,CAAS;gBAEZ,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC;IAQ5D;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAK9B;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI;IAI9C;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI5D;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI3D;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI3D;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI3E;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI3E;;OAEG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,IAAI;IAQ/B;;OAEG;IACH,OAAO,CAAC,GAAG;IAqCX;;OAEG;IACH,OAAO,CAAC,YAAY;IAkBpB;;OAEG;YACW,SAAS;IAevB;;OAEG;IACH,OAAO,CAAC,UAAU;IAIlB;;OAEG;IACH,OAAO,CAAC,UAAU;CA4CnB;AAED;;GAEG;AACH,eAAO,MAAM,MAAM,QAAe,CAAC;AAEnC;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,MAAM,CAEpF"}

package/dist/utils/logger.js

@@ -0,0 +1,237 @@
+/**
+ * Logger Utility
+ *
+ * Provides structured logging with levels, formatting, and output options
+ *
+ * @packageDocumentation
+ * @module utils/logger
+ *
+ * @see REQ-MNT-001 - Logger
+ * @see DES-MUSUBIX-001 Section 16.1 - Logger Design
+ */
+import { appendFile, mkdir } from 'fs/promises';
+import { dirname } from 'path';
+/**
+ * Log level priority (lower = more verbose)
+ */
+const LOG_LEVEL_PRIORITY = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+    fatal: 4,
+};
+/**
+ * Default logger configuration
+ */
+const DEFAULT_CONFIG = {
+    level: 'info',
+    console: true,
+    file: false,
+    json: false,
+    colors: true,
+    timestamps: true,
+};
+/**
+ * ANSI color codes
+ */
+const COLORS = {
+    reset: '\x1b[0m',
+    dim: '\x1b[2m',
+    bold: '\x1b[1m',
+    debug: '\x1b[36m', // cyan
+    info: '\x1b[32m', // green
+    warn: '\x1b[33m', // yellow
+    error: '\x1b[31m', // red
+    fatal: '\x1b[35m', // magenta
+};
+/**
+ * Logger class
+ */
+export class Logger {
+    config;
+    context;
+    constructor(context, config) {
+        this.context = context ?? 'musubix';
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        if (context) {
+            this.config.context = context;
+        }
+    }
+    /**
+     * Create a child logger with additional context
+     */
+    child(context) {
+        const childContext = this.context ? `${this.context}:${context}` : context;
+        return new Logger(childContext, this.config);
+    }
+    /**
+     * Update configuration
+     */
+    configure(config) {
+        this.config = { ...this.config, ...config };
+    }
+    /**
+     * Log debug message
+     */
+    debug(message, data) {
+        this.log('debug', message, data);
+    }
+    /**
+     * Log info message
+     */
+    info(message, data) {
+        this.log('info', message, data);
+    }
+    /**
+     * Log warning message
+     */
+    warn(message, data) {
+        this.log('warn', message, data);
+    }
+    /**
+     * Log error message
+     */
+    error(message, error, data) {
+        this.log('error', message, data, error);
+    }
+    /**
+     * Log fatal message
+     */
+    fatal(message, error, data) {
+        this.log('fatal', message, data, error);
+    }
+    /**
+     * Log with timing
+     */
+    time(label) {
+        const start = performance.now();
+        return () => {
+            const duration = performance.now() - start;
+            this.debug(`${label} completed`, { durationMs: duration.toFixed(2) });
+        };
+    }
+    /**
+     * Core logging method
+     */
+    log(level, message, data, error) {
+        // Check log level
+        if (LOG_LEVEL_PRIORITY[level] < LOG_LEVEL_PRIORITY[this.config.level]) {
+            return;
+        }
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level,
+            message,
+            context: this.context,
+            data,
+            error: error ? {
+                name: error.name,
+                message: error.message,
+                stack: error.stack,
+            } : undefined,
+        };
+        // Console output
+        if (this.config.console) {
+            this.writeConsole(entry);
+        }
+        // File output
+        if (this.config.file && this.config.filePath) {
+            this.writeFile(entry).catch(() => {
+                // Silently fail file writes
+            });
+        }
+    }
+    /**
+     * Write to console
+     */
+    writeConsole(entry) {
+        const output = this.config.json
+            ? this.formatJson(entry)
+            : this.formatText(entry);
+        switch (entry.level) {
+            case 'error':
+            case 'fatal':
+                console.error(output);
+                break;
+            case 'warn':
+                console.warn(output);
+                break;
+            default:
+                console.log(output);
+        }
+    }
+    /**
+     * Write to file
+     */
+    async writeFile(entry) {
+        if (!this.config.filePath) {
+            return;
+        }
+        const line = this.formatJson(entry) + '\n';
+        try {
+            await mkdir(dirname(this.config.filePath), { recursive: true });
+            await appendFile(this.config.filePath, line);
+        }
+        catch {
+            // Silently fail
+        }
+    }
+    /**
+     * Format entry as JSON
+     */
+    formatJson(entry) {
+        return JSON.stringify(entry);
+    }
+    /**
+     * Format entry as text
+     */
+    formatText(entry) {
+        const parts = [];
+        // Timestamp
+        if (this.config.timestamps) {
+            const time = this.config.colors
+                ? `${COLORS.dim}${entry.timestamp}${COLORS.reset}`
+                : entry.timestamp;
+            parts.push(time);
+        }
+        // Level
+        const levelUpper = entry.level.toUpperCase().padEnd(5);
+        const level = this.config.colors
+            ? `${COLORS[entry.level]}${levelUpper}${COLORS.reset}`
+            : levelUpper;
+        parts.push(level);
+        // Context
+        if (entry.context) {
+            const ctx = this.config.colors
+                ? `${COLORS.dim}[${entry.context}]${COLORS.reset}`
+                : `[${entry.context}]`;
+            parts.push(ctx);
+        }
+        // Message
+        parts.push(entry.message);
+        // Data
+        if (entry.data && Object.keys(entry.data).length > 0) {
+            parts.push(JSON.stringify(entry.data));
+        }
+        // Error
+        if (entry.error) {
+            parts.push(`\n  ${entry.error.name}: ${entry.error.message}`);
+            if (entry.error.stack) {
+                parts.push(`\n${entry.error.stack}`);
+            }
+        }
+        return parts.join(' ');
+    }
+}
+/**
+ * Global logger instance
+ */
+export const logger = new Logger();
+/**
+ * Create a new logger with context
+ */
+export function createLogger(context, config) {
+    return new Logger(context, config);
+}
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

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

package/dist/utils/performance-profiler.d.ts

@@ -0,0 +1,251 @@
+/**
+ * Performance Profiler
+ *
+ * Profiles and measures system performance
+ *
+ * @packageDocumentation
+ * @module utils/performance-profiler
+ *
+ * @see REQ-PER-001 - Performance Monitoring
+ * @see Article VI - Decision Transparency
+ */
+/**
+ * Profile entry type
+ */
+export type ProfileEntryType = 'function' | 'api' | 'query' | 'io' | 'custom';
+/**
+ * Profile entry
+ */
+export interface ProfileEntry {
+    /** Entry ID */
+    id: string;
+    /** Name */
+    name: string;
+    /** Type */
+    type: ProfileEntryType;
+    /** Start time */
+    startTime: number;
+    /** End time */
+    endTime?: number;
+    /** Duration (ms) */
+    duration?: number;
+    /** Parent entry ID */
+    parentId?: string;
+    /** Child entry IDs */
+    children: string[];
+    /** Metadata */
+    metadata?: Record<string, unknown>;
+    /** Memory usage */
+    memoryUsage?: {
+        heapUsed: number;
+        heapTotal: number;
+        external: number;
+    };
+}
+/**
+ * Profile statistics
+ */
+export interface ProfileStats {
+    /** Name */
+    name: string;
+    /** Call count */
+    count: number;
+    /** Total duration (ms) */
+    totalDuration: number;
+    /** Average duration (ms) */
+    avgDuration: number;
+    /** Min duration (ms) */
+    minDuration: number;
+    /** Max duration (ms) */
+    maxDuration: number;
+    /** Standard deviation */
+    stdDev: number;
+    /** Median */
+    median: number;
+    /** 95th percentile */
+    p95: number;
+    /** 99th percentile */
+    p99: number;
+}
+/**
+ * Memory snapshot
+ */
+export interface MemorySnapshot {
+    /** Timestamp */
+    timestamp: number;
+    /** Heap used */
+    heapUsed: number;
+    /** Heap total */
+    heapTotal: number;
+    /** External */
+    external: number;
+    /** Array buffers */
+    arrayBuffers: number;
+    /** RSS */
+    rss: number;
+}
+/**
+ * Performance report
+ */
+export interface PerformanceReport {
+    /** Report ID */
+    id: string;
+    /** Timestamp */
+    timestamp: Date;
+    /** Duration (ms) */
+    duration: number;
+    /** Total entries */
+    totalEntries: number;
+    /** Entries by type */
+    byType: Record<ProfileEntryType, number>;
+    /** Top slowest */
+    slowest: Array<{
+        name: string;
+        duration: number;
+    }>;
+    /** Statistics */
+    stats: ProfileStats[];
+    /** Memory snapshots */
+    memorySnapshots: MemorySnapshot[];
+    /** Hotspots */
+    hotspots: Array<{
+        name: string;
+        percentage: number;
+        duration: number;
+    }>;
+    /** Recommendations */
+    recommendations: string[];
+}
+/**
+ * Profiler config
+ */
+export interface ProfilerConfig {
+    /** Enabled */
+    enabled: boolean;
+    /** Sample rate (0-1) */
+    sampleRate: number;
+    /** Max entries */
+    maxEntries: number;
+    /** Capture memory */
+    captureMemory: boolean;
+    /** Memory snapshot interval (ms) */
+    memoryInterval: number;
+    /** Slow threshold (ms) */
+    slowThreshold: number;
+}
+/**
+ * Default configuration
+ */
+export declare const DEFAULT_PROFILER_CONFIG: ProfilerConfig;
+/**
+ * Performance Profiler
+ */
+export declare class PerformanceProfiler {
+    private config;
+    private entries;
+    private entryStack;
+    private memorySnapshots;
+    private memoryTimer?;
+    private startTime;
+    private entryCounter;
+    constructor(config?: Partial<ProfilerConfig>);
+    /**
+     * Start profiling session
+     */
+    start(): void;
+    /**
+     * Stop profiling session
+     */
+    stop(): PerformanceReport;
+    /**
+     * Begin profiling an operation
+     */
+    begin(name: string, type?: ProfileEntryType, metadata?: Record<string, unknown>): string;
+    /**
+     * End profiling current operation
+     */
+    end(id?: string): void;
+    /**
+     * Profile a function
+     */
+    profile<T>(name: string, fn: () => T, type?: ProfileEntryType): T;
+    /**
+     * Profile an async function
+     */
+    profileAsync<T>(name: string, fn: () => Promise<T>, type?: ProfileEntryType): Promise<T>;
+    /**
+     * Create a timer for measuring duration
+     */
+    createTimer(name: string, type?: ProfileEntryType): {
+        stop: () => number;
+    };
+    /**
+     * Mark a point in time
+     */
+    mark(name: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Get current entry
+     */
+    getCurrentEntry(): ProfileEntry | undefined;
+    /**
+     * Get all entries
+     */
+    getEntries(): ProfileEntry[];
+    /**
+     * Get entries by type
+     */
+    getEntriesByType(type: ProfileEntryType): ProfileEntry[];
+    /**
+     * Get slow entries
+     */
+    getSlowEntries(): ProfileEntry[];
+    /**
+     * Calculate statistics for a name
+     */
+    getStats(name: string): ProfileStats | null;
+    /**
+     * Generate performance report
+     */
+    generateReport(): PerformanceReport;
+    /**
+     * Generate recommendations
+     */
+    private generateRecommendations;
+    /**
+     * Start memory capture
+     */
+    private startMemoryCapture;
+    /**
+     * Capture memory snapshot
+     */
+    private captureMemorySnapshot;
+    /**
+     * Capture memory usage
+     */
+    private captureMemory;
+    /**
+     * Get current time (high resolution)
+     */
+    private now;
+    /**
+     * Calculate percentile
+     */
+    private percentile;
+    /**
+     * Format report as string
+     */
+    formatReport(report: PerformanceReport): string;
+}
+/**
+ * Create decorator for profiling methods
+ */
+export declare function profiled(profiler: PerformanceProfiler, type?: ProfileEntryType): MethodDecorator;
+/**
+ * Create performance profiler instance
+ */
+export declare function createPerformanceProfiler(config?: Partial<ProfilerConfig>): PerformanceProfiler;
+/**
+ * Global profiler instance
+ */
+export declare const globalProfiler: PerformanceProfiler;
+//# sourceMappingURL=performance-profiler.d.ts.map

package/dist/utils/performance-profiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"performance-profiler.d.ts","sourceRoot":"","sources":["../../src/utils/performance-profiler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,KAAK,GAAG,OAAO,GAAG,IAAI,GAAG,QAAQ,CAAC;AAE9E;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,eAAe;IACf,EAAE,EAAE,MAAM,CAAC;IACX,WAAW;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW;IACX,IAAI,EAAE,gBAAgB,CAAC;IACvB,iBAAiB;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oBAAoB;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sBAAsB;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sBAAsB;IACtB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,eAAe;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,mBAAmB;IACnB,WAAW,CAAC,EAAE;QACZ,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,WAAW;IACX,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,0BAA0B;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,4BAA4B;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,yBAAyB;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa;IACb,MAAM,EAAE,MAAM,CAAC;IACf,sBAAsB;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,sBAAsB;IACtB,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,gBAAgB;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU;IACV,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,gBAAgB;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,gBAAgB;IAChB,SAAS,EAAE,IAAI,CAAC;IAChB,oBAAoB;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;IACzC,kBAAkB;IAClB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnD,iBAAiB;IACjB,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,uBAAuB;IACvB,eAAe,EAAE,cAAc,EAAE,CAAC;IAClC,eAAe;IACf,QAAQ,EAAE,KAAK,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IACH,sBAAsB;IACtB,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,cAAc;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,wBAAwB;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,qBAAqB;IACrB,aAAa,EAAE,OAAO,CAAC;IACvB,oCAAoC;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,0BAA0B;IAC1B,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,eAAO,MAAM,uBAAuB,EAAE,cAOrC,CAAC;AAEF;;GAEG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,OAAO,CAAwC;IACvD,OAAO,CAAC,UAAU,CAAgB;IAClC,OAAO,CAAC,eAAe,CAAwB;IAC/C,OAAO,CAAC,WAAW,CAAC,CAAiC;IACrD,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,YAAY,CAAK;gBAEb,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC;IAI5C;;OAEG;IACH,KAAK,IAAI,IAAI;IAcb;;OAEG;IACH,IAAI,IAAI,iBAAiB;IAczB;;OAEG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,gBAA6B,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM;IAmCpG;;OAEG;IACH,GAAG,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI;IAqBtB;;OAEG;IACH,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,IAAI,GAAE,gBAA6B,GAAG,CAAC;IAS7E;;OAEG;IACG,YAAY,CAAC,CAAC,EAClB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,IAAI,GAAE,gBAA6B,GAClC,OAAO,CAAC,CAAC,CAAC;IASb;;OAEG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,gBAA2B,GAAG;QAC5D,IAAI,EAAE,MAAM,MAAM,CAAC;KACpB;IAYD;;OAEG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAK5D;;OAEG;IACH,eAAe,IAAI,YAAY,GAAG,SAAS;IAK3C;;OAEG;IACH,UAAU,IAAI,YAAY,EAAE;IAI5B;;OAEG;IACH,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,GAAG,YAAY,EAAE;IAIxD;;OAEG;IACH,cAAc,IAAI,YAAY,EAAE;IAMhC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IA0B3C;;OAEG;IACH,cAAc,IAAI,iBAAiB;IA8DnC;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAkD/B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAQ1B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAU7B;;OAEG;IACH,OAAO,CAAC,aAAa;IAwBrB;;OAEG;IACH,OAAO,CAAC,GAAG;IAOX;;OAEG;IACH,OAAO,CAAC,UAAU;IAMlB;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM;CAoEhD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,mBAAmB,EAC7B,IAAI,GAAE,gBAA6B,GAClC,eAAe,CAejB;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,mBAAmB,CAE/F;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,qBAA4B,CAAC"}