diff --git a/.changeset/grumpy-grapes-type.md b/.changeset/grumpy-grapes-type.md new file mode 100644 index 0000000000..cd1e9f4430 --- /dev/null +++ b/.changeset/grumpy-grapes-type.md @@ -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', +}); +``` diff --git a/plugins/catalog-backend/api-report.md b/plugins/catalog-backend/api-report.md index f52bbdc22e..1db5ca1e5e 100644 --- a/plugins/catalog-backend/api-report.md +++ b/plugins/catalog-backend/api-report.md @@ -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) diff --git a/plugins/catalog-backend/src/ingestion/processors/AzureDevOpsDiscoveryProcessor.ts b/plugins/catalog-backend/src/ingestion/processors/AzureDevOpsDiscoveryProcessor.ts index 693cc61bd8..c1cc610495 100644 --- a/plugins/catalog-backend/src/ingestion/processors/AzureDevOpsDiscoveryProcessor.ts +++ b/plugins/catalog-backend/src/ingestion/processors/AzureDevOpsDiscoveryProcessor.ts @@ -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', + }), ); } diff --git a/plugins/catalog-backend/src/ingestion/processors/BitbucketDiscoveryProcessor.test.ts b/plugins/catalog-backend/src/ingestion/processors/BitbucketDiscoveryProcessor.test.ts index 7ace995fda..b60a55a156 100644 --- a/plugins/catalog-backend/src/ingestion/processors/BitbucketDiscoveryProcessor.test.ts +++ b/plugins/catalog-backend/src/ingestion/processors/BitbucketDiscoveryProcessor.test.ts @@ -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( diff --git a/plugins/catalog-backend/src/ingestion/processors/GitLabDiscoveryProcessor.ts b/plugins/catalog-backend/src/ingestion/processors/GitLabDiscoveryProcessor.ts index 0822d40ef6..776ec1e7a8 100644 --- a/plugins/catalog-backend/src/ingestion/processors/GitLabDiscoveryProcessor.ts +++ b/plugins/catalog-backend/src/ingestion/processors/GitLabDiscoveryProcessor.ts @@ -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', + }), ); } diff --git a/plugins/catalog-backend/src/ingestion/processors/GithubDiscoveryProcessor.ts b/plugins/catalog-backend/src/ingestion/processors/GithubDiscoveryProcessor.ts index e0d2c3ca16..ec0de74b00 100644 --- a/plugins/catalog-backend/src/ingestion/processors/GithubDiscoveryProcessor.ts +++ b/plugins/catalog-backend/src/ingestion/processors/GithubDiscoveryProcessor.ts @@ -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', + }), ); } diff --git a/plugins/catalog-backend/src/ingestion/processors/LocationEntityProcessor.ts b/plugins/catalog-backend/src/ingestion/processors/LocationEntityProcessor.ts index ded6bd5ecf..60941486c3 100644 --- a/plugins/catalog-backend/src/ingestion/processors/LocationEntityProcessor.ts +++ b/plugins/catalog-backend/src/ingestion/processors/LocationEntityProcessor.ts @@ -81,7 +81,7 @@ export class LocationEntityProcessor implements CatalogProcessor { location, maybeRelativeTarget, ); - emit(result.location({ type, target }, false)); + emit(result.location({ type, target })); } } diff --git a/plugins/catalog-backend/src/ingestion/processors/StaticLocationProcessor.ts b/plugins/catalog-backend/src/ingestion/processors/StaticLocationProcessor.ts index a4bd8b5afa..c23c14bac9 100644 --- a/plugins/catalog-backend/src/ingestion/processors/StaticLocationProcessor.ts +++ b/plugins/catalog-backend/src/ingestion/processors/StaticLocationProcessor.ts @@ -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; diff --git a/plugins/catalog-backend/src/ingestion/processors/bitbucket/BitbucketRepositoryParser.test.ts b/plugins/catalog-backend/src/ingestion/processors/bitbucket/BitbucketRepositoryParser.test.ts index 397d259bae..35e24ed4cb 100644 --- a/plugins/catalog-backend/src/ingestion/processors/bitbucket/BitbucketRepositoryParser.test.ts +++ b/plugins/catalog-backend/src/ingestion/processors/bitbucket/BitbucketRepositoryParser.test.ts @@ -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, diff --git a/plugins/catalog-backend/src/ingestion/processors/bitbucket/BitbucketRepositoryParser.ts b/plugins/catalog-backend/src/ingestion/processors/bitbucket/BitbucketRepositoryParser.ts index 34a9284b3e..3407fae16a 100644 --- a/plugins/catalog-backend/src/ingestion/processors/bitbucket/BitbucketRepositoryParser.ts +++ b/plugins/catalog-backend/src/ingestion/processors/bitbucket/BitbucketRepositoryParser.ts @@ -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', + }); }; diff --git a/plugins/catalog-backend/src/ingestion/processors/results.ts b/plugins/catalog-backend/src/ingestion/processors/results.ts index 5b6f07bae4..5401f9c933 100644 --- a/plugins/catalog-backend/src/ingestion/processors/results.ts +++ b/plugins/catalog-backend/src/ingestion/processors/results.ts @@ -53,7 +53,7 @@ export function generalError( export function location( newLocation: LocationSpec, - optional: boolean, + optional?: boolean, ): CatalogProcessorResult { return { type: 'location', location: newLocation, optional }; } diff --git a/plugins/catalog-backend/src/ingestion/processors/types.ts b/plugins/catalog-backend/src/ingestion/processors/types.ts index b011281d55..722df42a04 100644 --- a/plugins/catalog-backend/src/ingestion/processors/types.ts +++ b/plugins/catalog-backend/src/ingestion/processors/types.ts @@ -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 = {