sh-ast 0.3.1 → 0.5.0

package/dist/syntax-walk.js

@@ -0,0 +1,322 @@
+import { InputError } from './syntax-errors.js';
+import { afterItemStart, atStatementEnd } from './syntax-walk-bounds.js';
+import { nilDereference, WalkPanicError } from './syntax-walk-errors.js';
+export { WalkPanicError } from './syntax-walk-errors.js';
+/**
+ * Walks synchronously using the pinned upstream case ordering. Each accepted entry is followed by its
+ * children and a null exit. Returning false prunes the entry without an exit;
+ * boolean exit return values are ignored. Every callback must return a boolean
+ * synchronously; other results produce InputError. Callback exceptions retain their identity,
+ * and upstream deferred comment callbacks still run during exception unwinding.
+ *
+ * Children and later fields are read live. Each list captures its array reference
+ * and length when traversal reaches that list, then reads existing later slots
+ * when reached. Replacing or reordering later slots is observed and can cause
+ * a node to be skipped or revisited. Indices added beyond the captured extent
+ * are not visited by that active list. Replacing the owner's array field does not
+ * redirect an active list, but a later walk or print sees the current field.
+ * Changes made before a list is reached are observed when it starts.
+ *
+ * Supported edits preserve each node's Type (and TypedNil.Kind), required field
+ * shapes and every index within each active list's captured extent. Leaving
+ * holes or shrinking an array below that extent (for example through truncation,
+ * deletion, or length-reducing splice/shift) is outside the mutation contract.
+ * These are not runtime validation rules. Ordinary JavaScript object and array
+ * aliases remain shared; the binding does not model distinct Go slice headers or
+ * capacity-dependent allocation over shared backing storage.
+ *
+ * Comments on Stmt, CaseItem and ArrayElem are copied before their callbacks,
+ * including position and byte-string values; editing a copy does not edit the
+ * stored comment. Last/CondLast/ThenLast/DoLast callbacks receive the stored
+ * JavaScript Comment object. Replacing its array slot leaves any previously
+ * retained callback object unchanged: there is no Go value-slot pointer identity.
+ * Reentrant walks maintain independent traversal state.
+ * @public
+ */
+export function walk(node, callback) {
+    visit(node, callback);
+}
+/**
+ * Calls user code without intercepting its exceptions, then enforces Go's bool
+ * return domain before traversal can consume the result. Exit results share
+ * that domain even though their boolean values do not control traversal.
+ */
+function invokeCallback(node, callback) {
+    const result = callback(node);
+    if (typeof result !== 'boolean') {
+        throw new InputError('Walk callbacks must return a boolean synchronously');
+    }
+    return result;
+}
+/** An unconditional concrete-pointer child is observable even when the pointer is nil. */
+function pointer(node, kind, callback) {
+    visit(node ?? { Type: 'TypedNil', Kind: kind }, callback);
+}
+/** Optional fields skip null; a typed-nil interface is nevertheless a non-null interface. */
+function optional(node, callback) {
+    if (node !== null) {
+        visit(node, callback);
+    }
+}
+/**
+ * Captures one ordinary array and its initial extent when this list is reached.
+ * Later existing slots are read live; appends and owner-field replacements cannot
+ * extend or redirect the active list. Removing indices within its captured
+ * extent is unsupported.
+ */
+function list(nodes, kind, callback) {
+    if (nodes === null) {
+        return;
+    }
+    const length = nodes.length;
+    for (let index = 0; index < length; index++) {
+        const node = nodes[index] ?? null;
+        if (kind === null) {
+            visit(node, callback);
+        }
+        else {
+            pointer(node, kind, callback);
+        }
+    }
+}
+/**
+ * Visits stored JavaScript Comment objects, unlike the copies used by item loops.
+ * Later slot replacement is read live, but retained objects do not become Go
+ * pointers to replacement values. The active array and extent remain captured.
+ */
+function comments(nodes, callback) {
+    if (nodes === null) {
+        return;
+    }
+    const length = nodes.length;
+    for (let index = 0; index < length; index++) {
+        pointer(nodes[index] ?? null, 'Comment', callback);
+    }
+}
+/** Auxiliary pointers are reread after callbacks may replace or clear their owner field. */
+function dereference(value) {
+    if (value === null) {
+        return nilDereference();
+    }
+    return value;
+}
+/** Go copies a Comment's position and immutable string value before its callback. */
+function copyComment(node) {
+    return {
+        Type: 'Comment',
+        Hash: { ...node.Hash },
+        Text: typeof node.Text === 'string' ? node.Text : node.Text.slice(),
+    };
+}
+/**
+ * A single defer belongs to this occurrence. The try/finally surrounds all child
+ * work and the null exit, preserving Go's unwind order and replacement exception.
+ */
+function visit(node, callback) {
+    if (!invokeCallback(node, callback)) {
+        return;
+    }
+    if (node === null) {
+        throw new WalkPanicError('syntax.Walk: unexpected node type <nil>');
+    }
+    if (node.Type === 'TypedNil') {
+        if (node.Kind === 'BraceExp') {
+            throw new WalkPanicError('syntax.Walk: unexpected node type *syntax.BraceExp');
+        }
+        if (node.Kind !== 'Lit' && node.Kind !== 'Comment' && node.Kind !== 'SglQuoted') {
+            nilDereference();
+        }
+        invokeCallback(null, callback);
+        return;
+    }
+    let deferred;
+    try {
+        switch (node.Type) {
+            case 'File':
+                list(node.Stmts, 'Stmt', callback);
+                comments(node.Last, callback);
+                break;
+            case 'Comment':
+            case 'Lit':
+            case 'SglQuoted':
+                break;
+            case 'Stmt': {
+                const values = node.Comments;
+                const length = values?.length ?? 0;
+                for (let index = 0; values !== null && index < length; index++) {
+                    const value = copyComment(values[index]);
+                    if (atStatementEnd(node, value.Hash)) {
+                        deferred = value;
+                        break;
+                    }
+                    visit(value, callback);
+                }
+                optional(node.Cmd, callback);
+                list(node.Redirs, 'Redirect', callback);
+                break;
+            }
+            case 'Assign':
+                optional(node.Name, callback);
+                optional(node.Value, callback);
+                optional(node.Index, callback);
+                optional(node.Array, callback);
+                break;
+            case 'Redirect':
+                optional(node.N, callback);
+                pointer(node.Word, 'Word', callback);
+                optional(node.Hdoc, callback);
+                break;
+            case 'CallExpr':
+                list(node.Assigns, 'Assign', callback);
+                list(node.Args, 'Word', callback);
+                break;
+            case 'Subshell':
+            case 'Block':
+            case 'CmdSubst':
+            case 'ProcSubst':
+                list(node.Stmts, 'Stmt', callback);
+                comments(node.Last, callback);
+                break;
+            case 'IfClause':
+                list(node.Cond, 'Stmt', callback);
+                comments(node.CondLast, callback);
+                list(node.Then, 'Stmt', callback);
+                comments(node.ThenLast, callback);
+                optional(node.Else, callback);
+                break;
+            case 'WhileClause':
+                list(node.Cond, 'Stmt', callback);
+                comments(node.CondLast, callback);
+                list(node.Do, 'Stmt', callback);
+                comments(node.DoLast, callback);
+                break;
+            case 'ForClause':
+                visit(node.Loop, callback);
+                list(node.Do, 'Stmt', callback);
+                comments(node.DoLast, callback);
+                break;
+            case 'WordIter':
+                pointer(node.Name, 'Lit', callback);
+                list(node.Items, 'Word', callback);
+                break;
+            case 'CStyleLoop':
+                optional(node.Init, callback);
+                optional(node.Cond, callback);
+                optional(node.Post, callback);
+                break;
+            case 'BinaryCmd':
+                pointer(node.X, 'Stmt', callback);
+                pointer(node.Y, 'Stmt', callback);
+                break;
+            case 'FuncDecl':
+                optional(node.Name, callback);
+                list(node.Names, 'Lit', callback);
+                pointer(node.Body, 'Stmt', callback);
+                break;
+            case 'Word':
+            case 'DblQuoted':
+                list(node.Parts, null, callback);
+                break;
+            case 'ParamExp':
+                optional(node.Flags, callback);
+                optional(node.Param, callback);
+                optional(node.NestedParam, callback);
+                optional(node.Index, callback);
+                if (node.Slice !== null) {
+                    optional(node.Slice.Offset, callback);
+                    optional(dereference(node.Slice).Length, callback);
+                }
+                if (node.Repl !== null) {
+                    optional(node.Repl.Orig, callback);
+                    optional(dereference(node.Repl).With, callback);
+                }
+                if (node.Exp !== null) {
+                    optional(node.Exp.Word, callback);
+                }
+                break;
+            case 'ArithmExp':
+            case 'ArithmCmd':
+            case 'UnaryArithm':
+            case 'UnaryTest':
+            case 'ParenArithm':
+            case 'ParenTest':
+            case 'TestClause':
+                visit(node.X, callback);
+                break;
+            case 'BinaryArithm':
+            case 'BinaryTest':
+                visit(node.X, callback);
+                visit(node.Y, callback);
+                break;
+            case 'FlagsArithm':
+                pointer(node.Flags, 'Lit', callback);
+                optional(node.X, callback);
+                break;
+            case 'CaseClause':
+                pointer(node.Word, 'Word', callback);
+                list(node.Items, 'CaseItem', callback);
+                comments(node.Last, callback);
+                break;
+            case 'CaseItem':
+            case 'ArrayElem': {
+                const values = node.Comments;
+                const length = values?.length ?? 0;
+                for (let index = 0; values !== null && index < length; index++) {
+                    const value = copyComment(values[index]);
+                    if (afterItemStart(node, value.Hash)) {
+                        deferred = value;
+                        break;
+                    }
+                    visit(value, callback);
+                }
+                if (node.Type === 'CaseItem') {
+                    list(node.Patterns, 'Word', callback);
+                    list(node.Stmts, 'Stmt', callback);
+                    comments(node.Last, callback);
+                }
+                else {
+                    optional(node.Index, callback);
+                    optional(node.Value, callback);
+                }
+                break;
+            }
+            case 'DeclClause':
+                list(node.Args, 'Assign', callback);
+                break;
+            case 'ArrayExpr':
+                list(node.Elems, 'ArrayElem', callback);
+                comments(node.Last, callback);
+                break;
+            case 'ExtGlob':
+                pointer(node.Pattern, 'Lit', callback);
+                break;
+            case 'TimeClause':
+                optional(node.Stmt, callback);
+                break;
+            case 'CoprocClause':
+                optional(node.Name, callback);
+                pointer(node.Stmt, 'Stmt', callback);
+                break;
+            case 'LetClause':
+                list(node.Exprs, null, callback);
+                break;
+            case 'TestDecl':
+                pointer(node.Description, 'Word', callback);
+                pointer(node.Body, 'Stmt', callback);
+                break;
+            case 'BraceExp':
+                throw new WalkPanicError('syntax.Walk: unexpected node type *syntax.BraceExp');
+            default: {
+                const exhaustive = node;
+                throw new WalkPanicError(`syntax.Walk: unexpected node type ${String(exhaustive)}`);
+            }
+        }
+        invokeCallback(null, callback);
+    }
+    finally {
+        if (deferred !== undefined) {
+            visit(deferred, callback);
+        }
+    }
+}
+//# sourceMappingURL=syntax-walk.js.map

package/dist/syntax-walk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syntax-walk.js","sourceRoot":"","sources":["../src/syntax-walk.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAOzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,IAAI,CAAC,IAAU,EAAE,QAAwC;IACvE,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AACxB,CAAC;AAED;;;;GAIG;AACH,SAAS,cAAc,CAAC,IAAiB,EAAE,QAAmB;IAC5D,MAAM,MAAM,GAAY,QAAQ,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,OAAO,MAAM,KAAK,SAAS,EAAE,CAAC;QAChC,MAAM,IAAI,UAAU,CAAC,oDAAoD,CAAC,CAAC;IAC7E,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,0FAA0F;AAC1F,SAAS,OAAO,CAAC,IAAiB,EAAE,IAAmB,EAAE,QAAmB;IAC1E,KAAK,CAAC,IAAI,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,QAAQ,CAAC,CAAC;AAC5D,CAAC;AACD,6FAA6F;AAC7F,SAAS,QAAQ,CAAC,IAAiB,EAAE,QAAmB;IACtD,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACxB,CAAC;AACH,CAAC;AACD;;;;;GAKG;AACH,SAAS,IAAI,CACX,KAAsC,EACtC,IAA0B,EAC1B,QAAmB;IAEnB,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,OAAO;IACT,CAAC;IACD,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC5B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;QAC5C,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC;QAClC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACxB,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;AACH,CAAC;AACD;;;;GAIG;AACH,SAAS,QAAQ,CAAC,KAAgC,EAAE,QAAmB;IACrE,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,OAAO;IACT,CAAC;IACD,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC5B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;QAC5C,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;IACrD,CAAC;AACH,CAAC;AACD,4FAA4F;AAC5F,SAAS,WAAW,CAAI,KAAe;IACrC,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,OAAO,cAAc,EAAE,CAAC;IAC1B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AACD,qFAAqF;AACrF,SAAS,WAAW,CAAC,IAAa;IAChC,OAAO;QACL,IAAI,EAAE,SAAS;QACf,IAAI,EAAE,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE;QACtB,IAAI,EAAE,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE;KACpE,CAAC;AACJ,CAAC;AACD;;;GAGG;AACH,SAAS,KAAK,CAAC,IAAiB,EAAE,QAAmB;IACnD,IAAI,CAAC,cAAc,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,CAAC;QACpC,OAAO;IACT,CAAC;IACD,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,MAAM,IAAI,cAAc,CAAC,yCAAyC,CAAC,CAAC;IACtE,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC7B,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YAC7B,MAAM,IAAI,cAAc,CAAC,oDAAoD,CAAC,CAAC;QACjF,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YAChF,cAAc,EAAE,CAAC;QACnB,CAAC;QACD,cAAc,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAC/B,OAAO;IACT,CAAC;IACD,IAAI,QAA6B,CAAC;IAClC,IAAI,CAAC;QACH,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;YAClB,KAAK,MAAM;gBACT,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;gBACnC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;gBAC9B,MAAM;YACR,KAAK,SAAS,CAAC;YACf,KAAK,KAAK,CAAC;YACX,KAAK,WAAW;gBACd,MAAM;YACR,KAAK,MAAM,CAAC,CAAC,CAAC;gBACZ,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC;gBAC7B,MAAM,MAAM,GAAG,MAAM,EAAE,MAAM,IAAI,CAAC,CAAC;gBACnC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,MAAM,KAAK,IAAI,IAAI,KAAK,GAAG,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;oBAC/D,MAAM,KAAK,GAAG,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;oBACzC,IAAI,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;wBACrC,QAAQ,GAAG,KAAK,CAAC;wBACjB,MAAM;oBACR,CAAC;oBACD,KAAK,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;gBACzB,CAAC;gBACD,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;gBAC7B,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC;gBACxC,MAAM;YACR,CAAC;YACD,KAAK,QAAQ;gBACX,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;gBAC9B,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;gBAC/B,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;gBAC/B,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;gBAC/B,MAAM;YACR,KAAK,UAAU;gBACb,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;gBAC3B,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;gBACrC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;gBAC9B,MAAM;YACR,KAAK,UAAU;gBACb,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;gBACvC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;gBAClC,MAAM;YACR,KAAK,UAAU,CAAC;YAChB,KAAK,OAAO,CAAC;YACb,KAAK,UAAU,CAAC;YAChB,KAAK,WAAW;gBACd,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;gBACnC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;gBAC9B,MAAM;YACR,KAAK,UAAU;gBACb,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;gBAClC,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;gBAClC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;gBAClC,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;gBAClC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;gBAC9B,MAAM;YACR,KAAK,aAAa;gBAChB,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;gBAClC,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;gBAClC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;gBAChC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;gBAChC,MAAM;YACR,KAAK,WAAW;gBACd,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;gBAC3B,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;gBAChC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;gBAChC,MAAM;YACR,KAAK,UAAU;gBACb,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;gBACpC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;gBACnC,MAAM;YACR,KAAK,YAAY;gBACf,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;gBAC9B,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;gBAC9B,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;gBAC9B,MAAM;YACR,KAAK,WAAW;gBACd,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;gBAClC,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;gBAClC,MAAM;YACR,KAAK,UAAU;gBACb,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;gBAC9B,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;gBAClC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;gBACrC,MAAM;YACR,KAAK,MAAM,CAAC;YACZ,KAAK,WAAW;gBACd,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;gBACjC,MAAM;YACR,KAAK,UAAU;gBACb,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;gBAC/B,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;gBAC/B,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;gBACrC,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;gBAC/B,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;oBACxB,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;oBACtC,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;gBACrD,CAAC;gBACD,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;oBACvB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;oBACnC,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;gBAClD,CAAC;gBACD,IAAI,IAAI,CAAC,GAAG,KAAK,IAAI,EAAE,CAAC;oBACtB,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;gBACpC,CAAC;gBACD,MAAM;YACR,KAAK,WAAW,CAAC;YACjB,KAAK,WAAW,CAAC;YACjB,KAAK,aAAa,CAAC;YACnB,KAAK,WAAW,CAAC;YACjB,KAAK,aAAa,CAAC;YACnB,KAAK,WAAW,CAAC;YACjB,KAAK,YAAY;gBACf,KAAK,CAAC,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;gBACxB,MAAM;YACR,KAAK,cAAc,CAAC;YACpB,KAAK,YAAY;gBACf,KAAK,CAAC,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;gBACxB,KAAK,CAAC,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;gBACxB,MAAM;YACR,KAAK,aAAa;gBAChB,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;gBACrC,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;gBAC3B,MAAM;YACR,KAAK,YAAY;gBACf,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;gBACrC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC;gBACvC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;gBAC9B,MAAM;YACR,KAAK,UAAU,CAAC;YAChB,KAAK,WAAW,CAAC,CAAC,CAAC;gBACjB,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC;gBAC7B,MAAM,MAAM,GAAG,MAAM,EAAE,MAAM,IAAI,CAAC,CAAC;gBACnC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,MAAM,KAAK,IAAI,IAAI,KAAK,GAAG,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;oBAC/D,MAAM,KAAK,GAAG,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;oBACzC,IAAI,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;wBACrC,QAAQ,GAAG,KAAK,CAAC;wBACjB,MAAM;oBACR,CAAC;oBACD,KAAK,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;gBACzB,CAAC;gBACD,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;oBAC7B,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;oBACtC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;oBACnC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;gBAChC,CAAC;qBAAM,CAAC;oBACN,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;oBAC/B,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;gBACjC,CAAC;gBACD,MAAM;YACR,CAAC;YACD,KAAK,YAAY;gBACf,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;gBACpC,MAAM;YACR,KAAK,WAAW;gBACd,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC;gBACxC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;gBAC9B,MAAM;YACR,KAAK,SAAS;gBACZ,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;gBACvC,MAAM;YACR,KAAK,YAAY;gBACf,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;gBAC9B,MAAM;YACR,KAAK,cAAc;gBACjB,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;gBAC9B,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;gBACrC,MAAM;YACR,KAAK,WAAW;gBACd,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;gBACjC,MAAM;YACR,KAAK,UAAU;gBACb,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;gBAC5C,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;gBACrC,MAAM;YACR,KAAK,UAAU;gBACb,MAAM,IAAI,cAAc,CAAC,oDAAoD,CAAC,CAAC;YACjF,OAAO,CAAC,CAAC,CAAC;gBACR,MAAM,UAAU,GAAU,IAAI,CAAC;gBAC/B,MAAM,IAAI,cAAc,CAAC,qCAAqC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;YACtF,CAAC;QACH,CAAC;QACD,cAAc,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACjC,CAAC;YAAS,CAAC;QACT,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,KAAK,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/syntax-wire.d.ts

@@ -0,0 +1,31 @@
+import type { File, GoString, Node, SyntaxPos } from '../generated/syntax-types.js';
+/** Values after JSON parsing have no inherited application behavior. @internal */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * Rejects unpaired UTF-16 surrogates before TextEncoder can replace them. Callers
+ * with source bytes use Uint8Array and receive the upstream byte-input behavior.
+ * @internal
+ */
+export declare function assertUnicodeString(value: string): void;
+/**
+ * Encodes bytes and exact integers without relying on JSON's number precision or
+ * Uint8Array property enumeration. Circular input is a caller error, not a stack
+ * overflow or a partially transferred request.
+ * @internal
+ */
+export declare function encodeWire(value: unknown): string;
+/**
+ * Restores byte-bearing Go values. Ordinary syntax fields retain their spelling,
+ * nulls, defaults, and ordering; no source location or synthetic node is added.
+ * @internal
+ */
+export declare function decodeWire(text: string): unknown;
+/** A Go string is text only when every original byte is valid UTF-8. @internal */
+export declare function isGoString(value: unknown): value is GoString;
+/** Checks the observable uint32-backed position shape without inventing bounds. @internal */
+export declare function isSyntaxPos(value: unknown): value is SyntaxPos;
+/** Narrows complete syntax.Nodes or typed nil Node interfaces; auxiliaries are excluded. @internal */
+export declare function isSyntaxNode(value: unknown): value is Node;
+/** The public parser's root is the precise upstream File representation. @internal */
+export declare function isSyntaxFile(value: unknown): value is File;
+//# sourceMappingURL=syntax-wire.d.ts.map

package/dist/syntax-wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"syntax-wire.d.ts","sourceRoot":"","sources":["../src/syntax-wire.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAEpF,kFAAkF;AAClF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CASvD;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAgCjD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAmBhD;AAED,kFAAkF;AAClF,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D;AAED,6FAA6F;AAC7F,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAwB9D;AA4ED,sGAAsG;AACtG,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,IAAI,CAS1D;AAED,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,IAAI,CAE1D"}

package/dist/syntax-wire.js

@@ -0,0 +1,202 @@
+/**
+ * Lossless JSON adaptation at the JS/Go boundary. Go strings are byte sequences;
+ * integer arguments may span 64 bits. Tagged encodings preserve those domains
+ * without changing the public syntax records into a second tree model.
+ */
+import { InputError } from './syntax-errors.js';
+import { ShInternalError } from './errors.js';
+import { SYNTAX_INTERFACES, SYNTAX_SCHEMA, } from '../generated/syntax-schema.js';
+/** Values after JSON parsing have no inherited application behavior. @internal */
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Rejects unpaired UTF-16 surrogates before TextEncoder can replace them. Callers
+ * with source bytes use Uint8Array and receive the upstream byte-input behavior.
+ * @internal
+ */
+export function assertUnicodeString(value) {
+    for (const character of value) {
+        const point = character.codePointAt(0);
+        if (point !== undefined && point >= 0xd800 && point <= 0xdfff) {
+            throw new InputError('A string contains an unpaired UTF-16 surrogate; supply exact bytes instead');
+        }
+    }
+}
+/**
+ * Encodes bytes and exact integers without relying on JSON's number precision or
+ * Uint8Array property enumeration. Circular input is a caller error, not a stack
+ * overflow or a partially transferred request.
+ * @internal
+ */
+export function encodeWire(value) {
+    const ancestors = new Set();
+    const visit = (item) => {
+        if (typeof item === 'string') {
+            assertUnicodeString(item);
+            return item;
+        }
+        if (typeof item === 'bigint')
+            return { Int: item.toString() };
+        if (item instanceof Uint8Array)
+            return { Bytes: Buffer.from(item).toString('base64') };
+        if (item === null || typeof item === 'boolean')
+            return item;
+        if (typeof item === 'number') {
+            if (!Number.isSafeInteger(item))
+                throw new InputError('Numeric values must be safe integers; use bigint for 64-bit arguments');
+            return item;
+        }
+        if (typeof item !== 'object')
+            throw new InputError('Syntax wire values must be data records, arrays, bytes, or scalar values');
+        if (ancestors.has(item))
+            throw new InputError('Syntax records cannot contain cycles');
+        ancestors.add(item);
+        try {
+            if (Array.isArray(item))
+                return item.map(visit);
+            if (!isRecord(item))
+                throw new InputError('Expected a syntax data record');
+            return Object.fromEntries(Object.entries(item).map(([key, child]) => [key, visit(child)]));
+        }
+        finally {
+            ancestors.delete(item);
+        }
+    };
+    return JSON.stringify(visit(value));
+}
+/**
+ * Restores byte-bearing Go values. Ordinary syntax fields retain their spelling,
+ * nulls, defaults, and ordering; no source location or synthetic node is added.
+ * @internal
+ */
+export function decodeWire(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (cause) {
+        throw new ShInternalError(`Invalid syntax bridge JSON: ${String(cause)}`);
+    }
+    const visit = (item) => {
+        if (Array.isArray(item))
+            return item.map(visit);
+        if (!isRecord(item))
+            return item;
+        if (Object.keys(item).length === 1 && typeof item.Bytes === 'string') {
+            const bytes = Buffer.from(item.Bytes, 'base64');
+            if (bytes.toString('base64') !== item.Bytes)
+                throw new ShInternalError('Invalid base64 in syntax bridge response');
+            return new Uint8Array(bytes);
+        }
+        return Object.fromEntries(Object.entries(item).map(([key, child]) => [key, visit(child)]));
+    };
+    return visit(parsed);
+}
+/** A Go string is text only when every original byte is valid UTF-8. @internal */
+export function isGoString(value) {
+    return typeof value === 'string' || value instanceof Uint8Array;
+}
+/** Checks the observable uint32-backed position shape without inventing bounds. @internal */
+export function isSyntaxPos(value) {
+    if (!isRecord(value))
+        return false;
+    const uint = (item, maximum) => typeof item === 'number' && Number.isInteger(item) && item >= 0 && item <= maximum;
+    const shape = Object.keys(value).length === 6 &&
+        uint(value.Offset, 0xffff_ffff - 11) &&
+        uint(value.Line, 0x3_ffff) &&
+        uint(value.Col, 0x3fff) &&
+        typeof value.IsValid === 'boolean' &&
+        typeof value.IsRecovered === 'boolean' &&
+        typeof value.OffsetOverflow === 'boolean';
+    if (!shape)
+        return false;
+    if (value.IsRecovered) {
+        return (value.OffsetOverflow === true &&
+            value.IsValid === false &&
+            value.Offset === 0 &&
+            value.Line === 0 &&
+            value.Col === 0);
+    }
+    if (value.OffsetOverflow)
+        return value.IsValid === false && value.Offset === 0;
+    return value.IsValid === (value.Line !== 0 || value.Col !== 0);
+}
+/**
+ * A Go interface can hold a nil pointer with a concrete dynamic type. Its tag
+ * preserves that type without inventing fields for a nonexistent record.
+ */
+function isTypedNil(value, implementers) {
+    return (isRecord(value) &&
+        value.Type === 'TypedNil' &&
+        typeof value.Kind === 'string' &&
+        Object.keys(value).length === 2 &&
+        implementers.includes(value.Kind));
+}
+/**
+ * Validates complete records against the pinned schema, including nil-bearing
+ * boundaries. This is a boundary check, not a semantic shell interpretation.
+ */
+function matchesRecord(value, active) {
+    if (!isRecord(value) || typeof value.Type !== 'string' || active.has(value))
+        return false;
+    if (!Object.hasOwn(SYNTAX_SCHEMA, value.Type))
+        return false;
+    const descriptor = SYNTAX_SCHEMA[value.Type];
+    if (Object.keys(value).length !== Object.keys(descriptor.fields).length + 1)
+        return false;
+    active.add(value);
+    try {
+        return Object.entries(descriptor.fields).every(([name, field]) => Object.hasOwn(value, name) && matchesField(value[name], field, active));
+    }
+    finally {
+        active.delete(value);
+    }
+}
+/** Checks one upstream field without conflating a nil slice with an empty one. */
+function matchesField(value, field, active) {
+    if (value === null)
+        return field.nullable;
+    if (field.slice) {
+        return (Array.isArray(value) &&
+            value.every((item) => item === null ? field.elementNullable : matchesScalar(item, field, active)));
+    }
+    return matchesScalar(value, field, active);
+}
+/** Each scalar category retains its upstream domain rather than JS coercions. */
+function matchesScalar(value, field, active) {
+    switch (field.kind) {
+        case 'boolean':
+            return typeof value === 'boolean';
+        case 'string':
+            return isGoString(value);
+        case 'position':
+            return isSyntaxPos(value);
+        case 'operator':
+            return (typeof value === 'number' && Number.isInteger(value) && value >= 0 && value <= 0xffff_ffff);
+        case 'struct':
+            return isRecord(value) && value.Type === field.type && matchesRecord(value, active);
+        case 'interface':
+            return (isRecord(value) &&
+                typeof value.Type === 'string' &&
+                field.type !== null &&
+                Object.hasOwn(SYNTAX_INTERFACES, field.type) &&
+                (isTypedNil(value, SYNTAX_INTERFACES[field.type]) ||
+                    (SYNTAX_INTERFACES[field.type].includes(value.Type) && matchesRecord(value, active))));
+    }
+}
+/** Narrows complete syntax.Nodes or typed nil Node interfaces; auxiliaries are excluded. @internal */
+export function isSyntaxNode(value) {
+    if (isTypedNil(value, SYNTAX_INTERFACES.Node))
+        return true;
+    return (isRecord(value) &&
+        typeof value.Type === 'string' &&
+        Object.hasOwn(SYNTAX_SCHEMA, value.Type) &&
+        SYNTAX_SCHEMA[value.Type].node &&
+        matchesRecord(value, new Set()));
+}
+/** The public parser's root is the precise upstream File representation. @internal */
+export function isSyntaxFile(value) {
+    return isSyntaxNode(value) && value.Type === 'File';
+}
+//# sourceMappingURL=syntax-wire.js.map

package/dist/syntax-wire.js.map

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

package/dist/syntax.d.ts

@@ -0,0 +1,65 @@
+import type { OperatorFamily, RawOperator } from '../generated/syntax-constants.js';
+import type { File, GoString, Node, SyntaxPos } from '../generated/syntax-types.js';
+import { type ParsedFile } from './syntax-snapshot.js';
+export type { ParsedFile, PositionSnapshot, NodePositions } from './syntax-snapshot.js';
+export { InputError, LangError, ParseError } from './syntax-errors.js';
+/**
+ * Whole-file parser inputs corresponding to upstream controls. Defaults match
+ * NewParser; in particular comments are retained only when KeepComments is true.
+ * Numeric int arguments accept bigint because Go's WASM int is signed 64-bit.
+ * @public
+ */
+export interface ParseOptions {
+    /** Source identity carried by File/errors; no file is opened by the binding. */
+    Filename?: GoString;
+    /** Retains comment nodes when true; upstream defaults to false. */
+    KeepComments?: boolean;
+    /** Upstream LangVariant value. Variant rejects unsupported values, including LangAuto. */
+    Variant?: number | bigint;
+    /** Lexer delimiter with upstream byte-length, whitespace and prefix semantics. */
+    StopAt?: GoString;
+    /** Maximum number of recoverable missing grammar tokens, using upstream behavior. */
+    RecoverErrors?: number | bigint;
+}
+/**
+ * Parses exact source bytes, or well-formed Unicode text encoded as UTF-8. First
+ * use synchronously initializes WASM. The existing conservative nesting guard is
+ * an explicit binding resource limit, not an upstream grammar restriction.
+ * @public
+ */
+export declare function parseSync(source: string | Uint8Array, options?: ParseOptions): File;
+/**
+ * Parses once while observing every real node's upstream bounds in Go. The
+ * separate immutable lookup describes this original parse; it never replaces
+ * live nodePos/nodeEnd or tracks edits. Source adapters avoid reconstructing
+ * each descendant subtree just to display the original source locations.
+ * @public
+ */
+export declare function parseWithPositionsSync(source: string | Uint8Array, options?: ParseOptions): ParsedFile;
+/**
+ * Computes a node's starting position from its current fields using upstream's
+ * Pos method. No cached parse-time position can override subsequent tree edits.
+ * @public
+ */
+export declare function nodePos(node: Node): SyntaxPos;
+/**
+ * Computes a node's ending position using upstream's End method, including
+ * recovered/invalid behavior and changes to text or child nodes.
+ * @public
+ */
+export declare function nodeEnd(node: Node): SyntaxPos;
+/**
+ * Constructs an upstream position. uint64 arguments use bigint when outside the
+ * safe-number range; upstream clamps offsets and zeroes overflowing line/column
+ * values. The binding does not replace those rules with its own range policy.
+ * @public
+ */
+export declare function newPos(offset: number | bigint, line: number | bigint, column: number | bigint): SyntaxPos;
+/**
+ * Represents an unnamed value in an upstream uint32 operator family. Named
+ * constants remain precise literal unions; this explicit path preserves other Go
+ * values without claiming an operation such as Print accepts them.
+ * @public
+ */
+export declare function rawOperator<Family extends OperatorFamily>(family: Family, value: number): RawOperator<Family>;
+//# sourceMappingURL=syntax.d.ts.map

package/dist/syntax.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"syntax.d.ts","sourceRoot":"","sources":["../src/syntax.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AACpF,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAepF,OAAO,EAA0B,KAAK,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAC/E,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAExF,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEvE;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,gFAAgF;IAChF,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,mEAAmE;IACnE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B,kFAAkF;IAClF,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,qFAAqF;IACrF,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACjC;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,EAAE,OAAO,GAAE,YAAiB,GAAG,IAAI,CAEvF;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,GAAG,UAAU,EAC3B,OAAO,GAAE,YAAiB,GACzB,UAAU,CAGZ;AAwBD;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,CAE7C;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,CAE7C;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CACpB,MAAM,EAAE,MAAM,GAAG,MAAM,EACvB,IAAI,EAAE,MAAM,GAAG,MAAM,EACrB,MAAM,EAAE,MAAM,GAAG,MAAM,GACtB,SAAS,CAQX;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,SAAS,cAAc,EACvD,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,WAAW,CAAC,MAAM,CAAC,CAarB"}