depvitals 0.1.2 → 0.3.0

package/dist/cli/notifier/registryLookup.d.ts

@@ -0,0 +1,111 @@
+/**
+ * One bounded public lookup of the DepVitals `latest` dist-tag (Step 66).
+ *
+ * This is the **only** place in the whole product that may perform a network request, and the only
+ * thing it can ever ask for is the public dist-tag metadata of the `depvitals` package itself.
+ * Nothing about the analyzed project is used here: no project path, no manifest content, no
+ * dependency name, no version, no user data and no credential of any kind. Core analysis stays
+ * fully offline - this module lives under `src/cli/notifier/` and is never reachable from
+ * `core/`, `scanner/`, `detectors/` or `reporters/` (asserted by tests), and it stays unwired until
+ * the CLI integration step introduces the notifier orchestrator.
+ *
+ * Contract enforced by this module:
+ *
+ * 1. the URL is the fixed constant {@link NPM_DIST_TAGS_ENDPOINT}; nothing is appended to it and no
+ *    caller-supplied string reaches it;
+ * 2. the whole fetch + body + parse operation is bounded by a short timeout, and the bound cannot
+ *    be loosened past {@link UPDATE_LOOKUP_MAX_TIMEOUT_MS}; when the bound elapses the request is
+ *    abandoned (the abort signal tears the request down) and the result is `null`;
+ * 3. a successful HTTP status is required, the body must stay at or below
+ *    {@link MAX_UPDATE_RESPONSE_BYTES}, it must parse as a JSON object with an own `latest` string,
+ *    and that string must be an exact stable version according to the single grammar owned by
+ *    Step 63 (`versionCompare.parseStableVersion`);
+ * 4. **every** failure mode - DNS, TLS, abort/timeout, non-2xx status, empty/oversized/malformed
+ *    body, body stream error, invalid version - yields `null`. The function never throws and never
+ *    logs, because an optional convenience must not be able to break or delay a scan;
+ * 5. there are no retries: a failed lookup costs exactly one request and the caller falls back to
+ *    "no notice", and the request carries no headers, so no npm token can leak to the registry.
+ *
+ * Testability: `fetch` and the abort-signal factory are injected, so the tests never touch the real
+ * network, never depend on a real DNS/TLS stack and can simulate a hanging request deterministically.
+ */
+/**
+ * The fixed public endpoint of the update check, exactly as mandated by the update-notifier
+ * contract. It is a constant so that no project-derived value can ever influence the request.
+ */
+export declare const NPM_DIST_TAGS_ENDPOINT = "https://registry.npmjs.org/-/package/depvitals/dist-tags";
+/**
+ * Default hard bound for the complete request: one fetch plus its body and parse. Kept inside the
+ * 300-500 ms window agreed for the notifier, so a slow or unreachable registry can only ever cost a
+ * fraction of a second of an already finished scan.
+ */
+export declare const UPDATE_LOOKUP_TIMEOUT_MS = 400;
+/**
+ * Absolute ceiling for any injected timeout. Callers (and tests) may shorten the bound but cannot
+ * turn the "short hard timeout" of the contract into an unbounded wait.
+ */
+export declare const UPDATE_LOOKUP_MAX_TIMEOUT_MS = 500;
+/**
+ * Largest response body that is accepted. The real dist-tag document is a few dozen bytes, so the
+ * cap only ever rejects something hostile or unexpected; it is enforced while streaming, not after
+ * buffering an arbitrarily large payload.
+ */
+export declare const MAX_UPDATE_RESPONSE_BYTES: number;
+/**
+ * The single stream method this lookup needs from a response body, i.e. a byte stream that can be
+ * read incrementally and released early.
+ */
+export type RegistryStreamReader = {
+    read(): Promise<{
+        done: boolean;
+        value: Uint8Array | undefined;
+    }>;
+    cancel(reason?: unknown): Promise<void>;
+};
+/** Response body shape: readable as a byte stream, or absent (`null`, e.g. for a 204). */
+export type RegistryResponseBody = {
+    getReader(): RegistryStreamReader;
+};
+/** The only response property this lookup consults: the HTTP status plus an optional body. */
+export type RegistryResponse = {
+    readonly status: number;
+    readonly body: RegistryResponseBody | null;
+};
+/** The only request property this lookup sends: the timeout/abort signal. Never headers or bodies. */
+export type RegistryRequestInit = {
+    readonly signal: AbortSignal;
+};
+/**
+ * The injected `fetch` implementation. It is required rather than defaulted so that no accidental
+ * call inside this repository can reach the network: production callers pass the Node built-in
+ * `fetch`, tests pass a stub returning canned responses and canned failures.
+ */
+export type RegistryFetch = (endpoint: string, init: RegistryRequestInit) => Promise<RegistryResponse>;
+/** Dependencies of one lookup. Every field is injected, so nothing ambient is read implicitly. */
+export type RegistryLookupOptions = {
+    /** Transport to use, e.g. the Node built-in `fetch` bound by the caller. */
+    readonly fetchImpl: RegistryFetch;
+    /**
+     * Optional shorter bound in milliseconds, clamped into `[0, UPDATE_LOOKUP_MAX_TIMEOUT_MS]`.
+     * Defaults to {@link UPDATE_LOOKUP_TIMEOUT_MS}.
+     */
+    readonly timeoutMs?: number;
+    /**
+     * Abort-signal factory, defaulting to `AbortSignal.timeout`. Tests inject a factory returning a
+     * controller signal (or an already-aborted signal) to exercise the timeout path without waiting.
+     */
+    readonly createAbortSignal?: (timeoutMs: number) => AbortSignal;
+};
+/**
+ * Fetch the public `latest` dist-tag of the **DepVitals package itself**, at most once.
+ *
+ * The call is fully isolated: it never throws, never retries, never writes to stdout or stderr and
+ * never sends project-derived data or credentials. Any problem - DNS failure, TLS failure, abort or
+ * timeout, HTTP error status, empty, oversized, HTML or malformed body, missing `latest`, body
+ * stream error - results in `null`, which the caller must treat as "no update information".
+ *
+ * @param options - Injected transport and (optionally) a shorter timeout plus abort-signal factory.
+ * @returns the validated stable version string, or `null` for every other outcome.
+ */
+export declare function fetchLatestDepVitalsVersion(options: RegistryLookupOptions): Promise<string | null>;
+//# sourceMappingURL=registryLookup.d.ts.map

package/dist/cli/notifier/registryLookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registryLookup.d.ts","sourceRoot":"","sources":["../../../src/cli/notifier/registryLookup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAIH;;;GAGG;AACH,eAAO,MAAM,sBAAsB,6DAA6D,CAAC;AAEjG;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAE5C;;;GAGG;AACH,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,QAAW,CAAC;AAElD;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,UAAU,GAAG,SAAS,CAAA;KAAE,CAAC,CAAC;IAClE,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC,CAAC;AAEF,0FAA0F;AAC1F,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,IAAI,oBAAoB,CAAC;CACnC,CAAC;AAEF,8FAA8F;AAC9F,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,oBAAoB,GAAG,IAAI,CAAC;CAC5C,CAAC;AAEF,sGAAsG;AACtG,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,mBAAmB,KACtB,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAE/B,kGAAkG;AAClG,MAAM,MAAM,qBAAqB,GAAG;IAClC,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,WAAW,CAAC;CACjE,CAAC;AA2KF;;;;;;;;;;GAUG;AACH,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAWxB"}

package/dist/cli/notifier/registryLookup.js

@@ -0,0 +1,211 @@
+/**
+ * One bounded public lookup of the DepVitals `latest` dist-tag (Step 66).
+ *
+ * This is the **only** place in the whole product that may perform a network request, and the only
+ * thing it can ever ask for is the public dist-tag metadata of the `depvitals` package itself.
+ * Nothing about the analyzed project is used here: no project path, no manifest content, no
+ * dependency name, no version, no user data and no credential of any kind. Core analysis stays
+ * fully offline - this module lives under `src/cli/notifier/` and is never reachable from
+ * `core/`, `scanner/`, `detectors/` or `reporters/` (asserted by tests), and it stays unwired until
+ * the CLI integration step introduces the notifier orchestrator.
+ *
+ * Contract enforced by this module:
+ *
+ * 1. the URL is the fixed constant {@link NPM_DIST_TAGS_ENDPOINT}; nothing is appended to it and no
+ *    caller-supplied string reaches it;
+ * 2. the whole fetch + body + parse operation is bounded by a short timeout, and the bound cannot
+ *    be loosened past {@link UPDATE_LOOKUP_MAX_TIMEOUT_MS}; when the bound elapses the request is
+ *    abandoned (the abort signal tears the request down) and the result is `null`;
+ * 3. a successful HTTP status is required, the body must stay at or below
+ *    {@link MAX_UPDATE_RESPONSE_BYTES}, it must parse as a JSON object with an own `latest` string,
+ *    and that string must be an exact stable version according to the single grammar owned by
+ *    Step 63 (`versionCompare.parseStableVersion`);
+ * 4. **every** failure mode - DNS, TLS, abort/timeout, non-2xx status, empty/oversized/malformed
+ *    body, body stream error, invalid version - yields `null`. The function never throws and never
+ *    logs, because an optional convenience must not be able to break or delay a scan;
+ * 5. there are no retries: a failed lookup costs exactly one request and the caller falls back to
+ *    "no notice", and the request carries no headers, so no npm token can leak to the registry.
+ *
+ * Testability: `fetch` and the abort-signal factory are injected, so the tests never touch the real
+ * network, never depend on a real DNS/TLS stack and can simulate a hanging request deterministically.
+ */
+import { parseStableVersion } from './versionCompare.js';
+/**
+ * The fixed public endpoint of the update check, exactly as mandated by the update-notifier
+ * contract. It is a constant so that no project-derived value can ever influence the request.
+ */
+export const NPM_DIST_TAGS_ENDPOINT = 'https://registry.npmjs.org/-/package/depvitals/dist-tags';
+/**
+ * Default hard bound for the complete request: one fetch plus its body and parse. Kept inside the
+ * 300-500 ms window agreed for the notifier, so a slow or unreachable registry can only ever cost a
+ * fraction of a second of an already finished scan.
+ */
+export const UPDATE_LOOKUP_TIMEOUT_MS = 400;
+/**
+ * Absolute ceiling for any injected timeout. Callers (and tests) may shorten the bound but cannot
+ * turn the "short hard timeout" of the contract into an unbounded wait.
+ */
+export const UPDATE_LOOKUP_MAX_TIMEOUT_MS = 500;
+/**
+ * Largest response body that is accepted. The real dist-tag document is a few dozen bytes, so the
+ * cap only ever rejects something hostile or unexpected; it is enforced while streaming, not after
+ * buffering an arbitrarily large payload.
+ */
+export const MAX_UPDATE_RESPONSE_BYTES = 8 * 1024;
+/** The Node built-in timeout signal, wrapped so the default never depends on `this`. */
+function defaultCreateAbortSignal(timeoutMs) {
+    return AbortSignal.timeout(timeoutMs);
+}
+/**
+ * Clamp an injected timeout into the contract's hard bound. Non-finite values (NaN, Infinity) fall
+ * back to the default instead of disabling the bound.
+ */
+function boundTimeout(value) {
+    if (!Number.isFinite(value)) {
+        return UPDATE_LOOKUP_TIMEOUT_MS;
+    }
+    if (value < 0) {
+        return 0;
+    }
+    return Math.min(value, UPDATE_LOOKUP_MAX_TIMEOUT_MS);
+}
+/**
+ * Run `operation` under an abort deadline. The first caller to settle wins: a request that ignores
+ * its signal can still not extend the scan, because the deadline resolution is produced here instead
+ * of relying on the transport to reject.
+ *
+ * @returns whatever `operation` resolved with, or `null` when the deadline aborted first.
+ */
+async function withAbortDeadline(signal, operation) {
+    if (signal.aborted) {
+        // The deadline is already gone: do not start a request that cannot be answered in time.
+        return null;
+    }
+    let onAbort;
+    const deadline = new Promise((resolve) => {
+        onAbort = () => {
+            resolve(null);
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+    const request = operation();
+    try {
+        // `Promise.race` attaches handlers to both promises, so a request that fails after the deadline
+        // won the race cannot surface an unhandled rejection either.
+        return await Promise.race([request, deadline]);
+    }
+    finally {
+        if (onAbort !== undefined) {
+            signal.removeEventListener('abort', onAbort);
+        }
+    }
+}
+/**
+ * Read a response body incrementally, accepting at most {@link MAX_UPDATE_RESPONSE_BYTES} in total.
+ *
+ * Bytes are concatenated before decoding, so a valid body split into chunks at any boundary (even
+ * inside a multi-byte UTF-8 character) decodes correctly, and an oversized body is abandoned as soon
+ * as the cap is crossed instead of being buffered.
+ *
+ * @returns the decoded text, or `null` when the body exceeded the cap.
+ */
+async function readCappedText(reader) {
+    const chunks = [];
+    let totalBytes = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done) {
+            break;
+        }
+        if (value === undefined) {
+            continue;
+        }
+        totalBytes += value.byteLength;
+        if (totalBytes > MAX_UPDATE_RESPONSE_BYTES) {
+            // Release the stream; a failing `cancel` is irrelevant because the answer is already `null`.
+            await reader.cancel().catch(() => undefined);
+            return null;
+        }
+        chunks.push(value);
+    }
+    const bytes = new Uint8Array(totalBytes);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return new TextDecoder('utf-8').decode(bytes);
+}
+/**
+ * Extract the `latest` dist-tag from the response text.
+ *
+ * Only a JSON object with an own `latest` **string** that is an exact stable DepVitals version is
+ * accepted. HTML, truncated JSON, a non-object root, a missing or wrongly-typed `latest`, and a
+ * prerelease/build-tagged/malformed version all mean "no answer".
+ */
+function extractLatestVersion(text) {
+    let document;
+    try {
+        document = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (typeof document !== 'object' || document === null || Array.isArray(document)) {
+        return null;
+    }
+    if (!Object.hasOwn(document, 'latest')) {
+        return null;
+    }
+    const latest = document['latest'];
+    if (typeof latest !== 'string') {
+        return null;
+    }
+    // One grammar for "exact stable version", owned by Step 63; prerelease and malformed never pass.
+    return parseStableVersion(latest) === undefined ? null : latest;
+}
+/**
+ * Perform one bounded read of the dist-tag document and return the validated `latest` version.
+ *
+ * @throws whatever the transport or the body stream throws; the public wrapper converts every
+ *   failure into `null`.
+ */
+async function requestLatest(fetchImpl, signal) {
+    const response = await fetchImpl(NPM_DIST_TAGS_ENDPOINT, { signal });
+    // A redirect, 4xx or 5xx answer is not metadata; the body is not even read.
+    if (response.status < 200 || response.status >= 300) {
+        return null;
+    }
+    if (response.body === null) {
+        return null;
+    }
+    const text = await readCappedText(response.body.getReader());
+    if (text === null) {
+        return null;
+    }
+    return extractLatestVersion(text);
+}
+/**
+ * Fetch the public `latest` dist-tag of the **DepVitals package itself**, at most once.
+ *
+ * The call is fully isolated: it never throws, never retries, never writes to stdout or stderr and
+ * never sends project-derived data or credentials. Any problem - DNS failure, TLS failure, abort or
+ * timeout, HTTP error status, empty, oversized, HTML or malformed body, missing `latest`, body
+ * stream error - results in `null`, which the caller must treat as "no update information".
+ *
+ * @param options - Injected transport and (optionally) a shorter timeout plus abort-signal factory.
+ * @returns the validated stable version string, or `null` for every other outcome.
+ */
+export async function fetchLatestDepVitalsVersion(options) {
+    try {
+        const createAbortSignal = options.createAbortSignal ?? defaultCreateAbortSignal;
+        const timeoutMs = boundTimeout(options.timeoutMs ?? UPDATE_LOOKUP_TIMEOUT_MS);
+        const signal = createAbortSignal(timeoutMs);
+        return await withAbortDeadline(signal, () => requestLatest(options.fetchImpl, signal));
+    }
+    catch {
+        // No error detail is reported anywhere: an optional network convenience stays silent.
+        return null;
+    }
+}
+//# sourceMappingURL=registryLookup.js.map

package/dist/cli/notifier/registryLookup.js.map

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

package/dist/cli/notifier/updateCache.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Best-effort 24-hour cache for the optional CLI update check (Step 65).
+ *
+ * The update-notifier contract allows **at most one** bounded public registry lookup per user per
+ * day, so the version reported by a previous run is remembered in a tiny private cache file:
+ *
+ * ```json
+ * { "latest": "0.2.1", "checkedAt": 1792170000000 }
+ * ```
+ *
+ * Design rules, all of them derived from the contract and from the repository invariants:
+ *
+ * - **Outside every analyzed project.** The path is always resolved from a user-scoped environment
+ *   variable or from the user's home directory, and a candidate that is not absolute is rejected.
+ *   No part of the path is ever derived from the scanned directory, from `cwd`, or from any project
+ *   file, so scanning a project named `depvitals` - or running from any working directory - cannot
+ *   place the cache inside that project.
+ * - **Minimal, private content.** Only the public `latest` version string and the timestamp of the
+ *   check are stored: no project path, no manifest content, no dependency list, no credential, no
+ *   machine identifier and no telemetry. The directory is created `0o700` and the file `0o600` on
+ *   platforms that honor POSIX mode bits.
+ * - **Untrusted on read.** Cached data is treated exactly like untrusted registry data: missing
+ *   file, unreadable file, oversized file, non-regular file (including a symlink), invalid JSON,
+ *   wrong types, unexpected extra keys, a negative timestamp and a timestamp in the future are all
+ *   cache *misses*, never errors.
+ * - **Invisible on failure.** Every filesystem operation is wrapped so that permission denied,
+ *   read-only media, a missing parent directory or a failing rename resolve normally instead of
+ *   throwing. Nothing here writes to stdout/stderr, and nothing here can change scan output or the
+ *   process exit code.
+ *
+ * The module performs no network access, decides no eligibility, prints nothing and is deliberately
+ * not wired into the CLI yet: the update check is assembled in Step 67, and the registry lookup
+ * itself belongs to Step 66. Because both helpers are asynchronous, callers must await them so a
+ * short-lived process does not exit before the cache write finishes.
+ */
+/** Environment map shaped like the ambient environment, so tests can inject any values. */
+export type UpdateCacheEnvironment = Readonly<Record<string, string | undefined>>;
+/**
+ * The freshness window. An entry is usable while its age is `>= 0` and strictly below this value;
+ * an older entry is a miss, which is what allows a later step to refresh it.
+ */
+export declare const UPDATE_CACHE_TTL_MS: number;
+/** Name of the cache file, exported so callers and documentation can name the exact path. */
+export declare const UPDATE_CACHE_FILE_NAME = "update-check.json";
+/** Everything that influences *where* the cache lives; all of it injectable. */
+export type UpdateCacheLocationOptions = {
+    /**
+     * Explicit cache directory, intended for tests and for a future explicit override. Only an
+     * absolute path is honored: a relative value is ignored rather than resolved against `cwd`, and
+     * resolution continues with the user-scoped defaults below, which is what keeps the cache out of
+     * any analyzed project.
+     */
+    readonly cacheDir?: string;
+    /** Environment map to consult, e.g. the caller's own environment object. */
+    readonly env?: UpdateCacheEnvironment;
+    /** Home directory provider, defaulting to `node:os` `homedir()`. */
+    readonly homedir?: () => string;
+    /** Platform identifier, defaulting to `process.platform`; `'win32'` selects Windows rules. */
+    readonly platform?: string;
+};
+/** A cache operation additionally needs the injected current time, in epoch milliseconds. */
+export type UpdateCacheOptions = UpdateCacheLocationOptions & {
+    /** Current time in epoch milliseconds; a non-integer or negative value disables the operation. */
+    readonly now: number;
+};
+/**
+ * Resolve the absolute path of the cache file, or `undefined` when no safe location exists, i.e.
+ * when no usable cache environment variable and no absolute home directory is available. A
+ * relative `cacheDir` is ignored in favor of those user-scoped defaults. The result never depends
+ * on the scanned directory or on `cwd`.
+ *
+ * @param options - Location inputs (override directory, environment map, home provider, platform).
+ * @returns The absolute cache file path, or `undefined` when caching is impossible.
+ */
+export declare function resolveUpdateCacheFile(options?: UpdateCacheLocationOptions): string | undefined;
+/**
+ * Look up a fresh cached `latest` version.
+ *
+ * Returns the cached string only when the record exists, is valid, and its age is `>= 0` and below
+ * {@link UPDATE_CACHE_TTL_MS}. Every other case - no file, invalid or oversized content, wrong
+ * types, an extra key, a negative or future timestamp, a permission error, a symlink, a locked-down
+ * home folder - returns `undefined`, i.e. a miss. This function never throws and never logs, so a
+ * broken cache can never change a scan.
+ *
+ * @param options - The injected clock plus the cache location inputs.
+ * @returns The cached `latest` version, or `undefined` when the cache must be treated as empty.
+ */
+export declare function readCachedLatest(options: UpdateCacheOptions): Promise<string | undefined>;
+/**
+ * Record a `latest` version together with the injected current time.
+ *
+ * The write is best effort and completely silent: it creates the cache directory if needed
+ * (`0o700`), stages the file (`0o600`) and renames it into place, and it resolves normally even when
+ * nothing at all could be written. Only the two contract-approved fields are serialized.
+ *
+ * @param latest - The public `latest` version string to remember; anything whitespace/control-bearing,
+ *   empty or longer than 64 characters is not written.
+ * @param options - The injected clock plus the cache location inputs.
+ */
+export declare function writeCachedLatest(latest: string, options: UpdateCacheOptions): Promise<void>;
+//# sourceMappingURL=updateCache.d.ts.map

package/dist/cli/notifier/updateCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"updateCache.d.ts","sourceRoot":"","sources":["../../../src/cli/notifier/updateCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAMH,2FAA2F;AAC3F,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAElF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,QAAsB,CAAC;AAEvD,6FAA6F;AAC7F,eAAO,MAAM,sBAAsB,sBAAsB,CAAC;AA6D1D,gFAAgF;AAChF,MAAM,MAAM,0BAA0B,GAAG;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,CAAC,EAAE,sBAAsB,CAAC;IACtC,oEAAoE;IACpE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;IAChC,8FAA8F;IAC9F,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,6FAA6F;AAC7F,MAAM,MAAM,kBAAkB,GAAG,0BAA0B,GAAG;IAC5D,kGAAkG;IAClG,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB,CAAC;AAsHF;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,GAAE,0BAA+B,GACvC,MAAM,GAAG,SAAS,CAEpB;AA+ED;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAoC/F;AA6CD;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAmBf"}