RHCLOUD-23014: Use API Extractor on distributable packages

.dockerignore

@@ -1,4 +1,5 @@
 /coverage
+/docs/generated
 /screenshots
 **/node_modules
 **/dist

.gitignore

@@ -1,3 +1,9 @@
+/coverage
+/docs/generated
+/screenshots
+**/node_modules
+**/dist
+
 # https://next.yarnpkg.com/getting-started/qa#which-files-should-be-gitignored
 .pnp.*
 .yarn/*
@@ -6,9 +12,3 @@
 !.yarn/releases
 !.yarn/sdks
 !.yarn/versions
-
-/coverage
-/screenshots
-**/node_modules
-**/dist
-**/.DS_Store

.vscode/settings.json

@@ -14,6 +14,13 @@
     "**/node_modules": true,
     "**/dist": true
   },
+  "files.associations": {
+    "**/api-extractor.json": "jsonc"
+  },
+
+  "eslint.options": {
+    "rulePaths": ["./packages/eslint-plugin-internal/src/runtime-rules"]
+  },
 
   // https://code.visualstudio.com/docs/languages/identifiers
   "[javascript]": {

api-extractor.json

@@ -0,0 +1,45 @@
+{
+  // Matches the end_of_line setting in .editorconfig
+  "newlineKind": "lf",
+
+  "dtsRollup": {
+    "enabled": true,
+    "untrimmedFilePath": "<projectFolder>/dist/index.d.ts"
+  },
+
+  "apiReport": {
+    "enabled": true,
+    "reportFolder": "reports",
+    "reportTempFolder": "<projectFolder>/dist/api"
+  },
+
+  "docModel": {
+    "enabled": true
+  },
+
+  // Avoid generating tsdoc-metadata.json
+  // https://github.com/microsoft/rushstack/pull/1628#issuecomment-553665782
+  "tsdocMetadata": {
+    "enabled": false
+  },
+
+  "messages": {
+    "extractorMessageReporting": {
+      // Avoid having to explicitly mark every exported API member with @public tag
+      "ae-missing-release-tag": {
+        "logLevel": "none"
+      },
+      // Avoid issues with TSDoc parser unable to process @link references
+      "ae-unresolved-link": {
+        "logLevel": "none"
+      }
+    },
+
+    "tsdocMessageReporting": {
+      // https://github.com/Microsoft/tsdoc/issues/19
+      "tsdoc-param-tag-with-invalid-name": {
+        "logLevel": "none"
+      }
+    }
+  }
+}

generate-api-docs.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+set -euo pipefail
+
+yarn install
+yarn build-libs
+
+mkdir -p docs/generated && rm -rf docs/generated/*
+
+shopt -s globstar
+cp packages/lib-*/dist/api/lib-*.api.json docs/generated
+
+yarn api-documenter markdown -i docs/generated -o docs/generated/api

package.json

@@ -15,15 +15,17 @@
     "test-e2e": "yarn workspace @monorepo/e2e-sample-app run test-e2e",
     "test-e2e-open": "yarn workspace @monorepo/e2e-sample-app run test-e2e-open",
     "test-e2e-ci": "start-server-and-test 'yarn run-samples' '9000|9001' 'yarn test-e2e'",
-    "eslint": "eslint --max-warnings 0 --ext .js,.jsx,.ts,.tsx",
-    "eslint-print-config": "eslint --print-config",
+    "eslint": "eslint --max-warnings 0 --ext .js,.jsx,.ts,.tsx --rulesdir ./packages/eslint-plugin-internal/src/runtime-rules",
+    "eslint-print-config": "yarn eslint --print-config",
     "jest": "TZ=UTC jest --passWithNoTests",
-    "storybook": "start-storybook -p 6006",
-    "build-storybook": "build-storybook"
+    "api-extractor": "api-extractor run --typescript-compiler-folder ./node_modules/typescript/lib",
+    "storybook": "start-storybook -p 6006"
   },
   "devDependencies": {
     "@babel/core": "^7.18.6",
     "@mdx-js/react": "^1.6.22",
+    "@microsoft/api-documenter": "^7.19.24",
+    "@microsoft/api-extractor": "^7.33.6",
     "@patternfly/react-core": "^4.202.16",
     "@patternfly/react-table": "^4.71.16",
     "@patternfly/react-virtualized-extension": "^4.53.2",
@@ -60,7 +62,6 @@
     "@typescript-eslint/parser": "^5.3.1",
     "babel-loader": "^8.2.5",
     "cypress": "^9.7.0",
-    "downlevel-dts": "^0.10.0",
     "eslint": "^7.32.0",
     "eslint-config-airbnb": "^19.0.0",
     "eslint-config-airbnb-base": "^15.0.0",
@@ -74,11 +75,13 @@
     "eslint-plugin-promise": "^5.1.1",
     "eslint-plugin-react": "^7.27.0",
     "eslint-plugin-react-hooks": "^4.3.0",
+    "find-up": "^5.0.0",
     "identity-obj-proxy": "^3.0.0",
     "jest": "^27.5.1",
     "jest-axe": "^6.0.0",
     "lodash": "^4.17.21",
     "lodash-es": "^4.17.21",
+    "minimatch": "^3.1.2",
     "prettier": "^2.4.1",
     "react": "^17.0.2",
     "react-dom": "^17.0.2",
@@ -91,7 +94,6 @@
     "redux-thunk": "^2.4.1",
     "rollup": "^2.61.1",
     "rollup-plugin-analyzer": "^4.0.0",
-    "rollup-plugin-dts": "^4.0.1",
     "rollup-plugin-import-css": "^3.0.3",
     "start-server-and-test": "^1.14.0",
     "storybook-addon-react-router-v6": "^0.1.14",

packages/common/rollup-configs.js

@@ -3,9 +3,7 @@ import commonjs from '@rollup/plugin-commonjs';
 import nodeResolve from '@rollup/plugin-node-resolve';
 import typescript from '@rollup/plugin-typescript';
 import analyzer from 'rollup-plugin-analyzer';
-import dts from 'rollup-plugin-dts';
 import css from 'rollup-plugin-import-css';
-import { replaceCode } from './rollup-plugins/replaceCode';
 import { writeJSONFile } from './rollup-plugins/writeJSONFile';
 
 // https://yarnpkg.com/advanced/lifecycle-scripts#environment-variables
@@ -52,36 +50,8 @@ const getBanner = ({ repository }, buildMetadata) => {
 /**
  * @param {import('type-fest').PackageJson} pkg
  */
-const getExternalModules = ({ dependencies, peerDependencies }) => {
-  const modules = new Set([
-    ...Object.keys(dependencies ?? {}),
-    ...Object.keys(peerDependencies ?? {}),
-  ]);
-
-  modules.add('lodash-es');
-  modules.delete('lodash');
-
-  return Array.from(modules);
-};
-
-/**
- * @param {import('type-fest').PackageJson} pkg
- */
-const getExternalModuleRegExps = (pkg) => {
-  const externalModules = getExternalModules(pkg);
-  return externalModules.map((module) => new RegExp(`^${module}(\\/.+)*$`));
-};
-
-/**
- * @param {string} fileName
- */
-const replaceLodashEsRequire = (fileName) =>
-  replaceCode({
-    fileName,
-    replacements: {
-      "require('lodash-es')": "require('lodash')",
-    },
-  });
+const getExternalModules = ({ dependencies, peerDependencies }) =>
+  Array.from(new Set([...Object.keys(dependencies ?? {}), ...Object.keys(peerDependencies ?? {})]));
 
 /**
  * Rollup configuration for generating the library `.js` bundle.
@@ -93,6 +63,7 @@ const replaceLodashEsRequire = (fileName) =>
  */
 export const tsLibConfig = (pkg, inputFile, format = 'esm') => {
   const buildMetadata = getBuildMetadata(pkg);
+  const externalModules = getExternalModules(pkg);
 
   return {
     input: inputFile,
@@ -101,7 +72,7 @@ export const tsLibConfig = (pkg, inputFile, format = 'esm') => {
       format,
       banner: getBanner(pkg, buildMetadata),
     },
-    external: getExternalModuleRegExps(pkg),
+    external: externalModules.map((m) => new RegExp(`^${m}(\\/.+)*$`)),
     plugins: [
       nodeResolve(),
       commonjs(),
@@ -113,9 +84,8 @@ export const tsLibConfig = (pkg, inputFile, format = 'esm') => {
         include: ['src/**/*', '../common/src/**/*'],
         noEmitOnError: true,
       }),
-      ...(format === 'cjs' ? [replaceLodashEsRequire('index.js')] : []),
       writeJSONFile({
-        fileName: 'build-meta.json',
+        fileName: 'build-metadata.json',
         value: buildMetadata,
       }),
       analyzer({
@@ -125,27 +95,3 @@ export const tsLibConfig = (pkg, inputFile, format = 'esm') => {
     ],
   };
 };
-
-/**
- * Rollup configuration for generating the library `.d.ts` bundle.
- *
- * @param {import('type-fest').PackageJson} pkg
- * @param {string} inputFile
- * @returns {import('rollup').RollupOptions}
- */
-export const dtsLibConfig = (pkg, inputFile) => ({
-  input: inputFile,
-  output: {
-    file: 'dist/index.d.ts',
-  },
-  external: [...getExternalModuleRegExps(pkg), /\.css$/],
-  plugins: [
-    dts({
-      respectExternal: true,
-    }),
-    analyzer({
-      summaryOnly: true,
-      root: rootDir,
-    }),
-  ],
-});

packages/common/src/index.ts

@@ -1,6 +1,5 @@
 export * from './errors/CustomError';
 export * from './errors/ErrorWithCause';
 export * from './types/common';
-export * from './types/fetch';
 export * from './utils/logger';
 export * from './utils/objects';

packages/common/src/types/common.ts

@@ -29,7 +29,7 @@ export type ReplaceProperties<T, R> = {
  *
  * Utility type, probably never a reason to export.
  */
-type Never<T> = {
+export type Never<T> = {
   [K in keyof T]?: never;
 };
 

packages/common/src/utils/logger.ts

@@ -1,12 +1,12 @@
 import * as _ from 'lodash-es';
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-type LogFunction = (message?: any, ...optionalParams: any[]) => void;
+export type LogFunction = (message?: any, ...optionalParams: any[]) => void;
 
 /**
  * Minimal logger interface.
  */
-type Logger = Record<'info' | 'warn' | 'error', LogFunction>;
+export type Logger = Record<'info' | 'warn' | 'error', LogFunction>;
 
 const isProdEnv = process.env.NODE_ENV === 'production';
 

packages/common/tsconfig-bases/lib-node-cjs.json

@@ -5,6 +5,7 @@
     "target": "es2021",
     "module": "commonjs",
     "moduleResolution": "node",
-    "declaration": true
+    "declaration": true,
+    "declarationMap": true
   }
 }

packages/common/tsconfig-bases/lib-react-esm.json

@@ -6,6 +6,7 @@
     "module": "esnext",
     "moduleResolution": "node",
     "declaration": true,
+    "declarationMap": true,
     "jsx": "react"
   }
 }

packages/eslint-plugin-internal/src/rules/all-bases.js

@@ -16,4 +16,23 @@ module.exports = {
 
   // Enforce a maximum number of classes per file
   'max-classes-per-file': 'off',
+
+  // This rule has inconsistent behavior and poor monorepo support, replaced by lib-restricted-external-imports
+  'import/no-extraneous-dependencies': 'off',
+
+  // Enforce imported external modules to be declared in dependencies or peerDependencies within the closest parent package.json
+  'lib-restricted-external-imports': [
+    'error',
+    [
+      {
+        includeFiles: 'packages/lib-core/src/**',
+        excludeFiles: '**/*.test.*',
+        excludeModules: ['@monorepo/common'],
+      },
+      {
+        includeFiles: 'packages/+(lib-extensions|lib-utils|lib-webpack)/src/**',
+        excludeFiles: '**/*.+(test|stories).*',
+      },
+    ],
+  ],
 };