@backstage/plugin-catalog-backend 0.21.4 → 0.21.5

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @backstage/plugin-catalog-backend
 
+## 0.21.5
+
+### Patch Changes
+
+- Fix for the previous release with missing type declarations.
+- Updated dependencies
+  - @backstage/backend-common@0.10.9
+  - @backstage/catalog-client@0.7.1
+  - @backstage/catalog-model@0.10.1
+  - @backstage/config@0.1.15
+  - @backstage/errors@0.2.2
+  - @backstage/integration@0.7.4
+  - @backstage/search-common@0.2.4
+  - @backstage/types@0.1.3
+  - @backstage/plugin-catalog-common@0.1.4
+  - @backstage/plugin-permission-common@0.5.1
+  - @backstage/plugin-permission-node@0.5.1
+  - @backstage/plugin-scaffolder-common@0.2.1
+
 ## 0.21.4
 
 ### Patch Changes

package/dist/index.d.ts

@@ -0,0 +1,1144 @@
+/// <reference types="node" />
+import * as _backstage_catalog_model from '@backstage/catalog-model';
+import { Entity, LocationSpec, EntityRelationSpec, ResourceEntityV1alpha1, EntityPolicy, Validators } from '@backstage/catalog-model';
+import { Config } from '@backstage/config';
+import { JsonValue, JsonObject } from '@backstage/types';
+import { ScmIntegrationRegistry, BitbucketIntegration, GithubCredentialsProvider, GitHubIntegrationConfig } from '@backstage/integration';
+import { Organizations } from 'aws-sdk';
+import { Account } from 'aws-sdk/clients/organizations';
+import { Logger } from 'winston';
+import { UrlReader, PluginEndpointDiscovery, TokenManager, PluginDatabaseManager } from '@backstage/backend-common';
+import * as _backstage_plugin_permission_common from '@backstage/plugin-permission-common';
+import { PermissionAuthorizer } from '@backstage/plugin-permission-common';
+import { IndexableDocument, DocumentCollator } from '@backstage/search-common';
+import { GetEntitiesRequest, CatalogApi, Location } from '@backstage/catalog-client';
+import express, { Router } from 'express';
+import * as _backstage_plugin_permission_node from '@backstage/plugin-permission-node';
+import { PermissionRule } from '@backstage/plugin-permission-node';
+
+/**
+ * A filter expression for entities.
+ *
+ * Any (at least one) of the outer sets must match, within which all of the
+ * individual filters must match.
+ */
+declare type EntityFilter = {
+    allOf: EntityFilter[];
+} | {
+    anyOf: EntityFilter[];
+} | {
+    not: EntityFilter;
+} | EntitiesSearchFilter;
+/**
+ * A pagination rule for entities.
+ */
+declare type EntityPagination = {
+    limit?: number;
+    offset?: number;
+    after?: string;
+};
+/**
+ * Matches rows in the entities_search table.
+ */
+declare type EntitiesSearchFilter = {
+    /**
+     * The key to match on.
+     *
+     * Matches are always case insensitive.
+     */
+    key: string;
+    /**
+     * Match on plain equality of values.
+     *
+     * Match on values that are equal to any of the given array items. Matches are
+     * always case insensitive.
+     */
+    values?: string[];
+};
+declare type PageInfo = {
+    hasNextPage: false;
+} | {
+    hasNextPage: true;
+    endCursor: string;
+};
+declare type EntitiesRequest = {
+    filter?: EntityFilter;
+    fields?: (entity: Entity) => Entity;
+    pagination?: EntityPagination;
+    authorizationToken?: string;
+};
+declare type EntitiesResponse = {
+    entities: Entity[];
+    pageInfo: PageInfo;
+};
+/** @public */
+declare type EntityAncestryResponse = {
+    rootEntityRef: string;
+    items: Array<{
+        entity: Entity;
+        parentEntityRefs: string[];
+    }>;
+};
+/** @public */
+declare type EntitiesCatalog = {
+    /**
+     * Fetch entities.
+     *
+     * @param request - Request options
+     */
+    entities(request?: EntitiesRequest): Promise<EntitiesResponse>;
+    /**
+     * Removes a single entity.
+     *
+     * @param uid - The metadata.uid of the entity
+     */
+    removeEntityByUid(uid: string, options?: {
+        authorizationToken?: string;
+    }): Promise<void>;
+    /**
+     * Returns the full ancestry tree upward along reference edges.
+     *
+     * @param entityRef - An entity reference to the root of the tree
+     */
+    entityAncestry(entityRef: string, options?: {
+        authorizationToken?: string;
+    }): Promise<EntityAncestryResponse>;
+};
+
+/**
+ * Rules to apply to catalog entities.
+ *
+ * An undefined list of matchers means match all, an empty list of matchers means match none.
+ *
+ * @public
+ */
+declare type CatalogRule = {
+    allow: Array<{
+        kind: string;
+    }>;
+    locations?: Array<{
+        target?: string;
+        type: string;
+    }>;
+};
+/**
+ * Decides whether an entity from a given location is allowed to enter the
+ * catalog, according to some rule set.
+ *
+ * @public
+ */
+declare type CatalogRulesEnforcer = {
+    isAllowed(entity: Entity, location: LocationSpec): boolean;
+};
+/**
+ * Implements the default catalog rule set, consuming the config keys
+ * `catalog.rules` and `catalog.locations.[].rules`.
+ *
+ * @public
+ */
+declare class DefaultCatalogRulesEnforcer implements CatalogRulesEnforcer {
+    private readonly rules;
+    /**
+     * Default rules used by the catalog.
+     *
+     * Denies any location from specifying user or group entities.
+     */
+    static readonly defaultRules: CatalogRule[];
+    /**
+     * Loads catalog rules from config.
+     *
+     * This reads `catalog.rules` and defaults to the default rules if no value is present.
+     * The value of the config should be a list of config objects, each with a single `allow`
+     * field which in turn is a list of entity kinds to allow.
+     *
+     * If there is no matching rule to allow an ingested entity, it will be rejected by the catalog.
+     *
+     * It also reads in rules from `catalog.locations`, where each location can have a list
+     * of rules for that specific location, specified in a `rules` field.
+     *
+     * For example:
+     *
+     * ```yaml
+     * catalog:
+     *   rules:
+     *   - allow: [Component, API]
+     *
+     *   locations:
+     *   - type: url
+     *     target: https://github.com/org/repo/blob/master/users.yaml
+     *     rules:
+     *       - allow: [User, Group]
+     *   - type: url
+     *     target: https://github.com/org/repo/blob/master/systems.yaml
+     *     rules:
+     *       - allow: [System]
+     * ```
+     */
+    static fromConfig(config: Config): DefaultCatalogRulesEnforcer;
+    constructor(rules: CatalogRule[]);
+    /**
+     * Checks wether a specific entity/location combination is allowed
+     * according to the configured rules.
+     */
+    isAllowed(entity: Entity, location: LocationSpec): boolean;
+    private matchLocation;
+    private matchEntity;
+}
+
+declare type CatalogProcessor = {
+    /**
+     * A unique identifier for the Catalog Processor.
+     * It's strongly recommended to implement getProcessorName as this method will be required in the future.
+     */
+    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>;
+    /**
+     * Handles an emitted error.
+     *
+     * @param error - The error
+     * @param location - The location where the error occurred
+     * @param emit - A sink for items resulting from this handling
+     * @returns Nothing
+     */
+    handleError?(error: Error, location: LocationSpec, emit: CatalogProcessorEmit): Promise<void>;
+};
+/**
+ * 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.
+ */
+declare type CatalogProcessorParser = (options: {
+    data: Buffer;
+    location: LocationSpec;
+}) => AsyncIterable<CatalogProcessorResult>;
+/**
+ * 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
+ */
+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>;
+}
+declare type CatalogProcessorEmit = (generated: CatalogProcessorResult) => void;
+declare type CatalogProcessorLocationResult = {
+    type: 'location';
+    location: LocationSpec;
+    optional: boolean;
+};
+declare type CatalogProcessorEntityResult = {
+    type: 'entity';
+    entity: Entity;
+    location: LocationSpec;
+};
+declare type CatalogProcessorRelationResult = {
+    type: 'relation';
+    relation: EntityRelationSpec;
+    entityRef?: string;
+};
+declare type CatalogProcessorErrorResult = {
+    type: 'error';
+    error: Error;
+    location: LocationSpec;
+};
+declare type CatalogProcessorResult = CatalogProcessorLocationResult | CatalogProcessorEntityResult | CatalogProcessorRelationResult | CatalogProcessorErrorResult;
+
+declare function notFoundError(atLocation: LocationSpec, message: string): CatalogProcessorResult;
+declare function inputError(atLocation: LocationSpec, message: string): CatalogProcessorResult;
+declare function generalError(atLocation: LocationSpec, message: string): CatalogProcessorResult;
+declare function location(newLocation: LocationSpec, optional: boolean): CatalogProcessorResult;
+declare function entity(atLocation: LocationSpec, newEntity: Entity): CatalogProcessorResult;
+declare function relation(spec: EntityRelationSpec): CatalogProcessorResult;
+
+declare const results_d_notFoundError: typeof notFoundError;
+declare const results_d_inputError: typeof inputError;
+declare const results_d_generalError: typeof generalError;
+declare const results_d_location: typeof location;
+declare const results_d_entity: typeof entity;
+declare const results_d_relation: typeof relation;
+declare namespace results_d {
+  export {
+    results_d_notFoundError as notFoundError,
+    results_d_inputError as inputError,
+    results_d_generalError as generalError,
+    results_d_location as location,
+    results_d_entity as entity,
+    results_d_relation as relation,
+  };
+}
+
+declare type Options$1 = {
+    integrations: ScmIntegrationRegistry;
+};
+declare class AnnotateLocationEntityProcessor implements CatalogProcessor {
+    private readonly options;
+    constructor(options: Options$1);
+    preProcessEntity(entity: Entity, location: LocationSpec, _: CatalogProcessorEmit, originLocation: LocationSpec): Promise<Entity>;
+}
+
+declare class AnnotateScmSlugEntityProcessor implements CatalogProcessor {
+    private readonly opts;
+    constructor(opts: {
+        scmIntegrationRegistry: ScmIntegrationRegistry;
+    });
+    static fromConfig(config: Config): AnnotateScmSlugEntityProcessor;
+    preProcessEntity(entity: Entity, location: LocationSpec): Promise<Entity>;
+}
+
+/**
+ * The configuration parameters for a single AWS Organization Processor
+ */
+declare type AwsOrganizationProviderConfig = {
+    /**
+     * The role to assume for the processor.
+     */
+    roleArn?: string;
+};
+
+/**
+ * A processor for ingesting AWS Accounts from AWS Organizations.
+ *
+ * If custom authentication is needed, it can be achieved by configuring the global AWS.credentials object.
+ */
+declare class AwsOrganizationCloudAccountProcessor implements CatalogProcessor {
+    logger: Logger;
+    organizations: Organizations;
+    provider: AwsOrganizationProviderConfig;
+    static fromConfig(config: Config, options: {
+        logger: Logger;
+    }): AwsOrganizationCloudAccountProcessor;
+    private static buildCredentials;
+    constructor(options: {
+        provider: AwsOrganizationProviderConfig;
+        logger: Logger;
+    });
+    normalizeName(name: string): string;
+    extractInformationFromArn(arn: string): {
+        accountId: string;
+        organizationId: string;
+    };
+    getAwsAccounts(): Promise<Account[]>;
+    mapAccountToComponent(account: Account): ResourceEntityV1alpha1;
+    readLocation(location: LocationSpec, _optional: boolean, emit: CatalogProcessorEmit): Promise<boolean>;
+}
+
+declare class AwsS3DiscoveryProcessor implements CatalogProcessor {
+    private readonly reader;
+    constructor(reader: UrlReader);
+    readLocation(location: LocationSpec, optional: boolean, emit: CatalogProcessorEmit, parser: CatalogProcessorParser): Promise<boolean>;
+    private doRead;
+}
+
+declare type BitbucketRepositoryParser = (options: {
+    integration: BitbucketIntegration;
+    target: string;
+    logger: Logger;
+}) => AsyncIterable<CatalogProcessorResult>;
+
+declare class BitbucketDiscoveryProcessor implements CatalogProcessor {
+    private readonly integrations;
+    private readonly parser;
+    private readonly logger;
+    static fromConfig(config: Config, options: {
+        parser?: BitbucketRepositoryParser;
+        logger: Logger;
+    }): BitbucketDiscoveryProcessor;
+    constructor(options: {
+        integrations: ScmIntegrationRegistry;
+        parser?: BitbucketRepositoryParser;
+        logger: Logger;
+    });
+    readLocation(location: LocationSpec, _optional: boolean, emit: CatalogProcessorEmit): Promise<boolean>;
+    private processCloudRepositories;
+    private processOrganisationRepositories;
+}
+
+declare class BuiltinKindsEntityProcessor implements CatalogProcessor {
+    private readonly validators;
+    validateEntityKind(entity: Entity): Promise<boolean>;
+    postProcessEntity(entity: Entity, _location: LocationSpec, emit: CatalogProcessorEmit): Promise<Entity>;
+}
+
+declare class CodeOwnersProcessor implements CatalogProcessor {
+    private readonly integrations;
+    private readonly logger;
+    private readonly reader;
+    static fromConfig(config: Config, options: {
+        logger: Logger;
+        reader: UrlReader;
+    }): CodeOwnersProcessor;
+    constructor(options: {
+        integrations: ScmIntegrationRegistry;
+        logger: Logger;
+        reader: UrlReader;
+    });
+    preProcessEntity(entity: Entity, location: LocationSpec): Promise<Entity>;
+}
+
+declare class FileReaderProcessor implements CatalogProcessor {
+    readLocation(location: LocationSpec, optional: boolean, emit: CatalogProcessorEmit, parser: CatalogProcessorParser): Promise<boolean>;
+}
+
+/**
+ * Extracts repositories out of a GitHub org.
+ *
+ * The following will create locations for all projects which have a catalog-info.yaml
+ * on the default branch. The first is shorthand for the second.
+ *
+ *    target: "https://github.com/backstage"
+ *    or
+ *    target: https://github.com/backstage/*\/blob/-/catalog-info.yaml
+ *
+ * You may also explicitly specify the source branch:
+ *
+ *    target: https://github.com/backstage/*\/blob/main/catalog-info.yaml
+ **/
+declare class GithubDiscoveryProcessor implements CatalogProcessor {
+    private readonly integrations;
+    private readonly logger;
+    private readonly githubCredentialsProvider;
+    static fromConfig(config: Config, options: {
+        logger: Logger;
+        githubCredentialsProvider?: GithubCredentialsProvider;
+    }): GithubDiscoveryProcessor;
+    constructor(options: {
+        integrations: ScmIntegrationRegistry;
+        logger: Logger;
+        githubCredentialsProvider?: GithubCredentialsProvider;
+    });
+    readLocation(location: LocationSpec, _optional: boolean, emit: CatalogProcessorEmit): Promise<boolean>;
+}
+
+/**
+ * Extracts repositories out of an Azure DevOps org.
+ *
+ * The following will create locations for all projects which have a catalog-info.yaml
+ * on the default branch. The first is shorthand for the second.
+ *
+ *    target: "https://dev.azure.com/org/project"
+ *    or
+ *    target: https://dev.azure.com/org/project?path=/catalog-info.yaml
+ *
+ * You may also explicitly specify a single repo:
+ *
+ *    target: https://dev.azure.com/org/project/_git/repo
+ **/
+declare class AzureDevOpsDiscoveryProcessor implements CatalogProcessor {
+    private readonly integrations;
+    private readonly logger;
+    static fromConfig(config: Config, options: {
+        logger: Logger;
+    }): AzureDevOpsDiscoveryProcessor;
+    constructor(options: {
+        integrations: ScmIntegrationRegistry;
+        logger: Logger;
+    });
+    readLocation(location: LocationSpec, _optional: boolean, emit: CatalogProcessorEmit): Promise<boolean>;
+}
+
+/**
+ * Extracts teams and users out of a GitHub org.
+ */
+declare class GithubOrgReaderProcessor implements CatalogProcessor {
+    private readonly integrations;
+    private readonly logger;
+    private readonly githubCredentialsProvider;
+    static fromConfig(config: Config, options: {
+        logger: Logger;
+        githubCredentialsProvider?: GithubCredentialsProvider;
+    }): GithubOrgReaderProcessor;
+    constructor(options: {
+        integrations: ScmIntegrationRegistry;
+        logger: Logger;
+        githubCredentialsProvider?: GithubCredentialsProvider;
+    });
+    readLocation(location: LocationSpec, _optional: boolean, emit: CatalogProcessorEmit): Promise<boolean>;
+    private createClient;
+}
+
+/**
+ * The configuration parameters for a multi-org GitHub processor.
+ */
+declare type GithubMultiOrgConfig = Array<{
+    /**
+     * The name of the GitHub org to process.
+     */
+    name: string;
+    /**
+     * The namespace of the group created for this org.
+     */
+    groupNamespace: string;
+    /**
+     * The namespace of the users created for this org. If not specified defaults to undefined.
+     */
+    userNamespace: string | undefined;
+}>;
+
+/**
+ * @alpha
+ * Extracts teams and users out of a multiple GitHub orgs namespaced per org.
+ *
+ * Be aware that this processor may not be compatible with future org structures in the catalog.
+ */
+declare class GithubMultiOrgReaderProcessor implements CatalogProcessor {
+    private readonly integrations;
+    private readonly orgs;
+    private readonly logger;
+    private readonly githubCredentialsProvider;
+    static fromConfig(config: Config, options: {
+        logger: Logger;
+        githubCredentialsProvider?: GithubCredentialsProvider;
+    }): GithubMultiOrgReaderProcessor;
+    constructor(options: {
+        integrations: ScmIntegrationRegistry;
+        logger: Logger;
+        orgs: GithubMultiOrgConfig;
+        githubCredentialsProvider?: GithubCredentialsProvider;
+    });
+    readLocation(location: LocationSpec, _optional: boolean, emit: CatalogProcessorEmit): Promise<boolean>;
+    private getAllOrgs;
+}
+
+/**
+ * Extracts repositories out of an GitLab instance.
+ */
+declare class GitLabDiscoveryProcessor implements CatalogProcessor {
+    private readonly integrations;
+    private readonly logger;
+    private readonly cache;
+    static fromConfig(config: Config, options: {
+        logger: Logger;
+    }): GitLabDiscoveryProcessor;
+    private constructor();
+    readLocation(location: LocationSpec, _optional: boolean, emit: CatalogProcessorEmit): Promise<boolean>;
+    updateLastActivity(): Promise<string | undefined>;
+}
+
+declare type LocationEntityProcessorOptions = {
+    integrations: ScmIntegrationRegistry;
+};
+declare class LocationEntityProcessor implements CatalogProcessor {
+    private readonly options;
+    constructor(options: LocationEntityProcessorOptions);
+    postProcessEntity(entity: Entity, location: LocationSpec, emit: CatalogProcessorEmit): Promise<Entity>;
+}
+
+declare type PlaceholderResolverRead = (url: string) => Promise<Buffer>;
+declare type PlaceholderResolverResolveUrl = (url: string, base: string) => string;
+declare type PlaceholderResolverParams = {
+    key: string;
+    value: JsonValue;
+    baseUrl: string;
+    read: PlaceholderResolverRead;
+    resolveUrl: PlaceholderResolverResolveUrl;
+};
+declare type PlaceholderResolver = (params: PlaceholderResolverParams) => Promise<JsonValue>;
+declare type PlaceholderProcessorOptions = {
+    resolvers: Record<string, PlaceholderResolver>;
+    reader: UrlReader;
+    integrations: ScmIntegrationRegistry;
+};
+/**
+ * Traverses raw entity JSON looking for occurrences of $-prefixed placeholders
+ * that it then fills in with actual data.
+ */
+declare class PlaceholderProcessor implements CatalogProcessor {
+    private readonly options;
+    constructor(options: PlaceholderProcessorOptions);
+    preProcessEntity(entity: Entity, location: LocationSpec): Promise<Entity>;
+}
+
+declare class StaticLocationProcessor implements StaticLocationProcessor {
+    private readonly staticLocations;
+    static fromConfig(config: Config): StaticLocationProcessor;
+    constructor(staticLocations: LocationSpec[]);
+    readLocation(location: LocationSpec, _optional: boolean, emit: CatalogProcessorEmit): Promise<boolean>;
+}
+
+declare type Options = {
+    reader: UrlReader;
+    logger: Logger;
+};
+declare class UrlReaderProcessor implements CatalogProcessor {
+    private readonly options;
+    constructor(options: Options);
+    getProcessorName(): string;
+    readLocation(location: LocationSpec, optional: boolean, emit: CatalogProcessorEmit, parser: CatalogProcessorParser, cache: CatalogProcessorCache): Promise<boolean>;
+    private doRead;
+}
+
+declare function parseEntityYaml(data: Buffer, location: LocationSpec): Iterable<CatalogProcessorResult>;
+
+declare type EntityProcessingRequest = {
+    entity: Entity;
+    state?: JsonObject;
+};
+declare type EntityProcessingResult = {
+    ok: true;
+    state: JsonObject;
+    completedEntity: Entity;
+    deferredEntities: DeferredEntity[];
+    relations: EntityRelationSpec[];
+    errors: Error[];
+} | {
+    ok: false;
+    errors: Error[];
+};
+interface CatalogProcessingOrchestrator {
+    process(request: EntityProcessingRequest): Promise<EntityProcessingResult>;
+}
+declare type DeferredEntity = {
+    entity: Entity;
+    locationKey?: string;
+};
+interface CatalogProcessingEngine {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+
+declare class DefaultCatalogProcessingOrchestrator implements CatalogProcessingOrchestrator {
+    private readonly options;
+    constructor(options: {
+        processors: CatalogProcessor[];
+        integrations: ScmIntegrationRegistry;
+        logger: Logger;
+        parser: CatalogProcessorParser;
+        policy: EntityPolicy;
+        rulesEnforcer: CatalogRulesEnforcer;
+    });
+    process(request: EntityProcessingRequest): Promise<EntityProcessingResult>;
+    private processSingleEntity;
+    private runPreProcessStep;
+    /**
+     * Enforce entity policies making sure that entities conform to a general schema
+     */
+    private runPolicyStep;
+    /**
+     * Validate the given entity
+     */
+    private runValidateStep;
+    /**
+     * Backwards compatible processing of location entities
+     */
+    private runSpecialLocationStep;
+    /**
+     * Main processing step of the entity
+     */
+    private runPostProcessStep;
+}
+
+/**
+ * Function that returns the catalog refresh interval in seconds.
+ */
+declare type RefreshIntervalFunction = () => number;
+/**
+ * Creates a function that returns a random refresh interval between minSeconds and maxSeconds.
+ * @returns A {@link RefreshIntervalFunction} that provides the next refresh interval
+ */
+declare function createRandomRefreshInterval(options: {
+    minSeconds: number;
+    maxSeconds: number;
+}): RefreshIntervalFunction;
+
+declare type EntityProviderMutation = {
+    type: 'full';
+    entities: DeferredEntity[];
+} | {
+    type: 'delta';
+    added: DeferredEntity[];
+    removed: DeferredEntity[];
+};
+interface EntityProviderConnection {
+    applyMutation(mutation: EntityProviderMutation): Promise<void>;
+}
+interface EntityProvider {
+    getProviderName(): string;
+    connect(connection: EntityProviderConnection): Promise<void>;
+}
+
+declare class GitHubOrgEntityProvider implements EntityProvider {
+    private options;
+    private connection?;
+    private githubCredentialsProvider;
+    static fromConfig(config: Config, options: {
+        id: string;
+        orgUrl: string;
+        logger: Logger;
+        githubCredentialsProvider?: GithubCredentialsProvider;
+    }): GitHubOrgEntityProvider;
+    constructor(options: {
+        id: string;
+        orgUrl: string;
+        gitHubConfig: GitHubIntegrationConfig;
+        logger: Logger;
+        githubCredentialsProvider?: GithubCredentialsProvider;
+    });
+    getProviderName(): string;
+    connect(connection: EntityProviderConnection): Promise<void>;
+    read(): Promise<void>;
+}
+
+/**
+ * Makes all keys of an entire hierarchy optional.
+ */
+declare type RecursivePartial<T> = {
+    [P in keyof T]?: T[P] extends (infer U)[] ? RecursivePartial<U>[] : T[P] extends object ? RecursivePartial<T[P]> : T[P];
+};
+
+declare type LocationAnalyzer = {
+    /**
+     * Generates an entity configuration for given git repository. It's used for
+     * importing new component to the backstage app.
+     *
+     * @param location - Git repository to analyze and generate config for.
+     */
+    analyzeLocation(location: AnalyzeLocationRequest): Promise<AnalyzeLocationResponse>;
+};
+declare type AnalyzeLocationRequest = {
+    location: LocationSpec;
+};
+declare type AnalyzeLocationResponse = {
+    existingEntityFiles: AnalyzeLocationExistingEntity[];
+    generateEntities: AnalyzeLocationGenerateEntity[];
+};
+declare type AnalyzeLocationExistingEntity = {
+    location: LocationSpec;
+    isRegistered: boolean;
+    entity: Entity;
+};
+declare type AnalyzeLocationGenerateEntity = {
+    entity: RecursivePartial<Entity>;
+    fields: AnalyzeLocationEntityField[];
+};
+declare type AnalyzeLocationEntityField = {
+    field: string;
+    state: 'analysisSuggestedValue' | 'analysisSuggestedNoValue' | 'needsUserInput';
+    value: string | null;
+    description: string;
+};
+
+interface CatalogEntityDocument extends IndexableDocument {
+    componentType: string;
+    namespace: string;
+    kind: string;
+    lifecycle: string;
+    owner: string;
+}
+declare class DefaultCatalogCollator implements DocumentCollator {
+    protected discovery: PluginEndpointDiscovery;
+    protected locationTemplate: string;
+    protected filter?: GetEntitiesRequest['filter'];
+    protected readonly catalogClient: CatalogApi;
+    readonly type: string;
+    readonly visibilityPermission: _backstage_plugin_permission_common.Permission;
+    protected tokenManager: TokenManager;
+    static fromConfig(_config: Config, options: {
+        discovery: PluginEndpointDiscovery;
+        tokenManager: TokenManager;
+        filter?: GetEntitiesRequest['filter'];
+    }): DefaultCatalogCollator;
+    constructor(options: {
+        discovery: PluginEndpointDiscovery;
+        tokenManager: TokenManager;
+        locationTemplate?: string;
+        filter?: GetEntitiesRequest['filter'];
+        catalogClient?: CatalogApi;
+    });
+    protected applyArgsToFormat(format: string, args: Record<string, string>): string;
+    private isUserEntity;
+    private getDocumentText;
+    execute(): Promise<CatalogEntityDocument[]>;
+}
+
+/**
+ * Runs a function repeatedly, with a fixed wait between invocations.
+ *
+ * Supports async functions, and silently ignores exceptions and rejections.
+ *
+ * @param fn - The function to run. May return a Promise.
+ * @param delayMs - The delay between a completed function invocation and the
+ *                next.
+ * @returns A function that, when called, stops the invocation loop.
+ */
+declare function runPeriodically(fn: () => any, delayMs: number): () => void;
+
+/**
+ * Returns a string with the elapsed time since the start of an operation,
+ * with some human friendly precision, e.g. "133ms" or "14.5s".
+ *
+ * @param startTimestamp - The timestamp (from process.hrtime()) at the start ot
+ *                       the operation
+ */
+declare function durationText(startTimestamp: [number, number]): string;
+
+interface LocationService {
+    createLocation(spec: LocationSpec, dryRun: boolean, options?: {
+        authorizationToken?: string;
+    }): Promise<{
+        location: Location;
+        entities: Entity[];
+        exists?: boolean;
+    }>;
+    listLocations(options?: {
+        authorizationToken?: string;
+    }): Promise<Location[]>;
+    getLocation(id: string, options?: {
+        authorizationToken?: string;
+    }): Promise<Location>;
+    deleteLocation(id: string, options?: {
+        authorizationToken?: string;
+    }): Promise<void>;
+}
+/**
+ * Options for requesting a refresh of entities in the catalog.
+ *
+ * @public
+ */
+declare type RefreshOptions = {
+    /** The reference to a single entity that should be refreshed */
+    entityRef: string;
+    authorizationToken?: string;
+};
+/**
+ * A service that manages refreshes of entities in the catalog.
+ *
+ * @public
+ */
+interface RefreshService {
+    /**
+     * Request a refresh of entities in the catalog.
+     */
+    refresh(options: RefreshOptions): Promise<void>;
+}
+interface LocationStore {
+    createLocation(spec: LocationSpec): Promise<Location>;
+    listLocations(): Promise<Location[]>;
+    getLocation(id: string): Promise<Location>;
+    deleteLocation(id: string): Promise<void>;
+}
+
+/**
+ * Options used by {@link createRouter}.
+ *
+ * @public
+ */
+interface RouterOptions {
+    entitiesCatalog?: EntitiesCatalog;
+    locationAnalyzer?: LocationAnalyzer;
+    locationService: LocationService;
+    refreshService?: RefreshService;
+    logger: Logger;
+    config: Config;
+    permissionIntegrationRouter?: express.Router;
+}
+/**
+ * Creates a catalog router.
+ *
+ * @public
+ */
+declare function createRouter(options: RouterOptions): Promise<express.Router>;
+
+declare type CatalogEnvironment = {
+    logger: Logger;
+    database: PluginDatabaseManager;
+    config: Config;
+    reader: UrlReader;
+    permissions: PermissionAuthorizer;
+};
+/**
+ * A builder that helps wire up all of the component parts of the catalog.
+ *
+ * The touch points where you can replace or extend behavior are as follows:
+ *
+ * - Entity policies can be added or replaced. These are automatically run
+ *   after the processors' pre-processing steps. All policies are given the
+ *   chance to inspect the entity, and all of them have to pass in order for
+ *   the entity to be considered valid from an overall point of view.
+ * - Placeholder resolvers can be replaced or added. These run on the raw
+ *   structured data between the parsing and pre-processing steps, to replace
+ *   dollar-prefixed entries with their actual values (like $file).
+ * - Field format validators can be replaced. These check the format of
+ *   individual core fields such as metadata.name, to ensure that they adhere
+ *   to certain rules.
+ * - Processors can be added or replaced. These implement the functionality of
+ *   reading, parsing, validating, and processing the entity data before it is
+ *   persisted in the catalog.
+ *
+ * @public
+ */
+declare class CatalogBuilder {
+    private readonly env;
+    private entityPolicies;
+    private entityPoliciesReplace;
+    private placeholderResolvers;
+    private fieldFormatValidators;
+    private entityProviders;
+    private processors;
+    private processorsReplace;
+    private parser;
+    private refreshInterval;
+    private locationAnalyzer;
+    private permissionRules;
+    /**
+     * Creates a catalog builder.
+     */
+    static create(env: CatalogEnvironment): CatalogBuilder;
+    private constructor();
+    /**
+     * Adds policies that are used to validate entities between the pre-
+     * processing and post-processing stages. All such policies must pass for the
+     * entity to be considered valid.
+     *
+     * If what you want to do is to replace the rules for what format is allowed
+     * in various core entity fields (such as metadata.name), you may want to use
+     * {@link CatalogBuilder#setFieldFormatValidators} instead.
+     *
+     * @param policies - One or more policies
+     */
+    addEntityPolicy(...policies: EntityPolicy[]): CatalogBuilder;
+    /**
+     * Refresh interval determines how often entities should be refreshed.
+     * Seconds provided will be multiplied by 1.5
+     * The default refresh duration is 100-150 seconds.
+     * setting this too low will potentially deplete request quotas to upstream services.
+     */
+    setRefreshIntervalSeconds(seconds: number): CatalogBuilder;
+    /**
+     * Overwrites the default refresh interval function used to spread
+     * entity updates in the catalog.
+     */
+    setRefreshInterval(refreshInterval: RefreshIntervalFunction): CatalogBuilder;
+    /**
+     * Overwrites the default location analyzer.
+     */
+    setLocationAnalyzer(locationAnalyzer: LocationAnalyzer): CatalogBuilder;
+    /**
+     * Sets what policies to use for validation of entities between the pre-
+     * processing and post-processing stages. All such policies must pass for the
+     * entity to be considered valid.
+     *
+     * If what you want to do is to replace the rules for what format is allowed
+     * in various core entity fields (such as metadata.name), you may want to use
+     * {@link CatalogBuilder#setFieldFormatValidators} instead.
+     *
+     * This function replaces the default set of policies; use with care.
+     *
+     * @param policies - One or more policies
+     */
+    replaceEntityPolicies(policies: EntityPolicy[]): CatalogBuilder;
+    /**
+     * Adds, or overwrites, a handler for placeholders (e.g. $file) in entity
+     * definition files.
+     *
+     * @param key - The key that identifies the placeholder, e.g. "file"
+     * @param resolver - The resolver that gets values for this placeholder
+     */
+    setPlaceholderResolver(key: string, resolver: PlaceholderResolver): CatalogBuilder;
+    /**
+     * Sets the validator function to use for one or more special fields of an
+     * entity. This is useful if the default rules for formatting of fields are
+     * not sufficient.
+     *
+     * This function has no effect if used together with
+     * {@link CatalogBuilder#replaceEntityPolicies}.
+     *
+     * @param validators - The (subset of) validators to set
+     */
+    setFieldFormatValidators(validators: Partial<Validators>): CatalogBuilder;
+    /**
+     * Adds or replaces entity providers. These are responsible for bootstrapping
+     * the list of entities out of original data sources. For example, there is
+     * one entity source for the config locations, and one for the database
+     * stored locations. If you ingest entities out of a third party system, you
+     * may want to implement that in terms of an entity provider as well.
+     *
+     * @param providers - One or more entity providers
+     */
+    addEntityProvider(...providers: EntityProvider[]): CatalogBuilder;
+    /**
+     * Adds entity processors. These are responsible for reading, parsing, and
+     * processing entities before they are persisted in the catalog.
+     *
+     * @param processors - One or more processors
+     */
+    addProcessor(...processors: CatalogProcessor[]): CatalogBuilder;
+    /**
+     * Sets what entity processors to use. These are responsible for reading,
+     * parsing, and processing entities before they are persisted in the catalog.
+     *
+     * This function replaces the default set of processors, consider using with
+     * {@link CatalogBuilder#getDefaultProcessors}; use with care.
+     *
+     * @param processors - One or more processors
+     */
+    replaceProcessors(processors: CatalogProcessor[]): CatalogBuilder;
+    /**
+     * Returns the default list of entity processors. These are responsible for reading,
+     * parsing, and processing entities before they are persisted in the catalog. Changing
+     * the order of processing can give more control to custom processors.
+     *
+     * Consider using with {@link CatalogBuilder#replaceProcessors}
+     *
+     */
+    getDefaultProcessors(): CatalogProcessor[];
+    /**
+     * Sets up the catalog to use a custom parser for entity data.
+     *
+     * This is the function that gets called immediately after some raw entity
+     * specification data has been read from a remote source, and needs to be
+     * parsed and emitted as structured data.
+     *
+     * @param parser - The custom parser
+     */
+    setEntityDataParser(parser: CatalogProcessorParser): CatalogBuilder;
+    /**
+     * Adds additional permission rules. Permission rules are used to evaluate
+     * catalog resources against queries. See
+     * {@link @backstage/plugin-permission-node#PermissionRule}.
+     *
+     * @param permissionRules - Additional permission rules
+     */
+    addPermissionRules(...permissionRules: PermissionRule<Entity, EntitiesSearchFilter, unknown[]>[]): void;
+    /**
+     * Wires up and returns all of the component parts of the catalog
+     */
+    build(): Promise<{
+        entitiesCatalog: EntitiesCatalog;
+        locationAnalyzer: LocationAnalyzer;
+        processingEngine: CatalogProcessingEngine;
+        locationService: LocationService;
+        router: Router;
+    }>;
+    private buildEntityPolicy;
+    private buildProcessors;
+    private checkDeprecatedReaderProcessors;
+}
+
+/**
+ * These conditions are used when creating conditional decisions that are returned
+ * by authorization policies.
+ * @public
+ */
+declare const catalogConditions: _backstage_plugin_permission_node.Conditions<{
+    hasAnnotation: _backstage_plugin_permission_node.PermissionRule<_backstage_catalog_model.Entity, EntitiesSearchFilter, [annotation: string]>;
+    hasLabel: _backstage_plugin_permission_node.PermissionRule<_backstage_catalog_model.Entity, EntitiesSearchFilter, [label: string]>;
+    hasMetadata: _backstage_plugin_permission_node.PermissionRule<_backstage_catalog_model.Entity, EntitiesSearchFilter, [key: string, value?: string | undefined]>;
+    hasSpec: _backstage_plugin_permission_node.PermissionRule<_backstage_catalog_model.Entity, EntitiesSearchFilter, [key: string, value?: string | undefined]>;
+    isEntityKind: _backstage_plugin_permission_node.PermissionRule<_backstage_catalog_model.Entity, EntitiesSearchFilter, [kinds: string[]]>;
+    isEntityOwner: _backstage_plugin_permission_node.PermissionRule<_backstage_catalog_model.Entity, EntitiesSearchFilter, [claims: string[]]>;
+}>;
+/**
+ * `createCatalogPolicyDecision` can be used when authoring policies to create
+ * conditional decisions.
+ *
+ * ```
+ * // MyAuthorizationPolicy.ts
+ * ...
+ * import { createCatalogPolicyDecision } from '@backstage/plugin-catalog-backend';
+ *
+ * class MyAuthorizationPolicy implements PermissionPolicy {
+ *   async handle(request, user) {
+ *     ...
+ *
+ *     return createCatalogPolicyDecision({
+ *       anyOf: [...insert conditions here...],
+ *     });
+ *   }
+ * }
+ * ```
+ * @public
+ */
+declare const createCatalogPolicyDecision: (conditions: _backstage_plugin_permission_common.PermissionCriteria<_backstage_plugin_permission_common.PermissionCondition<unknown[]>>) => _backstage_plugin_permission_node.ConditionalPolicyDecision;
+
+/**
+ * Helper function for creating correctly-typed
+ * {@link @backstage/plugin-permission-node#PermissionRule}s for the
+ * catalog-backend.
+ *
+ * @public
+ */
+declare const createCatalogPermissionRule: <TParams extends unknown[]>(rule: _backstage_plugin_permission_node.PermissionRule<Entity, EntitiesSearchFilter, TParams>) => _backstage_plugin_permission_node.PermissionRule<Entity, EntitiesSearchFilter, TParams>;
+
+/**
+ * These permission rules can be used to conditionally filter catalog entities
+ * or describe a user's access to the entities.
+ * @public
+ */
+declare const permissionRules: {
+    hasAnnotation: _backstage_plugin_permission_node.PermissionRule<_backstage_catalog_model.Entity, EntitiesSearchFilter, [annotation: string]>;
+    hasLabel: _backstage_plugin_permission_node.PermissionRule<_backstage_catalog_model.Entity, EntitiesSearchFilter, [label: string]>;
+    hasMetadata: _backstage_plugin_permission_node.PermissionRule<_backstage_catalog_model.Entity, EntitiesSearchFilter, [key: string, value?: string | undefined]>;
+    hasSpec: _backstage_plugin_permission_node.PermissionRule<_backstage_catalog_model.Entity, EntitiesSearchFilter, [key: string, value?: string | undefined]>;
+    isEntityKind: _backstage_plugin_permission_node.PermissionRule<_backstage_catalog_model.Entity, EntitiesSearchFilter, [kinds: string[]]>;
+    isEntityOwner: _backstage_plugin_permission_node.PermissionRule<_backstage_catalog_model.Entity, EntitiesSearchFilter, [claims: string[]]>;
+};
+
+export { AnalyzeLocationEntityField, AnalyzeLocationExistingEntity, AnalyzeLocationGenerateEntity, AnalyzeLocationRequest, AnalyzeLocationResponse, AnnotateLocationEntityProcessor, AnnotateScmSlugEntityProcessor, AwsOrganizationCloudAccountProcessor, AwsOrganizationProviderConfig, AwsS3DiscoveryProcessor, AzureDevOpsDiscoveryProcessor, BitbucketDiscoveryProcessor, BitbucketRepositoryParser, BuiltinKindsEntityProcessor, CatalogBuilder, CatalogEntityDocument, CatalogEnvironment, CatalogProcessingEngine, CatalogProcessingOrchestrator, CatalogProcessor, CatalogProcessorCache, CatalogProcessorEmit, CatalogProcessorEntityResult, CatalogProcessorErrorResult, CatalogProcessorLocationResult, CatalogProcessorParser, CatalogProcessorRelationResult, CatalogProcessorResult, CatalogRule, CatalogRulesEnforcer, CodeOwnersProcessor, DefaultCatalogCollator, DefaultCatalogProcessingOrchestrator, DefaultCatalogRulesEnforcer, DeferredEntity, EntitiesCatalog, EntitiesRequest, EntitiesResponse, EntitiesSearchFilter, EntityAncestryResponse, EntityFilter, EntityPagination, EntityProcessingRequest, EntityProcessingResult, EntityProvider, EntityProviderConnection, EntityProviderMutation, FileReaderProcessor, GitHubOrgEntityProvider, GitLabDiscoveryProcessor, GithubDiscoveryProcessor, GithubMultiOrgReaderProcessor, GithubOrgReaderProcessor, LocationAnalyzer, LocationEntityProcessor, LocationEntityProcessorOptions, LocationService, LocationStore, PageInfo, PlaceholderProcessor, PlaceholderProcessorOptions, PlaceholderResolver, PlaceholderResolverParams, PlaceholderResolverRead, PlaceholderResolverResolveUrl, RecursivePartial, RefreshIntervalFunction, RefreshOptions, RefreshService, RouterOptions, StaticLocationProcessor, UrlReaderProcessor, catalogConditions, createCatalogPermissionRule, createCatalogPolicyDecision, createRandomRefreshInterval, createRouter, durationText, parseEntityYaml, permissionRules, results_d as results, runPeriodically };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@backstage/plugin-catalog-backend",
   "description": "The Backstage backend plugin that provides the Backstage catalog",
-  "version": "0.21.4",
+  "version": "0.21.5",
   "main": "dist/index.cjs.js",
   "types": "dist/index.d.ts",
   "license": "Apache-2.0",
@@ -33,18 +33,18 @@
     "clean": "backstage-cli package clean"
   },
   "dependencies": {
-    "@backstage/backend-common": "^0.10.8",
-    "@backstage/catalog-client": "^0.7.0",
-    "@backstage/catalog-model": "^0.10.0",
-    "@backstage/config": "^0.1.14",
-    "@backstage/errors": "^0.2.1",
-    "@backstage/integration": "^0.7.3",
-    "@backstage/plugin-catalog-common": "^0.1.3",
-    "@backstage/plugin-permission-common": "^0.5.0",
-    "@backstage/plugin-permission-node": "^0.5.0",
-    "@backstage/plugin-scaffolder-common": "^0.2.0",
-    "@backstage/search-common": "^0.2.3",
-    "@backstage/types": "^0.1.2",
+    "@backstage/backend-common": "^0.10.9",
+    "@backstage/catalog-client": "^0.7.1",
+    "@backstage/catalog-model": "^0.10.1",
+    "@backstage/config": "^0.1.15",
+    "@backstage/errors": "^0.2.2",
+    "@backstage/integration": "^0.7.4",
+    "@backstage/plugin-catalog-common": "^0.1.4",
+    "@backstage/plugin-permission-common": "^0.5.1",
+    "@backstage/plugin-permission-node": "^0.5.1",
+    "@backstage/plugin-scaffolder-common": "^0.2.1",
+    "@backstage/search-common": "^0.2.4",
+    "@backstage/types": "^0.1.3",
     "@octokit/graphql": "^4.5.8",
     "@types/express": "^4.17.6",
     "aws-sdk": "^2.840.0",
@@ -71,7 +71,7 @@
   "devDependencies": {
     "@backstage/backend-test-utils": "^0.1.18",
     "@backstage/cli": "^0.14.0",
-    "@backstage/plugin-permission-common": "^0.5.0",
+    "@backstage/plugin-permission-common": "^0.5.1",
     "@backstage/test-utils": "^0.2.5",
     "@types/core-js": "^2.5.4",
     "@types/git-url-parse": "^9.0.0",
@@ -91,5 +91,5 @@
     "config.d.ts"
   ],
   "configSchema": "config.d.ts",
-  "gitHead": "4805c3d13ce9bfc369e53c271b1b95e722b3b4dc"
+  "gitHead": "e244b348c473700e7d5e5fbcef38bd9f9fd1d0ba"
 }