Add tooling to verify dependency chain

package.json

@@ -58,13 +58,17 @@
     "integration/*"
   ],
   "devDependencies": {
+    "@microsoft/api-documenter": "7.7.20",
+    "@microsoft/api-extractor": "7.7.13",
     "@types/chai": "4.2.11",
     "@types/chai-as-promised": "7.1.2",
     "@types/long": "4.0.1",
     "@types/mocha": "7.0.2",
     "@types/node": "12.12.37",
     "@types/sinon": "9.0.0",
     "@types/sinon-chai": "3.2.4",
+    "@types/tmp": "0.2.0",
+    "@types/yargs": "15.0.4",
     "@typescript-eslint/eslint-plugin": "2.30.0",
     "@typescript-eslint/eslint-plugin-tslint": "2.30.0",
     "@typescript-eslint/parser": "2.30.0",
@@ -132,9 +136,7 @@
     "typescript": "3.8.3",
     "watch": "1.0.2",
     "webpack": "4.43.0",
-    "yargs": "15.3.1",
-    "@microsoft/api-extractor": "7.7.13",
-    "@microsoft/api-documenter": "7.7.20"
+    "yargs": "15.3.1"
   },
   "husky": {
     "hooks": {

packages/firestore/exp/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export function foo(): string;
+export function bar(): string;

packages/firestore/exp/index.node.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export { foo, bar } from './src/api/foobar';

packages/firestore/exp/src/api/foobar.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export function foo(): string {
+  return bar();
+}
+
+export function bar(): string {
+  return 'bar';
+}

packages/firestore/exp/test/deps/dependencies.json

@@ -0,0 +1,15 @@
+{
+    "foo": {
+        "dependencies": [
+            "bar",
+            "foo"
+        ],
+        "sizeInBytes": 67
+    },
+    "bar": {
+        "dependencies": [
+            "bar"
+        ],
+        "sizeInBytes": 39
+    }
+}

packages/firestore/exp/test/deps/verify_dependencies.test.ts

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { expect } from 'chai';
+
+import { extractDependencies } from '../../../../../scripts/exp/extract-deps.helpers';
+
+import * as dependencies from './dependencies.json';
+import * as pkg from '../../../package.json';
+import { forEach } from '../../../src/util/obj';
+
+describe('Dependencies', () => {
+  forEach(dependencies, (api, { dependencies }) => {
+    it(api, () => {
+      return extractDependencies(api, pkg.exp).then(extractedDependencies => {
+        dependencies.sort();
+        expect(extractedDependencies).to.have.members(dependencies);
+      });
+    });
+  });
+});

packages/firestore/package.json

@@ -11,11 +11,16 @@
     "build": "rollup -c rollup.config.es2017.js && rollup -c rollup.config.es5.js",
     "build:deps": "lerna run --scope @firebase/'{app,firestore}' --include-dependencies build",
     "build:console": "node tools/console.build.js",
+    "build:exp": "rollup -c rollup.config.exp.js",
     "predev": "yarn prebuild",
     "dev": "rollup -c -w",
     "lint": "eslint -c .eslintrc.js '**/*.ts' --ignore-path '../../.gitignore'",
     "lint:fix": "eslint --fix -c .eslintrc.js '**/*.ts' --ignore-path '../../.gitignore'",
-    "prettier": "prettier --write '*.ts' '*.js' 'src/**/*.js' 'test/**/*.js' 'src/**/*.ts' 'test/**/*.ts'",
+    "prettier": "prettier --write '*.ts' '*.js' 'exp/**/*.ts' 'src/**/*.js' 'test/**/*.js' 'src/**/*.ts' 'test/**/*.ts'",
+    "pregendeps:exp": "yarn build:exp",
+    "gendeps:exp": "../../scripts/exp/extract-deps.sh --types ./exp/index.d.ts --bundle ./dist/exp/index.js --output ./exp/test/deps/dependencies.json",
+    "pretest:exp": "yarn build:exp",
+    "test:exp":  "TS_NODE_CACHE=NO TS_NODE_COMPILER_OPTIONS='{\"module\":\"commonjs\"}' nyc --reporter lcovonly -- mocha 'exp/test/**/*.test.ts' --file exp/index.node.ts --config ../../config/mocharc.node.js",
     "test": "run-s lint test:all",
     "test:ci": "node ../../scripts/run_tests_in_ci.js",
     "test:all": "run-p test:browser test:travis test:minified",
@@ -34,6 +39,7 @@
   "browser": "dist/index.cjs.js",
   "module": "dist/index.esm.js",
   "esm2017": "dist/index.esm2017.js",
+  "exp": "dist/exp/index.js",
   "license": "Apache-2.0",
   "files": [
     "dist",

packages/firestore/rollup.config.exp.js

@@ -0,0 +1,52 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import typescriptPlugin from 'rollup-plugin-typescript2';
+import typescript from 'typescript';
+
+import { resolveNodeExterns } from './rollup.shared';
+
+import pkg from './package.json';
+
+const defaultPlugins = [
+  typescriptPlugin({
+    typescript,
+    tsconfigOverride: {
+      compilerOptions: {
+        target: 'es2017'
+      }
+    },
+    clean: true
+  })
+];
+
+const nodeBuilds = [
+  {
+    input: './exp/index.node.ts',
+    output: {
+      file: pkg.exp,
+      format: 'es'
+    },
+    plugins: defaultPlugins,
+    external: resolveNodeExterns,
+    treeshake: {
+      tryCatchDeoptimization: false
+    }
+  }
+];
+
+export default [...nodeBuilds];

scripts/exp/extract-deps.helpers.ts

@@ -0,0 +1,111 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as tmp from 'tmp';
+import * as path from 'path';
+import * as fs from 'fs';
+import * as rollup from 'rollup';
+import * as terser from 'terser';
+import * as ts from 'typescript';
+
+/** Contains the dependencies and the size of their code for a single export. */
+export type ExportData = { dependencies: string[]; sizeInBytes: number };
+
+/**
+ * This functions builds a simple JS app that only depends on the provided
+ * export. It then uses Rollup to gather all top-level classes and functions
+ * that that the export depends on.
+ *
+ * @param exportName The name of the export to verify
+ * @param jsBundle The file name of the source bundle that contains the export
+ * @return A list of dependencies for the given export
+ */
+export async function extractDependencies(
+  exportName: string,
+  jsBundle: string
+): Promise<string[]> {
+  const { dependencies } = await extractDependenciesAndSize(
+    exportName,
+    jsBundle
+  );
+  return dependencies;
+}
+
+/**
+ * Helper for extractDependencies that extracts the dependencies and the size
+ * of the minified build.
+ */
+export async function extractDependenciesAndSize(
+  exportName: string,
+  jsBundle: string
+): Promise<ExportData> {
+  const input = tmp.fileSync().name + '.js';
+  const output = tmp.fileSync().name + '.js';
+
+  // JavaScript content that exports a single API from the bundle
+  const beforeContent = `export { ${exportName} } from '${path.resolve(
+    jsBundle
+  )}';`;
+  fs.writeFileSync(input, beforeContent);
+
+  // Run Rollup on the JavaScript above to produce a tree-shaken build
+  const bundle = await rollup.rollup({
+    input,
+    external: id => id.startsWith('@firebase/')
+  });
+  await bundle.write({ file: output, format: 'es' });
+
+  const dependencies = extractFunctionsAndClasses(output);
+  dependencies.sort();
+
+  // Extract size of minified build
+  const afterContent = fs.readFileSync(output, 'utf-8');
+  const { code } = terser.minify(afterContent, {
+    output: {
+      comments: false
+    },
+    mangle: false,
+    compress: false
+  });
+
+  fs.unlinkSync(input);
+  fs.unlinkSync(output);
+
+  return { dependencies, sizeInBytes: Buffer.byteLength(code!, 'utf-8') };
+}
+
+/**
+ * Extracts all top-level function and classes using the TypeScript compiler
+ * API.
+ */
+export function extractFunctionsAndClasses(jsFile: string): string[] {
+  const program = ts.createProgram([jsFile], { allowJs: true });
+  const sourceFile = program.getSourceFile(jsFile);
+  if (!sourceFile) {
+    throw new Error('Failed to parse file: ' + jsFile);
+  }
+
+  const exports: string[] = [];
+  ts.forEachChild(sourceFile, node => {
+    if (ts.isFunctionDeclaration(node)) {
+      exports.push(node.name!.text);
+    } else if (ts.isClassDeclaration(node)) {
+      exports.push(node.name!.text);
+    }
+  });
+  return exports;
+}

scripts/exp/extract-deps.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+
+# Copyright 2020 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# extract-deps --- Invokes extract-deps using TS_NODE
+
+set -o nounset
+set -o errexit
+
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+NPM_BIN_DIR="$(npm bin)"
+TSNODE="$NPM_BIN_DIR/ts-node"
+GENERATE_DEPS_JS="$DIR/extract-deps.ts"
+
+export TS_NODE_CACHE=NO 
+export TS_NODE_COMPILER_OPTIONS='{"module":"commonjs"}' 
+export TS_NODE_PROJECT="$DIR/../../config/tsconfig.base.json"
+
+$TSNODE $GENERATE_DEPS_JS "$@"