build: add CI check to ensure consistent exports for MDC packages (#20960)

Adds a new script that checks whether an MDC package exports the same set of
symbols as its non-MDC counterpart. Also fixes all of the failures.

Author: crisbeto

.circleci/config.yml

@@ -366,6 +366,7 @@ jobs:
       - run: yarn stylelint
       - run: yarn tslint
       - run: yarn -s ts-circular-deps:check
+      - run: yarn check-mdc-exports
 
       - *slack_notify_on_failure
       - *save_cache

package.json

@@ -46,7 +46,8 @@
     "integration-tests": "bazel test --test_tag_filters=-view-engine-only --build_tests_only -- //integration/... -//integration/size-test/...",
     "integration-tests:view-engine": "bazel test --test_tag_filters=view-engine-only --build_tests_only -- //integration/... -//integration/size-test/...",
     "integration-tests:size-test": "bazel test //integration/size-test/...",
-    "check-mdc-tests": "ts-node --project scripts/tsconfig.json scripts/check-mdc-tests.ts"
+    "check-mdc-tests": "ts-node --project scripts/tsconfig.json scripts/check-mdc-tests.ts",
+    "check-mdc-exports": "ts-node --project scripts/tsconfig.json scripts/check-mdc-exports.ts"
   },
   "version": "11.1.0-next.0",
   "dependencies": {

scripts/check-mdc-exports-config.ts

@@ -0,0 +1,65 @@
+export const config = {
+  // The MDC sidenav hasn't been implemented yet.
+  skippedPackages: ['mdc-sidenav'],
+  skippedExports: {
+    'mdc-chips': [
+      // These components haven't been implemented for MDC due to a different accessibility pattern.
+      'MatChipListChange',
+      'MatChipList'
+    ],
+    'mdc-autocomplete': [
+      // Private base classes that are only exported for MDC.
+      '_MatAutocompleteBase',
+      '_MatAutocompleteTriggerBase',
+      '_MatAutocompleteOriginBase'
+    ],
+    'mdc-core': [
+      // Private base classes that are only exported for MDC.
+      '_MatOptionBase',
+      '_MatOptgroupBase'
+    ],
+    'mdc-dialog': [
+      // Private base classes and utility function that are only exported for MDC.
+      '_MatDialogBase',
+      '_MatDialogContainerBase',
+      '_closeDialogVia',
+    ],
+    'mdc-input': [
+      // TODO: an MDC version of this directive has to be implemented.
+      'MatTextareaAutosize'
+    ],
+    'mdc-menu': [
+      // Private base class that is only exported for MDC.
+      '_MatMenuBase'
+    ],
+    'mdc-paginator': [
+      // Private base class that is only exported for MDC.
+      '_MatPaginatorBase'
+    ],
+    'mdc-radio': [
+      // Private base classes that are only exported for MDC.
+      '_MatRadioGroupBase',
+      '_MatRadioButtonBase',
+    ],
+    'mdc-select': [
+      // Private base class that is only exported for MDC.
+      '_MatSelectBase'
+    ],
+    'mdc-slide-toggle': [
+      // Private module used to provide some common functionality.
+      '_MatSlideToggleRequiredValidatorModule'
+    ],
+    'mdc-snack-bar': [
+      // Private interface used to ensure consistency for MDC package.
+      '_SnackBarContainer'
+    ],
+    'mdc-tabs': [
+      // Private base classes that are only exported for MDC.
+      '_MatTabBodyBase',
+      '_MatTabHeaderBase',
+      '_MatTabNavBase',
+      '_MatTabLinkBase',
+      '_MatTabGroupBase'
+    ]
+  }
+};

scripts/check-mdc-exports.ts

@@ -0,0 +1,92 @@
+import {join} from 'path';
+import {readdirSync, existsSync} from 'fs';
+import * as ts from 'typescript';
+import chalk from 'chalk';
+import {config} from './check-mdc-exports-config';
+
+// Script which ensures that a particular MDC package exports all of the same symbols as its
+// non-MDC counterparts. Only looks at symbol names, not their signatures. Exceptions
+// can be configured through the `check-mdc-exports-config.ts` file.
+
+let hasFailed = false;
+
+readdirSync(join(__dirname, '../src/material'), {withFileTypes: true})
+  .filter(entity => entity.isDirectory())
+  .map(entity => entity.name)
+  .filter(name => !config.skippedPackages.includes(`mdc-${name}`))
+  .filter(hasCorrespondingMdcPackage)
+  .forEach(name => {
+    const missingSymbols = getMissingSymbols(name, config.skippedExports[`mdc-${name}`] || []);
+
+    if (missingSymbols.length) {
+      console.log(chalk.redBright(`\nMissing symbols from mdc-${name}:`));
+      console.log(missingSymbols.join('\n'));
+      hasFailed = true;
+    }
+  });
+
+if (hasFailed) {
+  console.log(chalk.redBright(
+    '\nDetected one or more MDC packages that do not export the same set of symbols from\n' +
+    'public-api.ts as their non-MDC counterpart.\nEither implement the missing symbols or ' +
+    're-export them from the Material package,\nor add them to the `skippedExports` list in ' +
+    `scripts/check-mdc-exports-config.ts.`
+    ));
+  process.exit(1);
+} else {
+  console.log(chalk.green(
+    'All MDC packages export the same public API symbols as their non-MDC counterparts.'));
+  process.exit(0);
+}
+
+/**
+ * Gets the names of symbols that are present in a Material package,
+ * but not its MDC counterpart.
+ */
+function getMissingSymbols(name: string, skipped: string[]): string[] {
+  const mdcExports = getExports(`material-experimental/mdc-${name}`);
+  const materialExports = getExports(`material/${name}`);
+
+  if (!mdcExports.length) {
+    throw Error(`Could not resolve exports in mdc-${name}`);
+  }
+
+  if (!materialExports.length) {
+    throw Error(`Could not resolve exports in ${name}`);
+  }
+
+  return materialExports.filter(exportName => {
+    return !skipped.includes(exportName) && !mdcExports.includes(exportName);
+  });
+}
+
+/**
+ * Gets the name of the exported symbols from a particular package.
+ * Based on https://github.com/angular/angular/blob/master/tools/ts-api-guardian/lib/serializer.ts
+ */
+function getExports(name: string): string[] {
+  const entryPoint = join(__dirname, '../src', name, 'public-api.ts');
+  const program = ts.createProgram([entryPoint], {
+    // This is a bit faster than the default and seems to produce identical results.
+    moduleResolution: ts.ModuleResolutionKind.Classic
+  });
+  const sourceFile = program.getSourceFiles().find(f => f.fileName.endsWith('public-api.ts'))!;
+  const typeChecker = program.getTypeChecker();
+  const mainSymbol = typeChecker.getSymbolAtLocation(sourceFile);
+
+  return (mainSymbol ? (typeChecker.getExportsOfModule(mainSymbol) || []) : []).map(symbol => {
+    // tslint:disable-next-line:no-bitwise
+    if (symbol.flags & ts.SymbolFlags.Alias) {
+      const resolvedSymbol = typeChecker.getAliasedSymbol(symbol);
+      return (!resolvedSymbol.valueDeclaration && !resolvedSymbol.declarations) ?
+        symbol : resolvedSymbol;
+    } else {
+      return symbol;
+    }
+  }).map(symbol => symbol.name);
+}
+
+/** Checks whether a particular Material package has an MDC-based equivalent. */
+function hasCorrespondingMdcPackage(name: string): boolean {
+  return existsSync(join(__dirname, '../src/material-experimental', 'mdc-' + name));
+}

src/material-experimental/mdc-checkbox/public-api.ts

@@ -6,8 +6,6 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import {_MatCheckboxRequiredValidatorModule} from '@angular/material/checkbox';
-
 export * from './checkbox';
 export * from './module';
 
@@ -21,4 +19,7 @@ export {
    * @breaking-change 9.0.0
    */
   TransitionCheckState,
+  MAT_CHECKBOX_DEFAULT_OPTIONS_FACTORY,
+  MatCheckboxDefaultOptions,
+  MAT_CHECKBOX_DEFAULT_OPTIONS,
 } from '@angular/material/checkbox';

src/material-experimental/mdc-dialog/public-api.ts

@@ -19,4 +19,5 @@ export {
   throwMatDialogContentAlreadyAttachedError,
   DialogRole,
   DialogPosition,
+  MAT_DIALOG_SCROLL_STRATEGY_FACTORY
 } from '@angular/material/dialog';

src/material-experimental/mdc-form-field/public-api.ts

@@ -6,17 +6,21 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-export {
-  MAT_FORM_FIELD,
-  MatFormFieldControl,
-  getMatFormFieldDuplicatedHintError,
-  getMatFormFieldMissingControlError,
-} from '@angular/material/form-field';
-
 export * from './directives/label';
 export * from './directives/error';
 export * from './directives/hint';
 export * from './directives/prefix';
 export * from './directives/suffix';
 export * from './form-field';
 export * from './module';
+
+export {
+  MAT_FORM_FIELD,
+  MatFormFieldControl,
+  getMatFormFieldDuplicatedHintError,
+  getMatFormFieldMissingControlError,
+  getMatFormFieldPlaceholderConflictError,
+  _MAT_HINT,
+  MatPlaceholder,
+  matFormFieldAnimations,
+} from '@angular/material/form-field';

src/material-experimental/mdc-input/public-api.ts

@@ -6,6 +6,10 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-export {getMatInputUnsupportedTypeError, MAT_INPUT_VALUE_ACCESSOR} from '@angular/material/input';
 export {MatInput} from './input';
 export {MatInputModule} from './module';
+
+export {
+  getMatInputUnsupportedTypeError,
+  MAT_INPUT_VALUE_ACCESSOR,
+} from '@angular/material/input';

src/material-experimental/mdc-list/BUILD.bazel

@@ -29,6 +29,7 @@ ng_module(
         "//src/cdk/collections",
         "//src/material-experimental/mdc-core",
         "//src/material/divider",
+        "//src/material/list",
         "@npm//@angular/core",
         "@npm//@angular/forms",
         "@npm//@material/list",

src/material-experimental/mdc-list/public-api.ts

@@ -13,6 +13,11 @@ export * from './nav-list';
 export * from './selection-list';
 export * from './list-option';
 export * from './list-styling';
-
 export {MatListOptionCheckboxPosition} from './list-option-types';
 export {MatListOption} from './list-option';
+
+export {
+  MAT_LIST,
+  MAT_NAV_LIST,
+  MAT_SELECTION_LIST_VALUE_ACCESSOR,
+} from '@angular/material/list';

src/material-experimental/mdc-menu/public-api.ts

@@ -24,4 +24,5 @@ export {
   MenuPositionX,
   MenuPositionY,
   transformMenu,
+  MAT_MENU_CONTENT,
 } from '@angular/material/menu';

src/material-experimental/mdc-progress-spinner/public-api.ts

@@ -8,3 +8,9 @@
 
 export * from './progress-spinner';
 export * from './module';
+
+export {
+  MAT_PROGRESS_SPINNER_DEFAULT_OPTIONS,
+  MatProgressSpinnerDefaultOptions,
+  MAT_PROGRESS_SPINNER_DEFAULT_OPTIONS_FACTORY,
+} from '@angular/material/progress-spinner';

src/material-experimental/mdc-radio/public-api.ts

@@ -8,3 +8,8 @@
 
 export * from './radio';
 export * from './module';
+
+export {
+  MAT_RADIO_DEFAULT_OPTIONS_FACTORY,
+  MatRadioDefaultOptions,
+} from '@angular/material/radio';

src/material-experimental/mdc-slide-toggle/public-api.ts

@@ -9,3 +9,8 @@
 export * from './slide-toggle';
 export * from './slide-toggle-config';
 export * from './module';
+
+export {
+  MAT_SLIDE_TOGGLE_REQUIRED_VALIDATOR,
+  MatSlideToggleRequiredValidator,
+} from '@angular/material/slide-toggle';

src/material-experimental/mdc-snack-bar/public-api.ts

@@ -19,4 +19,9 @@ export {
   SimpleSnackBar,
   MAT_SNACK_BAR_DATA,
   MAT_SNACK_BAR_DEFAULT_OPTIONS,
+  MAT_SNACK_BAR_DEFAULT_OPTIONS_FACTORY,
+  MatSnackBarHorizontalPosition,
+  MatSnackBarVerticalPosition,
+  TextOnlySnackBar,
+  matSnackBarAnimations,
 } from '@angular/material/snack-bar';

src/material-experimental/mdc-tabs/public-api.ts

@@ -7,7 +7,7 @@
  */
 
 export * from './module';
-export {MatTabBodyPortal} from './tab-body';
+export {MatTabBodyPortal, MatTabBody} from './tab-body';
 export {MatTabContent} from './tab-content';
 export {MatTabLabel} from './tab-label';
 export {MatTabLabelWrapper} from './tab-label-wrapper';
@@ -28,4 +28,5 @@ export {
   MatTabsConfig,
   MAT_TABS_CONFIG,
   MAT_TAB_GROUP,
+  ScrollDirection,
 } from '@angular/material/tabs';