diff --git a/.changeset/modern-windows-brush.md b/.changeset/modern-windows-brush.md new file mode 100644 index 0000000000..49c45eb41e --- /dev/null +++ b/.changeset/modern-windows-brush.md @@ -0,0 +1,9 @@ +--- +'@backstage/catalog-model': minor +--- + +**BREAKING**: + +- Removed the previously deprecated type `EntityRef`. Please use `string` for stringified entity refs, `CompoundEntityRef` for compound kind-namespace-name triplet objects, or custom objects like `{ kind?: string; namespace?: string; name: string }` and similar if you have need for partial types. +- Removed the previously deprecated type `LocationSpec` type, which has been moved to `@backstage/plugin-catalog-backend`. +- Removed the previously deprecated function `parseEntityName`. Please use `parseEntityRef` instead. diff --git a/packages/catalog-model/api-report.md b/packages/catalog-model/api-report.md index 9a65401d55..90242f9293 100644 --- a/packages/catalog-model/api-report.md +++ b/packages/catalog-model/api-report.md @@ -190,15 +190,6 @@ export type EntityPolicy = { enforce(entity: Entity): Promise; }; -// @public @deprecated -export type EntityRef = - | string - | { - kind?: string; - namespace?: string; - name: string; - }; - // @public export type EntityRelation = { type: string; @@ -316,13 +307,6 @@ export { LocationEntityV1alpha1 }; // @public export const locationEntityV1alpha1Validator: KindValidator; -// @public @deprecated -export type LocationSpec = { - type: string; - target: string; - presence?: 'optional' | 'required'; -}; - // @public export function makeValidator(overrides?: Partial): Validators; @@ -333,21 +317,6 @@ export class NoForeignRootFieldsEntityPolicy implements EntityPolicy { enforce(entity: Entity): Promise; } -// @public @deprecated -export function parseEntityName( - ref: - | string - | { - kind?: string; - namespace?: string; - name: string; - }, - context?: { - defaultKind?: string; - defaultNamespace?: string; - }, -): CompoundEntityRef; - // @public export function parseEntityRef( ref: diff --git a/packages/catalog-model/src/entity/index.ts b/packages/catalog-model/src/entity/index.ts index fb9eee0353..f46f53945f 100644 --- a/packages/catalog-model/src/entity/index.ts +++ b/packages/catalog-model/src/entity/index.ts @@ -36,7 +36,6 @@ export * from './policies'; export { getCompoundEntityRef, getEntityName, - parseEntityName, parseEntityRef, stringifyEntityRef, } from './ref'; diff --git a/packages/catalog-model/src/entity/ref.test.ts b/packages/catalog-model/src/entity/ref.test.ts index 045c4710dc..6cb7612439 100644 --- a/packages/catalog-model/src/entity/ref.test.ts +++ b/packages/catalog-model/src/entity/ref.test.ts @@ -14,171 +14,9 @@ * limitations under the License. */ -import { DEFAULT_NAMESPACE } from './constants'; -import { parseEntityName, parseEntityRef } from './ref'; +import { parseEntityRef } from './ref'; describe('ref', () => { - describe('parseEntityName', () => { - it('handles some omissions', () => { - expect(parseEntityName('a:b/c')).toEqual({ - kind: 'a', - namespace: 'b', - name: 'c', - }); - expect(() => parseEntityName('b/c')).toThrow(/kind/); - expect(parseEntityName('a:c')).toEqual({ - kind: 'a', - namespace: DEFAULT_NAMESPACE, - name: 'c', - }); - expect(() => parseEntityName('c')).toThrow(/kind/); - }); - - it('rejects bad inputs', () => { - expect(() => parseEntityName(null as any)).toThrow(); - expect(() => parseEntityName(7 as any)).toThrow(); - expect(() => parseEntityName('a:b:c')).toThrow(); - expect(() => parseEntityName('a/b/c')).toThrow(); - expect(() => parseEntityName('a/b:c')).toThrow(); - expect(() => parseEntityName('a:b/c/d')).toThrow(); - expect(() => parseEntityName('a:b/c:d')).toThrow(); - }); - - it('rejects empty parts in strings', () => { - // one is empty - expect(() => parseEntityName(':b/c')).toThrow(); - expect(() => parseEntityName('a:/c')).toThrow(); - expect(() => parseEntityName('a:b/')).toThrow(); - // two are empty - expect(() => parseEntityName('a:/')).toThrow(); - expect(() => parseEntityName(':b/')).toThrow(); - expect(() => parseEntityName(':/c')).toThrow(); - // three are empty - expect(() => parseEntityName(':/')).toThrow(); - // one is left out, one empty - expect(() => parseEntityName('/c')).toThrow(); - expect(() => parseEntityName('b/')).toThrow(); - expect(() => parseEntityName(':c')).toThrow(); - expect(() => parseEntityName('a:')).toThrow(); - // nothing at all - expect(() => parseEntityName('')).toThrow(); - }); - - it('rejects empty parts in compounds', () => { - // one is empty - expect(() => - parseEntityName({ kind: '', namespace: 'b', name: 'c' }), - ).toThrow(); - expect(() => parseEntityName({ namespace: 'b', name: 'c' })).toThrow(); - expect(() => - parseEntityName({ kind: 'a', namespace: '', name: 'c' }), - ).toThrow(); - expect(() => parseEntityName({ kind: 'a', name: 'c' })).not.toThrow(); - expect(() => - parseEntityName({ kind: 'a', namespace: 'b', name: '' }), - ).toThrow(); - expect(() => - parseEntityName({ kind: 'a', namespace: 'b' } as any), - ).toThrow(); - // two are empty - expect(() => - parseEntityName({ kind: '', namespace: '', name: 'c' }), - ).toThrow(); - expect(() => parseEntityName({ name: 'c' })).toThrow(); - expect(() => - parseEntityName({ kind: '', namespace: 'b', name: '' }), - ).toThrow(); - expect(() => parseEntityName({ namespace: 'b' } as any)).toThrow(); - expect(() => - parseEntityName({ kind: 'a', namespace: '', name: '' }), - ).toThrow(); - expect(() => parseEntityName({ kind: 'a' } as any)).toThrow(); - // three are empty - expect(() => - parseEntityName({ kind: '', namespace: '', name: '' }), - ).toThrow(); - expect(() => parseEntityName({} as any)).toThrow(); - // one is left out, one empty - expect(() => parseEntityName({ namespace: '', name: 'c' })).toThrow(); - expect(() => parseEntityName({ namespace: 'b', name: '' })).toThrow(); - expect(() => parseEntityName({ kind: '', name: 'c' })).toThrow(); - expect(() => parseEntityName({ kind: 'a', name: '' })).toThrow(); - }); - - it('adds defaults where necessary to strings', () => { - expect( - parseEntityName('a:b/c', { defaultKind: 'x', defaultNamespace: 'y' }), - ).toEqual({ kind: 'a', namespace: 'b', name: 'c' }); - expect( - parseEntityName('b/c', { defaultKind: 'x', defaultNamespace: 'y' }), - ).toEqual({ kind: 'x', namespace: 'b', name: 'c' }); - expect( - parseEntityName('a:c', { defaultKind: 'x', defaultNamespace: 'y' }), - ).toEqual({ kind: 'a', namespace: 'y', name: 'c' }); - expect(parseEntityName('a:c', { defaultKind: 'x' })).toEqual({ - kind: 'a', - namespace: DEFAULT_NAMESPACE, - name: 'c', - }); - expect( - parseEntityName('c', { defaultKind: 'x', defaultNamespace: 'y' }), - ).toEqual({ kind: 'x', namespace: 'y', name: 'c' }); - expect(parseEntityName('c', { defaultKind: 'x' })).toEqual({ - kind: 'x', - namespace: DEFAULT_NAMESPACE, - name: 'c', - }); - }); - - it('adds defaults where necessary to compounds', () => { - expect( - parseEntityName( - { kind: 'a', namespace: 'b', name: 'c' }, - { defaultKind: 'x', defaultNamespace: 'y' }, - ), - ).toEqual({ kind: 'a', namespace: 'b', name: 'c' }); - expect( - parseEntityName( - { namespace: 'b', name: 'c' }, - { defaultKind: 'x', defaultNamespace: 'y' }, - ), - ).toEqual({ kind: 'x', namespace: 'b', name: 'c' }); - expect( - parseEntityName( - { kind: 'a', name: 'c' }, - { defaultKind: 'x', defaultNamespace: 'y' }, - ), - ).toEqual({ kind: 'a', namespace: 'y', name: 'c' }); - expect( - parseEntityName({ kind: 'a', name: 'c' }, { defaultKind: 'x' }), - ).toEqual({ kind: 'a', namespace: DEFAULT_NAMESPACE, name: 'c' }); - expect( - parseEntityName( - { name: 'c' }, - { defaultKind: 'x', defaultNamespace: 'y' }, - ), - ).toEqual({ kind: 'x', namespace: 'y', name: 'c' }); - expect(parseEntityName({ name: 'c' }, { defaultKind: 'x' })).toEqual({ - kind: 'x', - namespace: DEFAULT_NAMESPACE, - name: 'c', - }); - // empty strings are errors, not defaults - expect(() => - parseEntityName( - { kind: '', namespace: 'b', name: 'c' }, - { defaultKind: 'x', defaultNamespace: 'y' }, - ), - ).toThrow(/kind/); - expect(() => - parseEntityName( - { kind: 'a', namespace: '', name: 'c' }, - { defaultKind: 'x', defaultNamespace: 'y' }, - ), - ).toThrow(/namespace/); - }); - }); - describe('parseEntityRef', () => { it('handles some omissions', () => { expect(parseEntityRef('a:b/c')).toEqual({ diff --git a/packages/catalog-model/src/entity/ref.ts b/packages/catalog-model/src/entity/ref.ts index 4529b1174c..acede5a56b 100644 --- a/packages/catalog-model/src/entity/ref.ts +++ b/packages/catalog-model/src/entity/ref.ts @@ -64,45 +64,6 @@ export function getCompoundEntityRef(entity: Entity): CompoundEntityRef { }; } -/** - * Parses an entity reference, either on string or compound form, and always - * returns a complete entity name including kind, namespace and name. - * - * @remarks - * - * This function automatically assumes the default namespace "default" unless - * 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. - * - * @deprecated Please use parseEntityRef instead - * @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( - ref: string | { kind?: string; namespace?: string; name: string }, - context: { - /** The default kind, if none is given in the reference */ - defaultKind?: string; - /** The default namespace, if none is given in the reference */ - defaultNamespace?: string; - } = {}, -): CompoundEntityRef { - const { kind, namespace, name } = parseEntityRef(ref, { - defaultNamespace: DEFAULT_NAMESPACE, - ...context, - }); - - if (!kind) { - throw new Error( - `Entity reference ${namespace}/${name} did not contain a kind`, - ); - } - - return { kind, namespace, name }; -} - /** * Parses an entity reference, either on string or compound form, and returns * a structure with a name, and optional kind and namespace. diff --git a/packages/catalog-model/src/index.ts b/packages/catalog-model/src/index.ts index 19eacd4925..b5ccfed149 100644 --- a/packages/catalog-model/src/index.ts +++ b/packages/catalog-model/src/index.ts @@ -24,5 +24,5 @@ export * from './entity'; export { EntityPolicies } from './EntityPolicies'; export * from './kinds'; export * from './location'; -export type { EntityName, EntityRef, CompoundEntityRef } from './types'; +export type { EntityName, CompoundEntityRef } from './types'; export * from './validation'; diff --git a/packages/catalog-model/src/location/annotation.ts b/packages/catalog-model/src/location/annotation.ts index 61dbc0b305..bd282e2871 100644 --- a/packages/catalog-model/src/location/annotation.ts +++ b/packages/catalog-model/src/location/annotation.ts @@ -15,19 +15,25 @@ */ /** - * Constant storing location annotation. + * Entity annotation containing the location from which the entity is sourced. * - * @public */ + * @public + */ export const ANNOTATION_LOCATION = 'backstage.io/managed-by-location'; + /** - * Constant storing origin location annotation + * Entity annotation containing the originally sourced location which ultimately + * led to this entity being ingested. * - * @public */ + * @public + */ export const ANNOTATION_ORIGIN_LOCATION = 'backstage.io/managed-by-origin-location'; /** - * Contant storing source location annotation + * Entity annotation pointing to the source (e.g. source code repository root or + * similar) for this entity. * - * @public */ + * @public + */ export const ANNOTATION_SOURCE_LOCATION = 'backstage.io/source-location'; diff --git a/packages/catalog-model/src/location/index.ts b/packages/catalog-model/src/location/index.ts index dc709144b2..c53a1d2c83 100644 --- a/packages/catalog-model/src/location/index.ts +++ b/packages/catalog-model/src/location/index.ts @@ -24,4 +24,3 @@ export { parseLocationRef, stringifyLocationRef, } from './helpers'; -export type { LocationSpec } from './types'; diff --git a/packages/catalog-model/src/location/types.ts b/packages/catalog-model/src/location/types.ts deleted file mode 100644 index 9e2c9339e6..0000000000 --- a/packages/catalog-model/src/location/types.ts +++ /dev/null @@ -1,33 +0,0 @@ -/* - * Copyright 2020 The Backstage Authors - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -/** - * Holds the entity location information. - * - * @remarks - * - * `presence` flag: when using repo importer plugin, location is being created before the component yaml file is merged to the main branch. - * This flag is then set to indicate that the file can be not present. - * default value: 'required'. - * - * @public - * @deprecated Import from `@backstage/plugin-catalog-backend` instead. - */ -export type LocationSpec = { - type: string; - target: string; - presence?: 'optional' | 'required'; -}; diff --git a/packages/catalog-model/src/types.ts b/packages/catalog-model/src/types.ts index e7d819ace9..7b3f23c64f 100644 --- a/packages/catalog-model/src/types.ts +++ b/packages/catalog-model/src/types.ts @@ -33,25 +33,3 @@ export type CompoundEntityRef = { * @public */ export type EntityName = CompoundEntityRef; - -/** - * A reference by name to an entity, either as a compact string representation, - * or as a compound reference structure. - * - * @deprecated Please use string directly, or EntityName (depending on what you actually need) - * @remarks - * - * The string representation is on the form `[:][/]`. - * - * 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 - | { - kind?: string; - namespace?: string; - name: string; - };