From 6d994fd9dae0d1bba8648c82176715f566c1b6b9 Mon Sep 17 00:00:00 2001 From: Johan Haals Date: Mon, 21 Feb 2022 14:55:34 +0100 Subject: [PATCH] catalog-backend: Cleanup API report Signed-off-by: Johan Haals --- .changeset/late-dots-compare.md | 5 + plugins/catalog-backend/api-report.md | 178 ++---------------- plugins/catalog-backend/src/catalog/types.ts | 6 + .../AnnotateLocationEntityProcessor.ts | 11 +- .../AnnotateScmSlugEntityProcessor.ts | 1 + .../processors/AwsS3DiscoveryProcessor.ts | 1 + .../AzureDevOpsDiscoveryProcessor.ts | 2 + .../processors/BitbucketDiscoveryProcessor.ts | 1 + .../processors/BuiltinKindsEntityProcessor.ts | 1 + .../processors/CodeOwnersProcessor.ts | 1 + .../processors/FileReaderProcessor.ts | 1 + .../processors/GitLabDiscoveryProcessor.ts | 1 + .../processors/GithubDiscoveryProcessor.ts | 2 + .../processors/GithubOrgReaderProcessor.ts | 1 + .../processors/LocationEntityProcessor.ts | 2 + .../processors/PlaceholderProcessor.ts | 7 + .../processors/StaticLocationProcessor.ts | 1 + .../processors/UrlReaderProcessor.ts | 13 +- .../bitbucket/BitbucketRepositoryParser.ts | 1 + .../src/ingestion/processors/github/config.ts | 1 + .../src/ingestion/processors/index.ts | 1 + .../src/ingestion/processors/results.ts | 6 + .../src/ingestion/processors/types.ts | 10 + .../src/ingestion/processors/util/parse.ts | 1 + .../providers/GitHubOrgEntityProvider.ts | 2 +- .../catalog-backend/src/ingestion/types.ts | 51 ++--- .../DefaultCatalogProcessingOrchestrator.ts | 1 + .../catalog-backend/src/processing/refresh.ts | 2 + .../catalog-backend/src/processing/types.ts | 17 ++ .../catalog-backend/src/providers/types.ts | 21 +++ .../src/search/DefaultCatalogCollator.ts | 2 + .../src/service/CatalogBuilder.ts | 1 + plugins/catalog-backend/src/service/types.ts | 7 + .../src/util/RecursivePartial.ts | 1 + .../src/util/runPeriodically.ts | 1 + scripts/api-extractor.ts | 1 + 36 files changed, 171 insertions(+), 191 deletions(-) create mode 100644 .changeset/late-dots-compare.md diff --git a/.changeset/late-dots-compare.md b/.changeset/late-dots-compare.md new file mode 100644 index 0000000000..0625e70ef9 --- /dev/null +++ b/.changeset/late-dots-compare.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-catalog-backend': patch +--- + +Cleanup catalog-backend API report. diff --git a/plugins/catalog-backend/api-report.md b/plugins/catalog-backend/api-report.md index b2c2dca0bc..5dc0981fb0 100644 --- a/plugins/catalog-backend/api-report.md +++ b/plugins/catalog-backend/api-report.md @@ -37,8 +37,6 @@ import { TokenManager } from '@backstage/backend-common'; import { UrlReader } from '@backstage/backend-common'; import { Validators } from '@backstage/catalog-model'; -// Warning: (ae-missing-release-tag) "AnalyzeLocationEntityField" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type AnalyzeLocationEntityField = { field: string; @@ -50,44 +48,33 @@ export type AnalyzeLocationEntityField = { description: string; }; -// Warning: (ae-missing-release-tag) "AnalyzeLocationExistingEntity" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export type AnalyzeLocationExistingEntity = { location: LocationSpec; isRegistered: boolean; entity: Entity; }; -// Warning: (ae-missing-release-tag) "AnalyzeLocationGenerateEntity" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export type AnalyzeLocationGenerateEntity = { entity: RecursivePartial; fields: AnalyzeLocationEntityField[]; }; -// Warning: (ae-missing-release-tag) "AnalyzeLocationRequest" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type AnalyzeLocationRequest = { location: LocationSpec; }; -// Warning: (ae-missing-release-tag) "AnalyzeLocationResponse" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type AnalyzeLocationResponse = { existingEntityFiles: AnalyzeLocationExistingEntity[]; generateEntities: AnalyzeLocationGenerateEntity[]; }; -// Warning: (ae-missing-release-tag) "AnnotateLocationEntityProcessor" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export class AnnotateLocationEntityProcessor implements CatalogProcessor { - // Warning: (ae-forgotten-export) The symbol "Options" needs to be exported by the entry point index.d.ts - constructor(options: Options); + constructor(options: { integrations: ScmIntegrationRegistry }); // (undocumented) getProcessorName(): string; // (undocumented) @@ -99,8 +86,6 @@ export class AnnotateLocationEntityProcessor implements CatalogProcessor { ): Promise; } -// Warning: (ae-missing-release-tag) "AnnotateScmSlugEntityProcessor" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export class AnnotateScmSlugEntityProcessor implements CatalogProcessor { constructor(opts: { scmIntegrationRegistry: ScmIntegrationRegistry }); @@ -112,8 +97,6 @@ export class AnnotateScmSlugEntityProcessor implements CatalogProcessor { preProcessEntity(entity: Entity, location: LocationSpec): Promise; } -// Warning: (ae-missing-release-tag) "AwsS3DiscoveryProcessor" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export class AwsS3DiscoveryProcessor implements CatalogProcessor { constructor(reader: UrlReader); @@ -128,8 +111,6 @@ export class AwsS3DiscoveryProcessor implements CatalogProcessor { ): Promise; } -// Warning: (ae-missing-release-tag) "AzureDevOpsDiscoveryProcessor" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export class AzureDevOpsDiscoveryProcessor implements CatalogProcessor { constructor(options: { @@ -153,8 +134,6 @@ export class AzureDevOpsDiscoveryProcessor implements CatalogProcessor { ): Promise; } -// Warning: (ae-missing-release-tag) "BitbucketDiscoveryProcessor" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export class BitbucketDiscoveryProcessor implements CatalogProcessor { constructor(options: { @@ -180,8 +159,6 @@ export class BitbucketDiscoveryProcessor implements CatalogProcessor { ): Promise; } -// Warning: (ae-missing-release-tag) "BitbucketRepositoryParser" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type BitbucketRepositoryParser = (options: { integration: BitbucketIntegration; @@ -189,8 +166,6 @@ export type BitbucketRepositoryParser = (options: { logger: Logger_2; }) => AsyncIterable; -// Warning: (ae-missing-release-tag) "BuiltinKindsEntityProcessor" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export class BuiltinKindsEntityProcessor implements CatalogProcessor { // (undocumented) @@ -265,8 +240,6 @@ export const catalogConditions: Conditions<{ >; }>; -// Warning: (ae-missing-release-tag) "CatalogEntityDocument" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export interface CatalogEntityDocument extends IndexableDocument { // (undocumented) @@ -281,8 +254,6 @@ export interface CatalogEntityDocument extends IndexableDocument { owner: string; } -// Warning: (ae-missing-release-tag) "CatalogEnvironment" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type CatalogEnvironment = { logger: Logger_2; @@ -292,8 +263,6 @@ export type CatalogEnvironment = { permissions: PermissionAuthorizer; }; -// Warning: (ae-missing-release-tag) "CatalogProcessingEngine" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export interface CatalogProcessingEngine { // (undocumented) @@ -302,16 +271,12 @@ export interface CatalogProcessingEngine { stop(): Promise; } -// Warning: (ae-missing-release-tag) "CatalogProcessingOrchestrator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export interface CatalogProcessingOrchestrator { // (undocumented) process(request: EntityProcessingRequest): Promise; } -// Warning: (ae-missing-release-tag) "CatalogProcessor" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type CatalogProcessor = { getProcessorName(): string; @@ -349,13 +314,9 @@ export interface CatalogProcessorCache { set(key: string, value: ItemType): Promise; } -// Warning: (ae-missing-release-tag) "CatalogProcessorEmit" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type CatalogProcessorEmit = (generated: CatalogProcessorResult) => void; -// Warning: (ae-missing-release-tag) "CatalogProcessorEntityResult" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type CatalogProcessorEntityResult = { type: 'entity'; @@ -363,8 +324,6 @@ export type CatalogProcessorEntityResult = { location: LocationSpec; }; -// Warning: (ae-missing-release-tag) "CatalogProcessorErrorResult" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type CatalogProcessorErrorResult = { type: 'error'; @@ -372,8 +331,6 @@ export type CatalogProcessorErrorResult = { location: LocationSpec; }; -// Warning: (ae-missing-release-tag) "CatalogProcessorLocationResult" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type CatalogProcessorLocationResult = { type: 'location'; @@ -381,16 +338,12 @@ export type CatalogProcessorLocationResult = { optional?: boolean; }; -// Warning: (ae-missing-release-tag) "CatalogProcessorParser" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export type CatalogProcessorParser = (options: { data: Buffer; location: LocationSpec; }) => AsyncIterable; -// Warning: (ae-missing-release-tag) "CatalogProcessorRelationResult" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type CatalogProcessorRelationResult = { type: 'relation'; @@ -398,8 +351,6 @@ export type CatalogProcessorRelationResult = { entityRef?: string; }; -// Warning: (ae-missing-release-tag) "CatalogProcessorResult" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type CatalogProcessorResult = | CatalogProcessorLocationResult @@ -423,8 +374,6 @@ export type CatalogRulesEnforcer = { isAllowed(entity: Entity, location: LocationSpec): boolean; }; -// Warning: (ae-missing-release-tag) "CodeOwnersProcessor" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export class CodeOwnersProcessor implements CatalogProcessor { constructor(options: { @@ -456,8 +405,6 @@ export const createCatalogPolicyDecision: ( conditions: PermissionCriteria>, ) => ConditionalPolicyDecision; -// Warning: (ae-missing-release-tag) "createRandomRefreshInterval" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export function createRandomRefreshInterval(options: { minSeconds: number; @@ -467,8 +414,6 @@ export function createRandomRefreshInterval(options: { // @public export function createRouter(options: RouterOptions): Promise; -// Warning: (ae-missing-release-tag) "DefaultCatalogCollator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export class DefaultCatalogCollator implements DocumentCollator { constructor(options: { @@ -510,8 +455,6 @@ export class DefaultCatalogCollator implements DocumentCollator { readonly visibilityPermission: Permission; } -// Warning: (ae-missing-release-tag) "DefaultCatalogProcessingOrchestrator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export class DefaultCatalogProcessingOrchestrator implements CatalogProcessingOrchestrator @@ -536,9 +479,7 @@ export class DefaultCatalogRulesEnforcer implements CatalogRulesEnforcer { isAllowed(entity: Entity, location: LocationSpec): boolean; } -// Warning: (ae-missing-release-tag) "DeferredEntity" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export type DeferredEntity = { entity: Entity; locationKey?: string; @@ -562,8 +503,6 @@ export type EntitiesCatalog = { facets(request: EntityFacetsRequest): Promise; }; -// Warning: (ae-missing-release-tag) "EntitiesRequest" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type EntitiesRequest = { filter?: EntityFilter; @@ -572,24 +511,18 @@ export type EntitiesRequest = { authorizationToken?: string; }; -// Warning: (ae-missing-release-tag) "EntitiesResponse" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type EntitiesResponse = { entities: Entity[]; pageInfo: PageInfo; }; -// Warning: (ae-missing-release-tag) "EntitiesSearchFilter" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export type EntitiesSearchFilter = { key: string; values?: string[]; }; -// Warning: (ae-missing-release-tag) "entity" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) function entity( atLocation: LocationSpec, @@ -623,8 +556,6 @@ export interface EntityFacetsResponse { >; } -// Warning: (ae-missing-release-tag) "EntityFilter" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export type EntityFilter = | { @@ -638,8 +569,6 @@ export type EntityFilter = } | EntitiesSearchFilter; -// Warning: (ae-missing-release-tag) "EntityPagination" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export type EntityPagination = { limit?: number; @@ -647,17 +576,13 @@ export type EntityPagination = { after?: string; }; -// Warning: (ae-missing-release-tag) "EntityProcessingRequest" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export type EntityProcessingRequest = { entity: Entity; state?: JsonObject; }; -// Warning: (ae-missing-release-tag) "EntityProcessingResult" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export type EntityProcessingResult = | { ok: true; @@ -672,27 +597,18 @@ export type EntityProcessingResult = errors: Error[]; }; -// Warning: (ae-missing-release-tag) "EntityProvider" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export interface EntityProvider { - // (undocumented) connect(connection: EntityProviderConnection): Promise; - // (undocumented) getProviderName(): string; } -// Warning: (ae-missing-release-tag) "EntityProviderConnection" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export interface EntityProviderConnection { - // (undocumented) applyMutation(mutation: EntityProviderMutation): Promise; } -// Warning: (ae-missing-release-tag) "EntityProviderMutation" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export type EntityProviderMutation = | { type: 'full'; @@ -711,8 +627,6 @@ export type EntityRelationSpec = { target: EntityName; }; -// Warning: (ae-missing-release-tag) "FileReaderProcessor" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export class FileReaderProcessor implements CatalogProcessor { // (undocumented) @@ -726,16 +640,12 @@ export class FileReaderProcessor implements CatalogProcessor { ): Promise; } -// Warning: (ae-missing-release-tag) "generalError" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) function generalError( atLocation: LocationSpec, message: string, ): CatalogProcessorResult; -// Warning: (ae-missing-release-tag) "GithubDiscoveryProcessor" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export class GithubDiscoveryProcessor implements CatalogProcessor { constructor(options: { @@ -761,6 +671,13 @@ export class GithubDiscoveryProcessor implements CatalogProcessor { ): Promise; } +// @public +export type GithubMultiOrgConfig = Array<{ + name: string; + groupNamespace: string; + userNamespace: string | undefined; +}>; + // @alpha export class GithubMultiOrgReaderProcessor implements CatalogProcessor { constructor(options: { @@ -787,8 +704,6 @@ export class GithubMultiOrgReaderProcessor implements CatalogProcessor { ): Promise; } -// Warning: (ae-missing-release-tag) "GitHubOrgEntityProvider" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export class GitHubOrgEntityProvider implements EntityProvider { constructor(options: { @@ -816,8 +731,6 @@ export class GitHubOrgEntityProvider implements EntityProvider { read(): Promise; } -// Warning: (ae-missing-release-tag) "GithubOrgReaderProcessor" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export class GithubOrgReaderProcessor implements CatalogProcessor { constructor(options: { @@ -843,8 +756,6 @@ export class GithubOrgReaderProcessor implements CatalogProcessor { ): Promise; } -// Warning: (ae-missing-release-tag) "GitLabDiscoveryProcessor" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export class GitLabDiscoveryProcessor implements CatalogProcessor { // (undocumented) @@ -864,24 +775,18 @@ export class GitLabDiscoveryProcessor implements CatalogProcessor { ): Promise; } -// Warning: (ae-missing-release-tag) "inputError" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) function inputError( atLocation: LocationSpec, message: string, ): CatalogProcessorResult; -// Warning: (ae-missing-release-tag) "location" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) function location_2( newLocation: LocationSpec, optional?: boolean, ): CatalogProcessorResult; -// Warning: (ae-missing-release-tag) "LocationAnalyzer" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type LocationAnalyzer = { analyzeLocation( @@ -889,8 +794,6 @@ export type LocationAnalyzer = { ): Promise; }; -// Warning: (ae-missing-release-tag) "LocationEntityProcessor" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export class LocationEntityProcessor implements CatalogProcessor { constructor(options: LocationEntityProcessorOptions); @@ -904,16 +807,12 @@ export class LocationEntityProcessor implements CatalogProcessor { ): Promise; } -// Warning: (ae-missing-release-tag) "LocationEntityProcessorOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type LocationEntityProcessorOptions = { integrations: ScmIntegrationRegistry; }; -// Warning: (ae-missing-release-tag) "LocationService" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export interface LocationService { // (undocumented) createLocation( @@ -947,9 +846,7 @@ export interface LocationService { }): Promise; } -// Warning: (ae-missing-release-tag) "LocationStore" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export interface LocationStore { // (undocumented) createLocation(spec: LocationSpec): Promise; @@ -961,16 +858,12 @@ export interface LocationStore { listLocations(): Promise; } -// Warning: (ae-missing-release-tag) "notFoundError" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) function notFoundError( atLocation: LocationSpec, message: string, ): CatalogProcessorResult; -// Warning: (ae-missing-release-tag) "PageInfo" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type PageInfo = | { @@ -981,8 +874,6 @@ export type PageInfo = endCursor: string; }; -// Warning: (ae-missing-release-tag) "parseEntityYaml" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export function parseEntityYaml( data: Buffer, @@ -1015,8 +906,6 @@ export const permissionRules: { >; }; -// Warning: (ae-missing-release-tag) "PlaceholderProcessor" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export class PlaceholderProcessor implements CatalogProcessor { constructor(options: PlaceholderProcessorOptions); @@ -1026,8 +915,6 @@ export class PlaceholderProcessor implements CatalogProcessor { preProcessEntity(entity: Entity, location: LocationSpec): Promise; } -// Warning: (ae-missing-release-tag) "PlaceholderProcessorOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type PlaceholderProcessorOptions = { resolvers: Record; @@ -1035,15 +922,11 @@ export type PlaceholderProcessorOptions = { integrations: ScmIntegrationRegistry; }; -// Warning: (ae-missing-release-tag) "PlaceholderResolver" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type PlaceholderResolver = ( params: PlaceholderResolverParams, ) => Promise; -// Warning: (ae-missing-release-tag) "PlaceholderResolverParams" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type PlaceholderResolverParams = { key: string; @@ -1053,21 +936,15 @@ export type PlaceholderResolverParams = { resolveUrl: PlaceholderResolverResolveUrl; }; -// Warning: (ae-missing-release-tag) "PlaceholderResolverRead" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type PlaceholderResolverRead = (url: string) => Promise; -// Warning: (ae-missing-release-tag) "PlaceholderResolverResolveUrl" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type PlaceholderResolverResolveUrl = ( url: string, base: string, ) => string; -// Warning: (ae-missing-release-tag) "RecursivePartial" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export type RecursivePartial = { [P in keyof T]?: T[P] extends (infer U)[] @@ -1077,8 +954,6 @@ export type RecursivePartial = { : T[P]; }; -// Warning: (ae-missing-release-tag) "RefreshIntervalFunction" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export type RefreshIntervalFunction = () => number; @@ -1093,8 +968,6 @@ export interface RefreshService { refresh(options: RefreshOptions): Promise; } -// Warning: (ae-missing-release-tag) "relation" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) function relation(spec: EntityRelationSpec): CatalogProcessorResult; @@ -1128,13 +1001,9 @@ export interface RouterOptions { refreshService?: RefreshService; } -// Warning: (ae-missing-release-tag) "runPeriodically" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public @deprecated export function runPeriodically(fn: () => any, delayMs: number): () => void; -// Warning: (ae-missing-release-tag) "StaticLocationProcessor" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public @deprecated (undocumented) export class StaticLocationProcessor implements StaticLocationProcessor { constructor(staticLocations: LocationSpec[]); @@ -1148,12 +1017,9 @@ export class StaticLocationProcessor implements StaticLocationProcessor { ): Promise; } -// Warning: (ae-missing-release-tag) "UrlReaderProcessor" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export class UrlReaderProcessor implements CatalogProcessor { - // Warning: (ae-forgotten-export) The symbol "Options" needs to be exported by the entry point index.d.ts - constructor(options: Options_2); + constructor(options: { reader: UrlReader; logger: Logger_2 }); // (undocumented) getProcessorName(): string; // (undocumented) @@ -1165,8 +1031,4 @@ export class UrlReaderProcessor implements CatalogProcessor { cache: CatalogProcessorCache, ): Promise; } - -// Warnings were encountered during analysis: -// -// src/ingestion/processors/GithubMultiOrgReaderProcessor.d.ts:25:9 - (ae-forgotten-export) The symbol "GithubMultiOrgConfig" needs to be exported by the entry point index.d.ts ``` diff --git a/plugins/catalog-backend/src/catalog/types.ts b/plugins/catalog-backend/src/catalog/types.ts index e285d4c100..abf9e4d114 100644 --- a/plugins/catalog-backend/src/catalog/types.ts +++ b/plugins/catalog-backend/src/catalog/types.ts @@ -21,6 +21,7 @@ import { Entity } from '@backstage/catalog-model'; * * Any (at least one) of the outer sets must match, within which all of the * individual filters must match. + * @public */ export type EntityFilter = | { allOf: EntityFilter[] } @@ -30,6 +31,7 @@ export type EntityFilter = /** * A pagination rule for entities. + * @public */ export type EntityPagination = { limit?: number; @@ -39,6 +41,7 @@ export type EntityPagination = { /** * Matches rows in the entities_search table. + * @public */ export type EntitiesSearchFilter = { /** @@ -57,6 +60,7 @@ export type EntitiesSearchFilter = { values?: string[]; }; +/** @public */ export type PageInfo = | { hasNextPage: false; @@ -66,6 +70,7 @@ export type PageInfo = endCursor: string; }; +/** @public */ export type EntitiesRequest = { filter?: EntityFilter; fields?: (entity: Entity) => Entity; @@ -73,6 +78,7 @@ export type EntitiesRequest = { authorizationToken?: string; }; +/** @public */ export type EntitiesResponse = { entities: Entity[]; pageInfo: PageInfo; diff --git a/plugins/catalog-backend/src/ingestion/processors/AnnotateLocationEntityProcessor.ts b/plugins/catalog-backend/src/ingestion/processors/AnnotateLocationEntityProcessor.ts index 90b3280ab8..0067f3c26d 100644 --- a/plugins/catalog-backend/src/ingestion/processors/AnnotateLocationEntityProcessor.ts +++ b/plugins/catalog-backend/src/ingestion/processors/AnnotateLocationEntityProcessor.ts @@ -28,12 +28,13 @@ import { ScmIntegrationRegistry } from '@backstage/integration'; import { identity, merge, pickBy } from 'lodash'; import { CatalogProcessor, CatalogProcessorEmit } from './types'; -type Options = { - integrations: ScmIntegrationRegistry; -}; - +/** @public */ export class AnnotateLocationEntityProcessor implements CatalogProcessor { - constructor(private readonly options: Options) {} + constructor( + private readonly options: { + integrations: ScmIntegrationRegistry; + }, + ) {} getProcessorName(): string { return 'AnnotateLocationEntityProcessor'; diff --git a/plugins/catalog-backend/src/ingestion/processors/AnnotateScmSlugEntityProcessor.ts b/plugins/catalog-backend/src/ingestion/processors/AnnotateScmSlugEntityProcessor.ts index b3a3cfd999..d6e037662e 100644 --- a/plugins/catalog-backend/src/ingestion/processors/AnnotateScmSlugEntityProcessor.ts +++ b/plugins/catalog-backend/src/ingestion/processors/AnnotateScmSlugEntityProcessor.ts @@ -25,6 +25,7 @@ import { CatalogProcessor } from './types'; const GITHUB_ACTIONS_ANNOTATION = 'github.com/project-slug'; +/** @public */ export class AnnotateScmSlugEntityProcessor implements CatalogProcessor { constructor( private readonly opts: { scmIntegrationRegistry: ScmIntegrationRegistry }, diff --git a/plugins/catalog-backend/src/ingestion/processors/AwsS3DiscoveryProcessor.ts b/plugins/catalog-backend/src/ingestion/processors/AwsS3DiscoveryProcessor.ts index 77152f81af..726c972d8d 100644 --- a/plugins/catalog-backend/src/ingestion/processors/AwsS3DiscoveryProcessor.ts +++ b/plugins/catalog-backend/src/ingestion/processors/AwsS3DiscoveryProcessor.ts @@ -25,6 +25,7 @@ import { CatalogProcessorParser, } from './types'; +/** @public */ export class AwsS3DiscoveryProcessor implements CatalogProcessor { constructor(private readonly reader: UrlReader) {} diff --git a/plugins/catalog-backend/src/ingestion/processors/AzureDevOpsDiscoveryProcessor.ts b/plugins/catalog-backend/src/ingestion/processors/AzureDevOpsDiscoveryProcessor.ts index c1cc610495..a257afc950 100644 --- a/plugins/catalog-backend/src/ingestion/processors/AzureDevOpsDiscoveryProcessor.ts +++ b/plugins/catalog-backend/src/ingestion/processors/AzureDevOpsDiscoveryProcessor.ts @@ -38,6 +38,8 @@ import { codeSearch } from './azure'; * You may also explicitly specify a single repo: * * target: https://dev.azure.com/org/project/_git/repo + * + * @public **/ export class AzureDevOpsDiscoveryProcessor implements CatalogProcessor { private readonly integrations: ScmIntegrationRegistry; diff --git a/plugins/catalog-backend/src/ingestion/processors/BitbucketDiscoveryProcessor.ts b/plugins/catalog-backend/src/ingestion/processors/BitbucketDiscoveryProcessor.ts index 2cc6822eaa..8ac6d617ca 100644 --- a/plugins/catalog-backend/src/ingestion/processors/BitbucketDiscoveryProcessor.ts +++ b/plugins/catalog-backend/src/ingestion/processors/BitbucketDiscoveryProcessor.ts @@ -37,6 +37,7 @@ const DEFAULT_BRANCH = 'master'; const DEFAULT_CATALOG_LOCATION = '/catalog-info.yaml'; const EMPTY_CATALOG_LOCATION = '/'; +/** @public */ export class BitbucketDiscoveryProcessor implements CatalogProcessor { private readonly integrations: ScmIntegrationRegistry; private readonly parser: BitbucketRepositoryParser; diff --git a/plugins/catalog-backend/src/ingestion/processors/BuiltinKindsEntityProcessor.ts b/plugins/catalog-backend/src/ingestion/processors/BuiltinKindsEntityProcessor.ts index 729cd023f8..ec0afeba36 100644 --- a/plugins/catalog-backend/src/ingestion/processors/BuiltinKindsEntityProcessor.ts +++ b/plugins/catalog-backend/src/ingestion/processors/BuiltinKindsEntityProcessor.ts @@ -56,6 +56,7 @@ import { import * as result from './results'; import { CatalogProcessor, CatalogProcessorEmit } from './types'; +/** @public */ export class BuiltinKindsEntityProcessor implements CatalogProcessor { private readonly validators = [ apiEntityV1alpha1Validator, diff --git a/plugins/catalog-backend/src/ingestion/processors/CodeOwnersProcessor.ts b/plugins/catalog-backend/src/ingestion/processors/CodeOwnersProcessor.ts index ff5dedcbbf..d7b2bf8849 100644 --- a/plugins/catalog-backend/src/ingestion/processors/CodeOwnersProcessor.ts +++ b/plugins/catalog-backend/src/ingestion/processors/CodeOwnersProcessor.ts @@ -29,6 +29,7 @@ const ALLOWED_KINDS = ['API', 'Component', 'Domain', 'Resource', 'System']; const ALLOWED_LOCATION_TYPES = ['url']; +/** @public */ export class CodeOwnersProcessor implements CatalogProcessor { private readonly integrations: ScmIntegrationRegistry; private readonly logger: Logger; diff --git a/plugins/catalog-backend/src/ingestion/processors/FileReaderProcessor.ts b/plugins/catalog-backend/src/ingestion/processors/FileReaderProcessor.ts index 20020fcfbe..5e3d4812c2 100644 --- a/plugins/catalog-backend/src/ingestion/processors/FileReaderProcessor.ts +++ b/plugins/catalog-backend/src/ingestion/processors/FileReaderProcessor.ts @@ -28,6 +28,7 @@ import { const glob = promisify(g); +/** @public */ export class FileReaderProcessor implements CatalogProcessor { getProcessorName(): string { return 'FileReaderProcessor'; diff --git a/plugins/catalog-backend/src/ingestion/processors/GitLabDiscoveryProcessor.ts b/plugins/catalog-backend/src/ingestion/processors/GitLabDiscoveryProcessor.ts index 776ec1e7a8..c8996e8d3e 100644 --- a/plugins/catalog-backend/src/ingestion/processors/GitLabDiscoveryProcessor.ts +++ b/plugins/catalog-backend/src/ingestion/processors/GitLabDiscoveryProcessor.ts @@ -32,6 +32,7 @@ import { /** * Extracts repositories out of an GitLab instance. + * @public */ export class GitLabDiscoveryProcessor implements CatalogProcessor { private readonly integrations: ScmIntegrationRegistry; diff --git a/plugins/catalog-backend/src/ingestion/processors/GithubDiscoveryProcessor.ts b/plugins/catalog-backend/src/ingestion/processors/GithubDiscoveryProcessor.ts index ec0de74b00..982007d3a5 100644 --- a/plugins/catalog-backend/src/ingestion/processors/GithubDiscoveryProcessor.ts +++ b/plugins/catalog-backend/src/ingestion/processors/GithubDiscoveryProcessor.ts @@ -41,6 +41,8 @@ import { CatalogProcessor, CatalogProcessorEmit } from './types'; * You may also explicitly specify the source branch: * * target: https://github.com/backstage/*\/blob/main/catalog-info.yaml + * + * @public **/ export class GithubDiscoveryProcessor implements CatalogProcessor { private readonly integrations: ScmIntegrationRegistry; diff --git a/plugins/catalog-backend/src/ingestion/processors/GithubOrgReaderProcessor.ts b/plugins/catalog-backend/src/ingestion/processors/GithubOrgReaderProcessor.ts index 2a411af33e..39384be0dc 100644 --- a/plugins/catalog-backend/src/ingestion/processors/GithubOrgReaderProcessor.ts +++ b/plugins/catalog-backend/src/ingestion/processors/GithubOrgReaderProcessor.ts @@ -38,6 +38,7 @@ type GraphQL = typeof graphql; /** * Extracts teams and users out of a GitHub org. + * @public */ export class GithubOrgReaderProcessor implements CatalogProcessor { private readonly integrations: ScmIntegrationRegistry; diff --git a/plugins/catalog-backend/src/ingestion/processors/LocationEntityProcessor.ts b/plugins/catalog-backend/src/ingestion/processors/LocationEntityProcessor.ts index 60941486c3..5aee5a1ca2 100644 --- a/plugins/catalog-backend/src/ingestion/processors/LocationEntityProcessor.ts +++ b/plugins/catalog-backend/src/ingestion/processors/LocationEntityProcessor.ts @@ -38,10 +38,12 @@ export function toAbsoluteUrl( } } +/** @public */ export type LocationEntityProcessorOptions = { integrations: ScmIntegrationRegistry; }; +/** @public */ export class LocationEntityProcessor implements CatalogProcessor { constructor(private readonly options: LocationEntityProcessorOptions) {} diff --git a/plugins/catalog-backend/src/ingestion/processors/PlaceholderProcessor.ts b/plugins/catalog-backend/src/ingestion/processors/PlaceholderProcessor.ts index 1a0ca75ba5..e19576d782 100644 --- a/plugins/catalog-backend/src/ingestion/processors/PlaceholderProcessor.ts +++ b/plugins/catalog-backend/src/ingestion/processors/PlaceholderProcessor.ts @@ -21,12 +21,16 @@ import { ScmIntegrationRegistry } from '@backstage/integration'; import yaml from 'yaml'; import { CatalogProcessor } from './types'; +/** @public */ export type PlaceholderResolverRead = (url: string) => Promise; + +/** @public */ export type PlaceholderResolverResolveUrl = ( url: string, base: string, ) => string; +/** @public */ export type PlaceholderResolverParams = { key: string; value: JsonValue; @@ -35,10 +39,12 @@ export type PlaceholderResolverParams = { resolveUrl: PlaceholderResolverResolveUrl; }; +/** @public */ export type PlaceholderResolver = ( params: PlaceholderResolverParams, ) => Promise; +/** @public */ export type PlaceholderProcessorOptions = { resolvers: Record; reader: UrlReader; @@ -48,6 +54,7 @@ export type PlaceholderProcessorOptions = { /** * Traverses raw entity JSON looking for occurrences of $-prefixed placeholders * that it then fills in with actual data. + * @public */ export class PlaceholderProcessor implements CatalogProcessor { constructor(private readonly options: PlaceholderProcessorOptions) {} diff --git a/plugins/catalog-backend/src/ingestion/processors/StaticLocationProcessor.ts b/plugins/catalog-backend/src/ingestion/processors/StaticLocationProcessor.ts index c23c14bac9..bcafa33162 100644 --- a/plugins/catalog-backend/src/ingestion/processors/StaticLocationProcessor.ts +++ b/plugins/catalog-backend/src/ingestion/processors/StaticLocationProcessor.ts @@ -21,6 +21,7 @@ import { CatalogProcessorEmit } from './types'; /** * @deprecated no longer in use, replaced by the ConfigLocationEntityProvider. + * @public */ export class StaticLocationProcessor implements StaticLocationProcessor { static fromConfig(config: Config): StaticLocationProcessor { diff --git a/plugins/catalog-backend/src/ingestion/processors/UrlReaderProcessor.ts b/plugins/catalog-backend/src/ingestion/processors/UrlReaderProcessor.ts index 6a85cc07c7..d13e5dfeda 100644 --- a/plugins/catalog-backend/src/ingestion/processors/UrlReaderProcessor.ts +++ b/plugins/catalog-backend/src/ingestion/processors/UrlReaderProcessor.ts @@ -32,11 +32,6 @@ import { const CACHE_KEY = 'v1'; -type Options = { - reader: UrlReader; - logger: Logger; -}; - // WARNING: If you change this type, you likely need to bump the CACHE_KEY as well type CacheItem = { etag: string; @@ -47,8 +42,14 @@ type CacheItem = { }[]; }; +/** @public */ export class UrlReaderProcessor implements CatalogProcessor { - constructor(private readonly options: Options) {} + constructor( + private readonly options: { + reader: UrlReader; + logger: Logger; + }, + ) {} getProcessorName() { return 'url-reader'; diff --git a/plugins/catalog-backend/src/ingestion/processors/bitbucket/BitbucketRepositoryParser.ts b/plugins/catalog-backend/src/ingestion/processors/bitbucket/BitbucketRepositoryParser.ts index 3407fae16a..9eaec221b5 100644 --- a/plugins/catalog-backend/src/ingestion/processors/bitbucket/BitbucketRepositoryParser.ts +++ b/plugins/catalog-backend/src/ingestion/processors/bitbucket/BitbucketRepositoryParser.ts @@ -18,6 +18,7 @@ import { results } from '../index'; import { Logger } from 'winston'; import { BitbucketIntegration } from '@backstage/integration'; +/** @public */ export type BitbucketRepositoryParser = (options: { integration: BitbucketIntegration; target: string; diff --git a/plugins/catalog-backend/src/ingestion/processors/github/config.ts b/plugins/catalog-backend/src/ingestion/processors/github/config.ts index 27bec6eb0d..cd17d30311 100644 --- a/plugins/catalog-backend/src/ingestion/processors/github/config.ts +++ b/plugins/catalog-backend/src/ingestion/processors/github/config.ts @@ -86,6 +86,7 @@ export function readGithubConfig(config: Config): ProviderConfig[] { /** * The configuration parameters for a multi-org GitHub processor. + * @public */ export type GithubMultiOrgConfig = Array<{ /** diff --git a/plugins/catalog-backend/src/ingestion/processors/index.ts b/plugins/catalog-backend/src/ingestion/processors/index.ts index 36f85647d3..84a92fb1ba 100644 --- a/plugins/catalog-backend/src/ingestion/processors/index.ts +++ b/plugins/catalog-backend/src/ingestion/processors/index.ts @@ -45,3 +45,4 @@ export { parseEntityYaml } from './util/parse'; export { results }; export type { BitbucketRepositoryParser } from './bitbucket'; +export type { GithubMultiOrgConfig } from './github'; diff --git a/plugins/catalog-backend/src/ingestion/processors/results.ts b/plugins/catalog-backend/src/ingestion/processors/results.ts index 2862c95119..539f915fba 100644 --- a/plugins/catalog-backend/src/ingestion/processors/results.ts +++ b/plugins/catalog-backend/src/ingestion/processors/results.ts @@ -19,6 +19,7 @@ import { Entity, LocationSpec } from '@backstage/catalog-model'; import { CatalogProcessorResult } from './types'; import { EntityRelationSpec } from '../../processing/types'; +/** @public */ export function notFoundError( atLocation: LocationSpec, message: string, @@ -30,6 +31,7 @@ export function notFoundError( }; } +/** @public */ export function inputError( atLocation: LocationSpec, message: string, @@ -41,6 +43,7 @@ export function inputError( }; } +/** @public */ export function generalError( atLocation: LocationSpec, message: string, @@ -48,6 +51,7 @@ export function generalError( return { type: 'error', location: atLocation, error: new Error(message) }; } +/** @public */ export function location( newLocation: LocationSpec, optional?: boolean, @@ -55,6 +59,7 @@ export function location( return { type: 'location', location: newLocation, optional }; } +/** @public */ export function entity( atLocation: LocationSpec, newEntity: Entity, @@ -62,6 +67,7 @@ export function entity( return { type: 'entity', location: atLocation, entity: newEntity }; } +/** @public */ export function relation(spec: EntityRelationSpec): CatalogProcessorResult { return { type: 'relation', relation: spec }; } diff --git a/plugins/catalog-backend/src/ingestion/processors/types.ts b/plugins/catalog-backend/src/ingestion/processors/types.ts index 873fef842f..1bd65c6f7a 100644 --- a/plugins/catalog-backend/src/ingestion/processors/types.ts +++ b/plugins/catalog-backend/src/ingestion/processors/types.ts @@ -18,6 +18,9 @@ import { Entity, LocationSpec } from '@backstage/catalog-model'; import { JsonValue } from '@backstage/types'; import { EntityRelationSpec } from '../../processing/types'; +/** + * @public + */ export type CatalogProcessor = { /** * A unique identifier for the Catalog Processor. @@ -116,6 +119,7 @@ export type CatalogProcessor = { * 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 type CatalogProcessorParser = (options: { data: Buffer; @@ -150,8 +154,10 @@ export interface CatalogProcessorCache { set(key: string, value: ItemType): Promise; } +/** @public */ export type CatalogProcessorEmit = (generated: CatalogProcessorResult) => void; +/** @public */ export type CatalogProcessorLocationResult = { type: 'location'; location: LocationSpec; @@ -159,24 +165,28 @@ export type CatalogProcessorLocationResult = { optional?: boolean; }; +/** @public */ export type CatalogProcessorEntityResult = { type: 'entity'; entity: Entity; location: LocationSpec; }; +/** @public */ export type CatalogProcessorRelationResult = { type: 'relation'; relation: EntityRelationSpec; entityRef?: string; }; +/** @public */ export type CatalogProcessorErrorResult = { type: 'error'; error: Error; location: LocationSpec; }; +/** @public */ export type CatalogProcessorResult = | CatalogProcessorLocationResult | CatalogProcessorEntityResult diff --git a/plugins/catalog-backend/src/ingestion/processors/util/parse.ts b/plugins/catalog-backend/src/ingestion/processors/util/parse.ts index a6aba7e1f9..5637170f9b 100644 --- a/plugins/catalog-backend/src/ingestion/processors/util/parse.ts +++ b/plugins/catalog-backend/src/ingestion/processors/util/parse.ts @@ -24,6 +24,7 @@ import yaml from 'yaml'; import * as result from '../results'; import { CatalogProcessorParser, CatalogProcessorResult } from '../types'; +/** @public */ export function* parseEntityYaml( data: Buffer, location: LocationSpec, diff --git a/plugins/catalog-backend/src/ingestion/providers/GitHubOrgEntityProvider.ts b/plugins/catalog-backend/src/ingestion/providers/GitHubOrgEntityProvider.ts index 20e9966bd1..a20f7fdb0b 100644 --- a/plugins/catalog-backend/src/ingestion/providers/GitHubOrgEntityProvider.ts +++ b/plugins/catalog-backend/src/ingestion/providers/GitHubOrgEntityProvider.ts @@ -38,7 +38,7 @@ import { import { assignGroupsToUsers, buildOrgHierarchy } from '../processors/util/org'; // TODO: Consider supporting an (optional) webhook that reacts on org changes - +/** @public */ export class GitHubOrgEntityProvider implements EntityProvider { private connection?: EntityProviderConnection; private githubCredentialsProvider: GithubCredentialsProvider; diff --git a/plugins/catalog-backend/src/ingestion/types.ts b/plugins/catalog-backend/src/ingestion/types.ts index 30cdee4760..7d7a185231 100644 --- a/plugins/catalog-backend/src/ingestion/types.ts +++ b/plugins/catalog-backend/src/ingestion/types.ts @@ -17,10 +17,7 @@ import { Entity, LocationSpec } from '@backstage/catalog-model'; import { RecursivePartial } from '../util/RecursivePartial'; -// -// LocationAnalyzer -// - +/** @public */ export type LocationAnalyzer = { /** * Generates an entity configuration for given git repository. It's used for @@ -33,30 +30,38 @@ export type LocationAnalyzer = { ): Promise; }; +/** @public */ export type AnalyzeLocationRequest = { location: LocationSpec; }; +/** @public */ export type AnalyzeLocationResponse = { existingEntityFiles: AnalyzeLocationExistingEntity[]; generateEntities: AnalyzeLocationGenerateEntity[]; }; -// If the folder pointed to already contained catalog info yaml files, they are -// read and emitted like this so that the frontend can inform the user that it -// located them and can make sure to register them as well if they weren't -// already +/** + * If the folder pointed to already contained catalog info yaml files, they are + * read and emitted like this so that the frontend can inform the user that it + * located them and can make sure to register them as well if they weren't + * already + * @public + */ export type AnalyzeLocationExistingEntity = { location: LocationSpec; isRegistered: boolean; entity: Entity; }; -// This is some form of representation of what the analyzer could deduce. -// We should probably have a chat about how this can best be conveyed to -// the frontend. It'll probably contain a (possibly incomplete) entity, plus -// enough info for the frontend to know what form data to show to the user -// for overriding/completing the info. +/** + * This is some form of representation of what the analyzer could deduce. + * We should probably have a chat about how this can best be conveyed to + * the frontend. It'll probably contain a (possibly incomplete) entity, plus + * enough info for the frontend to know what form data to show to the user + * for overriding/completing the info. + * @public + * */ export type AnalyzeLocationGenerateEntity = { // Some form of partial representation of the entity entity: RecursivePartial; @@ -67,12 +72,15 @@ export type AnalyzeLocationGenerateEntity = { // This is where I get really vague. Something like this perhaps? Or it could be // something like a json-schema that contains enough info for the frontend to // be able to present a form and explanations +/** @public */ export type AnalyzeLocationEntityField = { - // e.g. "spec.owner"? The frontend needs to know how to "inject" the field into the - // entity again if the user wants to change it + /** + * e.g. "spec.owner"? The frontend needs to know how to "inject" the field into the + * entity again if the user wants to change it + */ field: string; - // The outcome of the analysis for this particular field + /** The outcome of the analysis for this particular field */ state: | 'analysisSuggestedValue' | 'analysisSuggestedNoValue' @@ -81,10 +89,11 @@ export type AnalyzeLocationEntityField = { // If the analysis did suggest a value, this is where it would be. Not sure if we want // to limit this to strings or if we want it to be any JsonValue value: string | null; - - // A text to show to the user to inform about the choices made. Like, it could say - // "Found a CODEOWNERS file that covers this target, so we suggest leaving this - // field empty; which would currently make it owned by X" where X is taken from the - // codeowners file. + /** + * A text to show to the user to inform about the choices made. Like, it could say + * "Found a CODEOWNERS file that covers this target, so we suggest leaving this + * field empty; which would currently make it owned by X" where X is taken from the + * codeowners file. + */ description: string; }; diff --git a/plugins/catalog-backend/src/processing/DefaultCatalogProcessingOrchestrator.ts b/plugins/catalog-backend/src/processing/DefaultCatalogProcessingOrchestrator.ts index 105121ae2a..2ffaa2912f 100644 --- a/plugins/catalog-backend/src/processing/DefaultCatalogProcessingOrchestrator.ts +++ b/plugins/catalog-backend/src/processing/DefaultCatalogProcessingOrchestrator.ts @@ -64,6 +64,7 @@ type Context = { cache: ProcessorCacheManager; }; +/** @public */ export class DefaultCatalogProcessingOrchestrator implements CatalogProcessingOrchestrator { diff --git a/plugins/catalog-backend/src/processing/refresh.ts b/plugins/catalog-backend/src/processing/refresh.ts index c60f42ff96..3e03e3add8 100644 --- a/plugins/catalog-backend/src/processing/refresh.ts +++ b/plugins/catalog-backend/src/processing/refresh.ts @@ -16,12 +16,14 @@ /** * Function that returns the catalog refresh interval in seconds. + * @public */ export 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 + * @public */ export function createRandomRefreshInterval(options: { minSeconds: number; diff --git a/plugins/catalog-backend/src/processing/types.ts b/plugins/catalog-backend/src/processing/types.ts index 33d8ed8771..b732df297e 100644 --- a/plugins/catalog-backend/src/processing/types.ts +++ b/plugins/catalog-backend/src/processing/types.ts @@ -39,11 +39,19 @@ export type EntityRelationSpec = { target: EntityName; }; +/** + * The request to process an entity. + * @public + */ export type EntityProcessingRequest = { entity: Entity; state?: JsonObject; // Versions for multiple deployments etc }; +/** + * The result of processing an entity. + * @public + */ export type EntityProcessingResult = | { ok: true; @@ -58,15 +66,24 @@ export type EntityProcessingResult = errors: Error[]; }; +/** + * Responsible for executing the individual processing steps in order to fully process an entity. + * @public + * */ export interface CatalogProcessingOrchestrator { process(request: EntityProcessingRequest): Promise; } +/** + * Entities that are not yet processed. + * @public + * */ export type DeferredEntity = { entity: Entity; locationKey?: string; }; +/** @public */ export interface CatalogProcessingEngine { start(): Promise; stop(): Promise; diff --git a/plugins/catalog-backend/src/providers/types.ts b/plugins/catalog-backend/src/providers/types.ts index 90c5f13215..226c021e3c 100644 --- a/plugins/catalog-backend/src/providers/types.ts +++ b/plugins/catalog-backend/src/providers/types.ts @@ -16,15 +16,36 @@ import { DeferredEntity } from '../processing'; +/** + * @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 type EntityProviderMutation = | { type: 'full'; entities: DeferredEntity[] } | { type: 'delta'; added: DeferredEntity[]; removed: DeferredEntity[] }; +/** + * 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 interface EntityProviderConnection { + /** + * Applies either a full or delta update to the catalog engine. + */ applyMutation(mutation: EntityProviderMutation): Promise; } +/** + * 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 interface EntityProvider { + /** Unique name provider name used internally for caching. */ getProviderName(): string; + /** Connect is called upon initialization by the catalog engine. */ connect(connection: EntityProviderConnection): Promise; } diff --git a/plugins/catalog-backend/src/search/DefaultCatalogCollator.ts b/plugins/catalog-backend/src/search/DefaultCatalogCollator.ts index 8e72a265af..96704a6c1a 100644 --- a/plugins/catalog-backend/src/search/DefaultCatalogCollator.ts +++ b/plugins/catalog-backend/src/search/DefaultCatalogCollator.ts @@ -32,6 +32,7 @@ import { } from '@backstage/catalog-client'; import { catalogEntityReadPermission } from '@backstage/plugin-catalog-common'; +/** @public */ export interface CatalogEntityDocument extends IndexableDocument { componentType: string; namespace: string; @@ -40,6 +41,7 @@ export interface CatalogEntityDocument extends IndexableDocument { owner: string; } +/** @public */ export class DefaultCatalogCollator implements DocumentCollator { protected discovery: PluginEndpointDiscovery; protected locationTemplate: string; diff --git a/plugins/catalog-backend/src/service/CatalogBuilder.ts b/plugins/catalog-backend/src/service/CatalogBuilder.ts index 46c92c43da..9004cb4c56 100644 --- a/plugins/catalog-backend/src/service/CatalogBuilder.ts +++ b/plugins/catalog-backend/src/service/CatalogBuilder.ts @@ -97,6 +97,7 @@ import { basicEntityFilter } from './request/basicEntityFilter'; import { RESOURCE_TYPE_CATALOG_ENTITY } from '@backstage/plugin-catalog-common'; import { AuthorizedLocationService } from './AuthorizedLocationService'; +/** @public */ export type CatalogEnvironment = { logger: Logger; database: PluginDatabaseManager; diff --git a/plugins/catalog-backend/src/service/types.ts b/plugins/catalog-backend/src/service/types.ts index c923949a04..c10ccda14b 100644 --- a/plugins/catalog-backend/src/service/types.ts +++ b/plugins/catalog-backend/src/service/types.ts @@ -17,6 +17,10 @@ import { Entity, LocationSpec } from '@backstage/catalog-model'; import { Location } from '@backstage/catalog-client'; +/** + * The location service manages entity locations. + * @public + */ export interface LocationService { createLocation( spec: LocationSpec, @@ -59,6 +63,9 @@ export interface RefreshService { refresh(options: RefreshOptions): Promise; } +/** + * Interacts with the database to manage locations. + * @public */ export interface LocationStore { createLocation(spec: LocationSpec): Promise; listLocations(): Promise; diff --git a/plugins/catalog-backend/src/util/RecursivePartial.ts b/plugins/catalog-backend/src/util/RecursivePartial.ts index 502f4464c1..92e1ab9296 100644 --- a/plugins/catalog-backend/src/util/RecursivePartial.ts +++ b/plugins/catalog-backend/src/util/RecursivePartial.ts @@ -16,6 +16,7 @@ /** * Makes all keys of an entire hierarchy optional. + * @public */ export type RecursivePartial = { [P in keyof T]?: T[P] extends (infer U)[] diff --git a/plugins/catalog-backend/src/util/runPeriodically.ts b/plugins/catalog-backend/src/util/runPeriodically.ts index d3bf5d21d5..361fb33b2f 100644 --- a/plugins/catalog-backend/src/util/runPeriodically.ts +++ b/plugins/catalog-backend/src/util/runPeriodically.ts @@ -24,6 +24,7 @@ * next. * @returns A function that, when called, stops the invocation loop. * @deprecated use \@backstage/backend-tasks package instead. + * @public */ export function runPeriodically(fn: () => any, delayMs: number): () => void { let cancel: () => void; diff --git a/scripts/api-extractor.ts b/scripts/api-extractor.ts index 22d00e5dfe..482b011ffb 100644 --- a/scripts/api-extractor.ts +++ b/scripts/api-extractor.ts @@ -219,6 +219,7 @@ const NO_WARNING_PACKAGES = [ 'packages/release-manifests', 'packages/version-bridge', 'plugins/auth-node', + 'plugins/catalog-backend', 'plugins/catalog-backend-module-aws', 'plugins/catalog-backend-module-ldap', 'plugins/catalog-backend-module-msgraph',