@descryy/adapter-java 0.4.0 → 0.5.0

package/dist/dto.d.ts

@@ -0,0 +1,86 @@
+/**
+ * `DTO` for Java — the transport shapes a ROUTE declares, never a class that
+ * looks like one.
+ *
+ * ## The rule this keeps, and why the evidence is where it is
+ *
+ * DEC-043 refused `DTO` for the first real adapter because the corpus supplies
+ * three structurally identical classes separable only by name, and
+ * `*Request`/`*Response` -> `DTO` is a heuristic: a guessed node type is a
+ * false claim that caps nothing. That reasoning is intact and **nothing in
+ * this file reads the DTO class to decide whether it is one.**
+ *
+ * What was missing was a declaration somewhere else, and Spring has two, both
+ * written on the route:
+ *
+ *   - `@RestController` is `@Controller + @ResponseBody`, so a handler's
+ *     **return type is the response body** by the framework's own rule. A bare
+ *     `@Controller` returns view names and declares nothing unless
+ *     `@ResponseBody` opts in — the identical admission `spring.ts` already
+ *     applies to accept the route at all, shared here rather than re-derived.
+ *   - `@RequestBody` on a parameter states that the **parameter's type is the
+ *     request body**.
+ *
+ * Both markers sit on the handler, so the entity beside them is untouched:
+ * `Order` keeps the same fields and the same entity-shaped name as
+ * `CreateOrderRequest` and stays a `CLASS`. That is the discrimination golden
+ * pattern 07 exists to test, and reading the route rather than the class is
+ * what preserves it. `test/dto.test.ts` fails if any of it slips.
+ *
+ * ## Refusals, each of them load-bearing
+ *
+ * - **A parameter annotation is not a body.** `@PathVariable`/`@RequestParam`
+ *   sit in exactly the same position and declare a path segment or a query
+ *   value. A reader taking "annotated parameter" for "request shape" claims
+ *   `String`.
+ * - **A framework or built-in type names no shape here.** `ResponseEntity<T>`,
+ *   `String`, `void`, a collection, a primitive: `ResponseEntity`'s payload is
+ *   its type argument and resolving that is a generics read this file does not
+ *   do, so it refuses rather than minting the wrapper.
+ * - **A type that resolves to no class in this repository is refused**, never
+ *   minted as an empty node — a `DTO` with no shape joins nothing and
+ *   disguises a missing read as a present one.
+ * - **A mapped entity stays a `MODEL`.** A wrong `MODEL` is a claim about a
+ *   database and a wrong `DTO` a claim about a wire format; the mapping is the
+ *   stronger, narrower evidence and wins, exactly as it does in
+ *   `adapter-python`. Applied by the caller, which holds both maps.
+ *
+ * ## Field NAMES, and deliberately not field detail
+ *
+ * `attrs.fields` carries the names the class declares — a name-level fact,
+ * which rule 3 permits at R2. `attrs.fieldDetail` is **not** emitted and this
+ * file raises no node's resolution: whether a plain Java class body's field
+ * list is R3-grade evidence under DEC-202 is a separate question with
+ * fleet-wide blast radius (it would give `shape-reach.ts` its second fact kind
+ * and change what every Java finding may claim), it is filed, and it is not
+ * answered here. Golden 05's own note asks for exactly this shape — "an
+ * adapter stuck at R2 must emit the DTO nodes without field detail rather than
+ * guessing fields."
+ */
+import type { JavaUnit } from "./parse.ts";
+/** The declaration marker every `DTO` this file mints names in `attrs.schema`. */
+export declare const SCHEMA = "spring";
+/**
+ * A class this repository declares AND a route names as a transport shape.
+ * Keyed by `identityPackage::fqn`, the same key `readEntities` uses, so the
+ * caller can ask both maps with one lookup.
+ */
+export interface TransportShape {
+    /** Field names the class declares, sorted. Names only — see the header. */
+    readonly fields: readonly string[];
+    /** Which directions a route declared for it: `request`, `response`, or both. */
+    readonly roles: readonly ("request" | "response")[];
+}
+/**
+ * Every class a Spring route declares as a request or response body, across
+ * the whole batch — cross-unit, because a controller and the shape it names
+ * are routinely different files.
+ *
+ * Resolution is by SIMPLE name against the set of declared types, which is the
+ * same reach the rest of this adapter has (R1/R2 name resolution, no checker).
+ * An ambiguous simple name — two classes with the same name in one batch —
+ * is refused rather than resolved by ranking: the wrong one would carry the
+ * wrong shape into a comparison, and rule 2 prefers the disclosed gap.
+ */
+export declare function readTransportShapes(units: readonly JavaUnit[]): ReadonlyMap<string, TransportShape>;
+//# sourceMappingURL=dto.d.ts.map

package/dist/dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dto.d.ts","sourceRoot":"","sources":["../src/dto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAEH,OAAO,KAAK,EAAwB,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEjE,kFAAkF;AAClF,eAAO,MAAM,MAAM,WAAW,CAAC;AAmD/B;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,gFAAgF;IAChF,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,SAAS,GAAG,UAAU,CAAC,EAAE,CAAC;CACrD;AAsBD;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,SAAS,QAAQ,EAAE,GACzB,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,CA0DrC"}

package/dist/dto.js

@@ -0,0 +1,198 @@
+/**
+ * `DTO` for Java — the transport shapes a ROUTE declares, never a class that
+ * looks like one.
+ *
+ * ## The rule this keeps, and why the evidence is where it is
+ *
+ * DEC-043 refused `DTO` for the first real adapter because the corpus supplies
+ * three structurally identical classes separable only by name, and
+ * `*Request`/`*Response` -> `DTO` is a heuristic: a guessed node type is a
+ * false claim that caps nothing. That reasoning is intact and **nothing in
+ * this file reads the DTO class to decide whether it is one.**
+ *
+ * What was missing was a declaration somewhere else, and Spring has two, both
+ * written on the route:
+ *
+ *   - `@RestController` is `@Controller + @ResponseBody`, so a handler's
+ *     **return type is the response body** by the framework's own rule. A bare
+ *     `@Controller` returns view names and declares nothing unless
+ *     `@ResponseBody` opts in — the identical admission `spring.ts` already
+ *     applies to accept the route at all, shared here rather than re-derived.
+ *   - `@RequestBody` on a parameter states that the **parameter's type is the
+ *     request body**.
+ *
+ * Both markers sit on the handler, so the entity beside them is untouched:
+ * `Order` keeps the same fields and the same entity-shaped name as
+ * `CreateOrderRequest` and stays a `CLASS`. That is the discrimination golden
+ * pattern 07 exists to test, and reading the route rather than the class is
+ * what preserves it. `test/dto.test.ts` fails if any of it slips.
+ *
+ * ## Refusals, each of them load-bearing
+ *
+ * - **A parameter annotation is not a body.** `@PathVariable`/`@RequestParam`
+ *   sit in exactly the same position and declare a path segment or a query
+ *   value. A reader taking "annotated parameter" for "request shape" claims
+ *   `String`.
+ * - **A framework or built-in type names no shape here.** `ResponseEntity<T>`,
+ *   `String`, `void`, a collection, a primitive: `ResponseEntity`'s payload is
+ *   its type argument and resolving that is a generics read this file does not
+ *   do, so it refuses rather than minting the wrapper.
+ * - **A type that resolves to no class in this repository is refused**, never
+ *   minted as an empty node — a `DTO` with no shape joins nothing and
+ *   disguises a missing read as a present one.
+ * - **A mapped entity stays a `MODEL`.** A wrong `MODEL` is a claim about a
+ *   database and a wrong `DTO` a claim about a wire format; the mapping is the
+ *   stronger, narrower evidence and wins, exactly as it does in
+ *   `adapter-python`. Applied by the caller, which holds both maps.
+ *
+ * ## Field NAMES, and deliberately not field detail
+ *
+ * `attrs.fields` carries the names the class declares — a name-level fact,
+ * which rule 3 permits at R2. `attrs.fieldDetail` is **not** emitted and this
+ * file raises no node's resolution: whether a plain Java class body's field
+ * list is R3-grade evidence under DEC-202 is a separate question with
+ * fleet-wide blast radius (it would give `shape-reach.ts` its second fact kind
+ * and change what every Java finding may claim), it is filed, and it is not
+ * answered here. Golden 05's own note asks for exactly this shape — "an
+ * adapter stuck at R2 must emit the DTO nodes without field detail rather than
+ * guessing fields."
+ */
+/** The declaration marker every `DTO` this file mints names in `attrs.schema`. */
+export const SCHEMA = "spring";
+/** Spring's own statement that a parameter carries the request body. */
+const BODY_PARAMETER = "RequestBody";
+/**
+ * Types that are framework plumbing or language built-ins rather than a
+ * transport shape. A return type here is refused outright: `ResponseEntity`'s
+ * real payload is its type argument, and this reader does not resolve generics
+ * — so it declines rather than minting the wrapper as the shape.
+ */
+const NOT_A_SHAPE = new Set([
+    "ResponseEntity",
+    "HttpEntity",
+    "Mono",
+    "Flux",
+    "CompletableFuture",
+    "Optional",
+    "List",
+    "Set",
+    "Map",
+    "Collection",
+    "Iterable",
+    "String",
+    "Object",
+    "Void",
+    "byte",
+    "short",
+    "int",
+    "long",
+    "float",
+    "double",
+    "boolean",
+    "char",
+    "Byte",
+    "Short",
+    "Integer",
+    "Long",
+    "Float",
+    "Double",
+    "Boolean",
+    "Character",
+    "Number",
+    "BigDecimal",
+    "BigInteger",
+    "UUID",
+    "Instant",
+    "LocalDate",
+    "LocalDateTime",
+]);
+/** `@RestController`, or `@Controller` that opted into a body. Mirrors `spring.ts`. */
+function declaresBodies(type) {
+    const names = new Set(type.annotations.map((each) => each.name));
+    if (names.has("RestController"))
+        return true;
+    return names.has("Controller") && names.has("ResponseBody");
+}
+/** Is this method a Spring route handler at all? Any mapping annotation says so. */
+function isHandler(method) {
+    return method.annotations.some((each) => each.name === "RequestMapping" || /^(Get|Post|Put|Patch|Delete)Mapping$/.test(each.name));
+}
+/** A simple type name this reader is willing to carry, or `undefined`. */
+function shapeName(name) {
+    if (name === undefined || name === null || name === "")
+        return undefined;
+    return NOT_A_SHAPE.has(name) ? undefined : name;
+}
+/**
+ * Every class a Spring route declares as a request or response body, across
+ * the whole batch — cross-unit, because a controller and the shape it names
+ * are routinely different files.
+ *
+ * Resolution is by SIMPLE name against the set of declared types, which is the
+ * same reach the rest of this adapter has (R1/R2 name resolution, no checker).
+ * An ambiguous simple name — two classes with the same name in one batch —
+ * is refused rather than resolved by ranking: the wrong one would carry the
+ * wrong shape into a comparison, and rule 2 prefers the disclosed gap.
+ */
+export function readTransportShapes(units) {
+    /** Simple name -> `identityPackage::fqn`, or `null` once ambiguous. */
+    const declared = new Map();
+    /** `identityPackage::fqn` -> the class's own declared field names. */
+    const fieldsOf = new Map();
+    for (const unit of units) {
+        for (const type of unit.types) {
+            const key = `${unit.identityPackage}::${type.fqn}`;
+            fieldsOf.set(key, [...type.fields.keys()].sort());
+            declared.set(type.simpleName, declared.has(type.simpleName) ? null : key);
+        }
+    }
+    const roles = new Map();
+    const record = (simple, role) => {
+        if (simple === undefined)
+            return;
+        const key = declared.get(simple);
+        // `undefined` — declared nowhere here; `null` — declared twice. Both are
+        // refusals: a DTO with no shape, or the wrong class's shape.
+        if (key === undefined || key === null)
+            return;
+        const existing = roles.get(key);
+        if (existing === undefined)
+            roles.set(key, new Set([role]));
+        else
+            existing.add(role);
+    };
+    for (const unit of units) {
+        for (const type of unit.types) {
+            if (!declaresBodies(type))
+                continue;
+            for (const method of type.methods) {
+                if (!isHandler(method))
+                    continue;
+                // The return type IS the response body — that is what @RestController
+                // means. `TypeRead` keeps absent / void / unreadable apart, and only a
+                // written, named type is evidence.
+                const returned = method.returnType;
+                if (returned.kind === "named")
+                    record(shapeName(returned.name), "response");
+                // ...and a @RequestBody parameter's type IS the request body. The type
+                // comes from `locals`, which the parse fills for every parameter;
+                // `null` there means the name was declared twice or with `var` and
+                // poisons itself, which `shapeName` passes straight through.
+                for (const [name, annotations] of method.parameterAnnotations) {
+                    if (!annotations.some((each) => each.name === BODY_PARAMETER))
+                        continue;
+                    record(shapeName(method.locals.get(name)), "request");
+                }
+            }
+        }
+    }
+    const shapes = new Map();
+    for (const [key, directions] of roles) {
+        shapes.set(key, {
+            fields: fieldsOf.get(key) ?? [],
+            roles: [...directions].sort(),
+        });
+    }
+    return shapes;
+}
+//# sourceMappingURL=dto.js.map

package/dist/dto.js.map

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

package/dist/external.d.ts

@@ -0,0 +1,169 @@
+/**
+ * The dependency boundary, Java side.
+ *
+ * `LoggerFactory.getLogger(Foo.class)` leaves the repository. Today that becomes
+ * a ledger row saying "names a type this run did not analyse" and the call graph
+ * stops. This module answers the one question that turns the boundary into a
+ * fact the graph can hold: **which package, and which symbol in it.**
+ *
+ * ## The rule everything here rests on: attribute only from a binding the
+ * developer wrote
+ *
+ * In Go (`adapter-go/src/external.ts`, the model for this file) that binding is
+ * the file's own `import` block. Java's is the same statement, and it is the
+ * cleanest of the ten: `import org.slf4j.Logger;` binds the simple name `Logger`
+ * to a fully-qualified name **written in the file**, and `import static
+ * org.junit.jupiter.api.Assertions.assertEquals;` binds a bare member name to
+ * the type that declares it. Nothing here reads `pom.xml`'s dependency list, a
+ * Gradle configuration, `~/.m2`, or a jar. Two reasons, the same two Go gives:
+ *
+ * 1. Most checkouts have no dependencies fetched, so an identity taken from a
+ *    resolved classpath would exist for some runs and not others.
+ * 2. It would *move* the first time somebody ran `mvn dependency:resolve`.
+ *
+ * ## Why the Maven coordinate is not the identity
+ *
+ * `org.slf4j:slf4j-api` is the obvious answer and it is the one this module
+ * refuses. A jar's package-to-coordinate mapping lives in the jar, and the root
+ * `pom.xml`'s `<dependencies>` block binds a coordinate to no package at all —
+ * so there is no declared mapping to read without the resolved classpath. The
+ * **package** is written, in the import statement, by the developer, in the
+ * file. So the package is the identity, exactly as Go's import path is Go's and
+ * PHP's namespace is PHP's.
+ *
+ * ## The three shapes Java attributes, and what each costs
+ *
+ *   - `import a.b.C;` … `C x` or `C.m()` — a single-type import. The direct
+ *     analogue of Go's package-qualified call.
+ *   - `import a.b.C;` … `C x; x.m()` — a call through a local or field whose
+ *     **written type** is an imported name. Java writes its types down where Go
+ *     and PHP do not, and this is the half that makes Java worth doing.
+ *   - `import static a.b.C.m;` … `m()` — a bare name bound by a static import.
+ *     This is how every JUnit assertion is written, so without it a test file's
+ *     calls are almost entirely unattributable. Python's `from x import y` is
+ *     the same shape and was the larger half there too.
+ *
+ * ## What Java makes harder than Go, and the refusals it earns
+ *
+ * Go has no fallback: an unqualified name is package-local, full stop. Java has
+ * three, and none of them is a binding a developer wrote:
+ *
+ *   - **`java.lang` is imported implicitly.** `String`, `Integer`, `Exception`
+ *     appear with no import statement anywhere. A language rule filling a
+ *     silence is not a written binding, so they are declined — the same call
+ *     PHP's `external.ts` makes about its global-namespace fallback.
+ *   - **A wildcard import binds no name.** `import java.util.*;` then `List`
+ *     could be `java.util.List` or a type from any other wildcard in the file,
+ *     and telling them apart needs the classpath this module refuses to read.
+ *     Python's `from x import *` refusal, for the same reason.
+ *   - **Same-package types resolve without an import.** A name settled that way
+ *     is ours by construction, and `resolveType` has already claimed it.
+ *
+ * One more refusal is Java-specific and is a **precision** refusal rather than a
+ * recall one: `extract.ts`'s `REASONS.outside` discloses that some `outside`
+ * rows are declarations in *another language in this same repository* — 238 of
+ * `okhttp`'s 458 are in `.kt` files. The own-package check below is what keeps
+ * those from being called dependencies, and it is whole-segment, so a Kotlin
+ * class in a package this repository's Java sources also declare is ours.
+ *
+ * **Everything this module does not attribute is a deliberate refusal.** Rule 2
+ * prices a wrong edge far above a missing one.
+ */
+/** What one written name was bound by. Only a binding the developer wrote is
+ *  attributed; `implicit` covers `java.lang`, a wildcard and the same package,
+ *  which are language rules filling a silence. */
+export type Binding = "single-type-import" | "written-fully-qualified" | "static-import";
+export interface ExternalImports {
+    /** Simple name -> fully-qualified name, from `import a.b.C;`. */
+    readonly singleTypeImports: ReadonlyMap<string, string>;
+    /** Member name -> declaring type, from `import static a.b.C.m;`. */
+    readonly staticMemberImports: ReadonlyMap<string, string>;
+}
+export interface ExternalContext {
+    readonly imports: ExternalImports;
+    /**
+     * Packages declared by the repository's own compilation units. A type under
+     * one of them is OURS whether or not this run read it — calling unanalysed
+     * code of ours a dependency is the error that never surfaces.
+     */
+    readonly ownPackages: ReadonlySet<string>;
+    /** Fully-qualified names this run actually read. One of ours is not a boundary. */
+    readonly analysed: ReadonlySet<string>;
+}
+export interface ExternalAttribution {
+    /** The package **as written in the import statement** — this is the identity. */
+    readonly moduleOrNamespace: string;
+    /** The type chain, then any member named on it. Never a local alias; Java has none. */
+    readonly symbolPath: readonly string[];
+    /** Which written binding settled the name. Disclosure, never identity. */
+    readonly binding: Binding;
+    /**
+     * From a jar rather than the JDK, decided from the package name alone against
+     * `PLATFORM_BASIS`. Disclosure only — it never enters the node id, because a
+     * package that moved between the two (every `javax.*` that became `jakarta.*`
+     * did exactly this) would otherwise change identity with no line of source
+     * changing.
+     */
+    readonly thirdParty: boolean;
+}
+/**
+ * Provenance of the platform-package list, carried on every attributed node.
+ * A property of the language and its JDK, frozen into this source — never read
+ * from whatever JDK a developer happens to have installed, which would make the
+ * answer depend on the machine.
+ *
+ * `javax` is split rather than taken whole: `javax.swing` ships with the JDK and
+ * `javax.persistence` never did. Taking the whole prefix either way is a wrong
+ * disclosure on thousands of nodes, and the list is short enough to write down.
+ */
+export declare const PLATFORM_BASIS = "jdk-21 java./jdk./sun./com.sun. roots, plus the JDK's own javax subpackages";
+/**
+ * A fully-qualified name split into the package that names it and the symbol
+ * chain inside it: `java.util.Map.Entry` -> `java.util` + `Map.Entry`.
+ *
+ * `null` when the convention does not settle it — no lowercase prefix (a
+ * default-package name, or a name already inside a type) or no capitalised
+ * segment at all (`foo.bar.baz`, which is a value traversal and not a type).
+ */
+export declare function splitQualifiedName(fqn: string): {
+    pkg: string;
+    symbols: string[];
+} | null;
+/** Generic arguments and array brackets are not part of a name's identity, and
+ *  the type arguments inside them are separate references the extractor already
+ *  files on their own. */
+export declare function bareTypeName(written: string): string;
+/**
+ * The package and type behind a **type reference** that left the repository, or
+ * `null` when no binding the developer wrote settles it.
+ *
+ * `written` is the name exactly as the source wrote it — `Logger`,
+ * `java.util.List`, `Map.Entry`.
+ */
+export declare function attributeExternalType(written: string, context: ExternalContext): ExternalAttribution | null;
+/**
+ * The package, type and member behind a **call** that left the repository, or
+ * `null` when no binding the developer wrote settles it.
+ *
+ * `receiverType` is the receiver's type **as the source wrote it**: the declared
+ * type of a local or field, or the type name itself for a static call. It is
+ * never inferred — a `var`, a chained call or a generic type variable writes no
+ * type at the reference and `extract.ts` hands `undefined` here for all three.
+ */
+export declare function attributeExternalCall(receiverType: string | undefined, method: string, context: ExternalContext): ExternalAttribution | null;
+/**
+ * The package, type and member behind an **unqualified call bound by a static
+ * import**, or `null` when no such binding exists.
+ *
+ * `assertEquals(a, b)` under `import static org.junit.jupiter.api.Assertions.assertEquals;`
+ * is a binding the developer wrote and the language guarantees it — following it
+ * is resolution, not inference. A bare name with no static import is declined:
+ * it is the enclosing type's own member, or an inherited one from a supertype
+ * this run did not read, and neither is a dependency.
+ *
+ * `import static a.b.C.*;` binds no name and is never recorded in
+ * `staticMemberImports`, so it cannot arrive here — Python's `import *` refusal
+ * in the form Java's parse already applies.
+ */
+export declare function attributeExternalStaticCall(method: string, context: ExternalContext): ExternalAttribution | null;
+//# sourceMappingURL=external.d.ts.map

package/dist/external.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external.d.ts","sourceRoot":"","sources":["../src/external.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AAEH;;kDAEkD;AAClD,MAAM,MAAM,OAAO,GAAG,oBAAoB,GAAG,yBAAyB,GAAG,eAAe,CAAC;AAEzF,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,QAAQ,CAAC,iBAAiB,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxD,oEAAoE;IACpE,QAAQ,CAAC,mBAAmB,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3D;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1C,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,mBAAmB;IAClC,iFAAiF;IACjF,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,uFAAuF;IACvF,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,gFAAgF,CAAC;AAsD5G;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CAOzF;AAED;;0BAE0B;AAC1B,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAIpD;AA8DD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,eAAe,GACvB,mBAAmB,GAAG,IAAI,CAI5B;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,eAAe,GACvB,mBAAmB,GAAG,IAAI,CAK5B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,eAAe,GACvB,mBAAmB,GAAG,IAAI,CAK5B"}