Merge pull request #9939 from backstage/blam/catalog-entity-document

🧹 Moving `CatalogEntityDocument` to `plugin-catalog-common` and deprecating `componentType` in the document

.changeset/small-hornets-dress.md

@@ -0,0 +1,10 @@
+---
+'@backstage/plugin-catalog-backend': patch
+'@backstage/plugin-catalog-common': patch
+---
+
+**DEPRECATION**: Moved the `CatalogEntityDocument` to `@backstage/plugin-catalog-common` and deprecated the export from `@backstage/plugin-catalog-backend`.
+
+A new `type` field has also been added to `CatalogEntityDocument` as a replacement for `componentType`, which is now deprecated. Both fields are still present and should be set to the same value in order to avoid issues with indexing.
+
+Any search customizations need to be updated to use this new `type` field instead, including any custom frontend filters, custom frontend result components, custom search decorators, or non-default Catalog collator implementations.

plugins/catalog-backend/api-report.md

@@ -7,6 +7,7 @@
 
 import { BitbucketIntegration } from '@backstage/integration';
 import { CatalogApi } from '@backstage/catalog-client';
+import { CatalogEntityDocument as CatalogEntityDocument_2 } from '@backstage/plugin-catalog-common';
 import { CompoundEntityRef } from '@backstage/catalog-model';
 import { ConditionalPolicyDecision } from '@backstage/plugin-permission-node';
 import { Conditions } from '@backstage/plugin-permission-node';
@@ -18,7 +19,6 @@ import express from 'express';
 import { GetEntitiesRequest } from '@backstage/catalog-client';
 import { GithubCredentialsProvider } from '@backstage/integration';
 import { GitHubIntegrationConfig } from '@backstage/integration';
-import { IndexableDocument } from '@backstage/search-common';
 import { JsonObject } from '@backstage/types';
 import { JsonValue } from '@backstage/types';
 import { Location as Location_2 } from '@backstage/catalog-client';
@@ -254,19 +254,8 @@ export const catalogConditions: Conditions<{
   >;
 }>;
 
-// @public (undocumented)
-export interface CatalogEntityDocument extends IndexableDocument {
-  // (undocumented)
-  componentType: string;
-  // (undocumented)
-  kind: string;
-  // (undocumented)
-  lifecycle: string;
-  // (undocumented)
-  namespace: string;
-  // (undocumented)
-  owner: string;
-}
+// @public @deprecated (undocumented)
+export type CatalogEntityDocument = CatalogEntityDocument_2;
 
 // @public (undocumented)
 export type CatalogEnvironment = {
@@ -447,7 +436,7 @@ export class DefaultCatalogCollator {
   // (undocumented)
   protected discovery: PluginEndpointDiscovery;
   // (undocumented)
-  execute(): Promise<CatalogEntityDocument[]>;
+  execute(): Promise<CatalogEntityDocument_2[]>;
   // (undocumented)
   protected filter?: GetEntitiesRequest['filter'];
   // (undocumented)

plugins/catalog-backend/src/search/DefaultCatalogCollator.ts

@@ -29,8 +29,10 @@ import {
   CatalogClient,
   GetEntitiesRequest,
 } from '@backstage/catalog-client';
-import { catalogEntityReadPermission } from '@backstage/plugin-catalog-common';
-import { CatalogEntityDocument } from './DefaultCatalogCollatorFactory';
+import {
+  catalogEntityReadPermission,
+  CatalogEntityDocument,
+} from '@backstage/plugin-catalog-common';
 
 /**
  * @public
@@ -125,6 +127,7 @@ export class DefaultCatalogCollator {
         }),
         text: this.getDocumentText(entity),
         componentType: entity.spec?.type?.toString() || 'other',
+        type: entity.spec?.type?.toString() || 'other',
         namespace: entity.metadata.namespace || 'default',
         kind: entity.kind,
         lifecycle: (entity.spec?.lifecycle as string) || '',

plugins/catalog-backend/src/search/DefaultCatalogCollatorFactory.ts

@@ -29,22 +29,13 @@ import {
   UserEntity,
 } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
+import { DocumentCollatorFactory } from '@backstage/search-common';
 import {
-  DocumentCollatorFactory,
-  IndexableDocument,
-} from '@backstage/search-common';
-import { catalogEntityReadPermission } from '@backstage/plugin-catalog-common';
+  catalogEntityReadPermission,
+  CatalogEntityDocument,
+} from '@backstage/plugin-catalog-common';
 import { Readable } from 'stream';
 
-/** @public */
-export interface CatalogEntityDocument extends IndexableDocument {
-  componentType: string;
-  namespace: string;
-  kind: string;
-  lifecycle: string;
-  owner: string;
-}
-
 /** @public */
 export type DefaultCatalogCollatorFactoryOptions = {
   discovery: PluginEndpointDiscovery;
@@ -159,6 +150,7 @@ export class DefaultCatalogCollatorFactory implements DocumentCollatorFactory {
           }),
           text: this.getDocumentText(entity),
           componentType: entity.spec?.type?.toString() || 'other',
+          type: entity.spec?.type?.toString() || 'other',
           namespace: entity.metadata.namespace || 'default',
           kind: entity.kind,
           lifecycle: (entity.spec?.lifecycle as string) || '',

plugins/catalog-backend/src/search/index.ts

@@ -16,7 +16,14 @@
 
 export { DefaultCatalogCollatorFactory } from './DefaultCatalogCollatorFactory';
 export type { DefaultCatalogCollatorFactoryOptions } from './DefaultCatalogCollatorFactory';
-export type { CatalogEntityDocument } from './DefaultCatalogCollatorFactory';
+
+import { CatalogEntityDocument as CatalogEntityDocumentType } from '@backstage/plugin-catalog-common';
+
+/**
+ * @deprecated import from `@backstage/plugin-catalog-common` instead
+ * @public
+ */
+export type CatalogEntityDocument = CatalogEntityDocumentType;
 
 /**
  * todo(backstage/techdocs-core): stop exporting this in a future release.

plugins/catalog-common/api-report.md

@@ -3,6 +3,7 @@
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
 ```ts
+import { IndexableDocument } from '@backstage/search-common';
 import { Permission } from '@backstage/plugin-permission-common';
 
 // @alpha
@@ -11,6 +12,22 @@ export const catalogEntityCreatePermission: Permission;
 // @alpha
 export const catalogEntityDeletePermission: Permission;
 
+// @public
+export interface CatalogEntityDocument extends IndexableDocument {
+  // @deprecated (undocumented)
+  componentType: string;
+  // (undocumented)
+  kind: string;
+  // (undocumented)
+  lifecycle: string;
+  // (undocumented)
+  namespace: string;
+  // (undocumented)
+  owner: string;
+  // (undocumented)
+  type: string;
+}
+
 // @alpha
 export const catalogEntityReadPermission: Permission;
 

plugins/catalog-common/package.json

@@ -34,7 +34,8 @@
     "clean": "backstage-cli package clean"
   },
   "dependencies": {
-    "@backstage/plugin-permission-common": "^0.5.1"
+    "@backstage/plugin-permission-common": "^0.5.1",
+    "@backstage/search-common": "^0.2.4"
   },
   "devDependencies": {
     "@backstage/cli": "^0.14.0"

plugins/catalog-common/src/index.ts

@@ -31,3 +31,5 @@ export {
   catalogLocationCreatePermission,
   catalogLocationDeletePermission,
 } from './permissions';
+
+export * from './search';

plugins/catalog-common/src/search/CatalogEntityDocument.ts

@@ -0,0 +1,31 @@
+/*
+ * Copyright 2022 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.
+ */
+import { IndexableDocument } from '@backstage/search-common';
+
+/**
+ * The Document format for an Entity in the Catalog for search
+ *
+ * @public
+ */
+export interface CatalogEntityDocument extends IndexableDocument {
+  /** @deprecated `componentType` is being renamed to `type`. During the transition both of these fields should be set to the same value, in order to avoid issues with indexing. */
+  componentType: string;
+  type: string;
+  namespace: string;
+  kind: string;
+  lifecycle: string;
+  owner: string;
+}

plugins/catalog-common/src/search/index.ts

@@ -0,0 +1,16 @@
+/*
+ * Copyright 2022 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.
+ */
+export type { CatalogEntityDocument } from './CatalogEntityDocument';