catalog-model: move LocationSpec to catalog-backend

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

.changeset/khaki-needles-smile.md

@@ -0,0 +1,5 @@
+---
+'@backstage/catalog-model': patch
+---
+
+Deprecated the `LocationSpec` export, which should now be imported from `@backstage/plugin-catalog-backend` instead.

.changeset/kind-squids-repair.md

@@ -0,0 +1,7 @@
+---
+'@backstage/plugin-catalog-backend': patch
+---
+
+Added `LocationSpec`, which was moved over from `@backstage/catalog-model`.
+
+Added `LocationInput`, which replaced `LocationSpec` where it was used in the `LocationService` and `LocationStore` interfaces. The `LocationInput` type deprecates the `presence` field, which was not being used in those contexts.

.changeset/late-mice-battle.md

@@ -0,0 +1,9 @@
+---
+'@backstage/catalog-client': patch
+'@backstage/plugin-catalog-backend-module-ldap': patch
+'@backstage/plugin-catalog-backend-module-msgraph': patch
+'@backstage/plugin-scaffolder-backend': patch
+'@backstage/plugin-techdocs': patch
+---
+
+Updated usage of the `LocationSpec` type from `@backstage/catalog-model`, which is deprecated.

docs/features/software-catalog/external-integrations.md

@@ -367,11 +367,11 @@ The class will have this basic structure:
 
 ```ts
 import { UrlReader } from '@backstage/backend-common';
-import { LocationSpec } from '@backstage/catalog-model';
 import {
   results,
   CatalogProcessor,
   CatalogProcessorEmit,
+  LocationSpec,
 } from '@backstage/plugin-catalog-backend';
 
 // A processor that reads from the fictional System-X
@@ -448,13 +448,14 @@ behavior for `system-x` that we implemented earlier.
 
 ```ts
 import { UrlReader } from '@backstage/backend-common';
-import { Entity, LocationSpec } from '@backstage/catalog-model';
+import { Entity } from '@backstage/catalog-model';
 import {
   results,
   CatalogProcessor,
   CatalogProcessorEmit,
   CatalogProcessorCache,
   CatalogProcessorParser,
+  LocationSpec,
 } from '@backstage/plugin-catalog-backend';
 
 // It's recommended to always bump the CACHE_KEY version if you make

packages/catalog-client/api-report.md

@@ -5,7 +5,6 @@
 ```ts
 import { Entity } from '@backstage/catalog-model';
 import { EntityName } from '@backstage/catalog-model';
-import { LocationSpec } from '@backstage/catalog-model';
 
 // @public
 export type AddLocationRequest = {
@@ -211,6 +210,9 @@ export interface GetEntityFacetsResponse {
 // @public
 type Location_2 = {
   id: string;
-} & LocationSpec;
+  type: string;
+  target: string;
+  presence?: 'optional' | 'required';
+};
 export { Location_2 as Location };
 ```

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

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { Entity, EntityName, LocationSpec } from '@backstage/catalog-model';
+import { Entity, EntityName } from '@backstage/catalog-model';
 
 /**
  * This symbol can be used in place of a value when passed to filters in e.g.
@@ -242,7 +242,11 @@ export interface CatalogRequestOptions {
  */
 export type Location = {
   id: string;
-} & LocationSpec;
+  type: string;
+  target: string;
+  /** @deprecated This field is is ignored */
+  presence?: 'optional' | 'required';
+};
 
 /**
  * The request type for {@link CatalogClient.addLocation}.

packages/catalog-model/api-report.md

@@ -363,7 +363,7 @@ export { LocationEntityV1alpha1 };
 // @public
 export const locationEntityV1alpha1Validator: KindValidator;
 
-// @public
+// @public @deprecated
 export type LocationSpec = {
   type: string;
   target: string;

packages/catalog-model/src/location/helpers.ts

@@ -21,9 +21,6 @@ import { ANNOTATION_LOCATION } from './annotation';
 /**
  * Parses a string form location reference.
  *
- * Note that the return type is not `LocationSpec`, because we do not want to
- * conflate the string form with the additional properties of that type.
- *
  * @public
  * @param ref - A string-form location reference, e.g. `'url:https://host'`
  * @returns A location reference, e.g. `{ type: 'url', target: 'https://host' }`
@@ -36,11 +33,6 @@ export function parseLocationReference(ref: string) {
 /**
  * Parses a string form location reference.
  *
- * @remarks
- *
- * Note that the return type is not `LocationSpec`, because we do not want to
- * conflate the string form with the additional properties of that type.
- *
  * @public
  * @param ref - A string-form location ref, e.g. `'url:https://host'`
  * @returns A location ref, e.g. `{ type: 'url', target: 'https://host' }`
@@ -83,11 +75,6 @@ export function parseLocationRef(ref: string): {
 /**
  * Turns a location reference into its string form.
  *
- * @remarks
- *
- * Note that the input type is not `LocationSpec`, because we do not want to
- * conflate the string form with the additional properties of that type.
- *
  * @public
  * @param ref - A location reference, e.g. `{ type: 'url', target: 'https://host' }`
  * @returns A string-form location reference, e.g. `'url:https://host'`
@@ -103,11 +90,6 @@ export function stringifyLocationReference(ref: {
 /**
  * Turns a location ref into its string form.
  *
- * @remarks
- *
- * Note that the input type is not `LocationSpec`, because we do not want to
- * conflate the string form with the additional properties of that type.
- *
  * @public
  * @param ref - A location ref, e.g. `{ type: 'url', target: 'https://host' }`
  * @returns A string-form location ref, e.g. `'url:https://host'`

packages/catalog-model/src/location/types.ts

@@ -24,6 +24,7 @@
  *  default value: 'required'.
  *
  * @public
+ * @deprecated Import from `@backstage/plugin-catalog-backend` instead.
  */
 export type LocationSpec = {
   type: string;

plugins/catalog-backend-module-aws/api-report.md

@@ -6,7 +6,7 @@
 import { CatalogProcessor } from '@backstage/plugin-catalog-backend';
 import { CatalogProcessorEmit } from '@backstage/plugin-catalog-backend';
 import { Config } from '@backstage/config';
-import { LocationSpec } from '@backstage/catalog-model';
+import { LocationSpec } from '@backstage/plugin-catalog-backend';
 import { Logger as Logger_2 } from 'winston';
 
 // @public

plugins/catalog-backend-module-aws/src/processors/AwsOrganizationCloudAccountProcessor.ts

@@ -14,11 +14,12 @@
  * limitations under the License.
  */
 
-import { LocationSpec, ResourceEntityV1alpha1 } from '@backstage/catalog-model';
+import { ResourceEntityV1alpha1 } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
 import {
   CatalogProcessor,
   CatalogProcessorEmit,
+  LocationSpec,
   results,
 } from '@backstage/plugin-catalog-backend';
 import AWS, { Credentials, Organizations } from 'aws-sdk';

plugins/catalog-backend-module-ldap/api-report.md

@@ -11,7 +11,7 @@ import { EntityProvider } from '@backstage/plugin-catalog-backend';
 import { EntityProviderConnection } from '@backstage/plugin-catalog-backend';
 import { GroupEntity } from '@backstage/catalog-model';
 import { JsonValue } from '@backstage/types';
-import { LocationSpec } from '@backstage/catalog-model';
+import { LocationSpec } from '@backstage/plugin-catalog-backend';
 import { Logger as Logger_2 } from 'winston';
 import { SearchEntry } from 'ldapjs';
 import { SearchOptions } from 'ldapjs';

plugins/catalog-backend-module-ldap/src/processors/LdapOrgReaderProcessor.ts

@@ -14,7 +14,6 @@
  * limitations under the License.
  */
 
-import { LocationSpec } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
 import { Logger } from 'winston';
 import {
@@ -28,6 +27,7 @@ import {
 import {
   CatalogProcessor,
   CatalogProcessorEmit,
+  LocationSpec,
   results,
 } from '@backstage/plugin-catalog-backend';
 

plugins/catalog-backend-module-msgraph/api-report.md

@@ -9,7 +9,7 @@ import { Config } from '@backstage/config';
 import { EntityProvider } from '@backstage/plugin-catalog-backend';
 import { EntityProviderConnection } from '@backstage/plugin-catalog-backend';
 import { GroupEntity } from '@backstage/catalog-model';
-import { LocationSpec } from '@backstage/catalog-model';
+import { LocationSpec } from '@backstage/plugin-catalog-backend';
 import { Logger as Logger_2 } from 'winston';
 import * as MicrosoftGraph from '@microsoft/microsoft-graph-types';
 import * as msal from '@azure/msal-node';

plugins/catalog-backend-module-msgraph/src/processors/MicrosoftGraphOrgReaderProcessor.ts

@@ -14,11 +14,11 @@
  * limitations under the License.
  */
 
-import { LocationSpec } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
 import {
   CatalogProcessor,
   CatalogProcessorEmit,
+  LocationSpec,
   results,
 } from '@backstage/plugin-catalog-backend';
 import { Logger } from 'winston';

plugins/catalog-backend/api-report.md

@@ -22,7 +22,6 @@ 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';
-import { LocationSpec } from '@backstage/catalog-model';
 import { Logger as Logger_2 } from 'winston';
 import { Permission } from '@backstage/plugin-permission-common';
 import { PermissionAuthorizer } from '@backstage/plugin-permission-common';
@@ -812,11 +811,21 @@ export type LocationEntityProcessorOptions = {
   integrations: ScmIntegrationRegistry;
 };
 
+// @public
+export interface LocationInput {
+  // @deprecated (undocumented)
+  presence?: 'optional' | 'required';
+  // (undocumented)
+  target: string;
+  // (undocumented)
+  type: string;
+}
+
 // @public
 export interface LocationService {
   // (undocumented)
   createLocation(
-    spec: LocationSpec,
+    location: LocationInput,
     dryRun: boolean,
     options?: {
       authorizationToken?: string;
@@ -846,10 +855,17 @@ export interface LocationService {
   }): Promise<Location_2[]>;
 }
 
+// @public
+export type LocationSpec = {
+  type: string;
+  target: string;
+  presence?: 'optional' | 'required';
+};
+
 // @public
 export interface LocationStore {
   // (undocumented)
-  createLocation(spec: LocationSpec): Promise<Location_2>;
+  createLocation(location: LocationInput): Promise<Location_2>;
   // (undocumented)
   deleteLocation(id: string): Promise<void>;
   // (undocumented)

plugins/catalog-backend/src/ingestion/CatalogRules.test.ts

@@ -14,9 +14,10 @@
  * limitations under the License.
  */
 
-import { Entity, LocationSpec } from '@backstage/catalog-model';
+import { Entity } from '@backstage/catalog-model';
 import { ConfigReader } from '@backstage/config';
 import { DefaultCatalogRulesEnforcer } from './CatalogRules';
+import { LocationSpec } from './processors';
 
 const entity = {
   user: {

plugins/catalog-backend/src/ingestion/CatalogRules.ts

@@ -15,8 +15,9 @@
  */
 
 import { Config } from '@backstage/config';
-import { LocationSpec, Entity } from '@backstage/catalog-model';
+import { Entity } from '@backstage/catalog-model';
 import path from 'path';
+import { LocationSpec } from './processors';
 
 /**
  * Rules to apply to catalog entities.

plugins/catalog-backend/src/ingestion/processors/AnnotateLocationEntityProcessor.test.ts

@@ -14,9 +14,10 @@
  * limitations under the License.
  */
 
-import { Entity, LocationSpec } from '@backstage/catalog-model';
+import { Entity } from '@backstage/catalog-model';
 import { ConfigReader } from '@backstage/config';
 import { ScmIntegrations } from '@backstage/integration';
+import { LocationSpec } from './types';
 import { AnnotateLocationEntityProcessor } from './AnnotateLocationEntityProcessor';
 
 describe('AnnotateLocationEntityProcessor', () => {

plugins/catalog-backend/src/ingestion/processors/AnnotateLocationEntityProcessor.ts

@@ -21,12 +21,11 @@ import {
   ANNOTATION_SOURCE_LOCATION,
   ANNOTATION_VIEW_URL,
   Entity,
-  LocationSpec,
   stringifyLocationRef,
 } from '@backstage/catalog-model';
 import { ScmIntegrationRegistry } from '@backstage/integration';
 import { identity, merge, pickBy } from 'lodash';
-import { CatalogProcessor, CatalogProcessorEmit } from './types';
+import { CatalogProcessor, CatalogProcessorEmit, LocationSpec } from './types';
 
 /** @public */
 export class AnnotateLocationEntityProcessor implements CatalogProcessor {

plugins/catalog-backend/src/ingestion/processors/AnnotateScmSlugEntityProcessor.test.ts

@@ -13,9 +13,10 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { Entity, LocationSpec } from '@backstage/catalog-model';
+import { Entity } from '@backstage/catalog-model';
 import { ConfigReader } from '@backstage/config';
 import { AnnotateScmSlugEntityProcessor } from './AnnotateScmSlugEntityProcessor';
+import { LocationSpec } from './types';
 
 describe('AnnotateScmSlugEntityProcessor', () => {
   describe('github', () => {

plugins/catalog-backend/src/ingestion/processors/AnnotateScmSlugEntityProcessor.ts

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { Entity, LocationSpec } from '@backstage/catalog-model';
+import { Entity } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
 import {
   ScmIntegrationRegistry,
@@ -21,7 +21,7 @@ import {
 } from '@backstage/integration';
 import parseGitUrl from 'git-url-parse';
 import { identity, merge, pickBy } from 'lodash';
-import { CatalogProcessor } from './types';
+import { CatalogProcessor, LocationSpec } from './types';
 
 const GITHUB_ACTIONS_ANNOTATION = 'github.com/project-slug';
 

plugins/catalog-backend/src/ingestion/processors/AwsS3DiscoveryProcessor.ts

@@ -15,7 +15,6 @@
  */
 
 import { UrlReader } from '@backstage/backend-common';
-import { LocationSpec } from '@backstage/catalog-model';
 import { isError } from '@backstage/errors';
 import limiterFactory from 'p-limit';
 import * as result from './results';
@@ -23,6 +22,7 @@ import {
   CatalogProcessor,
   CatalogProcessorEmit,
   CatalogProcessorParser,
+  LocationSpec,
 } from './types';
 
 /** @public */

plugins/catalog-backend/src/ingestion/processors/AzureDevOpsDiscoveryProcessor.test.ts

@@ -15,13 +15,13 @@
  */
 
 import { getVoidLogger } from '@backstage/backend-common';
-import { LocationSpec } from '@backstage/catalog-model';
 import { ConfigReader } from '@backstage/config';
 import { codeSearch } from './azure';
 import {
   AzureDevOpsDiscoveryProcessor,
   parseUrl,
 } from './AzureDevOpsDiscoveryProcessor';
+import { LocationSpec } from './types';
 
 jest.mock('./azure');
 const mockCodeSearch = codeSearch as jest.MockedFunction<typeof codeSearch>;

plugins/catalog-backend/src/ingestion/processors/AzureDevOpsDiscoveryProcessor.ts

@@ -14,7 +14,6 @@
  * limitations under the License.
  */
 
-import { LocationSpec } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
 import {
   ScmIntegrationRegistry,
@@ -22,7 +21,7 @@ import {
 } from '@backstage/integration';
 import { Logger } from 'winston';
 import * as results from './results';
-import { CatalogProcessor, CatalogProcessorEmit } from './types';
+import { CatalogProcessor, CatalogProcessorEmit, LocationSpec } from './types';
 import { codeSearch } from './azure';
 
 /**

plugins/catalog-backend/src/ingestion/processors/BitbucketDiscoveryProcessor.test.ts

@@ -16,13 +16,13 @@
 import { getVoidLogger } from '@backstage/backend-common';
 import { BitbucketDiscoveryProcessor } from './BitbucketDiscoveryProcessor';
 import { ConfigReader } from '@backstage/config';
-import { LocationSpec } from '@backstage/catalog-model';
 import {
   BitbucketRepository20,
   BitbucketRepositoryParser,
   PagedResponse,
   PagedResponse20,
 } from './bitbucket';
+import { LocationSpec } from './types';
 import { results } from './index';
 import { RequestHandler, rest } from 'msw';
 import { setupServer } from 'msw/node';

plugins/catalog-backend/src/ingestion/processors/BitbucketDiscoveryProcessor.ts

@@ -21,7 +21,6 @@ import {
   ScmIntegrationRegistry,
   ScmIntegrations,
 } from '@backstage/integration';
-import { LocationSpec } from '@backstage/catalog-model';
 import {
   BitbucketRepositoryParser,
   BitbucketClient,
@@ -31,7 +30,7 @@ import {
   BitbucketRepository,
   BitbucketRepository20,
 } from './bitbucket';
-import { CatalogProcessor, CatalogProcessorEmit } from './types';
+import { CatalogProcessor, CatalogProcessorEmit, LocationSpec } from './types';
 
 const DEFAULT_BRANCH = 'master';
 const DEFAULT_CATALOG_LOCATION = '/catalog-info.yaml';

plugins/catalog-backend/src/ingestion/processors/BuiltinKindsEntityProcessor.ts

@@ -26,7 +26,6 @@ import {
   GroupEntity,
   groupEntityV1alpha1Validator,
   locationEntityV1alpha1Validator,
-  LocationSpec,
   parseEntityRef,
   RELATION_API_CONSUMED_BY,
   RELATION_API_PROVIDED_BY,
@@ -54,7 +53,7 @@ import {
   templateEntityV1beta2Validator,
 } from '@backstage/plugin-scaffolder-common';
 import * as result from './results';
-import { CatalogProcessor, CatalogProcessorEmit } from './types';
+import { CatalogProcessor, CatalogProcessorEmit, LocationSpec } from './types';
 
 /** @public */
 export class BuiltinKindsEntityProcessor implements CatalogProcessor {

plugins/catalog-backend/src/ingestion/processors/CodeOwnersProcessor.test.ts

@@ -15,9 +15,9 @@
  */
 
 import { getVoidLogger } from '@backstage/backend-common';
-import { LocationSpec } from '@backstage/catalog-model';
 import { ConfigReader } from '@backstage/config';
 import { CodeOwnersProcessor } from './CodeOwnersProcessor';
+import { LocationSpec } from './types';
 
 const mockCodeOwnersText = () => `
 *       @acme/team-foo @acme/team-bar

plugins/catalog-backend/src/ingestion/processors/CodeOwnersProcessor.ts

@@ -15,7 +15,7 @@
  */
 
 import { UrlReader } from '@backstage/backend-common';
-import { Entity, LocationSpec } from '@backstage/catalog-model';
+import { Entity } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
 import {
   ScmIntegrationRegistry,
@@ -23,7 +23,7 @@ import {
 } from '@backstage/integration';
 import { Logger } from 'winston';
 import { findCodeOwnerByTarget } from './codeowners';
-import { CatalogProcessor } from './types';
+import { CatalogProcessor, LocationSpec } from './types';
 
 const ALLOWED_KINDS = ['API', 'Component', 'Domain', 'Resource', 'System'];
 

plugins/catalog-backend/src/ingestion/processors/FileReaderProcessor.ts

@@ -14,7 +14,6 @@
  * limitations under the License.
  */
 
-import { LocationSpec } from '@backstage/catalog-model';
 import fs from 'fs-extra';
 import g from 'glob';
 import path from 'path';
@@ -24,6 +23,7 @@ import {
   CatalogProcessor,
   CatalogProcessorEmit,
   CatalogProcessorParser,
+  LocationSpec,
 } from './types';
 
 const glob = promisify(g);

plugins/catalog-backend/src/ingestion/processors/GitLabDiscoveryProcessor.test.ts

@@ -16,11 +16,11 @@
 
 import { ConfigReader } from '@backstage/config';
 import { getVoidLogger } from '@backstage/backend-common';
-import { LocationSpec } from '@backstage/catalog-model';
 import { GitLabDiscoveryProcessor, parseUrl } from './GitLabDiscoveryProcessor';
 import { setupServer } from 'msw/node';
 import { rest } from 'msw';
 import { GitLabProject } from './gitlab';
+import { LocationSpec } from './types';
 
 const server = setupServer();
 

plugins/catalog-backend/src/ingestion/processors/GitLabDiscoveryProcessor.ts

@@ -14,7 +14,6 @@
  * limitations under the License.
  */
 
-import { LocationSpec } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
 import {
   ScmIntegrationRegistry,
@@ -22,7 +21,7 @@ import {
 } from '@backstage/integration';
 import { Logger } from 'winston';
 import * as results from './results';
-import { CatalogProcessor, CatalogProcessorEmit } from './types';
+import { CatalogProcessor, CatalogProcessorEmit, LocationSpec } from './types';
 import { GitLabClient, GitLabProject, paginated } from './gitlab';
 import {
   CacheClient,

plugins/catalog-backend/src/ingestion/processors/GithubDiscoveryProcessor.test.ts

@@ -15,9 +15,9 @@
  */
 
 import { getVoidLogger } from '@backstage/backend-common';
-import { LocationSpec } from '@backstage/catalog-model';
 import { GithubDiscoveryProcessor, parseUrl } from './GithubDiscoveryProcessor';
 import { getOrganizationRepositories } from './github';
+import { LocationSpec } from './types';
 import { ConfigReader } from '@backstage/config';
 import {
   ScmIntegrations,

plugins/catalog-backend/src/ingestion/processors/GithubDiscoveryProcessor.ts

@@ -14,7 +14,6 @@
  * limitations under the License.
  */
 
-import { LocationSpec } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
 import {
   DefaultGithubCredentialsProvider,
@@ -26,7 +25,7 @@ import { graphql } from '@octokit/graphql';
 import { Logger } from 'winston';
 import { getOrganizationRepositories } from './github';
 import * as results from './results';
-import { CatalogProcessor, CatalogProcessorEmit } from './types';
+import { CatalogProcessor, CatalogProcessorEmit, LocationSpec } from './types';
 
 /**
  * Extracts repositories out of a GitHub org.

plugins/catalog-backend/src/ingestion/processors/GithubMultiOrgReaderProcessor.ts

@@ -14,7 +14,6 @@
  * limitations under the License.
  */
 
-import { LocationSpec } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
 import {
   DefaultGithubCredentialsProvider,
@@ -33,7 +32,7 @@ import {
   readGithubMultiOrgConfig,
 } from './github';
 import * as results from './results';
-import { CatalogProcessor, CatalogProcessorEmit } from './types';
+import { CatalogProcessor, CatalogProcessorEmit, LocationSpec } from './types';
 import { buildOrgHierarchy } from './util/org';
 
 /**

plugins/catalog-backend/src/ingestion/processors/GithubOrgReaderProcessor.test.ts

@@ -14,7 +14,6 @@
  * limitations under the License.
  */
 import { getVoidLogger } from '@backstage/backend-common';
-import { LocationSpec } from '@backstage/catalog-model';
 import { ConfigReader } from '@backstage/config';
 import {
   ScmIntegrations,
@@ -22,6 +21,7 @@ import {
 } from '@backstage/integration';
 import { graphql } from '@octokit/graphql';
 import { GithubOrgReaderProcessor } from './GithubOrgReaderProcessor';
+import { LocationSpec } from './types';
 
 jest.mock('@octokit/graphql');
 

plugins/catalog-backend/src/ingestion/processors/GithubOrgReaderProcessor.ts

@@ -14,7 +14,6 @@
  * limitations under the License.
  */
 
-import { LocationSpec } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
 import {
   GithubCredentialType,
@@ -31,7 +30,7 @@ import {
   parseGitHubOrgUrl,
 } from './github';
 import * as results from './results';
-import { CatalogProcessor, CatalogProcessorEmit } from './types';
+import { CatalogProcessor, CatalogProcessorEmit, LocationSpec } from './types';
 import { assignGroupsToUsers, buildOrgHierarchy } from './util/org';
 
 type GraphQL = typeof graphql;

plugins/catalog-backend/src/ingestion/processors/LocationEntityProcessor.test.ts

@@ -14,7 +14,6 @@
  * limitations under the License.
  */
 
-import { LocationSpec } from '@backstage/catalog-model';
 import { ConfigReader } from '@backstage/config';
 import {
   ScmIntegrations,
@@ -22,6 +21,7 @@ import {
 } from '@backstage/integration';
 import path from 'path';
 import { toAbsoluteUrl } from './LocationEntityProcessor';
+import { LocationSpec } from './types';
 
 describe('LocationEntityProcessor', () => {
   describe('toAbsoluteUrl', () => {

plugins/catalog-backend/src/ingestion/processors/LocationEntityProcessor.ts

@@ -14,11 +14,11 @@
  * limitations under the License.
  */
 
-import { Entity, LocationEntity, LocationSpec } from '@backstage/catalog-model';
+import { Entity, LocationEntity } from '@backstage/catalog-model';
 import { ScmIntegrationRegistry } from '@backstage/integration';
 import path from 'path';
 import * as result from './results';
-import { CatalogProcessor, CatalogProcessorEmit } from './types';
+import { CatalogProcessor, CatalogProcessorEmit, LocationSpec } from './types';
 
 export function toAbsoluteUrl(
   integrations: ScmIntegrationRegistry,

plugins/catalog-backend/src/ingestion/processors/PlaceholderProcessor.ts

@@ -15,11 +15,11 @@
  */
 
 import { UrlReader } from '@backstage/backend-common';
-import { Entity, LocationSpec } from '@backstage/catalog-model';
+import { Entity } from '@backstage/catalog-model';
 import { JsonValue } from '@backstage/types';
 import { ScmIntegrationRegistry } from '@backstage/integration';
 import yaml from 'yaml';
-import { CatalogProcessor } from './types';
+import { CatalogProcessor, LocationSpec } from './types';
 
 /** @public */
 export type PlaceholderResolverRead = (url: string) => Promise<Buffer>;

plugins/catalog-backend/src/ingestion/processors/StaticLocationProcessor.ts

@@ -14,10 +14,9 @@
  * limitations under the License.
  */
 
-import { LocationSpec } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
 import * as result from './results';
-import { CatalogProcessorEmit } from './types';
+import { CatalogProcessorEmit, LocationSpec } from './types';
 
 /**
  * @deprecated no longer in use, replaced by the ConfigLocationEntityProvider.

plugins/catalog-backend/src/ingestion/processors/UrlReaderProcessor.ts

@@ -15,7 +15,7 @@
  */
 
 import { UrlReader } from '@backstage/backend-common';
-import { Entity, LocationSpec } from '@backstage/catalog-model';
+import { Entity } from '@backstage/catalog-model';
 import { assertError } from '@backstage/errors';
 import parseGitUrl from 'git-url-parse';
 import limiterFactory from 'p-limit';
@@ -28,6 +28,7 @@ import {
   CatalogProcessorEntityResult,
   CatalogProcessorParser,
   CatalogProcessorResult,
+  LocationSpec,
 } from './types';
 
 const CACHE_KEY = 'v1';

plugins/catalog-backend/src/ingestion/processors/results.ts

@@ -15,8 +15,8 @@
  */
 
 import { InputError, NotFoundError } from '@backstage/errors';
-import { Entity, LocationSpec } from '@backstage/catalog-model';
-import { CatalogProcessorResult } from './types';
+import { Entity } from '@backstage/catalog-model';
+import { CatalogProcessorResult, LocationSpec } from './types';
 import { EntityRelationSpec } from '../../processing/types';
 
 /** @public */

plugins/catalog-backend/src/ingestion/processors/types.ts

@@ -14,10 +14,27 @@
  * limitations under the License.
  */
 
-import { Entity, LocationSpec } from '@backstage/catalog-model';
+import { Entity } from '@backstage/catalog-model';
 import { JsonValue } from '@backstage/types';
 import { EntityRelationSpec } from '../../processing/types';
 
+/**
+ * Holds the entity location information.
+ *
+ * @remarks
+ *
+ *  `presence` flag: when using repo importer plugin, location is being created before the component yaml file is merged to the main branch.
+ *  This flag is then set to indicate that the file can be not present.
+ *  default value: 'required'.
+ *
+ * @public
+ */
+export type LocationSpec = {
+  type: string;
+  target: string;
+  presence?: 'optional' | 'required';
+};
+
 /**
  * @public
  */

plugins/catalog-backend/src/ingestion/processors/util/parse.ts

@@ -14,15 +14,15 @@
  * limitations under the License.
  */
 
-import {
-  Entity,
-  LocationSpec,
-  stringifyLocationRef,
-} from '@backstage/catalog-model';
+import { Entity, stringifyLocationRef } from '@backstage/catalog-model';
 import lodash from 'lodash';
 import yaml from 'yaml';
 import * as result from '../results';
-import { CatalogProcessorParser, CatalogProcessorResult } from '../types';
+import {
+  CatalogProcessorParser,
+  CatalogProcessorResult,
+  LocationSpec,
+} from '../types';
 
 /** @public */
 export function* parseEntityYaml(

plugins/catalog-backend/src/ingestion/types.ts

@@ -14,8 +14,9 @@
  * limitations under the License.
  */
 
-import { Entity, LocationSpec } from '@backstage/catalog-model';
+import { Entity } from '@backstage/catalog-model';
 import { RecursivePartial } from '../util/RecursivePartial';
+import { LocationSpec } from './processors';
 
 /** @public */
 export type LocationAnalyzer = {

plugins/catalog-backend/src/processing/DefaultCatalogProcessingOrchestrator.test.ts

@@ -21,7 +21,6 @@ import {
   Entity,
   EntityPolicies,
   LocationEntity,
-  LocationSpec,
 } from '@backstage/catalog-model';
 import { ScmIntegrations } from '@backstage/integration';
 import {
@@ -29,6 +28,7 @@ import {
   CatalogProcessorCache,
   CatalogProcessorEmit,
   CatalogProcessorParser,
+  LocationSpec,
   results,
 } from '../ingestion';
 import { CatalogRulesEnforcer } from '../ingestion/CatalogRules';

plugins/catalog-backend/src/processing/DefaultCatalogProcessingOrchestrator.ts

@@ -18,7 +18,6 @@ import {
   Entity,
   EntityPolicy,
   LocationEntity,
-  LocationSpec,
   parseLocationRef,
   stringifyEntityRef,
   stringifyLocationRef,
@@ -36,6 +35,7 @@ import { Logger } from 'winston';
 import {
   CatalogProcessor,
   CatalogProcessorParser,
+  LocationSpec,
 } from '../ingestion/processors';
 import * as results from '../ingestion/processors/results';
 import {

plugins/catalog-backend/src/processing/util.ts

@@ -19,7 +19,6 @@ import {
   entityEnvelopeSchemaValidator,
   entitySchemaValidator,
   LocationEntity,
-  LocationSpec,
   ANNOTATION_LOCATION,
   ANNOTATION_ORIGIN_LOCATION,
   stringifyEntityRef,
@@ -28,6 +27,7 @@ import { JsonObject, JsonValue } from '@backstage/types';
 import { InputError } from '@backstage/errors';
 import { ScmIntegrationRegistry } from '@backstage/integration';
 import path from 'path';
+import { LocationSpec } from '../ingestion';
 
 export function isLocationEntity(entity: Entity): entity is LocationEntity {
   return entity.kind === 'Location';

plugins/catalog-backend/src/providers/DefaultLocationStore.ts

@@ -14,7 +14,6 @@
  * limitations under the License.
  */
 
-import { LocationSpec } from '@backstage/catalog-model';
 import { Location } from '@backstage/catalog-client';
 import { ConflictError, NotFoundError } from '@backstage/errors';
 import { Knex } from 'knex';
@@ -23,7 +22,7 @@ import { DbLocationsRow } from '../database/tables';
 import { getEntityLocationRef } from '../processing/util';
 import { EntityProvider, EntityProviderConnection } from './types';
 import { locationSpecToLocationEntity } from '../util/conversion';
-import { LocationStore } from '../service';
+import { LocationInput, LocationStore } from '../service';
 
 export class DefaultLocationStore implements LocationStore, EntityProvider {
   private _connection: EntityProviderConnection | undefined;
@@ -34,25 +33,25 @@ export class DefaultLocationStore implements LocationStore, EntityProvider {
     return 'DefaultLocationStore';
   }
 
-  async createLocation(spec: LocationSpec): Promise<Location> {
+  async createLocation(input: LocationInput): Promise<Location> {
     const location = await this.db.transaction(async tx => {
-      // Attempt to find a previous location matching the spec
+      // Attempt to find a previous location matching the input
       const previousLocations = await this.locations(tx);
-      // TODO: when location id's are a compilation of spec target we can remove this full
+      // TODO: when location id's are a compilation of input target we can remove this full
       // lookup of locations first and just grab the by that instead.
       const previousLocation = previousLocations.some(
-        l => spec.type === l.type && spec.target === l.target,
+        l => input.type === l.type && input.target === l.target,
       );
       if (previousLocation) {
         throw new ConflictError(
-          `Location ${spec.type}:${spec.target} already exists`,
+          `Location ${input.type}:${input.target} already exists`,
         );
       }
 
       const inner: DbLocationsRow = {
         id: uuid(),
-        type: spec.type,
-        target: spec.target,
+        type: input.type,
+        target: input.target,
       };
 
       await tx<DbLocationsRow>('locations').insert(inner);

plugins/catalog-backend/src/service/AuthorizedLocationService.ts

@@ -15,7 +15,7 @@
  */
 
 import { Location } from '@backstage/catalog-client';
-import { LocationSpec, Entity } from '@backstage/catalog-model';
+import { Entity } from '@backstage/catalog-model';
 import { NotAllowedError, NotFoundError } from '@backstage/errors';
 import {
   catalogLocationCreatePermission,
@@ -26,7 +26,7 @@ import {
   AuthorizeResult,
   PermissionAuthorizer,
 } from '@backstage/plugin-permission-common';
-import { LocationService } from './types';
+import { LocationInput, LocationService } from './types';
 
 export class AuthorizedLocationService implements LocationService {
   constructor(
@@ -35,7 +35,7 @@ export class AuthorizedLocationService implements LocationService {
   ) {}
 
   async createLocation(
-    spec: LocationSpec,
+    spec: LocationInput,
     dryRun: boolean,
     options?: {
       authorizationToken?: string;

plugins/catalog-backend/src/service/DefaultLocationService.ts

@@ -15,7 +15,6 @@
  */
 import {
   Entity,
-  LocationSpec,
   ANNOTATION_LOCATION,
   ANNOTATION_ORIGIN_LOCATION,
   stringifyEntityRef,
@@ -25,7 +24,7 @@ import {
   CatalogProcessingOrchestrator,
   DeferredEntity,
 } from '../processing/types';
-import { LocationService, LocationStore } from './types';
+import { LocationInput, LocationService, LocationStore } from './types';
 import { locationSpecToMetadataName } from '../util/conversion';
 
 export class DefaultLocationService implements LocationService {
@@ -35,13 +34,13 @@ export class DefaultLocationService implements LocationService {
   ) {}
 
   async createLocation(
-    spec: LocationSpec,
+    input: LocationInput,
     dryRun: boolean,
   ): Promise<{ location: Location; entities: Entity[]; exists?: boolean }> {
     if (dryRun) {
-      return this.dryRunCreateLocation(spec);
+      return this.dryRunCreateLocation(input);
     }
-    const location = await this.store.createLocation(spec);
+    const location = await this.store.createLocation(input);
     return { location, entities: [] };
   }
 
@@ -93,7 +92,7 @@ export class DefaultLocationService implements LocationService {
   }
 
   private async dryRunCreateLocation(
-    spec: LocationSpec,
+    spec: LocationInput,
   ): Promise<{ location: Location; entities: Entity[]; exists?: boolean }> {
     // Run the existence check in parallel with the processing
     const existsPromise = this.store

plugins/catalog-backend/src/service/createRouter.test.ts

@@ -18,11 +18,11 @@ import { getVoidLogger } from '@backstage/backend-common';
 import { ConfigReader } from '@backstage/config';
 import { NotFoundError } from '@backstage/errors';
 import type { Location } from '@backstage/catalog-client';
-import type { Entity, LocationSpec } from '@backstage/catalog-model';
+import type { Entity } from '@backstage/catalog-model';
 import express from 'express';
 import request from 'supertest';
 import { EntitiesCatalog } from '../catalog';
-import { LocationService, RefreshService } from './types';
+import { LocationInput, LocationService, RefreshService } from './types';
 import { basicEntityFilter } from './request';
 import { createRouter } from './createRouter';
 import { AuthorizeResult } from '@backstage/plugin-permission-common';
@@ -299,7 +299,7 @@ describe('createRouter readonly disabled', () => {
       const spec = {
         typez: 'b',
         target: 'c',
-      } as unknown as LocationSpec;
+      } as unknown as LocationInput;
 
       const response = await request(app)
         .post('/locations')
@@ -311,7 +311,7 @@ describe('createRouter readonly disabled', () => {
     });
 
     it('passes the body down', async () => {
-      const spec: LocationSpec = {
+      const spec: LocationInput = {
         type: 'b',
         target: 'c',
       };
@@ -339,7 +339,7 @@ describe('createRouter readonly disabled', () => {
     });
 
     it('supports dry run', async () => {
-      const spec: LocationSpec = {
+      const spec: LocationInput = {
         type: 'b',
         target: 'c',
       };
@@ -506,7 +506,7 @@ describe('createRouter readonly enabled', () => {
 
   describe('POST /locations', () => {
     it('is not allowed', async () => {
-      const spec: LocationSpec = {
+      const spec: LocationInput = {
         type: 'b',
         target: 'c',
       };
@@ -522,7 +522,7 @@ describe('createRouter readonly enabled', () => {
     });
 
     it('supports dry run', async () => {
-      const spec: LocationSpec = {
+      const spec: LocationInput = {
         type: 'b',
         target: 'c',
       };

plugins/catalog-backend/src/service/createRouter.ts

@@ -32,7 +32,7 @@ import {
 } from './request';
 import {
   disallowReadonlyMode,
-  locationSpec,
+  locationInput,
   validateRequestBody,
 } from './util';
 import { RefreshOptions, LocationService, RefreshService } from './types';
@@ -175,7 +175,7 @@ export async function createRouter(
   if (locationService) {
     router
       .post('/locations', async (req, res) => {
-        const location = await validateRequestBody(req, locationSpec);
+        const location = await validateRequestBody(req, locationInput);
         const dryRun = yn(req.query.dryRun, { default: false });
 
         // when in dryRun addLocation is effectively a read operation so we don't
@@ -218,9 +218,9 @@ export async function createRouter(
     router.post('/analyze-location', async (req, res) => {
       const body = await validateRequestBody(
         req,
-        z.object({ location: locationSpec }),
+        z.object({ location: locationInput }),
       );
-      const schema = z.object({ location: locationSpec });
+      const schema = z.object({ location: locationInput });
       const output = await locationAnalyzer.analyzeLocation(schema.parse(body));
       res.status(200).json(output);
     });

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

@@ -19,6 +19,7 @@ export type {
   RefreshService,
   RefreshOptions,
   LocationStore,
+  LocationInput,
 } from './types';
 export { createRouter } from './createRouter';
 export type { RouterOptions } from './createRouter';

plugins/catalog-backend/src/service/types.ts

@@ -14,16 +14,28 @@
  * limitations under the License.
  */
 
-import { Entity, LocationSpec } from '@backstage/catalog-model';
+import { Entity } from '@backstage/catalog-model';
 import { Location } from '@backstage/catalog-client';
 
+/**
+ * Holds the information required to create a new location in the catalog location store.
+ *
+ * @public
+ */
+export interface LocationInput {
+  type: string;
+  target: string;
+  /** @deprecated This field is ignored and will be removed */
+  presence?: 'optional' | 'required';
+}
+
 /**
  * The location service manages entity locations.
  * @public
  */
 export interface LocationService {
   createLocation(
-    spec: LocationSpec,
+    location: LocationInput,
     dryRun: boolean,
     options?: {
       authorizationToken?: string;
@@ -67,7 +79,7 @@ export interface RefreshService {
  * Interacts with the database to manage locations.
  * @public */
 export interface LocationStore {
-  createLocation(spec: LocationSpec): Promise<Location>;
+  createLocation(location: LocationInput): Promise<Location>;
   listLocations(): Promise<Location[]>;
   getLocation(id: string): Promise<Location>;
   deleteLocation(id: string): Promise<void>;

plugins/catalog-backend/src/service/util.ts

@@ -40,7 +40,7 @@ export async function requireRequestBody(req: Request): Promise<unknown> {
   return body;
 }
 
-export const locationSpec = z
+export const locationInput = z
   .object({
     type: z.string(),
     target: z.string(),

plugins/catalog-backend/src/util/conversion.ts

@@ -17,13 +17,13 @@
 import {
   Entity,
   LocationEntityV1alpha1,
-  LocationSpec,
   ANNOTATION_LOCATION,
   ANNOTATION_ORIGIN_LOCATION,
   stringifyEntityRef,
   stringifyLocationRef,
 } from '@backstage/catalog-model';
 import { createHash } from 'crypto';
+import { LocationSpec } from '../ingestion';
 
 export function locationSpecToMetadataName(location: LocationSpec) {
   const hash = createHash('sha1')

plugins/scaffolder-backend/api-report.md

@@ -18,7 +18,7 @@ import { GithubCredentialsProvider } from '@backstage/integration';
 import { JsonObject } from '@backstage/types';
 import { JsonValue } from '@backstage/types';
 import { Knex } from 'knex';
-import { LocationSpec } from '@backstage/catalog-model';
+import { LocationSpec } from '@backstage/plugin-catalog-backend';
 import { Logger as Logger_2 } from 'winston';
 import { Octokit } from 'octokit';
 import { PluginDatabaseManager } from '@backstage/backend-common';

plugins/scaffolder-backend/src/processor/ScaffolderEntitiesProcessor.ts

@@ -17,7 +17,6 @@
 import {
   Entity,
   getEntityName,
-  LocationSpec,
   parseEntityRef,
   RELATION_OWNED_BY,
   RELATION_OWNER_OF,
@@ -25,6 +24,7 @@ import {
 import {
   CatalogProcessor,
   CatalogProcessorEmit,
+  LocationSpec,
   results,
 } from '@backstage/plugin-catalog-backend';
 import {

plugins/techdocs/api-report.md

@@ -15,7 +15,6 @@ import { Entity } from '@backstage/catalog-model';
 import { EntityName } from '@backstage/catalog-model';
 import { FetchApi } from '@backstage/core-plugin-api';
 import { IdentityApi } from '@backstage/core-plugin-api';
-import { LocationSpec } from '@backstage/catalog-model';
 import { PropsWithChildren } from 'react';
 import { default as React_2 } from 'react';
 import { RouteRef } from '@backstage/core-plugin-api';

plugins/techdocs/src/types.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { Entity, LocationSpec } from '@backstage/catalog-model';
+import { Entity } from '@backstage/catalog-model';
 
 export type TechDocsMetadata = {
   site_name: string;
@@ -22,5 +22,5 @@ export type TechDocsMetadata = {
 };
 
 export type TechDocsEntityMetadata = Entity & {
-  locationMetadata?: LocationSpec;
+  locationMetadata?: { type: string; target: string };
 };