ember.nvp 1.14.0 → 1.16.0

package/src/migration-from/findings.js

@@ -0,0 +1,69 @@
+/**
+ * @typedef {import('#types').Finding} Finding
+ */
+
+/**
+ * Past this many, a finding's `where` list ends with "and N more".
+ */
+const LISTED = 8;
+
+/**
+ * Thrown when a project uses features that ember.nvp cannot migrate.
+ *
+ * Nothing is written before this is thrown.
+ */
+export class MigrationError extends Error {
+  /**
+   * @param {string} from the old blueprint
+   * @param {Finding[]} findings
+   */
+  constructor(from, findings) {
+    super(
+      `ember.nvp cannot migrate this project from ${from}.\n` +
+        `Fix these items, then run ember.nvp again:\n\n` +
+        formatFindings(findings),
+    );
+
+    this.name = "MigrationError";
+    this.from = from;
+    this.findings = findings;
+  }
+}
+
+/**
+ * A numbered list:
+ *
+ *   1. Templates in .hbs files
+ *      - src/components/foo.hbs
+ *      Move each template into its component as <template>.
+ *
+ * @param {Finding[]} findings
+ * @returns {string}
+ */
+export function formatFindings(findings) {
+  /** @type {string[]} */
+  let lines = [];
+
+  for (let i = 0; i < findings.length; i++) {
+    let finding = /** @type {Finding} */ (findings[i]);
+    let where = finding.where ?? [];
+
+    lines.push(`${i + 1}. ${finding.title}`);
+
+    for (let j = 0; j < where.length && j < LISTED; j++) {
+      lines.push(`   - ${where[j]}`);
+    }
+
+    if (where.length > LISTED) {
+      lines.push(`   - and ${where.length - LISTED} more`);
+    }
+
+    for (let line of finding.action.split("\n")) {
+      lines.push(`   ${line}`);
+    }
+
+    lines.push("");
+  }
+
+  return lines.join("\n").trimEnd();
+}

package/src/migration-from/index.js

@@ -0,0 +1,81 @@
+import addonBlueprint from "./at-ember/addon-blueprint/index.js";
+import appBlueprint from "./at-ember/app-blueprint/index.js";
+import classicAddon from "./at-ember-tooling/classic-build-addon-blueprint/index.js";
+import classicApp from "./at-ember-tooling/classic-build-app-blueprint/index.js";
+import { MigrationError } from "./findings.js";
+
+export { MigrationError, formatFindings } from "./findings.js";
+
+/**
+ * The older blueprints that ember.nvp migrates from.
+ *
+ * Detection asks them in this order.
+ * The markers of each one are its own, so the order only decides ties:
+ * - a v2 addon builds with rollup and @embroider/addon-dev
+ * - a classic addon has an index.js for ember-cli, and a dummy app in tests/
+ * - a Vite app still has an ember-cli-build for @embroider/compat
+ * - a classic app has an ember-cli-build without Vite
+ *
+ * @type {import('#types').Migration[]}
+ */
+export const migrations = [addonBlueprint, classicAddon, appBlueprint, classicApp];
+
+/**
+ * @param {string} directory an existing project
+ * @returns {import('#types').Migration | undefined}
+ */
+export function detectMigration(directory) {
+  return migrations.find((migration) => migration.detect(directory));
+}
+
+/**
+ * Checks the project, and changes nothing.
+ *
+ * @param {import('#utils/project.js').Project} project
+ * @returns {Promise<{ migration: import('#types').Migration, report: import('#types').MigrationReport } | undefined>}
+ *   undefined when the project is not from an older blueprint
+ */
+export async function checkMigration(project) {
+  let migration = detectMigration(project.directory);
+
+  if (!migration) return;
+
+  let report = await migration.check(project);
+
+  if (migration.type !== project.type) {
+    report.unsupported.unshift({
+      title: `A ${migration.type} from ${migration.label}`,
+      where: [`selected type: ${project.type}`],
+      action: `Select "${migration.type}" as the project type.`,
+    });
+  }
+
+  return { migration, report };
+}
+
+/**
+ * Moves a project from an older blueprint to the ember.nvp base,
+ * so that the base and the layers can run over it.
+ *
+ * Throws a MigrationError, before any change,
+ * when the project uses features that ember.nvp does not support.
+ *
+ * @param {import('#utils/project.js').Project} project
+ * @returns {Promise<{ migration: import('#types').Migration, report: import('#types').MigrationReport } | undefined>}
+ *   undefined when the project is not from an older blueprint
+ */
+export async function migrate(project) {
+  let result = await checkMigration(project);
+
+  if (!result) return;
+
+  let { migration, report } = result;
+
+  if (report.unsupported.length > 0) {
+    throw new MigrationError(migration.label, report.unsupported);
+  }
+
+  await migration.run(project, report);
+
+  return result;
+}

package/src/migration-from/javascript.js

@@ -0,0 +1,217 @@
+import { parse } from "ember-estree";
+
+/**
+ * An ESTree node.
+ *
+ * ember-estree types every property as `unknown`,
+ * and these helpers read many shapes of config files.
+ *
+ * @typedef {{ type: string, start?: number, end?: number, [key: string]: any }} Node
+ */
+
+/**
+ * @param {string} source
+ * @param {string} filePath decides the parser: `.ts` parses TypeScript
+ * @returns {Node | undefined} the Program, or undefined when the file does not parse
+ */
+export function parseProgram(source, filePath) {
+  try {
+    let file = /** @type {Node} */ (parse(source, { filePath }));
+
+    return /** @type {Node} */ (file.program ?? file);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Calls `visit` for every node below `node`, parents first.
+ *
+ * @param {unknown} node
+ * @param {(node: Node, parent: Node | undefined) => void} visit
+ * @param {Node} [parent]
+ */
+export function walk(node, visit, parent) {
+  if (!node || typeof node !== "object") return;
+
+  if (Array.isArray(node)) {
+    for (let child of node) walk(child, visit, parent);
+    return;
+  }
+
+  let astNode = /** @type {Node} */ (node);
+
+  if (typeof astNode.type !== "string") return;
+
+  visit(astNode, parent);
+
+  for (let [key, value] of Object.entries(astNode)) {
+    if (key === "loc" || key === "range" || key === "parent") continue;
+
+    walk(value, visit, astNode);
+  }
+}
+
+/**
+ * @param {unknown} node
+ * @returns {string | undefined} the value of a string literal, or of a template literal without expressions
+ */
+export function stringValue(node) {
+  let astNode = /** @type {Node | undefined} */ (node);
+
+  if (!astNode) return;
+
+  if (astNode.type === "Literal" && typeof astNode.value === "string") {
+    return astNode.value;
+  }
+
+  if (astNode.type === "StringLiteral") {
+    return /** @type {string} */ (astNode.value);
+  }
+
+  if (astNode.type === "TemplateLiteral" && astNode.expressions?.length === 0) {
+    return astNode.quasis?.[0]?.value?.cooked;
+  }
+}
+
+/**
+ * @param {unknown} node
+ * @returns {string[] | undefined} the values of an array of string literals
+ */
+export function stringArray(node) {
+  let astNode = /** @type {Node | undefined} */ (node);
+
+  if (astNode?.type !== "ArrayExpression") return;
+
+  /** @type {string[]} */
+  let result = [];
+
+  for (let element of astNode.elements ?? []) {
+    let value = stringValue(element);
+
+    if (value === undefined) return;
+
+    result.push(value);
+  }
+
+  return result;
+}
+
+/**
+ * @param {Node | undefined} node an ObjectExpression
+ * @param {string} name
+ * @returns {Node | undefined} the value of the property named `name`
+ */
+export function propertyValue(node, name) {
+  if (node?.type !== "ObjectExpression") return;
+
+  for (let property of node.properties ?? []) {
+    if (property.type !== "Property" && property.type !== "ObjectProperty") continue;
+
+    let key = property.key;
+    let keyName = key?.type === "Identifier" ? key.name : stringValue(key);
+
+    if (keyName === name) return property.value;
+  }
+}
+
+/**
+ * @param {Node | undefined} node an ObjectExpression
+ * @returns {string[]} the names of its properties, with `...` for spreads and computed keys
+ */
+export function propertyNames(node) {
+  if (node?.type !== "ObjectExpression") return [];
+
+  /** @type {string[]} */
+  let names = [];
+
+  for (let property of node.properties ?? []) {
+    let key = property.key;
+    let keyName = key?.type === "Identifier" && !property.computed ? key.name : stringValue(key);
+
+    names.push(keyName ?? "...");
+  }
+
+  return names;
+}
+
+/**
+ * Maps each imported (or required) local name to the module it comes from.
+ *
+ *   import { babel } from '@rollup/plugin-babel';   babel → @rollup/plugin-babel
+ *   const EmberApp = require('ember-cli/lib/broccoli/ember-app');
+ *
+ * @param {Node} program
+ * @returns {Map<string, string>}
+ */
+export function importedNames(program) {
+  /** @type {Map<string, string>} */
+  let names = new Map();
+
+  walk(program, (node) => {
+    if (node.type === "ImportDeclaration") {
+      let source = stringValue(node.source);
+
+      if (!source) return;
+
+      for (let specifier of node.specifiers ?? []) {
+        names.set(specifier.local.name, source);
+      }
+
+      return;
+    }
+
+    if (node.type === "VariableDeclarator" && node.init) {
+      let source = requiredModule(node.init);
+
+      if (!source) return;
+
+      if (node.id?.type === "Identifier") {
+        names.set(node.id.name, source);
+      }
+
+      if (node.id?.type === "ObjectPattern") {
+        for (let property of node.id.properties ?? []) {
+          if (property.value?.type === "Identifier") {
+            names.set(property.value.name, source);
+          }
+        }
+      }
+    }
+  });
+
+  return names;
+}
+
+/**
+ * @param {Node} node
+ * @returns {string | undefined} `x` for `require('x')`, `require('x').y`, and `await import('x')`
+ */
+function requiredModule(node) {
+  let current = node;
+
+  while (current?.type === "MemberExpression" || current?.type === "AwaitExpression") {
+    current = current.type === "AwaitExpression" ? current.argument : current.object;
+  }
+
+  if (current?.type === "ImportExpression") {
+    return stringValue(current.source);
+  }
+
+  if (
+    current?.type === "CallExpression" &&
+    current.callee?.type === "Identifier" &&
+    current.callee.name === "require"
+  ) {
+    return stringValue(current.arguments?.[0]);
+  }
+}
+
+/**
+ * @param {string} source
+ * @param {Node} node
+ * @returns {string} the node's source text
+ */
+export function sourceOf(source, node) {
+  return source.slice(/** @type {number} */ (node.start), /** @type {number} */ (node.end));
+}

package/src/migration-from/layers.js

@@ -0,0 +1,170 @@
+import { packageJson } from "ember-apply";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { remove } from "./files.js";
+
+/**
+ * Tooling that the old blueprints generate, by the layer that replaces it.
+ *
+ * When the user selects the layer, the migration removes the old tooling,
+ * so that the layer can write its own.
+ * Otherwise the old tooling stays as it is.
+ *
+ * @type {Record<string, { files: string[], scripts: string[], devDependencies: string[] }>}
+ */
+const REPLACED = {
+  "eslint-bundled": {
+    files: [
+      "eslint.config.mjs",
+      "eslint.config.cjs",
+      "eslint.config.js",
+      ".eslintrc.js",
+      ".eslintrc.cjs",
+      ".eslintrc.json",
+      ".eslintrc",
+      ".eslintignore",
+    ],
+    scripts: ["lint:js", "lint:js:fix"],
+    devDependencies: [
+      "@babel/eslint-parser",
+      "@eslint/js",
+      "@typescript-eslint/eslint-plugin",
+      "@typescript-eslint/parser",
+      "eslint-config-prettier",
+      "eslint-plugin-decorator-position",
+      "eslint-plugin-ember",
+      "eslint-plugin-import",
+      "eslint-plugin-n",
+      "eslint-plugin-node",
+      "eslint-plugin-prettier",
+      "eslint-plugin-qunit",
+      "eslint-plugin-warp-drive",
+      "globals",
+      "typescript-eslint",
+    ],
+  },
+  prettier: {
+    files: [
+      ".prettierrc.mjs",
+      ".prettierrc.cjs",
+      ".prettierrc.js",
+      ".prettierrc.json",
+      ".prettierrc",
+    ],
+    scripts: ["lint:format"],
+    devDependencies: [],
+  },
+  "github-actions": {
+    files: [".github/workflows/ci.yml"],
+    scripts: [],
+    devDependencies: [],
+  },
+  // Glint's own CLI and environments, which the typescript layer's setup does not use
+  typescript: {
+    files: [],
+    scripts: [],
+    devDependencies: [
+      "@glint/core",
+      "@glint/environment-ember-loose",
+      "@glint/environment-ember-template-imports",
+    ],
+  },
+};
+
+/**
+ * @param {import('#utils/project.js').Project} project
+ * @param {import('#types').MigrationReport} report
+ */
+export async function removeToolingOfWantedLayers(project, report) {
+  for (let [layer, replaced] of Object.entries(REPLACED)) {
+    if (!project.wantsLayer(layer)) continue;
+
+    await remove(project, replaced.files);
+    await packageJson.removeDevDependencies(replaced.devDependencies, project.directory);
+    await packageJson.modify((json) => {
+      for (let script of replaced.scripts) {
+        delete json.scripts?.[script];
+      }
+    }, project.directory);
+  }
+
+  if (!project.wantsLayer("typescript")) return;
+
+  let manifest = await packageJson.read(project.directory);
+  /** @type {string[]} */
+  let glint = [];
+
+  for (let [name, command] of Object.entries(manifest.scripts ?? {})) {
+    // the typescript layer writes its own lint:types
+    if (name !== "lint:types" && /(^|\s|&&)glint\b/.test(String(command)))
+      glint.push(`${name}: ${command}`);
+  }
+
+  if (glint.length > 0) {
+    report.todo.push({
+      title: "Scripts that run the glint CLI",
+      where: glint,
+      action:
+        "Run the checker of the typescript layer instead, the way lint:types does.\n" +
+        "The migration removed @glint/core, which has the glint CLI.",
+    });
+  }
+}
+
+/**
+ * The testem config that the qunit layer writes, by project kind
+ */
+const QUNIT_TESTEM = {
+  app: join(import.meta.dirname, "../layers/qunit/files/testem.cjs"),
+  library: join(import.meta.dirname, "../layers/qunit/library-files/config/test/testem.cjs"),
+};
+
+/**
+ * Browser flags are what projects change in a testem config,
+ * for example to let Chrome render WebGL.
+ *
+ * @param {string} root
+ * @param {string} file the old testem config, which the qunit layer's config replaces
+ * @param {"app" | "library"} kind
+ * @returns {import('#types').Finding | undefined} undefined when both configs pass the same flags
+ */
+export function changedTestemFlags(root, file, kind) {
+  if (!existsSync(join(root, file))) return;
+
+  let old = browserFlags(readFileSync(join(root, file), "utf-8"));
+  let current = browserFlags(readFileSync(QUNIT_TESTEM[kind], "utf-8"));
+  let target = kind === "library" ? "config/test/testem.cjs" : "testem.cjs";
+
+  /** @type {string[]} */
+  let where = [];
+
+  for (let flag of old) {
+    if (!current.has(flag)) where.push(`${flag}: only in ${file}`);
+  }
+
+  for (let flag of current) {
+    if (!old.has(flag)) where.push(`${flag}: only in ${target}`);
+  }
+
+  if (where.length === 0) return;
+
+  return {
+    title: "Browser flags that differ in the new testem config",
+    where,
+    action: `Change the flags in ${target} to the ones that your tests need.`,
+  };
+}
+
+/**
+ * @param {string} source
+ * @returns {Set<string>} such as `--headless`, with `--headless=new` read as `--headless`
+ */
+function browserFlags(source) {
+  let flags = new Set();
+
+  for (let [, flag] of source.matchAll(/["'`](--[\w-]+(?:=[^"'`]*)?)["'`]/g)) {
+    flags.add(flag === "--headless=new" ? "--headless" : flag);
+  }
+
+  return flags;
+}