diff --git a/.changeset/tricky-poems-decide.md b/.changeset/tricky-poems-decide.md new file mode 100644 index 0000000000..fb75c8e8ad --- /dev/null +++ b/.changeset/tricky-poems-decide.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-catalog-backend': patch +--- + +First steps of deprecating the old catalog engine diff --git a/plugins/catalog-backend/api-report.md b/plugins/catalog-backend/api-report.md index fb27a2cc2a..c9e2069684 100644 --- a/plugins/catalog-backend/api-report.md +++ b/plugins/catalog-backend/api-report.md @@ -35,7 +35,7 @@ import { Validators } from '@backstage/catalog-model'; // Warning: (ae-missing-release-tag) "AddLocationResult" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // -// @public (undocumented) +// @public @deprecated (undocumented) export type AddLocationResult = { location: Location_2; entities: Entity[]; @@ -91,7 +91,7 @@ export type AnalyzeLocationResponse = { // @public (undocumented) export class AnnotateLocationEntityProcessor implements CatalogProcessor { // Warning: (ae-forgotten-export) The symbol "Options" needs to be exported by the entry point index.d.ts - constructor(options: Options_2); + constructor(options: Options); // (undocumented) preProcessEntity( entity: Entity, @@ -1061,7 +1061,7 @@ export class GitLabDiscoveryProcessor implements CatalogProcessor { // Warning: (ae-missing-release-tag) "HigherOrderOperation" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // -// @public (undocumented) +// @public @deprecated (undocumented) export type HigherOrderOperation = { addLocation( spec: LocationSpec, @@ -1074,7 +1074,7 @@ export type HigherOrderOperation = { // Warning: (ae-missing-release-tag) "HigherOrderOperations" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // -// @public +// @public @deprecated export class HigherOrderOperations implements HigherOrderOperation { constructor( entitiesCatalog: EntitiesCatalog, @@ -1139,17 +1139,17 @@ export type LocationEntityProcessorOptions = { // Warning: (ae-missing-release-tag) "LocationReader" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // -// @public (undocumented) +// @public @deprecated (undocumented) export type LocationReader = { read(location: LocationSpec): Promise; }; // Warning: (ae-missing-release-tag) "LocationReaders" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // -// @public +// @public @deprecated export class LocationReaders implements LocationReader { // Warning: (ae-forgotten-export) The symbol "Options" needs to be exported by the entry point index.d.ts - constructor(options: Options); + constructor(options: Options_3); // (undocumented) read(location: LocationSpec): Promise; } @@ -1374,7 +1374,7 @@ export type PlaceholderResolverResolveUrl = ( // Warning: (ae-missing-release-tag) "ReadLocationEntity" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // -// @public (undocumented) +// @public @deprecated (undocumented) export type ReadLocationEntity = { location: LocationSpec; entity: Entity; @@ -1383,7 +1383,7 @@ export type ReadLocationEntity = { // Warning: (ae-missing-release-tag) "ReadLocationError" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // -// @public (undocumented) +// @public @deprecated (undocumented) export type ReadLocationError = { location: LocationSpec; error: Error; @@ -1391,7 +1391,7 @@ export type ReadLocationError = { // Warning: (ae-missing-release-tag) "ReadLocationResult" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // -// @public (undocumented) +// @public @deprecated (undocumented) export type ReadLocationResult = { entities: ReadLocationEntity[]; errors: ReadLocationError[]; @@ -1496,7 +1496,7 @@ export type Transaction = { // @public (undocumented) export class UrlReaderProcessor implements CatalogProcessor { // Warning: (ae-forgotten-export) The symbol "Options" needs to be exported by the entry point index.d.ts - constructor(options: Options_3); + constructor(options: Options_2); // (undocumented) getProcessorName(): string; // (undocumented) @@ -1525,6 +1525,6 @@ export class UrlReaderProcessor implements CatalogProcessor { // src/database/types.d.ts:164:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen // src/database/types.d.ts:165:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen // src/ingestion/processors/GithubMultiOrgReaderProcessor.d.ts:23:9 - (ae-forgotten-export) The symbol "GithubMultiOrgConfig" needs to be exported by the entry point index.d.ts -// src/ingestion/types.d.ts:17:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/ingestion/types.d.ts:41:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen +// src/ingestion/types.d.ts:8:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen +// src/legacy/ingestion/types.d.ts:19:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen ``` diff --git a/plugins/catalog-backend/src/index.ts b/plugins/catalog-backend/src/index.ts index c56fc4232a..dbb8b44424 100644 --- a/plugins/catalog-backend/src/index.ts +++ b/plugins/catalog-backend/src/index.ts @@ -23,6 +23,7 @@ export * from './catalog'; export * from './database'; export * from './ingestion'; +export * from './legacy'; export * from './search'; export * from './service'; export * from './util'; diff --git a/plugins/catalog-backend/src/ingestion/index.ts b/plugins/catalog-backend/src/ingestion/index.ts index 80fea962b9..33c81c56cc 100644 --- a/plugins/catalog-backend/src/ingestion/index.ts +++ b/plugins/catalog-backend/src/ingestion/index.ts @@ -16,18 +16,10 @@ export type { CatalogRule, CatalogRulesEnforcer } from './CatalogRules'; export { DefaultCatalogRulesEnforcer } from './CatalogRules'; -export { HigherOrderOperations } from './HigherOrderOperations'; -export { LocationReaders } from './LocationReaders'; export type { - AddLocationResult, AnalyzeLocationRequest, AnalyzeLocationResponse, - HigherOrderOperation, LocationAnalyzer, - LocationReader, - ReadLocationEntity, - ReadLocationError, - ReadLocationResult, AnalyzeLocationEntityField, AnalyzeLocationExistingEntity, AnalyzeLocationGenerateEntity, diff --git a/plugins/catalog-backend/src/ingestion/types.ts b/plugins/catalog-backend/src/ingestion/types.ts index eb7b84e95f..f353dd3818 100644 --- a/plugins/catalog-backend/src/ingestion/types.ts +++ b/plugins/catalog-backend/src/ingestion/types.ts @@ -14,62 +14,9 @@ * limitations under the License. */ -import { - Entity, - EntityRelationSpec, - Location, - LocationSpec, -} from '@backstage/catalog-model'; +import { Entity, LocationSpec } from '@backstage/catalog-model'; import { RecursivePartial } from '../util/RecursivePartial'; -// -// HigherOrderOperation -// - -export type HigherOrderOperation = { - addLocation( - spec: LocationSpec, - options?: { dryRun?: boolean }, - ): Promise; - refreshAllLocations(): Promise; -}; - -export type AddLocationResult = { - location: Location; - entities: Entity[]; -}; - -// -// LocationReader -// - -export type LocationReader = { - /** - * Reads the contents of a location. - * - * @param location The location to read - * @throws An error if the location was handled by this reader, but could not - * be read - */ - read(location: LocationSpec): Promise; -}; - -export type ReadLocationResult = { - entities: ReadLocationEntity[]; - errors: ReadLocationError[]; -}; - -export type ReadLocationEntity = { - location: LocationSpec; - entity: Entity; - relations: EntityRelationSpec[]; -}; - -export type ReadLocationError = { - location: LocationSpec; - error: Error; -}; - // // LocationAnalyzer // diff --git a/plugins/catalog-backend/src/legacy/index.ts b/plugins/catalog-backend/src/legacy/index.ts new file mode 100644 index 0000000000..848261cbc6 --- /dev/null +++ b/plugins/catalog-backend/src/legacy/index.ts @@ -0,0 +1,17 @@ +/* + * Copyright 2021 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 * from './ingestion'; diff --git a/plugins/catalog-backend/src/ingestion/HigherOrderOperations.test.ts b/plugins/catalog-backend/src/legacy/ingestion/HigherOrderOperations.test.ts similarity index 98% rename from plugins/catalog-backend/src/ingestion/HigherOrderOperations.test.ts rename to plugins/catalog-backend/src/legacy/ingestion/HigherOrderOperations.test.ts index f49c553ad3..3f7fccf024 100644 --- a/plugins/catalog-backend/src/ingestion/HigherOrderOperations.test.ts +++ b/plugins/catalog-backend/src/legacy/ingestion/HigherOrderOperations.test.ts @@ -16,9 +16,9 @@ import { getVoidLogger } from '@backstage/backend-common'; import { Entity, Location, LocationSpec } from '@backstage/catalog-model'; -import { EntitiesCatalog, LocationsCatalog } from '../catalog'; -import { LocationUpdateStatus } from '../catalog/types'; -import { DatabaseLocationUpdateLogStatus } from '../database/types'; +import { EntitiesCatalog, LocationsCatalog } from '../../catalog'; +import { LocationUpdateStatus } from '../../catalog/types'; +import { DatabaseLocationUpdateLogStatus } from '../../database/types'; import { HigherOrderOperations } from './HigherOrderOperations'; import { LocationReader } from './types'; diff --git a/plugins/catalog-backend/src/ingestion/HigherOrderOperations.ts b/plugins/catalog-backend/src/legacy/ingestion/HigherOrderOperations.ts similarity index 96% rename from plugins/catalog-backend/src/ingestion/HigherOrderOperations.ts rename to plugins/catalog-backend/src/legacy/ingestion/HigherOrderOperations.ts index b12fe7fb41..1ad882ebcd 100644 --- a/plugins/catalog-backend/src/ingestion/HigherOrderOperations.ts +++ b/plugins/catalog-backend/src/legacy/ingestion/HigherOrderOperations.ts @@ -21,8 +21,8 @@ import { } from '@backstage/catalog-model'; import { v4 as uuidv4 } from 'uuid'; import { Logger } from 'winston'; -import { EntitiesCatalog, LocationsCatalog } from '../catalog'; -import { durationText } from '../util'; +import { EntitiesCatalog, LocationsCatalog } from '../../catalog'; +import { durationText } from '../../util'; import { AddLocationResult, HigherOrderOperation, @@ -33,8 +33,7 @@ import { * Placeholder for operations that span several catalogs and/or stretches out * in time. * - * TODO(freben): Find a better home for these, possibly refactoring to use the - * database more directly. + * @deprecated This class was part of the legacy catalog engine */ export class HigherOrderOperations implements HigherOrderOperation { constructor( diff --git a/plugins/catalog-backend/src/ingestion/LocationReaders.ts b/plugins/catalog-backend/src/legacy/ingestion/LocationReaders.ts similarity index 97% rename from plugins/catalog-backend/src/ingestion/LocationReaders.ts rename to plugins/catalog-backend/src/legacy/ingestion/LocationReaders.ts index b8c9125893..041dc3b9e0 100644 --- a/plugins/catalog-backend/src/ingestion/LocationReaders.ts +++ b/plugins/catalog-backend/src/legacy/ingestion/LocationReaders.ts @@ -26,8 +26,8 @@ import { } from '@backstage/catalog-model'; import { Config } from '@backstage/config'; import { Logger } from 'winston'; -import { CatalogRulesEnforcer } from './CatalogRules'; -import * as result from './processors/results'; +import { CatalogRulesEnforcer } from '../../ingestion/CatalogRules'; +import * as result from '../../ingestion/processors/results'; import { CatalogProcessor, CatalogProcessorEmit, @@ -36,7 +36,7 @@ import { CatalogProcessorLocationResult, CatalogProcessorParser, CatalogProcessorResult, -} from './processors/types'; +} from '../../ingestion/processors/types'; import { LocationReader, ReadLocationResult } from './types'; // The max amount of nesting depth of generated work items @@ -61,6 +61,8 @@ const noopCache = { /** * Implements the reading of a location through a series of processor tasks. + * + * @deprecated This class was part of the legacy catalog engine */ export class LocationReaders implements LocationReader { private readonly options: Options; diff --git a/plugins/catalog-backend/src/legacy/ingestion/index.ts b/plugins/catalog-backend/src/legacy/ingestion/index.ts new file mode 100644 index 0000000000..fa63f076d6 --- /dev/null +++ b/plugins/catalog-backend/src/legacy/ingestion/index.ts @@ -0,0 +1,26 @@ +/* + * 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 { HigherOrderOperations } from './HigherOrderOperations'; +export { LocationReaders } from './LocationReaders'; +export type { + AddLocationResult, + HigherOrderOperation, + LocationReader, + ReadLocationEntity, + ReadLocationError, + ReadLocationResult, +} from './types'; diff --git a/plugins/catalog-backend/src/legacy/ingestion/types.ts b/plugins/catalog-backend/src/legacy/ingestion/types.ts new file mode 100644 index 0000000000..5792591c88 --- /dev/null +++ b/plugins/catalog-backend/src/legacy/ingestion/types.ts @@ -0,0 +1,76 @@ +/* + * 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 { + Entity, + EntityRelationSpec, + Location, + LocationSpec, +} from '@backstage/catalog-model'; + +// +// LocationReader +// + +/** @deprecated This class was part of the legacy catalog engine */ +export type HigherOrderOperation = { + addLocation( + spec: LocationSpec, + options?: { dryRun?: boolean }, + ): Promise; + refreshAllLocations(): Promise; +}; + +/** @deprecated This class was part of the legacy catalog engine */ +export type AddLocationResult = { + location: Location; + entities: Entity[]; +}; + +// +// LocationReader +// + +/** @deprecated This class was part of the legacy catalog engine */ +export type LocationReader = { + /** + * Reads the contents of a location. + * + * @param location The location to read + * @throws An error if the location was handled by this reader, but could not + * be read + */ + read(location: LocationSpec): Promise; +}; + +/** @deprecated This class was part of the legacy catalog engine */ +export type ReadLocationResult = { + entities: ReadLocationEntity[]; + errors: ReadLocationError[]; +}; + +/** @deprecated This class was part of the legacy catalog engine */ +export type ReadLocationEntity = { + location: LocationSpec; + entity: Entity; + relations: EntityRelationSpec[]; +}; + +/** @deprecated This class was part of the legacy catalog engine */ +export type ReadLocationError = { + location: LocationSpec; + error: Error; +}; diff --git a/plugins/catalog-backend/src/service/CatalogBuilder.ts b/plugins/catalog-backend/src/service/CatalogBuilder.ts index 40683bb4bf..23d69ef9d9 100644 --- a/plugins/catalog-backend/src/service/CatalogBuilder.ts +++ b/plugins/catalog-backend/src/service/CatalogBuilder.ts @@ -47,15 +47,17 @@ import { GithubDiscoveryProcessor, GithubOrgReaderProcessor, GitLabDiscoveryProcessor, - HigherOrderOperation, - HigherOrderOperations, LocationEntityProcessor, - LocationReaders, PlaceholderProcessor, PlaceholderResolver, StaticLocationProcessor, UrlReaderProcessor, } from '../ingestion'; +import { + HigherOrderOperation, + HigherOrderOperations, + LocationReaders, +} from '../legacy/ingestion'; import { DefaultCatalogRulesEnforcer } from '../ingestion/CatalogRules'; import { RepoLocationAnalyzer } from '../ingestion/LocationAnalyzer'; import { diff --git a/plugins/catalog-backend/src/service/router.test.ts b/plugins/catalog-backend/src/service/router.test.ts index 29b49ff157..def62d2e68 100644 --- a/plugins/catalog-backend/src/service/router.test.ts +++ b/plugins/catalog-backend/src/service/router.test.ts @@ -22,7 +22,7 @@ import express from 'express'; import request from 'supertest'; import { EntitiesCatalog, LocationsCatalog } from '../catalog'; import { LocationResponse } from '../catalog/types'; -import { HigherOrderOperation } from '../ingestion/types'; +import { HigherOrderOperation } from '../legacy/ingestion/types'; import { createRouter } from './router'; import { basicEntityFilter } from './request'; import { RefreshService } from '../next'; diff --git a/plugins/catalog-backend/src/service/router.ts b/plugins/catalog-backend/src/service/router.ts index f1bb18c825..38de32f357 100644 --- a/plugins/catalog-backend/src/service/router.ts +++ b/plugins/catalog-backend/src/service/router.ts @@ -27,7 +27,8 @@ import Router from 'express-promise-router'; import { Logger } from 'winston'; import yn from 'yn'; import { EntitiesCatalog, LocationsCatalog } from '../catalog'; -import { HigherOrderOperation, LocationAnalyzer } from '../ingestion/types'; +import { LocationAnalyzer } from '../ingestion/types'; +import { HigherOrderOperation } from '../legacy/ingestion/types'; import { RefreshService, LocationService, RefreshOptions } from '../next/types'; import { basicEntityFilter,