@backstage/plugin-catalog-backend 0.23.0 → 0.24.0

package/CHANGELOG.md

@@ -1,5 +1,163 @@
 # @backstage/plugin-catalog-backend
 
+## 0.24.0
+
+### Minor Changes
+
+- 66ba5d9023: **BREAKING**: Removed `GithubDiscoveryProcessor`, `GithubMultiOrgReaderProcessor`, `GitHubOrgEntityProvider`, `GithubOrgReaderProcessor`, and `GithubMultiOrgConfig` which now instead should be imported from `@backstage/plugin-catalog-backend-module-github`. NOTE THAT the `GithubDiscoveryProcessor` and `GithubOrgReaderProcessor` were part of the default set of processors in the catalog backend, and if you are a user of discovery or location based org ingestion on GitLab, you MUST now add them manually in the catalog initialization code of your backend.
+
+  ```diff
+  // In packages/backend/src/plugins/catalog.ts
+  +import {
+  +  GithubDiscoveryProcessor,
+  +  GithubOrgReaderProcessor,
+  +} from '@backstage/plugin-catalog-backend-module-github';
+  +import {
+  +  ScmIntegrations,
+  +  DefaultGithubCredentialsProvider
+  +} from '@backstage/integration';
+
+   export default async function createPlugin(
+     env: PluginEnvironment,
+   ): Promise<Router> {
+     const builder = await CatalogBuilder.create(env);
+  +  const integrations = ScmIntegrations.fromConfig(config);
+  +  const githubCredentialsProvider =
+  +    DefaultGithubCredentialsProvider.fromIntegrations(integrations);
+  +  builder.addProcessor(
+  +    GithubDiscoveryProcessor.fromConfig(config, {
+  +      logger,
+  +      githubCredentialsProvider,
+  +    }),
+  +    GithubOrgReaderProcessor.fromConfig(config, {
+  +      logger,
+  +      githubCredentialsProvider,
+  +    }),
+  +  );
+  ```
+
+  **BREAKING**: Removed `GitLabDiscoveryProcessor`, which now instead should be imported from `@backstage/plugin-catalog-backend-module-gitlab`. NOTE THAT this processor was part of the default set of processors in the catalog backend, and if you are a user of discovery on GitLab, you MUST now add it manually in the catalog initialization code of your backend.
+
+  ```diff
+  // In packages/backend/src/plugins/catalog.ts
+  +import { GitLabDiscoveryProcessor } from '@backstage/plugin-catalog-backend-module-gitlab';
+
+   export default async function createPlugin(
+     env: PluginEnvironment,
+   ): Promise<Router> {
+     const builder = await CatalogBuilder.create(env);
+  +  builder.addProcessor(
+  +    GitLabDiscoveryProcessor.fromConfig(env.config, { logger: env.logger })
+  +  );
+  ```
+
+  **BREAKING**: Removed `BitbucketDiscoveryProcessor`, which now instead should be imported from `@backstage/plugin-catalog-backend-module-bitbucket`. NOTE THAT this processor was part of the default set of processors in the catalog backend, and if you are a user of discovery on Bitbucket, you MUST now add it manually in the catalog initialization code of your backend.
+
+  ```diff
+  // In packages/backend/src/plugins/catalog.ts
+  +import { BitbucketDiscoveryProcessor } from '@backstage/plugin-catalog-backend-module-bitbucket';
+
+   export default async function createPlugin(
+     env: PluginEnvironment,
+   ): Promise<Router> {
+     const builder = await CatalogBuilder.create(env);
+  +  builder.addProcessor(
+  +    BitbucketDiscoveryProcessor.fromConfig(env.config, { logger: env.logger })
+  +  );
+  ```
+
+  **BREAKING**: Removed `AzureDevOpsDiscoveryProcessor`, which now instead should be imported from `@backstage/plugin-catalog-backend-module-azure`. This processor was not part of the set of default processors. If you were using it, you should already have a reference to it in your backend code and only need to update the import.
+
+  **BREAKING**: Removed the formerly deprecated type `BitbucketRepositoryParser`, which is instead reintroduced in `@backstage/plugin-catalog-backend-module-bitbucket`.
+
+- f115a7f8fd: **BREAKING**: Removed `AwsS3DiscoveryProcessor`, which now instead should be imported from `@backstage/plugin-catalog-backend-module-aws`.
+- 55150919ed: - **BREAKING**: Support for `backstage.io/v1beta2` Software Templates has been removed. Please migrate your legacy templates to the new `scaffolder.backstage.io/v1beta3` `apiVersion` by following the [migration guide](https://backstage.io/docs/features/software-templates/migrating-from-v1beta2-to-v1beta3)
+
+### Patch Changes
+
+- ab7cd7d70e: Do some groundwork for supporting the `better-sqlite3` driver, to maybe eventually replace `@vscode/sqlite3` (#9912)
+- e0a69ba49f: build(deps): bump `fs-extra` from 9.1.0 to 10.0.1
+- 616f02ade2: support Bitbucket Cloud's code search to discover catalog files (multiple per repo, Location entities for existing files only)
+- e421d77536: **BREAKING**:
+
+  - Removed the previously deprecated `runPeriodically` export. Please use the `@backstage/backend-tasks` package instead, or copy [the actual implementation](https://github.com/backstage/backstage/blob/02875d4d56708c60f86f6b0a5b3da82e24988354/plugins/catalog-backend/src/util/runPeriodically.ts#L29) into your own code if you explicitly do not want coordination of task runs across your worker nodes.
+  - Removed the previously deprecated `CatalogProcessorLocationResult.optional` field. Please set the corresponding `LocationSpec.presence` field to `'optional'` instead.
+  - Related to the previous point, the `processingResult.location` function no longer has a second boolean `optional` argument. Please set the corresponding `LocationSpec.presence` field to `'optional'` instead.
+  - Removed the previously deprecated `StaticLocationProcessor`. It has not been in use for some time; its functionality is covered by `ConfigLocationEntityProvider` instead.
+
+- 3c2bc73901: Use `setupRequestMockHandlers` from `@backstage/backend-test-utils`
+- c1168bb440: Fixed display of the location in the log message that is printed when entity envelope validation fails.
+- b1aacbf96a: Applied the fix for the `/alpha` entry point resolution that was part of the `v0.70.1` release of Backstage.
+- 3e54f6c436: Use `@backstage/plugin-search-common` package instead of `@backstage/search-common`.
+- Updated dependencies
+  - @backstage/backend-common@0.13.0
+  - @backstage/plugin-scaffolder-common@0.3.0
+  - @backstage/catalog-model@0.13.0
+  - @backstage/plugin-catalog-common@0.2.2
+  - @backstage/plugin-search-common@0.3.1
+  - @backstage/catalog-client@0.9.0
+  - @backstage/plugin-permission-node@0.5.4
+
+## 0.24.0-next.0
+
+### Minor Changes
+
+- 66ba5d9023: **BREAKING**: Removed `GitLabDiscoveryProcessor`, which now instead should be imported from `@backstage/plugin-catalog-backend-module-gitlab`. NOTE THAT this processor was part of the default set of processors in the catalog backend, and if you are a user of discovery on GitLab, you MUST now add it manually in the catalog initialization code of your backend.
+
+  ```diff
+  // In packages/backend/src/plugins/catalog.ts
+  +import { GitLabDiscoveryProcessor } from '@backstage/plugin-catalog-backend-module-gitlab';
+
+   export default async function createPlugin(
+     env: PluginEnvironment,
+   ): Promise<Router> {
+     const builder = await CatalogBuilder.create(env);
+  +  builder.addProcessor(
+  +    GitLabDiscoveryProcessor.fromConfig(env.config, { logger: env.logger })
+  +  );
+  ```
+
+  **BREAKING**: Removed `AzureDevOpsDiscoveryProcessor`, which now instead should be imported from `@backstage/plugin-catalog-backend-module-azure`. This processor was not part of the set of default processors. If you were using it, you should already have a reference to it in your backend code and only need to update the import.
+
+- f115a7f8fd: **BREAKING**: Removed `AwsS3DiscoveryProcessor`, which now instead should be imported from `@backstage/plugin-catalog-backend-module-aws`.
+- 55150919ed: - **BREAKING**: Support for `backstage.io/v1beta2` Software Templates has been removed. Please migrate your legacy templates to the new `scaffolder.backstage.io/v1beta3` `apiVersion` by following the [migration guide](https://backstage.io/docs/features/software-templates/migrating-from-v1beta2-to-v1beta3)
+
+### Patch Changes
+
+- ab7cd7d70e: Do some groundwork for supporting the `better-sqlite3` driver, to maybe eventually replace `@vscode/sqlite3` (#9912)
+- e0a69ba49f: build(deps): bump `fs-extra` from 9.1.0 to 10.0.1
+- 616f02ade2: support Bitbucket Cloud's code search to discover catalog files (multiple per repo, Location entities for existing files only)
+- e421d77536: **BREAKING**:
+
+  - Removed the previously deprecated `runPeriodically` export. Please use the `@backstage/backend-tasks` package instead, or copy [the actual implementation](https://github.com/backstage/backstage/blob/02875d4d56708c60f86f6b0a5b3da82e24988354/plugins/catalog-backend/src/util/runPeriodically.ts#L29) into your own code if you explicitly do not want coordination of task runs across your worker nodes.
+  - Removed the previously deprecated `CatalogProcessorLocationResult.optional` field. Please set the corresponding `LocationSpec.presence` field to `'optional'` instead.
+  - Related to the previous point, the `processingResult.location` function no longer has a second boolean `optional` argument. Please set the corresponding `LocationSpec.presence` field to `'optional'` instead.
+  - Removed the previously deprecated `StaticLocationProcessor`. It has not been in use for some time; its functionality is covered by `ConfigLocationEntityProvider` instead.
+
+- 3c2bc73901: Use `setupRequestMockHandlers` from `@backstage/backend-test-utils`
+- c1168bb440: Fixed display of the location in the log message that is printed when entity envelope validation fails.
+- b1aacbf96a: Applied the fix for the `/alpha` entry point resolution that was part of the `v0.70.1` release of Backstage.
+- 3e54f6c436: Use `@backstage/plugin-search-common` package instead of `@backstage/search-common`.
+- Updated dependencies
+  - @backstage/backend-common@0.13.0-next.0
+  - @backstage/plugin-scaffolder-common@0.3.0-next.0
+  - @backstage/catalog-model@0.13.0-next.0
+  - @backstage/plugin-catalog-common@0.2.2-next.0
+  - @backstage/plugin-search-common@0.3.1-next.0
+  - @backstage/catalog-client@0.9.0-next.0
+  - @backstage/plugin-permission-node@0.5.4-next.0
+
+## 0.23.1
+
+### Patch Changes
+
+- Marked `GithubMultiOrgReaderProcessor` as stable, as it was moved to `/alpha` by mistake.
+- Fixed runtime resolution of the `/alpha` entry point.
+- Updated dependencies
+  - @backstage/backend-common@0.12.1
+  - @backstage/catalog-model@0.12.1
+  - @backstage/plugin-catalog-common@0.2.1
+
 ## 0.23.0
 
 ### Minor Changes

package/alpha/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/plugin-catalog-backend",
-  "version": "0.23.0",
-  "main": "..",
+  "version": "0.24.0",
+  "main": "../dist/index.cjs.js",
   "types": "../dist/index.alpha.d.ts"
 }

package/dist/index.alpha.d.ts

@@ -6,20 +6,17 @@
 
 /// <reference types="node" />
 
-import { BitbucketIntegration } from '@backstage/integration';
 import { CatalogApi } from '@backstage/catalog-client';
 import { CatalogEntityDocument as CatalogEntityDocument_2 } from '@backstage/plugin-catalog-common';
 import { CompoundEntityRef } from '@backstage/catalog-model';
 import { ConditionalPolicyDecision } from '@backstage/plugin-permission-node';
 import { Conditions } from '@backstage/plugin-permission-node';
 import { Config } from '@backstage/config';
-import { DocumentCollatorFactory } from '@backstage/search-common';
+import { DocumentCollatorFactory } from '@backstage/plugin-search-common';
 import { Entity } from '@backstage/catalog-model';
 import { EntityPolicy } from '@backstage/catalog-model';
 import express from 'express';
 import { GetEntitiesRequest } from '@backstage/catalog-client';
-import { GithubCredentialsProvider } from '@backstage/integration';
-import { GitHubIntegrationConfig } from '@backstage/integration';
 import { JsonObject } from '@backstage/types';
 import { JsonValue } from '@backstage/types';
 import { Location as Location_2 } from '@backstage/catalog-client';
@@ -77,7 +74,7 @@ export declare type AnalyzeLocationExistingEntity = {
  * enough info for the frontend to know what form data to show to the user
  * for overriding/completing the info.
  * @public
- * */
+ */
 export declare type AnalyzeLocationGenerateEntity = {
     entity: RecursivePartial<Entity>;
     fields: AnalyzeLocationEntityField[];
@@ -115,83 +112,6 @@ export declare class AnnotateScmSlugEntityProcessor implements CatalogProcessor
     preProcessEntity(entity: Entity, location: LocationSpec): Promise<Entity>;
 }
 
-/** @public */
-export declare class AwsS3DiscoveryProcessor implements CatalogProcessor {
-    private readonly reader;
-    constructor(reader: UrlReader);
-    getProcessorName(): string;
-    readLocation(location: LocationSpec, optional: boolean, emit: CatalogProcessorEmit, parser: CatalogProcessorParser): Promise<boolean>;
-    private doRead;
-}
-
-/**
- * Extracts repositories out of an Azure DevOps org.
- *
- * The following will create locations for all projects which have a catalog-info.yaml
- * on the default branch. The first is shorthand for the second.
- *
- *    target: "https://dev.azure.com/org/project"
- *    or
- *    target: https://dev.azure.com/org/project?path=/catalog-info.yaml
- *
- * You may also explicitly specify a single repo:
- *
- *    target: https://dev.azure.com/org/project/_git/repo
- *
- * @public
- **/
-export declare class AzureDevOpsDiscoveryProcessor implements CatalogProcessor {
-    private readonly integrations;
-    private readonly logger;
-    static fromConfig(config: Config, options: {
-        logger: Logger;
-    }): AzureDevOpsDiscoveryProcessor;
-    constructor(options: {
-        integrations: ScmIntegrationRegistry;
-        logger: Logger;
-    });
-    getProcessorName(): string;
-    readLocation(location: LocationSpec, _optional: boolean, emit: CatalogProcessorEmit): Promise<boolean>;
-}
-
-/** @public */
-export declare class BitbucketDiscoveryProcessor implements CatalogProcessor {
-    private readonly integrations;
-    private readonly parser;
-    private readonly logger;
-    static fromConfig(config: Config, options: {
-        parser?: (options: {
-            integration: BitbucketIntegration;
-            target: string;
-            logger: Logger;
-        }) => AsyncIterable<CatalogProcessorResult>;
-        logger: Logger;
-    }): BitbucketDiscoveryProcessor;
-    constructor(options: {
-        integrations: ScmIntegrationRegistry;
-        parser?: (options: {
-            integration: BitbucketIntegration;
-            target: string;
-            logger: Logger;
-        }) => AsyncIterable<CatalogProcessorResult>;
-        logger: Logger;
-    });
-    getProcessorName(): string;
-    readLocation(location: LocationSpec, _optional: boolean, emit: CatalogProcessorEmit): Promise<boolean>;
-    private processCloudRepositories;
-    private processOrganisationRepositories;
-}
-
-/**
- * @public
- * @deprecated type inlined.
- */
-export declare type BitbucketRepositoryParser = (options: {
-    integration: BitbucketIntegration;
-    target: string;
-    logger: Logger;
-}) => AsyncIterable<CatalogProcessorResult>;
-
 /** @public */
 export declare class BuiltinKindsEntityProcessor implements CatalogProcessor {
     private readonly validators;
@@ -383,6 +303,7 @@ export declare class CatalogBuilder {
     private buildEntityPolicy;
     private buildProcessors;
     private checkDeprecatedReaderProcessors;
+    private checkMissingExternalProcessors;
 }
 
 /**
@@ -424,7 +345,7 @@ export declare interface CatalogProcessingEngine {
 /**
  * Responsible for executing the individual processing steps in order to fully process an entity.
  * @public
- * */
+ */
 export declare interface CatalogProcessingOrchestrator {
     process(request: EntityProcessingRequest): Promise<EntityProcessingResult>;
 }
@@ -539,8 +460,6 @@ export declare type CatalogProcessorErrorResult = {
 export declare type CatalogProcessorLocationResult = {
     type: 'location';
     location: LocationSpec;
-    /** @deprecated Set `location.presence = 'optional'` instead  */
-    optional?: boolean;
 };
 
 /**
@@ -818,7 +737,7 @@ export declare class DefaultCatalogRulesEnforcer implements CatalogRulesEnforcer
 /**
  * Entities that are not yet processed.
  * @public
- * */
+ */
 export declare type DeferredEntity = {
     entity: Entity;
     locationKey?: string;
@@ -1068,146 +987,6 @@ export declare class FileReaderProcessor implements CatalogProcessor {
  */
 declare function generalError(atLocation: LocationSpec, message: string): CatalogProcessorResult;
 
-/**
- * Extracts repositories out of a GitHub org.
- *
- * The following will create locations for all projects which have a catalog-info.yaml
- * on the default branch. The first is shorthand for the second.
- *
- *    target: "https://github.com/backstage"
- *    or
- *    target: https://github.com/backstage/*\/blob/-/catalog-info.yaml
- *
- * You may also explicitly specify the source branch:
- *
- *    target: https://github.com/backstage/*\/blob/main/catalog-info.yaml
- *
- * @public
- **/
-export declare class GithubDiscoveryProcessor implements CatalogProcessor {
-    private readonly integrations;
-    private readonly logger;
-    private readonly githubCredentialsProvider;
-    static fromConfig(config: Config, options: {
-        logger: Logger;
-        githubCredentialsProvider?: GithubCredentialsProvider;
-    }): GithubDiscoveryProcessor;
-    constructor(options: {
-        integrations: ScmIntegrationRegistry;
-        logger: Logger;
-        githubCredentialsProvider?: GithubCredentialsProvider;
-    });
-    getProcessorName(): string;
-    readLocation(location: LocationSpec, _optional: boolean, emit: CatalogProcessorEmit): Promise<boolean>;
-}
-
-/**
- * The configuration parameters for a multi-org GitHub processor.
- * @public
- */
-export declare type GithubMultiOrgConfig = Array<{
-    /**
-     * The name of the GitHub org to process.
-     */
-    name: string;
-    /**
-     * The namespace of the group created for this org.
-     */
-    groupNamespace: string;
-    /**
-     * The namespace of the users created for this org. If not specified defaults to undefined.
-     */
-    userNamespace: string | undefined;
-}>;
-
-/**
- * @alpha
- * Extracts teams and users out of a multiple GitHub orgs namespaced per org.
- *
- * Be aware that this processor may not be compatible with future org structures in the catalog.
- */
-export declare class GithubMultiOrgReaderProcessor implements CatalogProcessor {
-    private readonly integrations;
-    private readonly orgs;
-    private readonly logger;
-    private readonly githubCredentialsProvider;
-    static fromConfig(config: Config, options: {
-        logger: Logger;
-        githubCredentialsProvider?: GithubCredentialsProvider;
-    }): GithubMultiOrgReaderProcessor;
-    constructor(options: {
-        integrations: ScmIntegrationRegistry;
-        logger: Logger;
-        orgs: GithubMultiOrgConfig;
-        githubCredentialsProvider?: GithubCredentialsProvider;
-    });
-    getProcessorName(): string;
-    readLocation(location: LocationSpec, _optional: boolean, emit: CatalogProcessorEmit): Promise<boolean>;
-    private getAllOrgs;
-}
-
-/** @public */
-export declare class GitHubOrgEntityProvider implements EntityProvider {
-    private options;
-    private connection?;
-    private githubCredentialsProvider;
-    static fromConfig(config: Config, options: {
-        id: string;
-        orgUrl: string;
-        logger: Logger;
-        githubCredentialsProvider?: GithubCredentialsProvider;
-    }): GitHubOrgEntityProvider;
-    constructor(options: {
-        id: string;
-        orgUrl: string;
-        gitHubConfig: GitHubIntegrationConfig;
-        logger: Logger;
-        githubCredentialsProvider?: GithubCredentialsProvider;
-    });
-    getProviderName(): string;
-    connect(connection: EntityProviderConnection): Promise<void>;
-    read(): Promise<void>;
-}
-
-/**
- * Extracts teams and users out of a GitHub org.
- * @public
- */
-export declare class GithubOrgReaderProcessor implements CatalogProcessor {
-    private readonly integrations;
-    private readonly logger;
-    private readonly githubCredentialsProvider;
-    static fromConfig(config: Config, options: {
-        logger: Logger;
-        githubCredentialsProvider?: GithubCredentialsProvider;
-    }): GithubOrgReaderProcessor;
-    constructor(options: {
-        integrations: ScmIntegrationRegistry;
-        logger: Logger;
-        githubCredentialsProvider?: GithubCredentialsProvider;
-    });
-    getProcessorName(): string;
-    readLocation(location: LocationSpec, _optional: boolean, emit: CatalogProcessorEmit): Promise<boolean>;
-    private createClient;
-}
-
-/**
- * Extracts repositories out of an GitLab instance.
- * @public
- */
-export declare class GitLabDiscoveryProcessor implements CatalogProcessor {
-    private readonly integrations;
-    private readonly logger;
-    private readonly cache;
-    static fromConfig(config: Config, options: {
-        logger: Logger;
-    }): GitLabDiscoveryProcessor;
-    private constructor();
-    getProcessorName(): string;
-    readLocation(location: LocationSpec, _optional: boolean, emit: CatalogProcessorEmit): Promise<boolean>;
-    private updateLastActivity;
-}
-
 /**
  * @public
  * @deprecated import the processingResult symbol instead and use its fields
@@ -1218,7 +997,7 @@ declare function inputError(atLocation: LocationSpec, message: string): CatalogP
  * @public
  * @deprecated import the processingResult symbol instead and use its fields
  */
-declare function location_2(newLocation: LocationSpec, optional?: boolean): CatalogProcessorResult;
+declare function location_2(newLocation: LocationSpec, _optional?: boolean): CatalogProcessorResult;
 
 /** @public */
 export declare type LocationAnalyzer = {
@@ -1298,7 +1077,8 @@ export declare type LocationSpec = {
 
 /**
  * Interacts with the database to manage locations.
- * @public */
+ * @public
+ */
 export declare interface LocationStore {
     createLocation(location: LocationInput): Promise<Location_2>;
     listLocations(): Promise<Location_2[]>;
@@ -1390,7 +1170,7 @@ export declare const processingResult: Readonly<{
     readonly notFoundError: (atLocation: LocationSpec, message: string) => CatalogProcessorResult;
     readonly inputError: (atLocation: LocationSpec, message: string) => CatalogProcessorResult;
     readonly generalError: (atLocation: LocationSpec, message: string) => CatalogProcessorResult;
-    readonly location: (newLocation: LocationSpec, optional?: boolean | undefined) => CatalogProcessorResult;
+    readonly location: (newLocation: LocationSpec) => CatalogProcessorResult;
     readonly entity: (atLocation: LocationSpec, newEntity: Entity) => CatalogProcessorResult;
     readonly relation: (spec: EntityRelationSpec) => CatalogProcessorResult;
 }>;
@@ -1466,31 +1246,6 @@ export declare interface RouterOptions {
     permissionIntegrationRouter?: express.Router;
 }
 
-/**
- * Runs a function repeatedly, with a fixed wait between invocations.
- *
- * Supports async functions, and silently ignores exceptions and rejections.
- *
- * @param fn - The function to run. May return a Promise.
- * @param delayMs - The delay between a completed function invocation and the
- *                next.
- * @returns A function that, when called, stops the invocation loop.
- * @deprecated use \@backstage/backend-tasks package instead.
- * @public
- */
-export declare function runPeriodically(fn: () => any, delayMs: number): () => void;
-
-/**
- * @deprecated no longer in use, replaced by the ConfigLocationEntityProvider.
- * @public
- */
-export declare class StaticLocationProcessor implements StaticLocationProcessor {
-    private readonly staticLocations;
-    static fromConfig(config: Config): StaticLocationProcessor;
-    constructor(staticLocations: LocationSpec[]);
-    readLocation(location: LocationSpec, _optional: boolean, emit: CatalogProcessorEmit): Promise<boolean>;
-}
-
 /** @public */
 export declare class UrlReaderProcessor implements CatalogProcessor {
     private readonly options;