feat(compiler): deprecate customResolveOptions config option (#5269)

deprecate the `nodeResolve#customResolveOptions` configuration option
in a Stencil configuration. this field is used to configure
`@rollup/plugin-node-resolve` when generating any non-documentation
output target artifacts. the contents of this option get propagated by
the rollup plugin to `resolve`, which does the actual resolution of
files in stencil's in-memory filesystem.

in newer versions of `@rollup/plugin-node-resolve`, this option has been
removed, which no option to override defaults (creating a separation of
concerns between the plugin and `resolve`). since stencil exposes this
configuration in its public api, we cannot remove it without causing a
breaking change (nor could we find a suitable way to reuse an existing
configuration).

this change is a prerequisite to upgrading `@rollup/plugin-node-resolve`.
we will not remove the configuration option/upgrade the plugin until
stencil v5. in the interim, we add a warning message at config
validation time to try to elicit feedback on this change

STENCIL-595: Update Rollup v2.X Infrastructure

Author: rwaskiewicz

src/compiler/config/test/validate-custom.spec.ts

@@ -26,6 +26,24 @@ describe('validateCustom', () => {
       },
     ];
     const { diagnostics } = validateConfig(userConfig, mockLoadConfigInit());
-    expect(diagnostics.length).toBe(1);
+    // TODO(STENCIL-1107): Decrement the right-hand side value from 2 to 1
+    expect(diagnostics.length).toBe(2);
+    // TODO(STENCIL-1107): Keep this assertion
+    expect(diagnostics[0]).toEqual({
+      header: 'Build Warn',
+      level: 'warn',
+      lines: [],
+      messageText: 'test warning',
+      type: 'build',
+    });
+    // TODO(STENCIL-1107): Remove this assertion
+    expect(diagnostics[1]).toEqual({
+      header: 'Build Warn',
+      level: 'warn',
+      lines: [],
+      messageText:
+        'nodeResolve.customResolveOptions is a deprecated option in a Stencil Configuration file. If you need this option, please open a new issue in the Stencil repository (https://github.com/ionic-team/stencil/issues/new/choose)',
+      type: 'build',
+    });
   });
 });

src/compiler/config/validate-config.ts

@@ -1,5 +1,5 @@
 import { createNodeLogger, createNodeSys } from '@sys-api-node';
-import { buildError, isBoolean, isNumber, isString, sortBy } from '@utils';
+import { buildError, buildWarn, isBoolean, isNumber, isString, sortBy } from '@utils';
 
 import {
   ConfigBundle,
@@ -265,6 +265,15 @@ export const validateConfig = (
     return arr;
   }, [] as RegExp[]);
 
+  // TODO(STENCIL-1107): Remove this check. It'll be unneeded (and raise a compilation error when we build Stencil) once
+  // this property is removed.
+  if (validatedConfig.nodeResolve?.customResolveOptions) {
+    const warn = buildWarn(diagnostics);
+    // this message is particularly long - let the underlying logger implementation take responsibility for breaking it
+    // up to fit in a terminal window
+    warn.messageText = `nodeResolve.customResolveOptions is a deprecated option in a Stencil Configuration file. If you need this option, please open a new issue in the Stencil repository (https://github.com/ionic-team/stencil/issues/new/choose)`;
+  }
+
   CACHED_VALIDATED_CONFIG = validatedConfig;
 
   return {

src/declarations/stencil-public-compiler.ts

@@ -1613,8 +1613,12 @@ export interface NodeResolveConfig {
   only?: Array<string | RegExp>;
   modulesOnly?: boolean;
 
+  // TODO(STENCIL-1107): Remove this field [BREAKING_CHANGE]
   /**
    * @see https://github.com/browserify/resolve#resolveid-opts-cb
+   * @deprecated the `customResolveOptions` field is no longer honored in future versions of
+   * `@rollup/plugin-node-resolve`. If you are currently using it, please open a new issue in the Stencil repo to
+   * describe your use case & provide input (https://github.com/ionic-team/stencil/issues/new/choose)
    */
   customResolveOptions?: {
     basedir?: string;

src/testing/mocks.ts

@@ -99,6 +99,8 @@ export function mockConfig(overrides: Partial<UnvalidatedConfig> = {}): Unvalida
     minifyJs: false,
     namespace: 'Testing',
     nodeResolve: {
+      // TODO(STENCIL-1107): Remove this field - it's currently overriding Stencil's default options to pass into
+      // the `@rollup/plugin-node-resolve` plugin.
       customResolveOptions: {},
     },
     outputTargets: null,