From 162b0dfa663db8af55d787aca9d6ae40a3f627b5 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sun, 5 Sep 2021 21:18:04 +0200 Subject: [PATCH] catalog-model: API report warnings cleanup Signed-off-by: Patrik Oldsberg --- packages/catalog-model/api-report.md | 219 +----------------- packages/catalog-model/src/EntityPolicies.ts | 5 +- packages/catalog-model/src/entity/Entity.ts | 8 + .../src/entity/EntityEnvelope.ts | 1 + .../catalog-model/src/entity/EntityStatus.ts | 1 + .../catalog-model/src/entity/constants.ts | 7 + packages/catalog-model/src/entity/index.ts | 1 + .../policies/DefaultNamespaceEntityPolicy.ts | 2 + .../policies/FieldFormatEntityPolicy.ts | 2 + .../NoForeignRootFieldsEntityPolicy.ts | 2 + .../policies/SchemaValidEntityPolicy.ts | 2 + .../src/entity/policies/types.ts | 4 +- packages/catalog-model/src/entity/ref.ts | 32 ++- packages/catalog-model/src/entity/util.ts | 12 +- .../src/kinds/ApiEntityV1alpha1.ts | 2 + .../src/kinds/ComponentEntityV1alpha1.ts | 2 + .../src/kinds/DomainEntityV1alpha1.ts | 2 + .../src/kinds/GroupEntityV1alpha1.ts | 2 + .../src/kinds/LocationEntityV1alpha1.ts | 2 + .../src/kinds/ResourceEntityV1alpha1.ts | 2 + .../src/kinds/SystemEntityV1alpha1.ts | 2 + .../src/kinds/TemplateEntityV1beta2.ts | 2 + .../src/kinds/UserEntityV1alpha1.ts | 2 + packages/catalog-model/src/kinds/relations.ts | 20 ++ packages/catalog-model/src/kinds/types.ts | 4 +- .../catalog-model/src/location/annotation.ts | 3 + .../catalog-model/src/location/helpers.ts | 14 +- packages/catalog-model/src/location/types.ts | 2 + .../catalog-model/src/location/validation.ts | 15 +- packages/catalog-model/src/types.ts | 5 + .../validation/CommonValidatorFunctions.ts | 20 +- .../KubernetesValidatorFunctions.ts | 1 + .../entityEnvelopeSchemaValidator.ts | 3 +- .../validation/entityKindSchemaValidator.ts | 19 +- .../src/validation/entitySchemaValidator.ts | 3 +- .../src/validation/makeValidator.ts | 1 + .../catalog-model/src/validation/types.ts | 1 + 37 files changed, 170 insertions(+), 257 deletions(-) diff --git a/packages/catalog-model/api-report.md b/packages/catalog-model/api-report.md index b9f46add6a..407e18a409 100644 --- a/packages/catalog-model/api-report.md +++ b/packages/catalog-model/api-report.md @@ -9,9 +9,6 @@ import { JsonValue } from '@backstage/config'; import { SerializedError } from '@backstage/errors'; import * as yup from 'yup'; -// Warning: (tsdoc-missing-deprecation-message) The @deprecated block must include a deprecation message, e.g. describing the recommended alternative -// Warning: (ae-missing-release-tag) "analyzeLocationSchema" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public @deprecated (undocumented) export const analyzeLocationSchema: yup.ObjectSchema< { @@ -20,8 +17,6 @@ export const analyzeLocationSchema: yup.ObjectSchema< object >; -// Warning: (ae-missing-release-tag) "ApiEntityV1alpha1" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) interface ApiEntityV1alpha1 extends Entity { // (undocumented) @@ -40,43 +35,24 @@ interface ApiEntityV1alpha1 extends Entity { export { ApiEntityV1alpha1 as ApiEntity }; export { ApiEntityV1alpha1 }; -// Warning: (ae-missing-release-tag) "apiEntityV1alpha1Validator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export const apiEntityV1alpha1Validator: KindValidator; -// Warning: (ae-missing-release-tag) "CommonValidatorFunctions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export class CommonValidatorFunctions { - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen static isJsonSafe(value: unknown): boolean; - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen static isValidDnsLabel(value: unknown): boolean; - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen static isValidDnsSubdomain(value: unknown): boolean; - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen static isValidPrefixAndOrSuffix( value: unknown, separator: string, isValidPrefix: (value: string) => boolean, isValidSuffix: (value: string) => boolean, ): boolean; - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen static isValidString(value: unknown): boolean; - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen static isValidUrl(value: unknown): boolean; } -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (ae-forgotten-export) The symbol "EntityRefContext" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "compareEntityToRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export function compareEntityToRef( entity: Entity, @@ -84,8 +60,6 @@ export function compareEntityToRef( context?: EntityRefContext, ): boolean; -// Warning: (ae-missing-release-tag) "ComponentEntityV1alpha1" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) interface ComponentEntityV1alpha1 extends Entity { // (undocumented) @@ -107,13 +81,9 @@ interface ComponentEntityV1alpha1 extends Entity { export { ComponentEntityV1alpha1 as ComponentEntity }; export { ComponentEntityV1alpha1 }; -// Warning: (ae-missing-release-tag) "componentEntityV1alpha1Validator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export const componentEntityV1alpha1Validator: KindValidator; -// Warning: (ae-missing-release-tag) "DefaultNamespaceEntityPolicy" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export class DefaultNamespaceEntityPolicy implements EntityPolicy { constructor(namespace?: string); @@ -121,8 +91,6 @@ export class DefaultNamespaceEntityPolicy implements EntityPolicy { enforce(entity: Entity): Promise; } -// Warning: (ae-missing-release-tag) "DomainEntityV1alpha1" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) interface DomainEntityV1alpha1 extends Entity { // (undocumented) @@ -137,18 +105,12 @@ interface DomainEntityV1alpha1 extends Entity { export { DomainEntityV1alpha1 as DomainEntity }; export { DomainEntityV1alpha1 }; -// Warning: (ae-missing-release-tag) "domainEntityV1alpha1Validator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export const domainEntityV1alpha1Validator: KindValidator; -// Warning: (ae-missing-release-tag) "EDIT_URL_ANNOTATION" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export const EDIT_URL_ANNOTATION = 'backstage.io/edit-url'; -// Warning: (ae-missing-release-tag) "Entity" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export type Entity = { apiVersion: string; @@ -159,13 +121,9 @@ export type Entity = { status?: UNSTABLE_EntityStatus; }; -// Warning: (ae-missing-release-tag) "ENTITY_DEFAULT_NAMESPACE" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export const ENTITY_DEFAULT_NAMESPACE = 'default'; -// Warning: (ae-missing-release-tag) "ENTITY_META_GENERATED_FIELDS" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export const ENTITY_META_GENERATED_FIELDS: readonly [ 'uid', @@ -173,8 +131,6 @@ export const ENTITY_META_GENERATED_FIELDS: readonly [ 'generation', ]; -// Warning: (ae-missing-release-tag) "EntityEnvelope" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export type EntityEnvelope = { apiVersion: string; @@ -185,35 +141,19 @@ export type EntityEnvelope = { }; }; -// Warning: (ae-missing-release-tag) "entityEnvelopeSchemaValidator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@backstage/catalog-model" does not have an export "TypeError" -// // @public export function entityEnvelopeSchemaValidator< T extends EntityEnvelope = EntityEnvelope, >(schema?: unknown): (data: unknown) => T; -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (ae-missing-release-tag) "entityHasChanges" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export function entityHasChanges(previous: Entity, next: Entity): boolean; -// Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@" -// Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag -// Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@" -// Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag -// Warning: (ae-missing-release-tag) "entityKindSchemaValidator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@backstage/catalog-model" does not have an export "TypeError" -// // @public export function entityKindSchemaValidator( schema: unknown, ): (data: unknown) => T | false; -// Warning: (ae-missing-release-tag) "EntityLink" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export type EntityLink = { url: string; @@ -221,8 +161,6 @@ export type EntityLink = { icon?: string; }; -// Warning: (ae-missing-release-tag) "EntityMeta" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export type EntityMeta = JsonObject & { uid?: string; @@ -238,8 +176,6 @@ export type EntityMeta = JsonObject & { links?: EntityLink[]; }; -// Warning: (ae-missing-release-tag) "EntityName" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export type EntityName = { kind: string; @@ -247,23 +183,17 @@ export type EntityName = { name: string; }; -// Warning: (ae-missing-release-tag) "EntityPolicies" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export const EntityPolicies: { - allOf(policies: EntityPolicy[]): AllEntityPolicies; - oneOf(policies: EntityPolicy[]): AnyEntityPolicy; + allOf(policies: EntityPolicy[]): EntityPolicy; + oneOf(policies: EntityPolicy[]): EntityPolicy; }; -// Warning: (ae-missing-release-tag) "EntityPolicy" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export type EntityPolicy = { enforce(entity: Entity): Promise; }; -// Warning: (ae-missing-release-tag) "EntityRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export type EntityRef = | string @@ -273,16 +203,18 @@ export type EntityRef = name: string; }; -// Warning: (ae-missing-release-tag) "EntityRelation" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// +// @public +export type EntityRefContext = { + defaultKind?: string; + defaultNamespace?: string; +}; + // @public export type EntityRelation = { type: string; target: EntityName; }; -// Warning: (ae-missing-release-tag) "EntityRelationSpec" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export type EntityRelationSpec = { source: EntityName; @@ -290,16 +222,11 @@ export type EntityRelationSpec = { target: EntityName; }; -// Warning: (ae-missing-release-tag) "entitySchemaValidator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@backstage/catalog-model" does not have an export "TypeError" -// // @public export function entitySchemaValidator( schema?: unknown, ): (data: unknown) => T; -// Warning: (ae-missing-release-tag) "FieldFormatEntityPolicy" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export class FieldFormatEntityPolicy implements EntityPolicy { constructor(validators?: Validators); @@ -307,40 +234,24 @@ export class FieldFormatEntityPolicy implements EntityPolicy { enforce(entity: Entity): Promise; } -// Warning: (ae-missing-release-tag) "generateEntityEtag" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export function generateEntityEtag(): string; -// Warning: (ae-missing-release-tag) "generateEntityUid" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export function generateEntityUid(): string; -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (ae-missing-release-tag) "generateUpdatedEntity" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export function generateUpdatedEntity(previous: Entity, next: Entity): Entity; -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (ae-missing-release-tag) "getEntityName" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export function getEntityName(entity: Entity): EntityName; -// Warning: (tsdoc-characters-after-block-tag) The token "@backstage" looks like a TSDoc tag but contains an invalid character "/"; if it is not a tag, use a backslash to escape the "@" -// Warning: (ae-missing-release-tag) "getEntitySourceLocation" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export function getEntitySourceLocation(entity: Entity): { type: string; target: string; }; -// Warning: (ae-missing-release-tag) "GroupEntityV1alpha1" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) interface GroupEntityV1alpha1 extends Entity { // (undocumented) @@ -363,28 +274,20 @@ interface GroupEntityV1alpha1 extends Entity { export { GroupEntityV1alpha1 as GroupEntity }; export { GroupEntityV1alpha1 }; -// Warning: (ae-missing-release-tag) "groupEntityV1alpha1Validator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export const groupEntityV1alpha1Validator: KindValidator; -// Warning: (ae-missing-release-tag) "JSONSchema" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type JSONSchema = JSONSchema7 & { [key in string]?: JsonValue; }; -// Warning: (ae-missing-release-tag) "KindValidator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export type KindValidator = { check(entity: Entity): Promise; }; -// Warning: (ae-missing-release-tag) "KubernetesValidatorFunctions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export class KubernetesValidatorFunctions { // (undocumented) @@ -405,21 +308,15 @@ export class KubernetesValidatorFunctions { static isValidObjectName(value: unknown): boolean; } -// 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) type Location_2 = { id: string; } & LocationSpec; export { Location_2 as Location }; -// Warning: (ae-missing-release-tag) "LOCATION_ANNOTATION" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export const LOCATION_ANNOTATION = 'backstage.io/managed-by-location'; -// Warning: (ae-missing-release-tag) "LocationEntityV1alpha1" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) interface LocationEntityV1alpha1 extends Entity { // (undocumented) @@ -436,19 +333,12 @@ interface LocationEntityV1alpha1 extends Entity { export { LocationEntityV1alpha1 as LocationEntity }; export { LocationEntityV1alpha1 }; -// Warning: (ae-missing-release-tag) "locationEntityV1alpha1Validator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export const locationEntityV1alpha1Validator: KindValidator; -// Warning: (tsdoc-missing-deprecation-message) The @deprecated block must include a deprecation message, e.g. describing the recommended alternative -// Warning: (ae-missing-release-tag) "locationSchema" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public @deprecated (undocumented) export const locationSchema: yup.ObjectSchema; -// Warning: (ae-missing-release-tag) "LocationSpec" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type LocationSpec = { type: string; @@ -456,19 +346,12 @@ export type LocationSpec = { presence?: 'optional' | 'required'; }; -// Warning: (tsdoc-missing-deprecation-message) The @deprecated block must include a deprecation message, e.g. describing the recommended alternative -// Warning: (ae-missing-release-tag) "locationSpecSchema" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public @deprecated (undocumented) export const locationSpecSchema: yup.ObjectSchema; -// Warning: (ae-missing-release-tag) "makeValidator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export function makeValidator(overrides?: Partial): Validators; -// Warning: (ae-missing-release-tag) "NoForeignRootFieldsEntityPolicy" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export class NoForeignRootFieldsEntityPolicy implements EntityPolicy { constructor(knownFields?: string[]); @@ -476,28 +359,16 @@ export class NoForeignRootFieldsEntityPolicy implements EntityPolicy { enforce(entity: Entity): Promise; } -// Warning: (ae-missing-release-tag) "ORIGIN_LOCATION_ANNOTATION" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export const ORIGIN_LOCATION_ANNOTATION = 'backstage.io/managed-by-origin-location'; -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (ae-missing-release-tag) "parseEntityName" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export function parseEntityName( ref: EntityRef, context?: EntityRefContext, ): EntityName; -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (ae-missing-release-tag) "parseEntityRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// Warning: (ae-missing-release-tag) "parseEntityRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// Warning: (ae-missing-release-tag) "parseEntityRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export function parseEntityRef( ref: EntityRef, @@ -535,89 +406,54 @@ export function parseEntityRef( name: string; }; -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag -// Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@" -// Warning: (ae-missing-release-tag) "parseLocationReference" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export function parseLocationReference(ref: string): { type: string; target: string; }; -// Warning: (ae-missing-release-tag) "RELATION_API_CONSUMED_BY" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export const RELATION_API_CONSUMED_BY = 'apiConsumedBy'; -// Warning: (ae-missing-release-tag) "RELATION_API_PROVIDED_BY" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export const RELATION_API_PROVIDED_BY = 'apiProvidedBy'; -// Warning: (ae-missing-release-tag) "RELATION_CHILD_OF" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export const RELATION_CHILD_OF = 'childOf'; -// Warning: (ae-missing-release-tag) "RELATION_CONSUMES_API" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export const RELATION_CONSUMES_API = 'consumesApi'; -// Warning: (ae-missing-release-tag) "RELATION_DEPENDENCY_OF" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export const RELATION_DEPENDENCY_OF = 'dependencyOf'; -// Warning: (ae-missing-release-tag) "RELATION_DEPENDS_ON" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export const RELATION_DEPENDS_ON = 'dependsOn'; -// Warning: (ae-missing-release-tag) "RELATION_HAS_MEMBER" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export const RELATION_HAS_MEMBER = 'hasMember'; -// Warning: (ae-missing-release-tag) "RELATION_HAS_PART" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export const RELATION_HAS_PART = 'hasPart'; -// Warning: (ae-missing-release-tag) "RELATION_MEMBER_OF" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export const RELATION_MEMBER_OF = 'memberOf'; -// Warning: (ae-missing-release-tag) "RELATION_OWNED_BY" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export const RELATION_OWNED_BY = 'ownedBy'; -// Warning: (ae-missing-release-tag) "RELATION_OWNER_OF" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export const RELATION_OWNER_OF = 'ownerOf'; -// Warning: (ae-missing-release-tag) "RELATION_PARENT_OF" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export const RELATION_PARENT_OF = 'parentOf'; -// Warning: (ae-missing-release-tag) "RELATION_PART_OF" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export const RELATION_PART_OF = 'partOf'; -// Warning: (ae-missing-release-tag) "RELATION_PROVIDES_API" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export const RELATION_PROVIDES_API = 'providesApi'; -// Warning: (ae-missing-release-tag) "ResourceEntityV1alpha1" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) interface ResourceEntityV1alpha1 extends Entity { // (undocumented) @@ -635,22 +471,15 @@ interface ResourceEntityV1alpha1 extends Entity { export { ResourceEntityV1alpha1 as ResourceEntity }; export { ResourceEntityV1alpha1 }; -// Warning: (ae-missing-release-tag) "resourceEntityV1alpha1Validator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export const resourceEntityV1alpha1Validator: KindValidator; -// Warning: (ae-missing-release-tag) "SchemaValidEntityPolicy" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export class SchemaValidEntityPolicy implements EntityPolicy { // (undocumented) enforce(entity: Entity): Promise; } -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (ae-missing-release-tag) "serializeEntityRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public @deprecated export function serializeEntityRef( ref: @@ -662,14 +491,9 @@ export function serializeEntityRef( }, ): EntityRef; -// Warning: (ae-missing-release-tag) "SOURCE_LOCATION_ANNOTATION" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export const SOURCE_LOCATION_ANNOTATION = 'backstage.io/source-location'; -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (ae-missing-release-tag) "stringifyEntityRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export function stringifyEntityRef( ref: @@ -681,19 +505,12 @@ export function stringifyEntityRef( }, ): string; -// Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag -// Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@" -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (ae-missing-release-tag) "stringifyLocationReference" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export function stringifyLocationReference(ref: { type: string; target: string; }): string; -// Warning: (ae-missing-release-tag) "SystemEntityV1alpha1" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) interface SystemEntityV1alpha1 extends Entity { // (undocumented) @@ -709,13 +526,9 @@ interface SystemEntityV1alpha1 extends Entity { export { SystemEntityV1alpha1 as SystemEntity }; export { SystemEntityV1alpha1 }; -// Warning: (ae-missing-release-tag) "systemEntityV1alpha1Validator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export const systemEntityV1alpha1Validator: KindValidator; -// Warning: (ae-missing-release-tag) "TemplateEntityV1beta2" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export interface TemplateEntityV1beta2 extends Entity { // (undocumented) @@ -740,8 +553,6 @@ export interface TemplateEntityV1beta2 extends Entity { }; } -// Warning: (ae-missing-release-tag) "templateEntityV1beta2Validator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export const templateEntityV1beta2Validator: KindValidator; @@ -761,8 +572,6 @@ export type UNSTABLE_EntityStatusItem = { // @alpha export type UNSTABLE_EntityStatusLevel = 'info' | 'warning' | 'error'; -// Warning: (ae-missing-release-tag) "UserEntityV1alpha1" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) interface UserEntityV1alpha1 extends Entity { // (undocumented) @@ -782,13 +591,9 @@ interface UserEntityV1alpha1 extends Entity { export { UserEntityV1alpha1 as UserEntity }; export { UserEntityV1alpha1 }; -// Warning: (ae-missing-release-tag) "userEntityV1alpha1Validator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export const userEntityV1alpha1Validator: KindValidator; -// Warning: (ae-missing-release-tag) "Validators" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type Validators = { isValidApiVersion(value: unknown): boolean; @@ -802,18 +607,12 @@ export type Validators = { isValidTag(value: unknown): boolean; }; -// Warning: (ae-missing-release-tag) "VIEW_URL_ANNOTATION" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export const VIEW_URL_ANNOTATION = 'backstage.io/view-url'; // Warnings were encountered during analysis: // -// src/EntityPolicies.d.ts:13:5 - (ae-forgotten-export) The symbol "AllEntityPolicies" needs to be exported by the entry point index.d.ts -// src/EntityPolicies.d.ts:14:5 - (ae-forgotten-export) The symbol "AnyEntityPolicy" needs to be exported by the entry point index.d.ts -// src/entity/Entity.d.ts:37:5 - (ae-incompatible-release-tags) The symbol "status" is marked as @public, but its signature references "UNSTABLE_EntityStatus" which is marked as @alpha -// src/entity/policies/types.d.ts:10:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/kinds/types.d.ts:9:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen +// src/entity/Entity.d.ts:38:5 - (ae-incompatible-release-tags) The symbol "status" is marked as @public, but its signature references "UNSTABLE_EntityStatus" which is marked as @alpha // (No @packageDocumentation comment for this package) ``` diff --git a/packages/catalog-model/src/EntityPolicies.ts b/packages/catalog-model/src/EntityPolicies.ts index eca5e4b77a..0fff68d569 100644 --- a/packages/catalog-model/src/EntityPolicies.ts +++ b/packages/catalog-model/src/EntityPolicies.ts @@ -52,11 +52,12 @@ class AnyEntityPolicy implements EntityPolicy { } } +/** @public */ export const EntityPolicies = { - allOf(policies: EntityPolicy[]) { + allOf(policies: EntityPolicy[]): EntityPolicy { return new AllEntityPolicies(policies); }, - oneOf(policies: EntityPolicy[]) { + oneOf(policies: EntityPolicy[]): EntityPolicy { return new AnyEntityPolicy(policies); }, }; diff --git a/packages/catalog-model/src/entity/Entity.ts b/packages/catalog-model/src/entity/Entity.ts index 681ac43b80..ca38fef183 100644 --- a/packages/catalog-model/src/entity/Entity.ts +++ b/packages/catalog-model/src/entity/Entity.ts @@ -21,6 +21,7 @@ import { UNSTABLE_EntityStatus } from './EntityStatus'; /** * The parts of the format that's common to all versions/kinds of entity. * + * @public * @see https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/ */ export type Entity = { @@ -62,6 +63,7 @@ export type Entity = { /** * Metadata fields common to all versions/kinds of entity. * + * @public * @see https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/#objectmeta-v1-meta * @see https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/ */ @@ -166,6 +168,8 @@ export type EntityMeta = JsonObject & { /** * A relation of a specific type to another entity in the catalog. + * + * @public */ export type EntityRelation = { /** @@ -181,6 +185,8 @@ export type EntityRelation = { /** * Holds the relation data for entities. + * + * @public */ export type EntityRelationSpec = { /** @@ -201,6 +207,8 @@ export type EntityRelationSpec = { /** * A link to external information that is related to the entity. + * + * @public */ export type EntityLink = { /** diff --git a/packages/catalog-model/src/entity/EntityEnvelope.ts b/packages/catalog-model/src/entity/EntityEnvelope.ts index ed21a7d666..290738f491 100644 --- a/packages/catalog-model/src/entity/EntityEnvelope.ts +++ b/packages/catalog-model/src/entity/EntityEnvelope.ts @@ -18,6 +18,7 @@ * The envelope skeleton parts of an entity - whatever is necessary to be able * to give it a ref and pass to further validation / policy checking. * + * @public * @see https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/ */ export type EntityEnvelope = { diff --git a/packages/catalog-model/src/entity/EntityStatus.ts b/packages/catalog-model/src/entity/EntityStatus.ts index 92e1d1454f..8f79fbd615 100644 --- a/packages/catalog-model/src/entity/EntityStatus.ts +++ b/packages/catalog-model/src/entity/EntityStatus.ts @@ -18,6 +18,7 @@ import { SerializedError } from '@backstage/errors'; /** * The current status of the entity, as claimed by various sources. + * * @alpha */ export type UNSTABLE_EntityStatus = { diff --git a/packages/catalog-model/src/entity/constants.ts b/packages/catalog-model/src/entity/constants.ts index d46d839720..ff031fc1ae 100644 --- a/packages/catalog-model/src/entity/constants.ts +++ b/packages/catalog-model/src/entity/constants.ts @@ -16,11 +16,15 @@ /** * The namespace that entities without an explicit namespace fall into. + * + * @public */ export const ENTITY_DEFAULT_NAMESPACE = 'default'; /** * The keys of EntityMeta that are auto-generated. + * + * @public */ export const ENTITY_META_GENERATED_FIELDS = [ 'uid', @@ -30,6 +34,9 @@ export const ENTITY_META_GENERATED_FIELDS = [ /** * Annotations for linking to entity from catalog pages. + * + * @public */ export const VIEW_URL_ANNOTATION = 'backstage.io/view-url'; +/** @public */ export const EDIT_URL_ANNOTATION = 'backstage.io/edit-url'; diff --git a/packages/catalog-model/src/entity/index.ts b/packages/catalog-model/src/entity/index.ts index d05045fc78..eac55ea325 100644 --- a/packages/catalog-model/src/entity/index.ts +++ b/packages/catalog-model/src/entity/index.ts @@ -42,6 +42,7 @@ export { serializeEntityRef, stringifyEntityRef, } from './ref'; +export type { EntityRefContext } from './ref'; export { entityHasChanges, generateEntityEtag, diff --git a/packages/catalog-model/src/entity/policies/DefaultNamespaceEntityPolicy.ts b/packages/catalog-model/src/entity/policies/DefaultNamespaceEntityPolicy.ts index 1750aece17..9511dfb05f 100644 --- a/packages/catalog-model/src/entity/policies/DefaultNamespaceEntityPolicy.ts +++ b/packages/catalog-model/src/entity/policies/DefaultNamespaceEntityPolicy.ts @@ -21,6 +21,8 @@ import { Entity } from '../Entity'; /** * Sets a default namespace if none was set. + * + * @public */ export class DefaultNamespaceEntityPolicy implements EntityPolicy { private readonly namespace: string; diff --git a/packages/catalog-model/src/entity/policies/FieldFormatEntityPolicy.ts b/packages/catalog-model/src/entity/policies/FieldFormatEntityPolicy.ts index ee95fd16ea..8655116ec6 100644 --- a/packages/catalog-model/src/entity/policies/FieldFormatEntityPolicy.ts +++ b/packages/catalog-model/src/entity/policies/FieldFormatEntityPolicy.ts @@ -29,6 +29,8 @@ import { Entity } from '../Entity'; * * This does not take into account machine generated fields such as uid, etag * and generation. + * + * @public */ export class FieldFormatEntityPolicy implements EntityPolicy { private readonly validators: Validators; diff --git a/packages/catalog-model/src/entity/policies/NoForeignRootFieldsEntityPolicy.ts b/packages/catalog-model/src/entity/policies/NoForeignRootFieldsEntityPolicy.ts index 6700a935d5..1c3f865434 100644 --- a/packages/catalog-model/src/entity/policies/NoForeignRootFieldsEntityPolicy.ts +++ b/packages/catalog-model/src/entity/policies/NoForeignRootFieldsEntityPolicy.ts @@ -21,6 +21,8 @@ const defaultKnownFields = ['apiVersion', 'kind', 'metadata', 'spec']; /** * Ensures that there are no foreign root fields in the entity. + * + * @public */ export class NoForeignRootFieldsEntityPolicy implements EntityPolicy { private readonly knownFields: string[]; diff --git a/packages/catalog-model/src/entity/policies/SchemaValidEntityPolicy.ts b/packages/catalog-model/src/entity/policies/SchemaValidEntityPolicy.ts index b5a4305a3c..721dc7d2dc 100644 --- a/packages/catalog-model/src/entity/policies/SchemaValidEntityPolicy.ts +++ b/packages/catalog-model/src/entity/policies/SchemaValidEntityPolicy.ts @@ -27,6 +27,8 @@ import { EntityPolicy } from './types'; * This should be the first policy in the list, to ensure that other downstream * policies can work with a structure that is at least valid in therms of the * typescript type. + * + * @public */ export class SchemaValidEntityPolicy implements EntityPolicy { private validate: ValidateFunction | undefined; diff --git a/packages/catalog-model/src/entity/policies/types.ts b/packages/catalog-model/src/entity/policies/types.ts index 6c7f47c332..ad0485e711 100644 --- a/packages/catalog-model/src/entity/policies/types.ts +++ b/packages/catalog-model/src/entity/policies/types.ts @@ -19,12 +19,14 @@ import type { Entity } from '../Entity'; /** * A policy for validation or mutation to be applied to entities as they are * entering the system. + * + * @public */ export type EntityPolicy = { /** * Applies validation or mutation on an entity. * - * @param entity The entity, as validated/mutated so far in the policy tree + * @param entity - The entity, as validated/mutated so far in the policy tree * @returns The incoming entity, or a mutated version of the same, or * undefined if this processor could not handle the entity * @throws An error if the entity should be rejected diff --git a/packages/catalog-model/src/entity/ref.ts b/packages/catalog-model/src/entity/ref.ts index e2d9c5b203..c1b9383eeb 100644 --- a/packages/catalog-model/src/entity/ref.ts +++ b/packages/catalog-model/src/entity/ref.ts @@ -41,7 +41,8 @@ function parseRefString(ref: string): { * Extracts the kind, namespace and name that form the name triplet of the * given entity. * - * @param entity An entity + * @public + * @param entity - An entity * @returns The complete entity name */ export function getEntityName(entity: Entity): EntityName { @@ -54,8 +55,10 @@ export function getEntityName(entity: Entity): EntityName { /** * The context of defaults that entity reference parsing happens within. + * + * @public */ -type EntityRefContext = { +export type EntityRefContext = { /** The default kind, if none is given in the reference */ defaultKind?: string; /** The default namespace, if none is given in the reference */ @@ -70,8 +73,9 @@ type EntityRefContext = { * otherwise specified as part of the options, and will throw an error if no * kind was specified in the input reference and no default kind was given. * - * @param ref The reference to parse - * @param context The context of defaults that the parsing happens within + * @public + * @param ref - The reference to parse + * @param context - The context of defaults that the parsing happens within * @returns A complete entity name */ export function parseEntityName( @@ -99,8 +103,9 @@ export function parseEntityName( * The options object can contain default values for the kind and namespace, * that will be used if the input reference did not specify any. * - * @param ref The reference to parse - * @param context The context of defaults that the parsing happens within + * @public + * @param ref - The reference to parse + * @param context - The context of defaults that the parsing happens within * @returns The compound form of the reference */ export function parseEntityRef( @@ -111,6 +116,7 @@ export function parseEntityRef( namespace: string; name: string; }; +/** @public */ export function parseEntityRef( ref: EntityRef, context?: { defaultKind: string }, @@ -119,6 +125,7 @@ export function parseEntityRef( namespace?: string; name: string; }; +/** @public */ export function parseEntityRef( ref: EntityRef, context?: { defaultNamespace: string }, @@ -170,8 +177,9 @@ export function parseEntityRef( * special/reserved characters, it outputs the string form, otherwise it * outputs the compound form. * + * @public * @deprecated Use `stringifyEntityRef` instead - * @param ref The reference to serialize + * @param ref - The reference to serialize * @returns The same reference on either string or compound form */ export function serializeEntityRef( @@ -219,7 +227,8 @@ export function serializeEntityRef( * all parts of the name to lowercase and inserts the default namespace if needed. * It is typically not the best way to represent the entity reference to the user. * - * @param ref The reference to serialize + * @public + * @param ref - The reference to serialize * @returns The same reference on either string or compound form */ export function stringifyEntityRef( @@ -248,9 +257,10 @@ export function stringifyEntityRef( * The comparison is case insensitive, and all of kind, namespace, and name * must match (after applying the optional context to the ref). * - * @param entity The entity to match - * @param ref A string or compound entity ref - * @param context An optional context of default kind and namespace, that apply + * @public + * @param entity - The entity to match + * @param ref - A string or compound entity ref + * @param context - An optional context of default kind and namespace, that apply * to the ref if given * @returns True if matching, false otherwise */ diff --git a/packages/catalog-model/src/entity/util.ts b/packages/catalog-model/src/entity/util.ts index 84b6845347..314f3b7737 100644 --- a/packages/catalog-model/src/entity/util.ts +++ b/packages/catalog-model/src/entity/util.ts @@ -21,6 +21,7 @@ import { Entity } from './Entity'; /** * Generates a new random UID for an entity. * + * @public * @returns A string with enough randomness to uniquely identify an entity */ export function generateEntityUid(): string { @@ -30,6 +31,7 @@ export function generateEntityUid(): string { /** * Generates a new random Etag for an entity. * + * @public * @returns A string with enough randomness to uniquely identify an entity * revision */ @@ -48,8 +50,9 @@ export function generateEntityEtag(): string { * account. It only compares the actual input entity data, i.e. metadata and * spec. * - * @param previous The old state of the entity - * @param next The new state of the entity + * @public + * @param previous - The old state of the entity + * @param next - The new state of the entity */ export function entityHasChanges(previous: Entity, next: Entity): boolean { const e1 = lodash.cloneDeep(previous); @@ -98,8 +101,9 @@ export function entityHasChanges(previous: Entity, next: Entity): boolean { * The previous revision is expected to be a complete model loaded from the * catalog, including the uid, etag and generation fields. * - * @param previous The old state of the entity - * @param next The new state of the entity + * @public + * @param previous - The old state of the entity + * @param next - The new state of the entity * @returns An entity with the merged state of both */ export function generateUpdatedEntity(previous: Entity, next: Entity): Entity { diff --git a/packages/catalog-model/src/kinds/ApiEntityV1alpha1.ts b/packages/catalog-model/src/kinds/ApiEntityV1alpha1.ts index 2bcd9c7040..310b6695eb 100644 --- a/packages/catalog-model/src/kinds/ApiEntityV1alpha1.ts +++ b/packages/catalog-model/src/kinds/ApiEntityV1alpha1.ts @@ -18,6 +18,7 @@ import type { Entity } from '../entity/Entity'; import schema from '../schema/kinds/API.v1alpha1.schema.json'; import { ajvCompiledJsonSchemaValidator } from './util'; +/** @public */ export interface ApiEntityV1alpha1 extends Entity { apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1'; kind: 'API'; @@ -30,5 +31,6 @@ export interface ApiEntityV1alpha1 extends Entity { }; } +/** @public */ export const apiEntityV1alpha1Validator = ajvCompiledJsonSchemaValidator(schema); diff --git a/packages/catalog-model/src/kinds/ComponentEntityV1alpha1.ts b/packages/catalog-model/src/kinds/ComponentEntityV1alpha1.ts index 5312d87a35..6777778409 100644 --- a/packages/catalog-model/src/kinds/ComponentEntityV1alpha1.ts +++ b/packages/catalog-model/src/kinds/ComponentEntityV1alpha1.ts @@ -18,6 +18,7 @@ import type { Entity } from '../entity/Entity'; import schema from '../schema/kinds/Component.v1alpha1.schema.json'; import { ajvCompiledJsonSchemaValidator } from './util'; +/** @public */ export interface ComponentEntityV1alpha1 extends Entity { apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1'; kind: 'Component'; @@ -33,5 +34,6 @@ export interface ComponentEntityV1alpha1 extends Entity { }; } +/** @public */ export const componentEntityV1alpha1Validator = ajvCompiledJsonSchemaValidator(schema); diff --git a/packages/catalog-model/src/kinds/DomainEntityV1alpha1.ts b/packages/catalog-model/src/kinds/DomainEntityV1alpha1.ts index c832f35ee0..fe777af24e 100644 --- a/packages/catalog-model/src/kinds/DomainEntityV1alpha1.ts +++ b/packages/catalog-model/src/kinds/DomainEntityV1alpha1.ts @@ -18,6 +18,7 @@ import type { Entity } from '../entity/Entity'; import schema from '../schema/kinds/Domain.v1alpha1.schema.json'; import { ajvCompiledJsonSchemaValidator } from './util'; +/** @public */ export interface DomainEntityV1alpha1 extends Entity { apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1'; kind: 'Domain'; @@ -26,5 +27,6 @@ export interface DomainEntityV1alpha1 extends Entity { }; } +/** @public */ export const domainEntityV1alpha1Validator = ajvCompiledJsonSchemaValidator(schema); diff --git a/packages/catalog-model/src/kinds/GroupEntityV1alpha1.ts b/packages/catalog-model/src/kinds/GroupEntityV1alpha1.ts index 263ba311ad..f6aab856f0 100644 --- a/packages/catalog-model/src/kinds/GroupEntityV1alpha1.ts +++ b/packages/catalog-model/src/kinds/GroupEntityV1alpha1.ts @@ -18,6 +18,7 @@ import type { Entity } from '../entity/Entity'; import schema from '../schema/kinds/Group.v1alpha1.schema.json'; import { ajvCompiledJsonSchemaValidator } from './util'; +/** @public */ export interface GroupEntityV1alpha1 extends Entity { apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1'; kind: 'Group'; @@ -34,5 +35,6 @@ export interface GroupEntityV1alpha1 extends Entity { }; } +/** @public */ export const groupEntityV1alpha1Validator = ajvCompiledJsonSchemaValidator(schema); diff --git a/packages/catalog-model/src/kinds/LocationEntityV1alpha1.ts b/packages/catalog-model/src/kinds/LocationEntityV1alpha1.ts index 44f04b2c39..f2ae4bcc91 100644 --- a/packages/catalog-model/src/kinds/LocationEntityV1alpha1.ts +++ b/packages/catalog-model/src/kinds/LocationEntityV1alpha1.ts @@ -18,6 +18,7 @@ import type { Entity } from '../entity/Entity'; import schema from '../schema/kinds/Location.v1alpha1.schema.json'; import { ajvCompiledJsonSchemaValidator } from './util'; +/** @public */ export interface LocationEntityV1alpha1 extends Entity { apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1'; kind: 'Location'; @@ -28,5 +29,6 @@ export interface LocationEntityV1alpha1 extends Entity { }; } +/** @public */ export const locationEntityV1alpha1Validator = ajvCompiledJsonSchemaValidator(schema); diff --git a/packages/catalog-model/src/kinds/ResourceEntityV1alpha1.ts b/packages/catalog-model/src/kinds/ResourceEntityV1alpha1.ts index 211164f4c1..acc6ab5245 100644 --- a/packages/catalog-model/src/kinds/ResourceEntityV1alpha1.ts +++ b/packages/catalog-model/src/kinds/ResourceEntityV1alpha1.ts @@ -18,6 +18,7 @@ import type { Entity } from '../entity/Entity'; import schema from '../schema/kinds/Resource.v1alpha1.schema.json'; import { ajvCompiledJsonSchemaValidator } from './util'; +/** @public */ export interface ResourceEntityV1alpha1 extends Entity { apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1'; kind: 'Resource'; @@ -29,5 +30,6 @@ export interface ResourceEntityV1alpha1 extends Entity { }; } +/** @public */ export const resourceEntityV1alpha1Validator = ajvCompiledJsonSchemaValidator(schema); diff --git a/packages/catalog-model/src/kinds/SystemEntityV1alpha1.ts b/packages/catalog-model/src/kinds/SystemEntityV1alpha1.ts index 129e3fea50..5f90351480 100644 --- a/packages/catalog-model/src/kinds/SystemEntityV1alpha1.ts +++ b/packages/catalog-model/src/kinds/SystemEntityV1alpha1.ts @@ -18,6 +18,7 @@ import type { Entity } from '../entity/Entity'; import schema from '../schema/kinds/System.v1alpha1.schema.json'; import { ajvCompiledJsonSchemaValidator } from './util'; +/** @public */ export interface SystemEntityV1alpha1 extends Entity { apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1'; kind: 'System'; @@ -27,5 +28,6 @@ export interface SystemEntityV1alpha1 extends Entity { }; } +/** @public */ export const systemEntityV1alpha1Validator = ajvCompiledJsonSchemaValidator(schema); diff --git a/packages/catalog-model/src/kinds/TemplateEntityV1beta2.ts b/packages/catalog-model/src/kinds/TemplateEntityV1beta2.ts index 1d7aa2162c..e708d4b387 100644 --- a/packages/catalog-model/src/kinds/TemplateEntityV1beta2.ts +++ b/packages/catalog-model/src/kinds/TemplateEntityV1beta2.ts @@ -19,6 +19,7 @@ import type { Entity } from '../entity/Entity'; import schema from '../schema/kinds/Template.v1beta2.schema.json'; import { ajvCompiledJsonSchemaValidator } from './util'; +/** @public */ export interface TemplateEntityV1beta2 extends Entity { apiVersion: 'backstage.io/v1beta2'; kind: 'Template'; @@ -37,5 +38,6 @@ export interface TemplateEntityV1beta2 extends Entity { }; } +/** @public */ export const templateEntityV1beta2Validator = ajvCompiledJsonSchemaValidator(schema); diff --git a/packages/catalog-model/src/kinds/UserEntityV1alpha1.ts b/packages/catalog-model/src/kinds/UserEntityV1alpha1.ts index 65ebdb3262..d719ab35ef 100644 --- a/packages/catalog-model/src/kinds/UserEntityV1alpha1.ts +++ b/packages/catalog-model/src/kinds/UserEntityV1alpha1.ts @@ -18,6 +18,7 @@ import type { Entity } from '../entity/Entity'; import schema from '../schema/kinds/User.v1alpha1.schema.json'; import { ajvCompiledJsonSchemaValidator } from './util'; +/** @public */ export interface UserEntityV1alpha1 extends Entity { apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1'; kind: 'User'; @@ -31,5 +32,6 @@ export interface UserEntityV1alpha1 extends Entity { }; } +/** @public */ export const userEntityV1alpha1Validator = ajvCompiledJsonSchemaValidator(schema); diff --git a/packages/catalog-model/src/kinds/relations.ts b/packages/catalog-model/src/kinds/relations.ts index 57977e7168..7546d1508b 100644 --- a/packages/catalog-model/src/kinds/relations.ts +++ b/packages/catalog-model/src/kinds/relations.ts @@ -25,40 +25,60 @@ Naming rules for relations in priority order: /** * An ownership relation where the owner is usually an organizational * entity (user or group), and the other entity can be anything. + * + * @public */ export const RELATION_OWNED_BY = 'ownedBy'; +/** @public */ export const RELATION_OWNER_OF = 'ownerOf'; /** * A relation with an API entity, typically from a component + * + * @public */ export const RELATION_CONSUMES_API = 'consumesApi'; +/** @public */ export const RELATION_API_CONSUMED_BY = 'apiConsumedBy'; +/** @public */ export const RELATION_PROVIDES_API = 'providesApi'; +/** @public */ export const RELATION_API_PROVIDED_BY = 'apiProvidedBy'; /** * A relation denoting a dependency on another entity. + * + * @public */ export const RELATION_DEPENDS_ON = 'dependsOn'; +/** @public */ export const RELATION_DEPENDENCY_OF = 'dependencyOf'; /** * A parent/child relation to build up a tree, used for example to describe * the organizational structure between groups. + * + * @public */ export const RELATION_PARENT_OF = 'parentOf'; +/** @public */ export const RELATION_CHILD_OF = 'childOf'; /** * A membership relation, typically for users in a group. + * + * @public */ export const RELATION_MEMBER_OF = 'memberOf'; +/** @public */ export const RELATION_HAS_MEMBER = 'hasMember'; /** * A part/whole relation, typically for components in a system and systems * in a domain. + * + * @public */ export const RELATION_PART_OF = 'partOf'; +/** @public */ export const RELATION_HAS_PART = 'hasPart'; diff --git a/packages/catalog-model/src/kinds/types.ts b/packages/catalog-model/src/kinds/types.ts index 0ec0d313bb..f4bc151384 100644 --- a/packages/catalog-model/src/kinds/types.ts +++ b/packages/catalog-model/src/kinds/types.ts @@ -18,12 +18,14 @@ import { Entity } from '../entity'; /** * Validates entities of a certain kind. + * + * @public */ export type KindValidator = { /** * Validates the entity as a known entity kind. * - * @param entity The entity to validate + * @param entity - The entity to validate * @returns Resolves to true, if the entity was of a kind that was known and * handled by this validator, and was found to be valid. Resolves to false, * if the entity was not of a kind that was known by this validator. diff --git a/packages/catalog-model/src/location/annotation.ts b/packages/catalog-model/src/location/annotation.ts index 137d36a0da..4bcabdb705 100644 --- a/packages/catalog-model/src/location/annotation.ts +++ b/packages/catalog-model/src/location/annotation.ts @@ -14,8 +14,11 @@ * limitations under the License. */ +/** @public */ export const LOCATION_ANNOTATION = 'backstage.io/managed-by-location'; +/** @public */ export const ORIGIN_LOCATION_ANNOTATION = 'backstage.io/managed-by-origin-location'; +/** @public */ export const SOURCE_LOCATION_ANNOTATION = 'backstage.io/source-location'; diff --git a/packages/catalog-model/src/location/helpers.ts b/packages/catalog-model/src/location/helpers.ts index 91209e7a2a..cf12031dc1 100644 --- a/packages/catalog-model/src/location/helpers.ts +++ b/packages/catalog-model/src/location/helpers.ts @@ -23,8 +23,9 @@ import { LOCATION_ANNOTATION, SOURCE_LOCATION_ANNOTATION } from './annotation'; * Note that the return type is not `LocationSpec`, because we do not want to * conflate the string form with the additional properties of that type. * - * @param ref A string-form location reference, e.g. 'url:https://host' - * @returns A location reference, e.g. { type: 'url', target: 'https://host' } + * @public + * @param ref - A string-form location reference, e.g. `'url:https://host'` + * @returns A location reference, e.g. `{ type: 'url', target: 'https://host' }` */ export function parseLocationReference(ref: string): { type: string; @@ -67,8 +68,9 @@ export function parseLocationReference(ref: string): { * Note that the input type is not `LocationSpec`, because we do not want to * conflate the string form with the additional properties of that type. * - * @param ref A location reference, e.g. { type: 'url', target: 'https://host' } - * @returns A string-form location reference, e.g. 'url:https://host' + * @public + * @param ref - A location reference, e.g. `{ type: 'url', target: 'https://host' }` + * @returns A string-form location reference, e.g. `'url:https://host'` */ export function stringifyLocationReference(ref: { type: string; @@ -89,8 +91,10 @@ export function stringifyLocationReference(ref: { * Returns the source code location of the Entity, to the extent that one exists. * * If the returned location type is of type 'url', the target should be readable at least - * using the UrlReader from @backstage/backend-common. If it is not of type 'url', the caller + * using the UrlReader from `@backstage/backend-common`. If it is not of type 'url', the caller * needs to have explicit handling of each location type or signal that it is not supported. + * + * @public */ export function getEntitySourceLocation(entity: Entity): { type: string; diff --git a/packages/catalog-model/src/location/types.ts b/packages/catalog-model/src/location/types.ts index 9837ce384d..1d16a9047d 100644 --- a/packages/catalog-model/src/location/types.ts +++ b/packages/catalog-model/src/location/types.ts @@ -14,6 +14,7 @@ * limitations under the License. */ +/** @public */ export type LocationSpec = { type: string; target: string; @@ -23,6 +24,7 @@ export type LocationSpec = { presence?: 'optional' | 'required'; }; +/** @public */ export type Location = { id: string; } & LocationSpec; diff --git a/packages/catalog-model/src/location/validation.ts b/packages/catalog-model/src/location/validation.ts index 4857fc76bc..f6680d6eee 100644 --- a/packages/catalog-model/src/location/validation.ts +++ b/packages/catalog-model/src/location/validation.ts @@ -17,7 +17,10 @@ import * as yup from 'yup'; import { LocationSpec, Location } from './types'; -/** @deprecated */ +/** + * @public + * @deprecated Use JSONSchema or validators instead. + */ export const locationSpecSchema = yup .object({ type: yup.string().required(), @@ -27,7 +30,10 @@ export const locationSpecSchema = yup .noUnknown() .required(); -/** @deprecated */ +/** + * @public + * @deprecated Use JSONSchema or validators instead. + */ export const locationSchema = yup .object({ id: yup.string().required(), @@ -37,7 +43,10 @@ export const locationSchema = yup .noUnknown() .required(); -/** @deprecated */ +/** + * @public + * @deprecated Use JSONSchema or validators instead. + */ export const analyzeLocationSchema = yup .object<{ location: LocationSpec }>({ location: locationSpecSchema, diff --git a/packages/catalog-model/src/types.ts b/packages/catalog-model/src/types.ts index 50de5a1cea..1fbb3be95c 100644 --- a/packages/catalog-model/src/types.ts +++ b/packages/catalog-model/src/types.ts @@ -17,10 +17,13 @@ import { JsonValue } from '@backstage/config'; import { JSONSchema7 } from 'json-schema'; +/** @public */ export type JSONSchema = JSONSchema7 & { [key in string]?: JsonValue }; /** * A complete entity name, with the full kind-namespace-name triplet. + * + * @public */ export type EntityName = { kind: string; @@ -36,6 +39,8 @@ export type EntityName = { * * Left-out parts of the reference need to be handled by the application, * either by rejecting the reference or by falling back to default values. + * + * @public */ export type EntityRef = | string diff --git a/packages/catalog-model/src/validation/CommonValidatorFunctions.ts b/packages/catalog-model/src/validation/CommonValidatorFunctions.ts index 7c9736baf7..5fcd2ee755 100644 --- a/packages/catalog-model/src/validation/CommonValidatorFunctions.ts +++ b/packages/catalog-model/src/validation/CommonValidatorFunctions.ts @@ -19,16 +19,18 @@ import lodash from 'lodash'; /** * Contains various helper validation and normalization functions that can be * composed to form a Validator. + * + * @public */ export class CommonValidatorFunctions { /** * Checks that the value is on the form or , and validates * those parts separately. * - * @param value The value to check - * @param separator The separator between parts - * @param isValidPrefix Checks that the part before the separator is valid, if present - * @param isValidSuffix Checks that the part after the separator (or the entire value if there is no separator) is valid + * @param value - The value to check + * @param separator - The separator between parts + * @param isValidPrefix - Checks that the part before the separator is valid, if present + * @param isValidSuffix - Checks that the part after the separator (or the entire value if there is no separator) is valid */ static isValidPrefixAndOrSuffix( value: unknown, @@ -53,7 +55,7 @@ export class CommonValidatorFunctions { /** * Checks that the value can be safely transferred as JSON. * - * @param value The value to check + * @param value - The value to check */ static isJsonSafe(value: unknown): boolean { try { @@ -66,7 +68,7 @@ export class CommonValidatorFunctions { /** * Checks that the value is a valid DNS subdomain name. * - * @param value The value to check + * @param value - The value to check * @see https://tools.ietf.org/html/rfc1123 */ static isValidDnsSubdomain(value: unknown): boolean { @@ -81,7 +83,7 @@ export class CommonValidatorFunctions { /** * Checks that the value is a valid DNS label. * - * @param value The value to check + * @param value - The value to check * @see https://tools.ietf.org/html/rfc1123 */ static isValidDnsLabel(value: unknown): boolean { @@ -96,7 +98,7 @@ export class CommonValidatorFunctions { /** * Checks that the value is a valid URL. * - * @param value The value to check + * @param value - The value to check */ static isValidUrl(value: unknown): boolean { if (typeof value !== 'string') { @@ -115,7 +117,7 @@ export class CommonValidatorFunctions { /** * Checks that the value is a non empty string value. * - * @param value The value to check + * @param value - The value to check */ static isValidString(value: unknown): boolean { return typeof value === 'string' && value?.trim()?.length >= 1; diff --git a/packages/catalog-model/src/validation/KubernetesValidatorFunctions.ts b/packages/catalog-model/src/validation/KubernetesValidatorFunctions.ts index 86d27e7b13..2423c47bef 100644 --- a/packages/catalog-model/src/validation/KubernetesValidatorFunctions.ts +++ b/packages/catalog-model/src/validation/KubernetesValidatorFunctions.ts @@ -20,6 +20,7 @@ import { CommonValidatorFunctions } from './CommonValidatorFunctions'; * Contains validation functions that match the Kubernetes spec, usable to * build a catalog that is compatible with those rule sets. * + * @public * @see https://kubernetes.io/docs/concepts/overview/working-with-objects/names/ * @see https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set * @see https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/#syntax-and-character-set diff --git a/packages/catalog-model/src/validation/entityEnvelopeSchemaValidator.ts b/packages/catalog-model/src/validation/entityEnvelopeSchemaValidator.ts index aa865bcf1c..daa44ffaf1 100644 --- a/packages/catalog-model/src/validation/entityEnvelopeSchemaValidator.ts +++ b/packages/catalog-model/src/validation/entityEnvelopeSchemaValidator.ts @@ -22,7 +22,7 @@ import { compileAjvSchema, throwAjvError } from './ajv'; /** * Creates a validation function that takes some arbitrary data, and either * returns that data cast to an {@link EntityEnvelope} (or the given subtype) - * if it matches that schema, or throws a {@link TypeError} describing the + * if it matches that schema, or throws a {@link globals#TypeError} describing the * errors. * * Note that this validator is only meant for applying the base schema checks; @@ -38,6 +38,7 @@ import { compileAjvSchema, throwAjvError } from './ajv'; * - EntityMeta * - common# * + * @public * @see https://github.com/backstage/backstage/tree/master/packages/catalog-model/src/schema */ export function entityEnvelopeSchemaValidator< diff --git a/packages/catalog-model/src/validation/entityKindSchemaValidator.ts b/packages/catalog-model/src/validation/entityKindSchemaValidator.ts index a295fac205..535dba9842 100644 --- a/packages/catalog-model/src/validation/entityKindSchemaValidator.ts +++ b/packages/catalog-model/src/validation/entityKindSchemaValidator.ts @@ -22,20 +22,20 @@ import { compileAjvSchema, throwAjvError } from './ajv'; * Creates a validation function that takes some arbitrary data, and either * returns that data cast to a `T` if it matches that schema, or `false` if the * schema apiVersion/kind didn't apply to that data, or throws a - * {@link TypeError} describing actual errors. + * {@link globals#TypeError} describing actual errors. * * This validator is highly specialized, in that it has special treatment of * the `kind` and `apiVersion` root keys. This only works if your schema has * their rule set to `"enum"`: * - * 
- *   "apiVersion": {
- *      "enum": ["backstage.io/v1alpha1", "backstage.io/v1beta1"]
- *   },
- *   "kind": {
- *     "enum": ["Group"]
- *   },
- *
+ * ``` + * "apiVersion": { + * "enum": ["backstage.io/v1alpha1", "backstage.io/v1beta1"] + * }, + * "kind": { + * "enum": ["Group"] + * }, + * ``` * * In the above example, the created validator will return `false` if and only * if the kind and/or apiVersion mismatch. @@ -52,6 +52,7 @@ import { compileAjvSchema, throwAjvError } from './ajv'; * - EntityMeta * - common# * + * @public * @see https://github.com/backstage/backstage/tree/master/packages/catalog-model/src/schema */ export function entityKindSchemaValidator( diff --git a/packages/catalog-model/src/validation/entitySchemaValidator.ts b/packages/catalog-model/src/validation/entitySchemaValidator.ts index 8683ab6de6..dd110efd75 100644 --- a/packages/catalog-model/src/validation/entitySchemaValidator.ts +++ b/packages/catalog-model/src/validation/entitySchemaValidator.ts @@ -22,7 +22,7 @@ import { compileAjvSchema, throwAjvError } from './ajv'; /** * Creates a validation function that takes some arbitrary data, and either * returns that data cast to an {@link Entity} (or the given subtype) if it - * matches that schema, or throws a {@link TypeError} describing the errors. + * matches that schema, or throws a {@link globals#TypeError} describing the errors. * * Note that this validator is only meant for applying the base schema checks; * it does not take custom policies or additional processor based validation @@ -37,6 +37,7 @@ import { compileAjvSchema, throwAjvError } from './ajv'; * - EntityMeta * - common# * + * @public * @see https://github.com/backstage/backstage/tree/master/packages/catalog-model/src/schema */ export function entitySchemaValidator( diff --git a/packages/catalog-model/src/validation/makeValidator.ts b/packages/catalog-model/src/validation/makeValidator.ts index 0ddd9d1088..48eff566f2 100644 --- a/packages/catalog-model/src/validation/makeValidator.ts +++ b/packages/catalog-model/src/validation/makeValidator.ts @@ -30,6 +30,7 @@ const defaultValidators: Validators = { isValidTag: CommonValidatorFunctions.isValidDnsLabel, }; +/** @public */ export function makeValidator(overrides: Partial = {}): Validators { return { ...defaultValidators, diff --git a/packages/catalog-model/src/validation/types.ts b/packages/catalog-model/src/validation/types.ts index cfa9d845bc..23d639c166 100644 --- a/packages/catalog-model/src/validation/types.ts +++ b/packages/catalog-model/src/validation/types.ts @@ -14,6 +14,7 @@ * limitations under the License. */ +/** @public */ export type Validators = { isValidApiVersion(value: unknown): boolean; isValidKind(value: unknown): boolean;