test(ivy): add global utils to the public_api_guard test (#27008)

This API is part of our public api surface and needs to be monitored by the public_api_guard.

I also had to go back and mark all of the exported functions with @publicApi jsdoc tag.

PR Close #27008

packages/core/src/render3/discovery_utils.ts

@@ -33,6 +33,8 @@ import {NodeInjector} from './view_engine_compatibility';
  *    the component instance is exists in a template.
  * If a directive instance is used then it will return the
  *    component that contains that directive in it's template.
+ *
+ * @publicApi
  */
 export function getComponent<T = {}>(target: {}): T|null {
   const context = loadContext(target) !;
@@ -60,6 +62,8 @@ export function getComponent<T = {}>(target: {}): T|null {
  *
  * This will only return a component instance of the DOM node
  * contains an instance of a component on it.
+ *
+ * @publicApi
  */
 export function getHostComponent<T = {}>(target: {}): T|null {
   const context = loadContext(target);
@@ -74,6 +78,8 @@ export function getHostComponent<T = {}>(target: {}): T|null {
 /**
  * Returns the `RootContext` instance that is associated with
  * the application where the target is situated.
+ *
+ * @publicApi
  */
 export function getRootContext(target: LViewData | {}): RootContext {
   const lViewData = Array.isArray(target) ? target : loadContext(target) !.lViewData;
@@ -84,6 +90,8 @@ export function getRootContext(target: LViewData | {}): RootContext {
 /**
  * Returns a list of all the components in the application
  * that are have been bootstrapped.
+ *
+ * @publicApi
  */
 export function getRootComponents(target: {}): any[] {
   return [...getRootContext(target).components];
@@ -92,6 +100,8 @@ export function getRootComponents(target: {}): any[] {
 /**
  * Returns the injector instance that is associated with
  * the element, component or directive.
+ *
+ * @publicApi
  */
 export function getInjector(target: {}): Injector {
   const context = loadContext(target);
@@ -103,6 +113,8 @@ export function getInjector(target: {}): Injector {
 /**
  * Returns a list of all the directives that are associated
  * with the underlying target element.
+ *
+ * @publicApi
  */
 export function getDirectives(target: {}): Array<{}> {
   const context = loadContext(target) !;
@@ -117,6 +129,8 @@ export function getDirectives(target: {}): Array<{}> {
 /**
  * Returns LContext associated with a target passed as an argument.
  * Throws if a given target doesn't have associated LContext.
+ *
+ * @publicApi
  */
 export function loadContext(target: {}): LContext {
   const context = getContext(target);
@@ -133,6 +147,8 @@ export function loadContext(target: {}): LContext {
  * reaching the root `LViewData`.
  *
  * @param componentOrView any component or view
+ *
+ * @publicApi
  */
 export function getRootView(componentOrView: LViewData | {}): LViewData {
   let lViewData: LViewData;
@@ -151,6 +167,8 @@ export function getRootView(componentOrView: LViewData | {}): LViewData {
 
 /**
  *  Retrieve map of local references (local reference name => element or directive instance).
+ *
+ * @publicApi
  */
 export function getLocalRefs(target: {}): {[key: string]: any} {
   const context = loadContext(target) !;

packages/core/src/render3/global_utils.ts

@@ -6,8 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 import {global} from '../util';
-import {getComponent, getDirectives, getHostComponent, getInjector, getRootComponents} from './discovery_utils';
-import {getPlayers} from './players';
+import {getComponent, getDirectives, getHostComponent, getInjector, getPlayers, getRootComponents} from './global_utils_api';
 
 /**
  * This file introduces series of globally accessible debug tools

packages/core/src/render3/global_utils_api.ts

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+/**
+ * @fileoverview
+ * This file is the index file collecting all of the symbols published on the global.ng namespace.
+ *
+ * The reason why this file/module is separate global_utils.ts file is that we use this file
+ * to generate a d.ts file containing all the published symbols that is then compared to the golden
+ * file in the public_api_guard test.
+ */
+
+export {getComponent, getDirectives, getHostComponent, getInjector, getRootComponents} from './discovery_utils';
+export {getPlayers} from './players';

packages/core/src/render3/players.ts

@@ -50,6 +50,8 @@ export function addPlayer(
  * This function will only return players that have been added to the ref instance using
  * `addPlayer` or any players that are active through any template styling bindings
  * (`[style]`, `[style.prop]`, `[class]` and `[class.name]`).
+ *
+ * @publicApi
  */
 export function getPlayers(ref: ComponentInstance | DirectiveInstance | HTMLElement): Player[] {
   const context = getContext(ref);

packages/core/test/render3/global_utils_spec.ts

@@ -7,8 +7,8 @@
  */
 import {getComponent, getDirectives, getHostComponent, getInjector, getRootComponents} from '../../src/render3/discovery_utils';
 import {GLOBAL_PUBLISH_EXPANDO_KEY, GlobalDevModeContainer, publishDefaultGlobalUtils, publishGlobalUtil} from '../../src/render3/global_utils';
-import {global} from '../../src/util';
 import {getPlayers} from '../../src/render3/players';
+import {global} from '../../src/util';
 
 describe('global utils', () => {
   describe('publishGlobalUtil', () => {

tools/public_api_guard/BUILD.bazel

@@ -1,3 +1,14 @@
+load("//tools/ts-api-guardian:index.bzl", "ts_api_guardian_test")
 load(":public_api_guard.bzl", "generate_targets")
 
-generate_targets(glob(["**/*.d.ts"]))
+generate_targets(glob(["*/**/*.d.ts"]))
+
+ts_api_guardian_test(
+    name = "ng_global_utils_api",
+    actual = "angular/packages/core/src/render3/global_utils_api.d.ts",
+    data = [
+        ":global_utils.d.ts",
+        "//packages/core",
+    ],
+    golden = "angular/tools/public_api_guard/global_utils.d.ts",
+)

tools/public_api_guard/global_utils.d.ts

@@ -0,0 +1,11 @@
+export declare function getComponent<T = {}>(target: {}): T | null;
+
+export declare function getDirectives(target: {}): Array<{}>;
+
+export declare function getHostComponent<T = {}>(target: {}): T | null;
+
+export declare function getInjector(target: {}): Injector;
+
+export declare function getPlayers(ref: ComponentInstance | DirectiveInstance | HTMLElement): Player[];
+
+export declare function getRootComponents(target: {}): any[];