feat: warn when using the separate declaration option with a script output (#513)

Author: dsherret

mod.ts

@@ -88,7 +88,9 @@ export interface BuildOptions {
    *   the esm and script folders. This is the recommended option when publishing
    *   a dual ESM and script package to npm.
    * * `"separate"` - Emits declaration files to the `types` folder where both
-   *   the ESM and script code share the same type declarations.
+   *   the ESM and script code share the same type declarations. Deprecated,
+   *   because the shared declarations describe the ESM output, so they're not
+   *   correct for a CommonJS consumer. Use `"inline"` instead.
    * * `false` - Do not emit declaration files.
    * @default "inline"
    */
@@ -332,6 +334,17 @@ export async function build(options: BuildOptions): Promise<void> {
       ? "inline"
       : options.declaration ?? "inline",
   };
+  if (
+    options.declaration === "separate" && options.scriptModule !== false &&
+    options.esModule !== false
+  ) {
+    warn(
+      `The 'separate' declaration build option outputs the same type ` +
+        `declarations for the ESM and CommonJS/UMD output, but they describe ` +
+        `the ESM output. Use the default 'inline' option instead, which ` +
+        `outputs the declarations beside the code they describe.`,
+    );
+  }
   const cwd = Deno.cwd();
   // the declaration maps point at the `src` directory, so they're only useful
   // when it's written out and published alongside them

tests/integration.test.ts

@@ -239,6 +239,83 @@ pnpm-lock.yaml
   });
 });
 
+Deno.test("should warn when using separate declarations with a script output", async () => {
+  const warnings = await captureWarnings(() =>
+    runTest("test_project", {
+      entryPoints: ["mod.ts"],
+      outDir: "./npm",
+      declaration: "separate",
+      shims: {
+        deno: "dev",
+      },
+      test: false,
+      typeCheck: false,
+      skipNpmInstall: true,
+      package: {
+        name: "add",
+        version: "1.0.0",
+      },
+    })
+  );
+
+  assertStringIncludes(
+    warnings.join("\n"),
+    "The 'separate' declaration build option",
+  );
+});
+
+Deno.test("should not warn about separate declarations with a single output", async () => {
+  const warnings = await captureWarnings(() =>
+    runTest("test_project", {
+      entryPoints: ["mod.ts"],
+      outDir: "./npm",
+      declaration: "separate",
+      scriptModule: false,
+      shims: {
+        deno: "dev",
+      },
+      test: false,
+      typeCheck: false,
+      skipNpmInstall: true,
+      package: {
+        name: "add",
+        version: "1.0.0",
+      },
+    })
+  );
+
+  assertEquals(
+    warnings.some((w) => w.includes("The 'separate' declaration build option")),
+    false,
+  );
+});
+
+Deno.test("should not warn about separate declarations without an esm output", async () => {
+  const warnings = await captureWarnings(() =>
+    runTest("test_project", {
+      entryPoints: ["mod.ts"],
+      outDir: "./npm",
+      declaration: "separate",
+      esModule: false,
+      shims: {
+        deno: "dev",
+      },
+      test: false,
+      typeCheck: false,
+      skipNpmInstall: true,
+      package: {
+        name: "add",
+        version: "1.0.0",
+      },
+    })
+  );
+
+  assertEquals(
+    warnings.some((w) => w.includes("The 'separate' declaration build option")),
+    false,
+  );
+});
+
 Deno.test("should build umd module", async () => {
   await runTest("test_project", {
     entryPoints: ["mod.ts"],
@@ -1857,6 +1934,20 @@ function assertPreloadModuleOutput(output: Output) {
   assertEquals(filePaths.includes("test_preload"), false);
 }
 
+async function captureWarnings(action: () => Promise<void>) {
+  const warnings: string[] = [];
+  const originalWarn = console.warn;
+  console.warn = (...args: unknown[]) => {
+    warnings.push(args.join(" "));
+  };
+  try {
+    await action();
+  } finally {
+    console.warn = originalWarn;
+  }
+  return warnings;
+}
+
 async function captureLogs(action: () => Promise<void>) {
   const logs: string[] = [];
   const originalLog = console.log;