yuku-parser 0.5.14 → 0.5.16

package/README.md

@@ -15,8 +15,7 @@ import { parse } from "yuku-parser";
 
 const result = parse("const x = 1 + 2;");
 
-console.log(result.program); // ESTree / TypeScript-ESTree Program node
-console.log(result.comments); // all comments
+console.log(result.program);     // ESTree / TypeScript-ESTree Program node
 console.log(result.diagnostics); // errors and warnings
 ```
 
@@ -26,10 +25,15 @@ For JavaScript and JSX, the AST is fully conformant with the [ESTree](https://gi
 
 For TypeScript, the AST conforms to the [TypeScript-ESTree](https://www.npmjs.com/package/@typescript-eslint/typescript-estree) format used by `@typescript-eslint`.
 
-The only differences from the base ESTree / TypeScript-ESTree specifications are:
+Yuku also matches [Oxc](https://oxc.rs) for both JS and TS, with two intentional deviations from the base specs:
 
-- Support for Stage 3 [decorators](https://github.com/tc39/proposal-decorators).
-- Support for Stage 3 [import defer](https://github.com/tc39/proposal-defer-import-eval) and [import source](https://github.com/tc39/proposal-source-phase-imports). Dynamic forms (`import.defer(...)`, `import.source(...)`) are represented as an `ImportExpression` with a `phase` field set to `"defer"` or `"source"`, following the ESTree convention.
+- **Comments are attached to the AST nodes they belong to** rather than exposed as a separate offset-indexed array. See [Comments](#comments) for why.
+- **`Identifier` carries a `kind` field** (`"reference" | "binding" | "name" | "label" | "this"`) naming its role in the tree. ESTree collapses these distinct roles onto one `Identifier` type, so consumers normally have to walk the parent context to tell them apart. The parser already knows which is which, so it surfaces the answer as a free field.
+
+On top of the base specs, the AST also carries:
+
+- Stage 3 [decorators](https://github.com/tc39/proposal-decorators).
+- Stage 3 [import defer](https://github.com/tc39/proposal-defer-import-eval) and [import source](https://github.com/tc39/proposal-source-phase-imports). Dynamic forms (`import.defer(...)`, `import.source(...)`) are represented as an `ImportExpression` with a `phase` field set to `"defer"` or `"source"`, following the ESTree convention.
 - A non-standard `hashbang` field on `Program` for `#!/usr/bin/env node` lines.
 
 Any other deviation from Acorn's ESTree or `@typescript-eslint`'s TypeScript-ESTree would be considered a bug.
@@ -51,24 +55,26 @@ Two small helpers are exported for resolving the `lang` and `sourceType` options
 ```ts
 import { langFromPath, sourceTypeFromPath } from "yuku-parser";
 
-langFromPath("foo.tsx"); // "tsx"
-langFromPath("types.d.ts"); // "dts"
-sourceTypeFromPath("foo.cjs"); // "script"
-sourceTypeFromPath("foo.mjs"); // "module"
+langFromPath("foo.tsx");           // "tsx"
+langFromPath("types.d.ts");        // "dts"
+sourceTypeFromPath("foo.cjs");     // "script"
+sourceTypeFromPath("foo.mjs");     // "module"
 ```
 
 ## Resolving offsets to `(line, column)`
 
-Nodes, comments, and diagnostics carry `start`/`end` offsets. To turn an offset into a `{ line, column }` pair, use `locOf` with `lineStarts` from the parse result:
+Nodes and diagnostics carry `start`/`end` offsets (UTF-16 code units). To turn an offset into a `{ line, column }` pair, call `locOf` on the parse result:
 
 ```ts
-import { parse, locOf } from "yuku-parser";
+import { parse } from "yuku-parser";
 
-const { program, lineStarts } = parse(source);
-const { line, column } = locOf(lineStarts, program.body[0].start);
+const result = parse(source);
+const { line, column } = result.locOf(result.program.body[0].start);
 ```
 
-Lines are 1-based and columns are 0-based, matching ESTree's `loc` convention. The lookup is an O(log n) binary search: tens of nanoseconds per call, well over 10M ops/s even on million-line files, so it's safe to call per node during a walk.
+Lines are 1-based and columns are 0-based, matching ESTree's `loc` convention. The lookup is an O(log n) binary search: tens of nanoseconds per call, safe to invoke per node during a walk.
+
+For bulk work — building your own line/column index, integrating with another source-map or diagnostics library, or skipping the per-call binary search — read `result.lineStarts` directly. It's a sorted array of UTF-16 offsets where each line begins: `lineStarts[i]` is the start of line `i + 1`. Decoded lazily on first access and cached.
 
 ## Walking the AST
 
@@ -104,6 +110,7 @@ const result = parse(source, {
   preserveParens: true,
   allowReturnOutsideFunction: false,
   semanticErrors: false,
+  attachComments: false,
 });
 ```
 
@@ -114,6 +121,7 @@ const result = parse(source, {
 | `preserveParens`             | `true`, `false`                           | `true`     | Keep `ParenthesizedExpression` nodes in the AST. When false, parentheses are stripped and only the inner expression is kept. |
 | `allowReturnOutsideFunction` | `true`, `false`                           | `false`    | Allow `return` statements outside of functions, at the top level.                                                            |
 | `semanticErrors`             | `true`, `false`                           | `false`    | Run semantic analysis and report semantic errors alongside syntax errors.                                                    |
+| `attachComments`             | `true`, `false`                           | `false`    | Collect comments and attach them to host AST nodes. See [Comments](#comments).                                               |
 
 ## Result
 
@@ -122,13 +130,13 @@ const result = parse(source, {
 ```ts
 interface ParseResult {
   program: Program;
-  comments: Comment[];
-  lineStarts: number[];
   diagnostics: Diagnostic[];
+  lineStarts: number[];
+  locOf(offset: number): { line: number; column: number };
 }
 ```
 
-The parser is error-tolerant, an AST is always produced even when diagnostics are present. `lineStarts` records the byte offset of every line in the source, useful for resolving spans to `(line, column)` pairs without rescanning.
+The parser is error-tolerant: an AST is always produced even when diagnostics are present.
 
 ### Diagnostics
 
@@ -153,22 +161,65 @@ const result = parse(`let x = 1; let x = 2;`, { semanticErrors: true });
 
 This incurs a very small performance overhead. If your build pipeline already handles semantic validation (e.g. through a linter or type checker), you can leave this off for faster parsing.
 
-### Comments
+## Comments
 
-Every entry in `result.comments` describes one source comment:
+Comments are attached to the AST node they sit next to. Enable collection with `attachComments`, then read them off any node:
+
+```js
+const { program } = parse(
+  `// header\nfunction foo() {} // trailing`,
+  { attachComments: true },
+);
+
+const fn = program.body[0];
+for (const c of fn.comments ?? []) {
+  console.log(c.position, c.type, c.value);
+}
+// before Line " header"
+// after  Line " trailing"
+```
+
+Each comment is:
 
 ```ts
 interface Comment {
   type: "Line" | "Block";
-  precededByNewline: boolean;
-  followedByNewline: boolean;
-  value: string; // text without the surrounding delimiters
-  start: number; // byte offset
-  end: number; // byte offset
+  position: "before" | "after" | "inside";
+  sameLine: boolean;
+  value: string; // body without delimiters
 }
 ```
 
-`precededByNewline` and `followedByNewline` capture line layout, useful for tools that need to reconstruct source positioning.
+`position` tells you where the comment sits relative to its host:
+
+- `"before"`: leading the host node.
+- `"after"`: trailing the host node.
+- `"inside"`: interior to an otherwise empty host, like `function f() { /* hi */ }`.
+
+`sameLine` is `true` when the comment shares a source line with the host's adjacent edge (host's start for `before`, host's end for `after`). For `inside` it is always `false`.
+
+When `attachComments` is disabled (the default), comments are skipped like whitespace and no `comments` field appears on any node.
+
+### Why comments are attached to nodes
+
+Comments are part of the source. Any tool that reads or rewrites code needs to know which comments belong with which node, and that link has to survive AST transforms. Yuku puts a single `comments` array on each node, with a `position` field on each comment (`"before"`, `"after"`, `"inside"`). It is the simplest shape that holds up under transforms and stays cheap to decode. Every other approach trades away one of those properties.
+
+**Flat offset-indexed array (ESTree default, Oxc).** A separate `comments: [...]` array on the parse result, sibling to the program, each entry pointing at a source range. Fine for read-only analysis. It falls apart the moment you transform the tree.
+
+- *Transforms desync the array.* Insert, delete, or move a node and every offset downstream of the edit is wrong. The comment that used to sit between `a` and `b` may now sit inside something unrelated, or hang in empty space between two nodes. Re-syncing means walking the entire array and rewriting offsets on every edit, and even then the meaning of "the comment between these two things" cannot really be preserved by offsets alone.
+- *Codegen cannot trust the offsets.* A printer takes whatever AST it is handed. With offset-based comments, a transformed AST will either print comments in the wrong places or drop them entirely. With attached comments, when you move a node its comments come with it. The printer reads them off `node.comments` and emits them next to the node, no reconciliation needed.
+- *Lookup is awkward.* "Give me the comments belonging to this node" with a flat array is a binary search at best and a linear scan at worst. `node.comments` is O(1) and always exact.
+
+**Parser returns a flat list, you attach on the JS side (Acorn).** Acorn's `onComment` option pushes every comment into an array you provide, and that is all it does. To get them onto AST nodes you have to run a separate JS pass like `escodegen.attachComments`, which walks the tree, scans the comment list alongside it, and tags each comment as leading or trailing on the nearest node. That work is unavoidable if you want to transform the tree, and doing it in JavaScript is slow. Yuku does the same attachment in Zig as part of the parse. On the 7.8 MB `typescript.js` (30k+ comments), turning `attachComments` on adds only around 4ms.
+
+**Three separate fields per node (Babel).** `leadingComments`, `trailingComments`, and `innerComments`. Same idea as Yuku, but split across three arrays. Two costs come with the split.
+
+- *Decode work.* Three fields per node means three slots to check, three potential array allocations, and roughly 3x the work on the JS side for the same information.
+- *Duplication.* A comment that sits between two nodes is the `trailingComments` of one and the `leadingComments` of the other. Transforms have to track both copies and keep them in sync.
+
+A single `comments` array with a `position` field carries the same meaning, with one entry per comment and one place to look.
+
+Even with `attachComments` enabled, Yuku still parses the same file roughly 4x faster than Babel does without comments attached at all. When the flag is off (the default), comments are skipped like whitespace and there is no attachment work at all.
 
 ## License
 

package/decode.js

@@ -13,7 +13,6 @@ const PROPERTY_KINDS = ["init", "get", "set"];
 const METHOD_KINDS = ["constructor", "method", "get", "set"];
 const FUNCTION_TYPES = ["FunctionDeclaration", "FunctionExpression", "TSDeclareFunction", "TSEmptyBodyFunctionExpression"];
 const CLASS_TYPES = ["ClassDeclaration", "ClassExpression"];
-const COMMENT_TYPES = ["Line", "Block"];
 const SEVERITY = ["error", "warning", "hint", "info"];
 const IMPORT_EXPORT_KINDS = ["value", "type"];
 const ACCESSIBILITY = [null, "public", "private", "protected"];
@@ -34,7 +33,9 @@ function buildPosMap(src, byteLen, startByte) {
   while (i < len) {
     if (i + 16 <= len) {
       let allAscii = true;
-      for (let k = 0; k < 16; k++) if (src.charCodeAt(i + k) >= 0x80) { allAscii = false; break; }
+      for (let k = 0; k < 16; k++) {
+        if (src.charCodeAt(i + k) >= 0x80) { allAscii = false; break; }
+      }
       if (allAscii) {
         for (let k = 0; k < 16; k++) m[bp + k] = u16p + k;
         bp += 16; u16p += 16; i += 16;
@@ -45,8 +46,14 @@ function buildPosMap(src, byteLen, startByte) {
     m[bp] = u16p;
     if (cu < 0x80) { bp++; u16p++; i++; }
     else if (cu < 0x800) { m[bp + 1] = u16p + 1; bp += 2; u16p++; i++; }
-    else if (cu < 0xD800 || cu >= 0xE000) { m[bp + 1] = u16p + 1; m[bp + 2] = u16p + 1; bp += 3; u16p++; i++; }
-    else { m[bp + 1] = u16p + 1; m[bp + 2] = u16p + 2; m[bp + 3] = u16p + 2; bp += 4; u16p += 2; i += 2; }
+    else if (cu < 0xD800 || cu >= 0xE000) {
+      m[bp + 1] = u16p + 1; m[bp + 2] = u16p + 1;
+      bp += 3; u16p++; i++;
+    }
+    else {
+      m[bp + 1] = u16p + 1; m[bp + 2] = u16p + 2; m[bp + 3] = u16p + 2;
+      bp += 4; u16p += 2; i += 2;
+    }
   }
   m[byteLen - startByte] = u16p;
   return m;
@@ -57,14 +64,26 @@ function decode(buffer, source) {
   const _u32 = new Int32Array(buffer, 0, aLen >> 2);
   const _src = source;
   const _srcLen = _u32[3];
-  const nodeCount = _u32[0], extraCount = _u32[1], spLen = _u32[2];
-  const commentCount = _u32[4], lineStartsCount = _u32[5], diagCount = _u32[6], progIdx = _u32[7];
-  const _isTs = !!(_u32[8] & 1);
+  const nodeCount = _u32[0],
+        extraCount = _u32[1],
+        spLen = _u32[2];
+  const commentCount = _u32[4],
+        lineStartsCount = _u32[5],
+        diagCount = _u32[6],
+        progIdx = _u32[7];
+  const _flags = _u32[8];
+  const _isTs = !!(_flags & 1);
+  const _attachComments = !!(_flags & 2);
   const _firstNa = _u32[9];
   const _nodesOff = 40;
   const eOff = _nodesOff + nodeCount * 48;
   const _extraBase = eOff >> 2;
   const _spOff = eOff + extraCount * 4;
+  // sections after the variable-length string pool may be at any
+  // byte alignment, so reads against them use `dv`, not `_u32`.
+  const dv = new DataView(buffer);
+  const _coOff = _spOff + spLen;
+  const _cOff = _attachComments ? _coOff + (nodeCount + 1) * 4 : _coOff;
   function _poolDecode(s, e) {
     const a = _spOff + s - _srcLen, b = _spOff + e - _srcLen;
     let hasEd = false;
@@ -74,9 +93,23 @@ function decode(buffer, source) {
     for (let i = a; i < b; ) {
       const c = _u8[i];
       if (c < 0x80) { r += String.fromCharCode(c); i++; }
-      else if (c < 0xE0) { r += String.fromCharCode(((c & 0x1F) << 6) | (_u8[i+1] & 0x3F)); i += 2; }
-      else if (c < 0xF0) { r += String.fromCharCode(((c & 0x0F) << 12) | ((_u8[i+1] & 0x3F) << 6) | (_u8[i+2] & 0x3F)); i += 3; }
-      else { r += String.fromCodePoint(((c & 0x07) << 18) | ((_u8[i+1] & 0x3F) << 12) | ((_u8[i+2] & 0x3F) << 6) | (_u8[i+3] & 0x3F)); i += 4; }
+      else if (c < 0xE0) {
+        r += String.fromCharCode(((c & 0x1F) << 6) | (_u8[i+1] & 0x3F));
+        i += 2;
+      }
+      else if (c < 0xF0) {
+        r += String.fromCharCode(
+          ((c & 0x0F) << 12) | ((_u8[i+1] & 0x3F) << 6) | (_u8[i+2] & 0x3F)
+        );
+        i += 3;
+      }
+      else {
+        r += String.fromCodePoint(
+          ((c & 0x07) << 18) | ((_u8[i+1] & 0x3F) << 12) |
+            ((_u8[i+2] & 0x3F) << 6) | (_u8[i+3] & 0x3F)
+        );
+        i += 4;
+      }
     }
     return r;
   }
@@ -106,7 +139,10 @@ function decode(buffer, source) {
   }
   function nodeArrHoles(s, len) {
     const r = new Array(len);
-    for (let j = 0; j < len; j++) { const x = _u32[_extraBase + s + j]; r[j] = x !== NULL ? node(x) : null; }
+    for (let j = 0; j < len; j++) {
+      const x = _u32[_extraBase + s + j];
+      r[j] = x !== NULL ? node(x) : null;
+    }
     return r;
   }
   function fnParams(idx) {
@@ -119,19 +155,77 @@ function decode(buffer, source) {
     if (rest !== NULL) p.push(node(rest));
     return p;
   }
-  function node(i) {
+  function _commentsOf(a, e) {
+    const out = new Array(e - a);
+    for (let j = a; j < e; j++) {
+      const o = _cOff + j * 12;
+      const cf = _u8[o + 0];
+      const vs = dv.getUint32(o + 4, true),
+            ve = dv.getUint32(o + 8, true);
+      out[j - a] = {
+        type: (cf & 1) ? "Block" : "Line",
+        position: ["before", "after", "inside"][(cf >> 1) & 3],
+        sameLine: (cf & 8) !== 0,
+        value: str(vs, ve),
+      };
+    }
+    return out;
+  }
+  function nodeWithComments(i) {
+    const r = _decode(i);
+    // skip unwrap cases whose inner node already carries its own
+    // comments (e.g. formal_parameter returning its pattern)
+    if (r && r.type !== undefined && r.comments === undefined) {
+      const off = _coOff + i * 4;
+      const a = dv.getUint32(off, true), e = dv.getUint32(off + 4, true);
+      if (a !== e) r.comments = _commentsOf(a, e);
+    }
+    return r;
+  }
+  function _decode(i) {
     const o = _nodesOff + i * 48;
     const tag = _u8[o];
     const flags = _u8[o + 2] | (_u8[o + 3] << 8);
     const f0 = _u8[o + 4] | (_u8[o + 5] << 8);
     const b = o >> 2;
-    const f1 = _u32[b + 2], f2 = _u32[b + 3], f3 = _u32[b + 4], f4 = _u32[b + 5], f5 = _u32[b + 6], f6 = _u32[b + 7], f7 = _u32[b + 8], f8 = _u32[b + 9];
+    const f1 = _u32[b + 2], f2 = _u32[b + 3],
+          f3 = _u32[b + 4], f4 = _u32[b + 5],
+          f5 = _u32[b + 6], f6 = _u32[b + 7],
+          f7 = _u32[b + 8], f8 = _u32[b + 9];
     const start = _p(_u32[b + 10]), end = _p(_u32[b + 11]);
     switch (tag) {
     case 0: return { type: "SequenceExpression", start, end, expressions: nodeArr(f1, f0) };
     case 1: return { type: "ParenthesizedExpression", start, end, expression: f1 !== NULL ? node(f1) : null };
-    case 2: { const r = { type: "ArrowFunctionExpression", start, end, id: null, generator: false, async: !!(flags & 2), params: f1 !== NULL ? fnParams(f1) : [], body: node(f2), expression: !!(flags & 1) }; if (_isTs) { r.typeParameters = f3 !== NULL ? node(f3) : null; r.returnType = f4 !== NULL ? node(f4) : null; } return r; }
-    case 3: { const ft = flags & 3; const r = { type: FUNCTION_TYPES[ft], start, end, id: f1 !== NULL ? node(f1) : null, generator: !!(flags & 4), async: !!(flags & 8), params: f2 !== NULL ? fnParams(f2) : [], body: f3 !== NULL ? node(f3) : null, expression: false }; if (_isTs) { r.typeParameters = f4 !== NULL ? node(f4) : null; r.returnType = f5 !== NULL ? node(f5) : null; r.declare = !!(flags & 16); } return r; }
+    case 2: {
+      const r = {
+        type: "ArrowFunctionExpression", start, end,
+        id: null, generator: false, async: !!(flags & 2),
+        params: f1 !== NULL ? fnParams(f1) : [],
+        body: node(f2), expression: !!(flags & 1),
+      };
+      if (_isTs) {
+        r.typeParameters = f3 !== NULL ? node(f3) : null;
+        r.returnType = f4 !== NULL ? node(f4) : null;
+      }
+      return r;
+    }
+    case 3: {
+      const ft = flags & 3;
+      const r = {
+        type: FUNCTION_TYPES[ft], start, end,
+        id: f1 !== NULL ? node(f1) : null,
+        generator: !!(flags & 4), async: !!(flags & 8),
+        params: f2 !== NULL ? fnParams(f2) : [],
+        body: f3 !== NULL ? node(f3) : null,
+        expression: false,
+      };
+      if (_isTs) {
+        r.typeParameters = f4 !== NULL ? node(f4) : null;
+        r.returnType = f5 !== NULL ? node(f5) : null;
+        r.declare = !!(flags & 16);
+      }
+      return r;
+    }
     case 4: return { type: "BlockStatement", start, end, body: nodeArr(f1, f0) };
     case 5: return { type: "BlockStatement", start, end, body: nodeArr(f1, f0) };
     case 6: return { params: fnParams(i) };
@@ -139,7 +233,11 @@ function decode(buffer, source) {
     case 8: return { type: "BinaryExpression", start, end, left: f1 !== NULL ? node(f1) : null, right: f2 !== NULL ? node(f2) : null, operator: BINARY_OPS[flags & 31] };
     case 9: return { type: "LogicalExpression", start, end, left: f1 !== NULL ? node(f1) : null, right: f2 !== NULL ? node(f2) : null, operator: LOGICAL_OPS[flags & 3] };
     case 10: return { type: "ConditionalExpression", start, end, test: f1 !== NULL ? node(f1) : null, consequent: f2 !== NULL ? node(f2) : null, alternate: f3 !== NULL ? node(f3) : null };
-    case 11: return { type: "UnaryExpression", start, end, operator: UNARY_OPS[flags & 7], prefix: true, argument: f1 !== NULL ? node(f1) : null };
+    case 11: return {
+      type: "UnaryExpression", start, end,
+      operator: UNARY_OPS[flags & 7], prefix: true,
+      argument: f1 !== NULL ? node(f1) : null,
+    };
     case 12: return { type: "UpdateExpression", start, end, argument: f1 !== NULL ? node(f1) : null, operator: UPDATE_OPS[flags & 1], prefix: !!(flags & 2) };
     case 13: return { type: "AssignmentExpression", start, end, left: f1 !== NULL ? node(f1) : null, right: f2 !== NULL ? node(f2) : null, operator: ASSIGNMENT_OPS[flags & 15] };
     case 14: return { type: "ArrayExpression", start, end, elements: nodeArrHoles(f1, f0) };
@@ -155,26 +253,133 @@ function decode(buffer, source) {
     case 24: return { type: "YieldExpression", start, end, argument: f1 !== NULL ? node(f1) : null, delegate: !!(flags & 1) };
     case 25: return { type: "MetaProperty", start, end, meta: f1 !== NULL ? node(f1) : null, property: f2 !== NULL ? node(f2) : null };
     case 26: return { type: "Decorator", start, end, expression: f1 !== NULL ? node(f1) : null };
-    case 27: { const r = { type: CLASS_TYPES[flags & 1], start, end, decorators: nodeArr(f1, f0), id: f2 !== NULL ? node(f2) : null, superClass: f3 !== NULL ? node(f3) : null, body: node(f4) }; if (_isTs) { r.typeParameters = f5 !== NULL ? node(f5) : null; r.superTypeArguments = f6 !== NULL ? node(f6) : null; r.implements = nodeArr(f7, f8); r.abstract = !!(flags & 2); r.declare = !!(flags & 4); } return r; }
+    case 27: {
+      const r = {
+        type: CLASS_TYPES[flags & 1], start, end,
+        decorators: nodeArr(f1, f0),
+        id: f2 !== NULL ? node(f2) : null,
+        superClass: f3 !== NULL ? node(f3) : null,
+        body: node(f4),
+      };
+      if (_isTs) {
+        r.typeParameters = f5 !== NULL ? node(f5) : null;
+        r.superTypeArguments = f6 !== NULL ? node(f6) : null;
+        r.implements = nodeArr(f7, f8);
+        r.abstract = !!(flags & 2);
+        r.declare = !!(flags & 4);
+      }
+      return r;
+    }
     case 28: return { type: "ClassBody", start, end, body: nodeArr(f1, f0) };
-    case 29: { const r = { type: "MethodDefinition", start, end, decorators: nodeArr(f1, f0), key: node(f2), value: node(f3), kind: METHOD_KINDS[flags & 3], computed: !!(flags & 4), static: !!(flags & 8) }; if (_isTs) { r.override = !!(flags & 16); r.optional = !!(flags & 32); const _abs = !!(flags & 64); r.accessibility = ACCESSIBILITY[(flags >> 7) & 3]; if (_abs) r.type = "TSAbstractMethodDefinition"; } return r; }
-    case 30: { const _acc = !!(flags & 4); const r = { type: _acc ? "AccessorProperty" : "PropertyDefinition", start, end, decorators: nodeArr(f1, f0), key: node(f2), value: f3 !== NULL ? node(f3) : null, computed: !!(flags & 1), static: !!(flags & 2) }; if (_isTs) { r.typeAnnotation = f4 !== NULL ? node(f4) : null; r.declare = !!(flags & 8); r.override = !!(flags & 16); r.optional = !!(flags & 32); r.definite = !!(flags & 64); r.readonly = !!(flags & 128); const _abs = !!(flags & 256); r.accessibility = ACCESSIBILITY[(flags >> 9) & 3]; if (_abs) r.type = _acc ? "TSAbstractAccessorProperty" : "TSAbstractPropertyDefinition"; } return r; }
+    case 29: {
+      const r = {
+        type: "MethodDefinition", start, end,
+        decorators: nodeArr(f1, f0),
+        key: node(f2), value: node(f3),
+        kind: METHOD_KINDS[flags & 3],
+        computed: !!(flags & 4), static: !!(flags & 8),
+      };
+      if (_isTs) {
+        r.override = !!(flags & 16);
+        r.optional = !!(flags & 32);
+        const _abs = !!(flags & 64);
+        r.accessibility = ACCESSIBILITY[(flags >> 7) & 3];
+        if (_abs) r.type = "TSAbstractMethodDefinition";
+      }
+      return r;
+    }
+    case 30: {
+      const _acc = !!(flags & 4);
+      const r = {
+        type: _acc ? "AccessorProperty" : "PropertyDefinition",
+        start, end,
+        decorators: nodeArr(f1, f0),
+        key: node(f2),
+        value: f3 !== NULL ? node(f3) : null,
+        computed: !!(flags & 1), static: !!(flags & 2),
+      };
+      if (_isTs) {
+        r.typeAnnotation = f4 !== NULL ? node(f4) : null;
+        r.declare = !!(flags & 8);
+        r.override = !!(flags & 16);
+        r.optional = !!(flags & 32);
+        r.definite = !!(flags & 64);
+        r.readonly = !!(flags & 128);
+        const _abs = !!(flags & 256);
+        r.accessibility = ACCESSIBILITY[(flags >> 9) & 3];
+        if (_abs)
+          r.type = _acc
+            ? "TSAbstractAccessorProperty"
+            : "TSAbstractPropertyDefinition";
+      }
+      return r;
+    }
     case 31: return { type: "StaticBlock", start, end, body: nodeArr(f1, f0) };
     case 32: return { type: "Super", start, end };
-    case 33: return { type: "Literal", start, end, value: str(f1, f2), raw: _src.slice(start, end) };
-    case 34: { const r = _src.slice(start, end); const s = r.indexOf("_") === -1 ? r : r.replace(/_/g, ""); const v = (flags & 3) === 2 && s[1] !== "o" && s[1] !== "O" ? parseInt(s.slice(1), 8) : +s; return { type: "Literal", start, end, value: v === v && isFinite(v) ? v : null, raw: r }; }
-    case 35: { const r = _src.slice(start, end); const d = str(f1, f2).replace(/_/g, ""); const v = BigInt(d); return { type: "Literal", start, end, value: v, raw: r, bigint: v.toString() }; }
-    case 36: { const v = !!(flags & 1); return { type: "Literal", start, end, value: v, raw: v ? "true" : "false" }; }
+    case 33: return {
+      type: "Literal", start, end,
+      value: str(f1, f2), raw: _src.slice(start, end),
+    };
+    case 34: {
+      const r = _src.slice(start, end);
+      const s = r.indexOf("_") === -1 ? r : r.replace(/_/g, "");
+      const v = (flags & 3) === 2 && s[1] !== "o" && s[1] !== "O"
+        ? parseInt(s.slice(1), 8)
+        : +s;
+      return {
+        type: "Literal", start, end,
+        value: v === v && isFinite(v) ? v : null,
+        raw: r,
+      };
+    }
+    case 35: {
+      const r = _src.slice(start, end);
+      const d = str(f1, f2).replace(/_/g, "");
+      const v = BigInt(d);
+      return {
+        type: "Literal", start, end,
+        value: v, raw: r, bigint: v.toString(),
+      };
+    }
+    case 36: {
+      const v = !!(flags & 1);
+      return {
+        type: "Literal", start, end,
+        value: v, raw: v ? "true" : "false",
+      };
+    }
     case 37: return { type: "Literal", start, end, value: null, raw: "null" };
     case 38: return { type: "ThisExpression", start, end };
-    case 39: { const p = str(f1, f2), fl = str(f3, f4); let v = null; try { v = new RegExp(p, fl); } catch {} return { type: "Literal", start, end, value: v, raw: "/" + p + "/" + fl, regex: { pattern: p, flags: fl.split("").sort().join("") } }; }
+    case 39: {
+      const p = str(f1, f2), fl = str(f3, f4);
+      let v = null;
+      try { v = new RegExp(p, fl); } catch {}
+      return {
+        type: "Literal", start, end,
+        value: v, raw: "/" + p + "/" + fl,
+        regex: { pattern: p, flags: fl.split("").sort().join("") },
+      };
+    }
     case 40: return { type: "TemplateLiteral", start, end, quasis: nodeArr(f1, f0), expressions: nodeArr(f2, f3) };
-    case 41: { const raw = _src.slice(start, end).replace(/\r\n?/g, "\n"); const tl = !!(flags & 1); const s = _isTs ? start - 1 : start; const e = _isTs ? (tl ? end + 1 : end + 2) : end; return { type: "TemplateElement", start: s, end: e, value: { raw, cooked: (flags & 2) ? null : str(f1, f2) }, tail: tl }; }
-    case 42: { const r = { type: "Identifier", start, end, name: str(f1, f2) }; if (_isTs) { r.decorators = []; r.optional = false; r.typeAnnotation = null; } return r; }
+    case 41: {
+      const raw = _src.slice(start, end).replace(/\r\n?/g, "\n");
+      const tl = !!(flags & 1);
+      const s = _isTs ? start - 1 : start;
+      const e = _isTs ? (tl ? end + 1 : end + 2) : end;
+      return {
+        type: "TemplateElement", start: s, end: e,
+        value: {
+          raw,
+          cooked: (flags & 2) ? null : str(f1, f2),
+        },
+        tail: tl,
+      };
+    }
+    case 42: { const r = { type: "Identifier", start, end, name: str(f1, f2), kind: "reference" }; if (_isTs) { r.decorators = []; r.optional = false; r.typeAnnotation = null; } return r; }
     case 43: return { type: "PrivateIdentifier", start, end, name: str(f1, f2) };
-    case 44: { const r = { type: "Identifier", start, end, name: str(f1, f2) }; if (_isTs) { r.decorators = nodeArr(f3, f0); r.typeAnnotation = f4 !== NULL ? node(f4) : null; r.optional = !!(flags & 1); } return r; }
-    case 45: { const r = { type: "Identifier", start, end, name: str(f1, f2) }; if (_isTs) { r.decorators = []; r.optional = false; r.typeAnnotation = null; } return r; }
-    case 46: { const r = { type: "Identifier", start, end, name: str(f1, f2) }; if (_isTs) { r.decorators = []; r.optional = false; r.typeAnnotation = null; } return r; }
+    case 44: { const r = { type: "Identifier", start, end, name: str(f1, f2), kind: "binding" }; if (_isTs) { r.decorators = nodeArr(f3, f0); r.typeAnnotation = f4 !== NULL ? node(f4) : null; r.optional = !!(flags & 1); } return r; }
+    case 45: { const r = { type: "Identifier", start, end, name: str(f1, f2), kind: "name" }; if (_isTs) { r.decorators = []; r.optional = false; r.typeAnnotation = null; } return r; }
+    case 46: { const r = { type: "Identifier", start, end, name: str(f1, f2), kind: "label" }; if (_isTs) { r.decorators = []; r.optional = false; r.typeAnnotation = null; } return r; }
     case 47: { const r = { type: "ExpressionStatement", start, end, expression: f1 !== NULL ? node(f1) : null }; if (_isTs) { r.directive = null; } return r; }
     case 48: return { type: "IfStatement", start, end, test: f1 !== NULL ? node(f1) : null, consequent: f2 !== NULL ? node(f2) : null, alternate: f3 !== NULL ? node(f3) : null };
     case 49: return { type: "SwitchStatement", start, end, discriminant: f1 !== NULL ? node(f1) : null, cases: nodeArr(f2, f0) };
@@ -196,13 +401,53 @@ function decode(buffer, source) {
     case 65: return { type: "EmptyStatement", start, end };
     case 66: { const r = { type: "VariableDeclaration", start, end, kind: VAR_KINDS[flags & 7], declarations: nodeArr(f1, f0) }; if (_isTs) { r.declare = !!(flags & 8); } return r; }
     case 67: { const r = { type: "VariableDeclarator", start, end, id: f1 !== NULL ? node(f1) : null, init: f2 !== NULL ? node(f2) : null }; if (_isTs) { r.definite = !!(flags & 1); } return r; }
-    case 68: return { type: "ExpressionStatement", start, end, expression: node(f1), directive: str(f2, f3) };
+    case 68: return {
+      type: "ExpressionStatement", start, end,
+      expression: node(f1), directive: str(f2, f3),
+    };
     case 69: { const r = { type: "AssignmentPattern", start, end, left: f1 !== NULL ? node(f1) : null, right: f2 !== NULL ? node(f2) : null }; if (_isTs) { r.decorators = nodeArr(f3, f0); r.typeAnnotation = f4 !== NULL ? node(f4) : null; r.optional = !!(flags & 1); } return r; }
     case 70: { const r = { type: "RestElement", start, end, argument: f1 !== NULL ? node(f1) : null }; if (_isTs) { r.decorators = nodeArr(f2, f0); r.typeAnnotation = f3 !== NULL ? node(f3) : null; r.optional = !!(flags & 1); r.value = null; } return r; }
-    case 71: { const el = nodeArrHoles(f1, f0); if (f2 !== NULL) el.push(node(f2)); const r = { type: "ArrayPattern", start, end, elements: el }; if (_isTs) { r.decorators = nodeArr(f3, f4); r.optional = !!(flags & 1); r.typeAnnotation = f5 !== NULL ? node(f5) : null; } return r; }
-    case 72: { const pr = nodeArr(f1, f0); if (f2 !== NULL) pr.push(node(f2)); const r = { type: "ObjectPattern", start, end, properties: pr }; if (_isTs) { r.decorators = nodeArr(f3, f4); r.optional = !!(flags & 1); r.typeAnnotation = f5 !== NULL ? node(f5) : null; } return r; }
-    case 73: { const r = { type: "Property", start, end, kind: "init", key: node(f1), value: node(f2), method: false, shorthand: !!(flags & 1), computed: !!(flags & 2) }; if (_isTs) { r.optional = false; } return r; }
-    case 74: return { type: "Program", start, end, sourceType: (flags & 1) ? "module" : "script", hashbang: (flags & 2) ? { type: "Hashbang", start: _p(f2 - 2), end: _p(f3), value: str(f2, f3) } : null, body: nodeArr(f1, f0) };
+    case 71: {
+      const el = nodeArrHoles(f1, f0);
+      if (f2 !== NULL) el.push(node(f2));
+      const r = { type: "ArrayPattern", start, end, elements: el };
+      if (_isTs) {
+        r.decorators = nodeArr(f3, f4);
+        r.optional = !!(flags & 1);
+        r.typeAnnotation = f5 !== NULL ? node(f5) : null;
+      }
+      return r;
+    }
+    case 72: {
+      const pr = nodeArr(f1, f0);
+      if (f2 !== NULL) pr.push(node(f2));
+      const r = { type: "ObjectPattern", start, end, properties: pr };
+      if (_isTs) {
+        r.decorators = nodeArr(f3, f4);
+        r.optional = !!(flags & 1);
+        r.typeAnnotation = f5 !== NULL ? node(f5) : null;
+      }
+      return r;
+    }
+    case 73: {
+      const r = {
+        type: "Property", start, end,
+        kind: "init",
+        key: node(f1), value: node(f2),
+        method: false,
+        shorthand: !!(flags & 1),
+        computed: !!(flags & 2),
+      }; if (_isTs) { r.optional = false; } return r; }
+    case 74: return {
+      type: "Program", start, end,
+      sourceType: (flags & 1) ? "module" : "script",
+      hashbang: (flags & 2) ? {
+        type: "Hashbang",
+        start: _p(f2 - 2), end: _p(f3),
+        value: str(f2, f3),
+      } : null,
+      body: nodeArr(f1, f0),
+    };
     case 75: return { type: "ImportExpression", start, end, source: f1 !== NULL ? node(f1) : null, options: f2 !== NULL ? node(f2) : null, phase: (flags & 1) ? ["source", "defer"][(flags >> 1) & 1] : null };
     case 76: { const r = { type: "ImportDeclaration", start, end, specifiers: nodeArr(f1, f0), source: f2 !== NULL ? node(f2) : null, attributes: nodeArr(f3, f4), phase: (flags & 1) ? ["source", "defer"][(flags >> 1) & 1] : null }; if (_isTs) { r.importKind = IMPORT_EXPORT_KINDS[(flags >> 2) & 1]; } return r; }
     case 77: { const r = { type: "ImportSpecifier", start, end, imported: f1 !== NULL ? node(f1) : null, local: f2 !== NULL ? node(f2) : null }; if (_isTs) { r.importKind = IMPORT_EXPORT_KINDS[flags & 1]; } return r; }
@@ -252,15 +497,54 @@ function decode(buffer, source) {
     case 121: return { type: "TSInferType", start, end, typeParameter: f1 !== NULL ? node(f1) : null };
     case 122: return { type: "TSTypeOperator", start, end, operator: TS_TYPE_OPERATORS[flags & 3], typeAnnotation: f1 !== NULL ? node(f1) : null };
     case 123: return { type: "TSParenthesizedType", start, end, typeAnnotation: f1 !== NULL ? node(f1) : null };
-    case 124: return { type: "TSFunctionType", start, end, typeParameters: f1 !== NULL ? node(f1) : null, params: f2 !== NULL ? fnParams(f2) : [], returnType: f3 !== NULL ? node(f3) : null };
-    case 125: return { type: "TSConstructorType", start, end, abstract: !!(flags & 1), typeParameters: f1 !== NULL ? node(f1) : null, params: f2 !== NULL ? fnParams(f2) : [], returnType: f3 !== NULL ? node(f3) : null };
+    case 124: return {
+      type: "TSFunctionType", start, end,
+      typeParameters: f1 !== NULL ? node(f1) : null,
+      params: f2 !== NULL ? fnParams(f2) : [],
+      returnType: f3 !== NULL ? node(f3) : null,
+    };
+    case 125: return {
+      type: "TSConstructorType", start, end,
+      abstract: !!(flags & 1),
+      typeParameters: f1 !== NULL ? node(f1) : null,
+      params: f2 !== NULL ? fnParams(f2) : [],
+      returnType: f3 !== NULL ? node(f3) : null,
+    };
     case 126: return { type: "TSTypePredicate", start, end, parameterName: f1 !== NULL ? node(f1) : null, typeAnnotation: f2 !== NULL ? node(f2) : null, asserts: !!(flags & 1) };
     case 127: return { type: "TSTypeLiteral", start, end, members: nodeArr(f1, f0) };
-    case 128: return { type: "TSMappedType", start, end, key: node(f1), constraint: node(f2), nameType: f3 !== NULL ? node(f3) : null, typeAnnotation: f4 !== NULL ? node(f4) : null, optional: TS_MAPPED_OPTIONAL[(flags >> 0) & 3], readonly: TS_MAPPED_READONLY[(flags >> 2) & 3] };
+    case 128: return {
+      type: "TSMappedType", start, end,
+      key: node(f1),
+      constraint: node(f2),
+      nameType: f3 !== NULL ? node(f3) : null,
+      typeAnnotation: f4 !== NULL ? node(f4) : null,
+      optional: TS_MAPPED_OPTIONAL[(flags >> 0) & 3],
+      readonly: TS_MAPPED_READONLY[(flags >> 2) & 3],
+    };
     case 129: { const r = { type: "TSPropertySignature", start, end, key: f1 !== NULL ? node(f1) : null, typeAnnotation: f2 !== NULL ? node(f2) : null, computed: !!(flags & 1), optional: !!(flags & 2), readonly: !!(flags & 4) }; if (_isTs) { r.accessibility = null; r.static = false; } return r; }
-    case 130: return { type: "TSMethodSignature", start, end, key: node(f1), computed: !!(flags & 4), optional: !!(flags & 8), kind: TS_METHOD_SIGNATURE_KINDS[(flags >> 0) & 3], typeParameters: f2 !== NULL ? node(f2) : null, params: f3 !== NULL ? fnParams(f3) : [], returnType: f4 !== NULL ? node(f4) : null, accessibility: null, readonly: false, static: false };
-    case 131: return { type: "TSCallSignatureDeclaration", start, end, typeParameters: f1 !== NULL ? node(f1) : null, params: f2 !== NULL ? fnParams(f2) : [], returnType: f3 !== NULL ? node(f3) : null };
-    case 132: return { type: "TSConstructSignatureDeclaration", start, end, typeParameters: f1 !== NULL ? node(f1) : null, params: f2 !== NULL ? fnParams(f2) : [], returnType: f3 !== NULL ? node(f3) : null };
+    case 130: return {
+      type: "TSMethodSignature", start, end,
+      key: node(f1),
+      computed: !!(flags & 4),
+      optional: !!(flags & 8),
+      kind: TS_METHOD_SIGNATURE_KINDS[(flags >> 0) & 3],
+      typeParameters: f2 !== NULL ? node(f2) : null,
+      params: f3 !== NULL ? fnParams(f3) : [],
+      returnType: f4 !== NULL ? node(f4) : null,
+      accessibility: null, readonly: false, static: false,
+    };
+    case 131: return {
+      type: "TSCallSignatureDeclaration", start, end,
+      typeParameters: f1 !== NULL ? node(f1) : null,
+      params: f2 !== NULL ? fnParams(f2) : [],
+      returnType: f3 !== NULL ? node(f3) : null,
+    };
+    case 132: return {
+      type: "TSConstructSignatureDeclaration", start, end,
+      typeParameters: f1 !== NULL ? node(f1) : null,
+      params: f2 !== NULL ? fnParams(f2) : [],
+      returnType: f3 !== NULL ? node(f3) : null,
+    };
     case 133: { const r = { type: "TSIndexSignature", start, end, parameters: nodeArr(f1, f0), typeAnnotation: f2 !== NULL ? node(f2) : null, readonly: !!(flags & 1) }; if (_isTs) { r.static = !!(flags & 2); r.accessibility = null; } return r; }
     case 134: return { type: "TSTypeAliasDeclaration", start, end, id: f1 !== NULL ? node(f1) : null, typeParameters: f2 !== NULL ? node(f2) : null, typeAnnotation: f3 !== NULL ? node(f3) : null, declare: !!(flags & 1) };
     case 135: return { type: "TSInterfaceDeclaration", start, end, id: f1 !== NULL ? node(f1) : null, typeParameters: f2 !== NULL ? node(f2) : null, extends: nodeArr(f3, f0), body: f4 !== NULL ? node(f4) : null, declare: !!(flags & 1) };
@@ -270,11 +554,32 @@ function decode(buffer, source) {
     case 139: return { type: "TSEnumDeclaration", start, end, id: f1 !== NULL ? node(f1) : null, body: f2 !== NULL ? node(f2) : null, const: !!(flags & 1), declare: !!(flags & 2) };
     case 140: return { type: "TSEnumBody", start, end, members: nodeArr(f1, f0) };
     case 141: return { type: "TSEnumMember", start, end, id: f1 !== NULL ? node(f1) : null, initializer: f2 !== NULL ? node(f2) : null, computed: !!(flags & 1) };
-    case 142: { const r = { type: "TSModuleDeclaration", start, end, id: node(f1), kind: TS_MODULE_KINDS[(flags >> 0) & 1], declare: !!(flags & 2), global: false }; if (f2 !== NULL) r.body = node(f2); return r; }
+    case 142: {
+      const r = {
+        type: "TSModuleDeclaration", start, end,
+        id: node(f1),
+        kind: TS_MODULE_KINDS[(flags >> 0) & 1],
+        declare: !!(flags & 2),
+        global: false,
+      };
+      if (f2 !== NULL) r.body = node(f2);
+      return r;
+    }
     case 143: return { type: "TSModuleBlock", start, end, body: nodeArr(f1, f0) };
-    case 144: return { type: "TSModuleDeclaration", start, end, id: node(f1), body: node(f2), kind: "global", declare: !!(flags & 1), global: true };
+    case 144: return {
+      type: "TSModuleDeclaration", start, end,
+      id: node(f1), body: node(f2),
+      kind: "global",
+      declare: !!(flags & 1),
+      global: true,
+    };
     case 145: { const r = { type: "TSParameterProperty", start, end, decorators: nodeArr(f1, f0), parameter: f2 !== NULL ? node(f2) : null, override: !!(flags & 1), readonly: !!(flags & 2), accessibility: ACCESSIBILITY[(flags >> 2) & 3] }; if (_isTs) { r.static = false; } return r; }
-    case 146: return { type: "Identifier", start, end, decorators: [], name: "this", optional: false, typeAnnotation: f1 !== NULL ? node(f1) : null };
+    case 146: return {
+      type: "Identifier", start, end,
+      decorators: [],
+      name: "this", kind: "this", optional: false,
+      typeAnnotation: f1 !== NULL ? node(f1) : null,
+    };
     case 147: return { type: "TSAsExpression", start, end, expression: f1 !== NULL ? node(f1) : null, typeAnnotation: f2 !== NULL ? node(f2) : null };
     case 148: return { type: "TSSatisfiesExpression", start, end, expression: f1 !== NULL ? node(f1) : null, typeAnnotation: f2 !== NULL ? node(f2) : null };
     case 149: return { type: "TSTypeAssertion", start, end, typeAnnotation: f1 !== NULL ? node(f1) : null, expression: f2 !== NULL ? node(f2) : null };
@@ -297,34 +602,22 @@ function decode(buffer, source) {
     case 166: return { type: "JSXSpreadAttribute", start, end, argument: f1 !== NULL ? node(f1) : null };
     case 167: return { type: "JSXExpressionContainer", start, end, expression: f1 !== NULL ? node(f1) : null };
     case 168: return { type: "JSXEmptyExpression", start, end };
-    case 169: { const t = str(f1, f2); return { type: "JSXText", start, end, value: t, raw: t }; }
+    case 169: {
+      const t = str(f1, f2);
+      return { type: "JSXText", start, end, value: t, raw: t };
+    }
     case 170: return { type: "JSXSpreadChild", start, end, expression: f1 !== NULL ? node(f1) : null };
     }
   }
-  const cOff = _spOff + spLen;
-  const lsOff = cOff + commentCount * 20;
+  const node = _attachComments ? nodeWithComments : _decode;
+  const lsOff = _cOff + commentCount * 12;
   const dOff = lsOff + lineStartsCount * 4;
-  const dv = new DataView(buffer);
-  function _decodeComments() {
-    const out = new Array(commentCount);
-    for (let j = 0; j < commentCount; j++) {
-      const o = cOff + j * 20;
-      const flags = _u8[o + 1];
-      out[j] = {
-        type: COMMENT_TYPES[_u8[o + 0]],
-        precededByNewline: (flags & 1) !== 0,
-        followedByNewline: (flags & 2) !== 0,
-        value: str(dv.getUint32(o + 12, true), dv.getUint32(o + 16, true)),
-        start: _p(dv.getUint32(o + 4, true)),
-        end: _p(dv.getUint32(o + 8, true)),
-      };
-    }
-    return out;
-  }
   function _decodeLineStarts() {
     const out = new Array(lineStartsCount);
     if (_firstNa >= _srcLen) {
-      for (let j = 0; j < lineStartsCount; j++) out[j] = dv.getUint32(lsOff + j * 4, true);
+      for (let j = 0; j < lineStartsCount; j++) {
+        out[j] = dv.getUint32(lsOff + j * 4, true);
+      }
       return out;
     }
     if (pm === null) pm = buildPosMap(_src, _srcLen, _firstNa);
@@ -345,25 +638,51 @@ function decode(buffer, source) {
       const msg = _td.decode(_u8.subarray(dp, dp + ml)); dp += ml;
       const hh = _u8[dp]; dp++;
       let help = null;
-      if (hh) { const hl = dv.getUint32(dp, true); dp += 4; help = _td.decode(_u8.subarray(dp, dp + hl)); dp += hl; }
+      if (hh) {
+        const hl = dv.getUint32(dp, true); dp += 4;
+        help = _td.decode(_u8.subarray(dp, dp + hl)); dp += hl;
+      }
       const lc = dv.getUint32(dp, true); dp += 4;
       const labels = new Array(lc);
       for (let k = 0; k < lc; k++) {
         const ls = _p(dv.getUint32(dp, true)); dp += 4;
         const le = _p(dv.getUint32(dp, true)); dp += 4;
         const lml = dv.getUint32(dp, true); dp += 4;
-        labels[k] = { start: ls, end: le, message: _td.decode(_u8.subarray(dp, dp + lml)) }; dp += lml;
+        labels[k] = {
+          start: ls,
+          end: le,
+          message: _td.decode(_u8.subarray(dp, dp + lml)),
+        };
+        dp += lml;
       }
       out[j] = { severity: sev, message: msg, start: ds, end: de, help, labels };
     }
     return out;
   }
-  let _program, _comments, _lineStarts, _diagnostics;
+  let _program, _lineStarts, _diagnostics;
+  function _getLineStarts() {
+    if (_lineStarts === undefined) _lineStarts = _decodeLineStarts();
+    return _lineStarts;
+  }
   return {
-    get program() { return _program !== undefined ? _program : (_program = node(progIdx)); },
-    get comments() { return _comments !== undefined ? _comments : (_comments = _decodeComments()); },
-    get lineStarts() { return _lineStarts !== undefined ? _lineStarts : (_lineStarts = _decodeLineStarts()); },
-    get diagnostics() { return _diagnostics !== undefined ? _diagnostics : (_diagnostics = _decodeDiagnostics()); },
+    get program() {
+      return _program !== undefined ? _program : (_program = node(progIdx));
+    },
+    get diagnostics() {
+      return _diagnostics !== undefined
+        ? _diagnostics
+        : (_diagnostics = _decodeDiagnostics());
+    },
+    get lineStarts() { return _getLineStarts(); },
+    locOf(offset) {
+      const ls = _getLineStarts();
+      let lo = 0, hi = ls.length;
+      while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (ls[mid] <= offset) lo = mid + 1; else hi = mid;
+      }
+      return { line: lo, column: offset - ls[lo - 1] };
+    },
   };
 }
 export { decode };

package/index.d.ts

@@ -40,24 +40,39 @@ interface ParseOptions {
    * @default false
    */
   semanticErrors?: boolean;
+  /**
+   * Collect comments and attach them to host AST nodes via
+   * {@link BaseNode.comments}.
+   * @default false
+   */
+  attachComments?: boolean;
 }
 
 /** Whether a {@link Comment} came from a line or block source comment. */
 type CommentType = "Line" | "Block";
 
-/** A source code comment. */
+/**
+ * Position of a {@link Comment} relative to its host node.
+ *
+ * - `before`: leading the host.
+ * - `after`: trailing the host.
+ * - `inside`: interior to an otherwise empty host.
+ */
+type CommentPosition = "before" | "after" | "inside";
+
+/**
+ * A source code comment attached to a single host AST node.
+ *
+ * `sameLine` is true when the comment shares a source line with the
+ * host's adjacent edge (host's start for `before`, host's end for
+ * `after`). For `inside` it is always `false`.
+ */
 interface Comment {
   type: CommentType;
-  /** True when a line terminator immediately precedes this comment. */
-  precededByNewline: boolean;
-  /** True when a line terminator immediately follows this comment. */
-  followedByNewline: boolean;
+  position: CommentPosition;
+  sameLine: boolean;
   /** Comment text without the delimiters. */
   value: string;
-  /** Byte offset. */
-  start: number;
-  /** Byte offset. */
-  end: number;
 }
 
 /** A labeled source span attached to a {@link Diagnostic}. */
@@ -104,12 +119,19 @@ interface SourceLocation {
 interface ParseResult {
   /** Root ESTree/TypeScript-ESTree AST node. */
   program: Program;
-  /** All comments in source order. */
-  comments: Comment[];
-  /** Byte offset where each source line begins. Index 0 is always 0. */
-  lineStarts: number[];
   /** Syntax diagnostics, and semantic diagnostics when {@link ParseOptions.semanticErrors} is enabled. */
   diagnostics: Diagnostic[];
+  /**
+   * Sorted UTF-16 offsets where each line begins. Index `i` is the start of
+   * line `i + 1`. Used internally by {@link locOf}, and required by
+   * `yuku-codegen` for source maps.
+   */
+  lineStarts: number[];
+  /**
+   * Resolves an offset to a `{ line, column }` pair. Lines are
+   * 1-based, columns are 0-based, matching ESTree's `loc` convention.
+   */
+  locOf(offset: number): SourceLocation;
 }
 
 /**
@@ -136,25 +158,16 @@ export function langFromPath(path: string): SourceLang;
  */
 export function sourceTypeFromPath(path: string): SourceType;
 
-/**
- * Resolves a `{ line, column }` {@link SourceLocation} for an offset, using
- * {@link ParseResult.lineStarts}. Runs in O(log n).
- *
- * Lines are 1-based; columns are 0-based. The unit of `offset` (UTF-16 code
- * units in JS) must match the unit of `lineStarts`. Both come from the same
- * {@link ParseResult}, so this is automatic.
- *
- * @example
- * const { program, lineStarts } = parse(source);
- * locOf(lineStarts, program.body[0].start); // => { line, column }
- */
-export function locOf(lineStarts: number[], offset: number): SourceLocation;
-
 // AST node types
 
 interface BaseNode {
   start: number;
   end: number;
+  /**
+   * Comments attached to this node in source order. Present only when
+   * {@link ParseOptions.attachComments} is enabled.
+   */
+  comments?: Comment[];
 }
 
 type Span = BaseNode;
@@ -241,39 +254,37 @@ type PropertyDefinitionType = "PropertyDefinition" | "TSAbstractPropertyDefiniti
 
 type AccessorPropertyType = "AccessorProperty" | "TSAbstractAccessorProperty";
 
-interface IdentifierName extends BaseNode {
-  type: "Identifier";
-  name: string;
-  decorators?: [];
-  optional?: false;
-  typeAnnotation?: null;
-}
-
-interface IdentifierReference extends BaseNode {
-  type: "Identifier";
-  name: string;
-  decorators?: [];
-  optional?: false;
-  typeAnnotation?: null;
-}
+/**
+ * Role of an `Identifier` within the AST. Yuku exposes the four ESTree-collapsed
+ * identifier flavors as a discriminator, plus `"this"` for a TS `this`-parameter
+ * (which TS-ESTree also encodes as an `Identifier` with `name: "this"`).
+ *
+ * - `"reference"`: identifier read as a value (`x` in `x + 1`, `console`).
+ * - `"binding"`: identifier being declared (parameters, `let x`, function/class names).
+ * - `"name"`: identifier in a non-binding name slot (property/method names like `log` in `console.log`).
+ * - `"label"`: loop label (`outer` in `outer: for (...) {}`).
+ * - `"this"`: the TS `this`-parameter (`function f(this: T)`).
+ */
+type IdentifierKind = "reference" | "binding" | "name" | "label" | "this";
 
-interface BindingIdentifier extends BaseNode {
+interface Identifier extends BaseNode {
   type: "Identifier";
   name: string;
+  /**
+   * ESTree collapses several distinct identifier
+   * roles onto one `Identifier` node, `kind` lets you tell them apart without
+   * walking the parent context. See {@link IdentifierKind}.
+   */
+  kind: IdentifierKind;
   decorators?: Decorator[];
   optional?: boolean;
   typeAnnotation?: TSTypeAnnotation | null;
 }
 
-interface LabelIdentifier extends BaseNode {
-  type: "Identifier";
-  name: string;
-  decorators?: [];
-  optional?: false;
-  typeAnnotation?: null;
-}
-
-type Identifier = IdentifierName | IdentifierReference | BindingIdentifier | LabelIdentifier;
+type IdentifierName = Identifier;
+type IdentifierReference = Identifier;
+type BindingIdentifier = Identifier;
+type LabelIdentifier = Identifier;
 
 interface PrivateIdentifier extends BaseNode {
   type: "PrivateIdentifier";
@@ -1686,6 +1697,7 @@ type Node =
   | Directive
   | ObjectProperty
   | BindingProperty
+  | SpreadElement
   | PrivateIdentifier
   | TemplateElement
   | VariableDeclarator
@@ -1704,6 +1716,7 @@ type Node =
   | TSAbstractAccessorProperty
   | StaticBlock
   | Decorator
+  | TSEmptyBodyFunctionExpression
   | ImportSpecifier
   | ImportDefaultSpecifier
   | ImportNamespaceSpecifier
@@ -1749,6 +1762,7 @@ export type {
   ParseResult,
   Comment,
   CommentType,
+  CommentPosition,
   Diagnostic,
   DiagnosticLabel,
   DiagnosticSeverity,
@@ -1780,6 +1794,7 @@ export type {
   ModuleExportName,
   PropertyKey,
   Identifier,
+  IdentifierKind,
   IdentifierName,
   IdentifierReference,
   BindingIdentifier,

package/index.js

@@ -16,13 +16,3 @@ export function langFromPath(path) {
 export function sourceTypeFromPath(path) {
   return path.endsWith(".cjs") || path.endsWith(".cts") ? "script" : "module";
 }
-
-export function locOf(lineStarts, offset) {
-  let lo = 0, hi = lineStarts.length;
-  while (lo < hi) {
-    const mid = (lo + hi) >>> 1;
-    if (lineStarts[mid] <= offset) lo = mid + 1;
-    else hi = mid;
-  }
-  return { line: lo, column: offset - lineStarts[lo - 1] };
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yuku-parser",
-  "version": "0.5.14",
+  "version": "0.5.16",
   "description": "High-performance JavaScript/TypeScript parser",
   "license": "MIT",
   "repository": {
@@ -17,17 +17,17 @@
     "decode.js"
   ],
   "optionalDependencies": {
-    "@yuku-parser/binding-linux-x64-gnu": "0.5.14",
-    "@yuku-parser/binding-linux-arm64-gnu": "0.5.14",
-    "@yuku-parser/binding-linux-arm-gnu": "0.5.14",
-    "@yuku-parser/binding-linux-x64-musl": "0.5.14",
-    "@yuku-parser/binding-linux-arm64-musl": "0.5.14",
-    "@yuku-parser/binding-linux-arm-musl": "0.5.14",
-    "@yuku-parser/binding-darwin-x64": "0.5.14",
-    "@yuku-parser/binding-darwin-arm64": "0.5.14",
-    "@yuku-parser/binding-win32-x64": "0.5.14",
-    "@yuku-parser/binding-win32-arm64": "0.5.14",
-    "@yuku-parser/binding-freebsd-x64": "0.5.14"
+    "@yuku-parser/binding-linux-x64-gnu": "0.5.16",
+    "@yuku-parser/binding-linux-arm64-gnu": "0.5.16",
+    "@yuku-parser/binding-linux-arm-gnu": "0.5.16",
+    "@yuku-parser/binding-linux-x64-musl": "0.5.16",
+    "@yuku-parser/binding-linux-arm64-musl": "0.5.16",
+    "@yuku-parser/binding-linux-arm-musl": "0.5.16",
+    "@yuku-parser/binding-darwin-x64": "0.5.16",
+    "@yuku-parser/binding-darwin-arm64": "0.5.16",
+    "@yuku-parser/binding-win32-x64": "0.5.16",
+    "@yuku-parser/binding-win32-arm64": "0.5.16",
+    "@yuku-parser/binding-freebsd-x64": "0.5.16"
   },
   "keywords": [
     "acorn",