ember.nvp 1.6.0 → 1.7.1

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,12 +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";
+
+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;
@@ -40,6 +43,15 @@ export class Project {
     return this.desires.type;
   }
 
+  /**
+   * See {@link isLibraryType}
+   *
+   * @type {boolean}
+   */
+  get isLibrary() {
+    return isLibraryType(this.type);
+  }
+
   /**
    * @type {import('#types').PackageManager}
    */

package/src/utils/remove-types.js

@@ -26,9 +26,7 @@ export async function removeTypes(extension, code) {
 }
 
 /**
- *
  * Support for removeTypes
- *
  */
 
 const preprocessor = new Preprocessor();
@@ -78,8 +76,8 @@ async function wrappedRemoveTypes(code = "", callback = babelRemoveTypes) {
         templateTag,
       );
     } else {
-      // babel-remove-types uses prettier under the hood, and adds trailing `;` where allowed,
-      // so we need to take that into account when restoring the template tags:
+      // babel-remove-types uses prettier under the hood, and adds trailing `;` where allowed.
+      // Restoring the template tags has to account for that:
       transformedWithTemplateTag = transformedWithTemplateTag.replace(
         `${replacementExpression(i)};`,
         templateTag,

package/src/utils/rewrite-imports.js

@@ -6,10 +6,12 @@ import enhancedResolve from "enhanced-resolve";
 const { ResolverFactory, CachedInputFileSystem } = enhancedResolve;
 
 /**
- * The module files this util operates on. Doubles as the candidate
- * extensions the resolver may append when a request has none (or when we
- * retry a request without its original extension) -- the single source
- * of truth for both.
+ * The module files this util operates on.
+ *
+ * Doubles as the candidate extensions the resolver may append
+ * when a request has none, or when we retry a request without its original extension.
+ *
+ * The single source of truth for both.
  */
 const MODULE_EXTENSIONS = [".js", ".gjs", ".ts", ".gts"];
 
@@ -19,38 +21,48 @@ function createResolver() {
     fileSystem: new CachedInputFileSystem(fs, 100),
     useSyncFileSystemCalls: true,
     extensions: MODULE_EXTENSIONS,
-    // no conditionNames: we only resolve local paths and sub-path
-    // self-imports (whose targets in the emitted `imports` field are
-    // plain strings, which match regardless of conditions)
+    // no conditionNames: we only resolve local paths and sub-path self-imports.
+    // Their targets in the emitted `imports` field are plain strings,
+    // which match regardless of conditions.
   });
 }
 
 /**
- * Imports must match files. Generation renames files (e.g. type removal
- * turns .ts into .js), so for every local specifier (./, ../, and #
- * subpath-imports -- expanded against the project's package.json
- * `imports` field) we check what actually exists in the emitted project
- * tree:
+ * Imports must match files.
+ *
+ * Generation renames files (e.g. type removal turns .ts into .js).
+ * So for every local specifier, we check what actually exists in the emitted project tree.
  *
- * - the specifier resolves to a file and carries an extension? leave it
- *   alone.
- * - it resolves but has no extension? append the resolved file's
- *   extension (fully-specified local imports resolve faster), unless the
- *   fully-specified form no longer maps to the same file (e.g. `#config`,
- *   whose `imports` target carries the extension itself).
- * - it doesn't resolve, but the same specifier with whatever extension
- *   IS on disk does? rewrite it to that.
- * - nothing matches? leave it alone -- we can't know better, and the
- *   project's own build will report it loudly.
+ * Local specifiers are:
+ * - ./ and ../
+ * - # subpath-imports, expanded against the project's package.json `imports` field
+ *
+ * For each one:
+ * - it resolves to a file and carries an extension?
+ *   leave it alone.
+ * - it resolves but has no extension?
+ *   append the resolved file's extension (fully-specified local imports resolve faster).
+ *   Unless the fully-specified form no longer maps to the same file
+ *   (e.g. `#config`, whose `imports` target carries the extension itself).
+ * - it doesn't resolve, but the same specifier with whatever extension IS on disk does?
+ *   rewrite it to that.
+ * - nothing matches?
+ *   leave it alone. We can't know better, and the project's own build will report it.
  *
  * Non-module files are returned untouched.
  *
- * ember-estree parses gjs natively and its visitors fire on actual module
- * specifiers only (static imports, re-exports, and dynamic import()) --
- * matched specifiers are rewritten on the AST and the File is printed
- * back out (comments included). Formatting is the project's own concern:
- * new projects run their configured lint:fix / format right away (it's
- * in the CLI's "Next steps").
+ * ember-estree parses gjs natively.
+ * Its visitors fire on actual module specifiers only:
+ * - static imports
+ * - re-exports
+ * - dynamic import()
+ *
+ * Matched specifiers are rewritten on the AST,
+ * and the File is printed back out (comments included).
+ *
+ * Formatting is the project's own concern.
+ * New projects run their configured lint:fix / format right away
+ * (it's in the CLI's "Next steps").
  *
  * Files with no specifiers to rewrite are returned untouched.
  *
@@ -101,9 +113,9 @@ export function rewriteImportsToMatchFiles(code, emittedPath) {
       // fully specified and correct
       if (currentExtension) return;
 
-      // extensionless: append the resolved file's extension, as long as
-      // the fully-specified form still maps to the same file (`#config`
-      // maps with the extension in the target, so `#config.js` wouldn't)
+      // extensionless: append the resolved file's extension,
+      // as long as the fully-specified form still maps to the same file.
+      // (`#config` maps with the extension in the target, so `#config.js` wouldn't)
       let candidate = specifier + extname(resolved);
 
       if (resolveFrom(candidate) !== resolved) return;

package/src/utils/stage.js

@@ -6,9 +6,13 @@ import { styleText } from "node:util";
 import { structuredPatch } from "diff";
 
 /**
- * Directories that belong to the target project's environment rather than
- * its generated contents. They are never seeded into the stage, never
- * diffed, and never deleted on commit.
+ * Directories that belong to the target project's environment,
+ * not to its generated contents.
+ *
+ * They are:
+ * - never seeded into the stage
+ * - never diffed
+ * - never deleted on commit
  *
  * (`.git` has one exception: see {@link Stage#commit})
  */
@@ -20,30 +24,31 @@ const ENVIRONMENT_DIRECTORIES = new Set(["node_modules", ".git"]);
  */
 
 /**
- * A copy-on-write overlay for a project directory, in the spirit of
- * Docker's layered file systems:
+ * A copy-on-write overlay for a project directory,
+ * in the spirit of Docker's layered file systems:
  *
  * - the target directory is the read-only lower layer
  * - a real directory in the OS temp dir is the writable upper layer,
  *   seeded ("copied up") from the target
  *
- * All generation (bases, layers, consolidators) runs against the upper
- * layer via `stage.directory`. Because the upper layer is a real
- * directory, layers keep using `node:fs`, `ember-apply`, and even
- * subprocesses (`git`, package managers) exactly as they would against
- * the real project -- an in-process virtual fs can't offer that, since
- * child processes can't see it.
+ * All generation (bases, layers, consolidators) runs against the upper layer,
+ * via `stage.directory`.
+ *
+ * The upper layer is a real directory on purpose.
+ * Layers keep using `node:fs`, `ember-apply`, and subprocesses
+ * (`git`, package managers) exactly as they would against the real project.
+ * An in-process virtual fs can't offer that: child processes can't see it.
  *
- * Nothing touches the target until {@link Stage#commit}; {@link Stage#discard}
- * throws the upper layer away.
+ * Nothing touches the target until {@link Stage#commit}.
+ * {@link Stage#discard} throws the upper layer away.
  */
 export class Stage {
   /**
-   * @param {string} targetDirectory the directory the project should end up in
+   * @param {string} targetDirectory the directory the project must end up in
    * @param {{ seed?: boolean }} [options]
-   *   seed: copy the target's current contents into the stage first
-   *   (a "copy up"). Defaults to true. Pass false to stage a from-scratch
-   *   generation (e.g. the "replace" flow).
+   *   seed: copy the target's current contents into the stage first (a "copy up").
+   *   Defaults to true.
+   *   Pass false to stage a from-scratch generation (e.g. the "replace" flow).
    * @returns {Promise<Stage>}
    */
   static async create(targetDirectory, options = {}) {
@@ -80,8 +85,10 @@ export class Stage {
   }
 
   /**
-   * The writable upper layer. Generate in here,
-   * e.g. `new Project(stage.directory, desires)`.
+   * The writable upper layer.
+   *
+   * Generate in here:
+   *   `new Project(stage.directory, desires)`
    *
    * @type {string}
    */
@@ -169,19 +176,23 @@ export class Stage {
   }
 
   /**
-   * Applies the staged changes to the target directory, then removes the
-   * stage. Only paths reported by {@link Stage#changes} are touched --
-   * everything else in the target (untracked files, node_modules, .git)
-   * is left alone.
+   * Applies the staged changes to the target directory, then removes the stage.
    *
-   * One exception: when the stage has a `.git` directory and the target
-   * does not (the git layer ran `git init` inside the stage), the `.git`
-   * directory is carried over so a freshly generated project keeps its
-   * history.
+   * Only paths reported by {@link Stage#changes} are touched.
+   * Everything else in the target is left alone:
+   * - untracked files
+   * - node_modules
+   * - .git
    *
-   * @param {Change[]} [changes] the changes to apply -- pass a subset of
-   *   {@link Stage#changes} to apply only some of them (e.g. the ones a
-   *   user accepted during review). Defaults to all staged changes.
+   * One exception: when the stage has a `.git` directory and the target does not
+   * (the git layer ran `git init` inside the stage),
+   * the `.git` directory is carried over.
+   * A freshly generated project keeps its history that way.
+   *
+   * @param {Change[]} [changes] the changes to apply.
+   *   Pass a subset of {@link Stage#changes} to apply only some of them
+   *   (e.g. the ones a user accepted during review).
+   *   Defaults to all staged changes.
    * @returns {Promise<Change[]>} the changes that were written
    */
   async commit(changes) {
@@ -222,9 +233,9 @@ export class Stage {
 }
 
 /**
- * All files (as paths relative to `directory`), excluding environment
- * directories. Includes dotfiles (`.gitignore`, `.github/`, ...), which
- * `fs.glob` would skip.
+ * All files, as paths relative to `directory`, excluding environment directories.
+ *
+ * Includes dotfiles (`.gitignore`, `.github/`, ...), which `fs.glob` skips.
  *
  * @param {string} directory
  * @returns {Promise<Set<string>>}

package/src/utils/tsdown-config.js

@@ -2,12 +2,13 @@ import { readFile, writeFile } from "node:fs/promises";
 import { toTree, print, statements } from "ember-estree";
 
 /**
- * Adds a property to the object passed to `defineConfig(...)` in the
- * project's tsdown.config.js.
+ * Adds a property to the object passed to `defineConfig(...)`
+ * in the project's tsdown.config.js.
  *
- * No-ops when the property is already present (layers re-run), and when
- * the config doesn't have the `defineConfig({ ... })` shape -- an existing
- * project's hand-rolled config is the user's to manage.
+ * No-ops when:
+ * - the property is already present (layers re-run)
+ * - the config doesn't have the `defineConfig({ ... })` shape
+ *   (an existing project's hand-rolled config is the user's to manage)
  *
  * @param {import('#utils/project.js').Project} project
  * @param {string} propertyName

package/src/utils/types.ts

@@ -1,6 +1,6 @@
 import { Project } from "./project.js";
 export type PackageManager = "pnpm" | "npm";
-export type ProjectType = "app" | "library" | "extension";
+export type ProjectType = "app" | "library" | "extension" | "custom-element";
 
 export interface Layer {
   /**
@@ -9,13 +9,14 @@ export interface Layer {
   label: string;
   hint?: string;
   /**
-   * Whether the layer is pre-selected in the CLI (the user can still
-   * deselect it).
+   * Whether the layer is pre-selected in the CLI.
+   * The user can still 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.
+   * Optional README documentation snippet or function.
+   *
+   * Whatever is returned shows up in the generated project's README file.
    */
   readme?: string | ((project: Project) => string | undefined | Promise<string | undefined>);
   /**
@@ -40,10 +41,10 @@ export interface Layer {
 
 export interface DiscoveredLayer extends Layer {
   /**
-   * The unique name of the layer
-   * (exact match of the folder name
-   *   not provided by the layer
-   * )
+   * The unique name of the layer.
+   *
+   * An exact match of the folder name.
+   * Not provided by the layer itself.
    */
   name: string;
 }