@cdxgen/cdxgen 0.0.1 → 13.0.0

package/types/lib/inventory/envcontext.d.ts

@@ -0,0 +1,377 @@
+/**
+ * Git executable name used for all git invocations, overridable via GIT_CMD.
+ *
+ * @type {string}
+ */
+export declare const GIT_COMMAND: string;
+/**
+ * sdkman tool aliases mapping java version identifiers to candidate ids.
+ *
+ * Each alias can be overridden via the matching `JAVA*_TOOL` environment
+ * variable and otherwise defaults to a Temurin candidate version.
+ *
+ * @type {Object<string, string>}
+ */
+export declare const SDKMAN_JAVA_TOOL_ALIASES: Record<string, string>;
+/**
+ * Retrieves a git config item
+ * @param {string} configKey Git config key
+ * @param {string} dir repo directory
+ *
+ * @returns Output from git config or undefined
+ */
+export declare function getGitConfig(configKey: string, dir: string): string | undefined;
+/**
+ * Retrieves the git origin url
+ * @param {string} dir repo directory
+ *
+ * @returns Output from git config or undefined
+ */
+export declare function getOriginUrl(dir: string): string | undefined;
+/**
+ * Retrieves the git branch name
+ * @param {string} configKey Git config key
+ * @param {string} dir repo directory
+ *
+ * @returns Output from git config or undefined
+ */
+export declare function getBranch(_configKey: any, dir: string): string | undefined;
+/**
+ * Retrieves the tree and parent hash for a git repo
+ * @param {string} dir repo directory
+ *
+ * @returns Output from git cat-file or undefined
+ */
+export declare function gitTreeHashes(dir: string): {};
+/**
+ * Retrieves the files list from git
+ * @param {string} dir repo directory
+ *
+ * @returns Output from git config or undefined
+ */
+export declare function listFiles(dir: string): any[];
+/**
+ * Execute a git command
+ *
+ * @param {string} dir Repo directory
+ * @param {Array} args arguments to git command
+ *
+ * @returns Output from the git command
+ */
+export declare function execGitCommand(dir: string, args: any[]): string | undefined;
+/**
+ * Retrieves the author names and emails from the git commit log
+ *
+ * @param {string} dir Repo directory
+ * @param {number} maxCount Maximum number of commits to retrieve
+ *
+ * @returns {Array<{name: string, email: string}>} Array of authors
+ */
+export declare function gitLogAuthors(dir: string, maxCount?: number): Array<{
+    name: string;
+    email: string;
+}>;
+/**
+ * Retrieves the commit logs for a git repo, returning hashes and messages
+ *
+ * @param {string} dir Repo directory
+ * @param {number} maxCount Maximum number of commits to retrieve
+ *
+ * @returns {Array<{hash: string, message: string}>} Array of commit objects
+ */
+export declare function gitLogTrailers(dir: string, maxCount?: number): Array<{
+    hash: string;
+    message: string;
+}>;
+/**
+ * Collect Java version and installed modules
+ *
+ * @param {string} dir Working directory
+ * @returns Object containing the java details
+ */
+export declare function collectJavaInfo(dir: string): {
+    type: string;
+    name: string;
+    version: string;
+    description: string;
+    properties: {
+        name: string;
+        value: string;
+    }[];
+} | undefined;
+/**
+ * Collect dotnet version
+ *
+ * @param {string} dir Working directory
+ * @returns Object containing dotnet details
+ */
+export declare function collectDotnetInfo(dir: string): {
+    type: string;
+    name: string;
+    version: string;
+    description: string;
+} | undefined;
+/**
+ * Collect python version
+ *
+ * @param {string} dir Working directory
+ * @returns Object containing python details
+ */
+export declare function collectPythonInfo(dir: string): {
+    type: string;
+    name: string;
+    version: string;
+    description: string;
+} | undefined;
+/**
+ * Collect node runtime version
+ *
+ * @param {string} dir Working directory
+ * @returns {Object} Object containing node details
+ */
+export declare function collectNodeInfo(dir: string): Object;
+/**
+ * Collect gcc version
+ *
+ * @param {string} dir Working directory
+ * @returns Object containing gcc details
+ */
+export declare function collectGccInfo(dir: string): {
+    type: string;
+    name: string;
+    version: string;
+    description: string;
+} | undefined;
+/**
+ * Collect rust version
+ *
+ * @param {string} dir Working directory
+ * @returns Object containing rust details
+ */
+export declare function collectRustInfo(dir: string): {
+    type: string;
+    name: string;
+    version: string;
+    description: string;
+} | undefined;
+/**
+ * Collect go version
+ *
+ * @param {string} dir Working directory
+ * @returns Object containing go details
+ */
+export declare function collectGoInfo(dir: string): {
+    type: string;
+    name: string;
+    version: string;
+} | undefined;
+/**
+ * Collect swift version
+ *
+ * @param {string} dir Working directory
+ * @returns Object containing swift details
+ */
+export declare function collectSwiftInfo(dir: string): {
+    type: string;
+    name: string;
+    version: string;
+} | undefined;
+/**
+ * Collect Ruby version
+ *
+ * @param {string} dir Working directory
+ * @returns Object containing Ruby details
+ */
+export declare function collectRubyInfo(dir: string): {
+    type: string;
+    name: string;
+    version: string;
+} | undefined;
+/**
+ * Method to run a swift command
+ *
+ * @param {String} dir Working directory
+ * @param {Array} args Command arguments
+ * @returns Object containing swift details
+ */
+export declare function runSwiftCommand(dir: string, args: any[]): string | undefined;
+/**
+ * Collect toolchain information components for the current environment.
+ *
+ * Probes the working directory for java, dotnet, python, node, gcc, rust, go,
+ * and ruby toolchains and returns one component per detected tool.
+ *
+ * @param {string} dir Working directory to inspect
+ * @returns {Object[]} Array of toolchain component objects; empty when nothing is detected
+ */
+export declare function collectEnvInfo(dir: string): Object[];
+/**
+ * Method to check if sdkman is available.
+ */
+export declare function isSdkmanAvailable(): boolean;
+/**
+ * Method to check if nvm is available.
+ */
+export declare function isNvmAvailable(): boolean;
+/**
+ * Method to check if a given sdkman tool is installed and available.
+ *
+ * @param {String} toolType Tool type such as java, gradle, maven etc.
+ * @param {String} toolName Tool name with version. Eg: 22.0.2-tem
+ *
+ * @returns {Boolean} true if the tool is available. false otherwise.
+ */
+export declare function isSdkmanToolAvailable(toolType: string, toolName: string): boolean;
+/**
+ * Method to install and use a given sdkman tool.
+ *
+ * @param {String} toolType Tool type such as java, gradle, maven etc.
+ * @param {String} toolName Tool name with version. Eg: 22.0.2-tem
+ *
+ * @returns {Boolean} true if the tool is available. false otherwise.
+ */
+export declare function installSdkmanTool(toolType: string, toolName: string): boolean;
+/**
+ * Method to check if a given nvm tool is installed and available.
+ *
+ * @param {String} toolName Tool name with version. Eg: 22.0.2-tem
+ *
+ * @returns {String} path of nvm if present, otherwise false
+ */
+export declare function getNvmToolDirectory(toolName: string): string;
+/**
+ * Method to return nvm tool path
+ *
+ * @param {String} toolVersion Tool name with version. Eg: 22.0.2-tem
+ *
+ * @returns {String} path of the tool if not found installs and then returns paths. false if encounters an error.
+ */
+export declare function getOrInstallNvmTool(toolVersion: string): string;
+/**
+ * Method to check if rbenv is available.
+ *
+ * @returns {Boolean} true if rbenv is available. false otherwise.
+ */
+export declare function isRbenvAvailable(): boolean;
+/**
+ * Returns the rbenv binary directory for the given Ruby version.
+ * Respects the `RBENV_ROOT` environment variable when set; otherwise falls back
+ * to `~/.rbenv/versions/<rubyVersion>/bin`.
+ *
+ * @param {string} rubyVersion Ruby version string (e.g. `"3.2.2"`)
+ * @returns {string} Absolute path to the rbenv bin directory for that version
+ */
+export declare function rubyVersionDir(rubyVersion: string): string;
+/**
+ * Perform bundle install using Ruby container images. Not working cleanly yet.
+ *
+ * @param rubyVersion Ruby version
+ * @param cdxgenGemHome Gem Home
+ * @param filePath Path
+ */
+export declare function bundleInstallWithDocker(rubyVersion: any, cdxgenGemHome: any, filePath: any): boolean;
+/**
+ * Install a particular ruby version using rbenv.
+ *
+ * @param rubyVersion Ruby version to install
+ * @param filePath File path
+ */
+export declare function installRubyVersion(rubyVersion: any, filePath: any): {
+    fullToolBinDir: undefined;
+    status: boolean;
+} | {
+    fullToolBinDir: string;
+    status: boolean;
+};
+/**
+ * Method to install bundler using gem.
+ *
+ * @param rubyVersion Ruby version
+ * @param bundlerVersion Bundler version
+ */
+export declare function installRubyBundler(rubyVersion: any, bundlerVersion: any): boolean;
+/**
+ * Method to perform bundle install
+ *
+ * @param cdxgenGemHome cdxgen Gem home
+ * @param rubyVersion Ruby version
+ * @param bundleCommand Bundle command to use
+ * @param basePath working directory
+ *
+ * @returns {boolean} true if the install was successful. false otherwise.
+ */
+export declare function performBundleInstall(cdxgenGemHome: any, rubyVersion: any, bundleCommand: any, basePath: any): boolean;
+/**
+ * Retrieves the commit logs for a git repo with detailed author, committer, parents, signatures, and body.
+ *
+ * @param {string} dir Repo directory
+ * @param {number} maxCount Maximum number of commits to retrieve
+ * @returns {Array<Object>} Array of detailed commit objects
+ */
+export declare function gitLogCommitsDetailed(dir: string, maxCount?: number): Array<Object>;
+/**
+ * Runs a git show on a commit hash and analyzes the diff for test-file
+ * deletions and quality-gate-weakening changes (e.g. `|| true`,
+ * `continue-on-error: true`, `--no-verify`). Detection is intentionally
+ * conservative to avoid false positives from ordinary refactors.
+ *
+ * @param {string} dir Repo directory
+ * @param {string} commitHash Commit hash to analyze
+ * @returns {Object} Commit diff analysis results
+ */
+export declare function gitCommitDiffAnalysis(dir: string, commitHash: string): Object;
+/**
+ * Retrieves the git-ai notes metadata for recent commits.
+ *
+ * @param {string} dir Repo directory
+ * @param {Object} [options] Options for note retrieval
+ * @param {string} [options.ref] Notes reference path (defaults to refs/notes/ai)
+ * @param {number} [options.maxCount] Maximum commits to scan (defaults to 20)
+ * @returns {Array<Object>} Array of note objects { hash, note }
+ */
+export declare function gitAiNotes(dir: string, options?: {
+    ref?: string;
+    maxCount?: number;
+}): Array<Object>;
+/**
+ * Retrieves recent commits whose subject indicates a revert, hotfix, or
+ * rollback. Bounded to the same recency window as the other collectors — unlike
+ * `git log --grep`, which traverses the entire history looking for matches.
+ *
+ * @param {string} dir Repo directory
+ * @param {number} maxCount Maximum number of recent commits to scan
+ * @returns {Array<Object>} Array of { hash, message } revert/hotfix commits
+ */
+export declare function gitRevertsAndHotfixes(dir: string, maxCount?: number): Array<Object>;
+/**
+ * Get information about the runtime.
+ *
+ * @returns {Object} Object containing the name and version of the runtime
+ */
+export declare function getRuntimeInformation(): Object;
+/**
+ * Checks for dangerous Unicode characters that could enable homograph attacks
+  if (zeroWidthChars.test(str)) {
+    return true;
+  }
+
+  // Check for control characters (except common ones like \n, \r, \t)
+  const controlChars = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/;
+  return controlChars.test(str);
+}
+// biome-ignore-end lint/suspicious/noControlCharactersInRegex: validation
+
+/**
+ * Get version and runtime information
+ */
+export declare function retrieveCdxgenVersion(): string;
+/**
+ * Retrieve the version of the cdxgen plugins binary package from package.json.
+ *
+ * Reads the local package.json and searches the `optionalDependencies` for a package
+ * whose name starts with `@cdxgen/cdxgen-plugins-bin`, returning its declared version.
+ *
+ * @returns {string|undefined} Version string of the plugins binary package, or undefined if not found
+ */
+export declare function retrieveCdxgenPluginVersion(): string | undefined;
+//# sourceMappingURL=envcontext.d.ts.map

package/types/lib/inventory/envcontext.d.ts.map

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

package/types/lib/inventory/evidenceUtils.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Build a CycloneDX occurrence evidence object from a location string.
+ *
+ * @param {string} location Location string such as a file path or `file#line`
+ * @param {Object} [details] Extra fields (e.g. line, offset) merged into the occurrence; empty values are skipped
+ * @returns {Object|undefined} Occurrence evidence object with a location, or undefined when the location is empty
+ */
+export declare function createOccurrenceEvidence(location: string, details?: Object): Object | undefined;
+/**
+ * Parse a location string into a CycloneDX occurrence with file/line/offset fields.
+ *
+ * Recognizes `file#line`, `file:line:offset`, and `file:line` forms; other
+ * strings are kept as a plain location occurrence.
+ *
+ * @param {string} location Location string to parse
+ * @param {Object} [details] Extra fields merged into the occurrence
+ * @returns {Object|undefined} Occurrence evidence object, or undefined when the location is empty
+ */
+export declare function parseOccurrenceEvidenceLocation(location: string, details?: Object): Object | undefined;
+/**
+ * Format an occurrence evidence object back into a location string.
+ *
+ * @param {Object} occurrence Occurrence evidence object with location, and optional line/offset
+ * @returns {string} Location string in `file:line:offset`, `file#line`, or plain `file` form; empty when no location
+ */
+export declare function formatOccurrenceEvidence(occurrence: Object): string;
+/**
+ * Collect bom-refs from metadata.tools entries.
+ *
+ * @param {Object[]|Object} tools CycloneDX metadata.tools section
+ * @param {Function} predicate Optional filter function
+ * @returns {string[]} Unique tool bom-refs
+ */
+export declare function extractToolRefs(tools: Object[] | Object, predicate: Function): string[];
+/**
+ * Attach evidence.identity.tools references to the supplied subjects.
+ *
+ * @param {Object|Object[]} subjects Component or service objects
+ * @param {string[]} toolRefs Tool bom-refs
+ * @returns {Object|Object[]} The same mutated subject(s)
+ */
+export declare function attachIdentityTools(subjects: Object | Object[], toolRefs: string[]): Object | Object[];
+/**
+ * Enrich .NET package components with occurrence evidence and imported module/method
+ * information from a dosai dependency slices file.
+ *
+ * Builds a mapping of DLL filenames to purls using the `internal:PackageFiles` property of each
+ * package, then reads the slices file to add occurrence locations, imported modules,
+ * called methods, and assembly version information where available.
+ *
+ * @param {Object[]} pkgList Array of .NET package component objects to enrich
+ * @param {string} slicesFile Path to the dosai dependency slices JSON file
+ * @returns {Object[]} The enriched package list (same array, mutated in place)
+ */
+export declare function addEvidenceForDotnet(pkgList: Object[], slicesFile: string): Object[];
+/**
+ * Convert OS query results
+ *
+ * @param {string} queryCategory Query category
+ * @param {Object} queryObj Query Object from the queries.json configuration
+ * @param {Array} results Query Results
+ * @param {Boolean} enhance Optionally enhance results by invoking additional package manager commands
+ */
+export declare function convertOSQueryResults(queryCategory: string, queryObj: Object, results: any[], enhance?: boolean, osPackageListers?: undefined): {
+    name: string;
+    group: string;
+    version: string;
+    description: any;
+    publisher: string;
+    "bom-ref": string;
+    scope: any;
+    type: any;
+}[];
+//# sourceMappingURL=evidenceUtils.d.ts.map

package/types/lib/inventory/evidenceUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidenceUtils.d.ts","sourceRoot":"","sources":["../../../lib/inventory/evidenceUtils.js"],"names":[],"mappings":"AA4BA;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAJtC,MAIsC,EAAE,OAAO,AAHvD,CACA,EADQ,MAGoD,GAFlD,MAAM,GAAC,SAAS,CAgB5B;AAED;;;;;;;;;GASG;AACH,wBAAgB,+BAA+B,CAAC,QAAQ,EAJ7C,MAI6C,EAAE,OAAO,AAH9D,CACA,EADQ,MAG2D,GAFzD,MAAM,GAAC,SAAS,CA8B5B;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAHxC,MAGwC,GAFtC,MAAM,CAalB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAJ1B,MAAM,EAAE,GAAC,MAIiB,EAAE,SAAS,UAAA,GAFnC,MAAM,EAAE,CAmDpB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAJjC,MAAM,GAAC,MAAM,EAIoB,EAAE,QAAQ,EAH3C,MAAM,EAGqC,GAFzC,MAAM,GAAC,MAAM,EAAE,CAwB3B;AAsCD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAJjC,MAAM,EAI2B,EAAE,UAAU,EAH7C,MAG6C,GAF3C,MAAM,EAAE,CAsNpB;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,aAAa,EANJ,MAMI,EACb,QAAQ,EANC,MAMD,EACR,OAAO,OAAA,EACP,OAAO,UAAQ,EACf,gBAAgB,YAAY;;;;;;;;;IA6H7B"}

package/types/lib/inventory/fetchBatch.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Batched registry HTTP, via `cdxrs fetch` when it is available and a JS pool
+ * otherwise.
+ *
+ * The registry metadata functions in `lib/ecosystems/ecosystems.js` know every
+ * URL they are going to need before they need any of them, but fetch them one
+ * at a time with an `await` in a `for` body. That is the cost this module
+ * removes: the URLs are handed off in a single batch, fetched concurrently with
+ * a shared per-host rate policy, and returned as a map that the existing loops
+ * read instead of the network.
+ *
+ * There is one policy layer (`fetchRate.js`, mirrored by the Rust `rate.rs`)
+ * and two transports. When the `cdxrs` binary is available it is preferred,
+ * because it brings an on-disk conditional cache (D26) the JS pool does not
+ * have. When it is absent, disabled, or unusable, the JS pool runs every
+ * request through `cdxgenAgent` so the secure-mode host allowlist, the
+ * activity recorder and the test cassette interceptor all still apply.
+ *
+ * Two properties are deliberate and load-bearing:
+ *
+ * 1. **No field derivation happens here or in Rust.** Both transports return
+ *    registry documents verbatim; every `p.description`, `p.license`,
+ *    provenance property and SPDX lookup is still computed by the same
+ *    JavaScript that computes it on the serial path. Neither transport can
+ *    therefore produce a different SBOM — both can only produce the same one
+ *    sooner. An earlier design derived fields in Rust and diverged from the
+ *    JS on all three registries it covered.
+ *
+ * 2. **Fallback is per URL, not per run.** A URL that the batch could not
+ *    resolve for a transport reason is simply absent from the map, and the
+ *    caller's own `cdxgenAgent.get` runs for it exactly as before. A URL that
+ *    resolved to a definite HTTP error is recorded as such, so the caller does
+ *    not re-request it only to get the same 404.
+ */
+/**
+ * @returns {Object|null} Stats from the last batch (requests, unique, ok,
+ *   failures, cacheHits, elapsedMs, peakConcurrency), or null.
+ */
+export declare function lastBatchStats(): Object | null;
+/**
+ * Whether batched fetching through cdxrs is available.
+ *
+ * Memoized because the probe spawns the binary, and this is consulted once per
+ * metadata function rather than once per run.
+ *
+ * @returns {boolean} True when `cdxrs fetch` can be used.
+ */
+export declare function batchFetchAvailable(): boolean;
+/**
+ * Reset the memoized availability probe and the JS batcher's in-flight map.
+ * Tests only.
+ */
+export declare function resetBatchFetchAvailability(): void;
+export type BatchEntry = {
+    /**
+     * Whether a body was obtained.
+     */
+    ok: boolean;
+    /**
+     * Parsed response body when `ok`.
+     */
+    body?: any;
+    /**
+     * HTTP status, when the server produced one.
+     */
+    status?: number;
+    /**
+     * True when the status is a final answer (a 4xx
+     * other than 429) and re-requesting it in JS would be pointless.
+     */
+    definite?: boolean;
+};
+/**
+ * Fetch a batch of registry URLs concurrently.
+ *
+ * Dispatches to the Rust subprocess when it is available (it brings the D26
+ * on-disk cache), and to the JS pool otherwise. Both transports return a map
+ * keyed by URL with the same entry shape, so callers do not know — and do not
+ * need to know — which one ran.
+ *
+ * @param {Array<{url: string, accept?: string, authRealm?: string, responseType?: ("json"|"text"|"buffer"), headers?: Object}>} requests
+ *   URLs to fetch. Duplicates are fine; they are coalesced.
+ * @param {Object} [options]
+ * @param {number} [options.timeoutMs] Override the Rust batch timeout.
+ * @returns {Promise<Map<string, BatchEntry>>} Map keyed by URL. Empty when
+ *   prefetching is disabled (cassette replay) or the request list is empty;
+ *   never empty for "no binary", which is the whole point of the JS pool.
+ */
+export declare function prefetchJson(requests: Array<{
+    url: string;
+    accept?: string;
+    authRealm?: string;
+    responseType?: ("json" | "text" | "buffer");
+    headers?: Object;
+}>, options?: {
+    timeoutMs?: number;
+}): Promise<Map<string, BatchEntry>>;
+/**
+ * Read a prefetched response, or signal that the caller should fetch it itself.
+ *
+ * @param {Map<string, BatchEntry>} prefetched Result of {@link prefetchJson}.
+ * @param {string} url The URL the caller is about to request.
+ * @returns {{body: *}|undefined} A response-shaped object when the body is
+ *   available, or `undefined` when the caller should issue its own request.
+ * @throws {Error} When the batch established a definite HTTP error for this
+ *   URL, so that the caller's existing `catch` treats it exactly as it treats a
+ *   failed `cdxgenAgent.get`.
+ */
+export declare function prefetchedResponse(prefetched: Map<string, BatchEntry>, url: string): {
+    body: any;
+} | undefined;
+/**
+ * Whether batched prefetching should be attempted at all.
+ *
+ * The JS pool is always available (it is plain JavaScript through
+ * `cdxgenAgent`), so this is true for every real run. The single exception is
+ * cassette replay: the cassette interceptor lives inside undici inside this
+ * process, and the golden harness asserts exact request ordering and counts.
+ * The batch pool reorders requests by design, so it is disabled under replay
+ * to keep the golden cassettes stable. `CDXGEN_RS_DISABLE=fetch` and
+ * `--no-rust` disable only the Rust subprocess; the JS pool still runs, which
+ * is the point of this round.
+ *
+ * @returns {boolean} True when prefetching is allowed.
+ */
+export declare function prefetchEnabled(): boolean;
+//# sourceMappingURL=fetchBatch.d.ts.map

package/types/lib/inventory/fetchBatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetchBatch.d.ts","sourceRoot":"","sources":["../../../lib/inventory/fetchBatch.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AA2EH;;;GAGG;AACH,wBAAgB,cAAc,IAHjB,MAAM,GAAC,IAAI,CAKvB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,IAFtB,OAAO,CASnB;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,SAO1C;AAKE,YAAkB,UAAU,GAC5B;;;;IAAoB,EAAE,EAAX,OAAO,CAClB;;;;IAAe,IAAI,AAAnB,CACA,EADW,GAAC,CACZ;;;;IAAoB,MAAM,AAA1B,CACA,EADW,MAAM,CACjB;;;;;IAAqB,QAAQ,AAA7B,CAEF,EAFa,OAAO,CAEpB;CAAA,CAAA;AAoCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EARhC,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,CAAC,MAAM,GAAC,MAAM,GAAC,QAAQ,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAC,CAQnF,EAAE,OAAO,AANjD,CAEA,EADA;IAAyB,SAAS,AAAlC,CACA,EADQ,MAAM,CACd;CAIsD,GAJ5C,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAgC5C;AAifD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EARlC,GAAG,CAAC,MAAM,EAAE,UAAU,CAQY,EAAE,GAAG,EAPvC,MAOuC,GANrC;IAAC,IAAI,EAAE,GAAC,CAAA;CAAC,GAAC,SAAS,CAoB/B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,IAFlB,OAAO,CAOnB"}