ember.nvp 1.6.0 → 1.7.1

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>();
@@ -36,42 +36,56 @@ function resolvableDependencies(): Set<string> {
 }
 
 /**
- * The module names ember-source provides by renaming them into itself — the
- * keys of its `ember-addon.renamed-modules`, normalized from file paths to
- * import specifiers (`@glimmer/runtime/index.js` → `@glimmer/runtime`).
+ * The modules ember-source provides by renaming them into itself.
  *
- * This is the authoritative list of ember's provided modules, including
- * private API that @embroider/core's emberVirtualPackages doesn't cover
- * (e.g. `@glimmer/runtime`). It deliberately does NOT include real packages
- * like `@glimmer/component`, which a library may want bundled.
+ * This is its `ember-addon.renamed-modules`, keyed by module file path:
+ *   `@glimmer/runtime/index.js` → `ember-source/@glimmer/runtime/index.js`
  *
- * Resolved from the library's own dependency graph; empty when ember-source
- * isn't resolvable there.
+ * It is the authoritative list of ember's provided modules.
+ * It includes private API that @embroider/core's emberVirtualPackages
+ * doesn't cover (e.g. `@glimmer/runtime`).
+ *
+ * It deliberately does NOT include real packages like `@glimmer/component`,
+ * which a library may want bundled.
+ *
+ * Empty when ember-source isn't resolvable from the library.
  */
-function emberSourceRenamedModules(): Set<string> {
-  const provided = new Set<string>();
-
+export function emberSourceRenamedModules(): Record<string, string> {
   try {
     const require = createRequire(path.resolve("package.json"));
     const manifest = require("ember-source/package.json") as {
       "ember-addon"?: { "renamed-modules"?: Record<string, string> };
     };
 
-    for (const key of Object.keys(manifest["ember-addon"]?.["renamed-modules"] ?? {})) {
-      provided.add(key.replace(/\.js$/, "").replace(/\/index$/, ""));
-    }
+    return manifest["ember-addon"]?.["renamed-modules"] ?? {};
   } catch {
     // The library doesn't have ember-source in its graph; nothing to provide.
+    return {};
+  }
+}
+
+/**
+ * The renamed modules as import specifiers
+ *   `@glimmer/runtime/index.js` → `@glimmer/runtime`
+ */
+function emberSourceProvidedModules(): Set<string> {
+  const provided = new Set<string>();
+
+  for (const key of Object.keys(emberSourceRenamedModules())) {
+    provided.add(key.replace(/\.js$/, "").replace(/\/index$/, ""));
   }
 
   return provided;
 }
 
 /**
- * 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>;
@@ -83,14 +97,14 @@ export function emberExternals(): Plugin {
     buildStart() {
       this.addWatchFile("package.json");
       deps = resolvableDependencies();
-      renamedModules = emberSourceRenamedModules();
+      renamedModules = emberSourceProvidedModules();
     },
 
     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;
         }
@@ -113,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;
         }

package/packages/rolldown/src/isolated-declarations.ts

@@ -5,16 +5,16 @@ import type { Plugin } from "rolldown";
 import type { UserConfig } from "tsdown";
 
 /**
- * Resolve the tsconfig the build will actually use, mirroring tsdown's own
- * `tsconfig` option (`string | boolean`):
+ * Resolve the tsconfig the build will use.
  *
- * - `undefined` / `true`: `tsconfig.json` in the cwd.
- * - a path to a file: that file.
- * - a path to a directory: `tsconfig.json` inside it.
- * - `false`: no tsconfig at all.
+ * Mirrors tsdown's own `tsconfig` option (`string | boolean`):
+ * - `undefined` / `true`: `tsconfig.json` in the cwd
+ * - a path to a file: that file
+ * - a path to a directory: `tsconfig.json` inside it
+ * - `false`: no tsconfig at all
  *
- * Under plain rolldown there is no such option, so the cwd's `tsconfig.json`
- * is all there is.
+ * Under plain rolldown there is no such option,
+ * so the cwd's `tsconfig.json` is all there is.
  */
 function resolveTsconfigPath(option: string | boolean | undefined): string | undefined {
   if (option === false) return undefined;
@@ -33,33 +33,41 @@ function resolveTsconfigPath(option: string | boolean | undefined): string | und
 }
 
 /**
- * Errors the build when the tsconfig it builds with does not set
- * `isolatedDeclarations: true`.
+ * Errors the build when the tsconfig it builds with
+ * does not set `isolatedDeclarations: true`.
  *
- * This is required: declarations for `.gts`/`.gjs` (template tag) modules can
- * only be emitted by the isolated-declarations pipeline, which reads compiled
- * modules from the bundler's module graph. The `tsc`-based pipeline reads
- * source files from disk, where the compiled modules don't exist, and fails
- * with "Source file not found".
+ * This is required.
+ * Declarations for `.gts` / `.gjs` (template tag) modules can only be emitted
+ * by the isolated-declarations pipeline,
+ * which reads compiled modules from the bundler's module graph.
  *
- * Failing fast here -- rather than only when declaration emit happens to run
- * -- keeps the project honest: editors and `tsc`/`ember-tsc` then check the
- * same rules the build enforces (exported values need explicit type
- * annotations, e.g. `export const X: TOC<Sig> = <template>...`).
+ * The `tsc`-based pipeline reads source files from disk.
+ * The compiled modules don't exist there, so it fails with "Source file not found".
  *
- * The tsconfig checked is the one tsdown's `tsconfig` option points at, not
- * necessarily `tsconfig.json`. A library whose package also holds dev-only code
- * (a demo app, in-package tests) can therefore keep a permissive
- * `tsconfig.json` covering everything for editors and `tsc --noEmit`, and point
- * the build at a `tsconfig.publish.json` that covers only the publishable
- * sources -- isolated declarations then constrain exactly the code that gets
- * declarations emitted for it, and nothing else.
+ * Failing fast here, rather than only when declaration emit happens to run,
+ * keeps the project honest.
+ * Editors and `tsc` / `ember-tsc` then check the same rules the build enforces:
+ * exported values need explicit type annotations,
+ * e.g. `export const X: TOC<Sig> = <template>...`
  *
- * Projects with no tsconfig (JavaScript libraries) or without the `typescript`
- * package have no declarations to emit, so there is nothing to check.
- * `tsconfig: false` is different: it is an explicit opt-out, and combined with
- * declaration emit it produces a confusing "Source file not found" from the
- * tsc-based pipeline, so it errors here instead.
+ * The tsconfig checked is the one tsdown's `tsconfig` option points at,
+ * not necessarily `tsconfig.json`.
+ *
+ * So a library whose package also holds dev-only code (a demo app, in-package tests) can:
+ * - keep a permissive `tsconfig.json` covering everything,
+ *   for editors and `tsc --noEmit`
+ * - point the build at a `tsconfig.publish.json` that covers only the publishable sources
+ *
+ * Isolated declarations then constrain exactly the code that gets declarations emitted,
+ * and nothing else.
+ *
+ * Projects with no tsconfig (JavaScript libraries) or without the `typescript` package
+ * have no declarations to emit, so there is nothing to check.
+ *
+ * `tsconfig: false` is different.
+ * It is an explicit opt-out.
+ * Combined with declaration emit, it produces a confusing "Source file not found"
+ * from the tsc-based pipeline, so it errors here instead.
  */
 export function emberIsolatedDeclarations(): Plugin {
   let tsconfigOption: string | boolean | undefined;
@@ -68,13 +76,15 @@ export function emberIsolatedDeclarations(): Plugin {
   return {
     name: "ember:isolated-declarations",
 
-    // Not called under plain rolldown, which leaves `tsconfigOption` undefined
-    // -- i.e. the cwd's tsconfig.json, the only thing it could mean there.
+    // Not called under plain rolldown, which leaves `tsconfigOption` undefined.
+    // That means the cwd's tsconfig.json, the only thing it could mean there.
     tsdownConfig(config: UserConfig) {
       tsconfigOption = config.tsconfig;
-      // `emberConfig()` turns dts on unless the library turned it off, so an
-      // explicit `false` is the only "no declarations" signal. Hook order
-      // between plugins isn't guaranteed, so don't rely on it having run.
+      // `emberConfig()` turns dts on unless the library turned it off,
+      // so an explicit `false` is the only "no declarations" signal.
+      //
+      // Hook order between plugins isn't guaranteed,
+      // so don't rely on it having run.
       emitsDeclarations = config.dts !== false;
     },
 
@@ -82,11 +92,14 @@ export function emberIsolatedDeclarations(): Plugin {
       if (tsconfigOption === false) {
         if (!emitsDeclarations) return;
 
-        // Without a tsconfig there is no `isolatedDeclarations`, so tsdown
-        // falls back to the tsc-based declaration pipeline -- which reads
-        // source files from disk and dies with "Source file not found" on
-        // every `.gts`/`.gjs`, since those only exist compiled in the module
-        // graph. Say so here instead of leaving that to be decoded.
+        // Without a tsconfig there is no `isolatedDeclarations`,
+        // so tsdown falls back to the tsc-based declaration pipeline.
+        //
+        // That pipeline reads source files from disk,
+        // and dies with "Source file not found" on every `.gts` / `.gjs`,
+        // since those only exist compiled in the module graph.
+        //
+        // Say so here instead of leaving that to be decoded.
         this.error(
           `\`tsconfig: false\` cannot be combined with declaration emit.\n\n` +
             `Declarations are emitted by the isolated-declarations pipeline, which needs a ` +
@@ -112,8 +125,8 @@ export function emberIsolatedDeclarations(): Plugin {
       const { config, error } = ts.readConfigFile(tsconfigPath, ts.sys.readFile);
 
       if (error) {
-        // Unreadable/unparsable tsconfig: tsc itself will report this with a
-        // better message than we can.
+        // Unreadable / unparsable tsconfig.
+        // tsc itself will report this with a better message than we can.
         return;
       }
 

package/packages/rolldown/src/plugin-like.ts

@@ -1,22 +1,25 @@
 /**
- * What this package hands back: an object that rolldown and tsdown accept in
- * `plugins`.
+ * What this package hands back:
+ * an object that rolldown and tsdown accept in `plugins`.
  *
- * Structurally this *is* rolldown's `Plugin` -- `name` is its only required
- * member, every hook is optional -- so the two are assignable in both
- * directions: a consumer who imports rolldown's own type can still write
- * `const plugins: Plugin[] = ember()`, and tsdown's `plugins` option lists
- * `{ name: string }` among the shapes it takes.
+ * Structurally this *is* rolldown's `Plugin`.
+ * `name` is its only required member, every hook is optional.
  *
- * Declaring it here rather than re-exporting rolldown's type is what keeps
- * `rolldown` out of the published declarations. Otherwise it has to become a
- * runtime `dependency` purely so consumers can resolve a type: leave it a
- * devDependency and the declaration bundler inlines a ~200kB private copy of
- * rolldown's types instead, nominally distinct from the consumer's own.
+ * So the two are assignable in both directions:
+ * - a consumer who imports rolldown's own type can still write
+ *   `const plugins: Plugin[] = ember()`
+ * - tsdown's `plugins` option lists `{ name: string }` among the shapes it takes
  *
- * The precise hook signatures still apply inside this package -- each plugin
- * function is typed with rolldown's real `Plugin` (a devDependency), and this
- * type only widens what crosses the package boundary.
+ * Declaring it here, rather than re-exporting rolldown's type,
+ * keeps `rolldown` out of the published declarations.
+ *
+ * Otherwise it has to become a runtime `dependency`, purely so consumers can resolve a type.
+ * Leave it a devDependency, and the declaration bundler inlines a ~200kB private copy
+ * of rolldown's types instead, nominally distinct from the consumer's own.
+ *
+ * The precise hook signatures still apply inside this package.
+ * Each plugin function is typed with rolldown's real `Plugin` (a devDependency).
+ * This type only widens what crosses the package boundary.
  */
 export interface RolldownPluginLike {
   name: string;

package/packages/rolldown/src/published-types.test.ts

@@ -5,10 +5,13 @@ import { fileURLToPath } from "node:url";
 import { beforeAll, describe, expect, it } from "vitest";
 
 /**
- * This package's own published shape: consumers write their build config in
- * TypeScript, so `import { ember } from "@nullvoxpopuli/ember-rolldown"` has to
- * carry types. Without them it is an implicit `any` (TS7016), and a config file
- * silently stops being type-checked.
+ * This package's own published shape.
+ *
+ * Consumers write their build config in TypeScript,
+ * so `import { ember } from "@nullvoxpopuli/ember-rolldown"` has to carry types.
+ *
+ * Without them it is an implicit `any` (TS7016),
+ * and a config file silently stops being type-checked.
  */
 const packageDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -43,8 +46,8 @@ async function declarations() {
 
 describe("published types", () => {
   beforeAll(async () => {
-    // `clean` is on, but don't let these assertions depend on that: stale
-    // artifacts from an earlier build satisfy every one of them on their own
+    // `clean` is on, but don't let these assertions depend on that.
+    // Stale artifacts from an earlier build satisfy every one of them on their own.
     await rm(path.join(packageDir, "dist"), { recursive: true, force: true });
     await execa("pnpm", ["build"], { cwd: packageDir });
   }, 120_000);
@@ -66,14 +69,16 @@ describe("published types", () => {
 
   /**
    * A declaration may only reach for packages a consumer is guaranteed to have.
-   * Reference a devDependency and there are two ways to lose, both quiet:
-   * the specifier survives and consumers can't resolve it (`skipLibCheck` hides
-   * that, degrading the type to an error type), or the declaration bundler
-   * inlines the whole type surface — a ~200kB copy of rolldown's types, in the
-   * case that prompted this test, nominally distinct from the consumer's own.
    *
-   * `ember()` returns plugins, so `RolldownPluginLike` exists to keep rolldown
-   * on the devDependency side of that line.
+   * Reference a devDependency, and there are two ways to lose, both quiet:
+   * - the specifier survives and consumers can't resolve it
+   *   (`skipLibCheck` hides that, degrading the type to an error type)
+   * - the declaration bundler inlines the whole type surface
+   *   (a ~200kB copy of rolldown's types, in the case that prompted this test,
+   *    nominally distinct from the consumer's own)
+   *
+   * `ember()` returns plugins,
+   * so `RolldownPluginLike` exists to keep rolldown on the devDependency side of that line.
    */
   it("declarations only reference packages consumers have", async () => {
     const manifest = await readManifest();

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

@@ -8,10 +8,15 @@ import { describe, expect, it } from "vitest";
 import { emberTransform } from "./transform.ts";
 
 /**
- * Drives the plugin through a real rolldown build. `files` is a map of
- * relative path -> source; the build entry is `index.ts`. Every bare (package)
- * specifier is marked external so the build only exercises the local
- * `.gts`/`.gjs`/`.ts` handling and doesn't need real dependencies installed.
+ * Drives the plugin through a real rolldown build.
+ *
+ * `files` is a map of relative path -> source.
+ * The build entry is `index.ts`.
+ *
+ * Every bare (package) specifier is marked external,
+ * so the build only exercises the local `.gts` / `.gjs` / `.ts` handling
+ * and doesn't need real dependencies installed.
+ *
  * Returns the concatenated code of every emitted chunk.
  */
 async function bundle(
@@ -45,8 +50,8 @@ async function bundle(
     .map((chunk) => chunk.code)
     .join("\n");
 
-  // rolldown's `//#region <path>` comments reference the random temp dir;
-  // collapse them to the bare filename so snapshots stay deterministic.
+  // rolldown's `//#region <path>` comments reference the random temp dir.
+  // Collapse them to the bare filename so snapshots stay deterministic.
   return code.replace(/(\/\/#region ).*\/([^/\n]+)$/gm, "$1$2");
 }
 
@@ -180,11 +185,13 @@ describe("emberTransform (full plugin via rolldown)", () => {
 
   it("resolves an absolute .gts specifier imported from a plugin's virtual module", async () => {
     /**
-     * The shape a code-generating plugin emits: a virtual module (id prefixed
-     * with `\0`, so it exists nowhere on disk) whose generated source imports
-     * real files by absolute path, because it has no directory to be relative
-     * to. `path.dirname` of such an id is `"\0."`, so the specifier must not be
-     * resolved against the importer's directory.
+     * The shape a code-generating plugin emits:
+     * a virtual module (id prefixed with `\0`, so it exists nowhere on disk)
+     * whose generated source imports real files by absolute path,
+     * because it has no directory to be relative to.
+     *
+     * `path.dirname` of such an id is `"\0."`,
+     * so the specifier must not be resolved against the importer's directory.
      */
     const registry = (dir: string): Plugin[] => {
       const source = "./registry?virtual=views";
@@ -225,10 +232,12 @@ describe("emberTransform (full plugin via rolldown)", () => {
   it("compiles a .gts module used directly as an entry (no importer)", async () => {
     const code = await bundle(
       {
-        // Both an entry .gts and a .ts entry importing it: the shared module
-        // must resolve to ONE id (the entry resolution realpaths, matching
-        // rolldown's own resolver) so it lands in the entry chunk and the
-        // index chunk imports it, rather than duplicating the code.
+        // Both an entry .gts and a .ts entry importing it.
+        //
+        // The shared module must resolve to ONE id
+        // (the entry resolution realpaths, matching rolldown's own resolver),
+        // so it lands in the entry chunk and the index chunk imports it,
+        // rather than duplicating the code.
         "index.ts": `export { default as Foo } from './foo.gts';`,
         "foo.gts": [
           `import Component from '@glimmer/component';`,
@@ -299,8 +308,8 @@ describe("emberTransform (full plugin via rolldown)", () => {
 
     const chunk = output.find((entry) => entry.type === "chunk" && "map" in entry);
     expect(chunk).toBeDefined();
-    // The composed map traces through the rewrite back to the original .gts
-    // source (content-tag's map survives the specifier-rewrite pass).
+    // The composed map traces through the rewrite back to the original .gts source.
+    // (content-tag's map survives the specifier-rewrite pass)
     const sources = (chunk as { map?: { sources: string[] } }).map?.sources ?? [];
     expect(sources.some((source) => source.endsWith("foo.gts"))).toBe(true);
   });