ember.nvp 1.8.0 → 1.10.0

package/src/cli/help.js

@@ -0,0 +1,82 @@
+import { styleText } from "node:util";
+
+/**
+ * CLI flags only carry strings and booleans
+ *
+ * @type {Record<import('#types').LayerOptionType, string>}
+ */
+const FLAG_TYPES = {
+  text: "string",
+  number: "number",
+  confirm: "boolean",
+  select: "string",
+  multiselect: "string",
+};
+
+/**
+ * Print help text to stdout.
+ *
+ * @param {Record<string, any>} coreOptions
+ * @param {import('#types').DiscoveredLayer[]} [layers]
+ */
+export function printHelp(coreOptions, layers = []) {
+  const title = styleText(["bgCyan", "black"], " ember.nvp ");
+  console.log(`${title}\n`);
+  console.log(`${styleText("bold", "Usage:")} npx ember.nvp [options]\n`);
+
+  console.log(styleText("bold", "Core Options:"));
+  for (const [name, config] of Object.entries(coreOptions)) {
+    printOption({
+      flag: `--${name}`,
+      alias: config.short ? `-${config.short}, ` : "    ",
+      type: config.type,
+      description: config.description,
+      choices: config.choices,
+    });
+  }
+
+  const withOptions = layers.filter((layer) => layer.options);
+
+  if (withOptions.length === 0) return;
+
+  console.log(styleText("bold", "Layer Options:"));
+  for (const layer of withOptions) {
+    for (const [key, schema] of Object.entries(layer.options ?? {})) {
+      const name = `${layer.name}.${key}`;
+
+      printOption({
+        flag: schema.type === "confirm" ? `--[no-]${name}` : `--${name}`,
+        alias: "    ",
+        type: FLAG_TYPES[schema.type],
+        description: schema.prompt,
+        choices: schema.options?.map((choice) => choice.value),
+        fallback: schema.default,
+      });
+    }
+  }
+}
+
+/**
+ * @param {{
+ *   flag: string,
+ *   alias: string,
+ *   type?: string,
+ *   description?: string,
+ *   choices?: string[],
+ *   fallback?: unknown,
+ * }} option
+ */
+function printOption({ flag, alias, type, description = "", choices, fallback }) {
+  const typeStr = type ? styleText("dim", `<${type}>`) : "";
+  const choicesStr = choices
+    ? styleText("yellow", ` [choices: ${choices.map((c) => `"${c}"`).join(", ")}]`)
+    : "";
+  const fallbackStr =
+    fallback === undefined ? "" : styleText("dim", ` [default: ${JSON.stringify(fallback)}]`);
+
+  console.log(`  ${styleText("cyan", alias)}${styleText("cyan", flag)} ${typeStr}`);
+  if (description || choicesStr || fallbackStr) {
+    console.log(`      ${description}${choicesStr}${fallbackStr}`);
+  }
+  console.log("");
+}

package/src/cli/index.js

@@ -4,6 +4,7 @@ import * as p from "@clack/prompts";
 import { generateProject } from "./generator.js";
 import { askName } from "./questions/name.js";
 import { askLayers } from "./questions/layers.js";
+import { askLayerOptions } from "./questions/layer-options.js";
 import { askProjectType } from "./questions/project-type.js";
 import { askPackageManager } from "./questions/package-manager.js";
 import { askPath } from "./questions/path.js";
@@ -35,6 +36,19 @@ async function main() {
   const selectedLayers = await askLayers(projectType);
   const packageManager = await askPackageManager();
 
+  // Layer options start from what the project already uses
+  const existing =
+    replaceOrUpdate === "update"
+      ? new Project(projectPath, {
+          name: projectName,
+          type: projectType,
+          path: projectPath,
+          layers: selectedLayers,
+          packageManager,
+        })
+      : undefined;
+  const layerOptions = await askLayerOptions(selectedLayers, existing);
+
   await askIfOK();
 
   /**
@@ -60,6 +74,7 @@ async function main() {
     path: projectPath,
     layers: selectedLayers,
     packageManager,
+    options: layerOptions,
   });
 
   const s = p.spinner();

package/src/cli/questions/layer-options.js

@@ -0,0 +1,130 @@
+import { styleText } from "node:util";
+import * as p from "@clack/prompts";
+import { printArgInUse, parseLayerOptionsFromParsedArgs } from "#args";
+import { validateOption } from "./validate-option.js";
+
+/**
+ * Prompt the user for options defined on the selected layers.
+ * Skips options that were explicitly provided via CLI flags.
+ *
+ * @param {import('#types').DiscoveredLayer[]} selectedLayers
+ * @param {import('#utils/project.js').Project} [existing] the project being updated, for `detect`
+ * @returns {Promise<Record<string, Record<string, any>>>}
+ */
+export async function askLayerOptions(selectedLayers, existing) {
+  const cliOptions = parseLayerOptionsFromParsedArgs(selectedLayers);
+  /** @type {Record<string, Record<string, any>>} */
+  const result = {};
+
+  for (const layer of selectedLayers) {
+    if (!layer.options) continue;
+
+    const layerResult = (result[layer.name] ??= {});
+
+    for (const [key, schema] of Object.entries(layer.options)) {
+      const fromCli = cliOptions[layer.name]?.[key];
+
+      if (fromCli !== undefined) {
+        layerResult[key] = fromCli;
+        printArgInUse(`${layer.name}.${key}`, String(fromCli));
+        continue;
+      }
+
+      const message = `${styleText("magentaBright", layer.name)}: ${schema.prompt}`;
+      const detected = existing && schema.detect ? await schema.detect(existing) : undefined;
+
+      layerResult[key] = await ask(message, schema, detected ?? schema.default);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * @param {string} message
+ * @param {import('#types').LayerOptionSchema} schema
+ * @param {any} initial
+ * @returns {Promise<unknown>}
+ */
+async function ask(message, schema, initial) {
+  switch (schema.type) {
+    case "text":
+    case "number": {
+      const fallback = initial === undefined ? undefined : String(initial);
+
+      const answer = await p.text({
+        message,
+        placeholder: fallback,
+        defaultValue: fallback,
+        /**
+         * clack swaps in the defaultValue after validation,
+         * so an empty answer is checked as the default.
+         */
+        validate: (input) => {
+          const result = validateOption(schema, input || fallback || "");
+
+          return result.ok ? undefined : result.error;
+        },
+      });
+
+      // converts "number" answers, which clack returns as strings
+      const result = validateOption(schema, exitIfCancelled(answer));
+
+      if (!result.ok) throw new Error(result.error);
+
+      return result.value;
+    }
+
+    case "confirm":
+      return exitIfCancelled(
+        await p.confirm({
+          message,
+          initialValue: initial ?? true,
+        }),
+      );
+
+    case "select":
+      return exitIfCancelled(
+        await p.select({
+          message,
+          options: schema.options ?? [],
+          initialValue: initial,
+        }),
+      );
+
+    case "multiselect": {
+      // clack's multiselect has no validate, so ask again until the selection passes
+      while (true) {
+        const answer = await p.multiselect({
+          message,
+          options: schema.options ?? [],
+          initialValues: initial ?? [],
+          required: false,
+        });
+
+        const result = validateOption(schema, exitIfCancelled(answer));
+
+        if (result.ok) return result.value;
+
+        p.log.error(result.error);
+      }
+    }
+
+    default:
+      throw new Error(`Unknown option type '${String(schema.type)}'`);
+  }
+}
+
+/**
+ * @template T
+ * @param {T | symbol} answer
+ * @returns {T}
+ */
+function exitIfCancelled(answer) {
+  if (p.isCancel(answer)) {
+    p.cancel("Operation cancelled");
+    return process.exit(0);
+  }
+
+  return answer;
+}

package/src/cli/questions/validate-option.js

@@ -0,0 +1,106 @@
+import { runValidation } from "@clack/core";
+
+/**
+ * @typedef {import('#types').LayerOptionSchema} LayerOptionSchema
+ *
+ * @typedef {{ ok: true, value: any }} ValidationSuccess
+ * @typedef {{ ok: false, error: string }} ValidationFailure
+ * @typedef {ValidationSuccess | ValidationFailure} ValidationResult
+ */
+
+/**
+ * Convert a value from a CLI flag or a prompt to the option's type,
+ * then run the option's own `validate`.
+ *
+ * Defaults are not applied here.
+ * See `Project#getLayerOptions`.
+ *
+ * @param {LayerOptionSchema} schema
+ * @param {unknown} rawValue
+ * @returns {ValidationResult}
+ */
+export function validateOption(schema, rawValue) {
+  const converted = convert(schema, rawValue);
+
+  if (!converted.ok || !schema.validate) return converted;
+
+  const error = runValidation(schema.validate, converted.value);
+
+  if (!error) return converted;
+
+  return { ok: false, error: error instanceof Error ? error.message : error };
+}
+
+/**
+ * @param {LayerOptionSchema} schema
+ * @param {unknown} rawValue
+ * @returns {ValidationResult}
+ */
+function convert(schema, rawValue) {
+  switch (schema.type) {
+    case "text":
+      return { ok: true, value: String(rawValue) };
+
+    case "number": {
+      const text = String(rawValue).trim();
+
+      /**
+       * Number() also accepts "", "0x10", and "1e3",
+       * which nobody means when they type a count.
+       */
+      if (!/^-?\d+(\.\d+)?$/.test(text)) {
+        return { ok: false, error: `'${text}' is not a number` };
+      }
+
+      return { ok: true, value: Number(text) };
+    }
+
+    case "confirm":
+      return typeof rawValue === "boolean"
+        ? { ok: true, value: rawValue }
+        : { ok: false, error: `'${String(rawValue)}' is not true or false` };
+
+    case "select": {
+      const allowed = choicesOf(schema);
+
+      return typeof rawValue === "string" && allowed.includes(rawValue)
+        ? { ok: true, value: rawValue }
+        : { ok: false, error: notAChoice(rawValue, allowed) };
+    }
+
+    case "multiselect": {
+      const allowed = choicesOf(schema);
+
+      if (!Array.isArray(rawValue)) {
+        return { ok: false, error: `'${String(rawValue)}' is not a list` };
+      }
+
+      for (const item of rawValue) {
+        if (!allowed.includes(item)) {
+          return { ok: false, error: notAChoice(item, allowed) };
+        }
+      }
+
+      return { ok: true, value: rawValue };
+    }
+
+    default:
+      return { ok: false, error: `Unknown option type '${String(schema.type)}'` };
+  }
+}
+
+/**
+ * @param {LayerOptionSchema} schema
+ * @returns {string[]}
+ */
+function choicesOf(schema) {
+  return (schema.options ?? []).map((choice) => choice.value);
+}
+
+/**
+ * @param {unknown} value
+ * @param {string[]} allowed
+ */
+function notAChoice(value, allowed) {
+  return `Invalid option '${String(value)}'. Must be one of: ${allowed.join(", ")}`;
+}

package/src/layers/eslint-bundled/app.test.ts

@@ -0,0 +1,182 @@
+import { beforeAll, describe, it, expect as hardExpect, afterAll } from "vitest";
+import { expectIsSetup, generate, layers, reapply } from "#test-helpers";
+import { packageJson } from "ember-apply";
+
+import type { Project } from "ember.nvp";
+import { rm } from "node:fs/promises";
+
+const expect = hardExpect.soft;
+
+let layer = layers.find((layer) => layer.name === "eslint-bundled")!;
+
+const CONFIG_PACKAGES = {
+  ember: "ember-eslint",
+  nvp: "@nullvoxpopuli/eslint-configs",
+};
+
+describe.each(Object.entries(CONFIG_PACKAGES))("preset: %s", (preset, configPackage) => {
+  const options = { "eslint-bundled": { preset } };
+
+  describe("starting without eslint-bundled", () => {
+    let project: Project;
+
+    beforeAll(async () => {
+      project = await generate({
+        type: "app",
+        packageManager: "pnpm",
+        layers: ["git"],
+        options,
+      });
+    });
+
+    afterAll(async () => {
+      await rm(project.directory, { recursive: true, force: true });
+    });
+
+    it("applying eslint-bundled", async () => {
+      await reapply(project, ["eslint-bundled"]);
+
+      await expectIsSetup(project, layer);
+      expect(await project.gitHasDiff()).toBe(false);
+    });
+  });
+
+  describe("starting with eslint-bundled", () => {
+    let project: Project;
+
+    beforeAll(async () => {
+      project = await generate({
+        type: "app",
+        packageManager: "pnpm",
+        layers: ["eslint-bundled", "git"],
+        options,
+      });
+    });
+
+    afterAll(async () => {
+      await rm(project.directory, { recursive: true, force: true });
+    });
+
+    it("installs only this preset's config package", async () => {
+      let manifest = await packageJson.read(project.directory);
+      let installed = Object.values(CONFIG_PACKAGES).filter(
+        (name) => manifest.devDependencies?.[name],
+      );
+
+      expect(installed).toEqual([configPackage]);
+    });
+
+    it("detects the preset", async () => {
+      expect(await layer.options?.preset?.detect?.(project)).toBe(preset);
+    });
+
+    it("reapplying eslint-bundled causes no changes", async () => {
+      await reapply(project, ["eslint-bundled"]);
+
+      await expectIsSetup(project, layer);
+      expect(await project.gitHasDiff()).toBe(false);
+    });
+  });
+
+  describe("package.json scripts", () => {
+    let project: Project;
+
+    beforeAll(async () => {
+      project = await generate({
+        type: "app",
+        packageManager: "pnpm",
+        layers: ["eslint-bundled", "git"],
+        options,
+      });
+
+      let { exitCode } = await project.run("pnpm install");
+
+      hardExpect(exitCode).toBe(0);
+
+      await expectIsSetup(project, layer);
+    });
+
+    afterAll(async () => {
+      await rm(project.directory, { recursive: true, force: true });
+    });
+
+    it("linting and fixing works", async () => {
+      {
+        let { exitCode } = await project.run("pnpm lint:eslint --fix");
+
+        expect(exitCode).toBe(0);
+      }
+
+      {
+        let { exitCode } = await project.run("pnpm lint:eslint");
+
+        expect(exitCode).toBe(0);
+      }
+    });
+  });
+});
+
+describe.each([
+  ["ember", "nvp"],
+  ["nvp", "ember"],
+] as const)("switching presets: %s to %s", (from, to) => {
+  let project: Project;
+
+  beforeAll(async () => {
+    let before = await generate({
+      type: "app",
+      packageManager: "pnpm",
+      layers: ["eslint-bundled", "git"],
+      options: { "eslint-bundled": { preset: from } },
+    });
+
+    project = await generate({
+      directory: before.directory,
+      type: "app",
+      packageManager: "pnpm",
+      layers: ["eslint-bundled", "git"],
+      options: { "eslint-bundled": { preset: to } },
+    });
+  });
+
+  afterAll(async () => {
+    await rm(project.directory, { recursive: true, force: true });
+  });
+
+  it("replaces the config package and the config", async () => {
+    let manifest = await packageJson.read(project.directory);
+
+    expect(manifest.devDependencies).toHaveProperty(CONFIG_PACKAGES[to]);
+    expect(manifest.devDependencies).not.toHaveProperty(CONFIG_PACKAGES[from]);
+    expect(await project.read("eslint.config.js")).toContain(CONFIG_PACKAGES[to]);
+    expect(await project.read("eslint.config.js")).not.toContain(CONFIG_PACKAGES[from]);
+  });
+
+  it("is setup, and detects the new preset", async () => {
+    await expectIsSetup(project, layer);
+    expect(await layer.options?.preset?.detect?.(project)).toBe(to);
+  });
+
+  it("reapplying causes no changes", async () => {
+    await reapply(project, ["eslint-bundled", "git"]);
+
+    expect(await project.gitHasDiff()).toBe(false);
+  });
+
+  it("linting and fixing works", async () => {
+    let install = await project.run("pnpm install");
+    hardExpect(install.exitCode).toBe(0);
+
+    {
+      let { exitCode } = await project.run("pnpm lint:eslint --fix");
+
+      expect(exitCode).toBe(0);
+    }
+
+    {
+      let { exitCode } = await project.run("pnpm lint:eslint");
+
+      expect(exitCode).toBe(0);
+    }
+  });
+});

package/src/layers/eslint-bundled/index.js

@@ -0,0 +1,172 @@
+import { getLatest } from "#utils/npm.js";
+import { files, packageJson } from "ember-apply";
+import { formatLabel } from "#utils/cli.js";
+import { maybeLintWithConcurrently } from "#consolidators/linting.js";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { hasDevDeps, readManifest } from "#utils/manifest.js";
+import { hasTypeScript6, syncTypeScript6, usesTypeScript7 } from "#utils/typescript.js";
+
+/**
+ * The config package of each preset.
+ *
+ * Each preset also has a folder in `files/`.
+ *
+ * @type {Record<string, Record<string, string>>}
+ */
+const PRESETS = {
+  ember: { "ember-eslint": "^1.0.0" },
+  nvp: { "@nullvoxpopuli/eslint-configs": "^7.0.0" },
+};
+
+/**
+ * @param {Record<string, any>} manifest
+ * @returns {string | undefined}
+ */
+function presetIn(manifest) {
+  for (const [preset, deps] of Object.entries(PRESETS)) {
+    if (hasDevDeps(manifest, deps)) return preset;
+  }
+
+  return undefined;
+}
+
+/**
+ * @param {import('#utils/project.js').Project} project
+ * @returns {string | undefined} undefined when the layer is not selected
+ */
+function wantedPreset(project) {
+  if (!project.wantsLayer("eslint-bundled")) return undefined;
+
+  return project.getLayerOptions("eslint-bundled").preset;
+}
+
+/**
+ * @type {import('#types').Layer}
+ */
+export default {
+  label: formatLabel("ESLint", "encapsulated config"),
+  hint: `Minimal dependencies added to package.json`,
+
+  options: {
+    preset: {
+      type: "select",
+      prompt: "Which ESLint config?",
+      default: "ember",
+      options: [
+        {
+          value: "ember",
+          label: "ember-eslint",
+          hint: "Not official, but follows the official configuration",
+        },
+        {
+          value: "nvp",
+          label: "@nullvoxpopuli/eslint-configs",
+          hint: "NullVoxPopuli's config for apps, libraries, TypeScript, and more",
+        },
+      ],
+      async detect(project) {
+        return presetIn(await readManifest(project));
+      },
+    },
+  },
+
+  async run(project, { preset }) {
+    await files.applyFolder(join(import.meta.dirname, "files", preset), project.directory);
+
+    // Only one preset at a time, so that switching presets leaves nothing behind
+    for (const [other, deps] of Object.entries(PRESETS)) {
+      if (other === preset) continue;
+
+      await packageJson.removeDevDependencies(Object.keys(deps), project.directory);
+    }
+
+    await packageJson.addDevDependencies(
+      await getLatest({
+        ...PRESETS[preset],
+        eslint: "^10.9.1",
+      }),
+      project.directory,
+    );
+
+    await packageJson.addScripts(
+      {
+        "lint:eslint": "eslint . --cache",
+        "lint:eslint:fix": "eslint . --fix",
+      },
+      project.directory,
+    );
+
+    // typescript-eslint needs TypeScript 6
+    await syncTypeScript6(project);
+
+    await maybeLintWithConcurrently(project);
+  },
+
+  /**
+   * @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) {
+    const reasons = [];
+
+    if (!existsSync(join(project.directory, "eslint.config.js"))) {
+      reasons.push("eslint.config.js is missing");
+
+      if (!explain) return false;
+    }
+
+    let manifest = await packageJson.read(project.directory);
+    let wanted = wantedPreset(project);
+
+    if (!hasDevDeps(manifest, ["eslint"])) {
+      reasons.push("missing required dependency: eslint");
+
+      if (!explain) return false;
+    }
+
+    if (wanted ? !hasDevDeps(manifest, PRESETS[wanted] ?? {}) : !presetIn(manifest)) {
+      reasons.push(`missing the config package of the ${wanted ?? "ember or nvp"} preset`);
+
+      if (!explain) return false;
+    }
+
+    if (usesTypeScript7(project, manifest) && !hasTypeScript6(manifest)) {
+      reasons.push("missing typescript (TypeScript 6) for typescript-eslint");
+
+      if (!explain) return false;
+    }
+
+    let scripts = Object.values(manifest.scripts ?? {}).filter((script) =>
+      script.includes("eslint"),
+    );
+
+    if (!scripts.some((script) => script.includes("--cache"))) {
+      reasons.push("missing eslint script with --cache flag");
+
+      if (!explain) return false;
+    }
+    if (!scripts.some((script) => script.includes("--fix"))) {
+      reasons.push("missing eslint script with --fix flag");
+
+      if (!explain) return false;
+    }
+
+    if (explain) {
+      return {
+        isSetup: reasons.length === 0,
+        reasons,
+      };
+    }
+
+    return reasons.length === 0;
+  },
+};