add new catalog-node package

Co-authored-by: Johan Haals <johan.haals@gmail.com>
Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

.changeset/loud-lemons-listen.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-node': major
+---
+
+This package houses stable types from the `@backstage/plugin-catalog-backend` package and is intended for creation of catalog modules. Prefer importing from this package over the `@backstage/plugin-catalog-backend` package.

.changeset/twelve-peaches-tickle.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-backend': patch
+---
+
+Many symbol declarations have been moved to `@backstage/plugin-catalog-node`. This has no affect on users of this package as they are all re-exported. Modules that build on top of the catalog backend plugin should switch all of their imports to the `@backstage/plugin-catalog-node` package and remove the dependency on `@backstage/plugin-catalog-backend`.

plugins/catalog-backend/api-report.md

@@ -7,16 +7,31 @@
 
 import { CatalogApi } from '@backstage/catalog-client';
 import { CatalogEntityDocument } from '@backstage/plugin-catalog-common';
-import { CompoundEntityRef } from '@backstage/catalog-model';
+import { CatalogProcessor } from '@backstage/plugin-catalog-node';
+import { CatalogProcessorCache } from '@backstage/plugin-catalog-node';
+import { CatalogProcessorEmit } from '@backstage/plugin-catalog-node';
+import { CatalogProcessorEntityResult } from '@backstage/plugin-catalog-node';
+import { CatalogProcessorErrorResult } from '@backstage/plugin-catalog-node';
+import { CatalogProcessorLocationResult } from '@backstage/plugin-catalog-node';
+import { CatalogProcessorParser } from '@backstage/plugin-catalog-node';
+import { CatalogProcessorRefreshKeysResult } from '@backstage/plugin-catalog-node';
+import { CatalogProcessorRelationResult } from '@backstage/plugin-catalog-node';
+import { CatalogProcessorResult } from '@backstage/plugin-catalog-node';
 import { ConditionalPolicyDecision } from '@backstage/plugin-permission-common';
 import { Conditions } from '@backstage/plugin-permission-node';
 import { Config } from '@backstage/config';
+import { DeferredEntity } from '@backstage/plugin-catalog-node';
 import { DocumentCollatorFactory } from '@backstage/plugin-search-common';
 import { Entity } from '@backstage/catalog-model';
 import { EntityPolicy } from '@backstage/catalog-model';
+import { EntityProvider } from '@backstage/plugin-catalog-node';
+import { EntityProviderConnection } from '@backstage/plugin-catalog-node';
+import { EntityProviderMutation } from '@backstage/plugin-catalog-node';
+import { EntityRelationSpec } from '@backstage/plugin-catalog-node';
 import { GetEntitiesRequest } from '@backstage/catalog-client';
 import { JsonValue } from '@backstage/types';
 import { LocationEntityV1alpha1 } from '@backstage/catalog-model';
+import { LocationSpec } from '@backstage/plugin-catalog-node';
 import { Logger } from 'winston';
 import { Permission } from '@backstage/plugin-permission-common';
 import { PermissionAuthorizer } from '@backstage/plugin-permission-common';
@@ -26,6 +41,7 @@ import { PermissionEvaluator } from '@backstage/plugin-permission-common';
 import { PermissionRule } from '@backstage/plugin-permission-node';
 import { PluginDatabaseManager } from '@backstage/backend-common';
 import { PluginEndpointDiscovery } from '@backstage/backend-common';
+import { processingResult } from '@backstage/plugin-catalog-node';
 import { Readable } from 'stream';
 import { ResourcePermission } from '@backstage/plugin-permission-common';
 import { Router } from 'express';
@@ -207,86 +223,25 @@ export interface CatalogProcessingEngine {
   stop(): Promise<void>;
 }
 
-// @public (undocumented)
-export type CatalogProcessor = {
-  getProcessorName(): string;
-  readLocation?(
-    location: LocationSpec,
-    optional: boolean,
-    emit: CatalogProcessorEmit,
-    parser: CatalogProcessorParser,
-    cache: CatalogProcessorCache,
-  ): Promise<boolean>;
-  preProcessEntity?(
-    entity: Entity,
-    location: LocationSpec,
-    emit: CatalogProcessorEmit,
-    originLocation: LocationSpec,
-    cache: CatalogProcessorCache,
-  ): Promise<Entity>;
-  validateEntityKind?(entity: Entity): Promise<boolean>;
-  postProcessEntity?(
-    entity: Entity,
-    location: LocationSpec,
-    emit: CatalogProcessorEmit,
-    cache: CatalogProcessorCache,
-  ): Promise<Entity>;
-};
+export { CatalogProcessor };
 
-// @public
-export interface CatalogProcessorCache {
-  get<ItemType extends JsonValue>(key: string): Promise<ItemType | undefined>;
-  set<ItemType extends JsonValue>(key: string, value: ItemType): Promise<void>;
-}
+export { CatalogProcessorCache };
 
-// @public (undocumented)
-export type CatalogProcessorEmit = (generated: CatalogProcessorResult) => void;
+export { CatalogProcessorEmit };
 
-// @public (undocumented)
-export type CatalogProcessorEntityResult = {
-  type: 'entity';
-  entity: Entity;
-  location: LocationSpec;
-};
+export { CatalogProcessorEntityResult };
 
-// @public (undocumented)
-export type CatalogProcessorErrorResult = {
-  type: 'error';
-  error: Error;
-  location: LocationSpec;
-};
+export { CatalogProcessorErrorResult };
 
-// @public (undocumented)
-export type CatalogProcessorLocationResult = {
-  type: 'location';
-  location: LocationSpec;
-};
+export { CatalogProcessorLocationResult };
 
-// @public
-export type CatalogProcessorParser = (options: {
-  data: Buffer;
-  location: LocationSpec;
-}) => AsyncIterable<CatalogProcessorResult>;
+export { CatalogProcessorParser };
 
-// @public (undocumented)
-export type CatalogProcessorRefreshKeysResult = {
-  type: 'refresh';
-  key: string;
-};
+export { CatalogProcessorRefreshKeysResult };
 
-// @public (undocumented)
-export type CatalogProcessorRelationResult = {
-  type: 'relation';
-  relation: EntityRelationSpec;
-};
+export { CatalogProcessorRelationResult };
 
-// @public (undocumented)
-export type CatalogProcessorResult =
-  | CatalogProcessorLocationResult
-  | CatalogProcessorEntityResult
-  | CatalogProcessorRelationResult
-  | CatalogProcessorErrorResult
-  | CatalogProcessorRefreshKeysResult;
+export { CatalogProcessorResult };
 
 // @public (undocumented)
 export class CodeOwnersProcessor implements CatalogProcessor {
@@ -394,11 +349,7 @@ export type DefaultCatalogCollatorFactoryOptions = {
   catalogClient?: CatalogApi;
 };
 
-// @public
-export type DeferredEntity = {
-  entity: Entity;
-  locationKey?: string;
-};
+export { DeferredEntity };
 
 // @public
 export type EntitiesSearchFilter = {
@@ -419,35 +370,13 @@ export type EntityFilter =
     }
   | EntitiesSearchFilter;
 
-// @public
-export interface EntityProvider {
-  connect(connection: EntityProviderConnection): Promise<void>;
-  getProviderName(): string;
-}
+export { EntityProvider };
 
-// @public
-export interface EntityProviderConnection {
-  applyMutation(mutation: EntityProviderMutation): Promise<void>;
-}
+export { EntityProviderConnection };
 
-// @public
-export type EntityProviderMutation =
-  | {
-      type: 'full';
-      entities: DeferredEntity[];
-    }
-  | {
-      type: 'delta';
-      added: DeferredEntity[];
-      removed: DeferredEntity[];
-    };
+export { EntityProviderMutation };
 
-// @public
-export type EntityRelationSpec = {
-  source: CompoundEntityRef;
-  type: string;
-  target: CompoundEntityRef;
-};
+export { EntityRelationSpec };
 
 // @public (undocumented)
 export class FileReaderProcessor implements CatalogProcessor {
@@ -487,12 +416,7 @@ export type LocationEntityProcessorOptions = {
   integrations: ScmIntegrationRegistry;
 };
 
-// @public
-export type LocationSpec = {
-  type: string;
-  target: string;
-  presence?: 'optional' | 'required';
-};
+export { LocationSpec };
 
 // @public (undocumented)
 export function locationSpecToLocationEntity(opts: {
@@ -593,28 +517,7 @@ export type PlaceholderResolverResolveUrl = (
 // @public
 export type ProcessingIntervalFunction = () => number;
 
-// @public
-export const processingResult: Readonly<{
-  readonly notFoundError: (
-    atLocation: LocationSpec,
-    message: string,
-  ) => CatalogProcessorResult;
-  readonly inputError: (
-    atLocation: LocationSpec,
-    message: string,
-  ) => CatalogProcessorResult;
-  readonly generalError: (
-    atLocation: LocationSpec,
-    message: string,
-  ) => CatalogProcessorResult;
-  readonly location: (newLocation: LocationSpec) => CatalogProcessorResult;
-  readonly entity: (
-    atLocation: LocationSpec,
-    newEntity: Entity,
-  ) => CatalogProcessorResult;
-  readonly relation: (spec: EntityRelationSpec) => CatalogProcessorResult;
-  readonly refresh: (key: string) => CatalogProcessorResult;
-}>;
+export { processingResult };
 
 // @public (undocumented)
 export class UrlReaderProcessor implements CatalogProcessor {

plugins/catalog-backend/package.json

@@ -34,6 +34,7 @@
     "clean": "backstage-cli package clean"
   },
   "dependencies": {
+    "@backstage/plugin-catalog-node": "^0.0.0",
     "@backstage/backend-common": "^0.14.1-next.2",
     "@backstage/catalog-client": "^1.0.4-next.1",
     "@backstage/catalog-model": "^1.1.0-next.2",

plugins/catalog-backend/src/database/DefaultProcessingDatabase.ts

@@ -35,7 +35,6 @@ import {
   ListParentsResult,
   RefreshByKeyOptions,
 } from './types';
-import { DeferredEntity } from '../processing/types';
 import { ProcessingIntervalFunction } from '../processing/refresh';
 import { rethrowError, timestampToDateTime } from './conversion';
 import { initDatabaseMetrics } from './metrics';
@@ -48,6 +47,7 @@ import {
 
 import { generateStableHash } from './util';
 import { isDatabaseConflictError } from '@backstage/backend-common';
+import { DeferredEntity } from '@backstage/plugin-catalog-node';
 
 // The number of items that are sent per batch to the database layer, when
 // doing .batchInsert calls to knex. This needs to be low enough to not cause

plugins/catalog-backend/src/database/types.ts

@@ -17,9 +17,12 @@
 import { Entity } from '@backstage/catalog-model';
 import { JsonObject } from '@backstage/types';
 import { DateTime } from 'luxon';
-import { EntityRelationSpec } from '../api';
-import { DeferredEntity, RefreshKeyData } from '../processing/types';
+import {
+  EntityRelationSpec,
+  DeferredEntity,
+} from '@backstage/plugin-catalog-node';
 import { DbRelationsRow } from './tables';
+import { RefreshKeyData } from '../processing/types';
 
 /**
  * An abstraction for transactions of the underlying database technology.

plugins/catalog-backend/src/index.ts

@@ -20,7 +20,26 @@
  * @packageDocumentation
  */
 
-export * from './api';
+export type {
+  DeferredEntity,
+  LocationSpec,
+  EntityRelationSpec,
+  CatalogProcessor,
+  CatalogProcessorParser,
+  CatalogProcessorCache,
+  CatalogProcessorEmit,
+  CatalogProcessorLocationResult,
+  CatalogProcessorEntityResult,
+  CatalogProcessorRelationResult,
+  CatalogProcessorErrorResult,
+  CatalogProcessorRefreshKeysResult,
+  CatalogProcessorResult,
+  EntityProvider,
+  EntityProviderConnection,
+  EntityProviderMutation,
+} from '@backstage/plugin-catalog-node';
+export { processingResult } from '@backstage/plugin-catalog-node';
+
 export * from './catalog';
 export * from './ingestion';
 export * from './modules';

plugins/catalog-backend/src/ingestion/CatalogRules.test.ts

@@ -17,7 +17,7 @@
 import { Entity } from '@backstage/catalog-model';
 import { ConfigReader } from '@backstage/config';
 import { DefaultCatalogRulesEnforcer } from './CatalogRules';
-import { LocationSpec } from '../api';
+import { LocationSpec } from '@backstage/plugin-catalog-node';
 
 const entity = {
   user: {

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

@@ -17,7 +17,7 @@
 import { Config } from '@backstage/config';
 import { Entity } from '@backstage/catalog-model';
 import path from 'path';
-import { LocationSpec } from '../api';
+import { LocationSpec } from '@backstage/plugin-catalog-node';
 
 /**
  * Rules to apply to catalog entities.

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

@@ -16,7 +16,7 @@
 
 import { Entity } from '@backstage/catalog-model';
 import { RecursivePartial } from '../util/RecursivePartial';
-import { LocationSpec } from '../api';
+import { LocationSpec } from '@backstage/plugin-catalog-node';
 
 /** @public */
 export type LocationAnalyzer = {

plugins/catalog-backend/src/modules/codeowners/CodeOwnersProcessor.test.ts

@@ -17,7 +17,7 @@
 import { getVoidLogger } from '@backstage/backend-common';
 import { ConfigReader } from '@backstage/config';
 import { CodeOwnersProcessor } from './CodeOwnersProcessor';
-import { LocationSpec } from '../../api';
+import { LocationSpec } from '@backstage/plugin-catalog-node';
 
 const mockCodeOwnersText = () => `
 *       @acme/team-foo @acme/team-bar

plugins/catalog-backend/src/modules/codeowners/CodeOwnersProcessor.ts

@@ -22,7 +22,7 @@ import {
   ScmIntegrations,
 } from '@backstage/integration';
 import { Logger } from 'winston';
-import { CatalogProcessor, LocationSpec } from '../../api';
+import { CatalogProcessor, LocationSpec } from '@backstage/plugin-catalog-node';
 import { findCodeOwnerByTarget } from './lib';
 
 const ALLOWED_KINDS = ['API', 'Component', 'Domain', 'Resource', 'System'];

plugins/catalog-backend/src/modules/core/AnnotateLocationEntityProcessor.test.ts

@@ -17,7 +17,7 @@
 import { Entity } from '@backstage/catalog-model';
 import { ConfigReader } from '@backstage/config';
 import { ScmIntegrations } from '@backstage/integration';
-import { LocationSpec } from '../../api';
+import { LocationSpec } from '@backstage/plugin-catalog-node';
 import { AnnotateLocationEntityProcessor } from './AnnotateLocationEntityProcessor';
 
 describe('AnnotateLocationEntityProcessor', () => {

plugins/catalog-backend/src/modules/core/AnnotateLocationEntityProcessor.ts

@@ -29,7 +29,7 @@ import {
   CatalogProcessor,
   CatalogProcessorEmit,
   LocationSpec,
-} from '../../api';
+} from '@backstage/plugin-catalog-node';
 
 /** @public */
 export class AnnotateLocationEntityProcessor implements CatalogProcessor {

plugins/catalog-backend/src/modules/core/AnnotateScmSlugEntityProcessor.test.ts

@@ -16,7 +16,7 @@
 import { Entity } from '@backstage/catalog-model';
 import { ConfigReader } from '@backstage/config';
 import { AnnotateScmSlugEntityProcessor } from './AnnotateScmSlugEntityProcessor';
-import { LocationSpec } from '../../api';
+import { LocationSpec } from '@backstage/plugin-catalog-node';
 
 describe('AnnotateScmSlugEntityProcessor', () => {
   describe('github', () => {

plugins/catalog-backend/src/modules/core/AnnotateScmSlugEntityProcessor.ts

@@ -21,7 +21,7 @@ import {
 } from '@backstage/integration';
 import parseGitUrl from 'git-url-parse';
 import { identity, merge, pickBy } from 'lodash';
-import { CatalogProcessor, LocationSpec } from '../../api';
+import { CatalogProcessor, LocationSpec } from '@backstage/plugin-catalog-node';
 
 const GITHUB_ACTIONS_ANNOTATION = 'github.com/project-slug';
 const GITLAB_ACTIONS_ANNOTATION = 'gitlab.com/project-slug';

plugins/catalog-backend/src/modules/core/BuiltinKindsEntityProcessor.ts

@@ -53,7 +53,7 @@ import {
   CatalogProcessorEmit,
   LocationSpec,
   processingResult,
-} from '../../api';
+} from '@backstage/plugin-catalog-node';
 
 /** @public */
 export class BuiltinKindsEntityProcessor implements CatalogProcessor {

plugins/catalog-backend/src/modules/core/ConfigLocationEntityProvider.test.ts

@@ -17,7 +17,7 @@
 import { ConfigReader } from '@backstage/config';
 import path from 'path';
 import { ConfigLocationEntityProvider } from './ConfigLocationEntityProvider';
-import { EntityProviderConnection } from '../../api';
+import { EntityProviderConnection } from '@backstage/plugin-catalog-node';
 
 describe('ConfigLocationEntityProvider', () => {
   it('should apply mutation with the correct paths in the config', async () => {

plugins/catalog-backend/src/modules/core/ConfigLocationEntityProvider.ts

@@ -17,7 +17,10 @@
 import { Config } from '@backstage/config';
 import path from 'path';
 import { getEntityLocationRef } from '../../processing/util';
-import { EntityProvider, EntityProviderConnection } from '../../api';
+import {
+  EntityProvider,
+  EntityProviderConnection,
+} from '@backstage/plugin-catalog-node';
 import { locationSpecToLocationEntity } from '../../util/conversion';
 
 export class ConfigLocationEntityProvider implements EntityProvider {

plugins/catalog-backend/src/modules/core/DefaultLocationStore.ts

@@ -20,7 +20,10 @@ import { Knex } from 'knex';
 import { v4 as uuid } from 'uuid';
 import { DbLocationsRow } from '../../database/tables';
 import { getEntityLocationRef } from '../../processing/util';
-import { EntityProvider, EntityProviderConnection } from '../../api';
+import {
+  EntityProvider,
+  EntityProviderConnection,
+} from '@backstage/plugin-catalog-node';
 import { locationSpecToLocationEntity } from '../../util/conversion';
 import { LocationInput, LocationStore } from '../../service/types';
 

plugins/catalog-backend/src/modules/core/FileReaderProcessor.test.ts

@@ -19,7 +19,7 @@ import {
   CatalogProcessorEntityResult,
   CatalogProcessorErrorResult,
   CatalogProcessorResult,
-} from '../../api';
+} from '@backstage/plugin-catalog-node';
 import path from 'path';
 import { defaultEntityDataParser } from '../util/parse';
 

plugins/catalog-backend/src/modules/core/FileReaderProcessor.ts

@@ -24,7 +24,7 @@ import {
   CatalogProcessorParser,
   LocationSpec,
   processingResult,
-} from '../../api';
+} from '@backstage/plugin-catalog-node';
 
 const glob = promisify(g);
 

plugins/catalog-backend/src/modules/core/LocationEntityProcessor.test.ts

@@ -21,7 +21,7 @@ import {
 } from '@backstage/integration';
 import path from 'path';
 import { toAbsoluteUrl } from './LocationEntityProcessor';
-import { LocationSpec } from '../../api';
+import { LocationSpec } from '@backstage/plugin-catalog-node';
 
 describe('LocationEntityProcessor', () => {
   describe('toAbsoluteUrl', () => {

plugins/catalog-backend/src/modules/core/LocationEntityProcessor.ts

@@ -22,7 +22,7 @@ import {
   CatalogProcessor,
   CatalogProcessorEmit,
   LocationSpec,
-} from '../../api';
+} from '@backstage/plugin-catalog-node';
 
 export function toAbsoluteUrl(
   integrations: ScmIntegrationRegistry,

plugins/catalog-backend/src/modules/core/PlaceholderProcessor.test.ts

@@ -17,7 +17,7 @@ import { UrlReader } from '@backstage/backend-common';
 import { Entity } from '@backstage/catalog-model';
 import { ConfigReader } from '@backstage/config';
 import { ScmIntegrations } from '@backstage/integration';
-import { CatalogProcessorResult } from '../../api';
+import { CatalogProcessorResult } from '@backstage/plugin-catalog-node';
 import {
   jsonPlaceholderResolver,
   PlaceholderProcessor,

plugins/catalog-backend/src/modules/core/PlaceholderProcessor.ts

@@ -24,7 +24,7 @@ import {
   CatalogProcessorEmit,
   LocationSpec,
   processingResult,
-} from '../../api';
+} from '@backstage/plugin-catalog-node';
 
 /** @public */
 export type PlaceholderResolverRead = (url: string) => Promise<Buffer>;

plugins/catalog-backend/src/modules/core/UrlReaderProcessor.test.ts

@@ -28,7 +28,7 @@ import {
   CatalogProcessorEntityResult,
   CatalogProcessorErrorResult,
   CatalogProcessorResult,
-} from '../../api';
+} from '@backstage/plugin-catalog-node';
 import { defaultEntityDataParser } from '../util/parse';
 import { UrlReaderProcessor } from './UrlReaderProcessor';
 

plugins/catalog-backend/src/modules/core/UrlReaderProcessor.ts

@@ -29,7 +29,7 @@ import {
   CatalogProcessorResult,
   LocationSpec,
   processingResult,
-} from '../../api';
+} from '@backstage/plugin-catalog-node';
 
 const CACHE_KEY = 'v1';
 

plugins/catalog-backend/src/modules/util/parse.test.ts

@@ -15,7 +15,7 @@
  */
 
 import { parseEntityYaml } from './parse';
-import { processingResult } from '../../api';
+import { processingResult } from '@backstage/plugin-catalog-node';
 
 const testLoc = {
   target: 'my-loc-target',

plugins/catalog-backend/src/modules/util/parse.ts

@@ -22,7 +22,7 @@ import {
   CatalogProcessorResult,
   LocationSpec,
   processingResult,
-} from '../../api';
+} from '@backstage/plugin-catalog-node';
 
 /** @public */
 export function* parseEntityYaml(

plugins/catalog-backend/src/processing/DefaultCatalogProcessingOrchestrator.test.ts

@@ -30,7 +30,7 @@ import {
   CatalogProcessorParser,
   LocationSpec,
   processingResult,
-} from '../api';
+} from '@backstage/plugin-catalog-node';
 import { CatalogRulesEnforcer } from '../ingestion/CatalogRules';
 import { DefaultCatalogProcessingOrchestrator } from './DefaultCatalogProcessingOrchestrator';
 import { defaultEntityDataParser } from '../modules/util/parse';

plugins/catalog-backend/src/processing/DefaultCatalogProcessingOrchestrator.ts

@@ -37,7 +37,7 @@ import {
   CatalogProcessorParser,
   LocationSpec,
   processingResult,
-} from '../api';
+} from '@backstage/plugin-catalog-node';
 import {
   CatalogProcessingOrchestrator,
   EntityProcessingRequest,

plugins/catalog-backend/src/processing/ProcessorCacheManager.test.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { CatalogProcessor } from '../api';
+import { CatalogProcessor } from '@backstage/plugin-catalog-node';
 import { ProcessorCacheManager } from './ProcessorCacheManager';
 
 class MyProcessor implements CatalogProcessor {

plugins/catalog-backend/src/processing/ProcessorCacheManager.ts

@@ -15,7 +15,10 @@
  */
 
 import { JsonObject, JsonValue } from '@backstage/types';
-import { CatalogProcessor, CatalogProcessorCache } from '../api';
+import {
+  CatalogProcessor,
+  CatalogProcessorCache,
+} from '@backstage/plugin-catalog-node';
 import { isObject } from './util';
 
 class SingleProcessorSubCache implements CatalogProcessorCache {

plugins/catalog-backend/src/processing/ProcessorOutputCollector.ts

@@ -22,14 +22,18 @@ import {
 } from '@backstage/catalog-model';
 import { assertError } from '@backstage/errors';
 import { Logger } from 'winston';
-import { CatalogProcessorResult, EntityRelationSpec } from '../api';
+import {
+  CatalogProcessorResult,
+  DeferredEntity,
+  EntityRelationSpec,
+} from '@backstage/plugin-catalog-node';
 import { locationSpecToLocationEntity } from '../util/conversion';
-import { DeferredEntity, RefreshKeyData } from './types';
 import {
   getEntityLocationRef,
   getEntityOriginLocationRef,
   validateEntityEnvelope,
 } from './util';
+import { RefreshKeyData } from './types';
 
 /**
  * Helper class for aggregating all of the emitted data from processors.

plugins/catalog-backend/src/processing/connectEntityProviders.ts

@@ -23,7 +23,7 @@ import {
   EntityProvider,
   EntityProviderConnection,
   EntityProviderMutation,
-} from '../api';
+} from '@backstage/plugin-catalog-node';
 
 class Connection implements EntityProviderConnection {
   readonly validateEntityEnvelope = entityEnvelopeSchemaValidator();

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

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-export type { CatalogProcessingEngine, DeferredEntity } from './types';
+export type { CatalogProcessingEngine } from './types';
 
 export { createRandomProcessingInterval } from './refresh';
 export type { ProcessingIntervalFunction } from './refresh';

plugins/catalog-backend/src/processing/types.ts

@@ -16,7 +16,10 @@
 
 import { Entity } from '@backstage/catalog-model';
 import { JsonObject } from '@backstage/types';
-import { EntityRelationSpec } from '../api';
+import {
+  DeferredEntity,
+  EntityRelationSpec,
+} from '@backstage/plugin-catalog-node';
 
 /**
  * The request to process an entity.
@@ -47,7 +50,6 @@ export type EntityProcessingResult =
 
 /**
  * A string to associate to the entity itself.
- * @public
  */
 export type RefreshKeyData = {
   key: string;
@@ -61,15 +63,6 @@ export interface CatalogProcessingOrchestrator {
   process(request: EntityProcessingRequest): Promise<EntityProcessingResult>;
 }
 
-/**
- * Entities that are not yet processed.
- * @public
- */
-export type DeferredEntity = {
-  entity: Entity;
-  locationKey?: string;
-};
-
 /** @public */
 export interface CatalogProcessingEngine {
   start(): Promise<void>;

plugins/catalog-backend/src/processing/util.ts

@@ -27,7 +27,7 @@ import { JsonObject, JsonValue } from '@backstage/types';
 import { InputError } from '@backstage/errors';
 import { ScmIntegrationRegistry } from '@backstage/integration';
 import path from 'path';
-import { LocationSpec } from '../api';
+import { LocationSpec } from '@backstage/plugin-catalog-node';
 
 export function isLocationEntity(entity: Entity): entity is LocationEntity {
   return entity.kind === 'Location';

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

@@ -36,7 +36,7 @@ import {
   CatalogProcessor,
   CatalogProcessorParser,
   EntityProvider,
-} from '../api';
+} from '@backstage/plugin-catalog-node';
 import {
   AnnotateLocationEntityProcessor,
   BuiltinKindsEntityProcessor,

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

@@ -21,13 +21,11 @@ import {
   stringifyEntityRef,
 } from '@backstage/catalog-model';
 import { Location } from '@backstage/catalog-client';
-import {
-  CatalogProcessingOrchestrator,
-  DeferredEntity,
-} from '../processing/types';
+import { CatalogProcessingOrchestrator } from '../processing/types';
 import { LocationInput, LocationService, LocationStore } from './types';
 import { locationSpecToMetadataName } from '../util/conversion';
 import { InputError } from '@backstage/errors';
+import { DeferredEntity } from '@backstage/plugin-catalog-node';
 
 export class DefaultLocationService implements LocationService {
   constructor(

plugins/catalog-backend/src/util/conversion.ts

@@ -23,7 +23,7 @@ import {
   stringifyLocationRef,
 } from '@backstage/catalog-model';
 import { createHash } from 'crypto';
-import { LocationSpec } from '../api';
+import { LocationSpec } from '@backstage/plugin-catalog-node';
 
 export function locationSpecToMetadataName(location: LocationSpec) {
   const hash = createHash('sha1')

plugins/catalog-node/.eslintrc.js

@@ -0,0 +1 @@
+module.exports = require('@backstage/cli/config/eslint-factory')(__dirname);

plugins/catalog-node/README.md

@@ -0,0 +1,3 @@
+# plugin-catalog-node
+
+Houses types and utilities for building catalog modules.

plugins/catalog-node/api-report.md

@@ -0,0 +1,158 @@
+## API Report File for "@backstage/plugin-catalog-node"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+/// <reference types="node" />
+
+import { CompoundEntityRef } from '@backstage/catalog-model';
+import { Entity } from '@backstage/catalog-model';
+import { JsonValue } from '@backstage/types';
+
+// @public (undocumented)
+export type CatalogProcessor = {
+  getProcessorName(): string;
+  readLocation?(
+    location: LocationSpec,
+    optional: boolean,
+    emit: CatalogProcessorEmit,
+    parser: CatalogProcessorParser,
+    cache: CatalogProcessorCache,
+  ): Promise<boolean>;
+  preProcessEntity?(
+    entity: Entity,
+    location: LocationSpec,
+    emit: CatalogProcessorEmit,
+    originLocation: LocationSpec,
+    cache: CatalogProcessorCache,
+  ): Promise<Entity>;
+  validateEntityKind?(entity: Entity): Promise<boolean>;
+  postProcessEntity?(
+    entity: Entity,
+    location: LocationSpec,
+    emit: CatalogProcessorEmit,
+    cache: CatalogProcessorCache,
+  ): Promise<Entity>;
+};
+
+// @public
+export interface CatalogProcessorCache {
+  get<ItemType extends JsonValue>(key: string): Promise<ItemType | undefined>;
+  set<ItemType extends JsonValue>(key: string, value: ItemType): Promise<void>;
+}
+
+// @public (undocumented)
+export type CatalogProcessorEmit = (generated: CatalogProcessorResult) => void;
+
+// @public (undocumented)
+export type CatalogProcessorEntityResult = {
+  type: 'entity';
+  entity: Entity;
+  location: LocationSpec;
+};
+
+// @public (undocumented)
+export type CatalogProcessorErrorResult = {
+  type: 'error';
+  error: Error;
+  location: LocationSpec;
+};
+
+// @public (undocumented)
+export type CatalogProcessorLocationResult = {
+  type: 'location';
+  location: LocationSpec;
+};
+
+// @public
+export type CatalogProcessorParser = (options: {
+  data: Buffer;
+  location: LocationSpec;
+}) => AsyncIterable<CatalogProcessorResult>;
+
+// @public (undocumented)
+export type CatalogProcessorRefreshKeysResult = {
+  type: 'refresh';
+  key: string;
+};
+
+// @public (undocumented)
+export type CatalogProcessorRelationResult = {
+  type: 'relation';
+  relation: EntityRelationSpec;
+};
+
+// @public (undocumented)
+export type CatalogProcessorResult =
+  | CatalogProcessorLocationResult
+  | CatalogProcessorEntityResult
+  | CatalogProcessorRelationResult
+  | CatalogProcessorErrorResult
+  | CatalogProcessorRefreshKeysResult;
+
+// @public
+export type DeferredEntity = {
+  entity: Entity;
+  locationKey?: string;
+};
+
+// @public
+export interface EntityProvider {
+  connect(connection: EntityProviderConnection): Promise<void>;
+  getProviderName(): string;
+}
+
+// @public
+export interface EntityProviderConnection {
+  applyMutation(mutation: EntityProviderMutation): Promise<void>;
+}
+
+// @public
+export type EntityProviderMutation =
+  | {
+      type: 'full';
+      entities: DeferredEntity[];
+    }
+  | {
+      type: 'delta';
+      added: DeferredEntity[];
+      removed: DeferredEntity[];
+    };
+
+// @public
+export type EntityRelationSpec = {
+  source: CompoundEntityRef;
+  type: string;
+  target: CompoundEntityRef;
+};
+
+// @public
+export type LocationSpec = {
+  type: string;
+  target: string;
+  presence?: 'optional' | 'required';
+};
+
+// @public
+export const processingResult: Readonly<{
+  readonly notFoundError: (
+    atLocation: LocationSpec,
+    message: string,
+  ) => CatalogProcessorResult;
+  readonly inputError: (
+    atLocation: LocationSpec,
+    message: string,
+  ) => CatalogProcessorResult;
+  readonly generalError: (
+    atLocation: LocationSpec,
+    message: string,
+  ) => CatalogProcessorResult;
+  readonly location: (newLocation: LocationSpec) => CatalogProcessorResult;
+  readonly entity: (
+    atLocation: LocationSpec,
+    newEntity: Entity,
+  ) => CatalogProcessorResult;
+  readonly relation: (spec: EntityRelationSpec) => CatalogProcessorResult;
+  readonly refresh: (key: string) => CatalogProcessorResult;
+}>;
+```

plugins/catalog-node/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@backstage/plugin-catalog-node",
+  "description": "The plugin-catalog-node module for @backstage/plugin-catalog-backend",
+  "version": "0.0.0",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "license": "Apache-2.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.cjs.js",
+    "types": "dist/index.d.ts",
+    "alphaTypes": "dist/index.alpha.d.ts"
+  },
+  "backstage": {
+    "role": "node-library"
+  },
+  "scripts": {
+    "start": "backstage-cli package start",
+    "build": "backstage-cli package build --experimental-type-build",
+    "lint": "backstage-cli package lint",
+    "test": "backstage-cli package test",
+    "clean": "backstage-cli package clean",
+    "prepack": "backstage-cli package prepack",
+    "postpack": "backstage-cli package postpack"
+  },
+  "dependencies": {
+    "@backstage/catalog-model": "^1.1.0-next.2",
+    "@backstage/errors": "1.1.0-next.0",
+    "@backstage/types": "^1.0.0"
+  },
+  "devDependencies": {
+    "@backstage/backend-common": "^0.14.1-next.2",
+    "@backstage/cli": "^0.18.0-next.2"
+  },
+  "files": [
+    "dist",
+    "alpha"
+  ]
+}

plugins/catalog-node/src/index.ts

@@ -0,0 +1,24 @@
+/*
+ * Copyright 2022 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.
+ */
+
+/**
+ * The catalog-backend-node module for `@backstage/plugin-catalog-backend`.
+ *
+ * @packageDocumentation
+ */
+
+export * from './api';
+export * from './processing';

plugins/catalog-node/src/processing/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 type { DeferredEntity } from './types';

plugins/catalog-node/src/processing/types.ts

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2022 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 } from '@backstage/catalog-model';
+
+/**
+ * Entities that are not yet processed.
+ * @public
+ */
+export type DeferredEntity = {
+  entity: Entity;
+  locationKey?: string;
+};