opened
hiranya911
username_0
So far we have been exporting all API declarations through `default-namespace.d.ts` in order to generate a single API report that includes all of our APIs. However, we do not want to export everything from the above file. Since it is the declaration of the top-level `admin` namespace, it should only export the direct members of `admin` such as `admin.initializeApp()` and `admin.auth`. There are also other technical reasons why we cannot export everything from this file. For example, both RTDB and Firestore modules export a member named `Query`. Trying to export both these types from the same file results in an error.

Fixing this means we have to change how we generate API reports, and adopt a one report per module entry point scheme. API Extractor [doesn't support](https://github.com/microsoft/rushstack/issues/1596) this natively yet, and therefore I'm implementing a simple script that generates separate API reports for each entry point. I declare the following map of entry points:

```js
const entryPoints = {
  'firebase-admin': './lib/default-namespace.d.ts',
  'firebase-admin/app': './lib/app/index.d.ts',
  'firebase-admin/auth': './lib/auth/index.d.ts',
  'firebase-admin/database': './lib/database/index.d.ts',
  'firebase-admin/instance-id': './lib/instance-id/index.d.ts',
};
```

Then I iterate over the map, invoking API Extractor on each entry point. Generated reports are added under the `etc/` directory.

While this results in a set of comprehensive API reports (while enabling us to only export the necessary elements from `default-namespace.d.ts`), there are also a few caveats:

1. The API report of the top-level `firebase-admin` module which contains all the namespaces like `admin.auth` and `admin.database`, ends up with a lot of `ae-forgotten-export` warnings. This is because we export type aliases from each of the namespaces, without directly exporting the alias target. For example `firebase-admin` exports the `admin.auth.UserRecord` type alias, but not what it points to. This gets reported as a warning in the generated report:

```
// Warning: (ae-forgotten-export) The symbol "UserRecord" needs to be exported by the entry point default-namespace.d.ts
```

2. Other service-level API reports emit an  `ae-forgotten-export` warnings for the `App` type which comes from a separate module outside the immediate entry point.

```
// Warning: (ae-forgotten-export) The symbol "App" needs to be exported by the entry point index.d.ts
```

Hopefully, we shall decommission the top-level `admin` namespace some day making the 1st issue irrelevant. 2nd issue is more of an annoyance at this point, and might get fixed if API Extractor starts supporting multiple entry points in the future.
chore: Generating separate API reports for module entry points
issue
created
hiranya911
username_0
Check the end of CI build logs to see the new script in action.
comment
created
hiranya911
username_0
@Feiyang1 adding you for a quick look as well. This is my current solution to the multiple entry points problem with API Extractor. I'm ignoring the whole documentation issue for now (I'm hoping we can continue to use Typedoc or use a custom API Documenter plugin for that). But this gets us to a point where we can generate API reports for each entry point.
comment