Enforce API Extractor error/none policy and tag internal APIs (#8653)

tnorling · web-flow · commit e63bd1abc20e · 2026-06-15T16:15:26.000-07:00
## Summary Configures API Extractor so that every message either **fails the build** (`error`) or is **silenced** (`none`) — no `warning`-level messages remain, and nothing extraneous is written into the committed `*.api.md` reports. This eliminates the line-number "footer" churn that previously rewrote the API reports on unrelated edits. ## Rule policy | Rule | Level | Rationale | |---|---|---| | `ae-incompatible-release-tags` | error | Real signal — a `@public` symbol leaking an `@internal` type. Fixed at source by tagging the internal helpers `@internal`. | | `ae-unresolved-link` | error | Broken `{@link}` references are doc bugs. | | `ae-unresolved-inheritdoc-*`, `ae-internal-mixed-release-tag` | error | Correctness signals (no current violations). | | `ae-forgotten-export` | none | Our public types are projections (`Partial<Omit<Base, …>>`) of internal base types. Exporting the base to satisfy this rule would place the **entire** base type under semver — including members the projection deliberately omits. The base types are already shipped and structurally reachable; only their *name* is intentionally withheld. | | `tsdoc-*`, `ae-missing-release-tag`, `ae-internal-missing-underscore` | none | Cosmetic / not enforced; these were the source of the report churn. | ## Source changes - Tag internal helper functions and types with `@internal` (resolves `ae-incompatible-release-tags` with no public-surface change). - Fix ambiguous `{@link AuthorityType}` → `{@link AuthorityType:type}`. - Mark `BrowserExperimentalOptions` `@public` (it is referenced by the public `Configuration.experimental` field). - Regenerate all API reports. The source edits are TSDoc-comment-only — no functional or runtime change. ## Validation - `build:all`, `lint`, `format:check`, `apiExtractor` pass for all affected packages. - Unit tests pass for msal-common and msal-browser. > Paired with the 1P PR on the matching branch `chore/apiextractor-warning-policy`.
diff --git a/api-extractor-base.json b/api-extractor-base.json
@@ -16,31 +16,54 @@
   "messages": {
     "compilerMessageReporting": {
       "default": {
-        "logLevel": "warning",
-        "addToApiReportFile": true
+        "logLevel": "error"
       }
     },
     "extractorMessageReporting": {
       "default": {
-        "logLevel": "warning"
+        "logLevel": "error"
+      },
+      "ae-undocumented": {
+        "logLevel": "none"
       },
       "ae-missing-release-tag": {
-        "logLevel": "warning",
-        "addToApiReportFile": true
+        "logLevel": "none"
       },
       "ae-setter-with-docs": {
-        "logLevel": "warning",
-        "addToApiReportFile": true
+        "logLevel": "none"
+      },
+      "ae-internal-missing-underscore": {
+        "logLevel": "none",
+        "addToApiReportFile": false
+      },
+      "ae-forgotten-export": {
+        "logLevel": "none",
+        "addToApiReportFile": false
+      },
+      "ae-internal-mixed-release-tag": {
+        "logLevel": "error",
+        "addToApiReportFile": false
+      },
+      "ae-unresolved-inheritdoc-reference": {
+        "logLevel": "error",
+        "addToApiReportFile": false
+      },
+      "ae-unresolved-inheritdoc-base": {
+        "logLevel": "error",
+        "addToApiReportFile": false
+      },
+      "ae-incompatible-release-tags": {
+        "logLevel": "error",
+        "addToApiReportFile": false
       },
       "ae-unresolved-link": {
-        "logLevel": "warning",
-        "addToApiReportFile": true
+        "logLevel": "error",
+        "addToApiReportFile": false
       }
     },
     "tsdocMessageReporting": {
       "default": {
-        "logLevel": "warning",
-        "addToApiReportFile": true
+        "logLevel": "none"
       }
     }
   }
diff --git a/change/@azure-msal-browser-ce659b58-78f6-4319-bdae-d1570841907a.json b/change/@azure-msal-browser-ce659b58-78f6-4319-bdae-d1570841907a.json
@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "Update API Extractor warning policy and tag internal APIs with @internal [#8653](https://github.com/AzureAD/microsoft-authentication-library-for-js/pull/8653)",
+  "packageName": "@azure/msal-browser",
+  "email": "thomas.norling@microsoft.com",
+  "dependentChangeType": "patch"
+}
diff --git a/change/@azure-msal-common-f0697ace-678f-4e07-854e-6dcc4a37b22a.json b/change/@azure-msal-common-f0697ace-678f-4e07-854e-6dcc4a37b22a.json
@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "Update API Extractor warning policy and tag internal APIs with @internal [#8653](https://github.com/AzureAD/microsoft-authentication-library-for-js/pull/8653)",
+  "packageName": "@azure/msal-common",
+  "email": "thomas.norling@microsoft.com",
+  "dependentChangeType": "patch"
+}
diff --git a/lib/msal-browser/apiReview/msal-browser.api.md b/lib/msal-browser/apiReview/msal-browser.api.md
diff --git a/lib/msal-browser/src/config/Configuration.ts b/lib/msal-browser/src/config/Configuration.ts
@@ -175,7 +175,11 @@ export type BrowserSystemOptions = SystemOptions & {
     serverTelemetryEnabled?: boolean;
 };
 
-/** @internal */
+/**
+ * Options for configuring experimental features. These features do not follow
+ * semver and may be changed or removed without a major version bump. Use with caution.
+ * @public
+ */
 export type BrowserExperimentalOptions = {
     /**
      * Enables iframe timeout telemetry experiment for silent iframe bridge monitoring.
diff --git a/lib/msal-browser/src/utils/BrowserUtils.ts b/lib/msal-browser/src/utils/BrowserUtils.ts
@@ -258,6 +258,7 @@ export interface WaitForBridgeRequest {
     state?: string;
 }
 
+/** @internal */
 export async function waitForBridgeResponse(
     timeoutMs: number,
     logger: Logger,
@@ -461,9 +462,10 @@ export function preflightCheck(initialized: boolean): void {
 }
 
 /**
- * Helper to validate app enviornment before making redirect request
+ * Helper to validate app environment before making redirect request
  * @param initialized
  * @param config
+ * @internal
  */
 export function redirectPreflightCheck(
     initialized: boolean,
diff --git a/lib/msal-common/apiReview/msal-common.api.md b/lib/msal-common/apiReview/msal-common.api.md
diff --git a/lib/msal-common/src/authority/Authority.ts b/lib/msal-common/src/authority/Authority.ts
@@ -126,7 +126,7 @@ export class Authority {
     }
 
     /**
-     * Get {@link AuthorityType}
+     * Get {@link AuthorityType:type}
      * @param authorityUri {@link IUri}
      * @private
      */
diff --git a/lib/msal-common/src/cache/interface/ICacheManager.ts b/lib/msal-common/src/cache/interface/ICacheManager.ts
@@ -16,6 +16,7 @@ import { RefreshTokenEntity } from "../entities/RefreshTokenEntity.js";
 import { AuthorityMetadataEntity } from "../entities/AuthorityMetadataEntity.js";
 import { StoreInCache } from "../../request/StoreInCache.js";
 
+/** @internal */
 export interface ICacheManager {
     /**
      * fetch the account entity from the platform cache
diff --git a/lib/msal-common/src/cache/utils/AccountEntityUtils.ts b/lib/msal-common/src/cache/utils/AccountEntityUtils.ts
@@ -28,6 +28,7 @@ import { AccountEntity } from "../entities/AccountEntity.js";
 
 /**
  * Generate Account Id key component as per the schema: <home_account_id>-<environment>
+ * @internal
  */
 export function generateAccountId(accountEntity: AccountEntity): string {
     const accountId: Array<string> = [
@@ -39,6 +40,7 @@ export function generateAccountId(accountEntity: AccountEntity): string {
 
 /**
  * Returns the AccountInfo interface for this account.
+ * @internal
  */
 export function getAccountInfo(accountEntity: AccountEntity): AccountInfo {
     const tenantProfiles = accountEntity.tenantProfiles || [];
@@ -78,6 +80,7 @@ export function getAccountInfo(accountEntity: AccountEntity): AccountInfo {
 
 /**
  * Returns true if the account entity is in single tenant format (outdated), false otherwise
+ * @internal
  */
 export function isSingleTenant(accountEntity: AccountEntity): boolean {
     return !accountEntity.tenantProfiles;
@@ -86,6 +89,7 @@ export function isSingleTenant(accountEntity: AccountEntity): boolean {
 /**
  * Build Account cache from IdToken, clientInfo and authority/policy. Associated with AAD.
  * @param accountDetails
+ * @internal
  */
 export function createAccountEntity(
     accountDetails: {
@@ -195,6 +199,7 @@ export function createAccountEntity(
  * @param cloudGraphHostName
  * @param msGraphHost
  * @returns
+ * @internal
  */
 export function createAccountEntityFromAccountInfo(
     accountInfo: AccountInfo,
@@ -275,6 +280,7 @@ export function generateHomeAccountId(
 /**
  * Validates an entity: checks for all expected params
  * @param entity
+ * @internal
  */
 export function isAccountEntity(entity: object): entity is AccountEntity {
     if (!entity) {
diff --git a/lib/msal-common/src/cache/utils/CacheHelpers.ts b/lib/msal-common/src/cache/utils/CacheHelpers.ts
@@ -342,6 +342,7 @@ export function generateAuthorityMetadataExpiresAt(): number {
     );
 }
 
+/** @internal */
 export function updateAuthorityEndpointMetadata(
     authorityMetadata: AuthorityMetadataEntity,
     updatedValues: OpenIdConfigResponse,
@@ -356,6 +357,7 @@ export function updateAuthorityEndpointMetadata(
     authorityMetadata.jwks_uri = updatedValues.jwks_uri;
 }
 
+/** @internal */
 export function updateCloudDiscoveryMetadata(
     authorityMetadata: AuthorityMetadataEntity,
     updatedValues: CloudDiscoveryMetadata,
@@ -369,6 +371,7 @@ export function updateCloudDiscoveryMetadata(
 
 /**
  * Returns whether or not the data needs to be refreshed
+ * @internal
  */
 export function isAuthorityMetadataExpired(
     metadata: AuthorityMetadataEntity
diff --git a/lib/msal-common/src/config/ClientConfiguration.ts b/lib/msal-common/src/config/ClientConfiguration.ts
@@ -56,6 +56,9 @@ export type ClientConfiguration = {
     serializableCache?: ISerializableTokenCache | null;
 };
 
+/**
+ * @internal
+ */
 export type CommonClientConfiguration = {
     authOptions: Required<AuthOptions>;
     systemOptions: Required<SystemOptions>;
@@ -208,6 +211,7 @@ const DEFAULT_TELEMETRY_OPTIONS: Required<TelemetryOptions> = {
  * @param Configuration
  *
  * @returns Configuration
+ * @internal
  */
 export function buildClientConfiguration({
     authOptions: userAuthOptions,
diff --git a/lib/msal-common/src/protocol/Authorize.ts b/lib/msal-common/src/protocol/Authorize.ts
@@ -34,6 +34,7 @@ import { ServerError } from "../error/ServerError.js";
  * @param logger
  * @param performanceClient
  * @returns
+ * @internal
  */
 export function getStandardAuthorizeRequestParameters(
     authOptions: AuthOptions,
@@ -272,6 +273,7 @@ export function getStandardAuthorizeRequestParameters(
  * @param authority
  * @param requestParameters
  * @returns
+ * @internal
  */
 export function getAuthorizeUrl(
     authority: Authority,
diff --git a/lib/msal-common/src/protocol/Token.ts b/lib/msal-common/src/protocol/Token.ts
@@ -108,6 +108,7 @@ export function createTokenQueryParameters(
  * @param queryString
  * @param headers
  * @param thumbprint
+ * @internal
  */
 export async function executePostToTokenEndpoint(
     tokenEndpoint: string,
@@ -154,6 +155,7 @@ export async function executePostToTokenEndpoint(
  * @param networkClient - Network module instance
  * @param logger - Logger instance
  * @param performanceClient - Performance client instance
+ * @internal
  */
 export async function sendPostRequest<
     T extends ServerAuthorizationTokenResponse
diff --git a/lib/msal-common/src/request/RequestParameterBuilder.ts b/lib/msal-common/src/request/RequestParameterBuilder.ts
@@ -591,6 +591,7 @@ export function addSshJwk(
 /**
  * add server telemetry fields
  * @param serverTelemetryManager
+ * @internal
  */
 export function addServerTelemetry(
     parameters: Map<string, string>,
diff --git a/lib/msal-common/src/response/ResponseHandler.ts b/lib/msal-common/src/response/ResponseHandler.ts
@@ -632,6 +632,7 @@ export class ResponseHandler {
     }
 }
 
+/** @internal */
 export function buildAccountToCache(
     cacheStorage: CacheManager,
     authority: Authority,
diff --git a/lib/msal-node/apiReview/msal-node.api.md b/lib/msal-node/apiReview/msal-node.api.md
@@ -140,15 +140,11 @@ export { ClientConfigurationError }
 
 export { ClientConfigurationErrorCodes }
 
-// Warning: (ae-forgotten-export) The symbol "CommonClientCredentialRequest" needs to be exported by the entry point index.d.ts
-//
 // @public
 export type ClientCredentialRequest = Partial<Omit<CommonClientCredentialRequest, "resourceRequestMethod" | "resourceRequestUri" | "clientAssertion" | "storeInCache">> & {
     clientAssertion?: string | ClientAssertionCallback;
 };
 
-// Warning: (ae-forgotten-export) The symbol "ClientApplication" needs to be exported by the entry point index.d.ts
-//
 // @public
 export class ConfidentialClientApplication extends ClientApplication implements IConfidentialClientApplication {
     constructor(configuration: Configuration);
@@ -193,8 +189,6 @@ class Deserializer {
     static deserializeRefreshTokens(refreshTokens: Record<string, SerializedRefreshTokenEntity>): RefreshTokenCache;
 }
 
-// Warning: (ae-forgotten-export) The symbol "CommonDeviceCodeRequest" needs to be exported by the entry point index.d.ts
-//
 // @public
 export type DeviceCodeRequest = Partial<Omit<CommonDeviceCodeRequest, "scopes" | "deviceCodeCallback" | "resourceRequestMethod" | "resourceRequestUri" | "storeInCache">> & {
     scopes: Array<string>;
@@ -408,16 +402,12 @@ export type NodeTelemetryOptions = {
     application?: ApplicationTelemetry;
 };
 
-// Warning: (ae-forgotten-export) The symbol "CommonOnBehalfOfRequest" needs to be exported by the entry point index.d.ts
-//
 // @public
 export type OnBehalfOfRequest = Partial<Omit<CommonOnBehalfOfRequest, "oboAssertion" | "scopes" | "resourceRequestMethod" | "resourceRequestUri" | "storeInCache">> & {
     oboAssertion: string;
     scopes: Array<string>;
 };
 
-// Warning: (ae-missing-release-tag) "PromptValue" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export const PromptValue: {
     LOGIN: string;
@@ -449,8 +439,6 @@ export type RefreshTokenRequest = Partial<Omit<CommonRefreshTokenRequest, "scope
     forceCache?: boolean;
 };
 
-// Warning: (ae-missing-release-tag) "ResponseMode" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export const ResponseMode: {
     readonly QUERY: "query";
@@ -548,7 +536,6 @@ export type SilentFlowRequest = Partial<Omit<CommonSilentFlowRequest, "account"
 
 // @public
 export class TokenCache implements ISerializableTokenCache, ITokenCache {
-    // Warning: (ae-forgotten-export) The symbol "NodeStorage" needs to be exported by the entry point index.d.ts
     constructor(storage: NodeStorage, logger: Logger, cachePlugin?: ICachePlugin);
     deserialize(cache: string): void;
     getAccountByHomeId(homeAccountId: string): Promise<AccountInfo | null>;
@@ -566,8 +553,6 @@ export class TokenCache implements ISerializableTokenCache, ITokenCache {
 
 export { TokenCacheContext }
 
-// Warning: (ae-forgotten-export) The symbol "CommonUsernamePasswordRequest" needs to be exported by the entry point index.d.ts
-//
 // @public
 export type UsernamePasswordRequest = Partial<Omit<CommonUsernamePasswordRequest, "scopes" | "resourceRequestMethod" | "resourceRequestUri" | "username" | "password" | "storeInCache">> & {
     scopes: Array<string>;
@@ -577,14 +562,7 @@ export type UsernamePasswordRequest = Partial<Omit<CommonUsernamePasswordRequest
 
 export { ValidCacheType }
 
-// Warning: (ae-missing-release-tag) "version" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export const version = "5.2.4";
 
-// Warnings were encountered during analysis:
-//
-// src/index.ts:8:12 - (tsdoc-characters-after-block-tag) The token "@azure" looks like a TSDoc tag but contains an invalid character "/"; if it is not a tag, use a backslash to escape the "@"
-// src/index.ts:8:4 - (tsdoc-undefined-tag) The TSDoc tag "@module" is not defined in this configuration
-
 ```
diff --git a/lib/msal-react/apiReview/msal-react.api.md b/lib/msal-react/apiReview/msal-react.api.md

Original file line number	Diff line number	Diff line change
`@@ -126,7 +126,7 @@ export class Authority {`
`126`	`126`	`}`
`127`	`127`
`128`	`128`	`/**`
`129`		`- * Get {@link AuthorityType}`
	`129`	`+ * Get {@link AuthorityType:type}`
`130`	`130`	`* @param authorityUri {@link IUri}`
`131`	`131`	`* @private`
`132`	`132`	`*/`