@backstage/plugin-catalog-node 0.0.0-nightly-20220709024234

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# @backstage/plugin-catalog-node
+
+## 0.0.0-nightly-20220709024234
+
+### Major Changes
+
+- 9a6aba1d85: 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.
+
+### Minor Changes
+
+- 91c1d12123: Added alpha exports for the new experimental backend system.
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/backend-plugin-api@0.0.0-nightly-20220709024234
+  - @backstage/catalog-model@0.0.0-nightly-20220709024234
+  - @backstage/errors@0.0.0-nightly-20220709024234

package/README.md

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

package/alpha/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "@backstage/plugin-catalog-node",
+  "version": "0.0.0-nightly-20220709024234",
+  "main": "../dist/index.cjs.js",
+  "types": "../dist/index.alpha.d.ts"
+}

package/dist/index.alpha.d.ts

@@ -0,0 +1,265 @@
+/**
+ * The catalog-backend-node module for `@backstage/plugin-catalog-backend`.
+ *
+ * @packageDocumentation
+ */
+
+/// <reference types="node" />
+
+import { CompoundEntityRef } from '@backstage/catalog-model';
+import { Entity } from '@backstage/catalog-model';
+import { JsonValue } from '@backstage/types';
+import { ServiceRef } from '@backstage/backend-plugin-api';
+
+/**
+ * @alpha
+ */
+export declare interface CatalogProcessingExtensionPoint {
+    addProcessor(processor: CatalogProcessor): void;
+    addEntityProvider(provider: EntityProvider): void;
+}
+
+/**
+ * @alpha
+ */
+export declare const catalogProcessingExtentionPoint: ServiceRef<CatalogProcessingExtensionPoint>;
+
+/**
+ * @public
+ */
+export declare type CatalogProcessor = {
+    /**
+     * A unique identifier for the Catalog Processor.
+     */
+    getProcessorName(): string;
+    /**
+     * Reads the contents of a location.
+     *
+     * @param location - The location to read
+     * @param optional - Whether a missing target should trigger an error
+     * @param emit - A sink for items resulting from the read
+     * @param parser - A parser, that is able to take the raw catalog descriptor
+     *               data and turn it into the actual result pieces.
+     * @param cache - A cache for storing values local to this processor and the current entity.
+     * @returns True if handled by this processor, false otherwise
+     */
+    readLocation?(location: LocationSpec, optional: boolean, emit: CatalogProcessorEmit, parser: CatalogProcessorParser, cache: CatalogProcessorCache): Promise<boolean>;
+    /**
+     * Pre-processes an emitted entity, after it has been emitted but before it
+     * has been validated.
+     *
+     * This type of processing usually involves enriching the entity with
+     * additional data, and the input entity may actually still be incomplete
+     * when the processor is invoked.
+     *
+     * @param entity - The (possibly partial) entity to process
+     * @param location - The location that the entity came from
+     * @param emit - A sink for auxiliary items resulting from the processing
+     * @param originLocation - The location that the entity originally came from.
+     *   While location resolves to the direct parent location, originLocation
+     *   tells which location was used to start the ingestion loop.
+     * @param cache - A cache for storing values local to this processor and the current entity.
+     * @returns The same entity or a modified version of it
+     */
+    preProcessEntity?(entity: Entity, location: LocationSpec, emit: CatalogProcessorEmit, originLocation: LocationSpec, cache: CatalogProcessorCache): Promise<Entity>;
+    /**
+     * Validates the entity as a known entity kind, after it has been pre-
+     * processed and has passed through basic overall validation.
+     *
+     * @param entity - The entity to validate
+     * @returns Resolves to true, if the entity was of a kind that was known and
+     *   handled by this processor, and was found to be valid. Resolves to false,
+     *   if the entity was not of a kind that was known by this processor.
+     *   Rejects to an Error describing the problem, if the entity was of a kind
+     *   that was known by this processor and was not valid.
+     */
+    validateEntityKind?(entity: Entity): Promise<boolean>;
+    /**
+     * Post-processes an emitted entity, after it has been validated.
+     *
+     * @param entity - The entity to process
+     * @param location - The location that the entity came from
+     * @param emit - A sink for auxiliary items resulting from the processing
+     * @param cache - A cache for storing values local to this processor and the current entity.
+     * @returns The same entity or a modified version of it
+     */
+    postProcessEntity?(entity: Entity, location: LocationSpec, emit: CatalogProcessorEmit, cache: CatalogProcessorCache): Promise<Entity>;
+};
+
+/**
+ * A cache for storing data during processing.
+ *
+ * The values stored in the cache are always local to each processor, meaning
+ * no processor can see cache values from other processors.
+ *
+ * The cache instance provided to the CatalogProcessor is also scoped to the
+ * entity being processed, meaning that each processor run can't see cache
+ * values from processing runs for other entities.
+ *
+ * Values that are set during a processing run will only be visible in the directly
+ * following run. The cache will be overwritten every run unless no new cache items
+ * are written, in which case the existing values remain in the cache.
+ *
+ * @public
+ */
+export declare interface CatalogProcessorCache {
+    /**
+     * Retrieve a value from the cache.
+     */
+    get<ItemType extends JsonValue>(key: string): Promise<ItemType | undefined>;
+    /**
+     * Store a value in the cache.
+     */
+    set<ItemType extends JsonValue>(key: string, value: ItemType): Promise<void>;
+}
+
+/** @public */
+export declare type CatalogProcessorEmit = (generated: CatalogProcessorResult) => void;
+
+/** @public */
+export declare type CatalogProcessorEntityResult = {
+    type: 'entity';
+    entity: Entity;
+    location: LocationSpec;
+};
+
+/** @public */
+export declare type CatalogProcessorErrorResult = {
+    type: 'error';
+    error: Error;
+    location: LocationSpec;
+};
+
+/** @public */
+export declare type CatalogProcessorLocationResult = {
+    type: 'location';
+    location: LocationSpec;
+};
+
+/**
+ * A parser, that is able to take the raw catalog descriptor data and turn it
+ * into the actual result pieces. The default implementation performs a YAML
+ * document parsing.
+ * @public
+ */
+export declare type CatalogProcessorParser = (options: {
+    data: Buffer;
+    location: LocationSpec;
+}) => AsyncIterable<CatalogProcessorResult>;
+
+/** @public */
+export declare type CatalogProcessorRefreshKeysResult = {
+    type: 'refresh';
+    key: string;
+};
+
+/** @public */
+export declare type CatalogProcessorRelationResult = {
+    type: 'relation';
+    relation: EntityRelationSpec;
+};
+
+/** @public */
+export declare type CatalogProcessorResult = CatalogProcessorLocationResult | CatalogProcessorEntityResult | CatalogProcessorRelationResult | CatalogProcessorErrorResult | CatalogProcessorRefreshKeysResult;
+
+/**
+ * Entities that are not yet processed.
+ * @public
+ */
+export declare type DeferredEntity = {
+    entity: Entity;
+    locationKey?: string;
+};
+
+/**
+ * An EntityProvider is able to provide entities to the catalog.
+ * See https://backstage.io/docs/features/software-catalog/life-of-an-entity for more details.
+ * @public
+ */
+export declare interface EntityProvider {
+    /** Unique provider name used internally for caching. */
+    getProviderName(): string;
+    /** Connect is called upon initialization by the catalog engine. */
+    connect(connection: EntityProviderConnection): Promise<void>;
+}
+
+/**
+ * The EntityProviderConnection is the connection between the catalog and the entity provider.
+ * The EntityProvider use this connection to add and remove entities from the catalog.
+ * @public
+ */
+export declare interface EntityProviderConnection {
+    /**
+     * Applies either a full or delta update to the catalog engine.
+     */
+    applyMutation(mutation: EntityProviderMutation): Promise<void>;
+}
+
+/**
+ * @public
+ * A 'full' mutation replaces all existing entities created by this entity provider with new ones.
+ * A 'delta' mutation can both add and remove entities provided by this provider. Previously provided
+ * entities from a 'full' mutation are not removed.
+ */
+export declare type EntityProviderMutation = {
+    type: 'full';
+    entities: DeferredEntity[];
+} | {
+    type: 'delta';
+    added: DeferredEntity[];
+    removed: DeferredEntity[];
+};
+
+/**
+ * Holds the relation data for entities.
+ *
+ * @public
+ */
+export declare type EntityRelationSpec = {
+    /**
+     * The source entity of this relation.
+     */
+    source: CompoundEntityRef;
+    /**
+     * The type of the relation.
+     */
+    type: string;
+    /**
+     * The target entity of this relation.
+     */
+    target: CompoundEntityRef;
+};
+
+/**
+ * Holds the entity location information.
+ *
+ * @remarks
+ *
+ *  `presence` flag: when using repo importer plugin, location is being created before the component yaml file is merged to the main branch.
+ *  This flag is then set to indicate that the file can be not present.
+ *  default value: 'required'.
+ *
+ * @public
+ */
+export declare type LocationSpec = {
+    type: string;
+    target: string;
+    presence?: 'optional' | 'required';
+};
+
+/**
+ * Factory functions for the standard processing result types.
+ *
+ * @public
+ */
+export declare 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 { }

package/dist/index.beta.d.ts

@@ -0,0 +1,256 @@
+/**
+ * The catalog-backend-node module for `@backstage/plugin-catalog-backend`.
+ *
+ * @packageDocumentation
+ */
+
+/// <reference types="node" />
+
+import { CompoundEntityRef } from '@backstage/catalog-model';
+import { Entity } from '@backstage/catalog-model';
+import { JsonValue } from '@backstage/types';
+import { ServiceRef } from '@backstage/backend-plugin-api';
+
+/* Excluded from this release type: CatalogProcessingExtensionPoint */
+
+/* Excluded from this release type: catalogProcessingExtentionPoint */
+
+/**
+ * @public
+ */
+export declare type CatalogProcessor = {
+    /**
+     * A unique identifier for the Catalog Processor.
+     */
+    getProcessorName(): string;
+    /**
+     * Reads the contents of a location.
+     *
+     * @param location - The location to read
+     * @param optional - Whether a missing target should trigger an error
+     * @param emit - A sink for items resulting from the read
+     * @param parser - A parser, that is able to take the raw catalog descriptor
+     *               data and turn it into the actual result pieces.
+     * @param cache - A cache for storing values local to this processor and the current entity.
+     * @returns True if handled by this processor, false otherwise
+     */
+    readLocation?(location: LocationSpec, optional: boolean, emit: CatalogProcessorEmit, parser: CatalogProcessorParser, cache: CatalogProcessorCache): Promise<boolean>;
+    /**
+     * Pre-processes an emitted entity, after it has been emitted but before it
+     * has been validated.
+     *
+     * This type of processing usually involves enriching the entity with
+     * additional data, and the input entity may actually still be incomplete
+     * when the processor is invoked.
+     *
+     * @param entity - The (possibly partial) entity to process
+     * @param location - The location that the entity came from
+     * @param emit - A sink for auxiliary items resulting from the processing
+     * @param originLocation - The location that the entity originally came from.
+     *   While location resolves to the direct parent location, originLocation
+     *   tells which location was used to start the ingestion loop.
+     * @param cache - A cache for storing values local to this processor and the current entity.
+     * @returns The same entity or a modified version of it
+     */
+    preProcessEntity?(entity: Entity, location: LocationSpec, emit: CatalogProcessorEmit, originLocation: LocationSpec, cache: CatalogProcessorCache): Promise<Entity>;
+    /**
+     * Validates the entity as a known entity kind, after it has been pre-
+     * processed and has passed through basic overall validation.
+     *
+     * @param entity - The entity to validate
+     * @returns Resolves to true, if the entity was of a kind that was known and
+     *   handled by this processor, and was found to be valid. Resolves to false,
+     *   if the entity was not of a kind that was known by this processor.
+     *   Rejects to an Error describing the problem, if the entity was of a kind
+     *   that was known by this processor and was not valid.
+     */
+    validateEntityKind?(entity: Entity): Promise<boolean>;
+    /**
+     * Post-processes an emitted entity, after it has been validated.
+     *
+     * @param entity - The entity to process
+     * @param location - The location that the entity came from
+     * @param emit - A sink for auxiliary items resulting from the processing
+     * @param cache - A cache for storing values local to this processor and the current entity.
+     * @returns The same entity or a modified version of it
+     */
+    postProcessEntity?(entity: Entity, location: LocationSpec, emit: CatalogProcessorEmit, cache: CatalogProcessorCache): Promise<Entity>;
+};
+
+/**
+ * A cache for storing data during processing.
+ *
+ * The values stored in the cache are always local to each processor, meaning
+ * no processor can see cache values from other processors.
+ *
+ * The cache instance provided to the CatalogProcessor is also scoped to the
+ * entity being processed, meaning that each processor run can't see cache
+ * values from processing runs for other entities.
+ *
+ * Values that are set during a processing run will only be visible in the directly
+ * following run. The cache will be overwritten every run unless no new cache items
+ * are written, in which case the existing values remain in the cache.
+ *
+ * @public
+ */
+export declare interface CatalogProcessorCache {
+    /**
+     * Retrieve a value from the cache.
+     */
+    get<ItemType extends JsonValue>(key: string): Promise<ItemType | undefined>;
+    /**
+     * Store a value in the cache.
+     */
+    set<ItemType extends JsonValue>(key: string, value: ItemType): Promise<void>;
+}
+
+/** @public */
+export declare type CatalogProcessorEmit = (generated: CatalogProcessorResult) => void;
+
+/** @public */
+export declare type CatalogProcessorEntityResult = {
+    type: 'entity';
+    entity: Entity;
+    location: LocationSpec;
+};
+
+/** @public */
+export declare type CatalogProcessorErrorResult = {
+    type: 'error';
+    error: Error;
+    location: LocationSpec;
+};
+
+/** @public */
+export declare type CatalogProcessorLocationResult = {
+    type: 'location';
+    location: LocationSpec;
+};
+
+/**
+ * A parser, that is able to take the raw catalog descriptor data and turn it
+ * into the actual result pieces. The default implementation performs a YAML
+ * document parsing.
+ * @public
+ */
+export declare type CatalogProcessorParser = (options: {
+    data: Buffer;
+    location: LocationSpec;
+}) => AsyncIterable<CatalogProcessorResult>;
+
+/** @public */
+export declare type CatalogProcessorRefreshKeysResult = {
+    type: 'refresh';
+    key: string;
+};
+
+/** @public */
+export declare type CatalogProcessorRelationResult = {
+    type: 'relation';
+    relation: EntityRelationSpec;
+};
+
+/** @public */
+export declare type CatalogProcessorResult = CatalogProcessorLocationResult | CatalogProcessorEntityResult | CatalogProcessorRelationResult | CatalogProcessorErrorResult | CatalogProcessorRefreshKeysResult;
+
+/**
+ * Entities that are not yet processed.
+ * @public
+ */
+export declare type DeferredEntity = {
+    entity: Entity;
+    locationKey?: string;
+};
+
+/**
+ * An EntityProvider is able to provide entities to the catalog.
+ * See https://backstage.io/docs/features/software-catalog/life-of-an-entity for more details.
+ * @public
+ */
+export declare interface EntityProvider {
+    /** Unique provider name used internally for caching. */
+    getProviderName(): string;
+    /** Connect is called upon initialization by the catalog engine. */
+    connect(connection: EntityProviderConnection): Promise<void>;
+}
+
+/**
+ * The EntityProviderConnection is the connection between the catalog and the entity provider.
+ * The EntityProvider use this connection to add and remove entities from the catalog.
+ * @public
+ */
+export declare interface EntityProviderConnection {
+    /**
+     * Applies either a full or delta update to the catalog engine.
+     */
+    applyMutation(mutation: EntityProviderMutation): Promise<void>;
+}
+
+/**
+ * @public
+ * A 'full' mutation replaces all existing entities created by this entity provider with new ones.
+ * A 'delta' mutation can both add and remove entities provided by this provider. Previously provided
+ * entities from a 'full' mutation are not removed.
+ */
+export declare type EntityProviderMutation = {
+    type: 'full';
+    entities: DeferredEntity[];
+} | {
+    type: 'delta';
+    added: DeferredEntity[];
+    removed: DeferredEntity[];
+};
+
+/**
+ * Holds the relation data for entities.
+ *
+ * @public
+ */
+export declare type EntityRelationSpec = {
+    /**
+     * The source entity of this relation.
+     */
+    source: CompoundEntityRef;
+    /**
+     * The type of the relation.
+     */
+    type: string;
+    /**
+     * The target entity of this relation.
+     */
+    target: CompoundEntityRef;
+};
+
+/**
+ * Holds the entity location information.
+ *
+ * @remarks
+ *
+ *  `presence` flag: when using repo importer plugin, location is being created before the component yaml file is merged to the main branch.
+ *  This flag is then set to indicate that the file can be not present.
+ *  default value: 'required'.
+ *
+ * @public
+ */
+export declare type LocationSpec = {
+    type: string;
+    target: string;
+    presence?: 'optional' | 'required';
+};
+
+/**
+ * Factory functions for the standard processing result types.
+ *
+ * @public
+ */
+export declare 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 { }

package/dist/index.cjs.js

@@ -0,0 +1,46 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var backendPluginApi = require('@backstage/backend-plugin-api');
+var errors = require('@backstage/errors');
+
+const catalogProcessingExtentionPoint = backendPluginApi.createServiceRef({
+  id: "catalog.processing"
+});
+
+const processingResult = Object.freeze({
+  notFoundError(atLocation, message) {
+    return {
+      type: "error",
+      location: atLocation,
+      error: new errors.NotFoundError(message)
+    };
+  },
+  inputError(atLocation, message) {
+    return {
+      type: "error",
+      location: atLocation,
+      error: new errors.InputError(message)
+    };
+  },
+  generalError(atLocation, message) {
+    return { type: "error", location: atLocation, error: new Error(message) };
+  },
+  location(newLocation) {
+    return { type: "location", location: newLocation };
+  },
+  entity(atLocation, newEntity) {
+    return { type: "entity", location: atLocation, entity: newEntity };
+  },
+  relation(spec) {
+    return { type: "relation", relation: spec };
+  },
+  refresh(key) {
+    return { type: "refresh", key };
+  }
+});
+
+exports.catalogProcessingExtentionPoint = catalogProcessingExtentionPoint;
+exports.processingResult = processingResult;
+//# sourceMappingURL=index.cjs.js.map

package/dist/index.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs.js","sources":["../src/extensions.ts","../src/api/processingResult.ts"],"sourcesContent":["/*\n * Copyright 2022 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport { createServiceRef } from '@backstage/backend-plugin-api';\nimport { EntityProvider } from './api';\nimport { CatalogProcessor } from './api/processor';\n\n/**\n * @alpha\n */\nexport interface CatalogProcessingExtensionPoint {\n  addProcessor(processor: CatalogProcessor): void;\n  addEntityProvider(provider: EntityProvider): void;\n}\n\n/**\n * @alpha\n */\nexport const catalogProcessingExtentionPoint =\n  createServiceRef<CatalogProcessingExtensionPoint>({\n    id: 'catalog.processing',\n  });\n","/*\n * Copyright 2020 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { InputError, NotFoundError } from '@backstage/errors';\nimport { Entity } from '@backstage/catalog-model';\nimport { CatalogProcessorResult } from './processor';\nimport { EntityRelationSpec, LocationSpec } from './common';\n\n/**\n * Factory functions for the standard processing result types.\n *\n * @public\n */\nexport const processingResult = Object.freeze({\n  notFoundError(\n    atLocation: LocationSpec,\n    message: string,\n  ): CatalogProcessorResult {\n    return {\n      type: 'error',\n      location: atLocation,\n      error: new NotFoundError(message),\n    };\n  },\n\n  inputError(\n    atLocation: LocationSpec,\n    message: string,\n  ): CatalogProcessorResult {\n    return {\n      type: 'error',\n      location: atLocation,\n      error: new InputError(message),\n    };\n  },\n\n  generalError(\n    atLocation: LocationSpec,\n    message: string,\n  ): CatalogProcessorResult {\n    return { type: 'error', location: atLocation, error: new Error(message) };\n  },\n\n  location(newLocation: LocationSpec): CatalogProcessorResult {\n    return { type: 'location', location: newLocation };\n  },\n\n  entity(atLocation: LocationSpec, newEntity: Entity): CatalogProcessorResult {\n    return { type: 'entity', location: atLocation, entity: newEntity };\n  },\n\n  relation(spec: EntityRelationSpec): CatalogProcessorResult {\n    return { type: 'relation', relation: spec };\n  },\n\n  refresh(key: string): CatalogProcessorResult {\n    return { type: 'refresh', key };\n  },\n} as const);\n"],"names":["createServiceRef","NotFoundError","InputError"],"mappings":";;;;;;;AACY,MAAC,+BAA+B,GAAGA,iCAAgB,CAAC;AAChE,EAAE,EAAE,EAAE,oBAAoB;AAC1B,CAAC;;ACFW,MAAC,gBAAgB,GAAG,MAAM,CAAC,MAAM,CAAC;AAC9C,EAAE,aAAa,CAAC,UAAU,EAAE,OAAO,EAAE;AACrC,IAAI,OAAO;AACX,MAAM,IAAI,EAAE,OAAO;AACnB,MAAM,QAAQ,EAAE,UAAU;AAC1B,MAAM,KAAK,EAAE,IAAIC,oBAAa,CAAC,OAAO,CAAC;AACvC,KAAK,CAAC;AACN,GAAG;AACH,EAAE,UAAU,CAAC,UAAU,EAAE,OAAO,EAAE;AAClC,IAAI,OAAO;AACX,MAAM,IAAI,EAAE,OAAO;AACnB,MAAM,QAAQ,EAAE,UAAU;AAC1B,MAAM,KAAK,EAAE,IAAIC,iBAAU,CAAC,OAAO,CAAC;AACpC,KAAK,CAAC;AACN,GAAG;AACH,EAAE,YAAY,CAAC,UAAU,EAAE,OAAO,EAAE;AACpC,IAAI,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;AAC9E,GAAG;AACH,EAAE,QAAQ,CAAC,WAAW,EAAE;AACxB,IAAI,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;AACvD,GAAG;AACH,EAAE,MAAM,CAAC,UAAU,EAAE,SAAS,EAAE;AAChC,IAAI,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AACvE,GAAG;AACH,EAAE,QAAQ,CAAC,IAAI,EAAE;AACjB,IAAI,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAChD,GAAG;AACH,EAAE,OAAO,CAAC,GAAG,EAAE;AACf,IAAI,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC;AACpC,GAAG;AACH,CAAC;;;;;"}

package/dist/index.d.ts

@@ -0,0 +1,256 @@
+/**
+ * The catalog-backend-node module for `@backstage/plugin-catalog-backend`.
+ *
+ * @packageDocumentation
+ */
+
+/// <reference types="node" />
+
+import { CompoundEntityRef } from '@backstage/catalog-model';
+import { Entity } from '@backstage/catalog-model';
+import { JsonValue } from '@backstage/types';
+import { ServiceRef } from '@backstage/backend-plugin-api';
+
+/* Excluded from this release type: CatalogProcessingExtensionPoint */
+
+/* Excluded from this release type: catalogProcessingExtentionPoint */
+
+/**
+ * @public
+ */
+export declare type CatalogProcessor = {
+    /**
+     * A unique identifier for the Catalog Processor.
+     */
+    getProcessorName(): string;
+    /**
+     * Reads the contents of a location.
+     *
+     * @param location - The location to read
+     * @param optional - Whether a missing target should trigger an error
+     * @param emit - A sink for items resulting from the read
+     * @param parser - A parser, that is able to take the raw catalog descriptor
+     *               data and turn it into the actual result pieces.
+     * @param cache - A cache for storing values local to this processor and the current entity.
+     * @returns True if handled by this processor, false otherwise
+     */
+    readLocation?(location: LocationSpec, optional: boolean, emit: CatalogProcessorEmit, parser: CatalogProcessorParser, cache: CatalogProcessorCache): Promise<boolean>;
+    /**
+     * Pre-processes an emitted entity, after it has been emitted but before it
+     * has been validated.
+     *
+     * This type of processing usually involves enriching the entity with
+     * additional data, and the input entity may actually still be incomplete
+     * when the processor is invoked.
+     *
+     * @param entity - The (possibly partial) entity to process
+     * @param location - The location that the entity came from
+     * @param emit - A sink for auxiliary items resulting from the processing
+     * @param originLocation - The location that the entity originally came from.
+     *   While location resolves to the direct parent location, originLocation
+     *   tells which location was used to start the ingestion loop.
+     * @param cache - A cache for storing values local to this processor and the current entity.
+     * @returns The same entity or a modified version of it
+     */
+    preProcessEntity?(entity: Entity, location: LocationSpec, emit: CatalogProcessorEmit, originLocation: LocationSpec, cache: CatalogProcessorCache): Promise<Entity>;
+    /**
+     * Validates the entity as a known entity kind, after it has been pre-
+     * processed and has passed through basic overall validation.
+     *
+     * @param entity - The entity to validate
+     * @returns Resolves to true, if the entity was of a kind that was known and
+     *   handled by this processor, and was found to be valid. Resolves to false,
+     *   if the entity was not of a kind that was known by this processor.
+     *   Rejects to an Error describing the problem, if the entity was of a kind
+     *   that was known by this processor and was not valid.
+     */
+    validateEntityKind?(entity: Entity): Promise<boolean>;
+    /**
+     * Post-processes an emitted entity, after it has been validated.
+     *
+     * @param entity - The entity to process
+     * @param location - The location that the entity came from
+     * @param emit - A sink for auxiliary items resulting from the processing
+     * @param cache - A cache for storing values local to this processor and the current entity.
+     * @returns The same entity or a modified version of it
+     */
+    postProcessEntity?(entity: Entity, location: LocationSpec, emit: CatalogProcessorEmit, cache: CatalogProcessorCache): Promise<Entity>;
+};
+
+/**
+ * A cache for storing data during processing.
+ *
+ * The values stored in the cache are always local to each processor, meaning
+ * no processor can see cache values from other processors.
+ *
+ * The cache instance provided to the CatalogProcessor is also scoped to the
+ * entity being processed, meaning that each processor run can't see cache
+ * values from processing runs for other entities.
+ *
+ * Values that are set during a processing run will only be visible in the directly
+ * following run. The cache will be overwritten every run unless no new cache items
+ * are written, in which case the existing values remain in the cache.
+ *
+ * @public
+ */
+export declare interface CatalogProcessorCache {
+    /**
+     * Retrieve a value from the cache.
+     */
+    get<ItemType extends JsonValue>(key: string): Promise<ItemType | undefined>;
+    /**
+     * Store a value in the cache.
+     */
+    set<ItemType extends JsonValue>(key: string, value: ItemType): Promise<void>;
+}
+
+/** @public */
+export declare type CatalogProcessorEmit = (generated: CatalogProcessorResult) => void;
+
+/** @public */
+export declare type CatalogProcessorEntityResult = {
+    type: 'entity';
+    entity: Entity;
+    location: LocationSpec;
+};
+
+/** @public */
+export declare type CatalogProcessorErrorResult = {
+    type: 'error';
+    error: Error;
+    location: LocationSpec;
+};
+
+/** @public */
+export declare type CatalogProcessorLocationResult = {
+    type: 'location';
+    location: LocationSpec;
+};
+
+/**
+ * A parser, that is able to take the raw catalog descriptor data and turn it
+ * into the actual result pieces. The default implementation performs a YAML
+ * document parsing.
+ * @public
+ */
+export declare type CatalogProcessorParser = (options: {
+    data: Buffer;
+    location: LocationSpec;
+}) => AsyncIterable<CatalogProcessorResult>;
+
+/** @public */
+export declare type CatalogProcessorRefreshKeysResult = {
+    type: 'refresh';
+    key: string;
+};
+
+/** @public */
+export declare type CatalogProcessorRelationResult = {
+    type: 'relation';
+    relation: EntityRelationSpec;
+};
+
+/** @public */
+export declare type CatalogProcessorResult = CatalogProcessorLocationResult | CatalogProcessorEntityResult | CatalogProcessorRelationResult | CatalogProcessorErrorResult | CatalogProcessorRefreshKeysResult;
+
+/**
+ * Entities that are not yet processed.
+ * @public
+ */
+export declare type DeferredEntity = {
+    entity: Entity;
+    locationKey?: string;
+};
+
+/**
+ * An EntityProvider is able to provide entities to the catalog.
+ * See https://backstage.io/docs/features/software-catalog/life-of-an-entity for more details.
+ * @public
+ */
+export declare interface EntityProvider {
+    /** Unique provider name used internally for caching. */
+    getProviderName(): string;
+    /** Connect is called upon initialization by the catalog engine. */
+    connect(connection: EntityProviderConnection): Promise<void>;
+}
+
+/**
+ * The EntityProviderConnection is the connection between the catalog and the entity provider.
+ * The EntityProvider use this connection to add and remove entities from the catalog.
+ * @public
+ */
+export declare interface EntityProviderConnection {
+    /**
+     * Applies either a full or delta update to the catalog engine.
+     */
+    applyMutation(mutation: EntityProviderMutation): Promise<void>;
+}
+
+/**
+ * @public
+ * A 'full' mutation replaces all existing entities created by this entity provider with new ones.
+ * A 'delta' mutation can both add and remove entities provided by this provider. Previously provided
+ * entities from a 'full' mutation are not removed.
+ */
+export declare type EntityProviderMutation = {
+    type: 'full';
+    entities: DeferredEntity[];
+} | {
+    type: 'delta';
+    added: DeferredEntity[];
+    removed: DeferredEntity[];
+};
+
+/**
+ * Holds the relation data for entities.
+ *
+ * @public
+ */
+export declare type EntityRelationSpec = {
+    /**
+     * The source entity of this relation.
+     */
+    source: CompoundEntityRef;
+    /**
+     * The type of the relation.
+     */
+    type: string;
+    /**
+     * The target entity of this relation.
+     */
+    target: CompoundEntityRef;
+};
+
+/**
+ * Holds the entity location information.
+ *
+ * @remarks
+ *
+ *  `presence` flag: when using repo importer plugin, location is being created before the component yaml file is merged to the main branch.
+ *  This flag is then set to indicate that the file can be not present.
+ *  default value: 'required'.
+ *
+ * @public
+ */
+export declare type LocationSpec = {
+    type: string;
+    target: string;
+    presence?: 'optional' | 'required';
+};
+
+/**
+ * Factory functions for the standard processing result types.
+ *
+ * @public
+ */
+export declare 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 { }

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@backstage/plugin-catalog-node",
+  "description": "The plugin-catalog-node module for @backstage/plugin-catalog-backend",
+  "version": "0.0.0-nightly-20220709024234",
+  "main": "dist/index.cjs.js",
+  "types": "dist/index.d.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/backend-plugin-api": "0.0.0-nightly-20220709024234",
+    "@backstage/catalog-model": "0.0.0-nightly-20220709024234",
+    "@backstage/errors": "0.0.0-nightly-20220709024234",
+    "@backstage/types": "^1.0.0"
+  },
+  "devDependencies": {
+    "@backstage/backend-common": "0.0.0-nightly-20220709024234",
+    "@backstage/cli": "0.0.0-nightly-20220709024234"
+  },
+  "files": [
+    "dist",
+    "alpha"
+  ]
+}