feat: warn when using the separate declaration option with a script output

The declarations describe the ESM output, so sharing them with the
CommonJS/UMD output isn't correct for a CommonJS consumer.

Closes #327

Author: dsherret

mod.ts

@@ -89,6 +89,9 @@ export interface BuildOptions {
    *   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.
+   *
+   *   @deprecated 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"
    */
@@ -321,6 +324,14 @@ export async function build(options: BuildOptions): Promise<void> {
       ? "inline"
       : options.declaration ?? "inline",
   };
+  if (options.declaration === "separate" && options.scriptModule !== 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,57 @@ 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 without a script 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("declaration build option")),
+    false,
+  );
+});
+
 Deno.test("should build umd module", async () => {
   await runTest("test_project", {
     entryPoints: ["mod.ts"],
@@ -1840,6 +1891,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;