fix: address Andre's review comments

- Update copyright year from 2024 to 2026 across all new source files - Clear alpha entry point (no alpha exports needed for a net-new package) and regenerate report-alpha.api.md accordingly - Delete CHANGELOG.md (auto-generated by the release process) - Change changeset bump from patch to minor so the first release is 0.1.0, and remove the redundant "New package:" title line - Reset package version to 0.0.0 (release process sets the real version) - Add incremental ingestion section to docs/integrations/azure/org.md Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: pillaris <pillaris@adobe.com>
2026-04-28 09:54:40 +05:30
parent 1b5e83401f
commit ff199fef07
14 changed files with 43 additions and 123 deletions
@@ -1,7 +1,5 @@
 ---
-'@backstage/plugin-catalog-backend-module-msgraph-incremental': patch
+'@backstage/plugin-catalog-backend-module-msgraph-incremental': minor
 ---

-New package: `@backstage/plugin-catalog-backend-module-msgraph-incremental`
-
 Introduces a cursor-based incremental ingestion provider for Microsoft Graph that processes users and groups one page at a time. Unlike `MicrosoftGraphOrgEntityProvider`, this module never holds the full dataset in memory — each burst processes a single page (up to 999 users or 100 groups). The `@odata.nextLink` cursor is persisted so a pod restart resumes from the last completed page rather than starting over.
@@ -50,6 +50,37 @@ backend.add(import('@backstage/plugin-catalog-backend-module-msgraph'));
 /* highlight-add-end */
 ```

+## Incremental Ingestion for Large Tenants
+
+For very large Azure AD tenants where loading the full dataset into memory at once is not feasible, the `@backstage/plugin-catalog-backend-module-msgraph-incremental` package provides a memory-efficient alternative. It processes users and groups one page at a time and persists the `@odata.nextLink` cursor so ingestion resumes from the last completed page after a pod restart.
+
+```bash title="From your Backstage root directory"
+yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-incremental-ingestion
+yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-msgraph-incremental
+```
+
+```ts title="packages/backend/src/index.ts"
+backend.add(import('@backstage/plugin-catalog-backend'));
+/* highlight-add-start */
+backend.add(
+  import('@backstage/plugin-catalog-backend-module-incremental-ingestion'),
+);
+backend.add(
+  import('@backstage/plugin-catalog-backend-module-msgraph-incremental'),
+);
+/* highlight-add-end */
+```
+
+It uses the same `catalog.providers.microsoftGraphOrg` configuration as the standard module. The following options are **not** supported by the incremental provider: `userGroupMember*` and `groupIncludeSubGroups`. Use `MicrosoftGraphOrgEntityProvider` if you require those.
+
+|                            | `MicrosoftGraphOrgEntityProvider` | Incremental provider |
+| -------------------------- | --------------------------------- | -------------------- |
+| Memory usage               | Full dataset in RAM               | One page at a time   |
+| Resume on restart          | Starts from scratch               | Resumes from cursor  |
+| `userGroupMember*` options | Supported                         | Not supported        |
+| `groupIncludeSubGroups`    | Supported                         | Not supported        |
+| Suitable for large tenants | No                                | Yes                  |
+
 ## Authenticating with Microsoft Graph

 ### Local Development
@@ -1,16 +0,0 @@
-# @backstage/plugin-catalog-backend-module-msgraph-incremental
-
-## 0.1.0
-
-### Minor Changes
-
- Initial release of the incremental Microsoft Graph catalog module.
-
-  Provides `catalogModuleMicrosoftGraphIncrementalEntityProvider`, which
-  ingests users and groups from Microsoft Graph one page at a time using the
-  catalog's incremental ingestion framework. Unlike
-  `MicrosoftGraphOrgEntityProvider`, this module never holds the full dataset
-  in memory and resumes from its cursor on pod restart.
-
-  Requires `@backstage/plugin-catalog-backend-module-incremental-ingestion` to
-  be installed in the backend.
@@ -1,6 +1,6 @@
 {
  "name": "@backstage/plugin-catalog-backend-module-msgraph-incremental",
-  "version": "0.1.0",
+  "version": "0.0.0",
  "description": "A Backstage catalog backend module that incrementally ingests users and groups from Microsoft Graph",
  "backstage": {
    "role": "backend-plugin-module",
@@ -3,96 +3,5 @@
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).

 ```ts
-import { BackendFeature } from '@backstage/backend-plugin-api';
-import { Config } from '@backstage/config';
-import { EntityIteratorResult } from '@backstage/plugin-catalog-backend-module-incremental-ingestion';
-import { ExtensionPoint } from '@backstage/backend-plugin-api';
-import { GroupTransformer } from '@backstage/plugin-catalog-backend-module-msgraph';
-import { IncrementalEntityProvider } from '@backstage/plugin-catalog-backend-module-incremental-ingestion';
-import { LoggerService } from '@backstage/backend-plugin-api';
-import { MicrosoftGraphClient } from '@backstage/plugin-catalog-backend-module-msgraph';
-import { MicrosoftGraphProviderConfig } from '@backstage/plugin-catalog-backend-module-msgraph';
-import { OrganizationTransformer } from '@backstage/plugin-catalog-backend-module-msgraph';
-import { ProviderConfigTransformer } from '@backstage/plugin-catalog-backend-module-msgraph';
-import { UserTransformer } from '@backstage/plugin-catalog-backend-module-msgraph';

-// @public
-const catalogModuleMicrosoftGraphIncrementalEntityProvider: BackendFeature;
-export { catalogModuleMicrosoftGraphIncrementalEntityProvider };
-export default catalogModuleMicrosoftGraphIncrementalEntityProvider;
-
-// @public
-export class MicrosoftGraphIncrementalEntityProvider
-  implements IncrementalEntityProvider<MSGraphCursor, MSGraphContext>
-{
-  constructor(options: {
-    id: string;
-    provider: MicrosoftGraphProviderConfig;
-    logger: LoggerService;
-    userTransformer?: UserTransformer;
-    groupTransformer?: GroupTransformer;
-    organizationTransformer?: OrganizationTransformer;
-    providerConfigTransformer?: ProviderConfigTransformer;
-  });
-  around(burst: (context: MSGraphContext) => Promise<void>): Promise<void>;
-  static fromConfig(
-    configRoot: Config,
-    options: MicrosoftGraphIncrementalEntityProviderOptions,
-  ): MicrosoftGraphIncrementalEntityProvider[];
-  getProviderName(): string;
-  next(
-    input: MSGraphContext,
-    cursor?: MSGraphCursor,
-  ): Promise<EntityIteratorResult<MSGraphCursor>>;
-}
-
-// @public
-export interface MicrosoftGraphIncrementalEntityProviderOptions {
-  groupTransformer?: GroupTransformer | Record<string, GroupTransformer>;
-  logger: LoggerService;
-  organizationTransformer?:
-    | OrganizationTransformer
-    | Record<string, OrganizationTransformer>;
-  providerConfigTransformer?:
-    | ProviderConfigTransformer
-    | Record<string, ProviderConfigTransformer>;
-  userTransformer?: UserTransformer | Record<string, UserTransformer>;
-}
-
-// @public
-export const microsoftGraphIncrementalEntityProviderTransformExtensionPoint: ExtensionPoint<MicrosoftGraphIncrementalEntityProviderTransformsExtensionPoint>;
-
-// @public
-export interface MicrosoftGraphIncrementalEntityProviderTransformsExtensionPoint {
-  setGroupTransformer(
-    transformer: GroupTransformer | Record<string, GroupTransformer>,
-  ): void;
-  setOrganizationTransformer(
-    transformer:
-      | OrganizationTransformer
-      | Record<string, OrganizationTransformer>,
-  ): void;
-  setProviderConfigTransformer(
-    transformer:
-      | ProviderConfigTransformer
-      | Record<string, ProviderConfigTransformer>,
-  ): void;
-  setUserTransformer(
-    transformer: UserTransformer | Record<string, UserTransformer>,
-  ): void;
-}
-
-// @public
-export type MSGraphContext = {
-  client: MicrosoftGraphClient;
-  provider: MicrosoftGraphProviderConfig;
-};
-
-// @public
-export type MSGraphCursor = {
-  phase: 'users' | 'groups';
-  nextLink?: string;
-};
-
-// (No @packageDocumentation comment for this package)
 ```
@@ -1,5 +1,5 @@
 /*
- * Copyright 2024 The Backstage Authors
+ * Copyright 2026 The Backstage Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -1,5 +1,5 @@
 /*
- * Copyright 2024 The Backstage Authors
+ * Copyright 2026 The Backstage Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -1,5 +1,5 @@
 /*
- * Copyright 2024 The Backstage Authors
+ * Copyright 2026 The Backstage Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -14,6 +14,4 @@
 * limitations under the License.
 */

-// Re-export everything from the main entry point while the package is in alpha.
-export * from './index';
-export { default } from './index';
+export {};
@@ -1,5 +1,5 @@
 /*
- * Copyright 2024 The Backstage Authors
+ * Copyright 2026 The Backstage Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -1,5 +1,5 @@
 /*
- * Copyright 2024 The Backstage Authors
+ * Copyright 2026 The Backstage Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -1,5 +1,5 @@
 /*
- * Copyright 2024 The Backstage Authors
+ * Copyright 2026 The Backstage Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -1,5 +1,5 @@
 /*
- * Copyright 2024 The Backstage Authors
+ * Copyright 2026 The Backstage Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -1,5 +1,5 @@
 /*
- * Copyright 2024 The Backstage Authors
+ * Copyright 2026 The Backstage Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -1,5 +1,5 @@
 /*
- * Copyright 2024 The Backstage Authors
+ * Copyright 2026 The Backstage Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.