yuku-parser 0.5.10 → 0.5.14

package/README.md

@@ -57,6 +57,19 @@ 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:
+
+```ts
+import { parse, locOf } from "yuku-parser";
+
+const { program, lineStarts } = parse(source);
+const { line, column } = locOf(lineStarts, 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.
+
 ## Walking the AST
 
 The AST is standard ESTree, so any ESTree-compatible walker works. For example, with [zimmerframe](https://github.com/sveltejs/zimmerframe):
@@ -142,36 +155,17 @@ This incurs a very small performance overhead. If your build pipeline already ha
 
 ### Comments
 
-Every entry in `result.comments` is classified at parse time so consumers can route comments without rescanning the value:
+Every entry in `result.comments` describes one source comment:
 
 ```ts
 interface Comment {
   type: "Line" | "Block";
-  kind: CommentKind;
   precededByNewline: boolean;
   followedByNewline: boolean;
   value: string; // text without the surrounding delimiters
   start: number; // byte offset
   end: number; // byte offset
 }
-
-type CommentKind =
-  | "normal" // plain comment, no special meaning
-  | "legal" // /*! ... */ or contains @license / @preserve / @cc_on
-  | "jsdoc" // /** ... */ block
-  | "annotation" // /*# ... */ or /*@ ... */ other than tree-shaking
-  | "pure" // /*#__PURE__*/ or /*@__PURE__*/
-  | "no_side_effects"; // /*#__NO_SIDE_EFFECTS__*/ or /*@__NO_SIDE_EFFECTS__*/
-```
-
-Common patterns:
-
-```js
-// Extract legal banners for a sidecar file.
-const banners = result.comments.filter((c) => c.kind === "legal");
-
-// Find tree-shaking annotations.
-const pureMarkers = result.comments.filter((c) => c.kind === "pure");
 ```
 
 `precededByNewline` and `followedByNewline` capture line layout, useful for tools that need to reconstruct source positioning.

package/decode.js

@@ -1,5 +1,7 @@
 // generated by tools/gen_estree_decoder.zig, do not edit
-const NULL = 0xFFFFFFFF;
+// `_u32` is an Int32Array so NodeIndex NULL reads as -1 and fits in
+// an SMI/int32, avoiding heap-number boxing on every field read in JSC.
+const NULL = -1;
 const _td = new TextDecoder("utf-8", { ignoreBOM: true });
 const BINARY_OPS = ["==", "!=", "===", "!==", "<", "<=", ">", ">=", "+", "-", "*", "/", "%", "**", "|", "^", "&", "<<", ">>", ">>>", "in", "instanceof"];
 const LOGICAL_OPS = ["&&", "||", "??"];
@@ -12,7 +14,6 @@ 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 COMMENT_KINDS = ["normal", "legal", "jsdoc", "annotation", "pure", "no_side_effects"];
 const SEVERITY = ["error", "warning", "hint", "info"];
 const IMPORT_EXPORT_KINDS = ["value", "type"];
 const ACCESSIBILITY = [null, "public", "private", "protected"];
@@ -53,7 +54,7 @@ function buildPosMap(src, byteLen, startByte) {
 function decode(buffer, source) {
   const _u8 = new Uint8Array(buffer);
   const aLen = (buffer.byteLength >> 2) << 2;
-  const _u32 = new Uint32Array(buffer, 0, aLen >> 2);
+  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];
@@ -308,10 +309,9 @@ function decode(buffer, source) {
     const out = new Array(commentCount);
     for (let j = 0; j < commentCount; j++) {
       const o = cOff + j * 20;
-      const flags = _u8[o + 2];
+      const flags = _u8[o + 1];
       out[j] = {
         type: COMMENT_TYPES[_u8[o + 0]],
-        kind: COMMENT_KINDS[_u8[o + 1]],
         precededByNewline: (flags & 1) !== 0,
         followedByNewline: (flags & 2) !== 0,
         value: str(dv.getUint32(o + 12, true), dv.getUint32(o + 16, true)),

package/index.d.ts

@@ -45,23 +45,9 @@ interface ParseOptions {
 /** Whether a {@link Comment} came from a line or block source comment. */
 type CommentType = "Line" | "Block";
 
-/**
- * Semantic classification of a {@link Comment}, computed at parse time so
- * consumers can route comments without rescanning their value.
- *
- * - `"normal"`: plain comment with no special meaning.
- * - `"legal"`: `/*! ... *\/` or contains `@license`, `@preserve`, or `@cc_on`.
- * - `"jsdoc"`: `/** ... *\/` block.
- * - `"annotation"`: `/*# ... *\/` or `/*@ ... *\/` other than tree-shaking.
- * - `"pure"`: `/*#__PURE__*\/` or `/*@__PURE__*\/`.
- * - `"no_side_effects"`: `/*#__NO_SIDE_EFFECTS__*\/` or `/*@__NO_SIDE_EFFECTS__*\/`.
- */
-type CommentKind = "normal" | "legal" | "jsdoc" | "annotation" | "pure" | "no_side_effects";
-
 /** A source code comment. */
 interface Comment {
   type: CommentType;
-  kind: CommentKind;
   /** True when a line terminator immediately precedes this comment. */
   precededByNewline: boolean;
   /** True when a line terminator immediately follows this comment. */
@@ -103,6 +89,17 @@ interface Diagnostic {
   labels: DiagnosticLabel[];
 }
 
+/**
+ * A `(line, column)` pair into the source, matching ESTree's `loc` convention.
+ * Lines are 1-based; columns are 0-based.
+ */
+interface SourceLocation {
+  /** 1-based line number. */
+  line: number;
+  /** 0-based column number within the line. */
+  column: number;
+}
+
 /** The result returned by the parser. */
 interface ParseResult {
   /** Root ESTree/TypeScript-ESTree AST node. */
@@ -139,6 +136,20 @@ 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 {
@@ -1738,13 +1749,13 @@ export type {
   ParseResult,
   Comment,
   CommentType,
-  CommentKind,
   Diagnostic,
   DiagnosticLabel,
   DiagnosticSeverity,
   SourceType,
   ModuleKind,
   SourceLang,
+  SourceLocation,
   BaseNode,
   Span,
   Program,

package/index.js

@@ -16,3 +16,13 @@ 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.10",
+  "version": "0.5.14",
   "description": "High-performance JavaScript/TypeScript parser",
   "license": "MIT",
   "repository": {
@@ -17,17 +17,17 @@
     "decode.js"
   ],
   "optionalDependencies": {
-    "@yuku-parser/binding-linux-x64-gnu": "0.5.10",
-    "@yuku-parser/binding-linux-arm64-gnu": "0.5.10",
-    "@yuku-parser/binding-linux-arm-gnu": "0.5.10",
-    "@yuku-parser/binding-linux-x64-musl": "0.5.10",
-    "@yuku-parser/binding-linux-arm64-musl": "0.5.10",
-    "@yuku-parser/binding-linux-arm-musl": "0.5.10",
-    "@yuku-parser/binding-darwin-x64": "0.5.10",
-    "@yuku-parser/binding-darwin-arm64": "0.5.10",
-    "@yuku-parser/binding-win32-x64": "0.5.10",
-    "@yuku-parser/binding-win32-arm64": "0.5.10",
-    "@yuku-parser/binding-freebsd-x64": "0.5.10"
+    "@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"
   },
   "keywords": [
     "acorn",