ember.nvp 1.7.0 → 1.7.1

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

@@ -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;
 }

package/test/ember.nvp/base-library.test.ts

@@ -8,10 +8,12 @@ import { join } from "node:path";
 import type { Project } from "ember.nvp";
 
 /**
- * The minimal-library base has to produce a *buildable* library: these tests
- * generate both flavors (JavaScript and TypeScript), snapshot the interesting
- * generated files, and run the real `pnpm build` (tsdown + rolldown) against
- * them.
+ * The minimal-library base has to produce a *buildable* library.
+ *
+ * These tests:
+ * - generate both flavors (JavaScript and TypeScript)
+ * - snapshot the interesting generated files
+ * - run the real `pnpm build` (tsdown + rolldown) against them
  */
 
 async function installAndBuild(project: Project) {

package/test/ember.nvp/generator-replace-or-update.test.ts

@@ -7,10 +7,12 @@ import { join } from "node:path";
 
 /**
  * The replace-or-update question only matters when a project already exists
- * at the target path. These tests generate a project, assert the baseline
- * state, then regenerate over it the way the CLI does once the user has
- * answered the question, and assert the resulting project output is correct
- * for each answer.
+ * at the target path.
+ *
+ * These tests:
+ * - generate a project and assert the baseline state
+ * - regenerate over it, the way the CLI does once the user has answered
+ * - assert the resulting project is correct for each answer
  */
 describe("generating over an existing project", () => {
   const prettier = layers.find((layer) => layer.name === "prettier")!;

package/test/ember.nvp/inspector-support.test.ts

@@ -3,9 +3,10 @@ import { describe, it, expect } from "vitest";
 import { hasInspectorSupport, wireInspectorSupport } from "#utils/inspector-support.js";
 
 /**
- * The Application definition is found structurally, so every shape an app
- * author may have refactored their app file into gets wired the same way
- * the freshly generated shape does.
+ * The Application definition is found structurally.
+ *
+ * So every shape an app author has refactored their app file into
+ * gets wired the same way the freshly generated shape does.
  */
 describe("wireInspectorSupport", () => {
   it("wires the generated shape (export default class extends Application)", () => {

package/test/ember.nvp/layer-inspector-support.test.ts

@@ -43,11 +43,10 @@ describe("layer: inspector-support", () => {
       "/**
        * Looking for services that come from addons?
        *
+       * App-tree merging from libraries is not supported.
        * See: https://github.com/embroider-build/embroider/issues/2659
        *
-       * We currently don't support app-tree merging from libraries.
-       *
-       * For services, I highly recommend looking in to either of
+       * For services, look in to either of:
        * - https://github.com/chancancode/ember-polaris-service-
        * - https://ember-primitives.pages.dev/6-utils/createService.md
        *   - https://ember-primitives.pages.dev/6-utils/createAsyncService.md

package/test/ember.nvp/layer-publish-checks.test.ts

@@ -6,9 +6,8 @@ import { rm } from "node:fs/promises";
 import type { Project } from "ember.nvp";
 
 /**
- * publint and are-the-types-wrong run inside the library's own build
- * (tsdown), so the real assertion is their report lines in `pnpm build`
- * output.
+ * publint and are-the-types-wrong run inside the library's own build (tsdown),
+ * so the real assertion is their report lines in `pnpm build` output.
  */
 
 describe("layers: publint + are-the-types-wrong", () => {

package/test/ember.nvp/layer-qunit.test.ts

@@ -16,8 +16,8 @@ async function installAndTest(project: Project) {
 }
 
 /**
- * The layer ships testing infrastructure only; the tests exercising the
- * base's example exports are generated here, in both flavors.
+ * The layer ships testing infrastructure only.
+ * The tests exercising the base's example exports are generated here, in both flavors.
  */
 const exampleTests = {
   typescript: {

package/test/ember.nvp/layer-readme.test.ts

@@ -168,13 +168,13 @@ describe("layer: readme", () => {
 
         ### Building
 
-        To build the library:
+        To build the extension:
 
         \`\`\`sh
         pnpm build
         \`\`\`
 
-        or
+        or, to rebuild on change:
 
         \`\`\`sh
         pnpm build:watch

package/test/ember.nvp/layer-vitest.test.ts

@@ -9,9 +9,12 @@ import type { Project } from "ember.nvp";
 
 /**
  * The vitest layer ships infrastructure only (config, deps, scripts).
- * These tests generate projects with the layer, emit specs that exercise
- * each project's real exports, and run the real `pnpm test` (vitest in
- * headless-browser mode), asserting the specs genuinely run and pass.
+ *
+ * These tests:
+ * - generate projects with the layer
+ * - emit specs that exercise each project's real exports
+ * - run the real `pnpm test` (vitest in headless-browser mode),
+ *   and assert the specs run and pass
  */
 
 async function emit(project: Project, files: Record<string, string>) {
@@ -32,9 +35,11 @@ async function installAndTest(project: Project) {
 }
 
 /**
- * Specs against the library base's real exports, in the flavor matching
- * the generated project (these files are emitted by this test, not
- * shipped by the layer, so no automatic conversion applies).
+ * Specs against the library base's real exports,
+ * in the flavor matching the generated project.
+ *
+ * These files are emitted by this test, not shipped by the layer,
+ * so no automatic conversion applies.
  */
 function libraryTests(ext: "ts" | "js") {
   return {
@@ -82,9 +87,11 @@ describe("add", () => {
 }
 
 /**
- * Specs against the app base's real modules: boots an app made from the
- * app's own router class (pointed at a test-friendly location) and
- * application template, and visits its application route.
+ * Specs against the app base's real modules.
+ *
+ * Boots an app made from the app's own router class
+ * (pointed at a test-friendly location) and application template,
+ * then visits its application route.
  */
 function appTests(ext: "ts" | "js") {
   return {

package/test/ember.nvp/layers-load.test.ts

@@ -0,0 +1,26 @@
+import { test, expect } from "vitest";
+import { execa } from "execa";
+import { join } from "node:path";
+
+const root = join(import.meta.dirname, "../..");
+
+/**
+ * vitest runs modules through its own loader,
+ * so it does not see import cycles the way Node does.
+ *
+ * `#layers` awaits a dynamic import of each layer at the top level.
+ * If a layer imports a module that imports `#layers` back,
+ * the top-level await never settles and Node exits with code 13.
+ *
+ * Node's loader is the only thing that catches that,
+ * so load the module in a child process.
+ */
+test("the layers module loads in a plain node process", async () => {
+  const result = await execa(process.execPath, ["src/layers/index.js"], {
+    cwd: root,
+    reject: false,
+  });
+
+  expect(result.stderr).not.toContain("unsettled top-level await");
+  expect(result.exitCode).toBe(0);
+});

package/test/ember.nvp/library-src-fixtures.ts

@@ -4,9 +4,13 @@ import { dirname, join } from "node:path";
 import type { Project } from "ember.nvp";
 
 /**
- * The library base generates an empty `src/`; tests that build or test a
- * library write this example source (a class component, a template-only
- * component, and a plain module) into the generated project first.
+ * The library base generates an empty `src/`.
+ *
+ * Tests that build or test a library write this example source
+ * into the generated project first:
+ * - a class component
+ * - a template-only component
+ * - a plain module
  */
 export const librarySource = {
   typescript: {

package/test/ember.nvp/permutations/shared.ts

@@ -22,8 +22,9 @@ const INITIAL_ONLY = new Set<string>([
 
 /**
  * Layers that don't yet generate a working setup for a project type.
- * Every layer is *supposed* to support every base eventually -- shrink
- * these as layers learn.
+ *
+ * Every layer is *supposed* to support every base eventually.
+ * Shrink these as layers learn.
  */
 const NOT_YET_SUPPORTED: Record<ProjectType, Set<string>> = {
   // publish checks: apps aren't published
@@ -44,11 +45,14 @@ const TYPE_FOR_BASE: Record<(typeof bases)[number], ProjectType> = {
 };
 
 /**
- * Layers that only add lint / format / publish checks. They don't affect
- * the runtime shape of a project, so they permutate among themselves in a
- * small "checks" matrix instead of multiplying the main one. ("apply anew"
- * still applies each of them on top of every main permutation, so linear
- * cross-group coverage remains.)
+ * Layers that only add lint / format / publish checks.
+ *
+ * They don't affect the runtime shape of a project,
+ * so they permutate among themselves in a small "checks" matrix
+ * instead of multiplying the main one.
+ *
+ * "apply anew" still applies each of them on top of every main permutation,
+ * so linear cross-group coverage remains.
  */
 const CHECK_LAYERS = new Set<string>([
   "eslint-bundled-ember",
@@ -105,11 +109,14 @@ const eachBase = bases.map((base) => {
 });
 
 /**
- * The permutation matrix grows exponentially with the layer count, so
- * each base runs from its own test file(s) -- CI runs them as separate,
- * parallel jobs. A base whose matrix outgrows one job's budget runs from
- * several files, each taking a deterministic 1-of-N slice. The "checks"
- * group (CHECK_LAYERS) runs from its own file(s) the same way.
+ * The permutation matrix grows exponentially with the layer count,
+ * so each base runs from its own test file(s).
+ * CI runs them as separate, parallel jobs.
+ *
+ * A base whose matrix outgrows one job's budget runs from several files,
+ * each taking a deterministic 1-of-N slice.
+ *
+ * The "checks" group (CHECK_LAYERS) runs from its own file(s) the same way.
  *
  * @param base which base's permutations this file runs
  * @param options.index / options.total which 1-of-N slice of the permutations this file runs