Merge pull request #30462 from benjidotsh/catalog-client/analyze-location

feat(catalog): add analyze-location endpoint to CatalogClient

.changeset/evil-forks-hang.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-react': minor
+---
+
+Added the `analyzeLocation` method to `catalogApiMock`

.changeset/little-bugs-care.md

@@ -0,0 +1,5 @@
+---
+'@backstage/catalog-client': minor
+---
+
+Added the analyze-location endpoint to the CatalogClient

.changeset/long-grapes-glow.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-node': minor
+---
+
+Added the analyze-location endpoint to the CatalogService

packages/catalog-client/package.json

@@ -55,6 +55,7 @@
   },
   "devDependencies": {
     "@backstage/cli": "workspace:^",
+    "@backstage/plugin-catalog-common": "workspace:^",
     "msw": "^1.0.0"
   }
 }

packages/catalog-client/report-testUtils.api.md

@@ -5,6 +5,8 @@
 ```ts
 import { AddLocationRequest } from '@backstage/catalog-client';
 import { AddLocationResponse } from '@backstage/catalog-client';
+import type { AnalyzeLocationRequest } from '@backstage/plugin-catalog-common';
+import type { AnalyzeLocationResponse } from '@backstage/plugin-catalog-common';
 import { CatalogApi } from '@backstage/catalog-client';
 import { CompoundEntityRef } from '@backstage/catalog-model';
 import { Entity } from '@backstage/catalog-model';
@@ -28,6 +30,10 @@ export class InMemoryCatalogClient implements CatalogApi {
   // (undocumented)
   addLocation(_location: AddLocationRequest): Promise<AddLocationResponse>;
   // (undocumented)
+  analyzeLocation(
+    _location: AnalyzeLocationRequest,
+  ): Promise<AnalyzeLocationResponse>;
+  // (undocumented)
   getEntities(request?: GetEntitiesRequest): Promise<GetEntitiesResponse>;
   // (undocumented)
   getEntitiesByRefs(

packages/catalog-client/report.api.md

@@ -3,6 +3,8 @@
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
 ```ts
+import type { AnalyzeLocationRequest } from '@backstage/plugin-catalog-common';
+import type { AnalyzeLocationResponse } from '@backstage/plugin-catalog-common';
 import { CompoundEntityRef } from '@backstage/catalog-model';
 import { Entity } from '@backstage/catalog-model';
 import { SerializedError } from '@backstage/errors';
@@ -30,6 +32,10 @@ export interface CatalogApi {
     location: AddLocationRequest,
     options?: CatalogRequestOptions,
   ): Promise<AddLocationResponse>;
+  analyzeLocation(
+    location: AnalyzeLocationRequest,
+    options?: CatalogRequestOptions,
+  ): Promise<AnalyzeLocationResponse>;
   getEntities(
     request?: GetEntitiesRequest,
     options?: CatalogRequestOptions,
@@ -103,6 +109,10 @@ export class CatalogClient implements CatalogApi {
     request: AddLocationRequest,
     options?: CatalogRequestOptions,
   ): Promise<AddLocationResponse>;
+  analyzeLocation(
+    request: AnalyzeLocationRequest,
+    options?: CatalogRequestOptions,
+  ): Promise<AnalyzeLocationResponse>;
   getEntities(
     request?: GetEntitiesRequest,
     options?: CatalogRequestOptions,

packages/catalog-client/src/CatalogClient.ts

@@ -44,6 +44,10 @@ import {
 } from './types/api';
 import { isQueryEntitiesInitialRequest, splitRefsIntoChunks } from './utils';
 import { DefaultApiClient, TypedResponse } from './schema/openapi';
+import type {
+  AnalyzeLocationRequest,
+  AnalyzeLocationResponse,
+} from '@backstage/plugin-catalog-common';
 
 /**
  * A frontend and backend compatible client for communicating with the Backstage
@@ -431,6 +435,27 @@ export class CatalogClient implements CatalogApi {
     };
   }
 
+  /**
+   * {@inheritdoc CatalogApi.analyzeLocation}
+   */
+  async analyzeLocation(
+    request: AnalyzeLocationRequest,
+    options?: CatalogRequestOptions,
+  ): Promise<AnalyzeLocationResponse> {
+    const response = await this.apiClient.analyzeLocation(
+      {
+        body: request,
+      },
+      options,
+    );
+
+    if (response.status !== 200) {
+      throw await ResponseError.fromResponse(response);
+    }
+
+    return response.json() as Promise<AnalyzeLocationResponse>;
+  }
+
   //
   // Private methods
   //

packages/catalog-client/src/testUtils/InMemoryCatalogClient.ts

@@ -44,6 +44,10 @@ import {
 import { NotFoundError, NotImplementedError } from '@backstage/errors';
 // eslint-disable-next-line @backstage/no-relative-monorepo-imports
 import { traverse } from '../../../../plugins/catalog-backend/src/database/operations/stitcher/buildEntitySearch';
+import type {
+  AnalyzeLocationRequest,
+  AnalyzeLocationResponse,
+} from '@backstage/plugin-catalog-common';
 
 function buildEntitySearch(entity: Entity) {
   const rows = traverse(entity);
@@ -269,6 +273,12 @@ export class InMemoryCatalogClient implements CatalogApi {
     throw new NotImplementedError('Method not implemented.');
   }
 
+  async analyzeLocation(
+    _location: AnalyzeLocationRequest,
+  ): Promise<AnalyzeLocationResponse> {
+    throw new NotImplementedError('Method not implemented.');
+  }
+
   #createEntityRefMap() {
     return new Map(this.#entities.map(e => [stringifyEntityRef(e), e]));
   }

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

@@ -16,6 +16,10 @@
 
 import { CompoundEntityRef, Entity } from '@backstage/catalog-model';
 import { SerializedError } from '@backstage/errors';
+import type {
+  AnalyzeLocationRequest,
+  AnalyzeLocationResponse,
+} from '@backstage/plugin-catalog-common';
 
 /**
  * This symbol can be used in place of a value when passed to filters in e.g.
@@ -677,4 +681,15 @@ export interface CatalogApi {
     locationRef: string,
     options?: CatalogRequestOptions,
   ): Promise<ValidateEntityResponse>;
+
+  /**
+   * Validate a given location.
+   *
+   * @param location - Request parameters
+   * @param options - Additional options
+   */
+  analyzeLocation(
+    location: AnalyzeLocationRequest,
+    options?: CatalogRequestOptions,
+  ): Promise<AnalyzeLocationResponse>;
 }

plugins/catalog-node/report-testUtils.api.md

@@ -5,6 +5,8 @@
 ```ts
 import { AddLocationRequest } from '@backstage/catalog-client';
 import { AddLocationResponse } from '@backstage/catalog-client';
+import { AnalyzeLocationRequest } from '@backstage/plugin-catalog-common';
+import { AnalyzeLocationResponse } from '@backstage/plugin-catalog-common';
 import { CatalogApi } from '@backstage/catalog-client';
 import { CatalogRequestOptions } from '@backstage/catalog-client';
 import { CatalogService } from '@backstage/plugin-catalog-node';
@@ -35,6 +37,11 @@ export interface CatalogServiceMock extends CatalogService, CatalogApi {
     options?: CatalogServiceRequestOptions | CatalogRequestOptions,
   ): Promise<AddLocationResponse>;
   // (undocumented)
+  analyzeLocation(
+    location: AnalyzeLocationRequest,
+    options?: CatalogServiceRequestOptions | CatalogRequestOptions,
+  ): Promise<AnalyzeLocationResponse>;
+  // (undocumented)
   getEntities(
     request?: GetEntitiesRequest,
     options?: CatalogServiceRequestOptions | CatalogRequestOptions,

plugins/catalog-node/report.api.md

@@ -125,6 +125,11 @@ export interface CatalogService {
     options: CatalogServiceRequestOptions,
   ): Promise<AddLocationResponse>;
   // (undocumented)
+  analyzeLocation(
+    location: AnalyzeLocationRequest,
+    options: CatalogServiceRequestOptions,
+  ): Promise<AnalyzeLocationResponse>;
+  // (undocumented)
   getEntities(
     request: GetEntitiesRequest | undefined,
     options: CatalogServiceRequestOptions,

plugins/catalog-node/src/catalogService.ts

@@ -42,6 +42,10 @@ import {
   ValidateEntityResponse,
 } from '@backstage/catalog-client';
 import { CompoundEntityRef, Entity } from '@backstage/catalog-model';
+import {
+  AnalyzeLocationRequest,
+  AnalyzeLocationResponse,
+} from '@backstage/plugin-catalog-common';
 
 /**
  * @public
@@ -132,6 +136,11 @@ export interface CatalogService {
     locationRef: string,
     options: CatalogServiceRequestOptions,
   ): Promise<ValidateEntityResponse>;
+
+  analyzeLocation(
+    location: AnalyzeLocationRequest,
+    options: CatalogServiceRequestOptions,
+  ): Promise<AnalyzeLocationResponse>;
 }
 
 class DefaultCatalogService implements CatalogService {
@@ -301,6 +310,16 @@ class DefaultCatalogService implements CatalogService {
     );
   }
 
+  async analyzeLocation(
+    location: AnalyzeLocationRequest,
+    options: CatalogServiceRequestOptions,
+  ): Promise<AnalyzeLocationResponse> {
+    return this.#catalogApi.analyzeLocation(
+      location,
+      await this.#getOptions(options),
+    );
+  }
+
   async #getOptions(
     options: CatalogServiceRequestOptions,
   ): Promise<CatalogRequestOptions> {

plugins/catalog-node/src/testUtils/catalogServiceMock.ts

@@ -102,5 +102,6 @@ export namespace catalogServiceMock {
     removeLocationById: jest.fn(),
     getLocationByEntity: jest.fn(),
     validateEntity: jest.fn(),
+    analyzeLocation: jest.fn(),
   }));
 }

plugins/catalog-node/src/testUtils/types.ts

@@ -34,6 +34,10 @@ import {
   ValidateEntityResponse,
 } from '@backstage/catalog-client';
 import { CompoundEntityRef, Entity } from '@backstage/catalog-model';
+import {
+  AnalyzeLocationRequest,
+  AnalyzeLocationResponse,
+} from '@backstage/plugin-catalog-common';
 import {
   CatalogService,
   CatalogServiceRequestOptions,
@@ -126,4 +130,9 @@ export interface CatalogServiceMock extends CatalogService, CatalogApi {
     locationRef: string,
     options?: CatalogServiceRequestOptions | CatalogRequestOptions,
   ): Promise<ValidateEntityResponse>;
+
+  analyzeLocation(
+    location: AnalyzeLocationRequest,
+    options?: CatalogServiceRequestOptions | CatalogRequestOptions,
+  ): Promise<AnalyzeLocationResponse>;
 }

plugins/catalog-react/src/testUtils/catalogApiMock.ts

@@ -101,5 +101,6 @@ export namespace catalogApiMock {
     removeLocationById: jest.fn(),
     getLocationByEntity: jest.fn(),
     validateEntity: jest.fn(),
+    analyzeLocation: jest.fn(),
   }));
 }

yarn.lock

@@ -3766,6 +3766,7 @@ __metadata:
     "@backstage/catalog-model": "workspace:^"
     "@backstage/cli": "workspace:^"
     "@backstage/errors": "workspace:^"
+    "@backstage/plugin-catalog-common": "workspace:^"
     cross-fetch: "npm:^4.0.0"
     msw: "npm:^1.0.0"
     uri-template: "npm:^2.0.0"