Merge pull request #8823 from backstage/freben/apireportz

🧹 Clean up API reports in ldap and msgraph catalog modules
2022-01-09 13:57:48 +01:00
parent 508b3ffb36 722681b1b1
commit 7f3894be1c
23 changed files with 225 additions and 168 deletions
@@ -0,0 +1,6 @@
+---
+'@backstage/plugin-catalog-backend-module-ldap': patch
+'@backstage/plugin-catalog-backend-module-msgraph': patch
+---
+
+Clean up API report
@@ -136,3 +136,6 @@ site

 # e2e tests
 cypress/cypress/*
+
+# Possible leftover from build:api-reports
+tsconfig.tmp.json
@@ -17,26 +17,26 @@ import { SearchEntry } from 'ldapjs';
 import { SearchOptions } from 'ldapjs';
 import { UserEntity } from '@backstage/catalog-model';

-// Warning: (ae-missing-release-tag) "defaultGroupTransformer" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
+export type BindConfig = {
+  dn: string;
+  secret: string;
+};
+
+// @public
 export function defaultGroupTransformer(
  vendor: LdapVendor,
  config: GroupConfig,
  entry: SearchEntry,
 ): Promise<GroupEntity | undefined>;

-// Warning: (ae-missing-release-tag) "defaultUserTransformer" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export function defaultUserTransformer(
  vendor: LdapVendor,
  config: UserConfig,
  entry: SearchEntry,
 ): Promise<UserEntity | undefined>;

-// Warning: (ae-missing-release-tag) "GroupConfig" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type GroupConfig = {
  dn: string;
@@ -57,12 +57,6 @@ export type GroupConfig = {
  };
 };

-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (tsdoc-undefined-tag) The TSDoc tag "@return" is not defined in this configuration
-// Warning: (ae-missing-release-tag) "GroupTransformer" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type GroupTransformer = (
  vendor: LdapVendor,
@@ -70,28 +64,18 @@ export type GroupTransformer = (
  group: SearchEntry,
 ) => Promise<GroupEntity | undefined>;

-// Warning: (ae-missing-release-tag) "LDAP_DN_ANNOTATION" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export const LDAP_DN_ANNOTATION = 'backstage.io/ldap-dn';

-// Warning: (ae-missing-release-tag) "LDAP_RDN_ANNOTATION" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export const LDAP_RDN_ANNOTATION = 'backstage.io/ldap-rdn';

-// Warning: (ae-missing-release-tag) "LDAP_UUID_ANNOTATION" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export const LDAP_UUID_ANNOTATION = 'backstage.io/ldap-uuid';

-// Warning: (ae-missing-release-tag) "LdapClient" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export class LdapClient {
  constructor(client: Client, logger: Logger_2);
-  // Warning: (ae-forgotten-export) The symbol "BindConfig" needs to be exported by the entry point index.d.ts
-  //
  // (undocumented)
  static create(
    logger: Logger_2,
@@ -100,22 +84,14 @@ export class LdapClient {
  ): Promise<LdapClient>;
  getRootDSE(): Promise<SearchEntry | undefined>;
  getVendor(): Promise<LdapVendor>;
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
  search(dn: string, options: SearchOptions): Promise<SearchEntry[]>;
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-  // Warning: (ae-forgotten-export) The symbol "SearchCallback" needs to be exported by the entry point index.d.ts
  searchStreaming(
    dn: string,
    options: SearchOptions,
-    f: SearchCallback,
+    f: (entry: SearchEntry) => void,
  ): Promise<void>;
 }

-// Warning: (ae-missing-release-tag) "LdapOrgEntityProvider" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export class LdapOrgEntityProvider implements EntityProvider {
  constructor(options: {
@@ -140,12 +116,9 @@ export class LdapOrgEntityProvider implements EntityProvider {
  ): LdapOrgEntityProvider;
  // (undocumented)
  getProviderName(): string;
-  // (undocumented)
  read(): Promise<void>;
 }

-// Warning: (ae-missing-release-tag) "LdapOrgReaderProcessor" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export class LdapOrgReaderProcessor implements CatalogProcessor {
  constructor(options: {
@@ -171,8 +144,6 @@ export class LdapOrgReaderProcessor implements CatalogProcessor {
  ): Promise<boolean>;
 }

-// Warning: (ae-missing-release-tag) "LdapProviderConfig" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type LdapProviderConfig = {
  target: string;
@@ -181,8 +152,6 @@ export type LdapProviderConfig = {
  groups: GroupConfig;
 };

-// Warning: (ae-missing-release-tag) "LdapVendor" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type LdapVendor = {
  dnAttributeName: string;
@@ -190,12 +159,6 @@ export type LdapVendor = {
  decodeStringAttribute: (entry: SearchEntry, name: string) => string[];
 };

-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "mapStringAttr" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function mapStringAttr(
  entry: SearchEntry,
@@ -204,18 +167,9 @@ export function mapStringAttr(
  setter: (value: string) => void,
 ): void;

-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "readLdapConfig" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function readLdapConfig(config: Config): LdapProviderConfig[];

-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "readLdapOrg" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function readLdapOrg(
  client: LdapClient,
@@ -231,8 +185,6 @@ export function readLdapOrg(
  groups: GroupEntity[];
 }>;

-// Warning: (ae-missing-release-tag) "UserConfig" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type UserConfig = {
  dn: string;
@@ -251,21 +203,10 @@ export type UserConfig = {
  };
 };

-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (tsdoc-undefined-tag) The TSDoc tag "@return" is not defined in this configuration
-// Warning: (ae-missing-release-tag) "UserTransformer" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type UserTransformer = (
  vendor: LdapVendor,
  config: UserConfig,
  user: SearchEntry,
 ) => Promise<UserEntity | undefined>;
-
-// Warnings were encountered during analysis:
-//
-// src/ldap/vendors.d.ts:17:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// src/ldap/vendors.d.ts:18:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
 ```
@@ -25,14 +25,12 @@ import {
  LdapVendor,
 } from './vendors';

-export interface SearchCallback {
-  (entry: SearchEntry): void;
-}
-
 /**
- * Basic wrapper for the ldapjs library.
+ * Basic wrapper for the `ldapjs` library.
 *
 * Helps out with promisifying calls, paging, binding etc.
+ *
+ * @public
 */
 export class LdapClient {
  private vendor: Promise<LdapVendor> | undefined;
@@ -75,8 +73,8 @@ export class LdapClient {
  /**
   * Performs an LDAP search operation.
   *
-   * @param dn The fully qualified base DN to search within
-   * @param options The search options
+   * @param dn - The fully qualified base DN to search within
+   * @param options - The search options
   */
  async search(dn: string, options: SearchOptions): Promise<SearchEntry[]> {
    try {
@@ -128,14 +126,14 @@ export class LdapClient {
  /**
   * Performs an LDAP search operation, calls a function on each entry to limit memory usage
   *
-   * @param dn The fully qualified base DN to search within
-   * @param options The search options
-   * @param f The callback to call on each search entry
+   * @param dn - The fully qualified base DN to search within
+   * @param options - The search options
+   * @param f - The callback to call on each search entry
   */
  async searchStreaming(
    dn: string,
    options: SearchOptions,
-    f: SearchCallback,
+    f: (entry: SearchEntry) => void,
  ): Promise<void> {
    try {
      return await new Promise<void>((resolve, reject) => {
@@ -23,6 +23,8 @@ import { trimEnd } from 'lodash';

 /**
 * The configuration parameters for a single LDAP provider.
+ *
+ * @public
 */
 export type LdapProviderConfig = {
  // The prefix of the target that this matches on, e.g.
@@ -39,6 +41,8 @@ export type LdapProviderConfig = {

 /**
 * The settings to use for the a command.
+ *
+ * @public
 */
 export type BindConfig = {
  // The DN of the user to auth as, e.g.
@@ -50,6 +54,8 @@ export type BindConfig = {

 /**
 * The settings that govern the reading and interpretation of users.
+ *
+ * @public
 */
 export type UserConfig = {
  // The DN under which users are stored.
@@ -88,6 +94,8 @@ export type UserConfig = {

 /**
 * The settings that govern the reading and interpretation of groups.
+ *
+ * @public
 */
 export type GroupConfig = {
  // The DN under which groups are stored.
@@ -163,7 +171,9 @@ const defaultConfig = {
 /**
 * Parses configuration.
 *
- * @param config The root of the LDAP config hierarchy
+ * @param config - The root of the LDAP config hierarchy
+ *
+ * @public
 */
 export function readLdapConfig(config: Config): LdapProviderConfig[] {
  function freeze<T>(data: T): T {
@@ -22,6 +22,8 @@
 * example, for an item with the fully qualified DN
 * uid=john,ou=people,ou=spotify,dc=spotify,dc=net the generated entity would
 * have this annotation, with the value "john".
+ *
+ * @public
 */
 export const LDAP_RDN_ANNOTATION = 'backstage.io/ldap-rdn';

@@ -33,6 +35,8 @@ export const LDAP_RDN_ANNOTATION = 'backstage.io/ldap-rdn';
 * for an item with the DN uid=john,ou=people,ou=spotify,dc=spotify,dc=net the
 * generated entity would have this annotation, with that full string as its
 * value.
+ *
+ * @public
 */
 export const LDAP_DN_ANNOTATION = 'backstage.io/ldap-dn';

@@ -44,5 +48,7 @@ export const LDAP_DN_ANNOTATION = 'backstage.io/ldap-dn';
 * for an item with the UUID 76ef928a-b251-1037-9840-d78227f36a7e, the
 * generated entity would have this annotation, with that full string as its
 * value.
+ *
+ * @public
 */
 export const LDAP_UUID_ANNOTATION = 'backstage.io/ldap-uuid';
@@ -17,7 +17,12 @@
 export { LdapClient } from './client';
 export { mapStringAttr } from './util';
 export { readLdapConfig } from './config';
-export type { LdapProviderConfig, GroupConfig, UserConfig } from './config';
+export type {
+  LdapProviderConfig,
+  GroupConfig,
+  UserConfig,
+  BindConfig,
+} from './config';
 export type { LdapVendor } from './vendors';
 export {
  LDAP_DN_ANNOTATION,
@@ -31,6 +31,12 @@ import { Logger } from 'winston';
 import { GroupTransformer, UserTransformer } from './types';
 import { mapStringAttr } from './util';

+/**
+ * The default implementation of the transformation from an LDAP entry to a
+ * User entity.
+ *
+ * @public
+ */
 export async function defaultUserTransformer(
  vendor: LdapVendor,
  config: UserConfig,
@@ -88,9 +94,9 @@ export async function defaultUserTransformer(
 /**
 * Reads users out of an LDAP provider.
 *
- * @param client The LDAP client
- * @param config The user data configuration
- * @param opts
+ * @param client - The LDAP client
+ * @param config - The user data configuration
+ * @param opts - Additional options
 */
 export async function readLdapUsers(
  client: LdapClient,
@@ -125,6 +131,12 @@ export async function readLdapUsers(
  return { users: entities, userMemberOf };
 }

+/**
+ * The default implementation of the transformation from an LDAP entry to a
+ * Group entity.
+ *
+ * @public
+ */
 export async function defaultGroupTransformer(
  vendor: LdapVendor,
  config: GroupConfig,
@@ -185,9 +197,9 @@ export async function defaultGroupTransformer(
 /**
 * Reads groups out of an LDAP provider.
 *
- * @param client The LDAP client
- * @param config The group data configuration
- * @param opts
+ * @param client - The LDAP client
+ * @param config - The group data configuration
+ * @param opts - Additional options
 */
 export async function readLdapGroups(
  client: LdapClient,
@@ -240,13 +252,12 @@ export async function readLdapGroups(
 /**
 * Reads users and groups out of an LDAP provider.
 *
- * Invokes the above "raw" read functions and stitches together the results
- * with all relations etc filled in.
+ * @param client - The LDAP client
+ * @param userConfig - The user data configuration
+ * @param groupConfig - The group data configuration
+ * @param options - Additional options
 *
- * @param client The LDAP client
- * @param userConfig The user data configuration
- * @param groupConfig The group data configuration
- * @param options
+ * @public
 */
 export async function readLdapOrg(
  client: LdapClient,
@@ -261,6 +272,9 @@ export async function readLdapOrg(
  users: UserEntity[];
  groups: GroupEntity[];
 }> {
+  // Invokes the above "raw" read functions and stitches together the results
+  // with all relations etc filled in.
+
  const { users, userMemberOf } = await readLdapUsers(client, userConfig, {
    transformer: options?.userTransformer,
  });
@@ -321,14 +335,14 @@ function ensureItems(
 * Takes groups and entities with empty relations, and fills in the various
 * relations that were returned by the readers, and forms the org hierarchy.
 *
- * @param groups Group entities with empty relations; modified in place
- * @param users User entities with empty relations; modified in place
- * @param userMemberOf For a user DN, the set of group DNs or UUIDs that the
- *                     user is a member of
- * @param groupMemberOf For a group DN, the set of group DNs or UUIDs that the
- *                      group is a member of (parents in the hierarchy)
- * @param groupMember For a group DN, the set of group DNs or UUIDs that are
- *                    members of the group (children in the hierarchy)
+ * @param groups - Group entities with empty relations; modified in place
+ * @param users - User entities with empty relations; modified in place
+ * @param userMemberOf - For a user DN, the set of group DNs or UUIDs that the
+ *        user is a member of
+ * @param groupMemberOf - For a group DN, the set of group DNs or UUIDs that
+ *        the group is a member of (parents in the hierarchy)
+ * @param groupMember - For a group DN, the set of group DNs or UUIDs that are
+ *        members of the group (children in the hierarchy)
 */
 export function resolveRelations(
  groups: GroupEntity[],
@@ -21,10 +21,15 @@ import { GroupConfig, UserConfig } from './config';
 /**
 * Customize the ingested User entity
 *
- * @param vendor The LDAP vendor that can be used to find and decode vendor specific attributes
- * @param config The User specific config used by the default transformer.
- * @param user The found LDAP entry in its source format. This is the entry that you want to transform
- * @return A `UserEntity` or `undefined` if you want to ignore the found user for being ingested by the catalog
+ * @param vendor - The LDAP vendor that can be used to find and decode vendor
+ *        specific attributes
+ * @param config - The User specific config used by the default transformer.
+ * @param user - The found LDAP entry in its source format. This is the entry
+ *        that you want to transform
+ * @returns A `UserEntity` or `undefined` if you want to ignore the found user
+ *          for being ingested by the catalog
+ *
+ * @public
 */
 export type UserTransformer = (
  vendor: LdapVendor,
@@ -35,10 +40,15 @@ export type UserTransformer = (
 /**
 * Customize the ingested Group entity
 *
- * @param vendor The LDAP vendor that can be used to find and decode vendor specific attributes
- * @param config The Group specific config used by the default transformer.
- * @param group The found LDAP entry in its source format. This is the entry that you want to transform
- * @return A `GroupEntity` or `undefined` if you want to ignore the found group for being ingested by the catalog
+ * @param vendor - The LDAP vendor that can be used to find and decode vendor
+ *        specific attributes
+ * @param config - The Group specific config used by the default transformer.
+ * @param group - The found LDAP entry in its source format. This is the entry
+ *        that you want to transform
+ * @returns A `GroupEntity` or `undefined` if you want to ignore the found group
+ *          for being ingested by the catalog
+ *
+ * @public
 */
 export type GroupTransformer = (
  vendor: LdapVendor,
@@ -20,19 +20,25 @@ import { LdapVendor } from './vendors';
 /**
 * Builds a string form of an LDAP Error structure.
 *
- * @param error The error
+ * @param error - The error
 */
 export function errorString(error: LDAPError) {
  return `${error.code} ${error.name}: ${error.message}`;
 }

 /**
- * Maps a single-valued attribute to a consumer
+ * Maps a single-valued attribute to a consumer.
 *
- * @param entry The LDAP source entry
- * @param vendor The LDAP vendor
- * @param attributeName The source attribute to map. If the attribute is undefined the mapping will be silently ignored.
- * @param setter The function to be called with the decoded attribute from the source entry
+ * This helper can be useful when implementing a user or group transformer.
+ *
+ * @param entry - The LDAP source entry
+ * @param vendor - The LDAP vendor
+ * @param attributeName - The source attribute to map. If the attribute is
+ *        undefined the mapping will be silently ignored.
+ * @param setter - The function to be called with the decoded attribute from the
+ *        source entry
+ *
+ * @public
 */
 export function mapStringAttr(
  entry: SearchEntry,
@@ -18,6 +18,8 @@ import { SearchEntry } from 'ldapjs';

 /**
 * An LDAP Vendor handles unique nuances between different vendors.
+ *
+ * @public
 */
 export type LdapVendor = {
  /**
@@ -31,8 +33,8 @@ export type LdapVendor = {
  /**
   * Decode ldap entry values for a given attribute name to their string representation.
   *
-   * @param entry The ldap entry
-   * @param name The attribute to decode
+   * @param entry - The ldap entry
+   * @param name - The attribute to decode
   */
  decodeStringAttribute: (entry: SearchEntry, name: string) => string[];
 };
@@ -39,6 +39,13 @@ import {
 /**
 * Reads user and group entries out of an LDAP service, and provides them as
 * User and Group entities for the catalog.
+ *
+ * @remarks
+ *
+ * Add an instance of this class to your catalog builder, and then periodically
+ * call the {@link LdapOrgEntityProvider.read} method.
+ *
+ * @public
 */
 export class LdapOrgEntityProvider implements EntityProvider {
  private connection?: EntityProviderConnection;
@@ -113,14 +120,20 @@ export class LdapOrgEntityProvider implements EntityProvider {
    },
  ) {}

+  /** {@inheritdoc @backstage/plugin-catalog-backend#EntityProvider.getProviderName} */
  getProviderName() {
    return `LdapOrgEntityProvider:${this.options.id}`;
  }

+  /** {@inheritdoc @backstage/plugin-catalog-backend#EntityProvider.connect} */
  async connect(connection: EntityProviderConnection) {
    this.connection = connection;
  }

+  /**
+   * Runs one complete ingestion loop. Call this method regularly at some
+   * appropriate cadence.
+   */
  async read() {
    if (!this.connection) {
      throw new Error('Not initialized');
@@ -33,6 +33,8 @@ import {

 /**
 * Extracts teams and users out of an LDAP server.
+ *
+ * @public
 */
 export class LdapOrgReaderProcessor implements CatalogProcessor {
  private readonly providers: LdapProviderConfig[];
@@ -16,51 +16,37 @@ import * as msal from '@azure/msal-node';
 import { Response as Response_2 } from 'node-fetch';
 import { UserEntity } from '@backstage/catalog-model';

-// Warning: (ae-missing-release-tag) "defaultGroupTransformer" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export function defaultGroupTransformer(
  group: MicrosoftGraph.Group,
  groupPhoto?: string,
 ): Promise<GroupEntity | undefined>;

-// Warning: (ae-missing-release-tag) "defaultOrganizationTransformer" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export function defaultOrganizationTransformer(
  organization: MicrosoftGraph.Organization,
 ): Promise<GroupEntity | undefined>;

-// Warning: (ae-missing-release-tag) "defaultUserTransformer" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export function defaultUserTransformer(
  user: MicrosoftGraph.User,
  userPhoto?: string,
 ): Promise<UserEntity | undefined>;

-// Warning: (ae-missing-release-tag) "GroupTransformer" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type GroupTransformer = (
  group: MicrosoftGraph.Group,
  groupPhoto?: string,
 ) => Promise<GroupEntity | undefined>;

-// Warning: (ae-missing-release-tag) "MICROSOFT_GRAPH_GROUP_ID_ANNOTATION" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export const MICROSOFT_GRAPH_GROUP_ID_ANNOTATION =
  'graph.microsoft.com/group-id';

-// Warning: (ae-missing-release-tag) "MICROSOFT_GRAPH_TENANT_ID_ANNOTATION" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export const MICROSOFT_GRAPH_TENANT_ID_ANNOTATION =
  'graph.microsoft.com/tenant-id';

-// Warning: (ae-missing-release-tag) "MICROSOFT_GRAPH_USER_ID_ANNOTATION" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export const MICROSOFT_GRAPH_USER_ID_ANNOTATION = 'graph.microsoft.com/user-id';

@@ -76,7 +62,6 @@ export class MicrosoftGraphClient {
    groupId: string,
    maxSize: number,
  ): Promise<string | undefined>;
-  // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@backstage/plugin-catalog-backend-module-msgraph" does not have an export "ODataQuery"
  getGroups(query?: ODataQuery): AsyncIterable<MicrosoftGraph.Group>;
  getOrganization(tenantId: string): Promise<MicrosoftGraph.Organization>;
  // (undocumented)
@@ -86,18 +71,12 @@ export class MicrosoftGraphClient {
    maxSize: number,
  ): Promise<string | undefined>;
  getUserProfile(userId: string): Promise<MicrosoftGraph.User>;
-  // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@backstage/plugin-catalog-backend-module-msgraph" does not have an export "ODataQuery"
  getUsers(query?: ODataQuery): AsyncIterable<MicrosoftGraph.User>;
-  // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@backstage/plugin-catalog-backend-module-msgraph" does not have an export "ODataQuery"
  requestApi(path: string, query?: ODataQuery): Promise<Response_2>;
-  // Warning: (ae-forgotten-export) The symbol "ODataQuery" needs to be exported by the entry point index.d.ts
-  // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@backstage/plugin-catalog-backend-module-msgraph" does not have an export "ODataQuery"
  requestCollection<T>(path: string, query?: ODataQuery): AsyncIterable<T>;
  requestRaw(url: string): Promise<Response_2>;
 }

-// Warning: (ae-missing-release-tag) "MicrosoftGraphOrgEntityProvider" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export class MicrosoftGraphOrgEntityProvider implements EntityProvider {
  constructor(options: {
@@ -124,12 +103,9 @@ export class MicrosoftGraphOrgEntityProvider implements EntityProvider {
  ): MicrosoftGraphOrgEntityProvider;
  // (undocumented)
  getProviderName(): string;
-  // (undocumented)
  read(): Promise<void>;
 }

-// Warning: (ae-missing-release-tag) "MicrosoftGraphOrgReaderProcessor" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export class MicrosoftGraphOrgReaderProcessor implements CatalogProcessor {
  constructor(options: {
@@ -157,8 +133,6 @@ export class MicrosoftGraphOrgReaderProcessor implements CatalogProcessor {
  ): Promise<boolean>;
 }

-// Warning: (ae-missing-release-tag) "MicrosoftGraphProviderConfig" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type MicrosoftGraphProviderConfig = {
  target: string;
@@ -171,28 +145,27 @@ export type MicrosoftGraphProviderConfig = {
  groupFilter?: string;
 };

-// Warning: (ae-missing-release-tag) "normalizeEntityName" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export function normalizeEntityName(name: string): string;

-// Warning: (ae-missing-release-tag) "OrganizationTransformer" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
+export type ODataQuery = {
+  filter?: string;
+  expand?: string[];
+  select?: string[];
+};
+
+// @public
 export type OrganizationTransformer = (
  organization: MicrosoftGraph.Organization,
 ) => Promise<GroupEntity | undefined>;

-// Warning: (ae-missing-release-tag) "readMicrosoftGraphConfig" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export function readMicrosoftGraphConfig(
  config: Config,
 ): MicrosoftGraphProviderConfig[];

-// Warning: (ae-missing-release-tag) "readMicrosoftGraphOrg" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export function readMicrosoftGraphOrg(
  client: MicrosoftGraphClient,
  tenantId: string,
@@ -210,15 +183,9 @@ export function readMicrosoftGraphOrg(
  groups: GroupEntity[];
 }>;

-// Warning: (ae-missing-release-tag) "UserTransformer" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type UserTransformer = (
  user: MicrosoftGraph.User,
  userPhoto?: string,
 ) => Promise<UserEntity | undefined>;
-
-// Warnings were encountered during analysis:
-//
-// src/microsoftGraph/config.d.ts:28:8 - (tsdoc-undefined-tag) The TSDoc tag "@visibility" is not defined in this configuration
 ```
@@ -41,6 +41,11 @@ export type ODataQuery = {
  select?: string[];
 };

+/**
+ * Extends the base msgraph types to include the odata type.
+ *
+ * @public
+ */
 export type GroupMember =
  | (MicrosoftGraph.Group & { '@odata.type': '#microsoft.graph.user' })
  | (MicrosoftGraph.User & { '@odata.type': '#microsoft.graph.group' });
@@ -19,6 +19,8 @@ import { trimEnd } from 'lodash';

 /**
 * The configuration parameters for a single Microsoft Graph provider.
+ *
+ * @public
 */
 export type MicrosoftGraphProviderConfig = {
  /**
@@ -42,8 +44,6 @@ export type MicrosoftGraphProviderConfig = {
  clientId: string;
  /**
   * The OAuth client secret to use for authenticating requests.
-   *
-   * @visibility secret
   */
  clientSecret: string;
  /**
@@ -66,6 +66,13 @@ export type MicrosoftGraphProviderConfig = {
  groupFilter?: string;
 };

+/**
+ * Parses configuration.
+ *
+ * @param config - The root of the msgraph config hierarchy
+ *
+ * @public
+ */
 export function readMicrosoftGraphConfig(
  config: Config,
 ): MicrosoftGraphProviderConfig[] {
@@ -16,17 +16,23 @@

 /**
 * The tenant id used by the Microsoft Graph API
+ *
+ * @public
 */
 export const MICROSOFT_GRAPH_TENANT_ID_ANNOTATION =
  'graph.microsoft.com/tenant-id';

 /**
 * The group id used by the Microsoft Graph API
+ *
+ * @public
 */
 export const MICROSOFT_GRAPH_GROUP_ID_ANNOTATION =
  'graph.microsoft.com/group-id';

 /**
 * The user id used by the Microsoft Graph API
+ *
+ * @public
 */
 export const MICROSOFT_GRAPH_USER_ID_ANNOTATION = 'graph.microsoft.com/user-id';
@@ -14,6 +14,11 @@
 * limitations under the License.
 */

+/**
+ * Takes an input string and cleans it up to become suitable as an entity name.
+ *
+ * @public
+ */
 export function normalizeEntityName(name: string): string {
  let cleaned = name
    .trim()
@@ -14,6 +14,7 @@
 * limitations under the License.
 */
 export { MicrosoftGraphClient } from './client';
+export type { ODataQuery } from './client';
 export { readMicrosoftGraphConfig } from './config';
 export type { MicrosoftGraphProviderConfig } from './config';
 export {
@@ -13,6 +13,7 @@
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
+
 import {
  GroupEntity,
  stringifyEntityRef,
@@ -35,6 +36,12 @@ import {
  UserTransformer,
 } from './types';

+/**
+ * The default implementation of the transformation from a graph user entry to
+ * a User entity.
+ *
+ * @public
+ */
 export async function defaultUserTransformer(
  user: MicrosoftGraph.User,
  userPhoto?: string,
@@ -208,6 +215,12 @@ export async function readMicrosoftGraphUsersInGroups(
  return { users };
 }

+/**
+ * The default implementation of the transformation from a graph organization
+ * entry to a Group entity.
+ *
+ * @public
+ */
 export async function defaultOrganizationTransformer(
  organization: MicrosoftGraph.Organization,
 ): Promise<GroupEntity | undefined> {
@@ -258,6 +271,12 @@ function extractGroupName(group: MicrosoftGraph.Group): string {
  return (group.mailNickname || group.displayName) as string;
 }

+/**
+ * The default implementation of the transformation from a graph group entry to
+ * a Group entity.
+ *
+ * @public
+ */
 export async function defaultGroupTransformer(
  group: MicrosoftGraph.Group,
  groupPhoto?: string,
@@ -472,6 +491,11 @@ export function resolveRelations(
  buildMemberOf(groups, users);
 }

+/**
+ * Reads an entire org as Group and User entities.
+ *
+ * @public
+ */
 export async function readMicrosoftGraphOrg(
  client: MicrosoftGraphClient,
  tenantId: string,
@@ -17,15 +17,30 @@
 import { GroupEntity, UserEntity } from '@backstage/catalog-model';
 import * as MicrosoftGraph from '@microsoft/microsoft-graph-types';

+/**
+ * Customize the ingested User entity
+ *
+ * @public
+ */
 export type UserTransformer = (
  user: MicrosoftGraph.User,
  userPhoto?: string,
 ) => Promise<UserEntity | undefined>;

+/**
+ * Customize the ingested organization Group entity
+ *
+ * @public
+ */
 export type OrganizationTransformer = (
  organization: MicrosoftGraph.Organization,
 ) => Promise<GroupEntity | undefined>;

+/**
+ * Customize the ingested Group entity
+ *
+ * @public
+ */
 export type GroupTransformer = (
  group: MicrosoftGraph.Group,
  groupPhoto?: string,
@@ -13,6 +13,7 @@
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
+
 import {
  Entity,
  LOCATION_ANNOTATION,
@@ -41,6 +42,8 @@ import {
 /**
 * Reads user and group entries out of Microsoft Graph, and provides them as
 * User and Group entities for the catalog.
+ *
+ * @public
 */
 export class MicrosoftGraphOrgEntityProvider implements EntityProvider {
  private connection?: EntityProviderConnection;
@@ -91,14 +94,20 @@ export class MicrosoftGraphOrgEntityProvider implements EntityProvider {
    },
  ) {}

+  /** {@inheritdoc @backstage/plugin-catalog-backend#EntityProvider.getProviderName} */
  getProviderName() {
    return `MicrosoftGraphOrgEntityProvider:${this.options.id}`;
  }

+  /** {@inheritdoc @backstage/plugin-catalog-backend#EntityProvider.connect} */
  async connect(connection: EntityProviderConnection) {
    this.connection = connection;
  }

+  /**
+   * Runs one complete ingestion loop. Call this method regularly at some
+   * appropriate cadence.
+   */
  async read() {
    if (!this.connection) {
      throw new Error('Not initialized');
@@ -34,6 +34,8 @@ import {

 /**
 * Extracts teams and users out of a the Microsoft Graph API.
+ *
+ * @public
 */
 export class MicrosoftGraphOrgReaderProcessor implements CatalogProcessor {
  private readonly providers: MicrosoftGraphProviderConfig[];