ember.nvp 1.9.0 → 1.10.0

package/src/layers/typescript/index.js

@@ -1,43 +1,20 @@
-import { js, 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";
+import { packageJson } from "ember-apply";
+import { readManifest } from "#utils/manifest.js";
 import { isLibraryType } from "#utils/project-type.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");
-
-const sharedDeps = {
-  "@glint/ember-tsc": "^1.0.8",
-  "@glint/template": "^1.7.3",
-  "@glint/tsserver-plugin": "^2.0.8",
-  typescript: "^6.0.3",
-};
-
-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",
-};
+import { usesTypeScript7 } from "#utils/typescript.js";
+import * as typescript6 from "./typescript-6.js";
+import * as typescript7 from "./typescript-7.js";
 
 /**
+ * A project that has TypeScript 7 keeps it, even when version 6 is selected.
+ * Nothing moves a project from 7 back to 6 yet.
+ *
  * @param {import('#utils/project.js').Project} project
  */
-function depsFor(project) {
-  return {
-    ...sharedDeps,
-    ...(project.isLibrary ? libraryDeps : appDeps),
-  };
+async function setupFor(project) {
+  let manifest = await packageJson.read(project.directory);
+
+  return usesTypeScript7(project, manifest) ? typescript7 : typescript6;
 }
 
 /**
@@ -56,14 +33,38 @@ export default {
     return isLibraryType(projectType);
   },
 
+  options: {
+    version: {
+      type: "select",
+      prompt: "Which TypeScript version?",
+      default: "7",
+      options: [
+        {
+          value: "7",
+          label: "TypeScript 7.1+",
+          hint: "native tsc, checks .gts and .gjs with ember-content-mapper",
+        },
+        {
+          value: "6",
+          label: "TypeScript 6",
+          hint: "checks with Glint's ember-tsc",
+        },
+      ],
+      async detect(project) {
+        let deps = (await readManifest(project)).devDependencies ?? {};
+
+        if (deps["@typescript/native"]) return "7";
+        if (deps.typescript) return "6";
+
+        return undefined;
+      },
+    },
+  },
+
   async run(project) {
-    /**
-     * TODO:
-     * - if jsconfig exists, switch to tsconfig
-     */
-    await addTSConfig(project);
-    await updatePackageJson(project);
-    await updateBabelConfig(project);
+    let setup = await setupFor(project);
+
+    await setup.run(project);
   },
 
   /**
@@ -79,37 +80,9 @@ export default {
    * @returns {Promise<boolean>}
    */
   async isSetup(project, explain) {
-    const reasons = [];
-
-    if (!project.hasFile("tsconfig.json")) {
-      if (!explain) return false;
-
-      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.
-    if (project.hasFile("babel.config.js") && !(await hasConfiguredTSBabel(project))) {
-      if (!explain) return false;
-
-      reasons.push(`babel.config is missing @babel/plugin-transform-typescript`);
-    }
-
     let manifest = await packageJson.read(project.directory);
-
-    if (!manifest.scripts?.["lint:types"]) {
-      if (!explain) return false;
-
-      reasons.push(`package.json is missing the "lint:types" script`);
-    }
-
-    for (let dep of Object.keys(depsFor(project))) {
-      if (!manifest.devDependencies?.[dep]) {
-        if (!explain) return false;
-
-        reasons.push(`package.json is missing ${dep} in devDependencies`);
-      }
-    }
+    let setup = usesTypeScript7(project, manifest) ? typescript7 : typescript6;
+    let reasons = await setup.reasons(project, manifest);
 
     if (explain) {
       return {
@@ -124,82 +97,9 @@ export default {
   /**
    * @param {import('#utils/project.js').Project} project
    */
-  readme(project) {
-    return `### TypeScript
+  async readme(project) {
+    let setup = await setupFor(project);
 
-This project uses TypeScript and Glint for static type checking.
-
-- \`${project.runPrefix} lint:types\` - Typecheck code with Glint/TypeScript`;
+    return setup.readme(project);
   },
 };
-
-/**
- * @param {import('#utils/project.js').Project} project
- */
-async function updatePackageJson(project) {
-  await packageJson.modify(async (json) => {
-    json.scripts ||= {};
-    json.devDependencies ||= {};
-
-    Object.assign(json.scripts, {
-      "lint:types": "ember-tsc --noEmit",
-    });
-    Object.assign(json.devDependencies, await getLatest(depsFor(project)));
-  }, project.directory);
-}
-
-/**
- * Copies the base's tsconfig, unless the project already has one.
- *
- * @param {import('#utils/project.js').Project} project
- */
-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
- */
-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/src/layers/typescript/typescript-6.js

@@ -0,0 +1,102 @@
+import { packageJson } from "ember-apply";
+import { hasConfiguredTSBabel } from "#utils/babel.js";
+import { getLatest } from "#utils/npm.js";
+import { addTSConfig, updateBabelConfig } from "#utils/typescript.js";
+
+const sharedDeps = {
+  "@glint/ember-tsc": "^1.0.8",
+  "@glint/template": "^1.7.3",
+  "@glint/tsserver-plugin": "^2.0.8",
+  typescript: "^6.0.3",
+};
+
+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",
+};
+
+/**
+ * @param {import('#utils/project.js').Project} project
+ */
+function depsFor(project) {
+  return {
+    ...sharedDeps,
+    ...(project.isLibrary ? libraryDeps : appDeps),
+  };
+}
+
+/**
+ * @param {import('#utils/project.js').Project} project
+ */
+export async function run(project) {
+  /**
+   * TODO:
+   * - if jsconfig exists, switch to tsconfig
+   */
+  await addTSConfig(project);
+  await updatePackageJson(project);
+  await updateBabelConfig(project);
+}
+
+/**
+ * @param {import('#utils/project.js').Project} project
+ * @param {Record<string, any>} manifest
+ * @returns {Promise<string[]>} why TypeScript 6 is not set up
+ */
+export async function reasons(project, manifest) {
+  const reasons = [];
+
+  if (!project.hasFile("tsconfig.json")) {
+    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.
+  if (project.hasFile("babel.config.js") && !(await hasConfiguredTSBabel(project))) {
+    reasons.push(`babel.config is missing @babel/plugin-transform-typescript`);
+  }
+
+  if (!manifest.scripts?.["lint:types"]) {
+    reasons.push(`package.json is missing the "lint:types" script`);
+  }
+
+  for (let dep of Object.keys(depsFor(project))) {
+    if (!manifest.devDependencies?.[dep]) {
+      reasons.push(`package.json is missing ${dep} in devDependencies`);
+    }
+  }
+
+  return reasons;
+}
+
+/**
+ * @param {import('#utils/project.js').Project} project
+ */
+export function readme(project) {
+  return `### TypeScript
+
+This project uses TypeScript and Glint for static type checking.
+
+- \`${project.runPrefix} lint:types\` - Typecheck code with Glint/TypeScript`;
+}
+
+/**
+ * @param {import('#utils/project.js').Project} project
+ */
+async function updatePackageJson(project) {
+  await packageJson.modify(async (json) => {
+    json.scripts ||= {};
+    json.devDependencies ||= {};
+
+    Object.assign(json.scripts, {
+      "lint:types": "ember-tsc --noEmit",
+    });
+    Object.assign(json.devDependencies, await getLatest(depsFor(project)));
+  }, project.directory);
+}

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