catalog-backend-module-msgraph: move alpha options to extension point

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

.changeset/loud-wasps-smoke.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-backend-module-msgraph': patch
+---
+
+The alpha `catalogModuleMicrosoftGraphOrgEntityProvider` export no longer accepts options. Transformers are now instead configured via the `microsoftGraphOrgEntityProviderTransformExtensionPoint`.

plugins/catalog-backend-module-msgraph/alpha-api-report.md

@@ -4,6 +4,7 @@
 
 ```ts
 import { BackendFeature } from '@backstage/backend-plugin-api';
+import { ExtensionPoint } from '@backstage/backend-plugin-api';
 import { GroupTransformer } from '@backstage/plugin-catalog-backend-module-msgraph';
 import { OrganizationTransformer } from '@backstage/plugin-catalog-backend-module-msgraph';
 import { UserTransformer } from '@backstage/plugin-catalog-backend-module-msgraph';
@@ -12,12 +13,21 @@ import { UserTransformer } from '@backstage/plugin-catalog-backend-module-msgrap
 export const catalogModuleMicrosoftGraphOrgEntityProvider: () => BackendFeature;
 
 // @alpha
-export interface CatalogModuleMicrosoftGraphOrgEntityProviderOptions {
-  groupTransformer?: GroupTransformer | Record<string, GroupTransformer>;
-  organizationTransformer?:
-    | OrganizationTransformer
-    | Record<string, OrganizationTransformer>;
-  userTransformer?: UserTransformer | Record<string, UserTransformer>;
+export const microsoftGraphOrgEntityProviderTransformExtensionPoint: ExtensionPoint<MicrosoftGraphOrgEntityProviderTransformsExtensionPoint>;
+
+// @alpha
+export interface MicrosoftGraphOrgEntityProviderTransformsExtensionPoint {
+  setGroupTransformer(
+    transformer: GroupTransformer | Record<string, GroupTransformer>,
+  ): void;
+  setOrganizationTransformer(
+    transformer:
+      | OrganizationTransformer
+      | Record<string, OrganizationTransformer>,
+  ): void;
+  setUserTransformer(
+    transformer: UserTransformer | Record<string, UserTransformer>,
+  ): void;
 }
 
 // (No @packageDocumentation comment for this package)

plugins/catalog-backend-module-msgraph/src/module/catalogModuleMicrosoftGraphOrgEntityProvider.ts

@@ -17,6 +17,7 @@
 import {
   coreServices,
   createBackendModule,
+  createExtensionPoint,
 } from '@backstage/backend-plugin-api';
 import { loggerToWinstonLogger } from '@backstage/backend-common';
 import { catalogProcessingExtensionPoint } from '@backstage/plugin-catalog-node/alpha';
@@ -28,32 +29,50 @@ import {
 import { MicrosoftGraphOrgEntityProvider } from '../processors';
 
 /**
- * Options for {@link catalogModuleMicrosoftGraphOrgEntityProvider}.
+ * Interface for {@link microsoftGraphOrgEntityProviderTransformExtensionPoint}.
  *
  * @alpha
  */
-export interface CatalogModuleMicrosoftGraphOrgEntityProviderOptions {
+export interface MicrosoftGraphOrgEntityProviderTransformsExtensionPoint {
   /**
-   * The function that transforms a user entry in msgraph to an entity.
+   * Set the function that transforms a user entry in msgraph to an entity.
    * Optionally, you can pass separate transformers per provider ID.
    */
-  userTransformer?: UserTransformer | Record<string, UserTransformer>;
+  setUserTransformer(
+    transformer: UserTransformer | Record<string, UserTransformer>,
+  ): void;
 
   /**
-   * The function that transforms a group entry in msgraph to an entity.
+   * Set the function that transforms a group entry in msgraph to an entity.
    * Optionally, you can pass separate transformers per provider ID.
    */
-  groupTransformer?: GroupTransformer | Record<string, GroupTransformer>;
+  setGroupTransformer(
+    transformer: GroupTransformer | Record<string, GroupTransformer>,
+  ): void;
 
   /**
-   * The function that transforms an organization entry in msgraph to an entity.
+   * Set the function that transforms an organization entry in msgraph to an entity.
    * Optionally, you can pass separate transformers per provider ID.
    */
-  organizationTransformer?:
-    | OrganizationTransformer
-    | Record<string, OrganizationTransformer>;
+  setOrganizationTransformer(
+    transformer:
+      | OrganizationTransformer
+      | Record<string, OrganizationTransformer>,
+  ): void;
 }
 
+/**
+ * Extension point used to customize the transforms used by the {@link catalogModuleMicrosoftGraphOrgEntityProvider}.
+ *
+ * @alpha
+ */
+export const microsoftGraphOrgEntityProviderTransformExtensionPoint =
+  createExtensionPoint<MicrosoftGraphOrgEntityProviderTransformsExtensionPoint>(
+    {
+      id: 'catalog.microsoftGraphOrgEntityProvider.transforms',
+    },
+  );
+
 /**
  * Registers the MicrosoftGraphOrgEntityProvider with the catalog processing extension point.
  *
@@ -63,10 +82,44 @@ export const catalogModuleMicrosoftGraphOrgEntityProvider = createBackendModule(
   {
     pluginId: 'catalog',
     moduleId: 'microsoftGraphOrgEntityProvider',
-    register(
-      env,
-      options?: CatalogModuleMicrosoftGraphOrgEntityProviderOptions,
-    ) {
+    register(env) {
+      let userTransformer:
+        | UserTransformer
+        | Record<string, UserTransformer>
+        | undefined;
+      let groupTransformer:
+        | GroupTransformer
+        | Record<string, GroupTransformer>
+        | undefined;
+      let organizationTransformer:
+        | OrganizationTransformer
+        | Record<string, OrganizationTransformer>
+        | undefined;
+
+      env.registerExtensionPoint(
+        microsoftGraphOrgEntityProviderTransformExtensionPoint,
+        {
+          setUserTransformer(transformer) {
+            if (userTransformer) {
+              throw new Error('User transformer may only be set once');
+            }
+            userTransformer = transformer;
+          },
+          setGroupTransformer(transformer) {
+            if (groupTransformer) {
+              throw new Error('Group transformer may only be set once');
+            }
+            groupTransformer = transformer;
+          },
+          setOrganizationTransformer(transformer) {
+            if (organizationTransformer) {
+              throw new Error('Organization transformer may only be set once');
+            }
+            organizationTransformer = transformer;
+          },
+        },
+      );
+
       env.registerInit({
         deps: {
           catalog: catalogProcessingExtensionPoint,
@@ -77,11 +130,11 @@ export const catalogModuleMicrosoftGraphOrgEntityProvider = createBackendModule(
         async init({ catalog, config, logger, scheduler }) {
           catalog.addEntityProvider(
             MicrosoftGraphOrgEntityProvider.fromConfig(config, {
-              groupTransformer: options?.groupTransformer,
               logger: loggerToWinstonLogger(logger),
-              organizationTransformer: options?.organizationTransformer,
               scheduler,
-              userTransformer: options?.userTransformer,
+              userTransformer: userTransformer,
+              groupTransformer: groupTransformer,
+              organizationTransformer: organizationTransformer,
             }),
           );
         },

plugins/catalog-backend-module-msgraph/src/module/index.ts

@@ -14,5 +14,8 @@
  * limitations under the License.
  */
 
-export { catalogModuleMicrosoftGraphOrgEntityProvider } from './catalogModuleMicrosoftGraphOrgEntityProvider';
-export type { CatalogModuleMicrosoftGraphOrgEntityProviderOptions } from './catalogModuleMicrosoftGraphOrgEntityProvider';
+export {
+  catalogModuleMicrosoftGraphOrgEntityProvider,
+  microsoftGraphOrgEntityProviderTransformExtensionPoint,
+  type MicrosoftGraphOrgEntityProviderTransformsExtensionPoint,
+} from './catalogModuleMicrosoftGraphOrgEntityProvider';