catalog-node: update catalogAnalysisExtensionPoint

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

.changeset/brave-carrots-glow.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-node': minor
+---
+
+Added `LocationAnalyzer` type, moved from `@backstage/plugin-catalog-backend`.

.changeset/early-starfishes-hammer.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-backend': minor
+---
+
+Deprecated the `LocationAnalyzer` type, which has been moved to `@backstage/plugin-catalog-node`.

.changeset/happy-radios-kiss.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-backend': minor
+---
+
+The `/alpha` plugin export has had its implementation of the `catalogAnalysisExtensionPoint` updated to reflect the new API.

.changeset/rich-adults-float.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-backend-module-github': patch
+---
+
+Updated to use the new `catalogAnalysisExtensionPoint` API.

.changeset/tough-eggs-wink.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-node': minor
+---
+
+Breaking change to `/alpha` API where the `catalogAnalysisExtensionPoint` has been reworked. The `addLocationAnalyzer` method has been renamed to `addScmLocationAnalyzer`, and a new `setLocationAnalyzer` method has been added which allows the full `LocationAnalyzer` implementation to be overridden.

plugins/catalog-backend-module-github/src/module/githubCatalogModule.test.ts

@@ -37,7 +37,8 @@ describe('githubCatalogModule', () => {
     };
 
     const analysisExtensionPoint = {
-      addLocationAnalyzer: jest.fn(),
+      setLocationAnalyzer: jest.fn(),
+      addScmLocationAnalyzer: jest.fn(),
     };
 
     const runner = jest.fn();
@@ -81,7 +82,7 @@ describe('githubCatalogModule', () => {
       'github-provider:default',
     );
     expect(runner).not.toHaveBeenCalled();
-    expect(analysisExtensionPoint.addLocationAnalyzer).toHaveBeenCalledWith(
+    expect(analysisExtensionPoint.addScmLocationAnalyzer).toHaveBeenCalledWith(
       expect.any(GithubLocationAnalyzer),
     );
   });

plugins/catalog-backend-module-github/src/module/githubCatalogModule.ts

@@ -56,7 +56,7 @@ export const githubCatalogModule = createBackendModule({
         discovery,
         auth,
       }) {
-        analyzers.addLocationAnalyzer(
+        analyzers.addScmLocationAnalyzer(
           new GithubLocationAnalyzer({
             discovery,
             config,

plugins/catalog-backend/api-report.md

@@ -41,6 +41,7 @@ import { EntityRelationSpec as EntityRelationSpec_2 } from '@backstage/plugin-ca
 import { EventBroker } from '@backstage/plugin-events-node';
 import { GetEntitiesRequest } from '@backstage/catalog-client';
 import { HttpAuthService } from '@backstage/backend-plugin-api';
+import { LocationAnalyzer as LocationAnalyzer_2 } from '@backstage/plugin-catalog-node';
 import { LocationSpec as LocationSpec_2 } from '@backstage/plugin-catalog-common';
 import { locationSpecToLocationEntity as locationSpecToLocationEntity_2 } from '@backstage/plugin-catalog-node';
 import { locationSpecToMetadataName as locationSpecToMetadataName_2 } from '@backstage/plugin-catalog-node';
@@ -167,7 +168,7 @@ export class CatalogBuilder {
   setEntityDataParser(parser: CatalogProcessorParser_2): CatalogBuilder;
   setEventBroker(broker: EventBroker): CatalogBuilder;
   setFieldFormatValidators(validators: Partial<Validators>): CatalogBuilder;
-  setLocationAnalyzer(locationAnalyzer: LocationAnalyzer): CatalogBuilder;
+  setLocationAnalyzer(locationAnalyzer: LocationAnalyzer_2): CatalogBuilder;
   setPlaceholderResolver(
     key: string,
     resolver: PlaceholderResolver_2,
@@ -359,12 +360,8 @@ export class FileReaderProcessor implements CatalogProcessor_2 {
   ): Promise<boolean>;
 }
 
-// @public (undocumented)
-export type LocationAnalyzer = {
-  analyzeLocation(
-    location: AnalyzeLocationRequest_2,
-  ): Promise<AnalyzeLocationResponse_2>;
-};
+// @public @deprecated (undocumented)
+export type LocationAnalyzer = LocationAnalyzer_2;
 
 // @public @deprecated
 export class LocationEntityProcessor implements CatalogProcessor_2 {

plugins/catalog-backend/src/deprecated.ts

@@ -48,6 +48,7 @@ import {
   type PlaceholderResolverParams as _PlaceholderResolverParams,
   type PlaceholderResolverRead as _PlaceholderResolverRead,
   type PlaceholderResolverResolveUrl as _PlaceholderResolverResolveUrl,
+  type LocationAnalyzer as _LocationAnalyzer,
   type ScmLocationAnalyzer as _ScmLocationAnalyzer,
 } from '@backstage/plugin-catalog-node';
 import {
@@ -177,6 +178,11 @@ export type LocationSpec = _LocationSpec;
  * @deprecated import from `@backstage/plugin-catalog-node` instead
  */
 export type AnalyzeOptions = _AnalyzeOptions;
+/**
+ * @public
+ * @deprecated import from `@backstage/plugin-catalog-node` instead
+ */
+export type LocationAnalyzer = _LocationAnalyzer;
 /**
  * @public
  * @deprecated import from `@backstage/plugin-catalog-node` instead

plugins/catalog-backend/src/index.ts

@@ -20,7 +20,6 @@
  * @packageDocumentation
  */
 
-export * from './ingestion';
 export * from './modules';
 export * from './processing';
 export * from './search';

plugins/catalog-backend/src/ingestion/LocationAnalyzer.ts

@@ -17,12 +17,14 @@
 import parseGitUrl from 'git-url-parse';
 import { Entity } from '@backstage/catalog-model';
 import { ScmIntegrationRegistry } from '@backstage/integration';
-import { LocationAnalyzer } from './types';
 import {
   AnalyzeLocationRequest,
   AnalyzeLocationResponse,
 } from '@backstage/plugin-catalog-common';
-import { ScmLocationAnalyzer } from '@backstage/plugin-catalog-node';
+import {
+  LocationAnalyzer,
+  ScmLocationAnalyzer,
+} from '@backstage/plugin-catalog-node';
 import { LoggerService } from '@backstage/backend-plugin-api';
 
 export class RepoLocationAnalyzer implements LocationAnalyzer {

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

@@ -1,17 +0,0 @@
-/*
- * 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.
- */
-
-export type { LocationAnalyzer } from './types';

plugins/catalog-backend/src/ingestion/types.ts

@@ -1,33 +0,0 @@
-/*
- * 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.
- */
-
-import {
-  AnalyzeLocationRequest,
-  AnalyzeLocationResponse,
-} from '@backstage/plugin-catalog-common';
-
-/** @public */
-export type LocationAnalyzer = {
-  /**
-   * Generates an entity configuration for given git repository. It's used for
-   * importing new component to the backstage app.
-   *
-   * @param location - Git repository to analyze and generate config for.
-   */
-  analyzeLocation(
-    location: AnalyzeLocationRequest,
-  ): Promise<AnalyzeLocationResponse>;
-};

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

@@ -45,6 +45,7 @@ import {
   EntitiesSearchFilter,
   EntityProvider,
   PlaceholderResolver,
+  LocationAnalyzer,
   ScmLocationAnalyzer,
 } from '@backstage/plugin-catalog-node';
 import {
@@ -64,7 +65,6 @@ import {
   yamlPlaceholderResolver,
 } from '../modules/core/PlaceholderProcessor';
 import { defaultEntityDataParser } from '../modules/util/parse';
-import { LocationAnalyzer } from '../ingestion';
 import {
   CatalogProcessingEngine,
   createRandomProcessingInterval,

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

@@ -20,7 +20,6 @@ import {
 import { Entity, Validators } from '@backstage/catalog-model';
 import { CatalogBuilder, CatalogPermissionRuleInput } from './CatalogBuilder';
 import {
-  CatalogAnalysisExtensionPoint,
   catalogAnalysisExtensionPoint,
   CatalogModelExtensionPoint,
   catalogModelExtensionPoint,
@@ -33,6 +32,7 @@ import {
   CatalogProcessor,
   CatalogProcessorParser,
   EntityProvider,
+  LocationAnalyzer,
   PlaceholderResolver,
   ScmLocationAnalyzer,
 } from '@backstage/plugin-catalog-node';
@@ -96,20 +96,6 @@ class CatalogProcessingExtensionPointImpl
   }
 }
 
-class CatalogAnalysisExtensionPointImpl
-  implements CatalogAnalysisExtensionPoint
-{
-  #locationAnalyzers = new Array<ScmLocationAnalyzer>();
-
-  addLocationAnalyzer(analyzer: ScmLocationAnalyzer): void {
-    this.#locationAnalyzers.push(analyzer);
-  }
-
-  get locationAnalyzers() {
-    return this.#locationAnalyzers;
-  }
-}
-
 class CatalogPermissionExtensionPointImpl
   implements CatalogPermissionExtensionPoint
 {
@@ -178,11 +164,19 @@ export const catalogPlugin = createBackendPlugin({
       processingExtensions,
     );
 
-    const analysisExtensions = new CatalogAnalysisExtensionPointImpl();
-    env.registerExtensionPoint(
-      catalogAnalysisExtensionPoint,
-      analysisExtensions,
-    );
+    let locationAnalyzer: LocationAnalyzer | undefined = undefined;
+    const scmLocationAnalyzers = new Array<ScmLocationAnalyzer>();
+    env.registerExtensionPoint(catalogAnalysisExtensionPoint, {
+      setLocationAnalyzer(analyzer: LocationAnalyzer) {
+        if (locationAnalyzer) {
+          throw new Error('LocationAnalyzer has already been set');
+        }
+        locationAnalyzer = analyzer;
+      },
+      addScmLocationAnalyzer(analyzer: ScmLocationAnalyzer) {
+        scmLocationAnalyzers.push(analyzer);
+      },
+    });
 
     const permissionExtensions = new CatalogPermissionExtensionPointImpl();
     env.registerExtensionPoint(
@@ -246,7 +240,11 @@ export const catalogPlugin = createBackendPlugin({
         Object.entries(processingExtensions.placeholderResolvers).forEach(
           ([key, resolver]) => builder.setPlaceholderResolver(key, resolver),
         );
-        builder.addLocationAnalyzers(...analysisExtensions.locationAnalyzers);
+        if (locationAnalyzer) {
+          builder.setLocationAnalyzer(locationAnalyzer);
+        } else {
+          builder.addLocationAnalyzers(...scmLocationAnalyzers);
+        }
         builder.addPermissions(...permissionExtensions.permissions);
         builder.addPermissionRules(...permissionExtensions.permissionRules);
         builder.setFieldFormatValidators(modelExtensions.fieldValidators);

plugins/catalog-backend/src/service/createRouter.test.ts

@@ -42,7 +42,7 @@ import { decodeCursor, encodeCursor } from './util';
 import { wrapInOpenApiTestServer } from '@backstage/backend-openapi-utils';
 import { Server } from 'http';
 import { mockCredentials, mockServices } from '@backstage/backend-test-utils';
-import { LocationAnalyzer } from '../ingestion';
+import { LocationAnalyzer } from '@backstage/plugin-catalog-node';
 
 describe('createRouter readonly disabled', () => {
   let entitiesCatalog: jest.Mocked<EntitiesCatalog>;

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

@@ -28,7 +28,6 @@ import express from 'express';
 import yn from 'yn';
 import { z } from 'zod';
 import { EntitiesCatalog } from '../catalog/types';
-import { LocationAnalyzer } from '../ingestion';
 import { CatalogProcessingOrchestrator } from '../processing/types';
 import { validateEntityEnvelope } from '../processing/util';
 import {
@@ -55,6 +54,7 @@ import {
   HttpAuthService,
   LoggerService,
 } from '@backstage/backend-plugin-api';
+import { LocationAnalyzer } from '@backstage/plugin-catalog-node';
 
 /**
  * Options used by {@link createRouter}.

plugins/catalog-node/api-report-alpha.md

@@ -10,6 +10,7 @@ import { EntitiesSearchFilter } from '@backstage/plugin-catalog-node';
 import { Entity } from '@backstage/catalog-model';
 import { EntityProvider } from '@backstage/plugin-catalog-node';
 import { ExtensionPoint } from '@backstage/backend-plugin-api';
+import { LocationAnalyzer } from '@backstage/plugin-catalog-node';
 import { Permission } from '@backstage/plugin-permission-common';
 import { PermissionRule } from '@backstage/plugin-permission-node';
 import { PermissionRuleParams } from '@backstage/plugin-permission-common';
@@ -20,8 +21,8 @@ import { Validators } from '@backstage/catalog-model';
 
 // @alpha (undocumented)
 export interface CatalogAnalysisExtensionPoint {
-  // (undocumented)
-  addLocationAnalyzer(analyzer: ScmLocationAnalyzer): void;
+  addScmLocationAnalyzer(analyzer: ScmLocationAnalyzer): void;
+  setLocationAnalyzer(analyzer: LocationAnalyzer): void;
 }
 
 // @alpha (undocumented)

plugins/catalog-node/api-report.md

@@ -6,6 +6,8 @@
 /// <reference types="node" />
 
 import { AnalyzeLocationExistingEntity } from '@backstage/plugin-catalog-common';
+import { AnalyzeLocationRequest } from '@backstage/plugin-catalog-common';
+import { AnalyzeLocationResponse } from '@backstage/plugin-catalog-common';
 import { CompoundEntityRef } from '@backstage/catalog-model';
 import { Entity } from '@backstage/catalog-model';
 import { JsonValue } from '@backstage/types';
@@ -166,6 +168,13 @@ export type EntityRelationSpec = {
   target: CompoundEntityRef;
 };
 
+// @public (undocumented)
+export type LocationAnalyzer = {
+  analyzeLocation(
+    location: AnalyzeLocationRequest,
+  ): Promise<AnalyzeLocationResponse>;
+};
+
 // @public @deprecated
 export type LocationSpec = LocationSpec_2;
 

plugins/catalog-node/src/extensions.ts

@@ -22,6 +22,7 @@ import {
   EntitiesSearchFilter,
   EntityProvider,
   PlaceholderResolver,
+  LocationAnalyzer,
   ScmLocationAnalyzer,
 } from '@backstage/plugin-catalog-node';
 import {
@@ -79,7 +80,16 @@ export const catalogProcessingExtensionPoint =
  * @alpha
  */
 export interface CatalogAnalysisExtensionPoint {
-  addLocationAnalyzer(analyzer: ScmLocationAnalyzer): void;
+  /**
+   * Replaces the entire location analyzer with a new one. This will cause any
+   * SCM analyzers added through `addScmLocationAnalyzer` to be ignored.
+   */
+  setLocationAnalyzer(analyzer: LocationAnalyzer): void;
+
+  /**
+   * Adds an analyzer for a specific SCM type to the default location analyzer.
+   */
+  addScmLocationAnalyzer(analyzer: ScmLocationAnalyzer): void;
 }
 
 /**

plugins/catalog-node/src/processing/index.ts

@@ -21,5 +21,6 @@ export type {
   PlaceholderResolverParams,
   PlaceholderResolverRead,
   PlaceholderResolverResolveUrl,
+  LocationAnalyzer,
   ScmLocationAnalyzer,
 } from './types';

plugins/catalog-node/src/processing/types.ts

@@ -15,7 +15,11 @@
  */
 
 import { Entity } from '@backstage/catalog-model';
-import { AnalyzeLocationExistingEntity } from '@backstage/plugin-catalog-common';
+import {
+  AnalyzeLocationExistingEntity,
+  AnalyzeLocationRequest,
+  AnalyzeLocationResponse,
+} from '@backstage/plugin-catalog-common';
 import { JsonValue } from '@backstage/types';
 import { CatalogProcessorEmit } from '../api';
 
@@ -52,6 +56,19 @@ export type PlaceholderResolver = (
   params: PlaceholderResolverParams,
 ) => Promise<JsonValue>;
 
+/** @public */
+export type LocationAnalyzer = {
+  /**
+   * Generates an entity configuration for given git repository. It's used for
+   * importing new component to the backstage app.
+   *
+   * @param location - Git repository to analyze and generate config for.
+   */
+  analyzeLocation(
+    location: AnalyzeLocationRequest,
+  ): Promise<AnalyzeLocationResponse>;
+};
+
 /** @public */
 export type AnalyzeOptions = {
   url: string;