ember.nvp 1.2.0 → 1.4.0

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

@@ -0,0 +1,118 @@
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { rolldown } from "rolldown";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { emberExternals } from "./externals.ts";
+
+let restoreCwd: (() => void) | undefined;
+
+afterEach(() => {
+  restoreCwd?.();
+  restoreCwd = undefined;
+});
+
+/**
+ * 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",
+  version: "0.0.0",
+  "ember-addon": {
+    "renamed-modules": {
+      "@glimmer/runtime/index.js": "ember-source/@glimmer/runtime/index.js",
+      "@ember/-internals/glimmer/index.js": "ember-source/@ember/-internals/glimmer/index.js",
+    },
+  },
+};
+
+/**
+ * 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.
+ */
+async function fixture(manifest: object, { emberSource = true } = {}): Promise<string> {
+  const dir = await mkdtemp(path.join(tmpdir(), "ember-rolldown-externals-"));
+  await writeFile(path.join(dir, "package.json"), JSON.stringify(manifest));
+
+  if (emberSource) {
+    const stubDir = path.join(dir, "node_modules/ember-source");
+    await mkdir(stubDir, { recursive: true });
+    await writeFile(path.join(stubDir, "package.json"), JSON.stringify(EMBER_SOURCE_STUB));
+  }
+
+  const previousCwd = process.cwd();
+  process.chdir(dir);
+  restoreCwd = () => process.chdir(previousCwd);
+
+  return dir;
+}
+
+/** 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
+  (plugin.buildStart as any).call({ addWatchFile() {} });
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-explicit-any
+  return (plugin.resolveId as any).handler(source);
+}
+
+describe("emberExternals", () => {
+  it("externalizes declared dependencies and the ember virtual packages", async () => {
+    await fixture({ dependencies: { "some-dep": "*" } });
+    expect(resolveWith("some-dep")).toBe(false);
+    expect(resolveWith("@ember/component")).toBe(false);
+    expect(resolveWith("@glimmer/tracking")).toBe(false);
+  });
+
+  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.
+    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.
+    await fixture({});
+    expect(resolveWith("@glimmer/not-provided")).toBeUndefined();
+  });
+
+  it("leaves undeclared packages alone, with or without ember-source", async () => {
+    await fixture({});
+    expect(resolveWith("left-pad")).toBeUndefined();
+
+    await fixture({}, { emberSource: false });
+    expect(resolveWith("left-pad")).toBeUndefined();
+    // No ember-source in the graph -> no renamed-modules to consult.
+    expect(resolveWith("@glimmer/runtime")).toBeUndefined();
+  });
+
+  it("keeps a renamed-modules import external through a real build", async () => {
+    const dir = await fixture({ name: "build-fixture" });
+    await writeFile(
+      path.join(dir, "index.ts"),
+      `import { curry } from '@glimmer/runtime';\nexport const curried: unknown = curry;\n`,
+    );
+
+    const warnings: string[] = [];
+    const build = await rolldown({
+      input: path.join(dir, "index.ts"),
+      plugins: [emberExternals()],
+      onwarn(warning) {
+        warnings.push(warning.code ?? String(warning));
+      },
+    });
+    const { output } = await build.generate({ format: "es" });
+
+    expect(warnings.filter((code) => code === "UNRESOLVED_IMPORT")).toEqual([]);
+
+    const code = output.filter((chunk) => "code" in chunk).map((chunk) => chunk.code)[0] ?? "";
+    expect(code).toContain(`from "@glimmer/runtime"`);
+  });
+});

package/packages/rolldown/src/externals.ts

@@ -1,4 +1,6 @@
 import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
 
 import type { Plugin } from "rolldown";
 
@@ -33,6 +35,38 @@ function resolvableDependencies(): Set<string> {
   return deps;
 }
 
+/**
+ * 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`).
+ *
+ * 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.
+ *
+ * Resolved from the library's own dependency graph; empty when ember-source
+ * isn't resolvable there.
+ */
+function emberSourceRenamedModules(): Set<string> {
+  const provided = new Set<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$/, ""));
+    }
+  } catch {
+    // The library doesn't have ember-source in its graph; nothing to provide.
+  }
+
+  return provided;
+}
+
 /**
  * Keeps the library's declared dependencies and the ember virtual packages
  * (things like `@ember/component`, `@glimmer/tracking`, the template compiler,
@@ -41,6 +75,7 @@ function resolvableDependencies(): Set<string> {
  */
 export function emberExternals(): Plugin {
   let deps: Set<string>;
+  let renamedModules: Set<string>;
 
   return {
     name: "ember:externals",
@@ -48,6 +83,7 @@ export function emberExternals(): Plugin {
     buildStart() {
       this.addWatchFile("package.json");
       deps = resolvableDependencies();
+      renamedModules = emberSourceRenamedModules();
     },
 
     resolveId: {
@@ -76,6 +112,15 @@ export function emberExternals(): Plugin {
           return false;
         }
 
+        // 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.
+        if (renamedModules.has(source)) {
+          return false;
+        }
+
         return undefined;
       },
     },

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

@@ -1,10 +1,39 @@
-import { existsSync } from "node:fs";
+import { existsSync, statSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 
 import type { Plugin } from "rolldown";
+import type { UserConfig } from "tsdown";
 
 /**
- * Errors the build when a `tsconfig.json` is present without
+ * Resolve the tsconfig the build will actually use, mirroring 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.
+ */
+function resolveTsconfigPath(option: string | boolean | undefined): string | undefined {
+  if (option === false) return undefined;
+
+  if (typeof option === "string") {
+    const asPath = resolve(option);
+
+    if (existsSync(asPath) && statSync(asPath).isDirectory()) {
+      return resolve(asPath, "tsconfig.json");
+    }
+
+    return asPath;
+  }
+
+  return resolve("tsconfig.json");
+}
+
+/**
+ * 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
@@ -18,18 +47,59 @@ import type { Plugin } from "rolldown";
  * same rules the build enforces (exported values need explicit type
  * annotations, e.g. `export const X: TOC<Sig> = <template>...`).
  *
- * Projects without a `tsconfig.json` (JavaScript libraries) or without the
- * `typescript` package have no declarations to emit, so there is nothing to
- * check.
+ * 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.
+ *
+ * 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.
  */
 export function emberIsolatedDeclarations(): Plugin {
+  let tsconfigOption: string | boolean | undefined;
+  let emitsDeclarations = true;
+
   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.
+    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.
+      emitsDeclarations = config.dts !== false;
+    },
+
     async buildStart() {
-      const tsconfigPath = resolve("tsconfig.json");
+      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.
+        this.error(
+          `\`tsconfig: false\` cannot be combined with declaration emit.\n\n` +
+            `Declarations are emitted by the isolated-declarations pipeline, which needs a ` +
+            `tsconfig setting "compilerOptions.isolatedDeclarations": true -- it is the only ` +
+            `pipeline that can see compiled .gts/.gjs modules.\n\n` +
+            `Either point tsdown's \`tsconfig\` option at such a config, or set \`dts: false\` ` +
+            `if this library ships no types.`,
+        );
+      }
+
+      const tsconfigPath = resolveTsconfigPath(tsconfigOption);
 
-      if (!existsSync(tsconfigPath)) return;
+      if (!tsconfigPath || !existsSync(tsconfigPath)) return;
 
       let ts: typeof import("typescript");
 
@@ -57,7 +127,10 @@ export function emberIsolatedDeclarations(): Plugin {
             `isolated-declarations pipeline, which reads compiled modules from the bundler's ` +
             `module graph -- the tsc-based pipeline reads from disk and cannot see them.\n\n` +
             `Isolated declarations require exported values to have explicit type annotations, ` +
-            `e.g. \`export const X: TOC<Sig> = <template>...\`.`,
+            `e.g. \`export const X: TOC<Sig> = <template>...\`.\n\n` +
+            `If this tsconfig also covers dev-only code (a demo app, in-package tests) that ` +
+            `should not be constrained this way, point tsdown's \`tsconfig\` option at a ` +
+            `publish-only tsconfig that sets the flag and covers just the published sources.`,
         );
       }
     },

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

@@ -13,7 +13,10 @@ import { emberTransform } from "./transform.ts";
  * `.gts`/`.gjs`/`.ts` handling and doesn't need real dependencies installed.
  * Returns the concatenated code of every emitted chunk.
  */
-async function bundle(files: Record<string, string>): Promise<string> {
+async function bundle(
+  files: Record<string, string>,
+  { input = ["index.ts"] }: { input?: string[] } = {},
+): Promise<string> {
   const dir = await mkdtemp(path.join(tmpdir(), "ember-rolldown-build-"));
 
   for (const [relative, source] of Object.entries(files)) {
@@ -25,7 +28,7 @@ async function bundle(files: Record<string, string>): Promise<string> {
   const isLocal = (id: string) => id.startsWith(".") || id.startsWith("/") || path.isAbsolute(id);
 
   const build = await rolldown({
-    input: path.join(dir, "index.ts"),
+    input: input.map((relative) => path.join(dir, relative)),
     plugins: [emberTransform()],
     external: (id) => !isLocal(id),
     onwarn() {},
@@ -171,6 +174,54 @@ 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.
+        "index.ts": `export { default as Foo } from './foo.gts';`,
+        "foo.gts": [
+          `import Component from '@glimmer/component';`,
+          `export default class Foo extends Component {`,
+          `  <template>Entry</template>`,
+          `}`,
+        ].join("\n"),
+      },
+      { input: ["index.ts", "foo.gts"] },
+    );
+
+    expect(code).not.toContain("<template>");
+    expect(code).toContain("template(");
+    expect(code).toContain(`from "@glimmer/component"`);
+    // deduplicated: the class body appears exactly once, in foo's own chunk
+    expect(code.match(/extends Component/g)).toHaveLength(1);
+    expect(code).toContain(`from "./foo.js"`);
+
+    expect(code).toMatchInlineSnapshot(`
+      "import { template } from "@ember/template-compiler";
+      import Component from "@glimmer/component";
+      //#region foo.ts
+      var Foo = class extends Component {
+      	static {
+      		template(\`Entry\`, {
+      			component: this,
+      			eval() {
+      				return eval(arguments[0]);
+      			}
+      		});
+      	}
+      };
+      //#endregion
+      export { Foo as default };
+
+      import Foo from "./foo.js";
+      export { Foo };
+      "
+    `);
+  });
+
   it("emits sourcemaps for the specifier rewrite (no SOURCEMAP_BROKEN warnings)", async () => {
     const dir = await mkdtemp(path.join(tmpdir(), "ember-rolldown-map-"));
 

package/packages/rolldown/src/transform.ts

@@ -1,5 +1,5 @@
 import { Preprocessor } from "content-tag";
-import { existsSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
 import { readFile, writeFile, readdir } from "node:fs/promises";
 import path from "node:path";
 import type { Plugin } from "rolldown";
@@ -70,7 +70,28 @@ export function emberTransform(): Plugin {
     resolveId: {
       order: "pre",
       handler(id, importer) {
-        if (!importer) return null;
+        // Entries have no importer: their ids come straight from the build
+        // config (tsdown expands entry globs to on-disk paths). Resolve a
+        // `.gts`/`.gjs` entry to the same virtual `.ts`/`.js` id an imported
+        // module gets, so the load hook compiles it via content-tag instead
+        // of the raw `<template>` source hitting the parser. Entries may be
+        // any extension — the emitted `.js`/`.d.ts` paths mirror the entry
+        // paths either way (that's how tsdown's dts support works).
+        if (!importer) {
+          if (!id.endsWith(".gts") && !id.endsWith(".gjs")) return null;
+          if (!existsSync(id)) return null;
+
+          // rolldown's default resolver realpaths entry ids (e.g. macOS
+          // /var -> /private/var). Match it, or this same file imported from
+          // another entry resolves to a second module id and gets duplicated
+          // into both chunks.
+          const fileName = realpathSync(path.resolve(id));
+
+          return {
+            id: fileName.replace(/\.gts$/, ".ts").replace(/\.gjs$/, ".js"),
+            meta: { fileName },
+          };
+        }
 
         const fileName = path.join(path.dirname(importer), id);
 

package/src/layers/github-actions/index.js

@@ -49,6 +49,9 @@ export default {
 
     return reasons.length === 0;
   },
+  readme() {
+    return "### GitHub Actions\n\nContinuous Integration (CI) is configured under `.github/workflows/ci.yml` for automated testing and linting.";
+  },
 };
 
 /**

package/src/layers/prettier/index.js

@@ -62,4 +62,16 @@ export default {
 
     return true;
   },
+
+  /**
+   * @param {import('#utils/project.js').Project} project
+   */
+  readme(project) {
+    return `### Prettier
+
+Code formatting is managed with [Prettier](https://prettier.io/).
+
+- \`${project.runPrefix} format\` - Format code
+- \`${project.runPrefix} lint:prettier\` - Check code formatting`;
+  },
 };

package/src/layers/readme/index.js

@@ -0,0 +1,176 @@
+import { existsSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { formatLabel } from "#utils/cli.js";
+
+/**
+ * @param {import('#utils/project.js').Project} project
+ * @param {string} layerDocsMarkdown
+ */
+function appReadme(project, layerDocsMarkdown) {
+  return `# ${project.name}
+
+An Ember application created with \`ember.nvp\`.
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js >= 24
+- ${project.packageManager}
+
+### Installation
+
+~~~sh
+${project.packageManager} install
+~~~
+
+### Development
+
+To start the local development server:
+
+~~~sh
+${project.runPrefix} dev
+~~~
+
+or
+
+~~~sh
+${project.runPrefix} start
+~~~
+${layerDocsMarkdown}`;
+}
+
+/**
+ * @param {import('#utils/project.js').Project} project
+ * @param {string} layerDocsMarkdown
+ */
+function extensionReadme(project, layerDocsMarkdown) {
+  return `# ${project.name}
+
+A browser extension using Ember created with \`ember.nvp\`.
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js >= 24
+- ${project.packageManager}
+
+### Development
+
+To start development:
+
+~~~sh
+${project.runPrefix} dev
+~~~
+
+or
+
+~~~sh
+${project.runPrefix} start
+~~~
+
+### Building
+
+To build the library:
+
+~~~sh
+${project.runPrefix} build
+~~~
+
+or
+
+~~~sh
+${project.runPrefix} build:watch
+~~~
+${layerDocsMarkdown}`;
+}
+
+/**
+ * @param {import('#utils/project.js').Project} project
+ * @param {string} layerDocsMarkdown
+ */
+function libraryReadme(project, layerDocsMarkdown) {
+  return `# ${project.name}
+
+An Ember library/addon created with \`ember.nvp\`.
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js >= 24
+- ${project.packageManager}
+
+### Development & Building
+
+To build the library:
+
+~~~sh
+${project.runPrefix} build
+~~~
+${layerDocsMarkdown}`;
+}
+
+export default {
+  label: formatLabel("README.md", "generate project documentation"),
+  hint: "project README",
+
+  async defaultValue() {
+    return true;
+  },
+
+  /**
+   * @param {import('#utils/project.js').Project} project
+   */
+  async run(project) {
+    // Collect layer docs
+    const layerDocs = [];
+    for (const layer of project.desires.layers) {
+      if (layer.name === "readme" || !layer.readme) {
+        continue;
+      }
+
+      let doc;
+      if (typeof layer.readme === "function") {
+        doc = await layer.readme(project);
+      } else if (typeof layer.readme === "string") {
+        doc = layer.readme;
+      }
+
+      if (doc && typeof doc === "string" && doc.trim().length > 0) {
+        layerDocs.push(doc.trim());
+      }
+    }
+
+    let layerDocsMarkdown = "";
+    if (layerDocs.length > 0) {
+      layerDocsMarkdown = `\n## Features & Tooling\n\n${layerDocs.join("\n\n")}\n`;
+    }
+
+    // Merge the layers' snippets into the main readme template
+    let content;
+    switch (project.type) {
+      case "extension":
+        content = extensionReadme(project, layerDocsMarkdown);
+        break;
+      case "library":
+        content = libraryReadme(project, layerDocsMarkdown);
+        break;
+      default:
+        content = appReadme(project, layerDocsMarkdown);
+        break;
+    }
+
+    const targetPath = join(project.directory, "README.md");
+    await writeFile(targetPath, `${content.trim()}\n`, "utf-8");
+  },
+
+  /**
+   * @param {import('#utils/project.js').Project} project
+   */
+  async isSetup(project) {
+    return existsSync(join(project.directory, "README.md"));
+  },
+};

package/src/layers/typescript/index.js

@@ -120,6 +120,17 @@ export default {
 
     return reasons.length === 0;
   },
+
+  /**
+   * @param {import('#utils/project.js').Project} project
+   */
+  readme(project) {
+    return `### TypeScript
+
+This project uses TypeScript and Glint for static type checking.
+
+- \`${project.runPrefix} lint:types\` - Typecheck code with Glint/TypeScript`;
+  },
 };
 
 /**

package/src/layers/vitest/index.js

@@ -101,4 +101,15 @@ export default {
 
     return reasons.length === 0;
   },
+
+  /**
+   * @param {import('#utils/project.js').Project} project
+   */
+  readme(project) {
+    return `### Testing (Vitest)
+
+Testing is configured with [Vitest](https://vitest.dev/).
+
+- \`${project.runPrefix} test\` - Run tests`;
+  },
 };

package/src/utils/project.js

@@ -47,6 +47,13 @@ export class Project {
     return this.desires.packageManager;
   }
 
+  /**
+   * @type {string}
+   */
+  get runPrefix() {
+    return this.packageManager === "npm" ? "npm run" : "pnpm";
+  }
+
   /**
    * @type {string}
    */