pyric 0.0.1 → 0.1.0-alpha.11

package/dist/rules/linter/hallucinations.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Hallucination lint rules.
+ *
+ * Catches JavaScript-style code that compiles in Firestore rules
+ * (because CEL is dynamically typed) but fails at runtime with an
+ * opaque `permission-denied` error.
+ *
+ * These rules are mechanical AST checks against a known-bad set of
+ * method names, globals, and context paths. The CEL spec doesn't
+ * change often and Firestore's runtime stdlib is small, so the
+ * known-bad lists are stable.
+ *
+ * All rules in this module emit `error` severity by default — a true
+ * positive is always a true positive (the named method or global
+ * literally does not exist), so blocking deploy is correct behavior.
+ * The exceptions are LENGTH_PROPERTY and METHOD_MISSING_PARENS, which
+ * could theoretically collide with user-chosen field names; those emit
+ * `warning` severity.
+ */
+import type { FirestoreRules } from '../grammar/FirestoreAST.js';
+import type { LintWarning } from './linter.js';
+/**
+ * Pre-parse syntactic check. Strips comments, scans the source for the
+ * SYNTAX_HINTS patterns, emits one `INVALID_OPERATOR` per distinct hit.
+ */
+export declare function checkSyntaxHints(source: string): LintWarning[];
+/**
+ * Walks every expression in the rules and flags JS-style code that
+ * Firestore parses but cannot evaluate. Returns one warning per
+ * distinct (rule, key, location) tuple — duplicate identical patterns
+ * within the same rule are de-duplicated.
+ */
+export declare function checkHallucinations(ast: FirestoreRules): LintWarning[];
+//# sourceMappingURL=hallucinations.d.ts.map

package/dist/rules/linter/hallucinations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hallucinations.d.ts","sourceRoot":"","sources":["../../../src/rules/linter/hallucinations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EACV,cAAc,EAGf,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAmI/C;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,EAAE,CAe9D;AAiDD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,cAAc,GAAG,WAAW,EAAE,CA+ItE"}

package/dist/rules/linter/hallucinations.js

@@ -0,0 +1,334 @@
+// ─── Known-bad sets ───────────────────────────────────────────────────
+/**
+ * JavaScript array/string methods that don't exist on any CEL type
+ * used in Firestore rules (List, Map, String, Set, Timestamp, Path).
+ *
+ * The map value is a hint shown to the user — what to use instead, or
+ * why no equivalent exists.
+ */
+const HALLUCINATED_METHODS = {
+    // Array methods
+    where: 'No equivalent in rules — restructure logic instead of filtering a list',
+    filter: 'No equivalent in rules — restructure logic instead of filtering a list',
+    find: 'No equivalent in rules',
+    findIndex: 'No equivalent in rules',
+    map: 'No equivalent in rules — lists are not transformable',
+    reduce: 'No equivalent in rules',
+    forEach: 'No equivalent in rules',
+    every: 'Use `list.hasAll([...])` for "all elements present"',
+    some: 'Use `list.hasAny([...])` for "any element present"',
+    includes: 'Use `x in list` instead of `list.includes(x)`',
+    indexOf: 'No equivalent in rules',
+    push: 'Lists are immutable in rules',
+    pop: 'Lists are immutable in rules',
+    shift: 'Lists are immutable in rules',
+    unshift: 'Lists are immutable in rules',
+    splice: 'Lists are immutable in rules',
+    slice: 'No equivalent in rules',
+    sort: 'Lists are immutable in rules',
+    reverse: 'Lists are immutable in rules',
+    flat: 'No equivalent in rules',
+    flatMap: 'No equivalent in rules',
+    // String methods
+    toLowerCase: 'Use `.lower()` instead of `.toLowerCase()`',
+    toUpperCase: 'Use `.upper()` instead of `.toUpperCase()`',
+    charAt: 'No equivalent in rules — use `.split("")` and index',
+    charCodeAt: 'No equivalent in rules',
+    substring: 'No `.substring()` — use `.split()` and reassembly',
+    substr: 'No `.substr()` — use `.split()` and reassembly',
+    padStart: 'No equivalent in rules',
+    padEnd: 'No equivalent in rules',
+    trimStart: 'Use `.trim()` (trims both ends)',
+    trimEnd: 'Use `.trim()` (trims both ends)',
+    // Conversion
+    toString: 'Use the `string(x)` cast instead of `.toString()`',
+};
+/**
+ * JavaScript globals or constructors that don't exist as identifiers in
+ * Firestore rules. CEL has no module system and a tiny global namespace
+ * (just `request`, `resource`, custom functions, and a handful of
+ * built-in casts: `string`, `int`, `float`, `bool`, `timestamp`).
+ */
+const HALLUCINATED_GLOBALS = {
+    Object: 'No `Object` in rules — use `data.keys()` / `data.values()` directly',
+    Array: 'No `Array` in rules — test list type with `x is list`',
+    JSON: 'No `JSON` in rules — rules cannot parse or serialize JSON',
+    Math: 'No `Math` in rules — inline arithmetic or ternaries',
+    Date: 'No `Date` in rules — use `request.time` (a Timestamp)',
+    String: 'Use lowercase `string(x)` for casting',
+    Number: 'Use lowercase `int(x)` or `float(x)` for casting',
+    Boolean: 'Use lowercase `bool(x)` for casting',
+    parseInt: 'Use `int(x)` instead',
+    parseFloat: 'Use `float(x)` instead',
+    isNaN: 'No equivalent in rules',
+    isFinite: 'No equivalent in rules',
+    Promise: 'Rules are synchronous — no Promise support',
+    undefined: '`undefined` does not exist in rules — use `null`',
+};
+const WRONG_CONTEXT_PATHS = [
+    { receiver: 'request', property: 'data',
+        suggestion: 'Use `request.resource.data` (the incoming write payload)' },
+    { receiver: 'request', property: 'uid',
+        suggestion: 'Use `request.auth.uid`' },
+    { receiver: 'request', property: 'token',
+        suggestion: 'Use `request.auth.token`' },
+    { receiver: 'request', property: 'user',
+        suggestion: 'Use `request.auth` (or `request.auth.uid` for the user id)' },
+    { receiver: 'resource', property: 'path',
+        suggestion: '`resource.path` is not available — bind path captures in the match pattern' },
+    { receiver: 'resource', property: 'exists',
+        suggestion: 'Use `resource != null` (or `exists()` for cross-document checks)' },
+    { receiver: 'resource', property: 'id',
+        suggestion: '`resource.id` is not available — capture the document id with `/{docId}` in the match path' },
+];
+/**
+ * Built-in CEL methods that, when accessed without parentheses, are
+ * almost certainly a missing-call mistake. Restricted to a small
+ * high-confidence set; some method names (e.g. `keys`, `values`) could
+ * collide with user field names, so these emit `warning` severity.
+ */
+const KNOWN_BUILTIN_METHODS = new Set([
+    'size', 'keys', 'values', 'lower', 'upper', 'trim',
+    'hasAll', 'hasAny', 'hasOnly', 'toSet', 'toUtf8',
+]);
+// ─── Pre-parse syntactic hints ────────────────────────────────────────
+/**
+ * Operators and syntax forms that don't exist in CEL but commonly appear
+ * in agent-written rules. Detected via regex on the source so they fire
+ * even when the file fails to parse — most of these are syntax errors,
+ * but the underlying parse error message ("expected )") buries the
+ * actual cause.
+ */
+const SYNTAX_HINTS = [
+    { pattern: /===/,
+        message: 'Strict equality `===` is not supported in Firestore rules — use `==`.' },
+    { pattern: /!==/,
+        message: 'Strict inequality `!==` is not supported in Firestore rules — use `!=`.' },
+    { pattern: /\?\./,
+        message: 'Optional chaining `?.` is not supported — use `\'field\' in obj && obj.field`.' },
+    { pattern: /\?\?/,
+        message: 'Nullish coalescing `??` is not supported — use a ternary `cond ? a : b`.' },
+    { pattern: /=>/,
+        message: 'Arrow functions `=>` are not supported — define functions with `function name() { return ...; }`.' },
+    { pattern: /`[^`]*`/,
+        message: 'Backtick strings are not supported — use single or double quoted strings with `+` for concatenation.' },
+];
+/**
+ * Pre-parse syntactic check. Strips comments, scans the source for the
+ * SYNTAX_HINTS patterns, emits one `INVALID_OPERATOR` per distinct hit.
+ */
+export function checkSyntaxHints(source) {
+    const warnings = [];
+    const stripped = source
+        .replace(/\/\/[^\n]*/g, '')
+        .replace(/\/\*[\s\S]*?\*\//g, '');
+    for (const hint of SYNTAX_HINTS) {
+        if (hint.pattern.test(stripped)) {
+            warnings.push({
+                rule: 'INVALID_OPERATOR',
+                severity: 'error',
+                message: hint.message,
+            });
+        }
+    }
+    return warnings;
+}
+function walkAllExpressions(match, visit) {
+    const path = match.path.raw;
+    for (const fn of match.functions) {
+        const loc = { matchPath: path, functionName: fn.name };
+        walkExpr(fn.body, loc, visit);
+        for (const b of fn.lets)
+            walkExpr(b.value, loc, visit);
+    }
+    for (let i = 0; i < match.allows.length; i++) {
+        walkExpr(match.allows[i].condition, { matchPath: path, ruleIndex: i }, visit);
+    }
+    for (const child of match.children)
+        walkAllExpressions(child, visit);
+}
+function walkExpr(expr, loc, visit) {
+    visit(expr, loc);
+    switch (expr.type) {
+        case 'binaryOp':
+            walkExpr(expr.left, loc, visit);
+            walkExpr(expr.right, loc, visit);
+            break;
+        case 'unaryOp':
+            walkExpr(expr.operand, loc, visit);
+            break;
+        case 'methodCall':
+            walkExpr(expr.object, loc, visit);
+            expr.args.forEach(a => walkExpr(a, loc, visit));
+            break;
+        case 'memberAccess':
+            walkExpr(expr.object, loc, visit);
+            break;
+        case 'bracketAccess':
+            walkExpr(expr.object, loc, visit);
+            walkExpr(expr.index, loc, visit);
+            break;
+        case 'ternary':
+            walkExpr(expr.condition, loc, visit);
+            walkExpr(expr.consequent, loc, visit);
+            walkExpr(expr.alternate, loc, visit);
+            break;
+        case 'inExpr':
+            walkExpr(expr.element, loc, visit);
+            walkExpr(expr.collection, loc, visit);
+            break;
+        case 'isExpr':
+            walkExpr(expr.value, loc, visit);
+            break;
+        case 'listLiteral':
+            expr.elements.forEach(e => walkExpr(e, loc, visit));
+            break;
+        case 'mapLiteral':
+            expr.entries.forEach(en => { walkExpr(en.key, loc, visit); walkExpr(en.value, loc, visit); });
+            break;
+        case 'functionCall':
+            expr.args.forEach(a => walkExpr(a, loc, visit));
+            break;
+    }
+}
+// ─── Post-parse hallucination check ───────────────────────────────────
+/**
+ * Walks every expression in the rules and flags JS-style code that
+ * Firestore parses but cannot evaluate. Returns one warning per
+ * distinct (rule, key, location) tuple — duplicate identical patterns
+ * within the same rule are de-duplicated.
+ */
+export function checkHallucinations(ast) {
+    const warnings = [];
+    const seen = new Set();
+    function emit(rule, key, loc, w) {
+        const dedup = `${rule}|${key}|${loc.matchPath || ''}|${loc.functionName || ''}|${loc.ruleIndex ?? ''}`;
+        if (seen.has(dedup))
+            return;
+        seen.add(dedup);
+        warnings.push(w);
+    }
+    walkAllExpressions(ast.service.match, (expr, loc) => {
+        // HALLUCINATED_METHOD — obj.someJsMethod(...)
+        if (expr.type === 'methodCall' && HALLUCINATED_METHODS[expr.method]) {
+            emit('HALLUCINATED_METHOD', expr.method, loc, {
+                rule: 'HALLUCINATED_METHOD',
+                severity: 'error',
+                message: `\`.${expr.method}()\` does not exist in Firestore rules. ${HALLUCINATED_METHODS[expr.method]}`,
+                location: loc,
+                fix: HALLUCINATED_METHODS[expr.method],
+            });
+        }
+        // HALLUCINATED_GLOBAL — Object.keys(...), JSON.parse(...), Math.max(...)
+        if (expr.type === 'methodCall' && expr.object.type === 'identifier' && HALLUCINATED_GLOBALS[expr.object.name]) {
+            const name = expr.object.name;
+            emit('HALLUCINATED_GLOBAL', `${name}.${expr.method}`, loc, {
+                rule: 'HALLUCINATED_GLOBAL',
+                severity: 'error',
+                message: `\`${name}.${expr.method}()\` does not exist in Firestore rules. ${HALLUCINATED_GLOBALS[name]}`,
+                location: loc,
+                fix: HALLUCINATED_GLOBALS[name],
+            });
+        }
+        // HALLUCINATED_GLOBAL — bare function call: parseInt(x), isNaN(x)
+        if (expr.type === 'functionCall' && HALLUCINATED_GLOBALS[expr.name]) {
+            emit('HALLUCINATED_GLOBAL', expr.name, loc, {
+                rule: 'HALLUCINATED_GLOBAL',
+                severity: 'error',
+                message: `\`${expr.name}()\` does not exist in Firestore rules. ${HALLUCINATED_GLOBALS[expr.name]}`,
+                location: loc,
+                fix: HALLUCINATED_GLOBALS[expr.name],
+            });
+        }
+        // HALLUCINATED_GLOBAL — bare identifier reference (e.g. `Math` used as a value)
+        if (expr.type === 'identifier' && HALLUCINATED_GLOBALS[expr.name]) {
+            emit('HALLUCINATED_GLOBAL', `ref:${expr.name}`, loc, {
+                rule: 'HALLUCINATED_GLOBAL',
+                severity: 'error',
+                message: `\`${expr.name}\` is not a Firestore rules identifier. ${HALLUCINATED_GLOBALS[expr.name]}`,
+                location: loc,
+                fix: HALLUCINATED_GLOBALS[expr.name],
+            });
+        }
+        // WRONG_CONTEXT_PATH — request.data, request.uid, resource.path, etc.
+        if (expr.type === 'memberAccess' && expr.object.type === 'identifier') {
+            const recv = expr.object.name;
+            const prop = expr.property;
+            const m = WRONG_CONTEXT_PATHS.find(p => p.receiver === recv && p.property === prop);
+            if (m) {
+                emit('WRONG_CONTEXT_PATH', `${recv}.${prop}`, loc, {
+                    rule: 'WRONG_CONTEXT_PATH',
+                    severity: 'error',
+                    message: `\`${recv}.${prop}\` is not a valid Firestore rules path. ${m.suggestion}`,
+                    location: loc,
+                    fix: m.suggestion,
+                });
+            }
+        }
+        // LENGTH_PROPERTY — `.length` accessed on the result of a method call,
+        // which is unambiguously a JS confusion (CEL methods return lists or
+        // strings, neither of which has `.length` — both have `.size()`).
+        // Skip when the receiver is plain data, since fields named "length"
+        // are legitimate on user documents.
+        if (expr.type === 'memberAccess' &&
+            expr.property === 'length' &&
+            expr.object.type === 'methodCall') {
+            emit('LENGTH_PROPERTY', '', loc, {
+                rule: 'LENGTH_PROPERTY',
+                severity: 'error',
+                message: '`.length` is not a valid property in Firestore rules — use `.size()` (a method, with parentheses).',
+                location: loc,
+                fix: 'Replace `.length` with `.size()`.',
+            });
+        }
+        // INVALID_PATH_INTERPOLATION — `{var}` syntax used inside a path literal,
+        // which is the match-statement wildcard syntax in the wrong context.
+        // Path literals (the argument to get/exists/getAfter/existsAfter) require
+        // `$(var)` for interpolation. Without this rule, the parser would
+        // backtrack into MapLiteral and emit an opaque "expected ':'" diagnostic
+        // that an iterating agent cannot recover from. We accept `{ident}` in the
+        // grammar specifically so this diagnostic can fire.
+        if (expr.type === 'pathLiteral') {
+            for (const seg of expr.segments) {
+                if (typeof seg !== 'string')
+                    continue;
+                const m = seg.match(/^\{([A-Za-z_][A-Za-z0-9_]*)\}$/);
+                if (!m)
+                    continue;
+                const name = m[1];
+                emit('INVALID_PATH_INTERPOLATION', `${expr.raw}|${name}`, loc, {
+                    rule: 'INVALID_PATH_INTERPOLATION',
+                    severity: 'error',
+                    message: `\`{${name}}\` is not valid inside a path literal — Firestore rejects this at deploy. ` +
+                        `The \`{var}\` syntax is for match statement wildcards (e.g. \`match /users/{userId}\`); ` +
+                        `path interpolation in get()/exists()/getAfter()/existsAfter() requires \`$(var)\`. ` +
+                        `Replace \`{${name}}\` with \`$(${name})\` in path \`${expr.raw}\`.`,
+                    location: loc,
+                    fix: `Replace \`{${name}}\` with \`$(${name})\` inside the path argument.`,
+                });
+            }
+        }
+        // METHOD_MISSING_PARENS — built-in method name accessed as a bare
+        // property (e.g. `data.size` instead of `data.size()`). Restricted
+        // to receivers that are likely rules data, and emitted as `warning`
+        // because field names can collide with method names.
+        if (expr.type === 'memberAccess' && KNOWN_BUILTIN_METHODS.has(expr.property)) {
+            const isLikelyData = (expr.object.type === 'identifier' &&
+                (expr.object.name === 'request' || expr.object.name === 'resource')) ||
+                expr.object.type === 'memberAccess' ||
+                expr.object.type === 'methodCall' ||
+                expr.object.type === 'bracketAccess';
+            if (isLikelyData) {
+                emit('METHOD_MISSING_PARENS', expr.property, loc, {
+                    rule: 'METHOD_MISSING_PARENS',
+                    severity: 'warning',
+                    message: `\`.${expr.property}\` looks like a built-in method called without parentheses. Use \`.${expr.property}()\` if you meant to invoke it (otherwise this is a field access).`,
+                    location: loc,
+                    fix: `Add parentheses: \`.${expr.property}()\`.`,
+                });
+            }
+        }
+    });
+    return warnings;
+}
+//# sourceMappingURL=hallucinations.js.map

package/dist/rules/linter/hallucinations.js.map

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

package/dist/rules/linter/linter.d.ts

@@ -0,0 +1,84 @@
+import { type ParseError } from '../grammar/FirestoreParser.js';
+import type { TestCase } from '../test/spec.js';
+export interface LintWarning {
+    rule: string;
+    severity: 'warning' | 'error';
+    message: string;
+    location?: {
+        functionName?: string;
+        ruleIndex?: number;
+        matchPath?: string;
+        /** Test-case description from `TestCase.description`. Set only by
+         *  rules that operate on the optional test suite (e.g. REQUEST_TIME_NOT_PINNED). */
+        testCaseDescription?: string;
+    };
+    fix?: string;
+}
+export interface RulesMetrics {
+    sourceSize: number;
+    functionCount: number;
+    allowRuleCount: number;
+    maxChainDepth: number;
+    maxChainOp: string;
+    maxLetBindings: number;
+    maxLetBindingsFunction: string;
+    maxCallDepth: number;
+    maxEstimatedExpressions: number;
+    getCallCount: number;
+}
+export interface LintResult {
+    warnings: LintWarning[];
+    metrics: RulesMetrics;
+    /**
+     * Structured parse failure when the source did not parse. When defined,
+     * `metrics` (except `sourceSize`) and `warnings` carry no signal —
+     * budget checks were skipped. Callers should branch on `parseError`
+     * before interpreting warnings or metrics.
+     *
+     * Why this isn't a new `severity` value: a parse failure means "this
+     * isn't a rule yet" rather than "this rule will fail at runtime", which
+     * is a categorically different question from anything `warnings`
+     * answers. Adding a new severity would force every consumer to handle
+     * a third branch they don't care about; a separate field lets old
+     * code keep working and gives new code a clean signal to check.
+     */
+    parseError?: ParseError;
+}
+/**
+ * Optional inputs for `lintFirestoreRules` that activate test-suite-coupled
+ * checks. Only `REQUEST_TIME_NOT_PINNED` reads from this surface today.
+ */
+export interface LintOptions {
+    /**
+     * The test cases that will be run against this rules source. When
+     * supplied, the linter activates `REQUEST_TIME_NOT_PINNED`: rules that
+     * read `request.time` get a warning per test case that targets them
+     * without setting `requestTime`. Omit this arg to keep behavior
+     * source-only (the historical default).
+     */
+    testCases?: TestCase[];
+    /**
+     * Source of the previously deployed ruleset. When supplied, the
+     * linter activates `RULES_WEAKENED`: any security predicate that
+     * existed in the previous ruleset but has been removed from the
+     * current one is reported. Designed to catch agents silently
+     * weakening rules to make a failing test pass. Silently skipped if
+     * the previous source fails to parse — a malformed prior should not
+     * block linting of a valid current ruleset.
+     */
+    previousSource?: string;
+}
+/**
+ * Lint Firestore security rules.
+ *
+ * Contract: if the source doesn't parse, `parseError` is populated and
+ * budget checks are skipped — `warnings` will be empty (or contain only
+ * source-size which doesn't depend on parsing) and `metrics` fields other
+ * than `sourceSize` are zeroed. Callers must check `parseError` first.
+ *
+ * Pass `options.testCases` to activate test-suite-coupled checks (e.g.
+ * REQUEST_TIME_NOT_PINNED). When omitted, the linter behaves exactly as
+ * it did before — back-compat with all existing callers.
+ */
+export declare function lintFirestoreRules(source: string, options?: LintOptions): LintResult;
+//# sourceMappingURL=linter.d.ts.map

package/dist/rules/linter/linter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"linter.d.ts","sourceRoot":"","sources":["../../../src/rules/linter/linter.ts"],"names":[],"mappings":"AAUA,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,+BAA+B,CAAC;AACnF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAoBhD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,SAAS,GAAG,OAAO,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE;QACT,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB;4FACoF;QACpF,mBAAmB,CAAC,EAAE,MAAM,CAAC;KAC9B,CAAC;IACF,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,uBAAuB,EAAE,MAAM,CAAC;IAChC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,OAAO,EAAE,YAAY,CAAC;IACtB;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AA8pBD;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;IACvB;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,UAAU,CAwHxF"}