Merge pull request #10004 from backstage/freben/more-model-removal

more cleanup in catalog-model

.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.

packages/catalog-model/api-report.md

@@ -190,15 +190,6 @@ export type EntityPolicy = {
   enforce(entity: Entity): Promise<Entity | undefined>;
 };
 
-// @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>): Validators;
 
@@ -333,21 +317,6 @@ export class NoForeignRootFieldsEntityPolicy implements EntityPolicy {
   enforce(entity: Entity): Promise<Entity>;
 }
 
-// @public @deprecated
-export function parseEntityName(
-  ref:
-    | string
-    | {
-        kind?: string;
-        namespace?: string;
-        name: string;
-      },
-  context?: {
-    defaultKind?: string;
-    defaultNamespace?: string;
-  },
-): CompoundEntityRef;
-
 // @public
 export function parseEntityRef(
   ref:

packages/catalog-model/src/entity/index.ts

@@ -36,7 +36,6 @@ export * from './policies';
 export {
   getCompoundEntityRef,
   getEntityName,
-  parseEntityName,
   parseEntityRef,
   stringifyEntityRef,
 } from './ref';

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({

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.

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';

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';

packages/catalog-model/src/location/index.ts

@@ -24,4 +24,3 @@ export {
   parseLocationRef,
   stringifyLocationRef,
 } from './helpers';
-export type { LocationSpec } from './types';

packages/catalog-model/src/location/types.ts

@@ -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';
-};

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 `[<kind>:][<namespace>/]<name>`.
- *
- * 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;
-    };