yuku-codegen 0.5.9 → 0.5.10

package/README.md

@@ -1,8 +1,8 @@
 # yuku-codegen
 
-A high-performance JavaScript/TypeScript code generator written in Zig, powered by [Yuku](https://github.com/yuku-toolchain/yuku).
+A high-performance JavaScript and TypeScript code generator written in Zig, powered by [Yuku](https://github.com/yuku-toolchain/yuku).
 
-Renders an ESTree / TypeScript-ESTree AST back to source code, with optional Source Map V3 output. The input AST is exactly what [`yuku-parser`](https://www.npmjs.com/package/yuku-parser) produces.
+Renders an ESTree / TypeScript-ESTree AST back to source code, with optional Source Map V3 output. The input is exactly the `ParseResult` produced by [`yuku-parser`](https://www.npmjs.com/package/yuku-parser).
 
 ## Install
 
@@ -16,21 +16,23 @@ npm install yuku-codegen
 import { parse } from "yuku-parser";
 import { print } from "yuku-codegen";
 
-const { program } = parse("const x = 1 + 2;");
-const { code } = print(program);
+const ast = parse("const x = 1 + 2;");
+const { code } = print(ast);
 
 console.log(code); // "const x = 1 + 2;"
 ```
 
 ## API
 
-Three entry points share the same options shape:
+Three entry points share the same options and result shape. Each accepts the full `ParseResult` from `yuku-parser`.
 
-- `print(ast, options?)` renders verbatim, preserving TypeScript syntax.
-- `strip(ast, options?)` drops type-only syntax and emits plain JavaScript.
-- `minify(ast, options?)` applies size-reducing rewrites such as `true → !0` and shortest-numeric-form. Combine with `format: "compact"` for full minification.
+| Function | Behavior                                                                                              |
+| -------- | ----------------------------------------------------------------------------------------------------- |
+| `print`  | Renders verbatim, preserving TypeScript syntax.                                                       |
+| `strip`  | Drops type-only syntax and emits plain JavaScript. See [TypeScript stripping](#typescript-stripping). |
+| `minify` | Applies size-reducing rewrites at print time. See [Minification](#minification).                      |
 
-All return the same `CodegenResult`:
+All return a `CodegenResult`:
 
 ```ts
 interface CodegenResult {
@@ -40,7 +42,7 @@ interface CodegenResult {
 }
 ```
 
-`errors` is empty when codegen succeeded cleanly. `map` is populated only when `sourceMaps` is enabled.
+`errors` is empty on a clean run. `map` is non-null only when `sourceMaps` is set.
 
 ## Options
 
@@ -49,54 +51,54 @@ const result = print(ast, {
   format: "pretty",
   indent: 2,
   quotes: "double",
-  sourceMaps: { source },
+  comments: "some",
+  sourceMaps: { sourceFileName: "in.js" },
 });
 ```
 
-| Option       | Values                  | Default    | Description                                                                                |
-| ------------ | ----------------------- | ---------- | ------------------------------------------------------------------------------------------ |
-| `format`     | `"pretty"`, `"compact"` | `"pretty"` | Whitespace mode. `"compact"` emits only the separators the grammar requires.               |
-| `indent`     | `number`                | `2`        | Spaces per indentation level. Used only when `format` is `"pretty"`.                       |
-| `quotes`     | `"double"`, `"single"`  | `"double"` | Quote style for emitted string literals.                                                   |
-| `sourceMaps` | `SourceMapOptions`      | _disabled_ | Pass an object to emit a Source Map V3 alongside the code. Omit (or set to `null`) to skip. |
+| Option       | Type                                     | Default    | Description                                                                  |
+| ------------ | ---------------------------------------- | ---------- | ---------------------------------------------------------------------------- |
+| `format`     | `"pretty" \| "compact"`                  | `"pretty"` | Whitespace mode. `"compact"` emits only the separators the grammar requires. |
+| `indent`     | `number`                                 | `2`        | Spaces per indentation level. Applies in pretty mode only.                   |
+| `quotes`     | `"double" \| "single"`                   | `"double"` | Quote style for emitted string literals.                                     |
+| `comments`   | `boolean \| "some" \| "line" \| "block"` | `"some"`   | Comment passthrough filter. See [Comments](#comments).                       |
+| `sourceMaps` | `SourceMapOptions`                       | _disabled_ | Pass an object to emit a Source Map V3 alongside the code. Omit to skip.     |
 
 ## Source maps
 
-Pass `sourceMaps` to emit a Source Map V3 alongside the code. The original source text is required.
+Pass `sourceMaps` to emit a Source Map V3 alongside the generated code.
 
 ```js
 import { parse } from "yuku-parser";
 import { print } from "yuku-codegen";
 
 const source = `const greet = (name) => "Hello, " + name;`;
-const { program } = parse(source);
+const ast = parse(source);
 
-const { code, map } = print(program, {
+const { code, map } = print(ast, {
   sourceMaps: {
-    source,
     file: "out.js",
     sourceFileName: "in.js",
-    sourcesContent: true,
+    sourcesContent: source,
   },
 });
 
-await Bun.write("out.js", code + `\n//# sourceMappingURL=out.js.map`);
+await Bun.write("out.js", `${code}\n//# sourceMappingURL=out.js.map`);
 await Bun.write("out.js.map", JSON.stringify(map));
 ```
 
 ### `SourceMapOptions`
 
-| Field             | Type      | Required | Description                                                       |
-| ----------------- | --------- | -------- | ----------------------------------------------------------------- |
-| `source`          | `string`  | yes      | Original source the AST was parsed from.                          |
-| `file`            | `string`  | no       | Output filename, embedded as the map's `file`.                    |
-| `sourceFileName`  | `string`  | no       | Source filename, embedded as the single entry of `sources`.       |
-| `sourceRoot`      | `string`  | no       | Prefix embedded as `sourceRoot`.                                  |
-| `sourcesContent`  | `boolean` | no       | When `true`, embeds `source` into the map's `sourcesContent`.     |
+| Field            | Type     | Description                                                                         |
+| ---------------- | -------- | ----------------------------------------------------------------------------------- |
+| `file`           | `string` | Output filename, embedded as the map's `file`.                                      |
+| `sourceFileName` | `string` | Source filename, embedded as the single entry of `sources`.                         |
+| `sourceRoot`     | `string` | Prefix embedded as `sourceRoot`.                                                    |
+| `sourcesContent` | `string` | When set, embedded as the single entry of the map's `sourcesContent`. Omit to skip. |
 
-### Result
+### Output shape
 
-The returned `map` is a Source Map V3 object, ready to `JSON.stringify`:
+`map` is a Source Map V3 object, ready to serialize with `JSON.stringify`:
 
 ```ts
 interface SourceMap {
@@ -110,39 +112,57 @@ interface SourceMap {
 }
 ```
 
-Columns are 0-indexed UTF-16 code units, matching the convention used by Chrome DevTools and every consumer-side library (`@jridgewell/trace-mapping`, `source-map`, etc.).
+Columns are 0-indexed UTF-16 code units, matching Chrome DevTools and consumer-side libraries like `@jridgewell/trace-mapping` and `source-map`.
 
 ## TypeScript stripping
 
-`strip` rewrites the AST as plain JavaScript:
+`strip` rewrites the AST as plain JavaScript.
 
 ```js
 import { parse } from "yuku-parser";
 import { strip } from "yuku-codegen";
 
-const { program } = parse(`const x: number = 1;`, { lang: "ts" });
-console.log(strip(program).code); // "const x = 1;"
+const ast = parse(`const x: number = 1;`, { lang: "ts" });
+console.log(strip(ast).code); // "const x = 1;"
 ```
 
-Type annotations, type aliases, interfaces, and other type-only constructs are dropped. Constructs that don't have a clean JavaScript equivalent (`enum`, `namespace`, `import = require()`, `export =`) are reported in `errors` and elided. The output is always syntactically valid JavaScript.
+Type annotations, type aliases, interfaces, and other type-only constructs are dropped. Constructs that have no clean JavaScript equivalent (`enum`, `namespace`, `import = require()`, `export =`) are reported in `errors` and elided. The output is always syntactically valid JavaScript.
+
+## Comments
+
+The `comments` option selects which entries from `ast.comments` are emitted. The default is `"some"`, which matches the bundler convention of keeping legal banners, JSDoc, and tree-shaking annotations while dropping plain noise.
+
+| Value     | Behavior                                                        |
+| --------- | --------------------------------------------------------------- |
+| `"some"`  | Emit legal headers, JSDoc, and `@`/`#` annotations. _(default)_ |
+| `true`    | Emit every comment.                                             |
+| `false`   | Drop every comment.                                             |
+| `"line"`  | Emit `// ...` only.                                             |
+| `"block"` | Emit `/* ... */` only.                                          |
+
+```js
+const ast = parse(`// hello\nconst x = 1;`);
+print(ast, { comments: true }).code;
+// "// hello\nconst x = 1;"
+```
 
 ## Minification
 
 `minify` applies size-reducing rewrites at print time:
 
-- `true` / `false` → `!0` / `!1`
-- `undefined` → `void 0` (in expression position)
-- `Infinity` → `1/0`
-- numeric literals shortened to their shortest form (`1000000` → `1e6`, `0.5` → `.5`, etc.)
-- `obj["foo"]` → `obj.foo` when the key is a valid identifier
-- `{ "foo": x }` → `{ foo: x }` when safe
+- `true` and `false` rewrite to `!0` and `!1`.
+- `undefined` rewrites to `void 0` (in expression position).
+- `Infinity` rewrites to `1/0`.
+- Numeric literals shorten to their shortest form (`1000000` becomes `1e6`, `0.5` becomes `.5`).
+- `obj["foo"]` rewrites to `obj.foo` when the key is a valid identifier.
+- `{ "foo": x }` rewrites to `{ foo: x }` when safe.
 
 Combine with `format: "compact"` for full minification:
 
 ```js
 import { minify } from "yuku-codegen";
 
-const { code } = minify(program, { format: "compact" });
+const { code } = minify(ast, { format: "compact" });
 ```
 
 ## License

package/encode.js

@@ -4,12 +4,21 @@
 const NULL = 0xFFFFFFFF;
 const _enc = new TextEncoder();
 const NODE_SIZE = 48;
-const HEADER_SIZE = 36;
+const HEADER_SIZE = 40;
 const NODE_FLAGS_OFFSET = 2;
 const NODE_FIELD0_OFFSET = 4;
 const NODE_HEADER_U32S = 2;
 const NODE_SPAN_START_U32 = 10;
 const NODE_SPAN_END_U32 = 11;
+const COMMENT_SIZE = 20;
+const COMMENT_TYPE_OFFSET = 0;
+const COMMENT_KIND_OFFSET = 1;
+const COMMENT_FLAGS_OFFSET = 2;
+const COMMENT_START_OFFSET = 4;
+const COMMENT_END_OFFSET = 8;
+const COMMENT_VALUE_START_OFFSET = 12;
+const COMMENT_VALUE_END_OFFSET = 16;
+const COMMENT_KINDS_INV = {"normal": 0, "legal": 1, "jsdoc": 2, "annotation": 3, "pure": 4, "no_side_effects": 5};
 const BINARY_OPS_INV = {"==": 0, "!=": 1, "===": 2, "!==": 3, "<": 4, "<=": 5, ">": 6, ">=": 7, "+": 8, "-": 9, "*": 10, "/": 11, "%": 12, "**": 13, "|": 14, "^": 15, "&": 16, "<<": 17, ">>": 18, ">>>": 19, "in": 20, "instanceof": 21};
 const LOGICAL_OPS_INV = {"&&": 0, "||": 1, "??": 2};
 const UNARY_OPS_INV = {"-": 0, "+": 1, "!": 2, "~": 3, "typeof": 4, "void": 5, "delete": 6};
@@ -26,7 +35,7 @@ const IMPORT_PHASE_INV = {"source": 0, "defer": 1};
 const ACCESSIBILITY_INV = (v) => v == null ? 0 : v === "public" ? 1 : v === "private" ? 2 : 3;
 const TS_MAPPED_OPTIONAL_INV = (v) => v === true ? 1 : v === "+" ? 2 : v === "-" ? 3 : 0;
 const TS_MAPPED_READONLY_INV = (v) => v === true ? 1 : v === "+" ? 2 : v === "-" ? 3 : 0;
-function encode(estree) {
+function encode(estree, comments, lineStarts) {
   let nodeCap = 512;
   let nodeAB = new ArrayBuffer(nodeCap * NODE_SIZE);
   let nU8 = new Uint8Array(nodeAB);
@@ -2046,9 +2055,42 @@ function encode(estree) {
     }
   }
   const progIdx = encNode(estree);
+  // Comments are encoded after the node walk so string interning lands in the pool first.
+  const commentCount = Array.isArray(comments) ? comments.length : 0;
+  let commentBytes = null;
+  if (commentCount > 0) {
+    commentBytes = new ArrayBuffer(commentCount * COMMENT_SIZE);
+    const cU8 = new Uint8Array(commentBytes);
+    const cDV = new DataView(commentBytes);
+    for (let i = 0; i < commentCount; i++) {
+      const c = comments[i];
+      const v = encStr(typeof c.value === "string" ? c.value : "");
+      const kind = typeof c.kind === "string" ? (COMMENT_KINDS_INV[c.kind] ?? 0) : 0;
+      let flags = 0;
+      if (c.precededByNewline) flags |= 1;
+      if (c.followedByNewline) flags |= 2;
+      const o = i * COMMENT_SIZE;
+      cU8[o + COMMENT_TYPE_OFFSET] = c.type === "Block" ? 1 : 0;
+      cU8[o + COMMENT_KIND_OFFSET] = kind;
+      cU8[o + COMMENT_FLAGS_OFFSET] = flags;
+      cDV.setUint32(o + COMMENT_START_OFFSET, (c.start >>> 0), true);
+      cDV.setUint32(o + COMMENT_END_OFFSET, (c.end >>> 0), true);
+      cDV.setUint32(o + COMMENT_VALUE_START_OFFSET, v.start, true);
+      cDV.setUint32(o + COMMENT_VALUE_END_OFFSET, v.end, true);
+    }
+  }
+  const lineStartsCount = Array.isArray(lineStarts) ? lineStarts.length : 0;
+  let lineStartsBytes = null;
+  if (lineStartsCount > 0) {
+    lineStartsBytes = new ArrayBuffer(lineStartsCount * 4);
+    const lsDV = new DataView(lineStartsBytes);
+    for (let i = 0; i < lineStartsCount; i++) lsDV.setUint32(i * 4, lineStarts[i] >>> 0, true);
+  }
   const totalNodeBytes = nodeCount * NODE_SIZE;
   const totalExtraBytes = extraCount * 4;
-  const finalSize = HEADER_SIZE + totalNodeBytes + totalExtraBytes + poolLen;
+  const totalCommentBytes = commentCount * COMMENT_SIZE;
+  const totalLineStartsBytes = lineStartsCount * 4;
+  const finalSize = HEADER_SIZE + totalNodeBytes + totalExtraBytes + poolLen + totalCommentBytes + totalLineStartsBytes;
   const out = new ArrayBuffer(finalSize);
   const outU8 = new Uint8Array(out);
   const outU32 = new Uint32Array(out, 0, (finalSize >>> 2));
@@ -2056,14 +2098,22 @@ function encode(estree) {
   outU32[1] = extraCount;
   outU32[2] = poolLen;
   outU32[3] = 0;
-  outU32[4] = 0;
-  outU32[5] = 0;
-  outU32[6] = progIdx;
-  outU32[7] = 0;
+  outU32[4] = commentCount;
+  outU32[5] = lineStartsCount;
+  outU32[6] = 0;
+  outU32[7] = progIdx;
   outU32[8] = 0;
-  outU8.set(new Uint8Array(nodeAB, 0, totalNodeBytes), HEADER_SIZE);
-  outU8.set(new Uint8Array(extras.buffer, 0, totalExtraBytes), HEADER_SIZE + totalNodeBytes);
-  outU8.set(pool.subarray(0, poolLen), HEADER_SIZE + totalNodeBytes + totalExtraBytes);
+  outU32[9] = 0;
+  const nodesOff = HEADER_SIZE;
+  const extrasOff = nodesOff + totalNodeBytes;
+  const poolOff = extrasOff + totalExtraBytes;
+  const commentsOff = poolOff + poolLen;
+  const lineStartsOff = commentsOff + totalCommentBytes;
+  outU8.set(new Uint8Array(nodeAB, 0, totalNodeBytes), nodesOff);
+  outU8.set(new Uint8Array(extras.buffer, 0, totalExtraBytes), extrasOff);
+  outU8.set(pool.subarray(0, poolLen), poolOff);
+  if (commentBytes !== null) outU8.set(new Uint8Array(commentBytes), commentsOff);
+  if (lineStartsBytes !== null) outU8.set(new Uint8Array(lineStartsBytes), lineStartsOff);
   return out;
 }
 export { encode };

package/index.d.ts

@@ -1,4 +1,4 @@
-import type { Program } from "yuku-parser";
+import type { Comment, ParseResult } from "yuku-parser";
 
 /** Whitespace mode for the generated output. */
 export type Format = "pretty" | "compact";
@@ -6,21 +6,29 @@ export type Format = "pretty" | "compact";
 /** Quote style for emitted string literals. */
 export type Quotes = "double" | "single";
 
+/**
+ * Comment passthrough filter.
+ *
+ * - `false`: drop all comments.
+ * - `true` or `"all"`: emit every comment.
+ * - `"some"`: emit legal headers, JSDoc, and `@__*__` annotations.
+ * - `"line"`: emit `// ...` only.
+ * - `"block"`: emit block comments only.
+ */
+export type Comments = boolean | "all" | "some" | "line" | "block";
+
+export type { Comment };
+
 /** Source-map configuration. Pass to `CodegenOptions.sourceMaps` to enable. */
 export interface SourceMapOptions {
-  /** Original source the AST was parsed from. Required. */
-  source: string;
   /** Output filename, embedded as the map's `file`. */
   file?: string;
   /** Source filename, embedded as the single entry of `sources`. */
   sourceFileName?: string;
   /** Prefix embedded as `sourceRoot`. */
   sourceRoot?: string;
-  /**
-   * When true, embeds `source` into `sourcesContent`.
-   * @default false
-   */
-  sourcesContent?: boolean;
+  /** When set, embedded as the single entry of the map's `sourcesContent`. */
+  sourcesContent?: string;
 }
 
 /** Codegen options shared by `print`, `strip`, and `minify`. */
@@ -36,6 +44,12 @@ export interface CodegenOptions {
   quotes?: Quotes;
   /** Pass to enable source maps. Omit to disable. */
   sourceMaps?: SourceMapOptions;
+  /**
+   * Comment passthrough filter. Defaults to `"some"`, which preserves
+   * legal headers, JSDoc, and tree-shaking annotations.
+   * @default "some"
+   */
+  comments?: Comments;
 }
 
 /** A codegen-detected problem in the input AST. */
@@ -69,13 +83,13 @@ export interface CodegenResult {
 }
 
 /** Renders the AST verbatim, preserving TypeScript syntax. */
-export function print(estree: Program, options?: CodegenOptions): CodegenResult;
+export function print(ast: ParseResult, options?: CodegenOptions): CodegenResult;
 
 /** Renders the AST as JavaScript, dropping TypeScript-specific syntax. */
-export function strip(estree: Program, options?: CodegenOptions): CodegenResult;
+export function strip(ast: ParseResult, options?: CodegenOptions): CodegenResult;
 
 /**
  * Renders the AST with size-reducing rewrites. Combine with
  * `format: "compact"` for full minification.
  */
-export function minify(estree: Program, options?: CodegenOptions): CodegenResult;
+export function minify(ast: ParseResult, options?: CodegenOptions): CodegenResult;

package/index.js

@@ -1,14 +1,26 @@
 import binding from "./binding.js";
 import { encode } from "./encode.js";
 
-export function print(estree, options) {
-  return binding.print(encode(estree), options ?? {});
+function normalizeOptions(options) {
+  if (options == null) return {};
+  const c = options.comments;
+  if (c === true) return { ...options, comments: "all" };
+  if (c === false) return { ...options, comments: "none" };
+  return options;
 }
 
-export function strip(estree, options) {
-  return binding.strip(encode(estree), options ?? {});
+function encodeAst(ast) {
+  return encode(ast.program, ast.comments, ast.lineStarts);
 }
 
-export function minify(estree, options) {
-  return binding.minify(encode(estree), options ?? {});
+export function print(ast, options) {
+  return binding.print(encodeAst(ast), normalizeOptions(options));
+}
+
+export function strip(ast, options) {
+  return binding.strip(encodeAst(ast), normalizeOptions(options));
+}
+
+export function minify(ast, options) {
+  return binding.minify(encodeAst(ast), normalizeOptions(options));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yuku-codegen",
-  "version": "0.5.9",
+  "version": "0.5.10",
   "description": "High-performance JavaScript/TypeScript code generator written in Zig",
   "license": "MIT",
   "repository": {
@@ -17,29 +17,29 @@
     "encode.js"
   ],
   "optionalDependencies": {
-    "@yuku-codegen/binding-linux-x64-gnu": "0.5.9",
-    "@yuku-codegen/binding-linux-arm64-gnu": "0.5.9",
-    "@yuku-codegen/binding-linux-arm-gnu": "0.5.9",
-    "@yuku-codegen/binding-linux-x64-musl": "0.5.9",
-    "@yuku-codegen/binding-linux-arm64-musl": "0.5.9",
-    "@yuku-codegen/binding-linux-arm-musl": "0.5.9",
-    "@yuku-codegen/binding-darwin-x64": "0.5.9",
-    "@yuku-codegen/binding-darwin-arm64": "0.5.9",
-    "@yuku-codegen/binding-win32-x64": "0.5.9",
-    "@yuku-codegen/binding-win32-arm64": "0.5.9",
-    "@yuku-codegen/binding-freebsd-x64": "0.5.9"
-  },
-  "dependencies": {
-    "yuku-parser": "workspace:*"
+    "@yuku-codegen/binding-linux-x64-gnu": "0.5.10",
+    "@yuku-codegen/binding-linux-arm64-gnu": "0.5.10",
+    "@yuku-codegen/binding-linux-arm-gnu": "0.5.10",
+    "@yuku-codegen/binding-linux-x64-musl": "0.5.10",
+    "@yuku-codegen/binding-linux-arm64-musl": "0.5.10",
+    "@yuku-codegen/binding-linux-arm-musl": "0.5.10",
+    "@yuku-codegen/binding-darwin-x64": "0.5.10",
+    "@yuku-codegen/binding-darwin-arm64": "0.5.10",
+    "@yuku-codegen/binding-win32-x64": "0.5.10",
+    "@yuku-codegen/binding-win32-arm64": "0.5.10",
+    "@yuku-codegen/binding-freebsd-x64": "0.5.10"
   },
   "keywords": [
-    "codegen",
-    "javascript",
-    "typescript",
     "ast",
+    "codegen",
     "estree",
-    "printer",
+    "javascript",
     "minifier",
-    "napi"
-  ]
+    "napi",
+    "printer",
+    "typescript"
+  ],
+  "dependencies": {
+    "yuku-parser": "workspace:*"
+  }
 }