feat(catalog): move setting location analyzers to a new analysis extension

Signed-off-by: Phil Kuang <pkuang@factset.com>

.changeset/blue-bags-warn.md

@@ -4,4 +4,4 @@
 '@backstage/plugin-catalog-backend-module-github': patch
 ---
 
-Support adding location analyzers in catalog processing extension point and move `AnalyzeOptions` and `ScmLocationAnalyzer` types to `@backstage/plugin-catalog-node`
+Support adding location analyzers in new catalog analysis extension point and move `AnalyzeOptions` and `ScmLocationAnalyzer` types to `@backstage/plugin-catalog-node`

plugins/catalog-backend/api-report.md

@@ -10,7 +10,7 @@ import { AnalyzeLocationExistingEntity as AnalyzeLocationExistingEntity_2 } from
 import { AnalyzeLocationGenerateEntity as AnalyzeLocationGenerateEntity_2 } from '@backstage/plugin-catalog-common';
 import { AnalyzeLocationRequest as AnalyzeLocationRequest_2 } from '@backstage/plugin-catalog-common';
 import { AnalyzeLocationResponse as AnalyzeLocationResponse_2 } from '@backstage/plugin-catalog-common';
-import { AnalyzeOptions } from '@backstage/plugin-catalog-node';
+import { AnalyzeOptions as AnalyzeOptions_2 } from '@backstage/plugin-catalog-node';
 import { CatalogApi } from '@backstage/catalog-client';
 import type { CatalogCollatorEntityTransformer as CatalogCollatorEntityTransformer_2 } from '@backstage/plugin-search-backend-module-catalog';
 import { CatalogEntityDocument } from '@backstage/plugin-catalog-common';
@@ -51,7 +51,7 @@ import { PluginEndpointDiscovery } from '@backstage/backend-common';
 import { PluginTaskScheduler } from '@backstage/backend-tasks';
 import { Router } from 'express';
 import { ScmIntegrationRegistry } from '@backstage/integration';
-import { ScmLocationAnalyzer } from '@backstage/plugin-catalog-node';
+import { ScmLocationAnalyzer as ScmLocationAnalyzer_2 } from '@backstage/plugin-catalog-node';
 import { TokenManager } from '@backstage/backend-common';
 import { UrlReader } from '@backstage/backend-common';
 import { Validators } from '@backstage/catalog-model';
@@ -71,7 +71,8 @@ export type AnalyzeLocationRequest = AnalyzeLocationRequest_2;
 // @public @deprecated (undocumented)
 export type AnalyzeLocationResponse = AnalyzeLocationResponse_2;
 
-export { AnalyzeOptions };
+// @public @deprecated (undocumented)
+export type AnalyzeOptions = AnalyzeOptions_2;
 
 // @public (undocumented)
 export class AnnotateLocationEntityProcessor implements CatalogProcessor_2 {
@@ -132,7 +133,7 @@ export class CatalogBuilder {
     ...providers: Array<EntityProvider_2 | Array<EntityProvider_2>>
   ): CatalogBuilder;
   addLocationAnalyzers(
-    ...analyzers: Array<ScmLocationAnalyzer | Array<ScmLocationAnalyzer>>
+    ...analyzers: Array<ScmLocationAnalyzer_2 | Array<ScmLocationAnalyzer_2>>
   ): CatalogBuilder;
   addPermissionRules(
     ...permissionRules: Array<
@@ -466,7 +467,8 @@ export const processingResult: Readonly<{
   readonly refresh: (key: string) => CatalogProcessorResult_2;
 }>;
 
-export { ScmLocationAnalyzer };
+// @public @deprecated (undocumented)
+export type ScmLocationAnalyzer = ScmLocationAnalyzer_2;
 
 // @public (undocumented)
 export class UrlReaderProcessor implements CatalogProcessor_2 {

plugins/catalog-backend/src/deprecated.ts

@@ -33,6 +33,8 @@ import {
   type EntityProvider as _EntityProvider,
   type EntityProviderConnection as _EntityProviderConnection,
   type EntityProviderMutation as _EntityProviderMutation,
+  type AnalyzeOptions as _AnalyzeOptions,
+  type ScmLocationAnalyzer as _ScmLocationAnalyzer,
 } from '@backstage/plugin-catalog-node';
 import { type LocationSpec as _LocationSpec } from '@backstage/plugin-catalog-common';
 
@@ -141,3 +143,13 @@ export type EntityProviderMutation = _EntityProviderMutation;
  * @deprecated use the same type from `@backstage/plugin-catalog-common` instead
  */
 export type LocationSpec = _LocationSpec;
+/**
+ * @public
+ * @deprecated import from `@backstage/plugin-catalog-node` instead
+ */
+export type AnalyzeOptions = _AnalyzeOptions;
+/**
+ * @public
+ * @deprecated import from `@backstage/plugin-catalog-node` instead
+ */
+export type ScmLocationAnalyzer = _ScmLocationAnalyzer;

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

@@ -22,11 +22,3 @@ export type {
   AnalyzeLocationResponse,
   LocationAnalyzer,
 } from './types';
-
-/**
- * @deprecated use the same type from `@backstage/plugin-catalog-node` instead
- */
-export type {
-  AnalyzeOptions,
-  ScmLocationAnalyzer,
-} from '@backstage/plugin-catalog-node';

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

@@ -19,6 +19,8 @@ import {
 } from '@backstage/backend-plugin-api';
 import { CatalogBuilder } from './CatalogBuilder';
 import {
+  CatalogAnalysisExtensionPoint,
+  catalogAnalysisExtensionPoint,
   CatalogProcessingExtensionPoint,
   catalogProcessingExtensionPoint,
 } from '@backstage/plugin-catalog-node/alpha';
@@ -30,11 +32,12 @@ import {
 import { loggerToWinstonLogger } from '@backstage/backend-common';
 import { PlaceholderResolver } from '../modules';
 
-class CatalogExtensionPointImpl implements CatalogProcessingExtensionPoint {
+class CatalogProcessingExtensionPointImpl
+  implements CatalogProcessingExtensionPoint
+{
   #processors = new Array<CatalogProcessor>();
   #entityProviders = new Array<EntityProvider>();
   #placeholderResolvers: Record<string, PlaceholderResolver> = {};
-  #locationAnalyzers = new Array<ScmLocationAnalyzer>();
 
   addProcessor(
     ...processors: Array<CatalogProcessor | Array<CatalogProcessor>>
@@ -56,12 +59,6 @@ class CatalogExtensionPointImpl implements CatalogProcessingExtensionPoint {
     this.#placeholderResolvers[key] = resolver;
   }
 
-  addLocationAnalyzers(
-    ...analyzers: Array<ScmLocationAnalyzer | Array<ScmLocationAnalyzer>>
-  ): void {
-    this.#locationAnalyzers.push(...analyzers.flat());
-  }
-
   get processors() {
     return this.#processors;
   }
@@ -73,6 +70,18 @@ class CatalogExtensionPointImpl implements CatalogProcessingExtensionPoint {
   get placeholderResolvers() {
     return this.#placeholderResolvers;
   }
+}
+
+class CatalogAnalysisExtensionPointImpl
+  implements CatalogAnalysisExtensionPoint
+{
+  #locationAnalyzers = new Array<ScmLocationAnalyzer>();
+
+  addLocationAnalyzers(
+    ...analyzers: Array<ScmLocationAnalyzer | Array<ScmLocationAnalyzer>>
+  ): void {
+    this.#locationAnalyzers.push(...analyzers.flat());
+  }
 
   get locationAnalyzers() {
     return this.#locationAnalyzers;
@@ -86,13 +95,19 @@ class CatalogExtensionPointImpl implements CatalogProcessingExtensionPoint {
 export const catalogPlugin = createBackendPlugin({
   pluginId: 'catalog',
   register(env) {
-    const processingExtensions = new CatalogExtensionPointImpl();
+    const processingExtensions = new CatalogProcessingExtensionPointImpl();
     // plugins depending on this API will be initialized before this plugins init method is executed.
     env.registerExtensionPoint(
       catalogProcessingExtensionPoint,
       processingExtensions,
     );
 
+    const analysisExtensions = new CatalogAnalysisExtensionPointImpl();
+    env.registerExtensionPoint(
+      catalogAnalysisExtensionPoint,
+      analysisExtensions,
+    );
+
     env.registerInit({
       deps: {
         logger: coreServices.logger,
@@ -128,7 +143,7 @@ export const catalogPlugin = createBackendPlugin({
         Object.entries(processingExtensions.placeholderResolvers).forEach(
           ([key, resolver]) => builder.setPlaceholderResolver(key, resolver),
         );
-        builder.addLocationAnalyzers(...processingExtensions.locationAnalyzers);
+        builder.addLocationAnalyzers(...analysisExtensions.locationAnalyzers);
 
         const { processingEngine, router } = await builder.build();
 

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

@@ -11,6 +11,17 @@ import { PlaceholderResolver } from '@backstage/plugin-catalog-node';
 import { ScmLocationAnalyzer } from '@backstage/plugin-catalog-node';
 import { ServiceRef } from '@backstage/backend-plugin-api';
 
+// @alpha (undocumented)
+export interface CatalogAnalysisExtensionPoint {
+  // (undocumented)
+  addLocationAnalyzers(
+    ...analyzers: Array<ScmLocationAnalyzer | Array<ScmLocationAnalyzer>>
+  ): void;
+}
+
+// @alpha (undocumented)
+export const catalogAnalysisExtensionPoint: ExtensionPoint<CatalogAnalysisExtensionPoint>;
+
 // @alpha (undocumented)
 export interface CatalogProcessingExtensionPoint {
   // (undocumented)
@@ -18,10 +29,6 @@ export interface CatalogProcessingExtensionPoint {
     ...providers: Array<EntityProvider | Array<EntityProvider>>
   ): void;
   // (undocumented)
-  addLocationAnalyzers(
-    ...analyzers: Array<ScmLocationAnalyzer | Array<ScmLocationAnalyzer>>
-  ): void;
-  // (undocumented)
   addPlaceholderResolver(key: string, resolver: PlaceholderResolver): void;
   // (undocumented)
   addProcessor(

plugins/catalog-node/src/alpha.ts

@@ -17,3 +17,5 @@
 export { catalogServiceRef } from './catalogService';
 export type { CatalogProcessingExtensionPoint } from './extensions';
 export { catalogProcessingExtensionPoint } from './extensions';
+export type { CatalogAnalysisExtensionPoint } from './extensions';
+export { catalogAnalysisExtensionPoint } from './extensions';

plugins/catalog-node/src/extensions.ts

@@ -32,9 +32,6 @@ export interface CatalogProcessingExtensionPoint {
     ...providers: Array<EntityProvider | Array<EntityProvider>>
   ): void;
   addPlaceholderResolver(key: string, resolver: PlaceholderResolver): void;
-  addLocationAnalyzers(
-    ...analyzers: Array<ScmLocationAnalyzer | Array<ScmLocationAnalyzer>>
-  ): void;
 }
 
 /**
@@ -44,3 +41,20 @@ export const catalogProcessingExtensionPoint =
   createExtensionPoint<CatalogProcessingExtensionPoint>({
     id: 'catalog.processing',
   });
+
+/**
+ * @alpha
+ */
+export interface CatalogAnalysisExtensionPoint {
+  addLocationAnalyzers(
+    ...analyzers: Array<ScmLocationAnalyzer | Array<ScmLocationAnalyzer>>
+  ): void;
+}
+
+/**
+ * @alpha
+ */
+export const catalogAnalysisExtensionPoint =
+  createExtensionPoint<CatalogAnalysisExtensionPoint>({
+    id: 'catalog.analysis',
+  });