ember.nvp 1.7.0 → 1.7.1

package/packages/rolldown/README.md

@@ -1,11 +1,11 @@
 # `@nullvoxpopuli/ember-rolldown`
 
 A batteries-included meta-plugin for building Ember v2 libraries (addons) with
-[rolldown](https://rolldown.rs/) — or [tsdown](https://tsdown.dev/), which is
-built on top of rolldown and also emits `.d.ts` files.
+[rolldown](https://rolldown.rs/), or with [tsdown](https://tsdown.dev/), which
+is built on top of rolldown and also emits `.d.ts` files.
 
-It compiles `.gts`/`.gjs` and template-tag (`<template>`) source into
-publishable output, so a single `ember()` call replaces the usual stack of
+It compiles `.gts` / `.gjs` and template-tag (`<template>`) source into
+publishable output. A single `ember()` call replaces the usual stack of
 `@embroider/*` externals handling, content-tag preprocessing, and babel wiring.
 
 ## Install
@@ -14,17 +14,18 @@ publishable output, so a single `ember()` call replaces the usual stack of
 npm add --save-dev @nullvoxpopuli/ember-rolldown
 ```
 
-Requires node 24+, and — since these packages ship TypeScript source — a
-modern TypeScript when type-checking: 6+ with `lib` covering `es2025` (e.g.
-`esnext`).
+Requires node 24+.
+
+These packages ship TypeScript source, so type-checking needs a modern
+TypeScript: 6+ with `lib` covering `es2025` (e.g. `esnext`).
 
 ## Usage
 
-Import `defineConfig` from the bundler you're using — `tsdown` or `rolldown` —
-so it carries that tool's own config types; `@nullvoxpopuli/ember-rolldown`
-provides `ember()` (the defaults travel with the plugin, not `defineConfig`).
+Import `defineConfig` from the bundler you use, `tsdown` or `rolldown`, so it
+carries that tool's own config types. `@nullvoxpopuli/ember-rolldown` provides
+`ember()`. The defaults travel with the plugin, not with `defineConfig`.
 
-In your `tsdown.config.js` (recommended — emits declarations):
+In your `tsdown.config.js` (recommended, because it emits declarations):
 
 ```js
 import { defineConfig } from "tsdown";
@@ -36,10 +37,10 @@ export default defineConfig({
 });
 ```
 
-This builds your entry to `dist/*.js` and `dist/*.d.ts` with sourcemaps,
-cleaning `dist/` between builds and leaving the ember virtual packages to the
-consuming app. You choose the `entry` and `plugins`; any tsdown option you
-pass wins.
+This builds your entry to `dist/*.js` and `dist/*.d.ts` with sourcemaps. It
+cleans `dist/` between builds and leaves the ember virtual packages to the
+consuming app. You choose the `entry` and `plugins`. Any tsdown option you pass
+wins.
 
 Or in a plain `rolldown.config.js`:
 
@@ -53,16 +54,16 @@ export default defineConfig({
 });
 ```
 
-A babel config is optional. Without one, `ember()` compiles templates
-(to `precompileTemplate`), decorators (via
+A babel config is optional. Without one, `ember()` compiles templates (to
+`precompileTemplate`), decorators (via
 [decorator-transforms](https://github.com/ef4/decorator-transforms)), and
-TypeScript; with one, your config runs instead. A `babel.publish.config.*` is
-preferred over a `babel.config.*` — see
+TypeScript. With one, your config runs instead. A `babel.publish.config.*` is
+preferred over a `babel.config.*`. See
 [Publish vs. development babel config](#publish-vs-development-babel-config).
 
 ### Entrypoints
 
-Entries may be any extension — `.ts`, `.js`, `.gts`, `.gjs`:
+Entries may be any extension: `.ts`, `.js`, `.gts`, `.gjs`.
 
 ```js
 export default defineConfig({
@@ -72,19 +73,20 @@ export default defineConfig({
 ```
 
 Whatever the source extension, the emitted `.js` and `.d.ts` paths mirror the
-entry paths (that's how tsdown's dts support works): the example emits
-`dist/index.js` + `dist/index.d.ts` and `dist/components/menu.js` +
-`dist/components/menu.d.ts`. Type imports resolve against those emitted
-paths, so your entries — together with your `exports` map — _are_ your
-public API: a module that isn't an entry has no stable `dist/` path of its
-own and is only reachable through the entrypoints that re-export it.
+entry paths. The example emits `dist/index.js` + `dist/index.d.ts` and
+`dist/components/menu.js` + `dist/components/menu.d.ts`.
+
+Type imports resolve against those emitted paths. So your entries, together
+with your `exports` map, _are_ your public API. A module that isn't an entry has
+no stable `dist/` path of its own. It is only reachable through the entrypoints
+that re-export it.
 
 ### Declarations
 
-Declarations are emitted with isolated declarations — the only declaration
-pipeline that can see `<template>` (`.gts`/`.gjs`) modules, which exist only
-inside the bundler's module graph. The tsconfig your build uses must enable it
-(`ember()` errors otherwise):
+Declarations are emitted with isolated declarations. That is the only
+declaration pipeline that can see `<template>` (`.gts` / `.gjs`) modules, which
+exist only inside the bundler's module graph. The tsconfig your build uses must
+enable it. `ember()` errors otherwise.
 
 ```jsonc
 {
@@ -106,14 +108,16 @@ export const Badge: TOC<BadgeSignature> = <template>...</template>;
 #### Keeping the constraint off dev-only code
 
 `isolatedDeclarations` is a constraint on how _published_ code is written, so it
-should cover only the code you emit declarations for. If your package also holds
-dev-only code — a demo app, in-package tests — putting the flag on the single
-`tsconfig.json` that covers everything would force explicit annotations on demo
-components and test helpers that never get a `.d.ts` emitted for them.
+must cover only the code you emit declarations for.
+
+If your package also holds dev-only code (a demo app, in-package tests), putting
+the flag on the single `tsconfig.json` that covers everything would force
+explicit annotations on demo components and test helpers that never get a
+`.d.ts`.
 
 The tsconfig `ember()` checks is the one
-[tsdown's `tsconfig` option](https://tsdown.dev/options/tsconfig) points at, so
-point the build at a publish-only config and leave `tsconfig.json` alone for
+[tsdown's `tsconfig` option](https://tsdown.dev/options/tsconfig) points at. So
+point the build at a publish-only config, and leave `tsconfig.json` alone for
 editors and `tsc --noEmit`:
 
 ```js
@@ -127,21 +131,21 @@ export default defineConfig({
 ```
 
 Any path works, so the publish config can live wherever you keep build
-configuration — `tsconfig: "./config/tsconfig.publish.json"`. (A directory works
-too: `tsconfig: "./config"` picks up `config/tsconfig.json`.)
+configuration: `tsconfig: "./config/tsconfig.publish.json"`. A directory works
+too: `tsconfig: "./config"` picks up `config/tsconfig.json`.
 
-`tsconfig: false` is rejected while declarations are on: with no tsconfig there
+`tsconfig: false` is rejected while declarations are on. With no tsconfig there
 is no `isolatedDeclarations`, and the fallback pipeline can't see compiled
 `.gts`, so it would fail later with "Source file not found". Set `dts: false`
 alongside it if the library ships no types.
 
-A tsconfig's relative paths resolve against the file itself, so a config kept in
+A tsconfig's relative paths resolve against the file itself. So a config kept in
 `config/` wants `"include": ["../src/**/*"]` and `"rootDir": "../src"`. The build
-won't tell you if you get that wrong — tsdown drives declaration emit from
-`entry`, not from the tsconfig's `include` — but `tsc`/`ember-tsc` and your
-editor will, if you ever point them at that config.
+won't tell you if you get that wrong, because tsdown drives declaration emit
+from `entry`, not from the tsconfig's `include`. `tsc` / `ember-tsc` and your
+editor will tell you, if you ever point them at that config.
 
-The tradeoff: isolated-declaration errors in `src` then surface when you build
+The tradeoff: isolated-declaration errors in `src` then surface when you build,
 rather than in your editor, since the editor uses `tsconfig.json`. Run the build
 (or `tsc --noEmit -p tsconfig.publish.json`) in CI so nothing lands unchecked.
 
@@ -149,24 +153,24 @@ rather than in your editor, since the editor uses `tsconfig.json`. Run the build
 
 Components that import co-located CSS (`import './popup.css'`) need
 [`@tsdown/css`](https://www.npmjs.com/package/@tsdown/css) installed in your
-library — tsdown auto-detects it and bundles every imported stylesheet into a
-single CSS file in `dist/`. Install the version matching your `tsdown`
-version (they're released in lockstep):
+library. tsdown auto-detects it and bundles every imported stylesheet into a
+single CSS file in `dist/`. Install the version matching your `tsdown` version.
+They are released in lockstep.
 
 ```bash
 npm add --save-dev @tsdown/css
 ```
 
-Without it, tsdown's css-guard fails the build on the first CSS import — and
-because the importing component module never loads, any declaration that
-references that component dangles, surfacing as misleading
-`UNLOADABLE_DEPENDENCY` errors on `<component>.d.ts` files.
+Without it, tsdown's css-guard fails the build on the first CSS import. Because
+the importing component module never loads, any declaration that references
+that component dangles. That surfaces as misleading `UNLOADABLE_DEPENDENCY`
+errors on `<component>.d.ts` files.
 
 ### ember-scoped-css
 
 [ember-scoped-css](https://github.com/auditboard/ember-scoped-css) works with
-this pipeline: its template transform rides along via `ember()`'s
-`babel.templateTransforms` option, and its unplugin (`ember-scoped-css/rollup`)
+this pipeline. Its template transform rides along via `ember()`'s
+`babel.templateTransforms` option. Its unplugin (`ember-scoped-css/rollup`)
 resolves the scoped CSS requests the transform injects:
 
 ```js
@@ -191,33 +195,32 @@ export default defineConfig({
 ```
 
 This scopes co-located `.css` files, inline `<style scoped>` blocks, and the
-`scopedClass` pseudo-helper (that last one is what the `babel.plugins` entry
-handles — leave it off if you don't use `scopedClass` in module code).
+`scopedClass` pseudo-helper. That last one is what the `babel.plugins` entry
+handles. Leave it off if you don't use `scopedClass` in module code.
 
-`css.inject` matters for libraries: it keeps the `import "./style.css"`
-statement in `dist/index.js`, so consuming apps pull the styles in through
-the module graph — without it the bundled CSS is emitted but nothing loads
-it.
+`css.inject` matters for libraries. It keeps the `import "./style.css"`
+statement in `dist/index.js`, so consuming apps pull the styles in through the
+module graph. Without it, the bundled CSS is emitted but nothing loads it.
 
 ## What `ember()` does
 
 `ember()` returns an array of rolldown plugins:
 
-- **`emberIsolatedDeclarations()`** — errors when the tsconfig the build uses
+- **`emberIsolatedDeclarations()`** errors when the tsconfig the build uses
   (tsdown's `tsconfig` option, defaulting to `tsconfig.json`) is present without
   `isolatedDeclarations: true`.
-- **`emberExternals()`** — keeps your `dependencies`, `peerDependencies`, and
-  the ember virtual packages (e.g. `@ember/component`, `@glimmer/tracking`, the
+- **`emberExternals()`** keeps your `dependencies`, `peerDependencies`, and the
+  ember virtual packages (e.g. `@ember/component`, `@glimmer/tracking`, the
   template compiler) external, so the consuming app resolves them.
-- **`emberBundle()`** — bundle mode only, in place of `emberExternals()`: makes
-  the ember virtual packages resolvable, so they can be bundled.
-- **`emberTransform()`** — preprocesses `<template>` via
+- **`emberBundle()`** replaces `emberExternals()` in bundle mode. It makes the
+  ember virtual packages resolvable, so they can be bundled.
+- **`emberTransform()`** preprocesses `<template>` via
   [content-tag](https://github.com/embroider-build/content-tag) and maps
-  `.gts`/`.gjs` to `.ts`/`.js` so rolldown understands them. Also rewrites
-  `.gts` specifiers in emitted `.d.ts` files.
-- **`emberBabel()`** — runs babel with `babelHelpers: "bundled"`, but only on
-  the files that actually need it (template-tag, decorators, template imports);
-  everything else stays on rolldown's fast native (oxc) transform. Uses your
+  `.gts` / `.gjs` to `.ts` / `.js` so rolldown understands them. It also
+  rewrites `.gts` specifiers in emitted `.d.ts` files.
+- **`emberBabel()`** runs babel with `babelHelpers: "bundled"`, but only on the
+  files that need it (template-tag, decorators, template imports). Everything
+  else stays on rolldown's fast native (oxc) transform. It uses your
   `babel.publish.config.*` (root or `config/`) in preference to your
   `babel.config.*`.
 
@@ -236,11 +239,12 @@ ember({
 });
 ```
 
-Each option is documented on `BabelOptions`. `templateTransforms` feeds
-template AST transforms to the default template-compilation step; it can't be
-combined with a babel config file — a config lists
-`babel-plugin-ember-template-compilation` itself, so its transforms belong
-there.
+Each option is documented on `BabelOptions`.
+
+`templateTransforms` feeds template AST transforms to the default
+template-compilation step. It can't be combined with a babel config file. A
+config lists `babel-plugin-ember-template-compilation` itself, so its
+transforms belong there.
 
 ### Bundle mode
 
@@ -276,12 +280,13 @@ Do not combine bundle mode with tsdown's `unbundle` option.
 
 ### Publish vs. development babel config
 
-A library's plain `babel.config.*` is usually its _development_ config: it
+A library's plain `babel.config.*` is usually its _development_ config. It
 compiles `@embroider/macros` away, targets the wire format, and wires up
-whatever the in-package demo app or test suite needs. None of that belongs in a
-published artifact — macros must survive for the consuming app to evaluate, and
-the wire format is private between one template compiler and one glimmer
-runtime of the same version.
+whatever the in-package demo app or test suite needs.
+
+None of that belongs in a published artifact. Macros must survive for the
+consuming app to evaluate. The wire format is private between one template
+compiler and one glimmer runtime of the same version.
 
 Babel's own resolution can't tell those apart, so `ember()` looks for a config
 named for publishing first. With no explicit `configFile`, detection is:
@@ -289,8 +294,8 @@ named for publishing first. With no explicit `configFile`, detection is:
 1. `babel.publish.config.{mjs,cjs,js,mts,cts,ts,json}` in the package root
 2. the same names in `config/`
 3. otherwise babel's own resolution (`babel.config.*`, honoring `rootMode`)
-4. otherwise no config file — templates, decorators and TypeScript are still
-   handled by the built-in defaults
+4. otherwise no config file. Templates, decorators and TypeScript are still
+   handled by the built-in defaults.
 
 So a library that keeps both configs needs no `babel` option at all:
 
@@ -307,18 +312,18 @@ my-addon/
   babel.config.mjs
   config/
     babel.publish.config.mjs  # what ember() uses
-    tsconfig.publish.json     # see below
+    tsconfig.publish.json     # see above
 ```
 
-Set `configFile` explicitly to override that (`configFile: false` ignores config
-files entirely, which is what you want when your publish config would just
-restate the built-in defaults).
+Set `configFile` explicitly to override that. `configFile: false` ignores
+config files entirely. That is what you want when your publish config would
+only restate the built-in defaults.
 
 ## App re-exports
 
-For libraries whose modules must appear in the consuming app's namespace
-(classic resolution: `{{a-component}}`, services and helpers looked up by
-name), `appReexports()` does the same job as `@embroider/addon-dev`'s
+Some libraries need their modules to appear in the consuming app's namespace
+for classic resolution: `{{a-component}}`, services and helpers looked up by
+name. For those, `appReexports()` does the same job as `@embroider/addon-dev`'s
 `appReexports` rollup plugin. It's a separate import because most libraries
 don't need it:
 
@@ -333,10 +338,12 @@ export default defineConfig({
 });
 ```
 
-With no arguments, top-level services (`services/*`) are re-exported — under
+With no arguments, top-level services (`services/*`) are re-exported. Under
 strict mode, components and helpers are imported, but services are still
-injected by name. A string or array of strings is the include glob(s),
-optionally followed by the remaining options; an object gives full control:
+injected by name.
+
+A string or array of strings is the include glob(s), optionally followed by the
+remaining options. An object gives full control:
 
 ```js
 appReexports(); // services/*
@@ -346,16 +353,14 @@ appReexports("components/**", { exclude: ["components/-private/**"] });
 appReexports({ include: ["services/*", "helpers/*"], exclude: [...] });
 ```
 
-For every built file matching `include` (minus `exclude` and `.d.ts` files),
-it writes a module under `dist/_app_/` re-exporting from the library's own
-name, and records the set in `package.json` under `ember-addon.app-js`.
-`mapFilename` renames a re-export; `exports` picks which bindings it forwards
+For every built file matching `include` (minus `exclude` and `.d.ts` files), it
+writes a module under `dist/_app_/` re-exporting from the library's own name,
+and records the set in `package.json` under `ember-addon.app-js`.
+`mapFilename` renames a re-export. `exports` picks which bindings it forwards
 (default `["default"]`).
 
-Unlike the embroider plugin, nothing is written unless its content actually
-differs from what is on disk — `_app_/` modules are compared byte-for-byte
-and `package.json` is only rewritten when the `app-js` map itself changed —
-so rebuilds don't re-trigger file watchers.
+Nothing is written unless its content differs from what is on disk, so rebuilds
+don't re-trigger file watchers.
 
 ## Credit
 

package/packages/rolldown/index.ts

@@ -27,39 +27,52 @@ interface Config {
    */
   bundle?: boolean;
   /**
-   * Options for the babel step; see `BabelOptions`.
+   * Options for the babel step.
+   * See `BabelOptions`.
    */
   babel?: BabelOptions;
 }
 
 /**
- * A batteries-included plugin for building Ember v2 libraries (addons) with
- * rolldown (or tsdown, which is built on rolldown).
+ * A batteries-included plugin for building Ember v2 libraries (addons)
+ * with rolldown, or with tsdown (which is built on rolldown).
  *
- * It bundles everything needed to compile `.gts`/`.gjs` and template-tag
- * (`<template>`) source into publishable output:
+ * It bundles everything needed to compile `.gts` / `.gjs` and
+ * template-tag (`<template>`) source into publishable output:
  *
- * - `emberConfig()` — applies sensible tsdown defaults for a library build
- *   (sourcemaps, `clean`, `dts`, `.js`/`.d.ts` extensions, quiet logging);
- *   anything you set explicitly still wins.
- * - `emberIsolatedDeclarations()` — errors when a tsconfig.json is present
- *   without `isolatedDeclarations: true` (required: it is the only
- *   declaration pipeline that can see compiled template-tag modules).
- * - `emberExternals()` — keeps your dependencies, peerDependencies, and the
- *   ember virtual packages external, so consuming apps resolve them.
- * - `emberBundle()` — bundle mode only, in place of `emberExternals()`:
- *   aliases the ember virtual packages into ember-source,
+ * - `emberConfig()`
+ *   applies sensible tsdown defaults for a library build
+ *   (sourcemaps, `clean`, `dts`, `.js` / `.d.ts` extensions, quiet logging).
+ *   Anything you set explicitly still wins.
+ *
+ * - `emberIsolatedDeclarations()`
+ *   errors when a tsconfig.json is present without `isolatedDeclarations: true`.
+ *   That is the only declaration pipeline that can see compiled template-tag modules.
+ *
+ * - `emberExternals()`
+ *   keeps your dependencies, peerDependencies, and the ember virtual packages external,
+ *   so consuming apps resolve them.
+ *
+ * - `emberBundle()`
+ *   bundle mode only, in place of `emberExternals()`.
+ *   Aliases the ember virtual packages into ember-source,
  *   whose export conditions pick the build to bundle.
- * - `emberTransform()` — preprocesses `<template>` via content-tag and maps
- *   `.gts`/`.gjs` to `.ts`/`.js` so rolldown can understand them.
- * - `emberBabel()` — runs babel (template compilation, decorators, type
- *   stripping) with `babelHelpers: "bundled"`, but only on the files that
- *   actually need it (via `maybeBabel`); everything else stays on the fast
- *   native transform. The library's own `babel.config.js` is used when it
- *   exists; no config file is required.
  *
- * Usage in `tsdown.config.js` (import `defineConfig` from `tsdown` — or from
- * `rolldown` for a `rolldown.config.js` — so it carries the correct types):
+ * - `emberTransform()`
+ *   preprocesses `<template>` via content-tag,
+ *   and maps `.gts` / `.gjs` to `.ts` / `.js` so rolldown can understand them.
+ *
+ * - `emberBabel()`
+ *   runs babel (template compilation, decorators, type stripping)
+ *   with `babelHelpers: "bundled"`.
+ *   Only the files that need it go through babel (via `maybeBabel`).
+ *   Everything else stays on the fast native transform.
+ *   The library's own `babel.config.js` is used when it exists.
+ *   No config file is required.
+ *
+ * Usage in `tsdown.config.js`.
+ * Import `defineConfig` from `tsdown` (or from `rolldown` for a `rolldown.config.js`)
+ * so it carries the correct types:
  *
  * ```js
  * import { defineConfig } from "tsdown";

package/packages/rolldown/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nullvoxpopuli/ember-rolldown",
-  "version": "2.8.0",
+  "version": "2.8.1",
   "description": "Meta plugin for building ember v2 libraries/addons with rolldown & tsdown.",
   "type": "module",
   "main": "index.ts",

package/packages/rolldown/src/app-reexports.test.ts

@@ -8,9 +8,10 @@ import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { appReexports, type AppReexportsOptions } from "./app-reexports.ts";
 
 /**
- * The plugin reads and writes package.json relative to the current working
- * directory (matching the other plugins in this package), so each test runs
- * inside its own temp project.
+ * The plugin reads and writes package.json relative to the current working directory
+ * (matching the other plugins in this package).
+ *
+ * So each test runs inside its own temp project.
  */
 describe("appReexports", () => {
   let projectDir: string;

package/packages/rolldown/src/app-reexports.ts

@@ -5,13 +5,14 @@ import type { RolldownPluginLike } from "./plugin-like.ts";
 
 export interface AppReexportsOptions {
   /**
-   * Globs, matched against each built filename (relative to the output
-   * directory), selecting which modules get an app re-export.
+   * Globs selecting which modules get an app re-export.
+   * Matched against each built filename, relative to the output directory.
    *
-   * Defaults to `["services/*"]` -- top-level services only. Under strict
-   * mode, components and helpers are imported, but services are still
-   * injected by name, so they are the one thing an app must always be able
-   * to resolve.
+   * Defaults to `["services/*"]`: top-level services only.
+   *
+   * Under strict mode, components and helpers are imported.
+   * Services are still injected by name,
+   * so they are the one thing an app must always be able to resolve.
    *
    * `.d.ts` files never match.
    */
@@ -23,33 +24,39 @@ export interface AppReexportsOptions {
   exclude?: string[];
 
   /**
-   * Rename a re-export: receives the built filename, returns the filename the
-   * app sees. Defaults to the built filename unchanged.
+   * Rename a re-export.
+   *
+   * Receives the built filename, returns the filename the app sees.
+   * Defaults to the built filename unchanged.
    */
   mapFilename?: (filename: string) => string;
 
   /**
-   * Which bindings a file's re-export module forwards: an array of names
-   * (default `["default"]`), or a raw export clause string such as `"*"`.
+   * Which bindings a file's re-export module forwards:
+   * - an array of names (default `["default"]`)
+   * - or a raw export clause string such as `"*"`
    */
   exports?: (filename: string) => string[] | string | undefined;
 }
 
 /**
- * Merges built modules into the consuming app's namespace, so classic
- * resolution (`{{a-component}}`, service/helper lookup by name) finds them --
- * the same job as `@embroider/addon-dev`'s `appReexports` rollup plugin.
+ * Merges built modules into the consuming app's namespace,
+ * so classic resolution finds them
+ * (`{{a-component}}`, service / helper lookup by name).
+ *
+ * The same job as `@embroider/addon-dev`'s `appReexports` rollup plugin.
  *
- * For every built file matching `include` (minus `exclude` and `.d.ts`), it
- * writes a tiny module under `<outDir>/_app_/` re-exporting from the
- * library's own name, and records the full set in `package.json` under
- * `ember-addon.app-js`.
+ * For every built file matching `include` (minus `exclude` and `.d.ts`):
+ * - writes a tiny module under `<outDir>/_app_/`,
+ *   re-exporting from the library's own name
+ * - records the full set in `package.json` under `ember-addon.app-js`
  *
- * Unlike the embroider plugin, nothing is written unless its content actually
- * differs from what is on disk: the `_app_/` modules are compared
- * byte-for-byte, and `package.json` is only rewritten when the `app-js` map
- * itself changed (so an equivalent map in different formatting is left
- * alone). This keeps rebuilds from re-triggering file watchers.
+ * Nothing is written unless its content differs from what is on disk:
+ * - the `_app_/` modules are compared byte-for-byte
+ * - `package.json` is only rewritten when the `app-js` map itself changed
+ *   (an equivalent map in different formatting is left alone)
+ *
+ * This keeps rebuilds from re-triggering file watchers.
  *
  * This is a separate import, because most libraries don't need it:
  *
@@ -64,9 +71,12 @@ export interface AppReexportsOptions {
  * });
  * ```
  *
- * With no arguments, top-level services (`services/*`) are re-exported. A
- * string or array of strings is the include glob(s), optionally followed by
- * the remaining options; an object gives full control:
+ * With no arguments, top-level services (`services/*`) are re-exported.
+ *
+ * The first argument can be:
+ * - a string or array of strings: the include glob(s),
+ *   optionally followed by the remaining options
+ * - an object: full control
  *
  * ```js
  * appReexports();                          // services/*
@@ -97,7 +107,7 @@ export function appReexports(
       const appJs: Record<string, string> = {};
 
       // Sorted so the app-js map (and therefore package.json) is stable
-      // across builds regardless of chunk emission order.
+      // across builds, regardless of chunk emission order.
       for (const builtFilename of Object.keys(bundle).sort()) {
         if (!isIncluded(builtFilename, include, resolved.exclude)) continue;
 
@@ -143,7 +153,7 @@ function writeFileIfChanged(path: string, content: string) {
   try {
     existing = readFileSync(path, { encoding: "utf8" });
   } catch {
-    // Doesn't exist yet (or isn't readable) -- write it.
+    // Doesn't exist yet (or isn't readable): write it.
   }
 
   if (existing === content) return;

package/packages/rolldown/src/babel.test.ts

@@ -15,8 +15,9 @@ afterEach(() => {
 });
 
 /**
- * A babel config whose only plugin rewrites the string `"MARKER"` to `name`, so
- * the emitted code says which config file babel actually loaded.
+ * A babel config whose only plugin rewrites the string `"MARKER"` to `name`.
+ *
+ * So the emitted code says which config file babel loaded.
  */
 function markerConfig(name: string): string {
   return [
@@ -37,9 +38,13 @@ function markerConfig(name: string): string {
 }
 
 /**
- * Builds a `.gts` entry (so babel actually runs -- `maybeBabel` skips files that
- * need no transform) in a temp dir that becomes the cwd, the way config
- * detection sees it under the tsdown CLI. Returns the emitted code.
+ * Builds a `.gts` entry in a temp dir that becomes the cwd,
+ * the way config detection sees it under the tsdown CLI.
+ *
+ * A `.gts` entry so babel runs at all:
+ * `maybeBabel` skips files that need no transform.
+ *
+ * Returns the emitted code.
  */
 async function bundleWithBabel(
   files: Record<string, string>,