catalog-backend: deprecated location result optional flag

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
2022-02-17 15:29:06 +01:00
parent 209fd128e6
commit 082c32f948
12 changed files with 66 additions and 59 deletions
@@ -0,0 +1,23 @@
+---
+'@backstage/plugin-catalog-backend': patch
+---
+
+Deprecated the second parameter of `results.location()` that determines whether an emitted location is optional. In cases where this is currently being set to `false`, the parameter can simply be dropped, as that is the default. Usage where this was being set to `true` should be migrated to set the `presence` option of the emitted location to `optional`. For example:
+
+```ts
+results.location(
+  {
+    type: 'url',
+    target: 'http://example.com/foo',
+  },
+  true,
+);
+
+// migrated to
+
+results.location({
+  type: 'url',
+  target: 'http://example.com/foo',
+  presence: 'optional',
+});
+```
@@ -430,7 +430,7 @@ export type CatalogProcessorErrorResult = {
 export type CatalogProcessorLocationResult = {
  type: 'location';
  location: LocationSpec;
-  optional: boolean;
+  optional?: boolean;
 };

 // Warning: (ae-missing-release-tag) "CatalogProcessorParser" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
@@ -903,7 +903,7 @@ function inputError(
 // @public (undocumented)
 function location_2(
  newLocation: LocationSpec,
-  optional: boolean,
+  optional?: boolean,
 ): CatalogProcessorResult;

 // Warning: (ae-missing-release-tag) "LocationAnalyzer" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
@@ -101,17 +101,14 @@ export class AzureDevOpsDiscoveryProcessor implements CatalogProcessor {

    for (const file of files) {
      emit(
-        results.location(
-          {
-            type: 'url',
-            target: `${baseUrl}/${org}/${project}/_git/${file.repository.name}?path=${file.path}`,
-            presence: 'optional',
-          },
+        results.location({
+          type: 'url',
+          target: `${baseUrl}/${org}/${project}/_git/${file.repository.name}?path=${file.path}`,
          // Not all locations may actually exist, since the user defined them as a wildcard pattern.
          // Thus, we emit them as optional and let the downstream processor find them while not outputting
          // an error if it couldn't.
-          true,
-        ),
+          presence: 'optional',
+        }),
      );
    }

@@ -766,13 +766,11 @@ describe('BitbucketDiscoveryProcessor', () => {
  describe('Custom repository parser', () => {
    const customRepositoryParser: BitbucketRepositoryParser =
      async function* customRepositoryParser({}) {
-        yield results.location(
-          {
-            type: 'custom-location-type',
-            target: 'custom-target',
-          },
-          true,
-        );
+        yield results.location({
+          type: 'custom-location-type',
+          target: 'custom-target',
+          presence: 'optional',
+        });
      };

    const processor = BitbucketDiscoveryProcessor.fromConfig(
@@ -117,20 +117,17 @@ export class GitLabDiscoveryProcessor implements CatalogProcessor {
      const project_branch = branch === '*' ? project.default_branch : branch;

      emit(
-        results.location(
-          {
-            type: 'url',
-            // The format expected by the GitLabUrlReader:
-            // https://gitlab.com/groupA/teams/teamA/subgroupA/repoA/-/blob/branch/filepath
-            //
-            // This unfortunately will trigger another API call in `getGitLabFileFetchUrl` to get the project ID.
-            // The alternative is using the `buildRawUrl` function, which does not support subgroups, so providing a raw
-            // URL here won't work either.
-            target: `${project.web_url}/-/blob/${project_branch}/${catalogPath}`,
-            presence: 'optional',
-          },
-          true,
-        ),
+        results.location({
+          type: 'url',
+          // The format expected by the GitLabUrlReader:
+          // https://gitlab.com/groupA/teams/teamA/subgroupA/repoA/-/blob/branch/filepath
+          //
+          // This unfortunately will trigger another API call in `getGitLabFileFetchUrl` to get the project ID.
+          // The alternative is using the `buildRawUrl` function, which does not support subgroups, so providing a raw
+          // URL here won't work either.
+          target: `${project.web_url}/-/blob/${project_branch}/${catalogPath}`,
+          presence: 'optional',
+        }),
      );
    }

@@ -140,17 +140,14 @@ export class GithubDiscoveryProcessor implements CatalogProcessor {
      const path = `/blob/${branchName}${catalogPath}`;

      emit(
-        results.location(
-          {
-            type: 'url',
-            target: `${repository.url}${path}`,
-            presence: 'optional',
-          },
+        results.location({
+          type: 'url',
+          target: `${repository.url}${path}`,
          // Not all locations may actually exist, since the user defined them as a wildcard pattern.
          // Thus, we emit them as optional and let the downstream processor find them while not outputting
          // an error if it couldn't.
-          true,
-        ),
+          presence: 'optional',
+        }),
      );
    }

@@ -81,7 +81,7 @@ export class LocationEntityProcessor implements CatalogProcessor {
          location,
          maybeRelativeTarget,
        );
-        emit(result.location({ type, target }, false));
+        emit(result.location({ type, target }));
      }
    }

@@ -48,7 +48,7 @@ export class StaticLocationProcessor implements StaticLocationProcessor {
    }

    for (const staticLocation of this.staticLocations) {
-      emit(result.location(staticLocation, false));
+      emit(result.location(staticLocation));
    }

    return true;
@@ -25,14 +25,11 @@ describe('BitbucketRepositoryParser', () => {
        'https://bitbucket.mycompany.com/projects/project-key/repos/repo-slug/browse';
      const path = '/catalog-info.yaml';
      const expected = [
-        results.location(
-          {
-            type: 'url',
-            target: `${browseUrl}${path}`,
-            presence: 'optional',
-          },
-          true,
-        ),
+        results.location({
+          type: 'url',
+          target: `${browseUrl}${path}`,
+          presence: 'optional',
+        }),
      ];
      const actual = await defaultRepositoryParser({
        integration: {} as BitbucketIntegration,
@@ -26,15 +26,12 @@ export type BitbucketRepositoryParser = (options: {

 export const defaultRepositoryParser: BitbucketRepositoryParser =
  async function* defaultRepositoryParser({ target }) {
-    yield results.location(
-      {
-        type: 'url',
-        target: target,
-        presence: 'optional',
-      },
+    yield results.location({
+      type: 'url',
+      target: target,
      // Not all locations may actually exist, since the user defined them as a wildcard pattern.
      // Thus, we emit them as optional and let the downstream processor find them while not outputting
      // an error if it couldn't.
-      true,
-    );
+      presence: 'optional',
+    });
  };
@@ -53,7 +53,7 @@ export function generalError(

 export function location(
  newLocation: LocationSpec,
-  optional: boolean,
+  optional?: boolean,
 ): CatalogProcessorResult {
  return { type: 'location', location: newLocation, optional };
 }
@@ -158,7 +158,8 @@ export type CatalogProcessorEmit = (generated: CatalogProcessorResult) => void;
 export type CatalogProcessorLocationResult = {
  type: 'location';
  location: LocationSpec;
-  optional: boolean;
+  /** @deprecated Set `location.presence = 'optional'` instead  */
+  optional?: boolean;
 };

 export type CatalogProcessorEntityResult = {