ember.nvp 1.7.0 → 1.8.0

package/src/cli/index.js

@@ -20,7 +20,7 @@ import { askReplaceOrUpdate } from "./questions/replace-or-update.js";
  * This whole file's primary purpose is to be an interactive CLI
  * for `generateProject`.
  *
- * Other tools can call `generateProject` themselves if they wish
+ * Other tools can call `generateProject` themselves
  * if they want to provide different TUI/GUIs.
  */
 async function main() {
@@ -38,19 +38,19 @@ async function main() {
   await askIfOK();
 
   /**
-   * Everything is generated in a stage: a real directory (in the OS temp
-   * dir) acting as a writable overlay of the target directory.
+   * Everything is generated in a stage:
+   * a real directory (in the OS temp dir) acting as a writable overlay of the target directory.
    *
-   * When updating an existing project, the stage is seeded with a full
-   * copy of it (sans node_modules/.git), so the bases and layers run
-   * against the project's current state -- isSetup checks, package.json
-   * reads, file existence checks, etc. all see the existing files, and
-   * the codemods modify them in the stage exactly as if they were
-   * operating in place. "replace" starts from an empty stage instead.
+   * When updating an existing project, the stage is seeded with a full copy of it
+   * (sans node_modules/.git), so the bases and layers run against the project's current state:
+   * - isSetup checks, package.json reads, file existence checks, etc. all see the existing files
+   * - the codemods modify them in the stage exactly as if they were operating in place
    *
-   * The target itself is not touched until stage.commit() below, which
-   * applies the difference between the stage and the target (or the
-   * subset of it the user accepts during review).
+   * "replace" starts from an empty stage instead.
+   *
+   * The target itself is not touched until stage.commit() below.
+   * That applies the difference between the stage and the target
+   * (or the subset of it the user accepts during review).
    */
   const stage = await Stage.create(projectPath, { seed: replaceOrUpdate !== "replace" });
 
@@ -98,9 +98,12 @@ async function main() {
   }
 
   /**
-   * New projects (and "replace", which was already confirmed) are written
-   * without asking. Updates to an existing project must be confirmed:
-   * write all / review each change (accept/reject) / cancel.
+   * New projects (and "replace", which was already confirmed) are written without asking.
+   *
+   * Updates to an existing project must be confirmed:
+   * - write all
+   * - review each change (accept/reject)
+   * - cancel
    */
   const isUpdate = !stage.isNew && replaceOrUpdate !== "replace";
 
@@ -123,9 +126,11 @@ async function main() {
 
   /**
    * Converted / generated files are written expecting the project's own
-   * formatting and lint pass to run right away (e.g. blank lines between
-   * import groups are `eslint --fix`'s job) -- so when the project has a
-   * lint:fix script, surface it as the step right after install.
+   * formatting and lint pass to run right away.
+   * (e.g. blank lines between import groups are `eslint --fix`'s job)
+   *
+   * So when the project has a lint:fix script,
+   * surface it as the step right after install.
    */
   let lintFixStep = "";
   try {

package/src/cli/questions/write.js

@@ -17,10 +17,11 @@ function isValid(selected) {
 }
 
 /**
- * Nothing has been written to the target directory yet -- everything so
- * far only exists in the stage. Ask whether to write the staged changes,
- * with the option to review the diff change-by-change, accepting or
- * rejecting each one.
+ * Nothing has been written to the target directory yet.
+ * Everything so far only exists in the stage.
+ *
+ * Ask whether to write the staged changes,
+ * with the option to review the diff change-by-change, accepting or rejecting each one.
  *
  * @param {import('#utils/stage.js').Stage} stage
  * @param {import('#utils/stage.js').Change[]} changes
@@ -61,10 +62,11 @@ export async function askToWrite(stage, changes) {
 }
 
 /**
- * Show each change's diff and ask what to do with it. "accept remaining"
- * and "reject remaining" finish the review early, so they require an
- * extra confirmation; declining the confirmation returns to the change
- * being reviewed.
+ * Show each change's diff and ask what to do with it.
+ *
+ * "accept remaining" and "reject remaining" finish the review early,
+ * so they require an extra confirmation.
+ * Declining the confirmation returns to the change being reviewed.
  *
  * @param {import('#utils/stage.js').Stage} stage
  * @param {import('#utils/stage.js').Change[]} changes
@@ -83,8 +85,8 @@ async function reviewEachChange(stage, changes) {
 
     const remaining = changes.length - index;
 
-    // Bypass clack for the diff itself: diffs are long, and clack's
-    // log decorations wrap every line.
+    // Bypass clack for the diff itself.
+    // Diffs are long, and clack's log decorations wrap every line.
     console.log("\n" + (await stage.diff([change])));
 
     const answer = await p.select({

package/src/layers/are-the-types-wrong/index.js

@@ -20,8 +20,8 @@ export default {
     // Declarations are the thing being checked
     if (!(await project.hasOrWantsLayer("typescript"))) return;
 
-    // ESM-only packages don't offer the CJS resolution modes the strict
-    // profile requires
+    // ESM-only packages don't offer the CJS resolution modes
+    // that the strict profile requires
     await addTsdownConfigProperty(project, "attw", `attw: { profile: "esm-only" }`);
     await packageJson.addDevDependencies(await getLatest(deps), project.directory);
   },
@@ -42,8 +42,8 @@ export default {
     /** @type {string[]} */
     const reasons = [];
 
-    // Nothing to set up outside TypeScript libraries, so nothing can be
-    // missing
+    // Nothing to set up outside TypeScript libraries,
+    // so nothing can be missing
     if (!project.isLibrary || !(await project.hasOrWantsLayer("typescript"))) {
       return explain ? { isSetup: true, reasons } : true;
     }

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

@@ -55,8 +55,9 @@ export default {
 };
 
 /**
- * This is a very silly way to handle YAML, but 🤷
- * will update if this starts getting to be troublesome.
+ * String concatenation is a very silly way to handle YAML, but 🤷
+ *
+ * Will update if this starts getting to be troublesome.
  */
 const preamble = `name: CI
 
@@ -135,8 +136,10 @@ async function transform(project) {
   content = await addOrUpdateTests(project, content);
 
   /**
-   * If we've still added nothing, we can't actually add the preamble
-   * because there are no jobs to run (we need at least one job).
+   * A workflow needs at least one job.
+   *
+   * If nothing was added, there is no job to run,
+   * so the preamble is not added either.
    */
   if (content === "") {
     return { content, original, didChange: original !== content, outputPath };

package/src/layers/inspector-support/index.js

@@ -42,8 +42,8 @@ export default {
       await writeFile(path, wired);
     }
 
-    // the dependency is only useful once the Application actually got
-    // wired (the codemod leaves unrecognized Application shapes alone)
+    // The codemod leaves unrecognized Application shapes alone.
+    // The dependency is only useful once the Application is wired.
     if (!hasInspectorSupport(wired, path)) return;
 
     await packageJson.addDevDependencies(await getLatest(deps), project.directory);

package/src/layers/qunit/index.js

@@ -18,9 +18,12 @@ const tsDeps = {
 };
 
 /**
- * Libraries don't have the app base's vite stack, so the test build
- * brings the pieces the generated configs and test-helper import
- * directly. Everything else (babel itself, the embroider machinery)
+ * Libraries don't have the app base's vite stack.
+ *
+ * So the test build brings the pieces that the generated configs
+ * and test-helper import directly.
+ *
+ * Everything else (babel itself, the embroider machinery)
  * comes with @nullvoxpopuli/ember-vite.
  */
 const libraryDeps = {
@@ -79,7 +82,6 @@ export default {
       project.directory,
     );
 
-    // Add scripts
     await packageJson.addScripts(
       {
         "build:test": "EMBER_ENV=test NODE_ENV=development vite build --mode development",
@@ -151,10 +153,11 @@ export default {
 };
 
 /**
- * Tests import the library's source (not its published dist), so the
- * `#src/*` subpath must exist before the test files are applied --
- * applying rewrites their import extensions by resolving each specifier
- * through this mapping.
+ * Tests import the library's source, not its published dist.
+ *
+ * The `#src/*` subpath must exist before the test files are applied:
+ * applying rewrites their import extensions
+ * by resolving each specifier through this mapping.
  *
  * @param {import('#utils/project.js').Project} project
  */
@@ -166,12 +169,13 @@ async function addSourceImports(project) {
 }
 
 /**
- * The test babel config is the qunit layer's own (a root babel config,
- * when a library has one, belongs to the publish build), so this layer
- * also keeps the config's TypeScript handling in step with the project:
- * the shipped config carries the TS plugin, which must not survive in a
- * JavaScript project, and must come back when a project adopts the
- * typescript layer later.
+ * The test babel config is the qunit layer's own.
+ * (a root babel config, when a library has one, belongs to the publish build)
+ *
+ * So this layer keeps the config's TypeScript handling in step with the project:
+ * - the shipped config carries the TS plugin
+ * - it must not survive in a JavaScript project
+ * - it must come back when a project adopts the typescript layer later
  *
  * @param {import('#utils/project.js').Project} project
  * @param {boolean} ts

package/src/layers/readme/index.js

@@ -74,13 +74,13 @@ ${project.runPrefix} start
 
 ### Building
 
-To build the library:
+To build the extension:
 
 \`\`\`sh
 ${project.runPrefix} build
 \`\`\`
 
-or
+or, to rebuild on change:
 
 \`\`\`sh
 ${project.runPrefix} build:watch
@@ -175,7 +175,6 @@ export default {
    * @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) {
@@ -199,7 +198,6 @@ export default {
       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":

package/src/layers/renovate/index.js

@@ -14,7 +14,8 @@ export default {
       return;
     }
 
-    // extensions aren't published to npm either, so they follow the app config
+    // extensions aren't published to npm either,
+    // so they follow the app config
     let source = project.isLibrary
       ? join(import.meta.dirname, "files/library.json5")
       : join(import.meta.dirname, "files/app.json5");

package/src/layers/typescript/index.js

@@ -4,7 +4,7 @@ import { cp } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { hasConfiguredTSBabel, prependPlugin } from "#utils/babel.js";
 import { getLatest } from "#utils/npm.js";
-import { isLibraryType } from "#utils/project.js";
+import { isLibraryType } from "#utils/project-type.js";
 
 const bases = join(import.meta.dirname, "../../bases");
 const appBase = join(bases, "minimal-app/files");
@@ -20,8 +20,8 @@ const sharedDeps = {
 };
 
 const appDeps = {
-  // Apps strip types via their own babel.config.js; libraries have no babel
-  // config -- ember() handles type stripping.
+  // Apps strip types via their own babel.config.js.
+  // Libraries have no babel config: ember() handles type stripping.
   "@babel/plugin-transform-typescript": "^7.28.5",
   "@ember/app-tsconfig": "^2.0.0",
 };
@@ -47,8 +47,8 @@ export default {
   label: "TypeScript",
 
   /**
-   * Libraries publish declarations, so they are TypeScript unless the
-   * user opts out.
+   * Libraries publish declarations,
+   * so they are TypeScript unless the user opts out.
    *
    * @param {import('#types').ProjectType} projectType
    */
@@ -58,10 +58,8 @@ export default {
 
   async run(project) {
     /**
-     * if jsconfig exists, switch to tsconfig
-     */
-    /**
-     * if tsconfig exists,
+     * TODO:
+     * - if jsconfig exists, switch to tsconfig
      */
     await addTSConfig(project);
     await updatePackageJson(project);
@@ -89,8 +87,8 @@ export default {
       reasons.push("tsconfig.json is missing");
     }
 
-    // Only projects with their own babel config need the TS plugin in it;
-    // without one (libraries), ember() strips types.
+    // Only projects with their own babel config need the TS plugin in it.
+    // Without one (libraries), ember() strips types.
     if (project.hasFile("babel.config.js") && !(await hasConfiguredTSBabel(project))) {
       if (!explain) return false;
 
@@ -151,6 +149,8 @@ async function updatePackageJson(project) {
 }
 
 /**
+ * Copies the base's tsconfig, unless the project already has one.
+ *
  * @param {import('#utils/project.js').Project} project
  */
 async function addTSConfig(project) {
@@ -183,7 +183,7 @@ async function addTSConfig(project) {
  */
 async function updateBabelConfig(project) {
   if (!project.hasFile("babel.config.js")) {
-    // No babel config to patch (libraries): ember() strips types.
+    // Nothing to patch (libraries): ember() strips types.
     return;
   }
 

package/src/layers/vitest/index.js

@@ -13,9 +13,13 @@ const deps = {
   webdriverio: "^9.29.1",
 };
 
-// Apps already get these from their base. The babel plugins are resolved
-// by name from the project by @nullvoxpopuli/ember-vite's no-config babel
-// fallback (decorator-transforms is already a base dependency).
+/**
+ * Apps already get these from their base.
+ *
+ * The babel plugins are resolved by name from the project,
+ * by @nullvoxpopuli/ember-vite's no-config babel fallback.
+ * (decorator-transforms is already a base dependency)
+ */
 const libraryDeps = {
   "@babel/plugin-transform-typescript": "^7.28.10",
   "@nullvoxpopuli/ember-vite": "workspace:*",

package/src/utils/babel.js

@@ -80,8 +80,9 @@ export async function prependPlugin(project, plugin, configPath = "babel.config.
 }
 
 /**
- * The plugins value may be the array itself, or the array with
- * methods chained off of it: `[ ... ].filter(Boolean)`
+ * The plugins value may be:
+ * - the array itself
+ * - the array with methods chained off of it: `[ ... ].filter(Boolean)`
  *
  * @param {any} node
  * @returns {any | undefined} the underlying ArrayExpression

package/src/utils/buffer.js

@@ -1,8 +1,8 @@
 /**
+ * Takes a substring of a string based on byte offsets.
+ *
  * from https://github.com/ember-cli/ember-cli/blob/8ea5b2e22d37805f5749a4917e0ef25fac3c9cda/lib/models/blueprint.js#L1789
  *
- *  Takes a substring of a string based on byte offsets.
-
  * @param {string} value : The input string.
  * @param {number} start : The byte index of the substring start.
  * @param {number} end : The byte index of the substring end.

package/src/utils/cli.js

@@ -7,12 +7,12 @@ export function isInteractive() {
 }
 
 /**
- * I would like to have selecs look more like a table,
+ * I would like to have selects look more like a table,
  * but @clack/prompts makes this a bit hard.
  *
- * I tried using padding, but then when it prints your selection,
- * I don't think there is a way to format just that, so
- * there are a bunch of goofy spacings in the labels.
+ * I tried using padding.
+ * But when it prints your selection, I don't think there is a way to format just that.
+ * So there are a bunch of goofy spacings in the labels.
  */
 const PADDING = 10;
 

package/src/utils/fs.js

@@ -7,17 +7,22 @@ import { rewriteImportsToMatchFiles } from "./rewrite-imports.js";
 
 /**
  * `**\/*` alone skips dotfiles, which bases legitimately provide
- * (`.gitignore`, `.env.development`, ...): the extra patterns match
- * dotfiles at any depth and files inside dot-directories (`.github/...`).
+ * (`.gitignore`, `.env.development`, ...).
+ *
+ * The extra patterns match:
+ * - dotfiles at any depth
+ * - files inside dot-directories (`.github/...`)
  */
 const EVERY_FILE = ["**/*", "**/.*", "**/.*/**/*"];
 
 /**
+ * Modified version of applyFolder from ember-apply.
  *
- * Modified version of applyFolder from ember-apply
- * where the caller gets to decide the final output filPath and contents - whereas the version from ember-apply only allows similar file paths in source and destination.
+ * Here, the caller decides the final output path and contents.
+ * The version from ember-apply only allows the same file paths
+ * in source and destination.
  *
- * We need customization because we will intake ts and output js
+ * We need that freedom because we intake ts and output js.
  *
  * @param {string} from
  * @param {{to: import('#utils/project.js').Project, process: (data: { entry: string, contents: string }) => string | Promise<void>}} options sub folder within the target project to copy the contents to
@@ -56,11 +61,12 @@ export async function applyFolderTo(from, project) {
   /**
    * Files we wrote, to be import-rewritten in a second pass.
    *
-   * Rewriting has to wait until every file is on disk: it checks which
-   * file a specifier actually resolves to, so rewriting while the folder
-   * is still half-applied depends on iteration order (e.g. `index.js`
-   * pointing at `./utils/math.ts` before `math.js` exists would be left
-   * alone, emitting a broken import).
+   * Rewriting has to wait until every file is on disk.
+   * It checks which file a specifier actually resolves to,
+   * so rewriting a half-applied folder depends on iteration order.
+   *
+   * For example: `index.js` pointing at `./utils/math.ts` before `math.js` exists
+   * would be left alone, emitting a broken import.
    *
    * @type {string[]}
    */
@@ -110,10 +116,13 @@ export async function applyFolderTo(from, project) {
   });
 
   /**
-   * Imports must always match the emitted files (and carry their
-   * extension). The util decides which files it applies to and is a
-   * no-op for everything else. Files that already existed are the
-   * user's; we leave them alone.
+   * Imports must always match the emitted files, and carry their extension.
+   *
+   * The util decides which files it applies to.
+   * It is a no-op for everything else.
+   *
+   * Files that already existed are the user's.
+   * We leave them alone.
    */
   for (let filePath of written) {
     let contents = await readFile(filePath, "utf-8");

package/src/utils/inspector-support.js

@@ -9,9 +9,9 @@ export const INSPECTOR_PACKAGE = "@embroider/legacy-inspector-support";
 export const INSPECTOR_ENTRY = `${INSPECTOR_PACKAGE}/ember-source-4.12`;
 
 /**
- * Modules whose default export is the Application (sub)class an app
- * extends. The class extending one of these is where inspector support
- * gets attached.
+ * Modules whose default export is the Application (sub)class an app extends.
+ *
+ * The class extending one of these is where inspector support gets attached.
  */
 const APPLICATION_MODULES = new Set(["ember-strict-application-resolver", "@ember/application"]);
 
@@ -56,10 +56,11 @@ function classMembers(classNode) {
 }
 
 /**
- * Everything wiring and detection need to know about the module: its
- * import declarations, the import from {@link INSPECTOR_PACKAGE} (any
- * subpath), the class extending an Application import, and that class's
- * `inspector` member.
+ * Everything wiring and detection need to know about the module:
+ * - its import declarations
+ * - the import from {@link INSPECTOR_PACKAGE} (any subpath)
+ * - the class extending an Application import
+ * - that class's `inspector` member
  *
  * @param {string} code
  * @param {string} filePath
@@ -117,9 +118,9 @@ function analyze(code, filePath) {
 }
 
 /**
- * Whether the module already wires inspector support: it imports
- * {@link INSPECTOR_PACKAGE} and its Application class carries the
- * `inspector` member.
+ * Whether the module already wires inspector support:
+ * - it imports {@link INSPECTOR_PACKAGE}
+ * - its Application class carries the `inspector` member
  *
  * @param {string} code
  * @param {string} filePath
@@ -143,16 +144,18 @@ export function hasInspectorSupport(code, filePath) {
  * }
  * ```
  *
- * The Application definition is found structurally -- any class
- * (declaration or expression, named, anonymous, or assigned to a
- * variable) extending a binding imported from an Application-providing
- * module -- so user-restructured app files are wired the same as
- * freshly generated ones.
+ * The Application definition is found structurally:
+ * any class extending a binding imported from an Application-providing module.
+ * - declaration or expression
+ * - named, anonymous, or assigned to a variable
+ *
+ * So user-restructured app files are wired the same as freshly generated ones.
+ *
+ * Idempotent.
+ * Already-wired (or partially wired) modules keep their existing import name and member.
  *
- * Idempotent: already-wired (or partially wired) modules keep their
- * existing import name and member. Returns the code unchanged when
- * there is nothing to do -- including when no Application definition
- * can be found.
+ * Returns the code unchanged when there is nothing to do,
+ * including when no Application definition can be found.
  *
  * @param {string} code
  * @param {string} filePath

package/src/utils/npm.js

@@ -8,9 +8,10 @@ import { join, resolve } from "node:path";
 const CACHE = {};
 
 /**
- * Local, not-yet-published workspace packages that must be `link:`ed rather
- * than resolved from the registry. Maps the published package name to its
- * folder under `packages/`.
+ * Local, not-yet-published workspace packages.
+ * These must be `link:`ed rather than resolved from the registry.
+ *
+ * Maps the published package name to its folder under `packages/`.
  *
  * @type {{ [name: string]: string }}
  */
@@ -37,16 +38,18 @@ export async function getLatest(deps) {
 
       /**
        * HACK FOR CI.
-       * In practice, these packages will be published separately, and those
-       * versions will be used. Only the local, not-yet-published
-       * @nullvoxpopuli/ember-* packages need the link; every other dependency
-       * must still resolve its real version.
        *
-       * We use `link:` (a symlink) rather than `file:` (a copy into the store)
-       * on purpose: the packages ship TypeScript source, and Node 24 refuses to
-       * strip types for files physically located under node_modules. A symlink
-       * makes Node resolve the realpath to packages/* (outside node_modules),
-       * so its `.ts` runs directly.
+       * In practice, these packages will be published separately,
+       * and those versions will be used.
+       *
+       * Only the local, not-yet-published @nullvoxpopuli/ember-* packages need the link.
+       * Every other dependency must still resolve its real version.
+       *
+       * We use `link:` (a symlink) rather than `file:` (a copy into the store) on purpose:
+       * - the packages ship TypeScript source
+       * - Node 24 refuses to strip types for files physically located under node_modules
+       * - a symlink makes Node resolve the realpath to packages/* (outside node_modules),
+       *   so its `.ts` runs directly
        */
       if (needsLocalLink && LOCAL_PACKAGES[dep]) {
         version =

package/src/utils/project-type.js

@@ -0,0 +1,19 @@
+/**
+ * Libraries and custom elements share one toolchain:
+ * - built with tsdown
+ * - no babel config
+ * - published to npm
+ *
+ * Layers that branch on "is this a library?" must treat both the same.
+ *
+ * This module has no imports on purpose.
+ * Layers are loaded by `#layers`, and `#utils/project.js` imports `#layers`.
+ * A layer that imports `#utils/project.js` at the top level
+ * creates a cycle that never settles, and Node exits with code 13.
+ *
+ * @param {import('#types').ProjectType} type
+ * @returns {boolean}
+ */
+export function isLibraryType(type) {
+  return type === "library" || type === "custom-element";
+}

package/src/utils/project.js

@@ -5,24 +5,15 @@ import { join } from "node:path";
 import { hasGit } from "#utils/git.js";
 import { assert } from "node:console";
 import { layers, layerNames } from "#layers";
+import { isLibraryType } from "#utils/project-type.js";
 
-/**
- * Libraries and custom elements share one toolchain: built with tsdown,
- * no babel config, published to npm. Layers that branch on "is this a
- * library?" must treat both the same.
- *
- * @param {import('#types').ProjectType} type
- * @returns {boolean}
- */
-export function isLibraryType(type) {
-  return type === "library" || type === "custom-element";
-}
+export { isLibraryType };
 
 /**
  * State container for the project.
  *
- * May eventually include information for discovering existing state
- * about a project.
+ * May eventually include information for discovering
+ * existing state about a project.
  */
 export class Project {
   #directory;