Set up auth to use a separate d.ts file for docgen (#5354)

* Allow auth to use a separate d.ts file for docgen

* Update API reports

Co-authored-by: hsubox76 <[email protected]>

Author: hsubox76

common/api-review/auth.api.md

@@ -102,14 +102,14 @@ export class AuthCredential {
     protected constructor(
     providerId: string,
     signInMethod: string);
-    // Warning: (ae-forgotten-export) The symbol "AuthInternal" needs to be exported by the entry point index.doc.d.ts
-    // Warning: (ae-forgotten-export) The symbol "PhoneOrOauthTokenResponse" needs to be exported by the entry point index.doc.d.ts
+    // Warning: (ae-forgotten-export) The symbol "AuthInternal" needs to be exported by the entry point index.d.ts
+    // Warning: (ae-forgotten-export) The symbol "PhoneOrOauthTokenResponse" needs to be exported by the entry point index.d.ts
     //
     // @internal (undocumented)
     _getIdTokenResponse(_auth: AuthInternal): Promise<PhoneOrOauthTokenResponse>;
     // @internal (undocumented)
     _getReauthenticationResolver(_auth: AuthInternal): Promise<IdTokenResponse>;
-    // Warning: (ae-forgotten-export) The symbol "IdTokenResponse" needs to be exported by the entry point index.doc.d.ts
+    // Warning: (ae-forgotten-export) The symbol "IdTokenResponse" needs to be exported by the entry point index.d.ts
     //
     // @internal (undocumented)
     _linkToIdToken(_auth: AuthInternal, _idToken: string): Promise<IdTokenResponse>;
@@ -277,9 +277,6 @@ export function connectAuthEmulator(auth: Auth, url: string, options?: {
     disableWarnings: boolean;
 }): void;
 
-// @public
-export const cordovaPopupRedirectResolver: PopupRedirectResolver;
-
 // @public
 export function createUserWithEmailAndPassword(auth: Auth, email: string, password: string): Promise<UserCredential>;
 
@@ -343,7 +340,7 @@ export interface EmulatorConfig {
 
 export { ErrorFn }
 
-// Warning: (ae-forgotten-export) The symbol "BaseOAuthProvider" needs to be exported by the entry point index.doc.d.ts
+// Warning: (ae-forgotten-export) The symbol "BaseOAuthProvider" needs to be exported by the entry point index.d.ts
 //
 // @public
 export class FacebookAuthProvider extends BaseOAuthProvider {
@@ -485,7 +482,7 @@ export type NextOrObserver<T> = NextFn<T | null> | Observer<T | null>;
 export class OAuthCredential extends AuthCredential {
     accessToken?: string;
     static fromJSON(json: string | object): OAuthCredential | null;
-    // Warning: (ae-forgotten-export) The symbol "OAuthCredentialParams" needs to be exported by the entry point index.doc.d.ts
+    // Warning: (ae-forgotten-export) The symbol "OAuthCredentialParams" needs to be exported by the entry point index.d.ts
     //
     // @internal (undocumented)
     static _fromParams(params: OAuthCredentialParams): OAuthCredential;
@@ -564,7 +561,7 @@ export class PhoneAuthCredential extends AuthCredential {
     _getReauthenticationResolver(auth: AuthInternal): Promise<IdTokenResponse>;
     // @internal (undocumented)
     _linkToIdToken(auth: AuthInternal, idToken: string): Promise<IdTokenResponse>;
-    // Warning: (ae-forgotten-export) The symbol "SignInWithPhoneNumberRequest" needs to be exported by the entry point index.doc.d.ts
+    // Warning: (ae-forgotten-export) The symbol "SignInWithPhoneNumberRequest" needs to be exported by the entry point index.d.ts
     //
     // @internal (undocumented)
     _makeVerificationRequest(): SignInWithPhoneNumberRequest;
@@ -637,9 +634,6 @@ export interface ReactNativeAsyncStorage {
     setItem(key: string, value: string): Promise<void>;
 }
 
-// @public
-export const reactNativeLocalPersistence: Persistence;
-
 // @public
 export function reauthenticateWithCredential(user: User, credential: AuthCredential): Promise<UserCredential>;
 
@@ -658,13 +652,13 @@ export interface RecaptchaParameters {
     [key: string]: any;
 }
 
-// Warning: (ae-forgotten-export) The symbol "ApplicationVerifierInternal" needs to be exported by the entry point index.doc.d.ts
+// Warning: (ae-forgotten-export) The symbol "ApplicationVerifierInternal" needs to be exported by the entry point index.d.ts
 //
 // @public
 export class RecaptchaVerifier implements ApplicationVerifierInternal {
     constructor(containerOrId: HTMLElement | string, parameters: RecaptchaParameters, authExtern: Auth);
     clear(): void;
-    // Warning: (ae-forgotten-export) The symbol "ReCaptchaLoader" needs to be exported by the entry point index.doc.d.ts
+    // Warning: (ae-forgotten-export) The symbol "ReCaptchaLoader" needs to be exported by the entry point index.d.ts
     //
     // @internal (undocumented)
     readonly _recaptchaLoader: ReCaptchaLoader;
@@ -678,7 +672,7 @@ export class RecaptchaVerifier implements ApplicationVerifierInternal {
 // @public
 export function reload(user: User): Promise<void>;
 
-// Warning: (ae-forgotten-export) The symbol "FederatedAuthProvider" needs to be exported by the entry point index.doc.d.ts
+// Warning: (ae-forgotten-export) The symbol "FederatedAuthProvider" needs to be exported by the entry point index.d.ts
 //
 // @public
 export class SAMLAuthProvider extends FederatedAuthProvider {

packages/auth/api-extractor.json

@@ -1,7 +1,8 @@
 {
     "extends": "../../config/api-extractor.json",
-    // Point it to your entry point d.ts file. 
-    "mainEntryPointFilePath": "<projectFolder>/dist/esm5/index.doc.d.ts",
+    // If this path ever changes, make sure to change scripts/exp/docgen.ts
+    // accordingly.
+    "mainEntryPointFilePath": "<projectFolder>/dist/esm5/index.d.ts",
     "dtsRollup": {
         "enabled": true,
         "untrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>.d.ts",

scripts/exp/docgen.ts

@@ -38,6 +38,20 @@ async function generateDocs(forDevsite: boolean = false) {
   const outputFolder = forDevsite ? 'docs-devsite' : 'docs-exp';
   const command = forDevsite ? 'api-documenter-devsite' : 'api-documenter';
 
+  // Use a special d.ts file for auth for doc gen only.
+  const authApiConfigOriginal = fs.readFileSync(
+    `${projectRoot}/packages/auth/api-extractor.json`,
+    'utf8'
+  );
+  const authApiConfigModified = authApiConfigOriginal.replace(
+    `"mainEntryPointFilePath": "<projectFolder>/dist/esm5/index.d.ts"`,
+    `"mainEntryPointFilePath": "<projectFolder>/dist/esm5/index.doc.d.ts"`
+  );
+  fs.writeFileSync(
+    `${projectRoot}/packages/auth/api-extractor.json`,
+    authApiConfigModified
+  );
+
   await spawn('yarn', ['build'], {
     stdio: 'inherit'
   });
@@ -46,6 +60,12 @@ async function generateDocs(forDevsite: boolean = false) {
     stdio: 'inherit'
   });
 
+  // Restore original auth api-extractor.json contents.
+  fs.writeFileSync(
+    `${projectRoot}/packages/auth/api-extractor.json`,
+    authApiConfigOriginal
+  );
+
   if (!fs.existsSync(tmpDir)) {
     fs.mkdirSync(tmpDir);
   }