ember.nvp 0.5.0 → 0.7.0

package/src/bases/minimal-library/index.js

@@ -1,10 +1,166 @@
+import { packageJson } from "ember-apply";
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { getLatest } from "#utils/npm.js";
+import { applyFolderTo } from "#utils/fs.js";
+import { removeConfiguredPlugin } from "#utils/babel.js";
+
+/**
+ * Minimal Library Base
+ *
+ * Provides the absolute bare minimum for an Ember v2 library (addon):
+ * - type: "module" in package.json
+ * - built with tsdown + @nullvoxpopuli/ember-rolldown
+ * - a sample `<template>` component and a plain module
+ * - No babel.config.js: ember() covers TS stripping, template compilation,
+ *   and decorators
+ * - No testing framework
+ * - No linting or formatting
+ *
+ * Testing, linting, formatting, etc. are opt-in via layers.
+ */
 export default {
   label: "Minimal Library Base",
-  description: "Bare minimum library structure",
+  description: "Bare minimum Ember v2 library (addon) structure",
 
   /**
+   * 1. Apply files
+   *   a. Remove TS if needed
+   * 2. Update name(s)
+   * 3. Make publishable
+   * 4. Remove TS deps/files/config if needed
+   * 5. Upgrade in-range dependencies
+   * 6. Update an existing babel config, if any
    *
    * @param {import('#utils/project.js').Project} project
    */
-  async run(project) {},
+  async run(project) {
+    await applyFiles(project);
+    await updateName(project);
+    await makePublishable(project);
+    await makeJavaScript(project);
+    await upgradeDependencies(project);
+    await updateBabelConfig(project);
+  },
 };
+
+/**
+ * @param {import('#utils/project.js').Project} project
+ */
+async function applyFiles(project) {
+  let filePath = join(import.meta.dirname, "files");
+
+  await applyFolderTo(filePath, project);
+}
+
+/**
+ * Operates on known files where the name matters
+ *
+ * @param {import('#utils/project.js').Project} project
+ */
+async function updateName(project) {
+  await packageJson.modify((json) => {
+    json.name = project.desires.name;
+  }, project.directory);
+}
+
+/**
+ * The template's package.json is `private: true` so it can never be
+ * published from this repo; the generated library exists to be published,
+ * so the flag is removed entirely.
+ *
+ * @param {import('#utils/project.js').Project} project
+ */
+async function makePublishable(project) {
+  await packageJson.modify((json) => {
+    delete json.private;
+  }, project.directory);
+}
+
+/**
+ * When the project is JavaScript (no typescript layer), remove the TS
+ * toolchain, drop the tsconfig, and point the build at the emitted `.js`
+ * entry (declarations can't be produced without types).
+ *
+ * @param {import('#utils/project.js').Project} project
+ */
+async function makeJavaScript(project) {
+  if (await project.hasOrWantsLayer("typescript")) return;
+
+  await packageJson.removeDevDependencies(
+    ["@babel/plugin-transform-typescript", "@ember/library-tsconfig", "typescript"],
+    project.directory,
+  );
+
+  await project.removeFile("tsconfig.json");
+
+  await removeTypesExports(project);
+  await pointBuildAtJavaScript(project);
+}
+
+/**
+ * No declarations are emitted for a JavaScript library, so the `types`
+ * export conditions would point at files that never exist.
+ *
+ * @param {import('#utils/project.js').Project} project
+ */
+async function removeTypesExports(project) {
+  await packageJson.modify((json) => {
+    for (let condition of Object.values(json.exports ?? {})) {
+      if (condition && typeof condition === "object") {
+        delete condition.types;
+      }
+    }
+  }, project.directory);
+}
+
+/**
+ * Rewrites the tsdown config so it builds the JavaScript entry and stops
+ * emitting declarations (defineConfig defaults to `dts: true`).
+ *
+ * @param {import('#utils/project.js').Project} project
+ */
+async function pointBuildAtJavaScript(project) {
+  let configPath = project.path("tsdown.config.js");
+  let contents = await readFile(configPath, "utf-8");
+
+  contents = contents.replace(
+    `entry: ["./src/index.ts"],`,
+    `entry: ["./src/index.js"],\n  dts: false,`,
+  );
+
+  await writeFile(configPath, contents);
+}
+
+/**
+ * Bumps in-range only.
+ * Majors will need to go through PR to this repo.
+ *
+ * @param {import('#utils/project.js').Project} project
+ */
+async function upgradeDependencies(project) {
+  let existing = await packageJson.read(project.directory);
+
+  await packageJson.modify(async (json) => {
+    if (json.dependencies) {
+      Object.assign(json.dependencies, await getLatest(existing.dependencies));
+    }
+    if (json.devDependencies) {
+      Object.assign(json.devDependencies, await getLatest(existing.devDependencies));
+    }
+  }, project.directory);
+}
+
+/**
+ * The base doesn't emit a babel.config.js, but this can run over an
+ * existing project that has one -- and a JavaScript project's config
+ * must not reference the TS plugin.
+ *
+ * @param {import('#utils/project.js').Project} project
+ */
+async function updateBabelConfig(project) {
+  if (await project.hasOrWantsLayer("typescript")) return;
+  if (!project.hasFile("babel.config.js")) return;
+
+  await removeConfiguredPlugin(project, "@babel/plugin-transform-typescript");
+}

package/src/cli/args.js

@@ -35,10 +35,15 @@ const { values } = parseArgs({
       type: "string",
       choices: ["replace", "update"],
     },
+
+    write: {
+      type: "string",
+      choices: ["yes", "no"],
+    },
   },
 });
 
-const { replaceOrUpdate, name, type, layers = [], packageManager, path, confirm } = values;
+const { replaceOrUpdate, name, type, layers = [], packageManager, path, confirm, write } = values;
 
 export const answers = {
   name,
@@ -48,6 +53,7 @@ export const answers = {
   path,
   confirm,
   replaceOrUpdate,
+  write,
 };
 
 /**

package/src/cli/index.js

@@ -8,8 +8,12 @@ import { askProjectType } from "./questions/project-type.js";
 import { askPackageManager } from "./questions/package-manager.js";
 import { askPath } from "./questions/path.js";
 import { askIfOK } from "./questions/ok.js";
+import { askToWrite } from "./questions/write.js";
 import { styleText } from "node:util";
+import { readFile, rm } from "node:fs/promises";
+import { join } from "node:path";
 import { Project } from "#utils/project.js";
+import { Stage } from "#utils/stage.js";
 import { askReplaceOrUpdate } from "./questions/replace-or-update.js";
 
 /**
@@ -28,10 +32,29 @@ async function main() {
   const projectPath = await askPath(projectName);
   const replaceOrUpdate = await askReplaceOrUpdate(projectPath);
   const projectType = await askProjectType();
-  const selectedLayers = await askLayers();
+  const selectedLayers = await askLayers(projectType);
   const packageManager = await askPackageManager();
 
-  let project = new Project(projectPath, {
+  await askIfOK();
+
+  /**
+   * Everything is generated in a stage: a real directory (in the OS temp
+   * dir) acting as a writable overlay of the target directory.
+   *
+   * When updating an existing project, the stage is seeded with a full
+   * copy of it (sans node_modules/.git), so the bases and layers run
+   * against the project's current state -- isSetup checks, package.json
+   * reads, file existence checks, etc. all see the existing files, and
+   * the codemods modify them in the stage exactly as if they were
+   * operating in place. "replace" starts from an empty stage instead.
+   *
+   * The target itself is not touched until stage.commit() below, which
+   * applies the difference between the stage and the target (or the
+   * subset of it the user accepts during review).
+   */
+  const stage = await Stage.create(projectPath, { seed: replaceOrUpdate !== "replace" });
+
+  let project = new Project(stage.directory, {
     name: projectName,
     type: projectType,
     path: projectPath,
@@ -39,28 +62,19 @@ async function main() {
     packageManager,
   });
 
-  await askIfOK();
-
   const s = p.spinner();
   s.start("Creating your Ember app...");
 
   try {
-    // Generate the project
-    await generateProject(project, replaceOrUpdate);
-
-    s.stop("Project created!");
-
-    p.note(
-      `cd ${projectName}\n` +
-        `${packageManager} install\n` +
-        `${packageManager} ${packageManager === "npm" ? "run " : ""}start`,
-      "Next steps",
-    );
+    // Generate the project (into the stage)
+    await generateProject(project);
 
-    p.outro(styleText("green", "✓") + " Project ready! " + styleText("dim", "Happy coding!"));
+    s.stop("Project generated");
   } catch (err) {
     s.stop("Failed to create project");
 
+    await stage.discard();
+
     if (err instanceof Error) {
       p.cancel(`Error: ${err.message}`);
       if (err.stack) {
@@ -73,6 +87,66 @@ async function main() {
     p.cancel(`Error: ${String(err)}`);
     process.exit(1);
   }
+
+  const changes = await stage.changes();
+
+  if (changes.length === 0 && replaceOrUpdate !== "replace") {
+    await stage.discard();
+
+    p.outro(styleText("green", "✓") + " Already up to date -- nothing to write.");
+    return;
+  }
+
+  /**
+   * New projects (and "replace", which was already confirmed) are written
+   * without asking. Updates to an existing project must be confirmed:
+   * write all / review each change (accept/reject) / cancel.
+   */
+  const isUpdate = !stage.isNew && replaceOrUpdate !== "replace";
+
+  const toApply = isUpdate ? await askToWrite(stage, changes) : changes;
+
+  if (!toApply || toApply.length === 0) {
+    await stage.discard();
+
+    p.cancel("Cancelled -- no files were written");
+    return process.exit(0);
+  }
+
+  if (replaceOrUpdate === "replace") {
+    await rm(projectPath, { recursive: true, force: true });
+  }
+
+  await stage.commit(toApply);
+
+  p.log.success(`Applied ${toApply.length} change${toApply.length === 1 ? "" : "s"}`);
+
+  /**
+   * Converted / generated files are written expecting the project's own
+   * formatting and lint pass to run right away (e.g. blank lines between
+   * import groups are `eslint --fix`'s job) -- so when the project has a
+   * lint:fix script, surface it as the step right after install.
+   */
+  let lintFixStep = "";
+  try {
+    const manifest = JSON.parse(await readFile(join(projectPath, "package.json"), "utf-8"));
+
+    if (manifest.scripts?.["lint:fix"]) {
+      lintFixStep = `${packageManager} ${packageManager === "npm" ? "run " : ""}lint:fix\n`;
+    }
+  } catch {
+    // no readable package.json -- skip the suggestion
+  }
+
+  p.note(
+    `cd ${projectName}\n` +
+      `${packageManager} install\n` +
+      lintFixStep +
+      `${packageManager} ${packageManager === "npm" ? "run " : ""}start`,
+    "Next steps",
+  );
+
+  p.outro(styleText("green", "✓") + " Project ready! " + styleText("dim", "Happy coding!"));
 }
 
 main().catch((err) => {

package/src/cli/questions/layers.js

@@ -3,7 +3,10 @@ import { discoverLayers } from "#layers";
 
 import * as p from "@clack/prompts";
 
-export async function askLayers() {
+/**
+ * @param {import('#types').ProjectType} projectType
+ */
+export async function askLayers(projectType) {
   const optionalLayers = (await discoverLayers()).filter(
     (layer) => typeof layer.run === "function",
   );
@@ -34,7 +37,7 @@ export async function askLayers() {
   const defaultValues = (
     await Promise.all(
       optionalLayers.map(async (layer) => {
-        let result = await layer.defaultValue?.();
+        let result = await layer.defaultValue?.(projectType);
 
         return result && layer.name;
       }),

package/src/cli/questions/project-type.js

@@ -41,11 +41,6 @@ export async function askProjectType() {
     ],
   });
 
-  if (answer === "library") {
-    p.cancel("Not implemented yet, apologies!");
-    return process.exit(0);
-  }
-
   if (p.isCancel(answer)) {
     p.cancel("Operation cancelled");
     return process.exit(0);

package/src/cli/questions/write.js

@@ -0,0 +1,169 @@
+import * as p from "@clack/prompts";
+import { styleText } from "node:util";
+
+import { answers, printArgInUse } from "#args";
+
+const SUPPORTED = new Set(["yes", "no"]);
+
+/**
+ *
+ * @param {string | undefined} selected
+ * @returns {selected is 'yes' | 'no'}
+ */
+function isValid(selected) {
+  if (!selected) return false;
+
+  return SUPPORTED.has(selected);
+}
+
+/**
+ * Nothing has been written to the target directory yet -- everything so
+ * far only exists in the stage. Ask whether to write the staged changes,
+ * with the option to review the diff change-by-change, accepting or
+ * rejecting each one.
+ *
+ * @param {import('#utils/stage.js').Stage} stage
+ * @param {import('#utils/stage.js').Change[]} changes
+ * @returns {Promise<import('#utils/stage.js').Change[] | null>}
+ *   the changes to write, or null to cancel without writing anything
+ */
+export async function askToWrite(stage, changes) {
+  if (isValid(answers.write)) {
+    printArgInUse("write", answers.write);
+
+    return answers.write === "yes" ? changes : null;
+  }
+
+  p.note(summarize(changes), `${changes.length} staged change${changes.length === 1 ? "" : "s"}`);
+
+  const answer = await p.select({
+    message: `Write these changes to ${stage.targetDirectory}?`,
+    options: [
+      { value: "yes", label: "write the files", hint: "apply all staged changes" },
+      {
+        value: "review",
+        label: "review the diff",
+        hint: "step through each change, accepting or rejecting it",
+      },
+      { value: "no", label: "cancel", hint: "discard the staged changes, touching nothing" },
+    ],
+  });
+
+  if (p.isCancel(answer) || answer === "no") {
+    return null;
+  }
+
+  if (answer === "yes") {
+    return changes;
+  }
+
+  return reviewEachChange(stage, changes);
+}
+
+/**
+ * Show each change's diff and ask what to do with it. "accept remaining"
+ * and "reject remaining" finish the review early, so they require an
+ * extra confirmation; declining the confirmation returns to the change
+ * being reviewed.
+ *
+ * @param {import('#utils/stage.js').Stage} stage
+ * @param {import('#utils/stage.js').Change[]} changes
+ * @returns {Promise<import('#utils/stage.js').Change[] | null>}
+ *   the accepted changes, or null to cancel the whole run
+ */
+async function reviewEachChange(stage, changes) {
+  /** @type {import('#utils/stage.js').Change[]} */
+  const accepted = [];
+  let index = 0;
+
+  while (index < changes.length) {
+    const change = changes[index];
+
+    if (!change) break;
+
+    const remaining = changes.length - index;
+
+    // Bypass clack for the diff itself: diffs are long, and clack's
+    // log decorations wrap every line.
+    console.log("\n" + (await stage.diff([change])));
+
+    const answer = await p.select({
+      message: `${change.path} (${index + 1} of ${changes.length})`,
+      options: [
+        { value: "accept", label: "accept", hint: "write this change" },
+        { value: "reject", label: "reject", hint: "skip this change" },
+        ...(remaining > 1
+          ? /** @type {const} */ ([
+              {
+                value: "accept-remaining",
+                label: "accept remaining",
+                hint: `accept this and the ${remaining - 1} unreviewed change${remaining - 1 === 1 ? "" : "s"} after it`,
+              },
+              {
+                value: "reject-remaining",
+                label: "reject remaining",
+                hint: `reject this and the ${remaining - 1} unreviewed change${remaining - 1 === 1 ? "" : "s"} after it`,
+              },
+            ])
+          : []),
+      ],
+    });
+
+    if (p.isCancel(answer)) {
+      return null;
+    }
+
+    if (answer === "accept") {
+      accepted.push(change);
+      index++;
+      continue;
+    }
+
+    if (answer === "reject") {
+      index++;
+      continue;
+    }
+
+    const bulkAccept = answer === "accept-remaining";
+    const confirmed = await p.confirm({
+      message: `${bulkAccept ? "Accept" : "Reject"} all ${remaining} remaining change${remaining === 1 ? "" : "s"} without reviewing them?`,
+    });
+
+    if (p.isCancel(confirmed) || !confirmed) {
+      // return to the change being reviewed
+      continue;
+    }
+
+    if (bulkAccept) {
+      accepted.push(...changes.slice(index));
+    }
+
+    break;
+  }
+
+  p.log.info(
+    `Accepted ${accepted.length} of ${changes.length} change${changes.length === 1 ? "" : "s"}`,
+  );
+
+  return accepted;
+}
+
+/**
+ * @param {import('#utils/stage.js').Change[]} changes
+ * @returns {string}
+ */
+function summarize(changes) {
+  const colors = /** @type {const} */ ({
+    added: "green",
+    modified: "yellow",
+    deleted: "red",
+  });
+
+  return changes
+    .map((change) => {
+      const letter = change.status[0]?.toUpperCase() ?? "?";
+
+      return `${styleText(colors[change.status], letter)} ${change.path}`;
+    })
+    .join("\n");
+}

package/src/index.js

@@ -1,2 +1,3 @@
 export { generateProject } from "./cli/generator.js";
 export { Project } from "./utils/project.js";
+export { Stage } from "./utils/stage.js";

package/src/layers/are-the-types-wrong/index.js

@@ -0,0 +1,74 @@
+import { packageJson } from "ember-apply";
+import { getLatest } from "#utils/npm.js";
+import { addTsdownConfigProperty, hasTsdownConfigProperty } from "#utils/tsdown-config.js";
+
+const deps = {
+  "@arethetypeswrong/core": "^0.18.5",
+};
+
+/**
+ * @type {import('#types').Layer}
+ */
+export default {
+  label: "Are The Types Wrong?",
+  hint: "validate the published declarations on every build",
+
+  async run(project) {
+    // Publish checks: apps aren't published
+    if (project.type !== "library") return;
+
+    // Declarations are the thing being checked
+    if (!(await project.hasOrWantsLayer("typescript"))) return;
+
+    // ESM-only packages don't offer the CJS resolution modes the strict
+    // profile requires
+    await addTsdownConfigProperty(project, "attw", `attw: { profile: "esm-only" }`);
+    await packageJson.addDevDependencies(await getLatest(deps), project.directory);
+  },
+
+  /**
+   * @overload
+   * @param {import('#utils/project.js').Project} project
+   * @param {true} explain
+   * @returns {Promise<{ isSetup: boolean; reasons: string[] }>}
+   */
+  /**
+   * @overload
+   * @param {import('#utils/project.js').Project} project
+   * @param {boolean | undefined} [explain]
+   * @returns {Promise<boolean>}
+   */
+  async isSetup(project, explain) {
+    /** @type {string[]} */
+    const reasons = [];
+
+    // Nothing to set up outside TypeScript libraries, so nothing can be
+    // missing
+    if (project.type !== "library" || !(await project.hasOrWantsLayer("typescript"))) {
+      return explain ? { isSetup: true, reasons } : true;
+    }
+
+    if (!(await hasTsdownConfigProperty(project, "attw"))) {
+      if (!explain) return false;
+
+      reasons.push("tsdown.config.js does not configure attw");
+    }
+
+    let manifest = await packageJson.read(project.directory);
+
+    if (!manifest.devDependencies?.["@arethetypeswrong/core"]) {
+      if (!explain) return false;
+
+      reasons.push("package.json is missing @arethetypeswrong/core in devDependencies");
+    }
+
+    if (explain) {
+      return {
+        isSetup: reasons.length === 0,
+        reasons,
+      };
+    }
+
+    return reasons.length === 0;
+  },
+};

package/src/layers/git/files/gitignore

@@ -1 +1,14 @@
-node_modules
+# compiled output
+/dist/
+/dist-*
+
+# dependencies
+/node_modules/
+
+# misc
+*.local
+/.pnp*
+/.eslintcache
+/coverage/
+/npm-debug.log*
+/testem.log

package/src/layers/git/index.js

@@ -1,5 +1,6 @@
 import { hasGit, initGit, isInGit } from "#utils/git.js";
 import { formatLabel } from "#utils/cli.js";
+import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { cp } from "node:fs/promises";
 
@@ -7,10 +8,7 @@ export default {
   label: formatLabel("git init"),
   hint: "set up this project as a fresh git repository",
 
-  /**
-   * @param {import('#utils/project.js').Project} project
-   */
-  async defaultValue(project) {
+  async defaultValue() {
     return !isInGit();
   },
 
@@ -27,7 +25,10 @@ export default {
       let gitIgnorePath = join(import.meta.dirname, "files/gitignore");
       let targetPath = join(project.directory, ".gitignore");
 
-      await cp(gitIgnorePath, targetPath, { force: true });
+      // Don't clobber a .gitignore provided by a base or by the user
+      if (!existsSync(targetPath)) {
+        await cp(gitIgnorePath, targetPath);
+      }
     }
 
     return initOk;