ember.nvp 1.1.0 → 1.3.0

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,34 @@ 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 `tsconfig: false`) or
+ * without the `typescript` package have no declarations to emit, so there is
+ * nothing to check.
  */
 export function emberIsolatedDeclarations(): Plugin {
+  let tsconfigOption: string | boolean | undefined;
+
   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;
+    },
+
     async buildStart() {
-      const tsconfigPath = resolve("tsconfig.json");
+      const tsconfigPath = resolveTsconfigPath(tsconfigOption);
 
-      if (!existsSync(tsconfigPath)) return;
+      if (!tsconfigPath || !existsSync(tsconfigPath)) return;
 
       let ts: typeof import("typescript");
 
@@ -57,7 +102,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() {},
@@ -170,4 +173,87 @@ 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-"));
+
+    const files = {
+      // index.ts contains a `.gts` specifier, so it goes through the rewrite.
+      "index.ts": `export { default as Foo } from './foo.gts';`,
+      "foo.gts": `<template>Foo</template>`,
+    };
+
+    for (const [relative, source] of Object.entries(files)) {
+      await writeFile(path.join(dir, relative), source, "utf8");
+    }
+
+    const warnings: string[] = [];
+    const build = await rolldown({
+      input: path.join(dir, "index.ts"),
+      plugins: [emberTransform()],
+      external: (id) => !(id.startsWith(".") || path.isAbsolute(id)),
+      onwarn(warning) {
+        warnings.push(warning.code ?? String(warning));
+      },
+    });
+
+    const { output } = await build.generate({ format: "es", sourcemap: true });
+
+    expect(warnings.filter((code) => code === "SOURCEMAP_BROKEN")).toEqual([]);
+
+    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).
+    const sources = (chunk as { map?: { sources: string[] } }).map?.sources ?? [];
+    expect(sources.some((source) => source.endsWith("foo.gts"))).toBe(true);
+  });
 });

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";
@@ -38,58 +38,96 @@ async function fixDtsExtensionsInDir(dir: string): Promise<void> {
   }
 }
 
+/**
+ * A sourcemap mapping every generated line to the same line of the input.
+ *
+ * `AAAA` is the [0, 0, 0, 0] VLQ segment (first line maps to source 0, line 0,
+ * column 0); `AACA` is [0, 0, +1, 0] (each following line advances the source
+ * line by one). Exact at line granularity, which is all the specifier rewrite
+ * can disturb.
+ */
+function lineIdentityMap(id: string, source: string) {
+  return {
+    version: 3,
+    sources: [id],
+    sourcesContent: [source],
+    names: [],
+    mappings: source
+      .split("\n")
+      .map((_, line) => (line === 0 ? "AAAA" : "AACA"))
+      .join(";"),
+  };
+}
+
 /**
  * Maps `.gts` -> `.ts` and `.gjs` -> `.js` (so rolldown can identify them as
  * ts/js) and preprocesses `<template>` via content-tag.
  */
 export function emberTransform(): Plugin {
-  const virtualFiles = new Set<string>();
-
   return {
     name: "ember:transform",
 
     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);
 
-        if (id.endsWith(".gts") && !importer.endsWith(".d.ts")) {
-          virtualFiles.add(fileName);
+        if (id.endsWith(".gts")) {
           return {
             id: fileName.replace(/\.gts$/, ".ts"),
             meta: { fileName },
           };
         }
 
-        if (id.endsWith(".gjs") && !importer.endsWith(".d.ts")) {
-          virtualFiles.add(fileName);
+        if (id.endsWith(".gjs")) {
           return {
             id: fileName.replace(/\.gjs$/, ".js"),
             meta: { fileName },
           };
         }
 
-        if (id.endsWith(".d.ts") && importer.endsWith(".d.ts")) {
-          const gtsFile = fileName.replace(".d.ts", ".gts");
-          if (virtualFiles.has(gtsFile)) {
-            return fileName;
-          }
-        }
-
-        if (id.endsWith(".ts") && !importer.endsWith(".d.ts")) {
+        // A `.ts`/`.js` specifier whose only backing file is a `.gts`/`.gjs`
+        // resolves to the virtual module. This must also serve `.d.ts`
+        // importers: rolldown-plugin-dts resolves a declaration module's
+        // imports through the plugin pipeline (`this.resolve`), and — when the
+        // resolution is a source file — loads it (registering its declaration)
+        // before mapping the import to the declaration id. Virtual modules
+        // exist nowhere else, so if we don't answer here the import either
+        // fails to resolve (no file on disk) or, worse, resolves to a
+        // declaration id that was never registered.
+        if (id.endsWith(".ts")) {
           const gtsFileName = fileName.replace(/\.ts$/, ".gts");
           if (existsSync(gtsFileName) && !existsSync(fileName)) {
-            virtualFiles.add(gtsFileName);
             return { id: fileName, meta: { fileName: gtsFileName } };
           }
         }
 
-        if (id.endsWith(".js") && !importer.endsWith(".d.ts")) {
+        if (id.endsWith(".js")) {
           const gjsFileName = fileName.replace(/\.js$/, ".gjs");
           if (existsSync(gjsFileName) && !existsSync(fileName)) {
-            virtualFiles.add(gjsFileName);
             return { id: fileName, meta: { fileName: gjsFileName } };
           }
         }
@@ -105,7 +143,18 @@ export function emberTransform(): Plugin {
       },
       async handler(id) {
         const meta = this.getModuleInfo(id)?.meta ?? {};
-        const fileName = meta?.fileName;
+        let fileName = meta?.fileName;
+
+        // A virtual id can be loaded without having passed through our
+        // resolveId (rolldown-plugin-dts calls `this.load({ id })` with just
+        // the id), so no meta is attached: recover the backing file from disk.
+        if (!fileName && !existsSync(id)) {
+          if (id.endsWith(".ts") && existsSync(id.replace(/\.ts$/, ".gts"))) {
+            fileName = id.replace(/\.ts$/, ".gts");
+          } else if (id.endsWith(".js") && existsSync(id.replace(/\.js$/, ".gjs"))) {
+            fileName = id.replace(/\.js$/, ".gjs");
+          }
+        }
 
         if (fileName) {
           this.addWatchFile(fileName);
@@ -132,21 +181,26 @@ export function emberTransform(): Plugin {
         id: /\.(js|ts)$/,
       },
       handler(input, id) {
-        if (input.includes(".gts") && id.endsWith(".d.ts")) {
-          return input.replace(
-            /(['"`])((?:\.\.?\/|\/|@|[A-Za-z0-9_\-])[^'"]*?\.gts)\1/g,
-            (_m, q, p) => `${q}${p.replace(/\.gts$/, ".d.ts")}${q}`,
-          );
-        }
-
-        if (input.includes(".gts") && !id.endsWith(".d.ts")) {
-          return input.replace(
-            /(['"`])((?:\.\.?\/|\/|@|[A-Za-z0-9_\-])[^'"]*?\.gts)\1/g,
-            (_m, q, p) => `${q}${p.replace(/\.gts$/, ".ts")}${q}`,
-          );
+        // Rewrite `.gts` specifiers to `.ts` — the (virtual) source id — in
+        // runtime modules AND declaration modules alike. Declaration modules
+        // must NOT be rewritten to `.d.ts`: rolldown-plugin-dts's resolver
+        // treats a source-file resolution as "load it (registering its
+        // declaration), then map to the declaration id", while a `.d.ts` id is
+        // returned as-is — unloadable when the module isn't registered yet
+        // (e.g. the `.gts` is only ever type-imported).
+        const output = input.replace(
+          /(['"`])((?:\.\.?\/|\/|@|[A-Za-z0-9_\-])[^'"]*?\.gts)\1/g,
+          (_m, q, p) => `${q}${p.replace(/\.gts$/, ".ts")}${q}`,
+        );
+
+        if (output === input) {
+          return null;
         }
 
-        return input;
+        // The rewrite only shortens import specifiers in place, so a
+        // line-identity map is accurate to the line (and to the column for
+        // everything before the first rewritten specifier on a line).
+        return { code: output, map: lineIdentityMap(id, input) };
       },
     },
 

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}
    */

package/src/utils/types.ts

@@ -13,6 +13,11 @@ export interface Layer {
    * deselect it).
    */
   defaultValue?: (projectType: ProjectType) => unknown;
+  /**
+   * Optional README documentation snippet or function. Whatever is returned
+   * will show up in the generated project's README file.
+   */
+  readme?: string | ((project: Project) => string | undefined | Promise<string | undefined>);
   /**
    * The function that applies the codemod
    *