From f2a2a83b8df7378752c0ae09bc4c23d5f4578075 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Thu, 2 May 2024 17:55:54 +0200 Subject: [PATCH] catalog-node: update catalogAnalysisExtensionPoint Signed-off-by: Patrik Oldsberg --- .changeset/brave-carrots-glow.md | 5 +++ .changeset/early-starfishes-hammer.md | 5 +++ .changeset/happy-radios-kiss.md | 5 +++ .changeset/rich-adults-float.md | 5 +++ .changeset/tough-eggs-wink.md | 5 +++ .../src/module/githubCatalogModule.test.ts | 5 ++- .../src/module/githubCatalogModule.ts | 2 +- plugins/catalog-backend/api-report.md | 11 ++--- plugins/catalog-backend/src/deprecated.ts | 6 +++ plugins/catalog-backend/src/index.ts | 1 - .../src/ingestion/LocationAnalyzer.ts | 6 ++- .../catalog-backend/src/ingestion/index.ts | 17 -------- .../catalog-backend/src/ingestion/types.ts | 33 --------------- .../src/service/CatalogBuilder.ts | 2 +- .../src/service/CatalogPlugin.ts | 40 +++++++++---------- .../src/service/createRouter.test.ts | 2 +- .../src/service/createRouter.ts | 2 +- plugins/catalog-node/api-report-alpha.md | 5 ++- plugins/catalog-node/api-report.md | 9 +++++ plugins/catalog-node/src/extensions.ts | 12 +++++- plugins/catalog-node/src/processing/index.ts | 1 + plugins/catalog-node/src/processing/types.ts | 19 ++++++++- 22 files changed, 107 insertions(+), 91 deletions(-) create mode 100644 .changeset/brave-carrots-glow.md create mode 100644 .changeset/early-starfishes-hammer.md create mode 100644 .changeset/happy-radios-kiss.md create mode 100644 .changeset/rich-adults-float.md create mode 100644 .changeset/tough-eggs-wink.md delete mode 100644 plugins/catalog-backend/src/ingestion/index.ts delete mode 100644 plugins/catalog-backend/src/ingestion/types.ts diff --git a/.changeset/brave-carrots-glow.md b/.changeset/brave-carrots-glow.md new file mode 100644 index 0000000000..b4493bf4f6 --- /dev/null +++ b/.changeset/brave-carrots-glow.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-catalog-node': minor +--- + +Added `LocationAnalyzer` type, moved from `@backstage/plugin-catalog-backend`. diff --git a/.changeset/early-starfishes-hammer.md b/.changeset/early-starfishes-hammer.md new file mode 100644 index 0000000000..abe17e85a2 --- /dev/null +++ b/.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`. diff --git a/.changeset/happy-radios-kiss.md b/.changeset/happy-radios-kiss.md new file mode 100644 index 0000000000..1097c832d8 --- /dev/null +++ b/.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. diff --git a/.changeset/rich-adults-float.md b/.changeset/rich-adults-float.md new file mode 100644 index 0000000000..5a9746b8f5 --- /dev/null +++ b/.changeset/rich-adults-float.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-catalog-backend-module-github': patch +--- + +Updated to use the new `catalogAnalysisExtensionPoint` API. diff --git a/.changeset/tough-eggs-wink.md b/.changeset/tough-eggs-wink.md new file mode 100644 index 0000000000..52644e3620 --- /dev/null +++ b/.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. diff --git a/plugins/catalog-backend-module-github/src/module/githubCatalogModule.test.ts b/plugins/catalog-backend-module-github/src/module/githubCatalogModule.test.ts index 0f466fefb7..24ee7f7108 100644 --- a/plugins/catalog-backend-module-github/src/module/githubCatalogModule.test.ts +++ b/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), ); }); diff --git a/plugins/catalog-backend-module-github/src/module/githubCatalogModule.ts b/plugins/catalog-backend-module-github/src/module/githubCatalogModule.ts index 0b46e1a023..809a1a5094 100644 --- a/plugins/catalog-backend-module-github/src/module/githubCatalogModule.ts +++ b/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, diff --git a/plugins/catalog-backend/api-report.md b/plugins/catalog-backend/api-report.md index 27c00257a5..1c65abf83e 100644 --- a/plugins/catalog-backend/api-report.md +++ b/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): 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; } -// @public (undocumented) -export type LocationAnalyzer = { - analyzeLocation( - location: AnalyzeLocationRequest_2, - ): Promise; -}; +// @public @deprecated (undocumented) +export type LocationAnalyzer = LocationAnalyzer_2; // @public @deprecated export class LocationEntityProcessor implements CatalogProcessor_2 { diff --git a/plugins/catalog-backend/src/deprecated.ts b/plugins/catalog-backend/src/deprecated.ts index 72c3cad225..2d08d2ce0c 100644 --- a/plugins/catalog-backend/src/deprecated.ts +++ b/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 diff --git a/plugins/catalog-backend/src/index.ts b/plugins/catalog-backend/src/index.ts index 6a479babdc..d3ffa9a974 100644 --- a/plugins/catalog-backend/src/index.ts +++ b/plugins/catalog-backend/src/index.ts @@ -20,7 +20,6 @@ * @packageDocumentation */ -export * from './ingestion'; export * from './modules'; export * from './processing'; export * from './search'; diff --git a/plugins/catalog-backend/src/ingestion/LocationAnalyzer.ts b/plugins/catalog-backend/src/ingestion/LocationAnalyzer.ts index 61d319bf37..d574f3b299 100644 --- a/plugins/catalog-backend/src/ingestion/LocationAnalyzer.ts +++ b/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 { diff --git a/plugins/catalog-backend/src/ingestion/index.ts b/plugins/catalog-backend/src/ingestion/index.ts deleted file mode 100644 index a6555dd98d..0000000000 --- a/plugins/catalog-backend/src/ingestion/index.ts +++ /dev/null @@ -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'; diff --git a/plugins/catalog-backend/src/ingestion/types.ts b/plugins/catalog-backend/src/ingestion/types.ts deleted file mode 100644 index 6ca0ab259b..0000000000 --- a/plugins/catalog-backend/src/ingestion/types.ts +++ /dev/null @@ -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; -}; diff --git a/plugins/catalog-backend/src/service/CatalogBuilder.ts b/plugins/catalog-backend/src/service/CatalogBuilder.ts index 2438dc9009..f305bf2d8b 100644 --- a/plugins/catalog-backend/src/service/CatalogBuilder.ts +++ b/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, diff --git a/plugins/catalog-backend/src/service/CatalogPlugin.ts b/plugins/catalog-backend/src/service/CatalogPlugin.ts index dd44e20add..6171ebbc1c 100644 --- a/plugins/catalog-backend/src/service/CatalogPlugin.ts +++ b/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(); - - 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(); + 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); diff --git a/plugins/catalog-backend/src/service/createRouter.test.ts b/plugins/catalog-backend/src/service/createRouter.test.ts index 292c4c1b7a..a2fae0e8bd 100644 --- a/plugins/catalog-backend/src/service/createRouter.test.ts +++ b/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; diff --git a/plugins/catalog-backend/src/service/createRouter.ts b/plugins/catalog-backend/src/service/createRouter.ts index 508f0bb3d6..774ee61a6d 100644 --- a/plugins/catalog-backend/src/service/createRouter.ts +++ b/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}. diff --git a/plugins/catalog-node/api-report-alpha.md b/plugins/catalog-node/api-report-alpha.md index fb41d6f03e..cc3f7e5fb5 100644 --- a/plugins/catalog-node/api-report-alpha.md +++ b/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) diff --git a/plugins/catalog-node/api-report.md b/plugins/catalog-node/api-report.md index a4ba95073f..7c1c8b5911 100644 --- a/plugins/catalog-node/api-report.md +++ b/plugins/catalog-node/api-report.md @@ -6,6 +6,8 @@ /// 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; +}; + // @public @deprecated export type LocationSpec = LocationSpec_2; diff --git a/plugins/catalog-node/src/extensions.ts b/plugins/catalog-node/src/extensions.ts index 648b8c5974..56478ec1db 100644 --- a/plugins/catalog-node/src/extensions.ts +++ b/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; } /** diff --git a/plugins/catalog-node/src/processing/index.ts b/plugins/catalog-node/src/processing/index.ts index 8cffac6961..4e83e6077d 100644 --- a/plugins/catalog-node/src/processing/index.ts +++ b/plugins/catalog-node/src/processing/index.ts @@ -21,5 +21,6 @@ export type { PlaceholderResolverParams, PlaceholderResolverRead, PlaceholderResolverResolveUrl, + LocationAnalyzer, ScmLocationAnalyzer, } from './types'; diff --git a/plugins/catalog-node/src/processing/types.ts b/plugins/catalog-node/src/processing/types.ts index b6785c1b91..e3d3c305fc 100644 --- a/plugins/catalog-node/src/processing/types.ts +++ b/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; +/** @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; +}; + /** @public */ export type AnalyzeOptions = { url: string;