first steps of deprecating the old catalog engine

Signed-off-by: Fredrik Adelöw <freben@gmail.com>

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<ReadLocationResult>;
 };
 
 // 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<ReadLocationResult>;
 }
@@ -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
 ```

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';

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,

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<AddLocationResult>;
-  refreshAllLocations(): Promise<void>;
-};
-
-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<ReadLocationResult>;
-};
-
-export type ReadLocationResult = {
-  entities: ReadLocationEntity[];
-  errors: ReadLocationError[];
-};
-
-export type ReadLocationEntity = {
-  location: LocationSpec;
-  entity: Entity;
-  relations: EntityRelationSpec[];
-};
-
-export type ReadLocationError = {
-  location: LocationSpec;
-  error: Error;
-};
-
 //
 // LocationAnalyzer
 //

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';

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';
 

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(

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;

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';

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<AddLocationResult>;
+  refreshAllLocations(): Promise<void>;
+};
+
+/** @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<ReadLocationResult>;
+};
+
+/** @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;
+};

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 {

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';

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,