Foundation for standard status values

Signed-off-by: Fredrik Adelöw <freben@gmail.com>

packages/catalog-client/api-report.md

@@ -7,6 +7,9 @@
 import { Entity } from '@backstage/catalog-model';
 import { EntityName } from '@backstage/catalog-model';
 import { Location as Location_2 } from '@backstage/catalog-model';
+import { SerializedError } from '@backstage/errors';
+import { UNSTABLE_EntityStatusLevel } from '@backstage/catalog-model';
+import { UNSTABLE_EntityStatusValue } from '@backstage/catalog-model';
 
 // @public (undocumented)
 export type AddLocationRequest = {
@@ -76,6 +79,21 @@ export type CatalogListResponse<T> = {
     items: T[];
 };
 
+// @public
+export const ENTITY_STATUS_CATALOG_PROCESSING_KEY = "backstage.io/catalog-processing";
+
+// @public
+export type UNSTABLE_CatalogProcessingStatus = UNSTABLE_EntityStatusValue & {
+    items?: UNSTABLE_CatalogProcessingStatusItem[];
+};
+
+// @public (undocumented)
+export type UNSTABLE_CatalogProcessingStatusItem = {
+    status: UNSTABLE_EntityStatusLevel;
+    message?: string;
+    error?: SerializedError;
+};
+
 
 // (No @packageDocumentation comment for this package)
 

packages/catalog-client/src/CatalogClient.test.ts

@@ -18,7 +18,8 @@ import { Entity } from '@backstage/catalog-model';
 import { rest } from 'msw';
 import { setupServer } from 'msw/node';
 import { CatalogClient } from './CatalogClient';
-import { CatalogListResponse, DiscoveryApi } from './types';
+import { CatalogListResponse } from './types/api';
+import { DiscoveryApi } from './types/discovery';
 
 const server = setupServer();
 const token = 'fake-token';

packages/catalog-client/src/CatalogClient.ts

@@ -31,8 +31,8 @@ import {
   CatalogEntitiesRequest,
   CatalogListResponse,
   CatalogRequestOptions,
-  DiscoveryApi,
-} from './types';
+} from './types/api';
+import { DiscoveryApi } from './types/discovery';
 
 export class CatalogClient implements CatalogApi {
   private readonly discoveryApi: DiscoveryApi;

packages/catalog-client/src/index.ts

@@ -15,10 +15,4 @@
  */
 
 export { CatalogClient } from './CatalogClient';
-export type {
-  AddLocationRequest,
-  AddLocationResponse,
-  CatalogApi,
-  CatalogEntitiesRequest,
-  CatalogListResponse,
-} from './types';
+export * from './types';

packages/catalog-client/src/types/api.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020 Spotify AB
+ * Copyright 2021 Spotify AB
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -81,10 +81,3 @@ export type AddLocationResponse = {
   location: Location;
   entities: Entity[];
 };
-
-/**
- * This is a copy of the core DiscoveryApi, to avoid importing core.
- */
-export type DiscoveryApi = {
-  getBaseUrl(pluginId: string): Promise<string>;
-};

packages/catalog-client/src/types/discovery.ts

@@ -0,0 +1,22 @@
+/*
+ * Copyright 2021 Spotify AB
+ *
+ * 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.
+ */
+
+/**
+ * This is a copy of the core DiscoveryApi, to avoid importing core.
+ */
+export type DiscoveryApi = {
+  getBaseUrl(pluginId: string): Promise<string>;
+};

packages/catalog-client/src/types/index.ts

@@ -0,0 +1,28 @@
+/*
+ * Copyright 2021 Spotify AB
+ *
+ * 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.
+ */
+
+export type {
+  AddLocationRequest,
+  AddLocationResponse,
+  CatalogApi,
+  CatalogEntitiesRequest,
+  CatalogListResponse,
+} from './api';
+export { ENTITY_STATUS_CATALOG_PROCESSING_KEY } from './status';
+export type {
+  UNSTABLE_CatalogProcessingStatus,
+  UNSTABLE_CatalogProcessingStatusItem,
+} from './status';

packages/catalog-client/src/types/status.ts

@@ -0,0 +1,63 @@
+/*
+ * Copyright 2021 Spotify AB
+ *
+ * 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.
+ */
+
+import {
+  UNSTABLE_EntityStatusLevel,
+  UNSTABLE_EntityStatusValue,
+} from '@backstage/catalog-model';
+import { SerializedError } from '@backstage/errors';
+
+/*
+ * This is the entity status field that's emitted by the catalog processing
+ * engine, to inform about the status of an entity.
+ *
+ * Example:
+ *
+ * "status": {
+ *   "backstage.io/catalog-processing": {
+ *     "status": "error",
+ *     "items": [
+ *       {
+ *         "status": "error",
+ *         "error": {
+ *           "name": "InputError",
+ *           "message": "Syntax error: ..."
+ *         }
+ *       }
+ *     ]
+ *   }
+ * }
+ */
+
+/**
+ * The entity `status` key for the status of the processing engine in regards
+ * to entity.
+ */
+export const ENTITY_STATUS_CATALOG_PROCESSING_KEY =
+  'backstage.io/catalog-processing';
+
+/**
+ * The status value for the `backstage.io/catalog-processing` key.
+ */
+export type UNSTABLE_CatalogProcessingStatus = UNSTABLE_EntityStatusValue & {
+  items?: UNSTABLE_CatalogProcessingStatusItem[];
+};
+
+export type UNSTABLE_CatalogProcessingStatusItem = {
+  status: UNSTABLE_EntityStatusLevel;
+  message?: string;
+  error?: SerializedError;
+};

packages/catalog-model/api-report.md

@@ -528,6 +528,15 @@ export interface TemplateEntityV1beta2 extends Entity {
 // @public (undocumented)
 export const templateEntityV1beta2Validator: KindValidator;
 
+// @public
+export type UNSTABLE_EntityStatusLevel = 'ok' | 'info' | 'warning' | 'error';
+
+// @public
+export type UNSTABLE_EntityStatusValue = {
+    status: UNSTABLE_EntityStatusLevel;
+    message?: string;
+};
+
 // @public (undocumented)
 interface UserEntityV1alpha1 extends Entity {
     // (undocumented)

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

@@ -15,10 +15,10 @@
  */
 
 export {
+  EDIT_URL_ANNOTATION,
   ENTITY_DEFAULT_NAMESPACE,
   ENTITY_META_GENERATED_FIELDS,
   VIEW_URL_ANNOTATION,
-  EDIT_URL_ANNOTATION,
 } from './constants';
 export type {
   Entity,
@@ -36,6 +36,10 @@ export {
   serializeEntityRef,
   stringifyEntityRef,
 } from './ref';
+export type {
+  UNSTABLE_EntityStatusLevel,
+  UNSTABLE_EntityStatusValue,
+} from './status';
 export {
   entityHasChanges,
   generateEntityEtag,

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

@@ -0,0 +1,32 @@
+/*
+ * Copyright 2021 Spotify AB
+ *
+ * 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.
+ */
+
+/**
+ * Each entity status entry has a level, describing its severity.
+ */
+export type UNSTABLE_EntityStatusLevel =
+  | 'ok' // Everything is OK
+  | 'info' // Only informative data
+  | 'warning' // Warnings were found
+  | 'error'; // Errors were found
+
+/**
+ * Reserved root fields in all `status` object values.
+ */
+export type UNSTABLE_EntityStatusValue = {
+  status: UNSTABLE_EntityStatusLevel;
+  message?: string;
+};