Merge pull request #10092 from backstage/freben/separate-bitbucket

move out bitbucket into a separate module too

.changeset/clever-garlics-rescue.md

@@ -17,4 +17,21 @@
 +  );
 ```
 
+**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`.

.changeset/silent-mugs-roll.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-backend-module-bitbucket': minor
+---
+
+Added package, moving out Bitbucket specific functionality from the catalog-backend

.github/styles/vocab.txt

@@ -24,7 +24,7 @@ backported
 backporting
 Bigtable
 Billett
-Bitbucket
+bitbucket
 Bitrise
 Blackbox
 bool

docs/integrations/bitbucket/discovery.md

@@ -11,6 +11,34 @@ catalog entities located in Bitbucket. The processor will crawl your Bitbucket
 account and register entities matching the configured path. This can be useful
 as an alternative to static locations or manually adding things to the catalog.
 
+## Installation
+
+You will have to add the processor in the catalog initialization code of your
+backend. The provider is not installed by default, therefore you have to add a
+dependency to `@backstage/plugin-catalog-backend-module-bitbucket` to your backend
+package.
+
+```bash
+# From your Backstage root directory
+cd packages/backend
+yarn add @backstage/plugin-catalog-backend-module-bitbucket
+```
+
+And then add the processor to your catalog builder:
+
+```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 })
++  );
+```
+
 ## Self-hosted Bitbucket Server
 
 To use the discovery processor with a self-hosted Bitbucket Server, you'll need
@@ -137,14 +165,11 @@ matching repository is processed.
 repository.
 
 ```typescript
-const customRepositoryParser: BitbucketRepositoryParser =
-  async function* customRepositoryParser({ client, repository }) {
-    // Custom logic for interpret the matching repository.
-    // See defaultRepositoryParser for an example
-  };
-
 const processor = BitbucketDiscoveryProcessor.fromConfig(env.config, {
-  parser: customRepositoryParser,
+  parser: async function* customRepositoryParser({ client, repository }) {
+    // Custom logic for interpreting the matching repository.
+    // See defaultRepositoryParser for an example
+  },
   logger: env.logger,
 });
 ```

plugins/catalog-backend-module-azure/.eslintrc.js

@@ -1,3 +1 @@
-module.exports = {
-  extends: [require.resolve('@backstage/cli/config/eslint.backend')],
-};
+module.exports = require('@backstage/cli/config/eslint-factory')(__dirname);

plugins/catalog-backend-module-bitbucket/.eslintrc.js

@@ -0,0 +1 @@
+module.exports = require('@backstage/cli/config/eslint-factory')(__dirname);

plugins/catalog-backend-module-bitbucket/README.md

@@ -0,0 +1,8 @@
+# Catalog Backend Module for Bitbucket
+
+This is an extension module to the plugin-catalog-backend plugin, providing extensions targeted at Bitbucket offerings.
+
+## Getting started
+
+See [Backstage documentation](https://backstage.io/docs/integrations/bitbucket/discovery) for details on how to install
+and configure the plugin.

plugins/catalog-backend-module-bitbucket/api-report.md

@@ -0,0 +1,47 @@
+## API Report File for "@backstage/plugin-catalog-backend-module-bitbucket"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+import { BitbucketIntegration } from '@backstage/integration';
+import { CatalogProcessor } from '@backstage/plugin-catalog-backend';
+import { CatalogProcessorEmit } from '@backstage/plugin-catalog-backend';
+import { CatalogProcessorResult } from '@backstage/plugin-catalog-backend';
+import { Config } from '@backstage/config';
+import { LocationSpec } from '@backstage/plugin-catalog-backend';
+import { Logger } from 'winston';
+import { ScmIntegrationRegistry } from '@backstage/integration';
+
+// @public (undocumented)
+export class BitbucketDiscoveryProcessor implements CatalogProcessor {
+  constructor(options: {
+    integrations: ScmIntegrationRegistry;
+    parser?: BitbucketRepositoryParser;
+    logger: Logger;
+  });
+  // (undocumented)
+  static fromConfig(
+    config: Config,
+    options: {
+      parser?: BitbucketRepositoryParser;
+      logger: Logger;
+    },
+  ): BitbucketDiscoveryProcessor;
+  // (undocumented)
+  getProcessorName(): string;
+  // (undocumented)
+  readLocation(
+    location: LocationSpec,
+    _optional: boolean,
+    emit: CatalogProcessorEmit,
+  ): Promise<boolean>;
+}
+
+// @public
+export type BitbucketRepositoryParser = (options: {
+  integration: BitbucketIntegration;
+  target: string;
+  presence?: 'optional' | 'required';
+  logger: Logger;
+}) => AsyncIterable<CatalogProcessorResult>;
+```

plugins/catalog-backend-module-bitbucket/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@backstage/plugin-catalog-backend-module-bitbucket",
+  "description": "A Backstage catalog backend module that helps integrate towards Bitbucket",
+  "version": "0.0.0",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "license": "Apache-2.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.cjs.js",
+    "types": "dist/index.d.ts"
+  },
+  "backstage": {
+    "role": "backend-plugin-module"
+  },
+  "homepage": "https://backstage.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/backstage/backstage",
+    "directory": "plugins/catalog-backend-module-bitbucket"
+  },
+  "keywords": [
+    "backstage"
+  ],
+  "scripts": {
+    "build": "backstage-cli package build",
+    "lint": "backstage-cli package lint",
+    "test": "backstage-cli package test",
+    "prepack": "backstage-cli package prepack",
+    "postpack": "backstage-cli package postpack",
+    "clean": "backstage-cli package clean",
+    "start": "backstage-cli package start"
+  },
+  "dependencies": {
+    "@backstage/backend-common": "^0.13.0-next.0",
+    "@backstage/catalog-model": "^0.13.0-next.0",
+    "@backstage/config": "^0.1.15",
+    "@backstage/errors": "^0.2.2",
+    "@backstage/integration": "^0.8.0",
+    "@backstage/plugin-catalog-backend": "^0.24.0-next.0",
+    "@backstage/types": "^0.1.3",
+    "lodash": "^4.17.21",
+    "msw": "^0.35.0",
+    "node-fetch": "^2.6.7",
+    "winston": "^3.2.1"
+  },
+  "devDependencies": {
+    "@backstage/backend-test-utils": "^0.1.21-next.0",
+    "@backstage/cli": "^0.15.2-next.0",
+    "@types/lodash": "^4.14.151"
+  },
+  "files": [
+    "dist"
+  ]
+}

plugins/catalog-backend-module-bitbucket/src/BitbucketDiscoveryProcessor.test.ts

@@ -15,12 +15,15 @@
  */
 
 import { getVoidLogger } from '@backstage/backend-common';
-import { BitbucketDiscoveryProcessor } from './BitbucketDiscoveryProcessor';
 import { ConfigReader } from '@backstage/config';
+import {
+  LocationSpec,
+  processingResult,
+} from '@backstage/plugin-catalog-backend';
 import { RequestHandler, rest } from 'msw';
 import { setupServer } from 'msw/node';
+import { BitbucketDiscoveryProcessor } from './BitbucketDiscoveryProcessor';
 import { BitbucketRepository20, PagedResponse, PagedResponse20 } from './lib';
-import { LocationSpec, processingResult } from '../../api';
 
 const server = setupServer();
 

plugins/catalog-backend-module-bitbucket/src/BitbucketDiscoveryProcessor.ts

@@ -14,28 +14,27 @@
  * limitations under the License.
  */
 
-import { Logger } from 'winston';
 import { Config } from '@backstage/config';
-
 import {
   BitbucketIntegration,
   ScmIntegrationRegistry,
   ScmIntegrations,
 } from '@backstage/integration';
+import {
+  CatalogProcessor,
+  CatalogProcessorEmit,
+  LocationSpec,
+} from '@backstage/plugin-catalog-backend';
+import { Logger } from 'winston';
 import {
   BitbucketClient,
+  BitbucketRepository,
+  BitbucketRepository20,
+  BitbucketRepositoryParser,
   defaultRepositoryParser,
   paginated,
   paginated20,
-  BitbucketRepository,
-  BitbucketRepository20,
 } from './lib';
-import {
-  CatalogProcessor,
-  CatalogProcessorEmit,
-  CatalogProcessorResult,
-  LocationSpec,
-} from '../../api';
 
 const DEFAULT_BRANCH = 'master';
 const DEFAULT_CATALOG_LOCATION = '/catalog-info.yaml';
@@ -43,23 +42,13 @@ const DEFAULT_CATALOG_LOCATION = '/catalog-info.yaml';
 /** @public */
 export class BitbucketDiscoveryProcessor implements CatalogProcessor {
   private readonly integrations: ScmIntegrationRegistry;
-  private readonly parser: (options: {
-    integration: BitbucketIntegration;
-    target: string;
-    presence?: 'optional' | 'required';
-    logger: Logger;
-  }) => AsyncIterable<CatalogProcessorResult>;
+  private readonly parser: BitbucketRepositoryParser;
   private readonly logger: Logger;
 
   static fromConfig(
     config: Config,
     options: {
-      parser?: (options: {
-        integration: BitbucketIntegration;
-        target: string;
-        presence?: 'optional' | 'required';
-        logger: Logger;
-      }) => AsyncIterable<CatalogProcessorResult>;
+      parser?: BitbucketRepositoryParser;
       logger: Logger;
     },
   ) {
@@ -73,12 +62,7 @@ export class BitbucketDiscoveryProcessor implements CatalogProcessor {
 
   constructor(options: {
     integrations: ScmIntegrationRegistry;
-    parser?: (options: {
-      integration: BitbucketIntegration;
-      target: string;
-      presence?: 'optional' | 'required';
-      logger: Logger;
-    }) => AsyncIterable<CatalogProcessorResult>;
+    parser?: BitbucketRepositoryParser;
     logger: Logger;
   }) {
     this.integrations = options.integrations;
@@ -123,7 +107,7 @@ export class BitbucketDiscoveryProcessor implements CatalogProcessor {
 
     const { scanned, matches } = isBitbucketCloud
       ? await this.processCloudRepositories(processOptions)
-      : await this.processOrganisationRepositories(processOptions);
+      : await this.processOrganizationRepositories(processOptions);
 
     const duration = ((Date.now() - startTimestamp) / 1000).toFixed(1);
     this.logger.debug(
@@ -160,7 +144,7 @@ export class BitbucketDiscoveryProcessor implements CatalogProcessor {
     };
   }
 
-  private async processOrganisationRepositories(
+  private async processOrganizationRepositories(
     options: ProcessOptions,
   ): Promise<ResultSummary> {
     const { client, location, integration, emit } = options;

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

@@ -0,0 +1,24 @@
+/*
+ * Copyright 2020 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.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * A Backstage catalog backend module that helps integrate towards Bitbucket
+ *
+ * @packageDocumentation
+ */
+
+export { BitbucketDiscoveryProcessor } from './BitbucketDiscoveryProcessor';
+export type { BitbucketRepositoryParser } from './lib/BitbucketRepositoryParser';

plugins/catalog-backend-module-bitbucket/src/lib/BitbucketRepositoryParser.test.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { processingResult } from '../../../api';
+import { processingResult } from '@backstage/plugin-catalog-backend';
 import { defaultRepositoryParser } from './BitbucketRepositoryParser';
 
 describe('BitbucketRepositoryParser', () => {

plugins/catalog-backend-module-bitbucket/src/lib/BitbucketRepositoryParser.ts

@@ -15,12 +15,17 @@
  */
 
 import { BitbucketIntegration } from '@backstage/integration';
+import {
+  CatalogProcessorResult,
+  processingResult,
+} from '@backstage/plugin-catalog-backend';
 import { Logger } from 'winston';
-import { CatalogProcessorResult, processingResult } from '../../../api';
 
 /**
+ * A custom callback that reacts to finding a repository by yielding processing
+ * results.
+ *
  * @public
- * @deprecated type inlined.
  */
 export type BitbucketRepositoryParser = (options: {
   integration: BitbucketIntegration;

plugins/catalog-backend-module-bitbucket/src/lib/client.ts

@@ -14,11 +14,11 @@
  * limitations under the License.
  */
 
-import fetch from 'node-fetch';
 import {
   BitbucketIntegrationConfig,
   getBitbucketRequestOptions,
 } from '@backstage/integration';
+import fetch from 'node-fetch';
 import { BitbucketRepository20 } from './types';
 
 export class BitbucketClient {

plugins/catalog-backend-module-bitbucket/src/lib/index.ts

@@ -14,8 +14,8 @@
  * limitations under the License.
  */
 
-export { BitbucketClient, paginated, paginated20 } from './client';
 export { defaultRepositoryParser } from './BitbucketRepositoryParser';
+export type { BitbucketRepositoryParser } from './BitbucketRepositoryParser';
+export { BitbucketClient, paginated, paginated20 } from './client';
 export type { PagedResponse, PagedResponse20 } from './client';
 export type { BitbucketRepository, BitbucketRepository20 } from './types';
-export type { BitbucketRepositoryParser } from './BitbucketRepositoryParser';

plugins/catalog-backend-module-bitbucket/src/setupTests.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright 2022 The Backstage Authors
+ * Copyright 2020 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,5 +14,4 @@
  * limitations under the License.
  */
 
-export { BitbucketDiscoveryProcessor } from './BitbucketDiscoveryProcessor';
-export type { BitbucketRepositoryParser } from './lib';
+export {};

plugins/catalog-backend-module-gitlab/.eslintrc.js

@@ -1,3 +1 @@
-module.exports = {
-  extends: [require.resolve('@backstage/cli/config/eslint.backend')],
-};
+module.exports = require('@backstage/cli/config/eslint-factory')(__dirname);

plugins/catalog-backend/api-report.md

@@ -5,7 +5,6 @@
 ```ts
 /// <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';
@@ -97,49 +96,6 @@ export class AnnotateScmSlugEntityProcessor implements CatalogProcessor {
   preProcessEntity(entity: Entity, location: LocationSpec): Promise<Entity>;
 }
 
-// @public (undocumented)
-export class BitbucketDiscoveryProcessor implements CatalogProcessor {
-  constructor(options: {
-    integrations: ScmIntegrationRegistry;
-    parser?: (options: {
-      integration: BitbucketIntegration;
-      target: string;
-      presence?: 'optional' | 'required';
-      logger: Logger;
-    }) => AsyncIterable<CatalogProcessorResult>;
-    logger: Logger;
-  });
-  // (undocumented)
-  static fromConfig(
-    config: Config,
-    options: {
-      parser?: (options: {
-        integration: BitbucketIntegration;
-        target: string;
-        presence?: 'optional' | 'required';
-        logger: Logger;
-      }) => AsyncIterable<CatalogProcessorResult>;
-      logger: Logger;
-    },
-  ): BitbucketDiscoveryProcessor;
-  // (undocumented)
-  getProcessorName(): string;
-  // (undocumented)
-  readLocation(
-    location: LocationSpec,
-    _optional: boolean,
-    emit: CatalogProcessorEmit,
-  ): Promise<boolean>;
-}
-
-// @public @deprecated (undocumented)
-export type BitbucketRepositoryParser = (options: {
-  integration: BitbucketIntegration;
-  target: string;
-  presence?: 'optional' | 'required';
-  logger: Logger;
-}) => AsyncIterable<CatalogProcessorResult>;
-
 // @public (undocumented)
 export class BuiltinKindsEntityProcessor implements CatalogProcessor {
   // (undocumented)

plugins/catalog-backend/src/modules/index.ts

@@ -14,7 +14,6 @@
  * limitations under the License.
  */
 
-export * from './bitbucket';
 export * from './codeowners';
 export * from './core';
 export * from './github';

plugins/catalog-backend/src/service/CatalogBuilder.ts

@@ -45,7 +45,6 @@ import {
 } from '../api';
 import {
   AnnotateLocationEntityProcessor,
-  BitbucketDiscoveryProcessor,
   BuiltinKindsEntityProcessor,
   CodeOwnersProcessor,
   FileReaderProcessor,
@@ -357,7 +356,6 @@ export class CatalogBuilder {
 
     return [
       new FileReaderProcessor(),
-      BitbucketDiscoveryProcessor.fromConfig(config, { logger }),
       GithubDiscoveryProcessor.fromConfig(config, {
         logger,
         githubCredentialsProvider,