ember.nvp 1.8.0 → 1.10.0

package/packages/rolldown/src/transform.test.ts

@@ -1,12 +1,29 @@
-import { mkdtemp, mkdir, writeFile } from "node:fs/promises";
+import { originalPositionFor, TraceMap } from "@jridgewell/trace-mapping";
+import { existsSync } from "node:fs";
+import { mkdtemp, mkdir, readFile, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { rolldown } from "rolldown";
-import type { Plugin } from "rolldown";
+import type { OutputChunk, Plugin } from "rolldown";
 import { describe, expect, it } from "vitest";
 
 import { emberTransform } from "./transform.ts";
 
+interface BuildOptions {
+  input?: string[];
+  plugins?: (dir: string) => Plugin[];
+  sourcemap?: boolean;
+}
+
+interface Build {
+  /**
+   * The output directory.
+   * Nothing is written to it, but sourcemaps name their sources relative to it.
+   */
+  dir: string;
+  chunks: OutputChunk[];
+}
+
 /**
  * Drives the plugin through a real rolldown build.
  *
@@ -16,16 +33,11 @@ import { emberTransform } from "./transform.ts";
  * Every bare (package) specifier is marked external,
  * so the build only exercises the local `.gts` / `.gjs` / `.ts` handling
  * and doesn't need real dependencies installed.
- *
- * Returns the concatenated code of every emitted chunk.
  */
-async function bundle(
+async function generate(
   files: Record<string, string>,
-  {
-    input = ["index.ts"],
-    plugins = () => [],
-  }: { input?: string[]; plugins?: (dir: string) => Plugin[] } = {},
-): Promise<string> {
+  { input = ["index.ts"], plugins = () => [], sourcemap = false }: BuildOptions = {},
+): Promise<Build> {
   const dir = await mkdtemp(path.join(tmpdir(), "ember-rolldown-build-"));
 
   for (const [relative, source] of Object.entries(files)) {
@@ -43,18 +55,73 @@ async function bundle(
     onwarn() {},
   });
 
-  const { output } = await build.generate({ format: "es" });
+  const outDir = path.join(dir, "dist");
+  const { output } = await build.generate({ format: "es", dir: outDir, sourcemap });
 
-  const code = output
-    .filter((chunk): chunk is typeof chunk & { code: string } => "code" in chunk)
-    .map((chunk) => chunk.code)
-    .join("\n");
+  return {
+    dir: outDir,
+    chunks: output.filter((chunk): chunk is OutputChunk => chunk.type === "chunk"),
+  };
+}
+
+/**
+ * Returns the concatenated code of every chunk that `generate` emits.
+ */
+async function bundle(files: Record<string, string>, options?: BuildOptions): Promise<string> {
+  const { chunks } = await generate(files, options);
+  const code = chunks.map((chunk) => chunk.code).join("\n");
 
   // rolldown's `//#region <path>` comments reference the random temp dir.
   // Collapse them to the bare filename so snapshots stay deterministic.
   return code.replace(/(\/\/#region ).*\/([^/\n]+)$/gm, "$1$2");
 }
 
+/**
+ * Follows each needle in the emitted code through the chunk's sourcemap,
+ * the way a debugger does.
+ *
+ * One line per needle:
+ * - the source the map names
+ * - that source's line (1-based) and column (0-based)
+ * - the source text from that column on
+ */
+async function traced(build: Build, needles: string[]): Promise<string> {
+  const [chunk] = build.chunks;
+  if (!chunk?.map) throw new Error("The build emitted no sourcemap");
+
+  const map = new TraceMap(chunk.map.toString());
+  const lines = chunk.code.split("\n");
+  const result: string[] = [];
+
+  for (const needle of needles) {
+    const index = lines.findIndex((line) => line.includes(needle));
+    if (index === -1) throw new Error(`\`${needle}\` is not in the output:\n${chunk.code}`);
+
+    const {
+      source,
+      line: sourceLine,
+      column,
+    } = originalPositionFor(map, {
+      line: index + 1,
+      column: lines[index]!.indexOf(needle),
+    });
+
+    if (!source || sourceLine === null || column === null) {
+      result.push(`${needle} -> (unmapped)`);
+      continue;
+    }
+
+    const sourcePath = path.resolve(build.dir, source);
+    const text = existsSync(sourcePath)
+      ? (await readFile(sourcePath, "utf8")).split("\n")[sourceLine - 1]?.slice(column)
+      : "(no such file)";
+
+    result.push(`${needle} -> ${source}:${sourceLine}:${column}  ${text}`);
+  }
+
+  return result.join("\n");
+}
+
 describe("emberTransform (full plugin via rolldown)", () => {
   it("compiles a .gts module's <template> and keeps bare imports external", async () => {
     const code = await bundle({
@@ -313,4 +380,134 @@ describe("emberTransform (full plugin via rolldown)", () => {
     const sources = (chunk as { map?: { sources: string[] } }).map?.sources ?? [];
     expect(sources.some((source) => source.endsWith("foo.gts"))).toBe(true);
   });
+
+  it("names the .gts file in the map of a .gts with no <template>", async () => {
+    // content-tag does not run on these modules, but they still load under a virtual .ts id.
+    // helpers.gts goes through the specifier rewrite, and plain.gts does not.
+    const { chunks } = await generate(
+      {
+        "index.ts": [
+          `export { double } from './helpers.gts';`,
+          `export { half } from './plain.gts';`,
+        ].join("\n"),
+        "helpers.gts": [
+          `import { half } from './plain.gts';`,
+          `export function double(value: number): number {`,
+          `  return half(value) * 4;`,
+          `}`,
+        ].join("\n"),
+        "plain.gts": [
+          `export function half(value: number): number {`,
+          `  return value / 2;`,
+          `}`,
+        ].join("\n"),
+      },
+      { sourcemap: true },
+    );
+
+    // index.ts only re-exports, so it contributes no code and no source.
+    expect(chunks[0]?.map?.sources.toSorted()).toEqual(["../helpers.gts", "../plain.gts"]);
+  });
+
+  it("maps a rewritten .gts module to its exact source lines and columns", async () => {
+    // content-tag puts a doc comment's closing `*/` and the next declaration on one line.
+    // widget.gts imports another .gts, so the specifier rewrite runs on that output.
+    const build = await generate(
+      {
+        "index.ts": `export { Widget } from './widget.ts';`,
+        "widget.gts": [
+          `import { helper } from './other.gts';`,
+          ``,
+          `/**`,
+          ` * A widget.`,
+          ` */`,
+          `export class Widget {`,
+          `  /**`,
+          `   * The name.`,
+          `   */`,
+          `  get name(): string {`,
+          `    return helper();`,
+          `  }`,
+          ``,
+          `  <template>Hello {{this.name}}</template>`,
+          `}`,
+        ].join("\n"),
+        "other.gts": [`export function helper(): string {`, `  return 'x';`, `}`].join("\n"),
+      },
+      { sourcemap: true },
+    );
+
+    expect(await traced(build, ["Widget = class", "name()", "return helper"]))
+      .toMatchInlineSnapshot(`
+        "Widget = class -> ../widget.gts:6:13  Widget {
+        name() -> ../widget.gts:10:6  name(): string {
+        return helper -> ../widget.gts:11:4  return helper();"
+      `);
+  });
+
+  it("keeps columns in a plain .ts module that imports a .gts", async () => {
+    const build = await generate(
+      {
+        "index.ts": [
+          `import { helper } from './other.gts';`,
+          ``,
+          `export function greet(name: string): string {`,
+          `  return helper() + name;`,
+          `}`,
+        ].join("\n"),
+        "other.gts": [`export function helper(): string {`, `  return 'x';`, `}`].join("\n"),
+      },
+      { sourcemap: true },
+    );
+
+    expect(await traced(build, ["greet", "return helper"])).toMatchInlineSnapshot(`
+      "greet -> ../index.ts:3:16  greet(name: string): string {
+      return helper -> ../index.ts:4:2  return helper() + name;"
+    `);
+  });
+
+  it("maps .gts modules that the specifier rewrite does not touch", async () => {
+    // other.gts has no <template>, and widget.gts imports no .gts.
+    // Neither goes through the rewrite.
+    const build = await generate(
+      {
+        "index.ts": [
+          `export { helper } from './other.ts';`,
+          `export { Widget } from './widget.ts';`,
+        ].join("\n"),
+        "widget.gts": [
+          `import { helper } from './other.ts';`,
+          ``,
+          `/**`,
+          ` * A widget.`,
+          ` */`,
+          `export class Widget {`,
+          `  get name(): string {`,
+          `    return helper();`,
+          `  }`,
+          ``,
+          `  <template>Hello {{this.name}}</template>`,
+          `}`,
+        ].join("\n"),
+        "other.gts": [`export function helper(): string {`, `  return 'x';`, `}`].join("\n"),
+      },
+      { sourcemap: true },
+    );
+
+    expect(
+      await traced(build, [
+        "helper() {",
+        `return "x"`,
+        "Widget = class",
+        "name()",
+        "return helper",
+      ]),
+    ).toMatchInlineSnapshot(`
+      "helper() { -> ../other.gts:1:16  helper(): string {
+      return "x" -> ../other.gts:2:2  return 'x';
+      Widget = class -> ../widget.gts:6:13  Widget {
+      name() -> ../widget.gts:7:6  name(): string {
+      return helper -> ../widget.gts:8:4  return helper();"
+    `);
+  });
 });

package/packages/rolldown/src/transform.ts

@@ -1,4 +1,6 @@
+import remapping, { type EncodedSourceMap } from "@jridgewell/remapping";
 import { Preprocessor } from "content-tag";
+import MagicString from "magic-string";
 import { existsSync, realpathSync } from "node:fs";
 import { readFile, writeFile, readdir } from "node:fs/promises";
 import path from "node:path";
@@ -40,26 +42,78 @@ async function fixDtsExtensionsInDir(dir: string): Promise<void> {
 }
 
 /**
- * A sourcemap mapping every generated line to the same line of the input.
+ * A sourcemap from `code` back to `source`, with a segment for every column.
  *
- * - `AAAA` is the [0, 0, 0, 0] VLQ segment
- *   (first line maps to source 0, line 0, column 0)
- * - `AACA` is [0, 0, +1, 0]
- *   (each following line advances the source line by one)
+ * rolldown traces each output position back through the map of every hook.
+ * A position between two segments resolves to the segment before it,
+ * so fewer segments move positions to an earlier column.
  *
- * Exact at line granularity, which is all the specifier rewrite can disturb.
+ * content-tag's output often puts a doc comment's end and a declaration on one line.
+ * With one segment per line, the declaration resolves to the comment.
  */
-function lineIdentityMap(id: string, source: string) {
-  return {
-    version: 3,
-    sources: [id],
-    sourcesContent: [source],
-    names: [],
-    mappings: source
-      .split("\n")
-      .map((_, line) => (line === 0 ? "AAAA" : "AACA"))
-      .join(";"),
-  };
+function columnMap(code: MagicString, source: string) {
+  return code.generateMap({ source, includeContent: true, hires: true });
+}
+
+/**
+ * The `.gts` / `.gjs` file behind a virtual `.ts` / `.js` id,
+ * and content-tag's map back to it (absent when there was no `<template>` to compile).
+ */
+interface Backing {
+  fileName: string;
+  map?: string;
+}
+
+/**
+ * Points a declaration map at the `.gts` / `.gjs` files behind its virtual sources.
+ *
+ * rolldown-plugin-dts generates declarations from the loaded module (content-tag's output).
+ * So its maps name:
+ * - the virtual id, a file that does not exist
+ * - content-tag's line numbers, which do not match the source
+ *
+ * Tracing through content-tag's map gives the file and line
+ * that a consumer's "go to definition" can open.
+ *
+ * Returns `undefined` when no source is virtual.
+ */
+function remapDeclarationMap(
+  json: string,
+  mapDir: string,
+  backings: Map<string, Backing>,
+): string | undefined {
+  const map = JSON.parse(json) as EncodedSourceMap;
+
+  if (!map.sources.some((source) => source && backings.has(path.resolve(mapDir, source)))) {
+    return undefined;
+  }
+
+  const remapped = remapping(
+    map,
+    (source, context) => {
+      // Only the declaration map's own sources can be virtual.
+      if (context.depth > 1) return null;
+
+      const backing = backings.get(path.resolve(mapDir, source));
+      if (!backing) return null;
+
+      context.source = backing.fileName;
+      return backing.map ?? null;
+    },
+    // Like the rest of the declaration map, point at the published sources.
+    // Do not embed them.
+    { excludeContent: true },
+  );
+
+  // Backing files come back absolute.
+  // The other sources are relative to the map's directory.
+  remapped.sources = remapped.sources.map((source) =>
+    source && path.isAbsolute(source)
+      ? path.relative(mapDir, source).split(path.sep).join("/")
+      : source,
+  );
+
+  return remapped.toString();
 }
 
 /**
@@ -69,6 +123,9 @@ function lineIdentityMap(id: string, source: string) {
  * so rolldown can identify them as ts / js.
  */
 export function emberTransform(): Plugin {
+  // virtual id -> what it was loaded from
+  const backings = new Map<string, Backing>();
+
   return {
     name: "ember:transform",
 
@@ -190,10 +247,16 @@ export function emberTransform(): Plugin {
             const { code, map } = processor.process(source, {
               filename: fileName,
             });
+            backings.set(id, { fileName, map });
             return { code, map };
           }
 
-          return source;
+          // The map names the `.gts` / `.gjs` file.
+          // Without it, the `.js.map` names the virtual id, which is not on disk.
+          //
+          // The backing needs no map, because its declaration lines match the source.
+          backings.set(id, { fileName });
+          return { code: source, map: columnMap(new MagicString(source), fileName) };
         }
 
         return null;
@@ -215,22 +278,39 @@ export function emberTransform(): Plugin {
         // "load it (registering its declaration), then map to the declaration id".
         // A `.d.ts` id is returned as-is: unloadable when the module isn't registered yet
         // (e.g. the `.gts` is only ever type-imported).
-        const output = input.replace(
+        const output = new MagicString(input);
+
+        for (const match of input.matchAll(
           /(['"`])((?:\.\.?\/|\/|@|[A-Za-z0-9_\-])[^'"]*?\.gts)\1/g,
-          (_m, q, p) => `${q}${p.replace(/\.gts$/, ".ts")}${q}`,
-        );
+        )) {
+          // `.gts` ends the specifier, just before the closing quote.
+          const end = match.index + match[0].length - 1;
+          output.overwrite(end - ".gts".length, end, ".ts");
+        }
 
-        if (output === input) {
+        if (!output.hasChanged()) {
           return null;
         }
 
-        // The rewrite only shortens import specifiers in place,
-        // so a line-identity map is accurate to the line
-        // (and to the column, for everything before the first rewritten specifier on a line).
-        return { code: output, map: lineIdentityMap(id, input) };
+        return { code: output.toString(), map: columnMap(output, id) };
       },
     },
 
+    generateBundle(options, bundle) {
+      const outDir = options.dir ?? (options.file && path.dirname(options.file));
+      if (!outDir || backings.size === 0) return;
+
+      for (const output of Object.values(bundle)) {
+        if (output.type !== "asset" || !output.fileName.endsWith(".d.ts.map")) continue;
+        if (typeof output.source !== "string") continue;
+
+        const mapDir = path.dirname(path.resolve(outDir, output.fileName));
+        const remapped = remapDeclarationMap(output.source, mapDir, backings);
+
+        if (remapped) output.source = remapped;
+      }
+    },
+
     writeBundle: {
       async handler(options) {
         const outDir = (options as { dir?: string }).dir;

package/src/cli/args.js

@@ -1,61 +1,183 @@
 import * as p from "@clack/prompts";
 import { styleText, parseArgs } from "node:util";
+import { layers as discoveredLayers } from "#layers";
+import { validateOption } from "./questions/validate-option.js";
+import { printHelp } from "./help.js";
 
-const { values } = parseArgs({
-  options: {
-    name: {
-      type: "string",
-    },
-
-    path: {
-      type: "string",
-    },
-
-    type: {
-      type: "string",
-      choices: ["app", "addon", "library", "extension", "custom-element"],
-    },
-
-    confirm: {
-      type: "string",
-      choices: ["yes", "no"],
-    },
-
-    layers: {
-      type: "string",
-      multiple: true,
-    },
-
-    packageManager: {
-      type: "string",
-      choices: ["npm", "pnpm"],
-    },
-
-    replaceOrUpdate: {
-      type: "string",
-      choices: ["replace", "update"],
-    },
-
-    write: {
-      type: "string",
-      choices: ["yes", "no"],
-    },
+export const coreOptions = /** @type {const} */ ({
+  help: {
+    type: "boolean",
+    short: "h",
+    description: "Show CLI help and option details",
+  },
+
+  name: {
+    type: "string",
+    description: "Name of the project",
+  },
+
+  path: {
+    type: "string",
+    description: "Target directory path for the project",
+  },
+
+  type: {
+    type: "string",
+    choices: ["app", "addon", "library", "extension", "custom-element"],
+    description: "Type of project to generate",
+  },
+
+  confirm: {
+    type: "string",
+    choices: ["yes", "no"],
+    description: "Bypass target confirmation step",
+  },
+
+  layers: {
+    type: "string",
+    multiple: true,
+    description: "Layers to apply to the project (repeat for multiple layers)",
+  },
+
+  packageManager: {
+    type: "string",
+    choices: ["npm", "pnpm"],
+    description: "Package manager to configure for the project",
+  },
+
+  replaceOrUpdate: {
+    type: "string",
+    choices: ["replace", "update"],
+    description: "Strategy to use if target directory exists",
+  },
+
+  write: {
+    type: "string",
+    choices: ["yes", "no"],
+    description: "Confirm writing changes to disk",
   },
 });
 
-const { replaceOrUpdate, name, type, layers = [], packageManager, path, confirm, write } = values;
+/**
+ * This lightweight check is here because Node's `parseArgs` is in strict mode.
+ * If a user runs `npx ember.nvp --help` alongside invalid or unknown flags,
+ * standard strict parsing would throw a `TypeError (ERR_PARSE_ARGS_UNKNOWN_OPTION)`
+ * before reaching any help handler. Pre-checking raw arguments ensures `--help`
+ * always prints successfully regardless of invalid flags.
+ */
+const isHelpRequested = process.argv.slice(2).some((arg) => arg === "--help" || arg === "-h");
+if (isHelpRequested) {
+  printHelp(coreOptions, discoveredLayers);
+  process.exit(0);
+}
+
+/**
+ * Parse the core flags, plus one `--<layer>.<option>` flag per layer option.
+ *
+ * Every layer adds its flags, not only the selected ones,
+ * because layers are selected after parsing.
+ *
+ * Throws on an unknown flag, or on a value given to a boolean flag.
+ *
+ * @param {string[]} args
+ * @param {import('#types').DiscoveredLayer[]} layers
+ */
+export function parseCliArgs(args, layers) {
+  /** @type {Record<string, import("node:util").ParseArgsOptionDescriptor>} */
+  const options = { ...coreOptions };
+
+  for (const layer of layers) {
+    for (const [key, schema] of Object.entries(layer.options ?? {})) {
+      options[`${layer.name}.${key}`] = {
+        type: schema.type === "confirm" ? "boolean" : "string",
+        multiple: schema.type === "multiselect",
+      };
+    }
+  }
+
+  // allowNegative makes `--no-<layer>.<option>` turn a "confirm" option off
+  return parseArgs({ args, options, allowNegative: true }).values;
+}
+
+/** @type {ReturnType<typeof parseCliArgs>} */
+let values;
+
+try {
+  values = parseCliArgs(process.argv.slice(2), discoveredLayers);
+} catch (error) {
+  // parseArgs errors name the flag, so a stack trace adds nothing for the user
+  p.cancel(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}
+
+const typedValues =
+  /** @type {ReturnType<typeof parseArgs<{ options: typeof coreOptions }>>['values']} */ (values);
 
 export const answers = {
-  name,
-  type,
-  layers,
-  packageManager,
-  path,
-  confirm,
-  replaceOrUpdate,
-  write,
+  ...typedValues,
+  layers: typedValues.layers ?? [],
 };
 
+/**
+ * Extract layer options from parsed CLI values.
+ *
+ * Exits when a value does not pass the option's validation.
+ *
+ * @param {import('#types').DiscoveredLayer[]} layers
+ * @param {Record<string, any>} [parsedValues] Defaults to the parsed `process.argv`
+ * @returns {Record<string, Record<string, any>>}
+ */
+export function parseLayerOptionsFromParsedArgs(layers = [], parsedValues = values) {
+  /** @type {Record<string, Record<string, any>>} */
+  const result = {};
+
+  for (const layer of layers) {
+    if (!layer.options) continue;
+
+    for (const [optionKey, schema] of Object.entries(layer.options)) {
+      const flagKey = `${layer.name}.${optionKey}`;
+      const rawVal = parsedValues[flagKey];
+
+      if (rawVal === undefined) continue;
+
+      const validation = validateOption(
+        schema,
+        schema.type === "multiselect" ? splitCommas(rawVal) : rawVal,
+      );
+
+      if (!validation.ok) {
+        p.cancel(`Invalid CLI argument '--${flagKey}': ${validation.error}`);
+        process.exit(1);
+      }
+
+      (result[layer.name] ??= {})[optionKey] = validation.value;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * `--x.y a,b` means the same as `--x.y a --x.y b`
+ *
+ * @param {string[]} values
+ * @returns {string[]}
+ */
+function splitCommas(values) {
+  /** @type {string[]} */
+  const result = [];
+
+  for (const value of values) {
+    for (const part of value.split(",")) {
+      const trimmed = part.trim();
+
+      if (trimmed) result.push(trimmed);
+    }
+  }
+
+  return result;
+}
+
 /**
  *
  * @param {string} label

package/src/cli/generator.js

@@ -80,7 +80,8 @@ async function runLap(project) {
       continue;
     }
 
-    await layer.run(project);
+    const options = project.getLayerOptions(layer.name);
+    await layer.run(project, options);
   }
 
   await consolidateLintingScripts(project);