From 7a2e2924c701c102f0b1be64d9c6f9ffbeb50b1d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= Date: Sat, 30 Sep 2023 14:46:15 +0200 Subject: [PATCH] Deprecated LocationEntityProcessor, added doc comments MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Fredrik Adelöw --- .changeset/four-pans-sin.md | 5 ++++ .changeset/heavy-forks-tie.md | 5 ++++ plugins/catalog-backend/api-report.md | 4 +-- .../modules/core/LocationEntityProcessor.ts | 18 +++++++++++-- .../catalog-node/src/api/processingResult.ts | 27 +++++++++++++++++++ 5 files changed, 55 insertions(+), 4 deletions(-) create mode 100644 .changeset/four-pans-sin.md create mode 100644 .changeset/heavy-forks-tie.md diff --git a/.changeset/four-pans-sin.md b/.changeset/four-pans-sin.md new file mode 100644 index 0000000000..46d31c242c --- /dev/null +++ b/.changeset/four-pans-sin.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-catalog-backend': patch +--- + +Marked the `LocationEntityProcessor` as deprecated, as it is no longer used internally since way back and can even be harmful at this point. diff --git a/.changeset/heavy-forks-tie.md b/.changeset/heavy-forks-tie.md new file mode 100644 index 0000000000..f5af5975b7 --- /dev/null +++ b/.changeset/heavy-forks-tie.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-catalog-node': patch +--- + +Added docs to `processingResult` diff --git a/plugins/catalog-backend/api-report.md b/plugins/catalog-backend/api-report.md index 345874d919..e426ca1d75 100644 --- a/plugins/catalog-backend/api-report.md +++ b/plugins/catalog-backend/api-report.md @@ -365,7 +365,7 @@ export type LocationAnalyzer = { ): Promise; }; -// @public (undocumented) +// @public @deprecated export class LocationEntityProcessor implements CatalogProcessor_2 { constructor(options: LocationEntityProcessorOptions); // (undocumented) @@ -378,7 +378,7 @@ export class LocationEntityProcessor implements CatalogProcessor_2 { ): Promise; } -// @public (undocumented) +// @public @deprecated (undocumented) export type LocationEntityProcessorOptions = { integrations: ScmIntegrationRegistry; }; diff --git a/plugins/catalog-backend/src/modules/core/LocationEntityProcessor.ts b/plugins/catalog-backend/src/modules/core/LocationEntityProcessor.ts index 1db74b3b56..7bfd7f33cd 100644 --- a/plugins/catalog-backend/src/modules/core/LocationEntityProcessor.ts +++ b/plugins/catalog-backend/src/modules/core/LocationEntityProcessor.ts @@ -42,12 +42,26 @@ export function toAbsoluteUrl( } } -/** @public */ +/** + * @public + * @deprecated This processor should no longer be used + */ export type LocationEntityProcessorOptions = { integrations: ScmIntegrationRegistry; }; -/** @public */ +/** + * Legacy processor, should not be used. + * + * @remarks + * + * In the old catalog architecture, this processor translated Location entities + * into URLs that should be fetched. This is no longer needed since the engine + * handles this internally. + * + * @public + * @deprecated This processor should no longer be used + */ export class LocationEntityProcessor implements CatalogProcessor { constructor(private readonly options: LocationEntityProcessorOptions) {} diff --git a/plugins/catalog-node/src/api/processingResult.ts b/plugins/catalog-node/src/api/processingResult.ts index d8b6f3ae02..0d4341fcb7 100644 --- a/plugins/catalog-node/src/api/processingResult.ts +++ b/plugins/catalog-node/src/api/processingResult.ts @@ -26,6 +26,9 @@ import { LocationSpec } from '@backstage/plugin-catalog-common'; * @public */ export const processingResult = Object.freeze({ + /** + * Associates a NotFoundError with the processing state of the current entity. + */ notFoundError( atLocation: LocationSpec, message: string, @@ -37,6 +40,9 @@ export const processingResult = Object.freeze({ }; }, + /** + * Associates an InputError with the processing state of the current entity. + */ inputError( atLocation: LocationSpec, message: string, @@ -48,6 +54,9 @@ export const processingResult = Object.freeze({ }; }, + /** + * Associates a general Error with the processing state of the current entity. + */ generalError( atLocation: LocationSpec, message: string, @@ -55,18 +64,36 @@ export const processingResult = Object.freeze({ return { type: 'error', location: atLocation, error: new Error(message) }; }, + /** + * Emits a location. In effect, this is analogous to emitting a Location kind + * child entity. This is commonly used in discovery processors. Do not use + * this while processing Location entities. + */ location(newLocation: LocationSpec): CatalogProcessorResult { return { type: 'location', location: newLocation }; }, + /** + * Emits a child of the current entity, associated with a certain location. + */ entity(atLocation: LocationSpec, newEntity: Entity): CatalogProcessorResult { return { type: 'entity', location: atLocation, entity: newEntity }; }, + /** + * Emits a relation owned by the current entity. The relation does not have to + * start or end at the current entity. The relation only lives for as long as + * the current entity lives. + */ relation(spec: EntityRelationSpec): CatalogProcessorResult { return { type: 'relation', relation: spec }; }, + /** + * Associates the given refresh key with the current entity. The effect of + * this is that the entity will be marked for refresh when such requests are + * made. + */ refresh(key: string): CatalogProcessorResult { return { type: 'refresh', key }; },