From 722681b1b13ff2192a0c3a3389d7fc7d0b752b13 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= Date: Sun, 9 Jan 2022 13:05:10 +0100 Subject: [PATCH] Clean up API reports in ldap and msgraph catalog modules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Fredrik Adelöw --- .changeset/long-otters-promise.md | 6 ++ .gitignore | 3 + .../catalog-backend-module-ldap/api-report.md | 77 +++---------------- .../src/ldap/client.ts | 20 +++-- .../src/ldap/config.ts | 12 ++- .../src/ldap/constants.ts | 6 ++ .../src/ldap/index.ts | 7 +- .../src/ldap/read.ts | 54 ++++++++----- .../src/ldap/types.ts | 26 +++++-- .../src/ldap/util.ts | 18 +++-- .../src/ldap/vendors.ts | 6 +- .../src/processors/LdapOrgEntityProvider.ts | 13 ++++ .../src/processors/LdapOrgReaderProcessor.ts | 2 + .../api-report.md | 65 ++++------------ .../src/microsoftGraph/client.ts | 5 ++ .../src/microsoftGraph/config.ts | 11 ++- .../src/microsoftGraph/constants.ts | 6 ++ .../src/microsoftGraph/helper.ts | 5 ++ .../src/microsoftGraph/index.ts | 1 + .../src/microsoftGraph/read.ts | 24 ++++++ .../src/microsoftGraph/types.ts | 15 ++++ .../MicrosoftGraphOrgEntityProvider.ts | 9 +++ .../MicrosoftGraphOrgReaderProcessor.ts | 2 + 23 files changed, 225 insertions(+), 168 deletions(-) create mode 100644 .changeset/long-otters-promise.md diff --git a/.changeset/long-otters-promise.md b/.changeset/long-otters-promise.md new file mode 100644 index 0000000000..eecb97e8ac --- /dev/null +++ b/.changeset/long-otters-promise.md @@ -0,0 +1,6 @@ +--- +'@backstage/plugin-catalog-backend-module-ldap': patch +'@backstage/plugin-catalog-backend-module-msgraph': patch +--- + +Clean up API report diff --git a/.gitignore b/.gitignore index 8c37280023..60d0d6da3b 100644 --- a/.gitignore +++ b/.gitignore @@ -136,3 +136,6 @@ site # e2e tests cypress/cypress/* + +# Possible leftover from build:api-reports +tsconfig.tmp.json diff --git a/plugins/catalog-backend-module-ldap/api-report.md b/plugins/catalog-backend-module-ldap/api-report.md index bbf92944b9..e2dbef74e5 100644 --- a/plugins/catalog-backend-module-ldap/api-report.md +++ b/plugins/catalog-backend-module-ldap/api-report.md @@ -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; -// 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; -// 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; -// 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; getRootDSE(): Promise; getVendor(): Promise; - // 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; - // 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; } -// 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; } -// 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; } -// 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; - -// 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 ``` diff --git a/plugins/catalog-backend-module-ldap/src/ldap/client.ts b/plugins/catalog-backend-module-ldap/src/ldap/client.ts index 553081f4b0..ea13ba49ee 100644 --- a/plugins/catalog-backend-module-ldap/src/ldap/client.ts +++ b/plugins/catalog-backend-module-ldap/src/ldap/client.ts @@ -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 | 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 { 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 { try { return await new Promise((resolve, reject) => { diff --git a/plugins/catalog-backend-module-ldap/src/ldap/config.ts b/plugins/catalog-backend-module-ldap/src/ldap/config.ts index b12c7c9fee..526467962e 100644 --- a/plugins/catalog-backend-module-ldap/src/ldap/config.ts +++ b/plugins/catalog-backend-module-ldap/src/ldap/config.ts @@ -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(data: T): T { diff --git a/plugins/catalog-backend-module-ldap/src/ldap/constants.ts b/plugins/catalog-backend-module-ldap/src/ldap/constants.ts index 73df5d6de8..cdc448b4dd 100644 --- a/plugins/catalog-backend-module-ldap/src/ldap/constants.ts +++ b/plugins/catalog-backend-module-ldap/src/ldap/constants.ts @@ -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'; diff --git a/plugins/catalog-backend-module-ldap/src/ldap/index.ts b/plugins/catalog-backend-module-ldap/src/ldap/index.ts index 70500299ae..c3aace492f 100644 --- a/plugins/catalog-backend-module-ldap/src/ldap/index.ts +++ b/plugins/catalog-backend-module-ldap/src/ldap/index.ts @@ -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, diff --git a/plugins/catalog-backend-module-ldap/src/ldap/read.ts b/plugins/catalog-backend-module-ldap/src/ldap/read.ts index 513d899304..e15ec85554 100644 --- a/plugins/catalog-backend-module-ldap/src/ldap/read.ts +++ b/plugins/catalog-backend-module-ldap/src/ldap/read.ts @@ -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[], diff --git a/plugins/catalog-backend-module-ldap/src/ldap/types.ts b/plugins/catalog-backend-module-ldap/src/ldap/types.ts index e32e4c5b42..9d7c326add 100644 --- a/plugins/catalog-backend-module-ldap/src/ldap/types.ts +++ b/plugins/catalog-backend-module-ldap/src/ldap/types.ts @@ -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, diff --git a/plugins/catalog-backend-module-ldap/src/ldap/util.ts b/plugins/catalog-backend-module-ldap/src/ldap/util.ts index 21ee40f52c..21829cef35 100644 --- a/plugins/catalog-backend-module-ldap/src/ldap/util.ts +++ b/plugins/catalog-backend-module-ldap/src/ldap/util.ts @@ -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, diff --git a/plugins/catalog-backend-module-ldap/src/ldap/vendors.ts b/plugins/catalog-backend-module-ldap/src/ldap/vendors.ts index 3341497ca8..3df29a5fb9 100644 --- a/plugins/catalog-backend-module-ldap/src/ldap/vendors.ts +++ b/plugins/catalog-backend-module-ldap/src/ldap/vendors.ts @@ -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[]; }; diff --git a/plugins/catalog-backend-module-ldap/src/processors/LdapOrgEntityProvider.ts b/plugins/catalog-backend-module-ldap/src/processors/LdapOrgEntityProvider.ts index c0cd663052..c74e5b3aee 100644 --- a/plugins/catalog-backend-module-ldap/src/processors/LdapOrgEntityProvider.ts +++ b/plugins/catalog-backend-module-ldap/src/processors/LdapOrgEntityProvider.ts @@ -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'); diff --git a/plugins/catalog-backend-module-ldap/src/processors/LdapOrgReaderProcessor.ts b/plugins/catalog-backend-module-ldap/src/processors/LdapOrgReaderProcessor.ts index f87afc38b9..be2d748840 100644 --- a/plugins/catalog-backend-module-ldap/src/processors/LdapOrgReaderProcessor.ts +++ b/plugins/catalog-backend-module-ldap/src/processors/LdapOrgReaderProcessor.ts @@ -33,6 +33,8 @@ import { /** * Extracts teams and users out of an LDAP server. + * + * @public */ export class LdapOrgReaderProcessor implements CatalogProcessor { private readonly providers: LdapProviderConfig[]; diff --git a/plugins/catalog-backend-module-msgraph/api-report.md b/plugins/catalog-backend-module-msgraph/api-report.md index e1a837d0c1..662056eff1 100644 --- a/plugins/catalog-backend-module-msgraph/api-report.md +++ b/plugins/catalog-backend-module-msgraph/api-report.md @@ -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; -// 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; -// 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; -// 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; -// 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; - // 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; getOrganization(tenantId: string): Promise; // (undocumented) @@ -86,18 +71,12 @@ export class MicrosoftGraphClient { maxSize: number, ): Promise; getUserProfile(userId: string): Promise; - // 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; - // 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; - // 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(path: string, query?: ODataQuery): AsyncIterable; requestRaw(url: string): Promise; } -// 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; } -// 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; } -// 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; -// 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; - -// 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 ``` diff --git a/plugins/catalog-backend-module-msgraph/src/microsoftGraph/client.ts b/plugins/catalog-backend-module-msgraph/src/microsoftGraph/client.ts index 63f256afbd..827c9fc14d 100644 --- a/plugins/catalog-backend-module-msgraph/src/microsoftGraph/client.ts +++ b/plugins/catalog-backend-module-msgraph/src/microsoftGraph/client.ts @@ -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' }); diff --git a/plugins/catalog-backend-module-msgraph/src/microsoftGraph/config.ts b/plugins/catalog-backend-module-msgraph/src/microsoftGraph/config.ts index 91a6d49b57..4d37e24632 100644 --- a/plugins/catalog-backend-module-msgraph/src/microsoftGraph/config.ts +++ b/plugins/catalog-backend-module-msgraph/src/microsoftGraph/config.ts @@ -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[] { diff --git a/plugins/catalog-backend-module-msgraph/src/microsoftGraph/constants.ts b/plugins/catalog-backend-module-msgraph/src/microsoftGraph/constants.ts index e6abbebb0a..bbfbd61efe 100644 --- a/plugins/catalog-backend-module-msgraph/src/microsoftGraph/constants.ts +++ b/plugins/catalog-backend-module-msgraph/src/microsoftGraph/constants.ts @@ -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'; diff --git a/plugins/catalog-backend-module-msgraph/src/microsoftGraph/helper.ts b/plugins/catalog-backend-module-msgraph/src/microsoftGraph/helper.ts index 41dbc1aed8..fd09d754d4 100644 --- a/plugins/catalog-backend-module-msgraph/src/microsoftGraph/helper.ts +++ b/plugins/catalog-backend-module-msgraph/src/microsoftGraph/helper.ts @@ -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() diff --git a/plugins/catalog-backend-module-msgraph/src/microsoftGraph/index.ts b/plugins/catalog-backend-module-msgraph/src/microsoftGraph/index.ts index eeb436d317..b0d53b43a2 100644 --- a/plugins/catalog-backend-module-msgraph/src/microsoftGraph/index.ts +++ b/plugins/catalog-backend-module-msgraph/src/microsoftGraph/index.ts @@ -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 { diff --git a/plugins/catalog-backend-module-msgraph/src/microsoftGraph/read.ts b/plugins/catalog-backend-module-msgraph/src/microsoftGraph/read.ts index 7dd6f83e2e..b2845ac78d 100644 --- a/plugins/catalog-backend-module-msgraph/src/microsoftGraph/read.ts +++ b/plugins/catalog-backend-module-msgraph/src/microsoftGraph/read.ts @@ -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 { @@ -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, diff --git a/plugins/catalog-backend-module-msgraph/src/microsoftGraph/types.ts b/plugins/catalog-backend-module-msgraph/src/microsoftGraph/types.ts index fab662cc3f..ef60d7b018 100644 --- a/plugins/catalog-backend-module-msgraph/src/microsoftGraph/types.ts +++ b/plugins/catalog-backend-module-msgraph/src/microsoftGraph/types.ts @@ -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; +/** + * Customize the ingested organization Group entity + * + * @public + */ export type OrganizationTransformer = ( organization: MicrosoftGraph.Organization, ) => Promise; +/** + * Customize the ingested Group entity + * + * @public + */ export type GroupTransformer = ( group: MicrosoftGraph.Group, groupPhoto?: string, diff --git a/plugins/catalog-backend-module-msgraph/src/processors/MicrosoftGraphOrgEntityProvider.ts b/plugins/catalog-backend-module-msgraph/src/processors/MicrosoftGraphOrgEntityProvider.ts index ea396162dd..6d66723970 100644 --- a/plugins/catalog-backend-module-msgraph/src/processors/MicrosoftGraphOrgEntityProvider.ts +++ b/plugins/catalog-backend-module-msgraph/src/processors/MicrosoftGraphOrgEntityProvider.ts @@ -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'); diff --git a/plugins/catalog-backend-module-msgraph/src/processors/MicrosoftGraphOrgReaderProcessor.ts b/plugins/catalog-backend-module-msgraph/src/processors/MicrosoftGraphOrgReaderProcessor.ts index cb7729e04a..351a4983d9 100644 --- a/plugins/catalog-backend-module-msgraph/src/processors/MicrosoftGraphOrgReaderProcessor.ts +++ b/plugins/catalog-backend-module-msgraph/src/processors/MicrosoftGraphOrgReaderProcessor.ts @@ -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[];