roll-parser 3.0.0-alpha.0 → 3.0.0

package/dist/parser/guards.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Parser-internal AST guards.
+ *
+ * These helpers answer structural questions the parser's reject rules ask
+ * ("does this operand resolve to a dice pool?", "is a Versus buried in
+ * here?"). They are implementation detail of `parser.ts` — the public
+ * `isXxx` type guards stay in `ast.ts`.
+ *
+ * @module parser/guards
+ */
+import type { ASTNode } from './ast.js';
+/**
+ * Peels nested `Grouped` wrappers, returning the first descendant that is not
+ * one. The narrow unwrap for reject helpers whose forbidden node cannot live
+ * inside `KeepDrop`/`Sort`/`CritThreshold` — those parsers already reject it
+ * upstream, so peeling parentheses is all that is left to see through.
+ */
+export declare function unwrapGrouped(node: ASTNode): ASTNode;
+/**
+ * Peels every transparent wrapper — `Grouped`, `KeepDrop`, `Sort`,
+ * `CritThreshold`, `DieBound` — returning the first descendant that is none of
+ * them.
+ *
+ * "Transparent" is relative to the question being asked. These wrappers
+ * preserve `containsDicePool`'s answer for whatever they wrap, so they are
+ * transparent for "what is the underlying operand?" when deciding whether to
+ * reject a `Group` target (e.g., `Group` cannot be the target of `cs`/`cf`,
+ * even when wrapped in `KeepDrop` like `{1d6}kh1cs>5`). They are NOT
+ * transparent for "is this a `SuccessCount`?" or "is this a `Versus`?" —
+ * those questions use `unwrapGrouped`.
+ */
+export declare function unwrapAllTransparent(node: ASTNode): ASTNode;
+/**
+ * Returns `true` only when `node`'s direct result is a dice pool —
+ * `Dice`, `FateDice`, or a chained pool modifier (`KeepDrop` / `Explode` /
+ * `Reroll`). Does NOT recurse through arithmetic wrappers (`BinaryOp`,
+ * `UnaryOp`, `FunctionCall`), so `(1d6+5)` and `floor(1d6/2)` are rejected.
+ *
+ * Used by the parser to reject postfix pool-modifier targets (kh/kl/dh/dl,
+ * !/!!/!p, r/ro) that wrap a non-pool expression. Operating on the inner
+ * dice pool would silently drop the surrounding arithmetic.
+ */
+export declare function containsDicePool(node: ASTNode): boolean;
+/**
+ * Deeper variant of `containsDicePool` that recurses through arithmetic and
+ * function wrappers. Used from the `Group` case above (ordinary parenthesized
+ * arithmetic `(1d6+5)kh1` must still reject, so the shallow `containsDicePool`
+ * handles those directly) and from the Sort parser guard (sort accepts
+ * `(1d6+2d8)s` per Stage 3 spec).
+ *
+ * A multi-sub-roll `Group` counts as a pool in its own right (compound dice),
+ * matching `containsDicePool`'s Group rule.
+ */
+export declare function deepContainsDicePool(node: ASTNode): boolean;
+/**
+ * Returns `true` if the pool this node resolves to is (or wraps) a `FateDice`
+ * pool. Walks through chained pool modifiers (`KeepDrop` / `Explode` /
+ * `Reroll`) but not arithmetic wrappers — callers should run
+ * `containsDicePool` first to reject those.
+ *
+ * Used by the parser to reject `!`, `!!`, `!p` applied to Fate pools
+ * (`4dF!`, `(4dF)kh2!`, etc.). Fate explosion semantics are undefined, so
+ * parse-time rejection is preferred over a silent evaluator no-op.
+ *
+ * Inside a `Group`, recursion uses `deepContainsFatePool` to mirror
+ * `containsDicePool`'s deep walk through the same case — otherwise
+ * `{4dF+1d6}cf` slips past the bare-Fate guard and the default fumble
+ * check (`result === 1`) flips `+1` faces into fumbles.
+ */
+export declare function containsFatePool(node: ASTNode): boolean;
+/**
+ * Deeper variant of `containsFatePool` that recurses through arithmetic and
+ * function wrappers. Mirrors `deepContainsDicePool`. Used from
+ * `containsFatePool`'s `Group` case so single-sub-roll groups containing
+ * arithmetic-wrapped Fate (`{4dF+1d6}cf`) still trip the bare-Fate guard.
+ *
+ * Outside a `Group`, ordinary parenthesized arithmetic (`(4dF+1d6)cf`) is
+ * already rejected upstream by shallow `containsDicePool`, so this helper
+ * intentionally stays Group-internal.
+ */
+export declare function deepContainsFatePool(node: ASTNode): boolean;
+/**
+ * Deep-walks a node to find any descendant `Group` with two or more
+ * sub-expressions. Used by `rejectGroupTarget`'s single-sub-roll
+ * passthrough so a multi-sub Group buried under arithmetic
+ * (`{{1d6,2d8}+0}cs>5`), function calls (`{abs({1d6,2d8})}cs>5`), or any
+ * other non-transparent wrapper still rejects with the same error code.
+ *
+ * Without this walk, the unwrap inside `rejectGroupTarget` only peels
+ * `Grouped`/`KeepDrop`/`Sort`/`CritThreshold` — a multi-sub Group cloaked
+ * in a `BinaryOp`/`UnaryOp`/`FunctionCall` reaches the evaluator, where it
+ * flags crits on dice belonging to dropped sub-rolls.
+ */
+export declare function containsMultiSubGroup(node: ASTNode): boolean;
+/**
+ * Deep-walks a node to find any descendant `Versus`. A buried Versus
+ * (`floor(1d20 vs 15)`, `(1d20 vs 15)+0`, `{1+(1d20 vs 15)}`) must reject with
+ * `NESTED_VERSUS` rather than silently drop `versusMetadata` at the consumer.
+ *
+ * Two callers, both on that hole: `rejectVersusMetaOperand` guards every meta
+ * operand — dice count and sides, keep/drop count, thresholds, die bounds — and
+ * `rejectVersusTarget` uses it for its single-sub-roll Group passthrough.
+ * `evalMetaOperand` runs the same walk as the hand-built-AST backstop.
+ */
+export declare function containsVersus(node: ASTNode): boolean;
+//# sourceMappingURL=guards.d.ts.map

package/dist/parser/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/parser/guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAExC;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAMpD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAiB3D;AA8DD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAyBvD;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAE3D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAkBvD;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAE3D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAE5D;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAErD"}

package/dist/parser/guards.js

@@ -0,0 +1,121 @@
+export function unwrapGrouped(node) {
+    let current = node;
+    while (current.type === 'Grouped') {
+        current = current.expression;
+    }
+    return current;
+}
+export function unwrapAllTransparent(node) {
+    let current = node;
+    while (true) {
+        switch (current.type) {
+            case 'Grouped':
+                current = current.expression;
+                break;
+            case 'KeepDrop':
+            case 'Sort':
+            case 'CritThreshold':
+            case 'DieBound':
+                current = current.target;
+                break;
+            default:
+                return current;
+        }
+    }
+}
+function someDescendant(node, isHit) {
+    if (isHit(node))
+        return true;
+    switch (node.type) {
+        case 'BinaryOp':
+            return someDescendant(node.left, isHit) || someDescendant(node.right, isHit);
+        case 'UnaryOp':
+            return someDescendant(node.operand, isHit);
+        case 'KeepDrop':
+        case 'Explode':
+        case 'Reroll':
+        case 'DieBound':
+        case 'SuccessCount':
+        case 'Sort':
+        case 'CritThreshold':
+            return someDescendant(node.target, isHit);
+        case 'Versus':
+            return someDescendant(node.roll, isHit) || someDescendant(node.dc, isHit);
+        case 'FunctionCall': {
+            for (const arg of node.args) {
+                if (someDescendant(arg, isHit))
+                    return true;
+            }
+            return false;
+        }
+        case 'Grouped':
+            return someDescendant(node.expression, isHit);
+        case 'Group': {
+            for (const expression of node.expressions) {
+                if (someDescendant(expression, isHit))
+                    return true;
+            }
+            return false;
+        }
+        default:
+            return false;
+    }
+}
+const isDicePoolHit = (current) => current.type === 'Dice' ||
+    current.type === 'FateDice' ||
+    (current.type === 'Group' && current.expressions.length >= 2);
+const isFateDiceHit = (current) => current.type === 'FateDice';
+const isMultiSubGroupHit = (current) => current.type === 'Group' && current.expressions.length >= 2;
+const isVersusHit = (current) => current.type === 'Versus';
+export function containsDicePool(node) {
+    switch (node.type) {
+        case 'Dice':
+        case 'FateDice':
+        case 'KeepDrop':
+        case 'Explode':
+        case 'Reroll':
+        case 'DieBound':
+            return true;
+        case 'Sort':
+        case 'CritThreshold':
+            return containsDicePool(node.target);
+        case 'Grouped':
+            return containsDicePool(node.expression);
+        case 'Group':
+            return node.expressions.length >= 2 || node.expressions.some(deepContainsDicePool);
+        default:
+            return false;
+    }
+}
+export function deepContainsDicePool(node) {
+    return someDescendant(node, isDicePoolHit);
+}
+export function containsFatePool(node) {
+    switch (node.type) {
+        case 'FateDice':
+            return true;
+        case 'KeepDrop':
+        case 'Explode':
+        case 'Reroll':
+        case 'DieBound':
+        case 'Sort':
+        case 'CritThreshold':
+            return containsFatePool(node.target);
+        case 'Grouped':
+            return containsFatePool(node.expression);
+        case 'Group':
+            return node.expressions.some(deepContainsFatePool);
+        default:
+            return false;
+    }
+}
+export function deepContainsFatePool(node) {
+    return someDescendant(node, isFateDiceHit);
+}
+export function containsMultiSubGroup(node) {
+    return someDescendant(node, isMultiSubGroupHit);
+}
+export function containsVersus(node) {
+    return someDescendant(node, isVersusHit);
+}
+//# sourceMappingURL=guards.js.map

package/dist/parser/guards.js.map

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

package/dist/parser/parser.d.ts

@@ -3,19 +3,70 @@
  *
  * @module parser/parser
  */
-import type { RollParserErrorCode } from '../errors';
-import { RollParserError } from '../errors';
-import { type Token } from '../lexer/tokens';
-import type { ComparePoint } from '../types';
-import type { ASTNode } from './ast';
+import type { RollParserErrorCode } from '../errors.js';
+import { RollParserError } from '../errors.js';
+import { type Token } from '../lexer/tokens.js';
+import type { ASTNode } from './ast.js';
 /**
  * Error thrown when the parser encounters invalid syntax.
+ *
+ * `position` is a zero-based UTF-16 offset into the notation. It is
+ * deliberately absent from `message` — read it from the field, or uniformly
+ * across all roll-parser errors via `getErrorSpan`.
+ *
+ * @example
+ * ```typescript
+ * import { ParseError, roll, TokenType } from 'roll-parser';
+ *
+ * try {
+ *   roll('4d6d1');
+ * } catch (error) {
+ *   const typed = error as ParseError;
+ *   typed.code; // 'AMBIGUOUS_DICE_CHAIN'
+ *   typed.position; // 3
+ *   typed.token?.type === TokenType.DICE; // true
+ * }
+ * ```
+ *
+ * @category Errors
  */
 export declare class ParseError extends RollParserError {
+    /** Zero-based UTF-16 offset in the notation where parsing failed. */
     readonly position: number;
+    /**
+     * The token the parser was looking at. `undefined` when the failure is not
+     * anchored to a token — currently only `UNEXPECTED_END`, raised when the
+     * input stops short.
+     */
     readonly token: Token | undefined;
-    constructor(message: string, code: RollParserErrorCode, position: number, token?: Token);
+    constructor(message: string, code: RollParserErrorCode, position: number, token?: Token, options?: ErrorOptions);
 }
+/**
+ * Maximum expression nesting depth. Far beyond any human-authored notation —
+ * exists so adversarial input like 20,000 nested parens throws a typed
+ * `ParseError` instead of an uncaught `RangeError` stack overflow (which
+ * would also break the `isRollParserError` contract). Bounding parse depth
+ * also bounds AST depth, protecting the recursive AST walkers and evaluator.
+ *
+ * Not configurable — unlike the {@link EvaluationOptions} caps, this one always
+ * applies, so untrusted notation can never blow the stack.
+ *
+ * @example
+ * ```typescript
+ * import { isRollParserError, MAX_PARSE_DEPTH, parse } from 'roll-parser';
+ *
+ * MAX_PARSE_DEPTH; // 128
+ *
+ * try {
+ *   parse('('.repeat(20_000) + '1d6' + ')'.repeat(20_000));
+ * } catch (error) {
+ *   isRollParserError(error) && error.code; // 'MAX_DEPTH_EXCEEDED'
+ * }
+ * ```
+ *
+ * @category Limits
+ */
+export declare const MAX_PARSE_DEPTH = 128;
 /**
  * Pratt parser for dice notation.
  *
@@ -25,6 +76,7 @@ export declare class ParseError extends RollParserError {
 export declare class Parser {
     private readonly tokens;
     private pos;
+    private depth;
     constructor(tokens: Token[]);
     /**
      * Parse the token stream into an AST.
@@ -34,6 +86,11 @@ export declare class Parser {
      * Parse an expression with minimum binding power.
      */
     private parseExpression;
+    /**
+     * Throw once the AST under construction is deeper than the recursive walkers
+     * can safely descend.
+     */
+    private guardDepth;
     /**
      * NUD - Null Denotation.
      * Handles tokens that appear at the start of an expression (prefix position).
@@ -44,6 +101,11 @@ export declare class Parser {
      * Handles tokens that appear between expressions (infix/postfix position).
      */
     private parseLed;
+    /**
+     * Zero-width span for synthetic nodes (implicit counts, `d%` sides) that
+     * have no source text of their own — anchored at the governing token.
+     */
+    private static syntheticLiteral;
     private parseLiteral;
     private parseUnaryMinus;
     private parsePrefixDice;
@@ -53,26 +115,82 @@ export declare class Parser {
     private parsePrefixFateDice;
     private parseInfixFateDice;
     private parseGrouped;
+    private parseGroup;
+    private parseVariable;
     private parseFunctionCall;
     private parseBinaryOp;
+    /**
+     * Rejects a dice token whose count operand is itself a bare (unparenthesized)
+     * dice expression. `4d6d1` would otherwise silently parse as `(4d6)d1` —
+     * roll 4d6, then use the result as a count of d1 dice — which is almost
+     * never intended: every major dice dialect reads `4d6d1` as "drop lowest 1".
+     * Both meanings stay reachable through explicit forms: `4d6dl1` to drop,
+     * `(4d6)d1` for nested dice.
+     */
+    private rejectBareDiceChain;
     private rejectSuccessCountTarget;
-    private parseModifier;
+    /**
+     * Rejects `GroupNode` (or a wrapper-cloaked group) as the target of `token`.
+     * Explode, reroll, and crit-threshold wrap bare dice pools only — a group
+     * is a container of sub-expressions, so these modifiers have no defined
+     * semantics. Walks `Grouped`/`KeepDrop`/`Sort`/`CritThreshold` so wrappers
+     * cannot smuggle a group past the check (`{1d6}kh1cs>5`, `({1d6})!`,
+     * `{1d6}scs>5` all reject the same as `{1d6}!`/`{1d6}cs>5`).
+     *
+     * `singleSubRollPasses` opts the caller into the single-sub-roll passthrough:
+     * a `Group` with one expression is the user's explicit flat-pool escape
+     * hatch and is equivalent to its unwrapped form. Currently only
+     * `parseCritThreshold` opts in — explode/reroll keep the strict reject so
+     * existing notation contracts don't shift.
+     */
+    private rejectGroupTarget;
+    /**
+     * Rejects a Versus anywhere inside a meta operand — a dice count, dice sides,
+     * a modifier count, or a threshold/bound value.
+     *
+     * Deep, unlike {@link rejectVersusTarget}: `evalMetaOperand` reduces the
+     * operand to a scalar and forwards rolls but not `versusMetadata`, so
+     * `floor(1d20 vs 15)` or `(1d20 vs 15)+0` buried in a count loses the degree
+     * exactly as a bare one does.
+     */
+    private rejectVersusMetaOperand;
+    /**
+     * The wording the meta-expression rejections share. Not every `NESTED_VERSUS`
+     * throw — `parseVersus` says "Cannot chain versus operators" for `a vs b vs c`,
+     * a different condition. Routing that one through here would silently rewrite
+     * its message, and `expectRollError` asserts only the code.
+     */
+    private static throwVersusMetaExpression;
+    private rejectVersusTarget;
+    private parseKeepDrop;
     private parseExplode;
     private parseReroll;
+    private parseDieBound;
+    private parseSort;
+    private parseCritThreshold;
     private parseSuccessCount;
+    /** Parses the `f...` suffix of a success count. Bare `fN` means `f=N`. */
+    private parseFailThreshold;
     private parseVersus;
     /**
      * Checks whether the next token is a comparison operator.
      */
-    isComparePointAhead(): boolean;
+    private isComparePointAhead;
     /**
      * Parses a comparison operator followed by a value expression.
      * Called by modifier parsers (explode, reroll, success counting).
      *
+     * The threshold value is parsed at `BP.DICE_LEFT`, which binds tighter than
+     * arithmetic. This keeps the comparison bound to the dice pool on the left
+     * rather than letting arithmetic to the right be consumed into the
+     * threshold. As a consequence, `1d6>=5+2` parses as `(1d6>=5)+2` with
+     * threshold `5` — not `7`. Computed thresholds require parens:
+     * `1d6>=(5+2)`. Same binding applies to `parseSuccessCount` below.
+     *
      * @returns A ComparePoint with the operator and value AST node
      * @throws {ParseError} If the next token is not a comparison operator
      */
-    parseComparePoint(): ComparePoint;
+    private parseComparePoint;
     private getCompareOp;
     private getOperatorSymbol;
     private getLeftBp;
@@ -83,20 +201,49 @@ export declare class Parser {
     private hasTokens;
 }
 /**
- * Parse a dice notation string into an AST.
+ * Parses a dice notation string into an {@link ASTNode} tree, lexing it first.
+ *
+ * {@link evaluate} never mutates the AST, so parse once and evaluate many times
+ * when rolling the same notation repeatedly — that skips the lexer and parser
+ * on every roll after the first. Use `parse` alone to validate notation
+ * without consuming randomness.
  *
  * @param notation - The dice notation to parse
- * @returns The root AST node
+ * @returns The root AST node, with `start`/`end` spans on every node
  * @throws {LexerError} If the input contains invalid characters
  * @throws {ParseError} If the input has invalid syntax
+ * @throws {RollParserError} `INVALID_NOTATION_TYPE` when `notation` is not a
+ *   string — raised before lexing, so it carries no position
  *
  * @example
  * ```typescript
- * const ast = parse('2d6+3');
- * // { type: 'BinaryOp', operator: '+',
- * //   left: { type: 'Dice', count: 2, sides: 6 },
- * //   right: { type: 'Literal', value: 3 } }
+ * import { parse } from 'roll-parser';
+ *
+ * parse('2d6+3');
+ * // {
+ * //   type: 'BinaryOp', operator: '+', start: 0, end: 5,
+ * //   left: {
+ * //     type: 'Dice', start: 0, end: 3,
+ * //     count: { type: 'Literal', value: 2, start: 0, end: 1 },
+ * //     sides: { type: 'Literal', value: 6, start: 2, end: 3 },
+ * //   },
+ * //   right: { type: 'Literal', value: 3, start: 4, end: 5 },
+ * // }
+ * ```
+ *
+ * `count` and `sides` are full nodes, not numbers — that is what makes
+ * computed dice like `(1d4)d6` expressible.
+ *
+ * @example Parse once, roll many
+ * ```typescript
+ * import { evaluate, parse, SeededRNG } from 'roll-parser';
+ *
+ * const ast = parse('4d6kh3');
+ * const rng = new SeededRNG('demo');
+ * const scores = Array.from({ length: 6 }, () => evaluate(ast, rng).total);
  * ```
+ *
+ * @category Core
  */
 export declare function parse(notation: string): ASTNode;
 //# sourceMappingURL=parser.d.ts.map

package/dist/parser/parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/parser/parser.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C,OAAO,EAAE,KAAK,KAAK,EAAa,MAAM,iBAAiB,CAAC;AACxD,OAAO,KAAK,EAAa,YAAY,EAAE,MAAM,UAAU,CAAC;AACxD,OAAO,KAAK,EACV,OAAO,EAYR,MAAM,OAAO,CAAC;AAGf;;GAEG;AACH,qBAAa,UAAW,SAAQ,eAAe;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC;gBAEtB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAMxF;AAkDD;;;;;GAKG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IACjC,OAAO,CAAC,GAAG,CAAK;gBAEJ,MAAM,EAAE,KAAK,EAAE;IAI3B;;OAEG;IACH,KAAK,IAAI,OAAO;IAqBhB;;OAEG;IACH,OAAO,CAAC,eAAe;IAgBvB;;;OAGG;IACH,OAAO,CAAC,QAAQ;IAsChB;;;OAGG;IACH,OAAO,CAAC,QAAQ;IAwDhB,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,sBAAsB;IAS9B,OAAO,CAAC,qBAAqB;IAS7B,OAAO,CAAC,mBAAmB;IAQ3B,OAAO,CAAC,kBAAkB;IAU1B,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,iBAAiB;IAgDzB,OAAO,CAAC,aAAa;IAarB,OAAO,CAAC,wBAAwB;IAWhC,OAAO,CAAC,aAAa;IA2BrB,OAAO,CAAC,YAAY;IA4BpB,OAAO,CAAC,WAAW;IAmBnB,OAAO,CAAC,iBAAiB;IAgCzB,OAAO,CAAC,WAAW;IAenB;;OAEG;IACH,mBAAmB,IAAI,OAAO;IAW9B;;;;;;OAMG;IACH,iBAAiB,IAAI,YAAY;IAWjC,OAAO,CAAC,YAAY;IAwBpB,OAAO,CAAC,iBAAiB;IAwBzB,OAAO,CAAC,SAAS;IA8CjB,OAAO,CAAC,UAAU;IAoBlB,OAAO,CAAC,IAAI;IAIZ,OAAO,CAAC,OAAO;IAMf,OAAO,CAAC,MAAM;IAcd,OAAO,CAAC,SAAS;CAGlB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAI/C"}
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/parser/parser.ts"],"names":[],"mappings":"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"}