@intentius/chant 0.124.45 → 0.124.48

package/dist/capabilities/base-mappings.json

@@ -0,0 +1,122 @@
+{
+  "$comment": "The kinds core's effective-topology folds read (#1139, #4362), as data. These were constants in graph-effective.ts; they stay in core so the folds work on a graph read without its lexicon's plugin. Each lexicon's own mapping (src/capabilities/mapping.json) extends its entry here.",
+  "mappings": [
+    {
+      "lexicon": "aws",
+      "types": "kind",
+      "refs": "cloudformation",
+      "labels": {
+        "AWS::EC2::Instance": "Instance",
+        "AWS::EC2::LaunchTemplate": "LaunchTemplate",
+        "AWS::EC2::SecurityGroup": "SecurityGroup",
+        "AWS::EC2::SecurityGroupIngress": { "label": "IngressRule", "style": "cfn" },
+        "AWS::EC2::Subnet": "Subnet",
+        "AWS::EC2::SubnetRouteTableAssociation": "RouteTableAssociation",
+        "AWS::EC2::RouteTable": "RouteTable",
+        "AWS::EC2::Route": "Route",
+        "AWS::EC2::InternetGateway": "InternetGateway"
+      },
+      "edges": {
+        "Instance": {
+          "SecurityGroupIds": "sg",
+          "SecurityGroupId": "sg",
+          "LaunchTemplate": "template",
+          "LaunchTemplateId": "template",
+          "SubnetId": "subnet"
+        },
+        "LaunchTemplate": {
+          "LaunchTemplateData": { "SecurityGroup": "sg" },
+          "SecurityGroupIds": "sg",
+          "SecurityGroupId": "sg"
+        },
+        "IngressRule": { "GroupId": "-ingress", "SourceSecurityGroupId": "source" },
+        "RouteTableAssociation": { "SubnetId": "subnet", "RouteTableId": "table" },
+        "Route": { "RouteTableId": "table", "GatewayId": "gateway" }
+      },
+      "attrs": {
+        "Route": { "dest": "DestinationCidrBlock" },
+        "IngressRule": { "proto": "IpProtocol", "from": "FromPort", "to": "ToPort", "cidrs": { "all": ["CidrIp", "CidrIpv6"] } }
+      },
+      "blocks": {
+        "SecurityGroup": [
+          {
+            "attr": "SecurityGroupIngress",
+            "label": "IngressRule",
+            "edge": "ingress",
+            "style": "cfn",
+            "attrs": { "proto": "IpProtocol", "from": "FromPort", "to": "ToPort", "cidrs": { "all": ["CidrIp", "CidrIpv6"] } },
+            "refs": { "SourceSecurityGroupId": "source" }
+          }
+        ]
+      }
+    },
+    {
+      "lexicon": "terraform",
+      "types": "terraform",
+      "body": "body",
+      "refs": "terraform",
+      "labels": {
+        "aws_instance": "Instance",
+        "aws_launch_template": "LaunchTemplate",
+        "aws_security_group": "SecurityGroup",
+        "aws_security_group_rule": { "label": "IngressRule", "when": { "type": "ingress" }, "style": "tf-sg-rule" },
+        "aws_vpc_security_group_ingress_rule": { "label": "IngressRule", "style": "tf-vpc-rule" },
+        "aws_subnet": "Subnet",
+        "aws_route_table_association": "RouteTableAssociation",
+        "aws_route_table": "RouteTable",
+        "aws_route": "Route",
+        "aws_internet_gateway": "InternetGateway"
+      },
+      "edges": {
+        "Instance": {
+          "vpc_security_group_ids": "sg",
+          "security_groups": "sg",
+          "launch_template": "template",
+          "subnet_id": "subnet"
+        },
+        "LaunchTemplate": {
+          "vpc_security_group_ids": "sg",
+          "security_group_names": "sg",
+          "network_interfaces": { "SecurityGroup": "sg" }
+        },
+        "IngressRule": {
+          "security_group_id": "-ingress",
+          "source_security_group_id": "source",
+          "referenced_security_group_id": "source"
+        },
+        "RouteTableAssociation": { "subnet_id": "subnet", "route_table_id": "table" },
+        "Route": { "route_table_id": "table", "gateway_id": "gateway" }
+      },
+      "attrs": {
+        "Route": { "dest": ["destination_cidr_block", "destination_ipv6_cidr_block"] },
+        "IngressRule": {
+          "proto": ["ip_protocol", "protocol"],
+          "from": "from_port",
+          "to": "to_port",
+          "cidrs": { "all": ["cidr_blocks", "ipv6_cidr_blocks", "cidr_ipv4", "cidr_ipv6"] }
+        }
+      },
+      "blocks": {
+        "SecurityGroup": [
+          {
+            "attr": "ingress",
+            "label": "IngressRule",
+            "edge": "ingress",
+            "style": "tf-inline",
+            "attrs": { "proto": "protocol", "from": "from_port", "to": "to_port", "cidrs": { "all": ["cidr_blocks", "ipv6_cidr_blocks"] } },
+            "refs": { "security_groups": "source" }
+          }
+        ],
+        "RouteTable": [
+          {
+            "attr": "route",
+            "label": "Route",
+            "edge": "-table",
+            "attrs": { "dest": ["cidr_block", "ipv6_cidr_block"] },
+            "refs": { "gateway_id": "gateway" }
+          }
+        ]
+      }
+    }
+  ]
+}

package/dist/capabilities/catalog.d.ts

@@ -0,0 +1,89 @@
+import type { GraphIR } from "../graph-ir.js";
+import { type Literal, type Rule } from "./language.js";
+import { CapabilityEngine } from "./matcher.js";
+import { type CapabilityMapping, type CapabilityPack, type View } from "./view.js";
+/** Every rule core ships, parsed, with the file each came from. */
+export declare function shippedRules(): {
+    rules: Rule[];
+    sources: Map<string, string>;
+};
+/** The mappings core's folds need, for a graph read without its lexicon's plugin. */
+export declare function basePacks(): CapabilityPack[];
+/**
+ * Register a lexicon's pack for callers that hold no plugin list (the folds,
+ * a test). A plugin's `capabilityPack` reaches search without this.
+ */
+export declare function registerCapabilityPack(pack: CapabilityPack): void;
+/** Base packs, registered packs, then the packs given: later ones extend earlier ones. */
+export declare function resolvePacks(packs?: CapabilityPack[]): CapabilityPack[];
+/**
+ * The capability engine for a graph, built once per graph object. Packs
+ * passed on the first call for a graph are the ones it uses.
+ */
+export declare function capabilityEngine(ir: GraphIR, packs?: CapabilityPack[]): CapabilityEngine;
+/** Bind a graph to the packs its search was given, before anything asks for a capability. */
+export declare function attachCapabilities(ir: GraphIR, packs: CapabilityPack[]): CapabilityEngine;
+/**
+ * Bind a graph to a view built elsewhere (#4378): a workspace's composed
+ * view, which each member's own chant mapped. The rules are this chant's.
+ */
+export declare function attachView(ir: GraphIR, view: View): CapabilityEngine;
+/**
+ * Read `name` or `name(arg, ...)`, as a search term or an edge qualifier
+ * spells a capability. An argument is a number, `true`/`false`, or text,
+ * quoted or not.
+ */
+export declare function parseCapabilityCall(text: string): {
+    name: string;
+    args: (Literal | undefined)[];
+} | undefined;
+/** Public capabilities: those whose rule carries a `## meaning`. Helpers carry none. */
+export declare function isPublic(rule: Rule): boolean;
+/**
+ * Whether a lexicon can supply a capability: its own statement when its
+ * mapping makes one, otherwise whether every label one alternative needs
+ * is one the mapping labels.
+ */
+export declare function lexiconSupport(rule: Rule, mapping: CapabilityMapping | undefined, lexicon: string): "supported" | {
+    code: string;
+    message: string;
+};
+/** The capabilities a rule uses, directly. */
+export declare function usesOf(rule: Rule): string[];
+/** One capability as the `capabilities` document lists it (#4375). */
+export interface CapabilityEntry {
+    name: string;
+    meaning: string;
+    shape: "set" | "edge";
+    params: {
+        name: string;
+        optional: boolean;
+        meaning: string;
+    }[];
+    /** The search term that asks for it: `cap:<name>` for a set, `->[cap=<name>]` for an edge. */
+    search: string;
+    answers: string[];
+    depth: "declared" | "live" | "either";
+    lexicons: Record<string, "supported" | {
+        code: string;
+        message: string;
+    }>;
+    notEvaluated: string[];
+    /** The capabilities and helpers its rule uses. */
+    uses: string[];
+    rule: string;
+}
+/**
+ * The catalog as the `capabilities` document carries it: every public
+ * capability, with whether each lexicon given can supply it, and the helper
+ * rules they use. `lexicons` maps each lexicon to its mapping, or to
+ * undefined when it ships none.
+ */
+export declare function capabilityCatalog(lexicons: Record<string, CapabilityMapping | undefined>): {
+    capabilities: CapabilityEntry[];
+    helpers: {
+        name: string;
+        rule: string;
+    }[];
+};
+//# sourceMappingURL=catalog.d.ts.map

package/dist/capabilities/catalog.d.ts.map

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

package/dist/capabilities/catalog.js

@@ -0,0 +1,204 @@
+/**
+ * The capability catalog (#4375): the rule files core ships, the packs
+ * lexicons contribute, and the engine that evaluates one over a graph.
+ *
+ * Rules are data: `aws.paths` beside this module, read at run time. It serves
+ * every lexicon that maps AWS resources onto the view (the aws lexicon's
+ * CloudFormation kinds and the terraform lexicon's AWS provider types), so it
+ * lives here rather than in either lexicon. Each lexicon ships its mapping
+ * (data) and, where it needs one, an adapter (code), as a `CapabilityPack` on
+ * its plugin.
+ */
+import { readFileSync } from "node:fs";
+import { parseRules, ruleDependencies } from "./language.js";
+import { CapabilityEngine } from "./matcher.js";
+import { buildView, mergeMappings } from "./view.js";
+import base from "./base-mappings.json" with { type: "json" };
+/** The rule files core ships, by name. */
+const RULE_FILES = ["aws.paths"];
+let rulesCache;
+/** Every rule core ships, parsed, with the file each came from. */
+export function shippedRules() {
+    if (rulesCache)
+        return rulesCache;
+    const rules = [];
+    const sources = new Map();
+    for (const file of RULE_FILES) {
+        const text = readFileSync(new URL(`./${file}`, import.meta.url), "utf-8");
+        for (const r of parseRules(text)) {
+            rules.push(r);
+            sources.set(r.name, file);
+        }
+    }
+    rulesCache = { rules, sources };
+    return rulesCache;
+}
+/** The mappings core's folds need, for a graph read without its lexicon's plugin. */
+export function basePacks() {
+    return base.mappings.map((mapping) => ({ mapping }));
+}
+const registered = [];
+/**
+ * Register a lexicon's pack for callers that hold no plugin list (the folds,
+ * a test). A plugin's `capabilityPack` reaches search without this.
+ */
+export function registerCapabilityPack(pack) {
+    if (!registered.includes(pack))
+        registered.push(pack);
+}
+/** Base packs, registered packs, then the packs given: later ones extend earlier ones. */
+export function resolvePacks(packs = []) {
+    return [...basePacks(), ...registered, ...packs.filter((p) => !registered.includes(p))];
+}
+const engines = new WeakMap();
+/**
+ * The capability engine for a graph, built once per graph object. Packs
+ * passed on the first call for a graph are the ones it uses.
+ */
+export function capabilityEngine(ir, packs = []) {
+    let e = engines.get(ir);
+    if (!e) {
+        e = new CapabilityEngine(buildView(ir, resolvePacks(packs)), shippedRules().rules);
+        engines.set(ir, e);
+    }
+    return e;
+}
+/** Bind a graph to the packs its search was given, before anything asks for a capability. */
+export function attachCapabilities(ir, packs) {
+    engines.delete(ir);
+    return capabilityEngine(ir, packs);
+}
+/**
+ * Bind a graph to a view built elsewhere (#4378): a workspace's composed
+ * view, which each member's own chant mapped. The rules are this chant's.
+ */
+export function attachView(ir, view) {
+    const e = new CapabilityEngine(view, shippedRules().rules);
+    engines.set(ir, e);
+    return e;
+}
+/**
+ * Read `name` or `name(arg, ...)`, as a search term or an edge qualifier
+ * spells a capability. An argument is a number, `true`/`false`, or text,
+ * quoted or not.
+ */
+export function parseCapabilityCall(text) {
+    const m = /^([A-Za-z_][\w-]*)(?:\((.*)\))?$/.exec(text.trim());
+    if (!m)
+        return undefined;
+    const args = m[2] === undefined || m[2].trim() === ""
+        ? []
+        : m[2].split(",").map((a) => {
+            const s = a.trim();
+            if (s === "" || s === "_")
+                return undefined;
+            if (/^-?\d+(\.\d+)?$/.test(s))
+                return Number(s);
+            if (s === "true" || s === "false")
+                return s === "true";
+            return s.replace(/^"(.*)"$/, "$1");
+        });
+    return { name: m[1], args };
+}
+/** Public capabilities: those whose rule carries a `## meaning`. Helpers carry none. */
+export function isPublic(rule) {
+    return rule.meta.meaning !== undefined;
+}
+/** Every label a rule needs, through the capabilities it uses, per alternative: any one alternative suffices. */
+function labelsNeeded(rule, byName, seen = new Set()) {
+    if (seen.has(rule.name))
+        return [[]];
+    seen.add(rule.name);
+    const out = [];
+    for (const alt of rule.alts) {
+        // A node of any one of its labels will do, so each label is an option.
+        let options = alt.head.labels ? alt.head.labels.map((l) => [l]) : [[]];
+        const add = (more) => {
+            options = options.flatMap((o) => more.map((m) => [...o, ...m]));
+        };
+        for (const t of alt.head.tests)
+            if (t.kind === "cap" && !t.negated)
+                add(labelsNeeded(byName.get(t.cap), byName, new Set(seen)));
+        for (const s of alt.steps) {
+            if (s.negated)
+                continue;
+            if (s.node.labels && s.min > 0)
+                add(s.node.labels.map((l) => [l]));
+            for (const t of s.node.tests)
+                if (t.kind === "cap" && !t.negated)
+                    add(labelsNeeded(byName.get(t.cap), byName, new Set(seen)));
+            if (s.min > 0) {
+                const edgeRules = s.names.map((n) => byName.get(n.name)).filter((r) => !!r);
+                if (edgeRules.length === s.names.length)
+                    add(edgeRules.flatMap((r) => labelsNeeded(r, byName, new Set(seen))));
+            }
+        }
+        out.push(...options);
+    }
+    return out;
+}
+/**
+ * Whether a lexicon can supply a capability: its own statement when its
+ * mapping makes one, otherwise whether every label one alternative needs
+ * is one the mapping labels.
+ */
+export function lexiconSupport(rule, mapping, lexicon) {
+    if (!mapping) {
+        return { code: "lexicon-has-no-mapping", message: `the ${lexicon} lexicon ships no capability mapping` };
+    }
+    const stated = mapping.unsupported?.[rule.name];
+    if (stated)
+        return stated;
+    // A lexicon's mapping extends core's base mapping for it (the folds' kinds).
+    const own = mapping;
+    const baseFor = basePacks().find((p) => p.mapping.lexicon === own.lexicon)?.mapping;
+    if (baseFor)
+        mapping = mergeMappings(baseFor, own);
+    const { rules } = shippedRules();
+    const byName = new Map(rules.map((r) => [r.name, r]));
+    const labels = new Set(Object.values(mapping.labels ?? {}).map((s) => (typeof s === "string" ? s : s.label)));
+    // Statements and inline blocks are the adapter's own nodes.
+    labels.add("Statement");
+    for (const specs of Object.values(mapping.blocks ?? {}))
+        for (const b of specs)
+            labels.add(b.label);
+    const options = labelsNeeded(rule, byName);
+    if (options.some((o) => o.every((l) => labels.has(l))))
+        return "supported";
+    const missing = [...new Set(options.flatMap((o) => o.filter((l) => !labels.has(l))))];
+    return {
+        code: "capability-not-derivable",
+        message: `the ${lexicon} mapping labels no ${missing.join(" or ")}`,
+    };
+}
+/** The capabilities a rule uses, directly. */
+export function usesOf(rule) {
+    const { rules } = shippedRules();
+    const names = new Set(rules.map((r) => r.name));
+    return [...ruleDependencies(rule)].filter((n) => names.has(n));
+}
+/**
+ * The catalog as the `capabilities` document carries it: every public
+ * capability, with whether each lexicon given can supply it, and the helper
+ * rules they use. `lexicons` maps each lexicon to its mapping, or to
+ * undefined when it ships none.
+ */
+export function capabilityCatalog(lexicons) {
+    const { rules } = shippedRules();
+    const list = (s) => (s ?? "").split(/\n|;/).map((x) => x.trim()).filter(Boolean);
+    const capabilities = rules.filter(isPublic).map((r) => ({
+        name: r.name,
+        meaning: r.meta.meaning,
+        shape: r.vars.length === 1 ? "set" : "edge",
+        params: r.params.map((p) => ({ name: p.name, optional: p.optional, meaning: r.meta[`param-${p.name}`] ?? "" })),
+        search: r.vars.length === 1 ? `cap:${r.name}` : `->[cap=${r.name}]`,
+        answers: (r.meta.answers ?? "").split("\n").map((x) => x.trim()).filter(Boolean),
+        depth: (r.meta.depth ?? "declared"),
+        lexicons: Object.fromEntries(Object.entries(lexicons).map(([lex, m]) => [lex, lexiconSupport(r, m, lex)])),
+        notEvaluated: list(r.meta["not-evaluated"]),
+        uses: usesOf(r),
+        rule: r.text,
+    }));
+    const helpers = rules.filter((r) => !isPublic(r)).map((r) => ({ name: r.name, rule: r.text }));
+    return { capabilities, helpers };
+}

package/dist/capabilities/language.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The capability rule language (#4375, ruled on #4361).
+ *
+ * A capability is a named path pattern over the lexicon-neutral view
+ * (`./view.ts`). Its steps are #4359's edge terms: an arrow, an optional
+ * depth, then what the edge is. A rule file is data, read at run time:
+ *
+ *   # a comment
+ *   ## meaning: what the capability says, in one line      (catalog metadata)
+ *   in-sg(x, g)          := x ->{0,1}template ->sg g:SecurityGroup
+ *   open-ingress(c; port?, proto?)
+ *                        := c ->in-sg ->ingress :IngressRule[cidrs in ("0.0.0.0/0"), from <= $port]
+ *   internet-reachable(c; port?)
+ *                        := c[@internet-facing, @open-ingress($port)]
+ *                         | c:Function <-function :FunctionUrl[authType = "NONE"]
+ *
+ * One variable makes a node set, used as `[@name]`. Two make a named edge,
+ * followed as `->name` or `<-name`, which carries the hops that proved it.
+ * Parameters come after `;`; a `?` makes one optional, and a test that names
+ * an absent parameter is left out. Lines starting `|` add an alternative.
+ *
+ * A step is `->` or `<-`, an optional depth (`?`, `*`, `+`, `{n}`, `{m,n}`,
+ * `{m,}`; a rule may start at 0, which #4359's query grammar refuses), an
+ * edge name or `(a|b)`, and an optional node: `var:Label|Label[tests]`.
+ * `!->name node` and `!<-name node` are negated steps: the walk stays where
+ * it is and goes on only when no such edge leads to such a node.
+ *
+ * A node test is `attr = v`, `attr != v`, `attr in (v, ...)`, `attr ~ "glob"`,
+ * `attr < n` (and `<=`, `>`, `>=`), a bare `attr` (present and not false),
+ * or `@cap` / `@cap(args)`. Any test takes a leading `!`. Against a list
+ * attribute, a test holds when it holds for any element.
+ */
+export type Literal = string | number | boolean | null;
+/** A value in a test or an argument: a literal, or a reference to a parameter. */
+export type Value = {
+    lit: Literal;
+} | {
+    param: string;
+};
+export type Test = {
+    kind: "attr";
+    negated: boolean;
+    attr: string;
+    op: "=" | "!=" | "in" | "~" | "<" | "<=" | ">" | ">=" | "present";
+    values: Value[];
+} | {
+    kind: "cap";
+    negated: boolean;
+    cap: string;
+    args: Value[];
+};
+export interface NodeSpec {
+    v?: string;
+    labels?: string[];
+    tests: Test[];
+}
+export interface Step {
+    dir: "out" | "in";
+    negated: boolean;
+    /** Edge names: view edges or two-variable capabilities. */
+    names: {
+        name: string;
+        args: Value[];
+    }[];
+    min: number;
+    max: number;
+    node: NodeSpec;
+}
+export interface Alternative {
+    head: NodeSpec;
+    steps: Step[];
+    /** 1-based line in the rule file, for messages. */
+    line: number;
+}
+export interface Param {
+    name: string;
+    optional: boolean;
+}
+export interface Rule {
+    name: string;
+    vars: string[];
+    params: Param[];
+    alts: Alternative[];
+    /** `## key: value` lines above the rule. */
+    meta: Record<string, string>;
+    line: number;
+    /** The rule as written, one alternative per line, comments dropped. */
+    text: string;
+}
+/** A rule file the parser cannot read, with the line it failed on. */
+export declare class RuleSyntaxError extends Error {
+    readonly line: number;
+    constructor(message: string, line: number);
+}
+/**
+ * Parse a rule file. Rules may span lines: a line that starts with `|`
+ * continues the rule above it, and so does an indented line when the rule's
+ * `:=` has nothing after it yet.
+ */
+export declare function parseRules(text: string): Rule[];
+/** The capabilities a rule refers to, by name: in `[@cap]` tests and in steps. */
+export declare function ruleDependencies(rule: Rule): Set<string>;
+//# sourceMappingURL=language.d.ts.map

package/dist/capabilities/language.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"language.d.ts","sourceRoot":"","sources":["../../src/capabilities/language.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAEvD,kFAAkF;AAClF,MAAM,MAAM,KAAK,GAAG;IAAE,GAAG,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD,MAAM,MAAM,IAAI,GACZ;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,GAAG,GAAG,IAAI,GAAG,IAAI,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,GAAG,GAAG,GAAG,IAAI,GAAG,SAAS,CAAC;IAAC,MAAM,EAAE,KAAK,EAAE,CAAA;CAAE,GACpI;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,KAAK,EAAE,CAAA;CAAE,CAAC;AAElE,MAAM,WAAW,QAAQ;IACvB,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,EAAE,IAAI,EAAE,CAAC;CACf;AAED,MAAM,WAAW,IAAI;IACnB,GAAG,EAAE,KAAK,GAAG,IAAI,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,2DAA2D;IAC3D,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,KAAK,EAAE,CAAA;KAAE,EAAE,CAAC;IACzC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,QAAQ,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,IAAI;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,IAAI,EAAE,WAAW,EAAE,CAAC;IACpB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;CACd;AAED,sEAAsE;AACtE,qBAAa,eAAgB,SAAQ,KAAK;IAGtC,QAAQ,CAAC,IAAI,EAAE,MAAM;IAFvB,YACE,OAAO,EAAE,MAAM,EACN,IAAI,EAAE,MAAM,EAGtB;CACF;AAkBD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,CA0D/C;AA2LD,kFAAkF;AAClF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,CAaxD"}