@amazon/vinyl-build-utils 1.0.0

package/README.md

@@ -0,0 +1,49 @@
+## Shared Build Utilities
+
+Reusable build utility for Amazon Vinyl and Amazon Vinyl-related TypeScript
+libraries.
+
+## Packages
+
+### util
+
+General utilities for build scripts and configuration.
+
+### vinyl
+
+Amazon Vinyl defaults for the provided tools.
+
+### typescript
+
+Utilities for compiling and running TypeScript code.
+
+## Build Tools
+
+### ESBuild (https://esbuild.github.io/)
+
+ESBuild provides an exceptionally fast typescript build system that provides
+simple hooks where we can add our custom plugins. This allows us to run babel
+transpilation, replace path aliases, and emit type declarations after file
+changes were detected.
+
+### Babel (https://babeljs.io/)
+
+Babel is a transpiler for js or ts that produces highly-compatible applications
+or libraries.
+
+The compatibility targets are defined in the package.json "browserslist"
+property. Use https://browsersl.ist/ to generate the expression for
+compatibility targets.
+
+### BrowserStack
+
+We use the BrowserStack service to run integration and unit tests on real
+browsers and devices. It allows us to set a compatibility matrix which we can
+assert that all functionality for our playback engine works as expected for
+every supported platform.
+
+[BrowserStack Readme](./src/browserstack/README.md)
+
+### Express
+
+Express is an HTTP server which supports SSL, proxies, and REST apis.

package/dist/babel/compatTransform.d.ts

@@ -0,0 +1,20 @@
+import type { TransformOptions } from '@babel/core';
+export interface CompatTransformOptions {
+    /**
+     * The modern esm module to transform.
+     */
+    readonly src: string;
+    /**
+     * The destination es5 js file.
+     */
+    readonly dest: string;
+    readonly options?: TransformOptions;
+}
+/**
+ * Transforms a source file to a destination ES5 target.
+ * Use the compatTransformPlugin for ESBuild integration.
+ *
+ * @param options
+ */
+export declare function compatTransform(options: CompatTransformOptions): Promise<void>;
+//# sourceMappingURL=compatTransform.d.ts.map

package/dist/babel/compatTransform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compatTransform.d.ts","sourceRoot":"","sources":["../../src/babel/compatTransform.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAmB,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAIpE,MAAM,WAAW,sBAAsB;IACnC;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IAEpB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,gBAAgB,CAAA;CACtC;AAQD;;;;;GAKG;AACH,wBAAsB,eAAe,CACjC,OAAO,EAAE,sBAAsB,GAChC,OAAO,CAAC,IAAI,CAAC,CA+Bf"}

package/dist/babel/compatTransform.js

@@ -0,0 +1,46 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { transformFile } from '@babel/core';
+import fs from 'node:fs';
+const defaultTransformOptions = {
+    presets: ['@babel/preset-env'],
+    minified: true,
+    sourceType: 'unambiguous',
+};
+/**
+ * Transforms a source file to a destination ES5 target.
+ * Use the compatTransformPlugin for ESBuild integration.
+ *
+ * @param options
+ */
+export async function compatTransform(options) {
+    if (!fs.existsSync(options.src)) {
+        throw new Error(`babel: src missing`);
+    }
+    // Currently does not handle source map chaining.
+    const result = await new Promise((resolve, reject) => {
+        transformFile(options.src, options.options ?? defaultTransformOptions, (err, result) => {
+            if (err)
+                reject(err);
+            else
+                resolve(result);
+        });
+    });
+    // Write the transformed code to a new file
+    const code = result?.code;
+    if (code) {
+        await new Promise((resolve, reject) => {
+            fs.writeFile(options.dest, code, 'utf8', (err) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve(void 0);
+            });
+        });
+    }
+    else {
+        throw new Error(`babel: transpile failed`);
+    }
+}

package/dist/browserstack/BrowserStackWorker.d.ts

@@ -0,0 +1,150 @@
+import { type BrowserStackAutomateClient, type SessionDetails, type WorkerOptions } from './browserStackRestApi';
+import type { LogEntry } from './configureReporterApi';
+/**
+ * Local state for a single session/worker.
+ */
+export interface BrowserStackWorkerState {
+    /**
+     * A local identifier for the session, used to map reporter API calls to its respective worker session.
+     */
+    readonly localId: string;
+    /**
+     * The browser worker configuration provided during construction.
+     */
+    readonly workerOptions: WorkerOptions;
+    /**
+     * If non-null, indicates a fatal error.
+     */
+    error: Error | null;
+    /**
+     * The session details, as retrieved from BrowserStack.
+     */
+    session: SessionDetails | null;
+    /**
+     * True if the worker has started via {@link BrowserStackWorker.start}.
+     * Once true, will not become false after termination.
+     */
+    started: boolean;
+    /**
+     * True if the session is active.
+     */
+    active: boolean;
+    /**
+     * The worker id.
+     * When the session and worker have been created, this will be set.
+     */
+    workerId: number | null;
+    /**
+     * The hashed session id.
+     * When the session and worker have been created, this will be set.
+     */
+    sessionId: string | null;
+    /**
+     * The total number of tests as reported by the test REST api.
+     * This will be null until the value is received.
+     */
+    totalSpecs: number | null;
+    /**
+     * The total number of specs completed, as reported by the test REST api.
+     */
+    totalCompleted: number;
+    /**
+     * The number of retry attempts remaining.
+     * A retry will happen if there has been a capture timeout, not if there has been a test failure.
+     */
+    attemptsRemaining: number;
+}
+export type ReadonlyBrowserStackWorkerState = Readonly<BrowserStackWorkerState>;
+export interface BrowserStackWorkerDeps {
+    /**
+     * The BrowserStack REST API.
+     */
+    readonly client: BrowserStackAutomateClient;
+}
+export interface BrowserStackWorkerOptions {
+    /**
+     * The number of seconds to wait for data before attempting to retry the test.
+     * Default: 45
+     */
+    readonly captureTimeout?: number;
+    /**
+     * The number of retries to start the session before giving up.
+     * Default: 2
+     */
+    readonly retries?: number;
+    /**
+     * The number of seconds between session update requests.
+     * Default: 5
+     */
+    readonly pollInterval?: number;
+    /**
+     * The directory to emit console logs.
+     * Set to null to disable console logging.
+     * Default: ./bStackLogs
+     */
+    readonly logsDir?: string | null;
+    /**
+     * If provided, adds the given query parameters to the launched URL.
+     */
+    readonly queryParams?: Record<string, string> | null;
+}
+export declare class BrowserStackWorker {
+    private readonly deps;
+    /**
+     * Set to observe state updates.
+     */
+    onUpdate: () => void;
+    private readonly _state;
+    private tasks;
+    private pollIntervalId;
+    private captureTimeoutId;
+    private options;
+    /**
+     * The worker url with an appended reportApi query param.
+     */
+    private readonly url;
+    constructor(deps: BrowserStackWorkerDeps, workerOptions: WorkerOptions, options?: BrowserStackWorkerOptions);
+    /**
+     * Returns true if this worker is completed. This will be true if either in an error state or the session status
+     * indicates completion
+     */
+    get completed(): boolean;
+    /**
+     * Returns this worker's state.
+     */
+    get state(): ReadonlyBrowserStackWorkerState;
+    get name(): string | undefined;
+    get passed(): boolean;
+    set totalCompleted(value: number);
+    set totalSpecs(value: number);
+    done(passed: boolean, reason: string): Promise<void>;
+    private refreshSession;
+    appendLogs(logs: readonly LogEntry[]): void;
+    /**
+     * Creates the worker/session.
+     */
+    start(): Promise<void>;
+    /**
+     * Deletes the worker.
+     * The worker may be created again.
+     */
+    terminate(): Promise<void>;
+    private clearTimers;
+    /**
+     * Deletes the session if it exists.
+     */
+    private deleteSession;
+    /**
+     * Terminates the worker, deletes the session, starts a new worker.
+     */
+    restart(): Promise<void>;
+    /**
+     * Invoked when the capture timeout has been reached. Checks if data has been received from the REST api.
+     */
+    private captureTimeoutHandler;
+    /**
+     * Sets the worker to a failed state and terminates.
+     */
+    private setError;
+}
+//# sourceMappingURL=BrowserStackWorker.d.ts.map

package/dist/browserstack/BrowserStackWorker.d.ts.map

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

package/dist/browserstack/BrowserStackWorker.js

@@ -0,0 +1,280 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { TaskQueue } from '../util/TaskQueue';
+import { logger } from '../util/Logger';
+import path from 'node:path';
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+export class BrowserStackWorker {
+    deps;
+    /**
+     * Set to observe state updates.
+     */
+    onUpdate = () => { };
+    _state;
+    tasks = new TaskQueue();
+    pollIntervalId = null;
+    captureTimeoutId = null;
+    options;
+    /**
+     * The worker url with an appended reportApi query param.
+     */
+    url;
+    constructor(deps, workerOptions, options) {
+        this.deps = deps;
+        this.tasks.onError = (error) => this.setError(error);
+        this.options = {
+            retries: 2,
+            captureTimeout: 45,
+            pollInterval: 5,
+            logsDir: './bStackLogs',
+            queryParams: null,
+            ...options,
+        };
+        this._state = {
+            localId: crypto.randomUUID(),
+            workerOptions: workerOptions,
+            error: null,
+            session: null,
+            started: false,
+            active: false,
+            workerId: null,
+            sessionId: null,
+            totalSpecs: null,
+            totalCompleted: 0,
+            attemptsRemaining: this.options.retries,
+        };
+        // Add the reportApi query param:
+        const finalUrl = new URL(workerOptions.url);
+        finalUrl.searchParams.set('reportApi', `/report/${this._state.localId}`);
+        // Add the provided query params from options.
+        if (options?.queryParams) {
+            for (const [name, value] of Object.entries(options.queryParams)) {
+                finalUrl.searchParams.set(name, value);
+            }
+        }
+        this.url = finalUrl.toString();
+        if (this.options.logsDir)
+            fs.mkdirSync(this.options.logsDir, { recursive: true });
+    }
+    /**
+     * Returns true if this worker is completed. This will be true if either in an error state or the session status
+     * indicates completion
+     */
+    get completed() {
+        const state = this._state;
+        const status = state.session?.status;
+        return (state.error != null ||
+            (state.started &&
+                status != null &&
+                ['timeout', 'passed', 'failed'].includes(status)));
+    }
+    /**
+     * Returns this worker's state.
+     */
+    get state() {
+        return this._state;
+    }
+    get name() {
+        return this._state.workerOptions.name;
+    }
+    get passed() {
+        return this._state.session?.status === 'passed';
+    }
+    set totalCompleted(value) {
+        this._state.totalCompleted = value;
+    }
+    set totalSpecs(value) {
+        this._state.totalSpecs = value;
+    }
+    done(passed, reason) {
+        const name = this.name;
+        if (passed)
+            logger.info(`✅ ${name} passed`);
+        else
+            logger.info(`❌ ${name} failed\n${reason}\n`);
+        const client = this.deps.client;
+        return this.tasks
+            .enqueue(async () => {
+            const state = this._state;
+            const { sessionId, workerId } = state;
+            if (!sessionId || !workerId) {
+                logger.debug('done aborting - sessionId or workerId is missing');
+                return;
+            }
+            logger.debug('done, passed:', passed);
+            state.session = await client.updateSession(sessionId, {
+                status: passed ? 'passed' : 'failed',
+                reason: reason,
+            });
+            this.onUpdate();
+        })
+            .finally(() => {
+            this.terminate().catch(() => { });
+        });
+    }
+    async refreshSession() {
+        const state = this._state;
+        if (state.sessionId) {
+            state.session = await this.deps.client.getSession(state.sessionId);
+            this.onUpdate();
+        }
+    }
+    appendLogs(logs) {
+        if (this.options.logsDir == null || logs.length === 0)
+            return;
+        const logFilePath = path.join(this.options.logsDir, `${this._state.sessionId}.log`);
+        // Append logs to a file.
+        fs.appendFile(logFilePath, logs.map((entry) => entry.join(' ')).join('\n') + '\n', (error) => {
+            if (error)
+                logger.error('Could not write to console log file:', error);
+        });
+    }
+    /**
+     * Creates the worker/session.
+     */
+    async start() {
+        logger.debug(`Starting session '${this.name}'...`);
+        const state = this._state;
+        state.started = true;
+        await this.tasks
+            .enqueue(async () => {
+            if (state.active)
+                return;
+            state.active = true;
+            this.onUpdate();
+            this.pollIntervalId = setInterval(() => {
+                void this.refreshSession();
+            }, this.options.pollInterval * 1000);
+            this.captureTimeoutId = setTimeout(this.captureTimeoutHandler, this.options.captureTimeout * 1000);
+            const client = this.deps.client;
+            const newWorker = await client.createWorker({
+                ...state.workerOptions,
+                url: this.url,
+            });
+            state.workerId = newWorker.id;
+            const workerDetails = await client.getWorker(newWorker.id);
+            logger.info(`Session created for '${this.name}': ${workerDetails.browser_url}`);
+            state.sessionId = workerDetails.sessionId;
+            await this.refreshSession();
+            this.onUpdate();
+        })
+            .catch((error) => {
+            logger.error(`Session start failed '${this.name}'`, error);
+            state.started = false;
+            this.clearTimers();
+            this.onUpdate();
+        });
+    }
+    /**
+     * Deletes the worker.
+     * The worker may be created again.
+     */
+    terminate() {
+        logger.debug(`Terminate session '${this.name}'`);
+        return this.tasks.enqueue(async () => {
+            const state = this._state;
+            if (!state.active)
+                return;
+            state.active = false;
+            this.clearTimers();
+            const workerId = state.workerId;
+            if (workerId) {
+                state.workerId = null;
+                try {
+                    await this.deps.client.deleteWorker(workerId);
+                    logger.debug(`Terminated worker: ${workerId}`);
+                }
+                catch (error) {
+                    logger.warn('Could not terminate worker:', error);
+                }
+            }
+            logger.debug(`Terminated session '${this.name}'...`);
+            this.onUpdate();
+        });
+    }
+    clearTimers() {
+        if (this.pollIntervalId) {
+            clearInterval(this.pollIntervalId);
+            this.pollIntervalId = null;
+        }
+        if (this.captureTimeoutId) {
+            clearTimeout(this.captureTimeoutId);
+            this.captureTimeoutId = null;
+        }
+    }
+    /**
+     * Deletes the session if it exists.
+     */
+    deleteSession() {
+        const state = this._state;
+        logger.debug(`Delete session '${this.name}'`);
+        return this.tasks.enqueue(async () => {
+            const sessionId = state.sessionId;
+            if (sessionId) {
+                state.sessionId = null;
+                state.session = null;
+                try {
+                    await this.deps.client.deleteSession(sessionId);
+                    logger.debug(`Deleted session '${this.name}'`);
+                }
+                catch (_) {
+                    logger.warn(`Could not delete session '${this.name}'`);
+                }
+                this.onUpdate();
+            }
+        });
+    }
+    /**
+     * Terminates the worker, deletes the session, starts a new worker.
+     */
+    async restart() {
+        await this.terminate().catch(() => { });
+        await this.deleteSession().catch(() => { });
+        await this.start();
+    }
+    /**
+     * Invoked when the capture timeout has been reached. Checks if data has been received from the REST api.
+     */
+    captureTimeoutHandler = () => {
+        const state = this._state;
+        if (state.totalSpecs == null) {
+            if (state.attemptsRemaining > 0) {
+                state.attemptsRemaining--;
+                logger.warn(`No test results received for ${this.name}, retrying. Attempts remaining: ${state.attemptsRemaining}`);
+                this.restart().catch((error) => {
+                    this.setError(error);
+                });
+            }
+            else {
+                this.setError(new Error(`Did not capture test progress after ${this.options.retries + 1} attempts for '${this.name}'.`));
+            }
+        }
+    };
+    /**
+     * Sets the worker to a failed state and terminates.
+     */
+    setError(error) {
+        const state = this._state;
+        if (state.error)
+            return; // Already in an erred state.
+        state.error = error;
+        logger.error(error == null
+            ? 'An internal error has occurred.'
+            : (error.message ?? String(error)));
+        this.tasks
+            .enqueue(async () => {
+            if (state.sessionId) {
+                state.session = await this.deps.client.updateSession(state.sessionId, {
+                    status: 'failed',
+                    reason: error?.message ?? 'Internal error',
+                });
+                this.onUpdate();
+            }
+        })
+            .catch(() => { });
+        this.terminate().catch(() => { });
+    }
+}

package/dist/browserstack/BrowserStackWorkerController.d.ts

@@ -0,0 +1,103 @@
+import type { BrowserStackWorkerOptions, ReadonlyBrowserStackWorkerState } from './BrowserStackWorker';
+import type { BrowserStackAutomateClient, WorkerOptions } from './browserStackRestApi';
+import type { DoneRequest, ProgressRequest, ReportingListener, StartedRequest } from './configureReporterApi';
+export interface BrowserStackWorkerControllerDeps {
+    /**
+     * The BrowserStack REST API client.
+     */
+    readonly client: BrowserStackAutomateClient;
+}
+export interface BrowserStackWorkerControllerOptions {
+    /**
+     * Configuration to provide to each Worker.
+     */
+    readonly worker?: BrowserStackWorkerOptions;
+    /**
+     * The maximum number of sessions to run in parallel.
+     * If not set, the maximum number of sessions according to the automate plan will be used.
+     */
+    readonly maxSessions?: number;
+}
+export interface BrowserStackWorkerControllerState {
+    readonly workers: readonly ReadonlyBrowserStackWorkerState[];
+    /**
+     * The number of workers not yet started.
+     */
+    pending: number;
+    /**
+     * The number of workers currently active.
+     */
+    running: number;
+    /**
+     * The number of workers completed and passed.
+     */
+    passed: number;
+    /**
+     * The number of workers completed and failed.
+     */
+    failed: number;
+    /**
+     * The estimated percentage complete, a number from 0-1.
+     */
+    percentComplete: number;
+    /**
+     * The total number of workers not yet completed.
+     */
+    remaining: number;
+    /**
+     * The total number of workers.
+     */
+    readonly total: number;
+}
+export type ReadonlyBrowserStackWorkerControllerState = Readonly<BrowserStackWorkerControllerState>;
+export declare class BrowserStackWorkerController implements ReportingListener {
+    private readonly deps;
+    private readonly options?;
+    /**
+     * Set to observe state updates.
+     */
+    onUpdate: () => void;
+    private readonly _state;
+    private readonly workers;
+    /**
+     * Maps the worker's local id to the worker.
+     */
+    private readonly localIdToWorkerMap;
+    private sessionPollIntervalId;
+    /**
+     * Tracks an in-flight startSessions invocation. While set, additional calls
+     * are deferred until the current one settles to avoid redundant API calls
+     * and racing state updates.
+     */
+    private startSessionsInFlight;
+    /**
+     * If set during an in-flight startSessions, indicates another invocation
+     * was requested and should run after the current one settles.
+     */
+    private startSessionsRequested;
+    constructor(deps: BrowserStackWorkerControllerDeps, browsers: readonly WorkerOptions[], options?: BrowserStackWorkerControllerOptions | undefined);
+    get state(): ReadonlyBrowserStackWorkerControllerState;
+    shouldHandleRequest(id: string): boolean;
+    onStarted(request: StartedRequest): void;
+    onProgress(request: ProgressRequest): void;
+    onDone(request: DoneRequest): void;
+    private refreshState;
+    /**
+     * Refreshes the current state and invokes the onUpdate callback.
+     */
+    private updateHandler;
+    /**
+     * Begins new workers until the maximum parallel sessions is reached.
+     * Reentrancy-safe: if invoked while a previous invocation is still
+     * running, schedules a single follow-up to run after it settles.
+     */
+    private startSessions;
+    private clearOpenSessionPollTimeout;
+    get allPassed(): boolean;
+    start(): void;
+    /**
+     * Terminates all running workers.
+     */
+    terminate(): Promise<void>;
+}
+//# sourceMappingURL=BrowserStackWorkerController.d.ts.map

package/dist/browserstack/BrowserStackWorkerController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrowserStackWorkerController.d.ts","sourceRoot":"","sources":["../../src/browserstack/BrowserStackWorkerController.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACR,yBAAyB,EACzB,+BAA+B,EAClC,MAAM,sBAAsB,CAAA;AAE7B,OAAO,KAAK,EACR,0BAA0B,EAC1B,aAAa,EAChB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,KAAK,EACR,WAAW,EACX,eAAe,EACf,iBAAiB,EACjB,cAAc,EACjB,MAAM,wBAAwB,CAAA;AAG/B,MAAM,WAAW,gCAAgC;IAC7C;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,0BAA0B,CAAA;CAC9C;AAED,MAAM,WAAW,mCAAmC;IAChD;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,yBAAyB,CAAA;IAE3C;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAChC;AAED,MAAM,WAAW,iCAAiC;IAC9C,QAAQ,CAAC,OAAO,EAAE,SAAS,+BAA+B,EAAE,CAAA;IAE5D;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IAEf;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IAEf;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IAEd;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IAEd;;OAEG;IACH,eAAe,EAAE,MAAM,CAAA;IAEvB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IAEjB;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,MAAM,yCAAyC,GACjD,QAAQ,CAAC,iCAAiC,CAAC,CAAA;AAI/C,qBAAa,4BAA6B,YAAW,iBAAiB;IA8B9D,OAAO,CAAC,QAAQ,CAAC,IAAI;IAErB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IA/B7B;;OAEG;IACI,QAAQ,EAAE,MAAM,IAAI,CAAW;IAEtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;IAC1D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAE9C;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAiC;IAEpE,OAAO,CAAC,qBAAqB,CAAuB;IAEpD;;;;OAIG;IACH,OAAO,CAAC,qBAAqB,CAA6B;IAE1D;;;OAGG;IACH,OAAO,CAAC,sBAAsB,CAAQ;gBAGjB,IAAI,EAAE,gCAAgC,EACvD,QAAQ,EAAE,SAAS,aAAa,EAAE,EACjB,OAAO,CAAC,EAAE,mCAAmC,YAAA;IA2BlE,IAAI,KAAK,IAAI,yCAAyC,CAErD;IAED,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIxC,SAAS,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;IAKxC,UAAU,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAM1C,MAAM,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;IAQlC,OAAO,CAAC,YAAY;IA8BpB;;OAEG;IACH,OAAO,CAAC,aAAa,CAMpB;IAED;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAwErB,OAAO,CAAC,2BAA2B;IAOnC,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,KAAK,IAAI,IAAI;IAKb;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;CAenC"}