ember.nvp 1.9.0 → 1.11.0

package/src/layers/typescript/typescript-7.js

@@ -0,0 +1,177 @@
+import { packageJson, tsconfig } from "ember-apply";
+import { hasConfiguredTSBabel } from "#utils/babel.js";
+import { getLatest } from "#utils/npm.js";
+import {
+  TYPESCRIPT_7,
+  addTSConfig,
+  hasTypeScript6,
+  syncTypeScript6,
+  updateBabelConfig,
+} from "#utils/typescript.js";
+
+const MAPPER = "ember-content-mapper";
+
+/**
+ * TypeScript 7 does not load tsserver plugins.
+ * The content mapper replaces this one.
+ */
+const TSSERVER_PLUGIN = "@glint/tsserver-plugin";
+
+/**
+ * `@typescript/native` owns the `tsc` bin.
+ * `typescript` is left to eslint, which needs TypeScript 6, see `syncTypeScript6`.
+ *
+ * The mapper transforms with `@glint/ember-tsc` and references its types.
+ * `@glint/template` types the signatures written by hand.
+ */
+const sharedDeps = {
+  "@glint/ember-tsc": "^1.11.0",
+  "@glint/template": "^1.7.3",
+  "@typescript/native": TYPESCRIPT_7,
+  [MAPPER]: "^0.3.1",
+};
+
+const appDeps = {
+  // 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",
+};
+
+const libraryDeps = {
+  "@ember/library-tsconfig": "^2.0.0",
+};
+
+const scripts = {
+  "lint:types": "tsc --noEmit --runExternalCode",
+};
+
+/**
+ * @param {import('#utils/project.js').Project} project
+ */
+function depsFor(project) {
+  return {
+    ...sharedDeps,
+    ...(project.isLibrary ? libraryDeps : appDeps),
+  };
+}
+
+/**
+ * @param {Record<string, any>} config
+ * @returns {boolean}
+ */
+function hasContentMapper(config) {
+  return (
+    Array.isArray(config.contentMappers) &&
+    config.contentMappers.some((/** @type {any} */ mapper) => mapper?.package === MAPPER)
+  );
+}
+
+/**
+ * @param {import('#utils/project.js').Project} project
+ */
+export async function run(project) {
+  await addTSConfig(project);
+  await updateTSConfig(project);
+  await updatePackageJson(project);
+  await syncTypeScript6(project);
+  await updateBabelConfig(project);
+}
+
+/**
+ * @param {import('#utils/project.js').Project} project
+ * @param {Record<string, any>} manifest
+ * @returns {Promise<string[]>} why TypeScript 7 is not set up
+ */
+export async function reasons(project, manifest) {
+  const reasons = [];
+
+  if (!project.hasFile("tsconfig.json")) {
+    reasons.push("tsconfig.json is missing");
+  } else if (!hasContentMapper(await tsconfig.read(project.directory))) {
+    reasons.push(`tsconfig.json is missing the ${MAPPER} entry in contentMappers`);
+  }
+
+  // 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))) {
+    reasons.push(`babel.config is missing @babel/plugin-transform-typescript`);
+  }
+
+  if (!manifest.scripts?.["lint:types"]?.includes("--runExternalCode")) {
+    reasons.push(`package.json's "lint:types" script is missing --runExternalCode`);
+  }
+
+  for (let dep of Object.keys(depsFor(project))) {
+    if (!manifest.devDependencies?.[dep]) {
+      reasons.push(`package.json is missing ${dep} in devDependencies`);
+    }
+  }
+
+  if (manifest.devDependencies?.typescript && !hasTypeScript6(manifest)) {
+    reasons.push(`package.json's typescript must be @typescript/typescript6, or tsc is ambiguous`);
+  }
+
+  return reasons;
+}
+
+/**
+ * @param {import('#utils/project.js').Project} project
+ */
+export function readme(project) {
+  return `### TypeScript
+
+This project uses TypeScript 7 and [ember-content-mapper](https://github.com/NullVoxPopuli/ember-content-mapper) for static type checking.
+
+- \`${project.runPrefix} lint:types\` - Typecheck code with TypeScript
+- Imports of \`.gts\` and \`.gjs\` modules must include the extension
+- Editor setup: see [ember-content-mapper's editors section](https://github.com/NullVoxPopuli/ember-content-mapper#editors)`;
+}
+
+/**
+ * @param {import('#utils/project.js').Project} project
+ */
+async function updateTSConfig(project) {
+  let config = await tsconfig.read(project.directory);
+
+  if (hasContentMapper(config) && !hasTSServerPlugin(config)) return;
+
+  await tsconfig.modify((json) => {
+    if (!hasContentMapper(json)) {
+      json.contentMappers ||= [];
+      json.contentMappers.push({ package: MAPPER, extensions: [".gts", ".gjs"] });
+    }
+
+    if (hasTSServerPlugin(json)) {
+      json.compilerOptions.plugins = json.compilerOptions.plugins.filter(
+        (/** @type {any} */ plugin) => plugin?.name !== TSSERVER_PLUGIN,
+      );
+
+      if (json.compilerOptions.plugins.length === 0) {
+        delete json.compilerOptions.plugins;
+      }
+    }
+  }, project.directory);
+}
+
+/**
+ * @param {Record<string, any>} config
+ * @returns {boolean}
+ */
+function hasTSServerPlugin(config) {
+  let plugins = config.compilerOptions?.plugins;
+
+  return (
+    Array.isArray(plugins) &&
+    plugins.some((/** @type {any} */ plugin) => plugin?.name === TSSERVER_PLUGIN)
+  );
+}
+
+/**
+ * @param {import('#utils/project.js').Project} project
+ */
+async function updatePackageJson(project) {
+  await packageJson.addScripts(scripts, project.directory);
+  await packageJson.addDevDependencies(await getLatest(depsFor(project)), project.directory);
+  await packageJson.removeDevDependencies([TSSERVER_PLUGIN], project.directory);
+}

package/src/utils/manifest.js

@@ -1,3 +1,4 @@
+import { packageJson } from "ember-apply";
 import { hasAllKeys } from "./object.js";
 
 /**
@@ -7,3 +8,15 @@ import { hasAllKeys } from "./object.js";
 export function hasDevDeps(manifest, listOrObject) {
   return hasAllKeys(manifest.devDependencies ?? {}, listOrObject);
 }
+
+/**
+ * Like `packageJson.read`, but an empty object when there is no package.json yet
+ *
+ * @param {import('./project.js').Project} project
+ * @returns {Promise<Record<string, any>>}
+ */
+export async function readManifest(project) {
+  if (!project.hasFile("package.json")) return {};
+
+  return packageJson.read(project.directory);
+}

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,9 @@
 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;
@@ -33,8 +37,8 @@ const BASIC_HELP_OUTPUT = `
           --confirm <string>
           Bypass target confirmation step [choices: "yes", "no"]
 
-          --layers <string>
-          Layers to apply to the project (repeat for multiple layers)
+          --layers <string> [--layers <string> ...]
+          Layers to apply to the project [choices: "are-the-types-wrong", "eslint-bundled", "expect-type", "git", "github-actions", "inspector-support", "prettier", "publint", "qunit", "readme", "renovate", "typescript", "vitest"]
 
           --packageManager <string>
           Package manager to configure for the project [choices: "npm", "pnpm"]
@@ -44,6 +48,15 @@ const BASIC_HELP_OUTPUT = `
 
           --write <string>
           Confirm writing changes to disk [choices: "yes", "no"]
+
+    Layer Options:
+      Layer: eslint-bundled
+          --eslint-bundled.preset <string>
+          Which ESLint config? [choices: "ember", "nvp"] [default: "ember"]
+
+      Layer: typescript
+          --typescript.version <string>
+          Which TypeScript version? [choices: "7", "6"] [default: "7"]
     "
   `;
 
@@ -66,3 +79,77 @@ test("cli -h alias works", async () => {
   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 });
+  }
+});