ember.nvp 0.5.0 → 0.7.0

package/src/utils/stage.js

@@ -0,0 +1,317 @@
+import { existsSync } from "node:fs";
+import { cp, mkdir, mkdtemp, readdir, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, relative, sep } from "node:path";
+import { styleText } from "node:util";
+import { structuredPatch } from "diff";
+
+/**
+ * Directories that belong to the target project's environment rather than
+ * its generated contents. They are never seeded into the stage, never
+ * diffed, and never deleted on commit.
+ *
+ * (`.git` has one exception: see {@link Stage#commit})
+ */
+const ENVIRONMENT_DIRECTORIES = new Set(["node_modules", ".git"]);
+
+/**
+ * @typedef {'added' | 'modified' | 'deleted'} ChangeStatus
+ * @typedef {{ path: string, status: ChangeStatus }} Change
+ */
+
+/**
+ * A copy-on-write overlay for a project directory, in the spirit of
+ * Docker's layered file systems:
+ *
+ * - the target directory is the read-only lower layer
+ * - a real directory in the OS temp dir is the writable upper layer,
+ *   seeded ("copied up") from the target
+ *
+ * All generation (bases, layers, consolidators) runs against the upper
+ * layer via `stage.directory`. Because the upper layer is a real
+ * directory, layers keep using `node:fs`, `ember-apply`, and even
+ * subprocesses (`git`, package managers) exactly as they would against
+ * the real project -- an in-process virtual fs can't offer that, since
+ * child processes can't see it.
+ *
+ * Nothing touches the target until {@link Stage#commit}; {@link Stage#discard}
+ * throws the upper layer away.
+ */
+export class Stage {
+  /**
+   * @param {string} targetDirectory the directory the project should end up in
+   * @param {{ seed?: boolean }} [options]
+   *   seed: copy the target's current contents into the stage first
+   *   (a "copy up"). Defaults to true. Pass false to stage a from-scratch
+   *   generation (e.g. the "replace" flow).
+   * @returns {Promise<Stage>}
+   */
+  static async create(targetDirectory, options = {}) {
+    const { seed = true } = options;
+    const directory = await mkdtemp(join(tmpdir(), "ember.nvp-stage-"));
+    const exists = existsSync(targetDirectory);
+
+    if (exists && seed) {
+      await cp(targetDirectory, directory, {
+        recursive: true,
+        force: true,
+        filter: (source) => !ENVIRONMENT_DIRECTORIES.has(basename(source)),
+      });
+    }
+
+    return new Stage(targetDirectory, directory, { isNew: !exists });
+  }
+
+  #target;
+  #directory;
+  #isNew;
+
+  /**
+   * Use {@link Stage.create} instead.
+   *
+   * @param {string} target
+   * @param {string} directory
+   * @param {{ isNew: boolean }} info
+   */
+  constructor(target, directory, info) {
+    this.#target = target;
+    this.#directory = directory;
+    this.#isNew = info.isNew;
+  }
+
+  /**
+   * The writable upper layer. Generate in here,
+   * e.g. `new Project(stage.directory, desires)`.
+   *
+   * @type {string}
+   */
+  get directory() {
+    return this.#directory;
+  }
+
+  /**
+   * The directory a commit writes to.
+   *
+   * @type {string}
+   */
+  get targetDirectory() {
+    return this.#target;
+  }
+
+  /**
+   * Whether the target directory existed when the stage was created.
+   *
+   * @type {boolean}
+   */
+  get isNew() {
+    return this.#isNew;
+  }
+
+  /**
+   * Compares the upper layer to the target.
+   *
+   * @returns {Promise<Change[]>}
+   */
+  async changes() {
+    const staged = await listFiles(this.#directory);
+    const existing = existsSync(this.#target) ? await listFiles(this.#target) : new Set();
+
+    /** @type {Change[]} */
+    const changes = [];
+
+    for (const path of staged) {
+      if (!existing.has(path)) {
+        changes.push({ path, status: "added" });
+        continue;
+      }
+
+      const [before, after] = await Promise.all([
+        readFile(join(this.#target, path)),
+        readFile(join(this.#directory, path)),
+      ]);
+
+      if (!before.equals(after)) {
+        changes.push({ path, status: "modified" });
+      }
+    }
+
+    for (const path of existing) {
+      if (!staged.has(path)) {
+        changes.push({ path, status: "deleted" });
+      }
+    }
+
+    return changes.sort((a, b) => a.path.localeCompare(b.path));
+  }
+
+  /**
+   * A unified diff of the staged changes against the target,
+   * colorized when stdout supports it.
+   *
+   * @param {Change[]} [changes] pass the result of {@link Stage#changes} to avoid recomputing
+   * @returns {Promise<string>}
+   */
+  async diff(changes) {
+    changes ??= await this.changes();
+
+    const patches = [];
+
+    for (const change of changes) {
+      const before =
+        change.status === "added" ? null : await readFile(join(this.#target, change.path));
+      const after =
+        change.status === "deleted" ? null : await readFile(join(this.#directory, change.path));
+
+      patches.push(renderPatch(change, before, after));
+    }
+
+    return patches.join("\n");
+  }
+
+  /**
+   * Applies the staged changes to the target directory, then removes the
+   * stage. Only paths reported by {@link Stage#changes} are touched --
+   * everything else in the target (untracked files, node_modules, .git)
+   * is left alone.
+   *
+   * One exception: when the stage has a `.git` directory and the target
+   * does not (the git layer ran `git init` inside the stage), the `.git`
+   * directory is carried over so a freshly generated project keeps its
+   * history.
+   *
+   * @param {Change[]} [changes] the changes to apply -- pass a subset of
+   *   {@link Stage#changes} to apply only some of them (e.g. the ones a
+   *   user accepted during review). Defaults to all staged changes.
+   * @returns {Promise<Change[]>} the changes that were written
+   */
+  async commit(changes) {
+    changes ??= await this.changes();
+
+    await mkdir(this.#target, { recursive: true });
+
+    for (const change of changes) {
+      const targetPath = join(this.#target, change.path);
+
+      if (change.status === "deleted") {
+        await rm(targetPath, { force: true });
+        continue;
+      }
+
+      await mkdir(dirname(targetPath), { recursive: true });
+      await cp(join(this.#directory, change.path), targetPath, { force: true });
+    }
+
+    const stagedGit = join(this.#directory, ".git");
+    const targetGit = join(this.#target, ".git");
+
+    if (existsSync(stagedGit) && !existsSync(targetGit)) {
+      await cp(stagedGit, targetGit, { recursive: true });
+    }
+
+    await this.discard();
+
+    return changes;
+  }
+
+  /**
+   * Removes the stage without writing anything to the target.
+   */
+  async discard() {
+    await rm(this.#directory, { recursive: true, force: true });
+  }
+}
+
+/**
+ * All files (as paths relative to `directory`), excluding environment
+ * directories. Includes dotfiles (`.gitignore`, `.github/`, ...), which
+ * `fs.glob` would skip.
+ *
+ * @param {string} directory
+ * @returns {Promise<Set<string>>}
+ */
+async function listFiles(directory) {
+  /** @type {Set<string>} */
+  const files = new Set();
+
+  const entries = await readdir(directory, { withFileTypes: true, recursive: true });
+
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+
+    const path = relative(directory, join(entry.parentPath, entry.name));
+
+    if (path.split(sep).some((segment) => ENVIRONMENT_DIRECTORIES.has(segment))) {
+      continue;
+    }
+
+    files.add(path);
+  }
+
+  return files;
+}
+
+/**
+ * @param {Change} change
+ * @param {Buffer | null} before
+ * @param {Buffer | null} after
+ * @returns {string}
+ */
+function renderPatch(change, before, after) {
+  const header = styleText("bold", `${statusLabel(change.status)} ${change.path}`);
+
+  if (before?.includes(0) || after?.includes(0)) {
+    return `${header}\n${styleText("dim", "(binary file)")}\n`;
+  }
+
+  const patch = structuredPatch(
+    change.path,
+    change.path,
+    before?.toString() ?? "",
+    after?.toString() ?? "",
+    undefined,
+    undefined,
+    { context: 3 },
+  );
+
+  const lines = [
+    header,
+    styleText("red", `--- ${change.status === "added" ? "/dev/null" : `a/${change.path}`}`),
+    styleText("green", `+++ ${change.status === "deleted" ? "/dev/null" : `b/${change.path}`}`),
+  ];
+
+  for (const hunk of patch.hunks) {
+    lines.push(
+      styleText(
+        "cyan",
+        `@@ -${hunk.oldStart},${hunk.oldLines} +${hunk.newStart},${hunk.newLines} @@`,
+      ),
+    );
+
+    for (const line of hunk.lines) {
+      if (line.startsWith("+")) {
+        lines.push(styleText("green", line));
+      } else if (line.startsWith("-")) {
+        lines.push(styleText("red", line));
+      } else {
+        lines.push(line);
+      }
+    }
+  }
+
+  return lines.join("\n") + "\n";
+}
+
+/**
+ * @param {ChangeStatus} status
+ * @returns {string}
+ */
+function statusLabel(status) {
+  switch (status) {
+    case "added":
+      return styleText("green", "A");
+    case "modified":
+      return styleText("yellow", "M");
+    case "deleted":
+      return styleText("red", "D");
+  }
+}

package/src/utils/tsdown-config.js

@@ -0,0 +1,85 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { toTree, print, statements } from "ember-estree";
+
+/**
+ * Adds a property to the object passed to `defineConfig(...)` in the
+ * project's tsdown.config.js.
+ *
+ * No-ops when the property is already present (layers re-run), and when
+ * the config doesn't have the `defineConfig({ ... })` shape -- an existing
+ * project's hand-rolled config is the user's to manage.
+ *
+ * @param {import('#utils/project.js').Project} project
+ * @param {string} propertyName
+ * @param {string} propertySource the property as source, e.g. `publint: true`
+ */
+export async function addTsdownConfigProperty(project, propertyName, propertySource) {
+  const configPath = project.path("tsdown.config.js");
+  const contents = await readFile(configPath, "utf-8");
+
+  /** @type {import('ember-estree').ASTNode | null} */
+  let configObject = null;
+
+  const tree = /** @type {import('ember-estree').FileNode} */ (
+    toTree(contents, {
+      filePath: configPath,
+      visitors: {
+        CallExpression(node) {
+          const callee = /** @type {import('ember-estree').ASTNode} */ (node.callee);
+
+          if (callee?.type !== "Identifier" || callee.name !== "defineConfig") return;
+
+          const [argument] = /** @type {import('ember-estree').ASTNode[]} */ (node.arguments ?? []);
+
+          if (argument?.type === "ObjectExpression") {
+            configObject = argument;
+          }
+        },
+      },
+    })
+  );
+
+  if (!configObject) return;
+
+  const found = /** @type {import('ember-estree').ASTNode} */ (configObject);
+  const properties = /** @type {import('ember-estree').ASTNode[]} */ (found.properties ?? []);
+
+  const alreadyPresent = properties.some((property) => {
+    const key = /** @type {import('ember-estree').ASTNode} */ (property.key);
+
+    return key?.type === "Identifier" && key.name === propertyName;
+  });
+
+  if (alreadyPresent) return;
+
+  const [statement] = statements`defineConfig({ ${propertySource} });`;
+
+  if (!statement) return;
+
+  const expression = /** @type {import('ember-estree').ASTNode} */ (statement.expression);
+  const [templateObject] = /** @type {import('ember-estree').ASTNode[]} */ (expression.arguments);
+  const [property] = /** @type {import('ember-estree').ASTNode[]} */ (
+    templateObject?.properties ?? []
+  );
+
+  if (!property) return;
+
+  properties.push(property);
+  found.properties = properties;
+
+  await writeFile(configPath, print(tree));
+}
+
+/**
+ * Whether the project's tsdown.config.js configures `propertyName`.
+ *
+ * @param {import('#utils/project.js').Project} project
+ * @param {string} propertyName
+ */
+export async function hasTsdownConfigProperty(project, propertyName) {
+  if (!project.hasFile("tsdown.config.js")) return false;
+
+  const contents = await readFile(project.path("tsdown.config.js"), "utf-8");
+
+  return contents.includes(propertyName);
+}

package/src/utils/types.ts

@@ -8,7 +8,11 @@ export interface Layer {
    */
   label: string;
   hint?: string;
-  defaultValue?: () => unknown;
+  /**
+   * Whether the layer is pre-selected in the CLI (the user can still
+   * deselect it).
+   */
+  defaultValue?: (projectType: ProjectType) => unknown;
   /**
    * The function that applies the codemod
    *

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

@@ -0,0 +1,232 @@
+import { describe, it, beforeAll, afterAll, expect } from "vitest";
+import { generate, mktemp } from "#test-helpers";
+import { writeLibrarySource } from "./library-src-fixtures.ts";
+import { execa } from "execa";
+import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+
+import type { Project } from "ember.nvp";
+
+/**
+ * The minimal-library base has to produce a *buildable* library: these tests
+ * generate both flavors (JavaScript and TypeScript), snapshot the interesting
+ * generated files, and run the real `pnpm build` (tsdown + rolldown) against
+ * them.
+ */
+
+async function listFiles(directory: string): Promise<string[]> {
+  const entries = await readdir(directory, { withFileTypes: true, recursive: true });
+
+  return entries
+    .filter((entry) => entry.isFile())
+    .map((entry) => relative(directory, join(entry.parentPath, entry.name)))
+    .filter((path) => !path.split(sep).includes("node_modules"))
+    .sort();
+}
+
+async function read(project: Project, filePath: string): Promise<string> {
+  return readFile(join(project.directory, filePath), "utf-8");
+}
+
+async function installAndBuild(project: Project) {
+  let install = await execa("pnpm install", { cwd: project.directory, shell: true });
+  expect(install.exitCode).toBe(0);
+
+  let build = await execa("pnpm build", { cwd: project.directory, shell: true });
+  expect(build.exitCode).toBe(0);
+}
+
+describe("base: minimal-library", () => {
+  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("JavaScript", () => {
+    let project: Project;
+
+    beforeAll(async () => {
+      project = await generate({ type: "library", name: "my-lib", layers: [] });
+      dirs.push(project.directory);
+    });
+
+    it("generates the expected files (src is empty)", async () => {
+      expect(await listFiles(project.directory)).toMatchInlineSnapshot(`
+        [
+          ".gitignore",
+          "README.md",
+          "package.json",
+          "src/index.js",
+          "tsdown.config.js",
+        ]
+      `);
+
+      expect(await read(project, "src/index.js")).toBe("");
+    });
+
+    it("is publishable", async () => {
+      let manifest = JSON.parse(await read(project, "package.json"));
+
+      // The template is private (it lives in a workspace); the generated
+      // library must not be
+      expect(manifest).not.toHaveProperty("private");
+    });
+
+    it("has no TypeScript leftovers", async () => {
+      let manifest = JSON.parse(await read(project, "package.json"));
+
+      expect(manifest.devDependencies).not.toHaveProperty("typescript");
+      expect(manifest.devDependencies).not.toHaveProperty("@ember/library-tsconfig");
+      // No declarations are emitted without types
+      expect(JSON.stringify(manifest.exports)).not.toContain("types");
+
+      expect(await read(project, "tsdown.config.js")).toMatchInlineSnapshot(`
+        "import { defineConfig, ember } from "@nullvoxpopuli/ember-rolldown";
+
+        export default defineConfig({
+          entry: ["./src/index.js"],
+          dts: false,
+          plugins: [ember()],
+        });
+        "
+      `);
+    });
+
+    it("removes the TS plugin from an existing project's babel config", async () => {
+      // The base doesn't emit a babel.config.js, but generation can run
+      // over an existing project that has one
+      let directory = await mktemp("existing-lib");
+
+      dirs.push(directory);
+
+      await mkdir(directory, { recursive: true });
+      await writeFile(
+        join(directory, "babel.config.js"),
+        `export default {
+  plugins: [
+    ["@babel/plugin-transform-typescript", { allExtensions: true }],
+    ["module:decorator-transforms"],
+  ],
+};
+`,
+      );
+
+      let existing = await generate({ directory, type: "library", name: "existing-lib" });
+
+      let babelConfig = await readFile(join(existing.directory, "babel.config.js"), "utf-8");
+
+      expect(babelConfig).not.toContain("@babel/plugin-transform-typescript");
+      expect(babelConfig).toContain("module:decorator-transforms");
+    });
+
+    it("builds (with example source written in)", async () => {
+      await writeLibrarySource(project, "javascript");
+      await installAndBuild(project);
+
+      let output = await read(project, "dist/index.js");
+
+      // Published libraries ship precompileTemplate (the consuming app does
+      // the final compile), never wire format
+      expect(output).toContain("precompileTemplate");
+      expect(output).not.toContain("createTemplateFactory");
+
+      expect(await listFiles(join(project.directory, "dist"))).toMatchInlineSnapshot(`
+        [
+          "index.js",
+          "index.js.map",
+        ]
+      `);
+    });
+  });
+
+  describe("TypeScript", () => {
+    let project: Project;
+
+    beforeAll(async () => {
+      project = await generate({ type: "library", name: "my-lib", layers: ["typescript"] });
+      dirs.push(project.directory);
+    });
+
+    it("generates the expected files (src is empty)", async () => {
+      expect(await listFiles(project.directory)).toMatchInlineSnapshot(`
+        [
+          ".gitignore",
+          "README.md",
+          "package.json",
+          "src/index.ts",
+          "tsconfig.json",
+          "tsdown.config.js",
+        ]
+      `);
+
+      expect(await read(project, "src/index.ts")).toBe("");
+    });
+
+    it("type checks", async () => {
+      await writeLibrarySource(project, "typescript");
+
+      let install = await execa("pnpm install", { cwd: project.directory, shell: true });
+      expect(install.exitCode).toBe(0);
+
+      let types = await execa("pnpm lint:types", { cwd: project.directory, shell: true });
+      expect(types.exitCode).toBe(0);
+    });
+
+    it("builds, including declarations", async () => {
+      await installAndBuild(project);
+
+      let output = await read(project, "dist/index.js");
+
+      expect(output).toContain("precompileTemplate");
+      expect(output).not.toContain("createTemplateFactory");
+
+      let declarations = await read(project, "dist/index.d.ts");
+
+      expect(declarations).toContain("declare class Greeting extends Component<GreetingSignature>");
+      expect(declarations).toContain("declare const Badge: TOC<BadgeSignature>");
+      expect(declarations).toContain("declare function add(a: number, b: number): number");
+
+      expect(await listFiles(join(project.directory, "dist"))).toMatchInlineSnapshot(`
+        [
+          "index.d.ts",
+          "index.d.ts.map",
+          "index.js",
+          "index.js.map",
+        ]
+      `);
+    });
+
+    it("errors when tsconfig lacks isolatedDeclarations", async () => {
+      let tsconfigPath = join(project.directory, "tsconfig.json");
+      let original = await readFile(tsconfigPath, "utf-8");
+
+      try {
+        await writeFile(
+          tsconfigPath,
+          JSON.stringify({
+            extends: "@ember/library-tsconfig",
+            include: ["src"],
+            compilerOptions: { allowJs: true, rootDir: "./src" },
+          }),
+        );
+
+        let build = await execa("pnpm build", {
+          cwd: project.directory,
+          shell: true,
+          reject: false,
+          all: true,
+        });
+
+        expect(build.exitCode).not.toBe(0);
+        expect(build.all).toContain('"compilerOptions.isolatedDeclarations": true');
+      } finally {
+        await writeFile(tsconfigPath, original);
+      }
+    });
+  });
+});

package/test/ember.nvp/generator-replace-or-update.test.ts

@@ -1,10 +1,9 @@
 import { describe, it, expect, afterAll } from "vitest";
 import { generate, layers, expectIsSetup } from "#test-helpers";
 import { generateProject } from "ember.nvp";
-import { writeFile } from "node:fs/promises";
+import { rm, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { rimraf } from "rimraf";
 
 /**
  * The replace-or-update question only matters when a project already exists
@@ -21,7 +20,7 @@ describe("generating over an existing project", () => {
     if (process.env.CI) return;
 
     for (const dir of dirs) {
-      await rimraf(dir, { maxRetries: 3, retryDelay: 100 });
+      await rm(dir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
     }
   });