ember.nvp 1.7.0 → 1.8.0

package/packages/rolldown/src/babel.ts

@@ -28,14 +28,15 @@ export interface BabelOptions {
   /**
    * The babel config file to use.
    *
-   * - `undefined`: auto-detect. A `babel.publish.config.*` (in the package root
-   *   or `config/`) wins, because this is a publish build; otherwise babel's own
-   *   config resolution applies (see `detectConfigFile`).
+   * - `undefined`: auto-detect.
+   *   A `babel.publish.config.*` (in the package root or `config/`) wins,
+   *   because this is a publish build.
+   *   Otherwise babel's own config resolution applies (see `detectConfigFile`).
    * - a string: use that config file.
    * - `false`: ignore config files entirely.
    *
-   * Without a config file, templates, decorators, and TypeScript are still
-   * handled (see `defaultPlugins`).
+   * Without a config file, templates, decorators, and TypeScript are still handled
+   * (see `defaultPlugins`).
    */
   configFile?: string | false;
   /**
@@ -43,17 +44,20 @@ export interface BabelOptions {
    */
   plugins?: PluginItem[];
   /**
-   * Template AST transforms (e.g. ember-scoped-css's `scopedCSS.template()`)
-   * passed to the default `babel-plugin-ember-template-compilation` entry.
+   * Template AST transforms passed to the default
+   * `babel-plugin-ember-template-compilation` entry.
+   *   e.g. ember-scoped-css's `scopedCSS.template()`
    *
-   * Only valid without a babel config file: with your own config, you list
-   * `babel-plugin-ember-template-compilation` yourself, so its `transforms`
-   * belong there.
+   * Only valid without a babel config file.
+   * With your own config, you list `babel-plugin-ember-template-compilation` yourself,
+   * so its `transforms` belong there.
    */
   templateTransforms?: Transform[];
   /**
-   * Opt additional files into babel (see maybeBabel's `filter`). Use this to
-   * cover addons that ship code needing babel (e.g. `ember-concurrency`).
+   * Opt additional files into babel (see maybeBabel's `filter`).
+   *
+   * Use this to cover addons that ship code needing babel
+   * (e.g. `ember-concurrency`).
    */
   filter?: {
     include: {
@@ -63,27 +67,34 @@ export interface BabelOptions {
   };
 }
 
-/** Tried in order, so an ESM config wins over a JSON one of the same name. */
+/**
+ * Tried in order, so an ESM config wins over a JSON one of the same name.
+ */
 const PUBLISH_CONFIG_EXTENSIONS = ["mjs", "cjs", "js", "mts", "cts", "ts", "json"];
 
 /**
- * Tried in order: next to package.json first, then `config/` for libraries that
- * keep their build configuration out of the package root.
+ * Tried in order:
+ * - next to package.json first
+ * - then `config/`, for libraries that keep their build configuration
+ *   out of the package root
  */
 const PUBLISH_CONFIG_DIRECTORIES = [".", "config"];
 
 /**
- * A `babel.publish.config.*` (in the package root or `config/`), if there is
- * one.
- *
- * A library's plain `babel.config.*` is its *development* config: it typically
- * 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 stay for the consuming app to evaluate,
- * and the wire format is private between one template compiler and one glimmer
- * runtime. Babel's own resolution can't tell the two apart (it finds whatever
- * `babel.config.*` exists), so a publish build has to prefer the config named
- * for publishing.
+ * A `babel.publish.config.*` (in the package root or `config/`), if there is one.
+ *
+ * A library's plain `babel.config.*` is its *development* config.
+ * It typically:
+ * - compiles `@embroider/macros` away
+ * - targets the wire format
+ * - wires up whatever the in-package demo app or test suite needs
+ *
+ * None of that belongs in a published artifact:
+ * - macros must stay, for the consuming app to evaluate
+ * - the wire format is private between one template compiler and one glimmer runtime
+ *
+ * Babel's own resolution can't tell the two apart (it finds whatever `babel.config.*` exists),
+ * so a publish build has to prefer the config named for publishing.
  */
 function detectPublishConfigFile(): string | undefined {
   for (const directory of PUBLISH_CONFIG_DIRECTORIES) {
@@ -98,14 +109,16 @@ function detectPublishConfigFile(): string | undefined {
 }
 
 /**
- * The config this publish build should use: a `babel.publish.config.*` when the
- * library has one, else the project's root babel config resolved the way babel
- * itself does (`babel.config.{js,cjs,mjs,cts,json}`, honoring `rootMode`
- * semantics) -- which for a library whose only config *is* its publish config
- * is the same file either way.
- *
- * The sync API evaluates the config file; on node 24+ that works for native
- * ESM configs too (require(esm)).
+ * The config this publish build must use:
+ * - a `babel.publish.config.*`, when the library has one
+ * - else the project's root babel config, resolved the way babel itself does
+ *   (`babel.config.{js,cjs,mjs,cts,json}`, honoring `rootMode` semantics)
+ *
+ * For a library whose only config *is* its publish config,
+ * that is the same file either way.
+ *
+ * The sync API evaluates the config file.
+ * On node 24+ that works for native ESM configs too (require(esm)).
  */
 function detectConfigFile(): string | undefined {
   const publishConfig = detectPublishConfigFile();
@@ -121,20 +134,21 @@ function detectConfigFile(): string | undefined {
  * Everything a library without its own babel config needs:
  *
  * - TypeScript stripping
+ *
  * - template compilation to `precompileTemplate` (`targetFormat: "hbs"`).
- *   Published libraries must NOT ship wire format: the wire format is
- *   private between the template compiler and the glimmer runtime of the
- *   same version, so baking it in ties the published artifact to the
- *   consuming app's exact ember-source. The consuming app performs final
- *   compilation.
+ *   Published libraries must NOT ship wire format.
+ *   The wire format is private between the template compiler and the glimmer runtime
+ *   of the same version, so baking it in ties the published artifact
+ *   to the consuming app's exact ember-source.
+ *   The consuming app performs final compilation.
  *
  *   A bundle-mode build ships that exact ember-source,
  *   so it compiles to the wire format with ember-source's own compiler,
  *   and needs no compiler at runtime.
  *
- * - decorator-transforms, with its runtime left as a bare specifier so the
- *   consuming app resolves it (the library keeps `decorator-transforms` as
- *   a real dependency).
+ * - decorator-transforms, with its runtime left as a bare specifier
+ *   so the consuming app resolves it.
+ *   (the library keeps `decorator-transforms` as a real dependency)
  *
  *   A bundle-mode build resolves it itself.
  */
@@ -155,8 +169,8 @@ function defaultPlugins(templateTransforms?: Transform[], bundle = false): Plugi
     [
       decoratorTransforms,
       {
-        // Emit `import ... from "decorator-transforms/runtime-esm"` as a bare
-        // specifier so it stays external and the consuming app resolves it.
+        // Emit `import ... from "decorator-transforms/runtime-esm"` as a bare specifier,
+        // so it stays external and the consuming app resolves it.
         runtime: { import: "decorator-transforms/runtime-esm" },
       },
     ],
@@ -164,29 +178,34 @@ function defaultPlugins(templateTransforms?: Transform[], bundle = false): Plugi
 }
 
 /**
- * We still need babel (not just oxc/rolldown's native transforms) for two
- * reasons:
- *
- * - template compilation: `babel-plugin-ember-template-compilation` turns the
- *   content-tag output into `precompileTemplate` calls; oxc has no equivalent.
- * - decorators: Ember uses the legacy/stage-1 decorator signature together
- *   with `decorator-transforms`, which rewrites decorated class fields
- *   (`@tracked x`) into getter/setters backed by a runtime. oxc's native
- *   "legacy decorators" emit tsc-style `__decorate` output, which does not
- *   match those semantics.
- *
- * But we don't want to send *every* file through babel and give back the speed
- * rolldown/oxc buys us -- so we run babel via `maybeBabel`, which filters down
- * to only the files that actually need it (template-tag, decorators, template
- * imports). Everything else stays on the native transform.
- *
- * The library's own babel config is used when it exists -- its
- * `babel.publish.config.*` (root or `config/`) in preference to its
- * `babel.config.*`, since this is a publish build. Without one, `defaultPlugins` covers templates, decorators,
- * and TypeScript, so no config file is required.
- *
- * Libraries default to `babelHelpers: "bundled"` so the emitted output is
- * self-contained.
+ * We still need babel (not just oxc / rolldown's native transforms) for two reasons:
+ *
+ * - template compilation.
+ *   `babel-plugin-ember-template-compilation` turns the content-tag output
+ *   into `precompileTemplate` calls.
+ *   oxc has no equivalent.
+ *
+ * - decorators.
+ *   Ember uses the legacy / stage-1 decorator signature together with `decorator-transforms`,
+ *   which rewrites decorated class fields (`@tracked x`) into getter / setters backed by a runtime.
+ *   oxc's native "legacy decorators" emit tsc-style `__decorate` output,
+ *   which does not match those semantics.
+ *
+ * But we don't want to send *every* file through babel
+ * and give back the speed rolldown / oxc buys us.
+ *
+ * So we run babel via `maybeBabel`, which filters down to only the files that need it
+ * (template-tag, decorators, template imports).
+ * Everything else stays on the native transform.
+ *
+ * The library's own babel config is used when it exists.
+ * Its `babel.publish.config.*` (root or `config/`) wins over its `babel.config.*`,
+ * since this is a publish build.
+ *
+ * Without one, `defaultPlugins` covers templates, decorators, and TypeScript,
+ * so no config file is required.
+ *
+ * Libraries default to `babelHelpers: "bundled"`, so the emitted output is self-contained.
  */
 export function emberBabel(options: BabelOptions = {}): Plugin {
   const configFile = options.configFile === undefined ? detectConfigFile() : options.configFile;
@@ -214,8 +233,8 @@ export function emberBabel(options: BabelOptions = {}): Plugin {
 
   return maybeBabel({
     ...shared,
-    // No config file (or the caller opted out): don't let babel go looking
-    // for one -- we provide the whole plugin list inline.
+    // No config file (or the caller opted out).
+    // Don't let babel go looking for one: we provide the whole plugin list inline.
     configFile: false,
     babelrc: false,
     plugins: defaultPlugins(options.templateTransforms, options.bundle).concat(

package/packages/rolldown/src/config.ts

@@ -1,29 +1,33 @@
 import type { TsdownPlugin, UserConfig } from "tsdown";
 
 /**
- * Sensible defaults for an Ember v2 library, applied through plugin hooks so
- * they travel with `ember()` — you get them whether you use this package's
- * `defineConfig`, tsdown's, or a plain `tsdown.config.js` / `rolldown.config.js`.
+ * Sensible defaults for an Ember v2 library.
+ *
+ * Applied through plugin hooks, so they travel with `ember()`.
+ * You get them whether you use this package's `defineConfig`, tsdown's,
+ * or a plain `tsdown.config.js` / `rolldown.config.js`.
  *
  * Every value is applied with `??=`, so anything you set explicitly wins.
  *
- * Under tsdown, the full set applies via the `tsdownConfig` hook (analogous to
- * Vite's `config` hook):
+ * Under tsdown, the full set applies via the `tsdownConfig` hook
+ * (analogous to Vite's `config` hook):
  *
- * - `sourcemap` — emit sourcemaps alongside the output.
- * - `clean` — wipe `dist/` between builds.
- * - `dts` — emit `.d.ts` declarations (via isolated declarations).
- * - `outExtensions` — `.js`/`.d.ts` rather than tsdown's default `.mjs`/`.d.mts`,
- *   since exports maps conventionally point at `.js`/`.d.ts`.
- * - `report` — off; the size report is noise for a library build.
- * - `deps.neverBundle` — leave node builtins and the ember virtual packages to
- *   the consuming app (`emberExternals()` handles the rest).
+ * - `sourcemap` — emit sourcemaps alongside the output
+ * - `clean` — wipe `dist/` between builds
+ * - `dts` — emit `.d.ts` declarations (via isolated declarations)
+ * - `outExtensions` — `.js` / `.d.ts` rather than tsdown's default `.mjs` / `.d.mts`
+ *   (exports maps conventionally point at `.js` / `.d.ts`)
+ * - `report` — off.
+ *   The size report is noise for a library build.
+ * - `deps.neverBundle` — leave node builtins and the ember virtual packages
+ *   to the consuming app (`emberExternals()` handles the rest)
  *
- * A plain rolldown build has no notion of `clean`/`dts`/`outExtensions`/`report`
- * (those are tsdown-level concepts), so only the options with rolldown
- * equivalents are applied there, via rolldown's own `outputOptions` hook:
+ * A plain rolldown build has no notion of `clean` / `dts` / `outExtensions` / `report`.
+ * Those are tsdown-level concepts.
+ * So only the options with rolldown equivalents are applied there,
+ * via rolldown's own `outputOptions` hook:
  *
- * - `output.sourcemap` — on (output option).
+ * - `output.sourcemap` — on
  *
  * Externals are handled by `emberExternals()` (a `resolveId` hook) in both cases.
  *

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

@@ -7,9 +7,13 @@ import { afterEach, describe, expect, it } from "vitest";
 import { ember } from "../index.ts";
 
 interface Dist {
-  /** Sorted dist-relative paths of every emitted file. */
+  /**
+   * Sorted dist-relative paths of every emitted file.
+   */
   files: string[];
-  /** dist-relative path -> content, for every emitted .d.ts and .css file. */
+  /**
+   * dist-relative path -> content, for every emitted .d.ts and .css file.
+   */
   contents: Record<string, string>;
 }
 
@@ -22,12 +26,16 @@ afterEach(() => {
 
 /**
  * Drives `ember()` through a real tsdown build (the dts pipeline included).
- * `files` is a map of relative path -> source, written into a temp dir that
- * becomes the cwd for the build (the externals and isolated-declarations
- * plugins read package.json / tsconfig.json from cwd, like the tsdown CLI).
  *
- * Returns the emitted file list plus the full contents of every declaration
- * and css file (js output is covered by transform.test.ts).
+ * `files` is a map of relative path -> source.
+ * It is written into a temp dir that becomes the cwd for the build.
+ * (the externals and isolated-declarations plugins read package.json / tsconfig.json
+ *  from cwd, like the tsdown CLI)
+ *
+ * Returns:
+ * - the emitted file list
+ * - the full contents of every declaration and css file
+ *   (js output is covered by transform.test.ts)
  */
 async function buildFixture(files: Record<string, string>, entry: string[]): Promise<Dist> {
   const dir = await mkdtemp(path.join(tmpdir(), "ember-rolldown-dts-"));
@@ -81,7 +89,9 @@ async function buildFixture(files: Record<string, string>, entry: string[]): Pro
   return dist;
 }
 
-/** One printable document of every captured file, for a single snapshot. */
+/**
+ * One printable document of every captured file, for a single snapshot.
+ */
 function printed(dist: Dist): string {
   return Object.entries(dist.contents)
     .sort(([a], [b]) => a.localeCompare(b))
@@ -91,10 +101,12 @@ function printed(dist: Dist): string {
 
 describe("declarations (full ember() via tsdown)", () => {
   it("emits .d.ts for an entry that type-imports from a non-entry .gts", async () => {
-    // Mirrors a design-system shape: the component is in the runtime graph via
-    // the index entry, while a second entry (a service) only *type*-imports
-    // from it. The service's declaration then references the component's
-    // (virtual) .d.ts, which only exists in the bundler's module graph.
+    // Mirrors a design-system shape:
+    // - the component is in the runtime graph via the index entry
+    // - a second entry (a service) only *type*-imports from it
+    //
+    // The service's declaration then references the component's (virtual) .d.ts,
+    // which only exists in the bundler's module graph.
     const dist = await buildFixture(
       {
         "src/index.ts": `export { default as Popup } from './popup.gts';`,
@@ -174,11 +186,12 @@ describe("declarations (full ember() via tsdown)", () => {
   });
 
   it("emits .d.ts when a .gts module is only ever type-imported", async () => {
-    // Nothing value-imports popup.gts, so its virtual module never enters the
-    // runtime graph: the only route to its declaration is the dts resolver
-    // loading it on demand. The declaration pipeline registers modules as
-    // their (virtual) source loads, so the import must resolve to the source
-    // id — a pre-rewritten `.d.ts` id skips that registration and dangles.
+    // Nothing value-imports popup.gts, so its virtual module never enters the runtime graph.
+    // The only route to its declaration is the dts resolver loading it on demand.
+    //
+    // The declaration pipeline registers modules as their (virtual) source loads,
+    // so the import must resolve to the source id.
+    // A pre-rewritten `.d.ts` id skips that registration and dangles.
     const dist = await buildFixture(
       {
         "src/service.ts": [
@@ -233,10 +246,10 @@ describe("declarations (full ember() via tsdown)", () => {
   });
 
   it("emits .d.ts for a .gts that type-imports another (otherwise unimported) .gts", async () => {
-    // A nested component type-imports a sibling from the parent directory;
-    // its declaration then carries a relative source specifier for a module
-    // that exists only in the bundler's graph (never on disk, never in the
-    // runtime graph).
+    // A nested component type-imports a sibling from the parent directory.
+    //
+    // Its declaration then carries a relative source specifier for a module
+    // that exists only in the bundler's graph (never on disk, never in the runtime graph).
     const dist = await buildFixture(
       {
         "src/index.ts": `export { default as OptionList } from './components/select/option-list.gts';`,
@@ -288,11 +301,14 @@ describe("declarations (full ember() via tsdown)", () => {
   });
 
   it("bundles co-located CSS (via @tsdown/css) without breaking declarations", async () => {
-    // Ember components routinely import a co-located .css file. Without CSS
-    // handling the build dies on tsdown's css-guard — and because the failing
-    // component module never loads, every declaration that references it
-    // dangles (surfacing as misleading UNLOADABLE_DEPENDENCY errors on
-    // <component>.d.ts). @tsdown/css makes both work.
+    // Ember components routinely import a co-located .css file.
+    //
+    // Without CSS handling, the build dies on tsdown's css-guard.
+    // And because the failing component module never loads,
+    // every declaration that references it dangles
+    // (surfacing as misleading UNLOADABLE_DEPENDENCY errors on <component>.d.ts).
+    //
+    // @tsdown/css makes both work.
     const dist = await buildFixture(
       {
         "src/index.ts": `export { default as Popup } from './popup.gts';`,

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

@@ -14,8 +14,9 @@ afterEach(() => {
 });
 
 /**
- * An ember-source stub whose `ember-addon.renamed-modules` provides
- * `@glimmer/runtime` (file-path keys, like the real manifest).
+ * An ember-source stub whose `ember-addon.renamed-modules` provides `@glimmer/runtime`.
+ *
+ * File-path keys, like the real manifest.
  */
 const EMBER_SOURCE_STUB = {
   name: "ember-source",
@@ -29,9 +30,11 @@ const EMBER_SOURCE_STUB = {
 };
 
 /**
- * Writes a fixture package (manifest + optional stub ember-source in its
- * node_modules) and cds into it — the plugin reads both from the library's
- * own context, like the tsdown CLI.
+ * Writes a fixture package and cds into it:
+ * - a manifest
+ * - an optional stub ember-source in its node_modules
+ *
+ * The plugin reads both from the library's own context, like the tsdown CLI.
  */
 async function fixture(manifest: object, { emberSource = true } = {}): Promise<string> {
   const dir = await mkdtemp(path.join(tmpdir(), "ember-rolldown-externals-"));
@@ -50,7 +53,9 @@ async function fixture(manifest: object, { emberSource = true } = {}): Promise<s
   return dir;
 }
 
-/** Runs the plugin's own hooks directly against the current fixture. */
+/**
+ * Runs the plugin's own hooks directly against the current fixture.
+ */
 function resolveWith(source: string): unknown {
   const plugin = emberExternals();
   // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-explicit-any
@@ -68,17 +73,17 @@ describe("emberExternals", () => {
   });
 
   it("externalizes the modules ember-source provides via renamed-modules", async () => {
-    // Private API like @glimmer/runtime exists only inside the app's
-    // ember-source (its ember-addon.renamed-modules) — @embroider/core's
-    // emberVirtualPackages doesn't list it.
+    // Private API like @glimmer/runtime exists only inside the app's ember-source
+    // (its ember-addon.renamed-modules).
+    // @embroider/core's emberVirtualPackages doesn't list it.
     await fixture({});
     expect(resolveWith("@glimmer/runtime")).toBe(false);
     expect(resolveWith("@ember/-internals/glimmer")).toBe(false);
   });
 
   it("does not blanket-externalize @glimmer packages ember-source doesn't provide", async () => {
-    // e.g. @glimmer/component is a real package a library may want bundled;
-    // only declared deps / virtual packages / renamed-modules are external.
+    // e.g. @glimmer/component is a real package a library may want bundled.
+    // Only declared deps / virtual packages / renamed-modules are external.
     await fixture({});
     expect(resolveWith("@glimmer/not-provided")).toBeUndefined();
   });

package/packages/rolldown/src/externals.ts

@@ -18,8 +18,8 @@ function readJsonSync(path: string) {
 }
 
 /**
- * Everything the library declares as a `dependency` or `peerDependency` is
- * resolvable by the consuming app, so we never bundle it.
+ * Everything the library declares as a `dependency` or `peerDependency`
+ * is resolvable by the consuming app, so we never bundle it.
  */
 function resolvableDependencies(): Set<string> {
   const deps = new Set<string>();
@@ -79,10 +79,13 @@ function emberSourceProvidedModules(): Set<string> {
 }
 
 /**
- * Keeps the library's declared dependencies and the ember virtual packages
- * (things like `@ember/component`, `@glimmer/tracking`, the template compiler,
- * …) external, so the app that consumes the library resolves them instead of
- * the library bundling copies of them.
+ * Keeps external:
+ * - the library's declared dependencies
+ * - the ember virtual packages
+ *   (things like `@ember/component`, `@glimmer/tracking`, the template compiler, …)
+ *
+ * So the app that consumes the library resolves them,
+ * instead of the library bundling copies of them.
  */
 export function emberExternals(): Plugin {
   let deps: Set<string>;
@@ -100,8 +103,8 @@ export function emberExternals(): Plugin {
     resolveId: {
       order: "pre",
       handler(source) {
-        // Anything with a protocol (`node:`, virtual modules, …) is not ours
-        // to externalize.
+        // Anything with a protocol (`node:`, virtual modules, …)
+        // is not ours to externalize.
         if (source.includes(":")) {
           return null;
         }
@@ -124,10 +127,13 @@ export function emberExternals(): Plugin {
         }
 
         // Modules ember-source provides by renaming them into itself
-        // (`ember-addon.renamed-modules`) — private API like
-        // `@glimmer/runtime` that only exists inside the app's ember-source.
-        // Matched on the full specifier: the renamed modules are module
-        // paths, not packages.
+        // (`ember-addon.renamed-modules`).
+        //
+        // Private API like `@glimmer/runtime`,
+        // which only exists inside the app's ember-source.
+        //
+        // Matched on the full specifier:
+        // the renamed modules are module paths, not packages.
         if (renamedModules.has(source)) {
           return false;
         }