ember.nvp 1.8.0 → 1.10.0

package/src/utils/npm.js

@@ -35,6 +35,7 @@ export async function getLatest(deps) {
       }
 
       let version;
+      let alias = parseAlias(range);
 
       /**
        * HACK FOR CI.
@@ -54,6 +55,8 @@ export async function getLatest(deps) {
       if (needsLocalLink && LOCAL_PACKAGES[dep]) {
         version =
           "link:" + resolve(join(import.meta.dirname, "../../packages", LOCAL_PACKAGES[dep]));
+      } else if (alias) {
+        version = `npm:${alias.name}@${await latestVersion(alias.name, { version: alias.range })}`;
       } else {
         if (range == "workspace:*") {
           range = "latest";
@@ -71,6 +74,30 @@ export async function getLatest(deps) {
   return Object.fromEntries(results);
 }
 
+/**
+ * An npm alias installs a package under another name:
+ *
+ *   "@typescript/native": "npm:typescript@^7.1.0-0"
+ *
+ * The range belongs to the aliased package.
+ *
+ * @param {string} range
+ * @returns {{ name: string; range: string } | undefined}
+ */
+function parseAlias(range) {
+  if (!range.startsWith("npm:")) return;
+
+  let spec = range.slice("npm:".length);
+  // The last `@` starts the range. A scope's `@` is at index 0.
+  let at = spec.lastIndexOf("@");
+
+  if (at <= 0) {
+    return { name: spec, range: "latest" };
+  }
+
+  return { name: spec.slice(0, at), range: spec.slice(at + 1) };
+}
+
 async function needsWorkspace() {
   if (process.env.GITHUB_REPOSITORY === "NullVoxPopuli/ember.nvp") return true;
 

package/src/utils/project.js

@@ -80,6 +80,29 @@ export class Project {
     return this.#desires;
   }
 
+  /**
+   * Get resolved options for a specific layer, merging defaults with user-supplied options.
+   *
+   * @param {string} layerName
+   * @returns {Record<string, any>}
+   */
+  getLayerOptions(layerName) {
+    let layer = this.desires.layers?.find((l) => l.name === layerName);
+    /** @type {Record<string, any>} */
+    let defaults = {};
+
+    if (layer?.options) {
+      for (const [key, schema] of Object.entries(layer.options)) {
+        if (schema.default !== undefined) {
+          defaults[key] = schema.default;
+        }
+      }
+    }
+
+    let userOptions = this.desires.options?.[layerName] ?? {};
+    return { ...defaults, ...userOptions };
+  }
+
   /**
    * @param {string} name
    * @returns {Promise<boolean>}

package/src/utils/types.ts

@@ -1,13 +1,61 @@
+import type { Validate } from "@clack/core";
 import { Project } from "./project.js";
 export type PackageManager = "pnpm" | "npm";
 export type ProjectType = "app" | "library" | "extension" | "custom-element";
 
+export type LayerOptionType = "text" | "number" | "select" | "confirm" | "multiselect";
+
+export interface LayerSelectChoice {
+  /**
+   * A string, because the same value is also typed as a CLI flag
+   */
+  value: string;
+  label: string;
+  hint?: string;
+}
+
+export interface LayerOptionSchema {
+  type: LayerOptionType;
+  /**
+   * The question to ask, also shown in `--help`
+   */
+  prompt: string;
+  default?: any;
+  /**
+   * The choices for "select" and "multiselect"
+   */
+  options?: LayerSelectChoice[];
+  /**
+   * The same as clack's `validate`:
+   * a function that returns a message (or an Error) to reject the value,
+   * or a Standard Schema.
+   *
+   * Receives the value after conversion to the option's type.
+   */
+  validate?: Validate<any>;
+  /**
+   * Reads the value that an existing project uses now.
+   *
+   * When updating a project, the prompt starts at this value instead of `default`,
+   * so that pressing enter keeps the project as it is.
+   */
+  detect?: (project: Project) => unknown;
+}
+
+export interface LayerOptionsSchema {
+  [optionKey: string]: LayerOptionSchema;
+}
+
 export interface Layer {
   /**
    * The text to show during selection
    */
   label: string;
   hint?: string;
+  /**
+   * Optional schema of configurable options for this layer
+   */
+  options?: LayerOptionsSchema;
   /**
    * Whether the layer is pre-selected in the CLI.
    * The user can still deselect it.
@@ -24,8 +72,10 @@ export interface Layer {
    *
    * run _may_ be invoked multiple times,
    * so it's important to not require interaction here
+   *
+   * `options` are this layer's options, with defaults filled in.
    */
-  run: (project: Project) => Promise<void>;
+  run: (project: Project, options: Record<string, any>) => Promise<void>;
   isSetup: <Explain extends boolean = false>(
     project: Project,
     explain?: Explain,
@@ -55,4 +105,5 @@ export interface Answers {
   name: string;
   layers: DiscoveredLayer[];
   packageManager: PackageManager;
+  options?: Record<string, Record<string, any>>;
 }

package/src/utils/typescript.js

@@ -0,0 +1,147 @@
+import { packageJson } from "ember-apply";
+import { join } from "node:path";
+import { cp } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { hasConfiguredTSBabel, prependPlugin } from "#utils/babel.js";
+import { getLatest } from "#utils/npm.js";
+
+const bases = join(import.meta.dirname, "../bases");
+const appBase = join(bases, "minimal-app/files");
+const extensionBase = join(bases, "minimal-extension/files");
+const libraryBase = join(bases, "minimal-library/files");
+const customElementBase = join(bases, "minimal-custom-element/files");
+
+/**
+ * TypeScript 7 has no JavaScript API.
+ *
+ * typescript-eslint imports `typescript`, so it keeps using TypeScript 6.
+ *
+ * `@typescript/typescript6` is TypeScript 6 with a `tsc6` bin,
+ * so `tsc` stays TypeScript 7.
+ */
+export const TYPESCRIPT_6 = "npm:@typescript/typescript6@^6.0.2";
+
+/**
+ * Content mappers (for .gts and .gjs) need 7.1 or newer.
+ */
+export const TYPESCRIPT_7 = "npm:typescript@^7.1.0-0";
+
+/**
+ * @param {Record<string, any>} manifest
+ * @returns {boolean}
+ */
+export function hasTypeScript6(manifest) {
+  let spec = manifest.devDependencies?.typescript;
+
+  return typeof spec === "string" && spec.startsWith("npm:@typescript/typescript6@");
+}
+
+/**
+ * @param {import('#utils/project.js').Project} project
+ * @returns {boolean}
+ */
+export function wantsTypeScript7(project) {
+  return project.wantsLayer("typescript") && project.getLayerOptions("typescript").version === "7";
+}
+
+/**
+ * Reads the manifest instead of asking the typescript layer.
+ * That layer's isSetup asks about eslint, and the eslint layers ask about TypeScript 7.
+ *
+ * @param {import('#utils/project.js').Project} project
+ * @param {Record<string, any>} manifest
+ * @returns {boolean}
+ */
+export function usesTypeScript7(project, manifest) {
+  return wantsTypeScript7(project) || Boolean(manifest.devDependencies?.["@typescript/native"]);
+}
+
+/**
+ * @param {import('#utils/project.js').Project} project
+ * @param {Record<string, any>} manifest
+ * @returns {boolean}
+ */
+export function needsTypeScript6(project, manifest) {
+  return project.wantsLayer("eslint") || Boolean(manifest.devDependencies?.eslint);
+}
+
+/**
+ * In a TypeScript 7 project:
+ * - keeps `@typescript/typescript6`
+ * - adds it when eslint needs TypeScript 6
+ * - removes any other `typescript`, because it would be a second `tsc`
+ *
+ * @param {import('#utils/project.js').Project} project
+ */
+export async function syncTypeScript6(project) {
+  let manifest = await packageJson.read(project.directory);
+
+  if (!usesTypeScript7(project, manifest)) return;
+  if (hasTypeScript6(manifest)) return;
+
+  if (needsTypeScript6(project, manifest)) {
+    await packageJson.addDevDependencies(
+      await getLatest({ typescript: TYPESCRIPT_6 }),
+      project.directory,
+    );
+    return;
+  }
+
+  await packageJson.removeDevDependencies(["typescript"], project.directory);
+}
+
+/**
+ * Copies the base's tsconfig, unless the project already has one.
+ *
+ * @param {import('#utils/project.js').Project} project
+ */
+export async function addTSConfig(project) {
+  if (existsSync(project.path("tsconfig.json"))) {
+    return;
+  }
+
+  if (project.type === "app") {
+    await cp(join(appBase, "tsconfig.json"), project.path("tsconfig.json"));
+    return;
+  }
+
+  if (project.type === "extension") {
+    await cp(join(extensionBase, "tsconfig.json"), project.path("tsconfig.json"));
+    return;
+  }
+
+  if (project.type === "library") {
+    await cp(join(libraryBase, "tsconfig.json"), project.path("tsconfig.json"));
+    return;
+  }
+
+  if (project.type === "custom-element") {
+    await cp(join(customElementBase, "tsconfig.json"), project.path("tsconfig.json"));
+  }
+}
+
+/**
+ * @param {import('#utils/project.js').Project} project
+ */
+export async function updateBabelConfig(project) {
+  if (!project.hasFile("babel.config.js")) {
+    // Nothing to patch (libraries): ember() strips types.
+    return;
+  }
+
+  if (await hasConfiguredTSBabel(project)) {
+    return;
+  }
+
+  await prependPlugin(
+    project,
+    `[
+      "@babel/plugin-transform-typescript",
+      {
+        allExtensions: true,
+        onlyRemoveTypeImports: true,
+        allowDeclareFields: true,
+      },
+    ]`,
+  );
+}

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

@@ -204,6 +204,17 @@ describe("base: minimal-library", () => {
         //# sourceMappingURL=index.d.ts.map"
       `);
 
+      // A consumer's "go to definition" opens these, from the published src/
+      let declarationMap = JSON.parse((await project.read("dist/index.d.ts.map"))!);
+
+      expect(declarationMap.sources).toMatchInlineSnapshot(`
+        [
+          "../src/components/badge.gts",
+          "../src/components/greeting.gts",
+          "../src/utils/math.ts",
+        ]
+      `);
+
       expect(await listFiles(join(project.directory, "dist"))).toMatchInlineSnapshot(`
         [
           "index.d.ts",

package/test/ember.nvp/cli.test.ts

@@ -1,5 +1,10 @@
 import { test, expect as hardExpect } from "vitest";
-import { cli } from "#test-helpers";
+import { cli, mktemp } from "#test-helpers";
+import { packageJson } from "ember-apply";
+import { existsSync } from "node:fs";
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import { stripVTControlCharacters } from "node:util";
 
 const expect = hardExpect.soft;
 
@@ -10,3 +15,139 @@ test.skip("cli works", async () => {
 
   expect(execaPromise.exitCode).toBe(0);
 });
+
+const BASIC_HELP_OUTPUT = `
+    " ember.nvp 
+
+    Usage: npx ember.nvp [options]
+
+    Core Options:
+      -h, --help <boolean>
+          Show CLI help and option details
+
+          --name <string>
+          Name of the project
+
+          --path <string>
+          Target directory path for the project
+
+          --type <string>
+          Type of project to generate [choices: "app", "addon", "library", "extension", "custom-element"]
+
+          --confirm <string>
+          Bypass target confirmation step [choices: "yes", "no"]
+
+          --layers <string>
+          Layers to apply to the project (repeat for multiple layers)
+
+          --packageManager <string>
+          Package manager to configure for the project [choices: "npm", "pnpm"]
+
+          --replaceOrUpdate <string>
+          Strategy to use if target directory exists [choices: "replace", "update"]
+
+          --write <string>
+          Confirm writing changes to disk [choices: "yes", "no"]
+
+    Layer Options:
+          --eslint-bundled.preset <string>
+          Which ESLint config? [choices: "ember", "nvp"] [default: "ember"]
+
+          --typescript.version <string>
+          Which TypeScript version? [choices: "7", "6"] [default: "7"]
+    "
+  `;
+
+test("cli --help outputs usage and core options", async () => {
+  let { execaPromise } = cli(["--help"]);
+
+  const res = await execaPromise;
+
+  expect(res.exitCode).toBe(0);
+  const outStr = stripVTControlCharacters(res.stdout);
+  expect(outStr).toMatchInlineSnapshot(BASIC_HELP_OUTPUT);
+});
+
+test("cli -h alias works", async () => {
+  let { execaPromise } = cli(["-h"]);
+
+  const res = await execaPromise;
+
+  expect(res.exitCode).toBe(0);
+  const outStr = stripVTControlCharacters(res.stdout);
+  expect(outStr).toMatchInlineSnapshot(BASIC_HELP_OUTPUT);
+});
+
+test("cli prints a message, not a stack trace, for an unknown flag", async () => {
+  let { execaPromise } = cli(["--bogus"]);
+
+  const res = await execaPromise.catch((error) => error);
+
+  expect(res.exitCode).toBe(1);
+  const outStr = stripVTControlCharacters(`${res.stdout}\n${res.stderr}`);
+  expect(outStr).toContain("Unknown option '--bogus'");
+  expect(outStr).not.toContain("TypeError");
+});
+
+/**
+ * Every question has a flag, so nothing prompts.
+ * The path does not exist yet, so there is no replace-or-update question either.
+ */
+async function eslintProjectArgs(preset: string) {
+  let parent = await mktemp("cli-layer-options");
+  let path = join(parent, "my-app");
+
+  return {
+    parent,
+    path,
+    args: [
+      "--name",
+      "my-app",
+      "--path",
+      path,
+      "--type",
+      "app",
+      "--layers",
+      "eslint-bundled",
+      "--packageManager",
+      "pnpm",
+      "--confirm",
+      "yes",
+      "--eslint-bundled.preset",
+      preset,
+    ],
+  };
+}
+
+test("cli applies a layer option flag", async () => {
+  let { parent, path, args } = await eslintProjectArgs("nvp");
+
+  try {
+    let res = await cli(args).execaPromise;
+
+    expect(res.exitCode).toBe(0);
+
+    let manifest = await packageJson.read(path);
+
+    expect(manifest.devDependencies).toHaveProperty("@nullvoxpopuli/eslint-configs");
+    expect(manifest.devDependencies).not.toHaveProperty("ember-eslint");
+  } finally {
+    await rm(parent, { recursive: true, force: true });
+  }
+});
+
+test("cli exits on an invalid layer option flag, before writing anything", async () => {
+  let { parent, path, args } = await eslintProjectArgs("bogus");
+
+  try {
+    const res = await cli(args).execaPromise.catch((error) => error);
+
+    expect(res.exitCode).toBe(1);
+    expect(stripVTControlCharacters(res.stdout)).toContain(
+      "Invalid CLI argument '--eslint-bundled.preset': Invalid option 'bogus'. Must be one of: ember, nvp",
+    );
+    expect(existsSync(path)).toBe(false);
+  } finally {
+    await rm(parent, { recursive: true, force: true });
+  }
+});

package/test/ember.nvp/layer-expect-type.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, beforeAll, afterAll, expect } from "vitest";
+import { generate, expectIsSetup, layers } from "#test-helpers";
+import { writeLibrarySource } from "./library-src-fixtures.ts";
+import { execa } from "execa";
+import { existsSync } from "node:fs";
+import { rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import type { Project } from "ember.nvp";
+
+const expectType = layers.find((layer) => layer.name === "expect-type")!;
+
+async function typecheck(project: Project) {
+  return execa("pnpm lint:type-tests", {
+    cwd: project.directory,
+    shell: true,
+    all: true,
+    reject: false,
+  });
+}
+
+describe("layer: expect-type", () => {
+  const dirs: string[] = [];
+
+  afterAll(async () => {
+    if (process.env.CI) return;
+
+    for (const dir of dirs) {
+      await rm(dir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+    }
+  });
+
+  describe("TypeScript library", () => {
+    let project: Project;
+
+    beforeAll(async () => {
+      project = await generate({
+        type: "library",
+        name: "my-lib",
+        layers: ["typescript", "expect-type"],
+      });
+      dirs.push(project.directory);
+
+      await writeLibrarySource(project, "typescript");
+
+      let install = await execa("pnpm install", { cwd: project.directory, shell: true });
+      expect(install.exitCode).toBe(0);
+    });
+
+    it("is setup", async () => {
+      await expectIsSetup(project, expectType);
+    });
+
+    it("the generated type tests pass", async () => {
+      let result = await typecheck(project);
+
+      expect(result.exitCode, result.all).toBe(0);
+    });
+
+    it("checks the library's real exports", async () => {
+      await writeFile(
+        join(project.directory, "type-tests/math.test.ts"),
+        `import { expectTypeOf } from "expect-type";
+import { add } from "../src/index.ts";
+
+expectTypeOf(add).parameters.toEqualTypeOf<[number, number]>();
+expectTypeOf(add).returns.toEqualTypeOf<number>();
+`,
+      );
+
+      let result = await typecheck(project);
+
+      expect(result.exitCode, result.all).toBe(0);
+    });
+
+    it("fails on a wrong type assertion", async () => {
+      await writeFile(
+        join(project.directory, "type-tests/wrong.test.ts"),
+        `import { expectTypeOf } from "expect-type";
+import { add } from "../src/index.ts";
+
+expectTypeOf(add).returns.toEqualTypeOf<string>();
+`,
+      );
+
+      let result = await typecheck(project);
+
+      expect(result.exitCode).not.toBe(0);
+      expect(result.all).toContain("wrong.test.ts");
+    });
+
+    it("keeps type tests out of the build", async () => {
+      await rm(join(project.directory, "type-tests/wrong.test.ts"));
+
+      let build = await execa("pnpm build", { cwd: project.directory, shell: true });
+      expect(build.exitCode).toBe(0);
+
+      expect(existsSync(join(project.directory, "dist/type-tests"))).toBe(false);
+    });
+  });
+
+  describe("JavaScript library", () => {
+    it("adds nothing (no declarations to test)", async () => {
+      let project = await generate({ type: "library", name: "my-lib", layers: ["expect-type"] });
+      dirs.push(project.directory);
+
+      await expectIsSetup(project, expectType);
+
+      expect(existsSync(join(project.directory, "type-tests"))).toBe(false);
+      expect(await project.read("package.json")).not.toContain("expect-type");
+    });
+  });
+});