catalog-model: enable alpha release stage and add AlphaEntity

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

.changeset/wise-cooks-admire.md

@@ -0,0 +1,21 @@
+---
+'@backstage/catalog-model': patch
+---
+
+Added `alpha` release stage type declarations, accessible via `@backstage/catalog-model/alpha`.
+
+**BREAKING**: The experimental entity `status` field was removed from the base `Entity` type and is now only available on the `AlphaEntity` type from the alpha release stage, along with all accompanying types that were previously marked as `UNSTABLE_`.
+
+For example, the following import:
+
+```ts
+import { UNSTABLE_EntityStatusItem } from '@backstage/catalog-model';
+```
+
+Becomes this:
+
+```ts
+import { EntityStatusItem } from '@backstage/catalog-model/alpha';
+```
+
+Note that exports that are only available from the alpha release stage are considered unstable and do not adhere to the semantic versioning of the package.

packages/catalog-model/api-report.md

@@ -9,6 +9,11 @@ import { JsonValue } from '@backstage/types';
 import { SerializedError } from '@backstage/errors';
 import * as yup from 'yup';
 
+// @alpha
+export interface AlphaEntity extends Entity {
+  status?: EntityStatus;
+}
+
 // @public @deprecated
 export const analyzeLocationSchema: yup.SchemaOf<{
   location: LocationSpec;
@@ -116,7 +121,6 @@ export type Entity = {
   metadata: EntityMeta;
   spec?: JsonObject;
   relations?: EntityRelation[];
-  status?: UNSTABLE_EntityStatus;
 };
 
 // @public
@@ -225,6 +229,22 @@ export function entitySchemaValidator<T extends Entity = Entity>(
   schema?: unknown,
 ): (data: unknown) => T;
 
+// @alpha
+export type EntityStatus = {
+  items?: EntityStatusItem[];
+};
+
+// @alpha
+export type EntityStatusItem = {
+  type: string;
+  level: EntityStatusLevel;
+  message: string;
+  error?: SerializedError;
+};
+
+// @alpha
+export type EntityStatusLevel = 'info' | 'warning' | 'error';
+
 // @public
 export class FieldFormatEntityPolicy implements EntityPolicy {
   constructor(validators?: Validators);
@@ -550,22 +570,6 @@ export interface TemplateEntityV1beta2 extends Entity {
 // @public
 export const templateEntityV1beta2Validator: KindValidator;
 
-// @alpha
-export type UNSTABLE_EntityStatus = {
-  items?: UNSTABLE_EntityStatusItem[];
-};
-
-// @alpha
-export type UNSTABLE_EntityStatusItem = {
-  type: string;
-  level: UNSTABLE_EntityStatusLevel;
-  message: string;
-  error?: SerializedError;
-};
-
-// @alpha
-export type UNSTABLE_EntityStatusLevel = 'info' | 'warning' | 'error';
-
 // @public
 interface UserEntityV1alpha1 extends Entity {
   // (undocumented)
@@ -603,8 +607,4 @@ export type Validators = {
 
 // @public
 export const VIEW_URL_ANNOTATION = 'backstage.io/view-url';
-
-// Warnings were encountered during analysis:
-//
-// src/entity/Entity.d.ts:41:5 - (ae-incompatible-release-tags) The symbol "status" is marked as @public, but its signature references "UNSTABLE_EntityStatus" which is marked as @alpha
 ```

packages/catalog-model/package.json

@@ -10,7 +10,8 @@
     "access": "public",
     "main": "dist/index.cjs.js",
     "module": "dist/index.esm.js",
-    "types": "dist/index.d.ts"
+    "types": "dist/index.d.ts",
+    "alphaTypes": "dist/index.alpha.d.ts"
   },
   "homepage": "https://backstage.io",
   "repository": {
@@ -22,7 +23,7 @@
     "backstage"
   ],
   "scripts": {
-    "build": "backstage-cli build",
+    "build": "backstage-cli build --experimental-type-build",
     "lint": "backstage-cli lint",
     "test": "backstage-cli test",
     "prepack": "backstage-cli prepack",
@@ -48,6 +49,7 @@
     "yaml": "^1.9.2"
   },
   "files": [
-    "dist"
+    "dist",
+    "alpha"
   ]
 }

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

@@ -16,7 +16,7 @@
 
 import { JsonObject } from '@backstage/types';
 import { EntityName } from '../types';
-import { UNSTABLE_EntityStatus } from './EntityStatus';
+import { EntityStatus } from './EntityStatus';
 
 /**
  * The parts of the format that's common to all versions/kinds of entity.
@@ -53,15 +53,26 @@ export type Entity = {
    * The relations that this entity has with other entities.
    */
   relations?: EntityRelation[];
+};
 
+/**
+ * A version of the {@link Entity} type that contains unstable alpha fields.
+ *
+ * @remarks
+ *
+ * Available via the `@backstage/catalog-model/alpha` import.
+ *
+ * @alpha
+ */
+export interface AlphaEntity extends Entity {
   /**
    * The current status of the entity, as claimed by various sources.
    *
    * The keys are implementation defined and the values can be any JSON object
    * with semantics that match that implementation.
    */
-  status?: UNSTABLE_EntityStatus;
-};
+  status?: EntityStatus;
+}
 
 /**
  * Metadata fields common to all versions/kinds of entity.

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

@@ -21,18 +21,18 @@ import { SerializedError } from '@backstage/errors';
  *
  * @alpha
  */
-export type UNSTABLE_EntityStatus = {
+export type EntityStatus = {
   /**
    * Specific status item on a well known format.
    */
-  items?: UNSTABLE_EntityStatusItem[];
+  items?: EntityStatusItem[];
 };
 
 /**
  * A specific status item on a well known format.
  * @alpha
  */
-export type UNSTABLE_EntityStatusItem = {
+export type EntityStatusItem = {
   /**
    * The type of status as a unique key per source.
    */
@@ -43,7 +43,7 @@ export type UNSTABLE_EntityStatusItem = {
    * entry may apply to a different, newer version of the data than what is
    * being returned in the catalog response.
    */
-  level: UNSTABLE_EntityStatusLevel;
+  level: EntityStatusLevel;
   /**
    * A brief message describing the status, intended for human consumption.
    */
@@ -58,7 +58,7 @@ export type UNSTABLE_EntityStatusItem = {
  * Each entity status item has a level, describing its severity.
  * @alpha
  */
-export type UNSTABLE_EntityStatusLevel =
+export type EntityStatusLevel =
   | 'info' // Only informative data
   | 'warning' // Warnings were found
   | 'error'; // Errors were found

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

@@ -21,6 +21,7 @@ export {
   VIEW_URL_ANNOTATION,
 } from './constants';
 export type {
+  AlphaEntity,
   Entity,
   EntityLink,
   EntityMeta,
@@ -29,9 +30,9 @@ export type {
 } from './Entity';
 export type { EntityEnvelope } from './EntityEnvelope';
 export type {
-  UNSTABLE_EntityStatus,
-  UNSTABLE_EntityStatusItem,
-  UNSTABLE_EntityStatusLevel,
+  EntityStatus,
+  EntityStatusItem,
+  EntityStatusLevel,
 } from './EntityStatus';
 export * from './policies';
 export {

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

@@ -16,7 +16,7 @@
 
 import lodash from 'lodash';
 import { v4 as uuidv4 } from 'uuid';
-import { Entity } from './Entity';
+import { Entity, AlphaEntity } from './Entity';
 
 /**
  * Generates a new random UID for an entity.
@@ -89,9 +89,9 @@ export function entityHasChanges(previous: Entity, next: Entity): boolean {
 
   // Remove things that we explicitly do not compare
   delete e1.relations;
-  delete e1.status;
+  delete (e1 as AlphaEntity).status;
   delete e2.relations;
-  delete e2.status;
+  delete (e2 as AlphaEntity).status;
 
   return !lodash.isEqual(e1, e2);
 }