build: add checks for public-api.ts formats (#25586)

* check that all exports from public-api.ts are  explicit exports
* check that all exported symbols contain 'legacy'

Author: wagnermaciel

scripts/check-public-api-formats.js

@@ -0,0 +1,99 @@
+const fs = require('fs');
+const path = require('path');
+const ts = require('typescript');
+const chalk = require('chalk');
+
+/** -------------------------------------------------------------------------------------------- */
+/** -------------------------------------- ERROR HANDLING -------------------------------------- */
+/** -------------------------------------------------------------------------------------------- */
+
+/** Stores all errors that are caught during execution. */
+const errors = [];
+
+/** Throws an error explaining that the given export node must be explicit. */
+function throwExplicitExportError(path, content, node) {
+  const invalidExport = content
+    .substring(node.jsDoc ? node.jsDoc[0].end : node.pos, node.end)
+    .trim();
+  errors.push(
+    chalk.red(
+      `ERROR ${errors.length + 1}:` +
+        `\n  File: ${path}` +
+        `\n  Line: "${invalidExport}"` +
+        `\n  Re-exports must be explicit. For example:` +
+        `\n    [x] export * from './foo';` +
+        `\n    [✓] export {MatFoo} from './foo';`,
+    ),
+  );
+}
+
+/** Throws an error explaining that the name(s) of given export node must contain "legacy". */
+function throwLegacyNamingError(path, node) {
+  const invalidSymbol = node.exportClause.elements
+    .map(n => n.name.escapedText)
+    .filter(n => !n.includes('legacy'))
+    .join('\n    * ');
+  errors.push(
+    chalk.red(
+      `ERROR ${errors.length + 1}:` +
+        `\n  File: ${path}` +
+        `\n  The following exported symbols do not contain 'legacy':` +
+        `\n    ${invalidSymbol}`,
+    ),
+  );
+}
+
+/** -------------------------------------------------------------------------------------------- */
+/** --------------------------------------- BEGIN SCRIPT --------------------------------------- */
+/** -------------------------------------------------------------------------------------------- */
+
+/** An array of the file paths of all public-api.ts files for legacy components. */
+const paths = fs
+  .readdirSync(path.join(path.dirname(__dirname), 'src/material'))
+  .filter(dir => dir.startsWith('legacy-'))
+  .filter(dir => dir !== 'legacy-prebuilt-themes' && dir !== 'legacy-core')
+  .flatMap(dir => {
+    const base = path.join(path.dirname(__dirname), 'src/material', dir);
+    return [path.join(base, 'public-api.ts'), path.join(base, 'testing/public-api.ts')];
+  });
+
+for (let i = 0; i < paths.length; i++) {
+  const content = fs.readFileSync(paths[i], 'utf8');
+  ts.createSourceFile(paths[i], content, ts.ScriptTarget.Latest).forEachChild(child => {
+    // todo: consider enforcing this for all public-api.ts files.
+    if (!ts.isExportDeclaration(child)) {
+      return;
+    }
+
+    // Do not allow wildcard forwarding of exports.
+    // E.g. `export * from './foo';` vs `export {Foo} from './foo';`.
+    if (!child.exportClause) {
+      throwExplicitExportError(paths[i], content, child);
+      return;
+    }
+
+    // Ensure all exports from public-api.ts files nested
+    // under src/legacy-* directory contain the word "legacy".
+    for (let j = 0; j < child.exportClause.elements.length; j++) {
+      if (!child.exportClause.elements[j].name.escapedText.toLowerCase().includes('legacy')) {
+        throwLegacyNamingError(paths[i], child);
+        return;
+      }
+    }
+  });
+}
+
+/** -------------------------------------------------------------------------------------------- */
+/** ------------------------------------- ERROR REPORTING -------------------------------------- */
+/** -------------------------------------------------------------------------------------------- */
+
+if (errors.length) {
+  const separator = chalk.red('\n-----------------------------------------------------\n');
+  console.log(
+    chalk.red(`\nPublic APIs check failed with ${errors.length} error(s)`),
+    separator,
+    errors.join(`${separator}`),
+    separator,
+  );
+  process.exitCode = 1;
+}