Merge branch 'backstage:master' into issue-7045/disable-template-create-button

2021-09-08 10:37:18 +01:00
parent 49c3f2bbbb 9ad1fd628d
commit 6c87b376c4
162 changed files with 1606 additions and 784 deletions
@@ -0,0 +1,14 @@
+---
+'@backstage/core-components': patch
+---
+
+Fix warning produced by BottomLink component
+
+During development, we noticed warnings such as:
+
+```
+react_devtools_backend.js:2842 Warning: validateDOMNesting(...): <div> cannot appear as a descendant of <p>.
+```
+
+The BottomLink component renders a Box component within a Typography component which leads to a div tag within a p tag.
+This change inverts that ordering without changing the visual appearance.
@@ -0,0 +1,11 @@
+---
+'@backstage/backend-test-utils': patch
+'@backstage/catalog-client': patch
+'@backstage/catalog-model': patch
+'@backstage/cli-common': patch
+'@backstage/config-loader': patch
+'@backstage/dev-utils': patch
+'@backstage/errors': patch
+---
+
+Properly export all used types.
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-todo': patch
+---
+
+All types are now properly documented and exported.
@@ -0,0 +1,6 @@
+---
+'@backstage/plugin-home': minor
+---
+
+Rename RandomJokeHomePageComponent to HomePageRandomJoke to fit convention, and update example app accordingly.
+**NOTE**: If you're using the RandomJoke component in your instance, it now has to be renamed to `HomePageRandomJoke`
@@ -0,0 +1,5 @@
+---
+'@backstage/config': patch
+---
+
+Documented `Config` interface and mark types as public.
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-scaffolder-backend': patch
+---
+
+GitHub Webhook action in Scaffolder Backend has been improved to validate event names against Octokit Webhook event names list.
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-org': patch
+---
+
+Make ownership card style customizable via custom `theme.getPageTheme()`.
@@ -0,0 +1,21 @@
+---
+'@backstage/plugin-catalog-backend': patch
+---
+
+Use `ScmIntegrationRegistry#resolveUrl` in the placeholder processors instead of a custom implementation.
+
+If you manually instantiate the `PlaceholderProcessor` (you most probably don't), add the new required constructor parameter:
+
+```diff
+ import { ScmIntegrations } from '@backstage/integration';
+  // ...
+ const integrations = ScmIntegrations.fromConfig(config);
+  // ...
+  new PlaceholderProcessor({
+    resolvers: placeholderResolvers,
+    reader,
+   integrations,
+  });
+```
+
+All custom `PlaceholderResolver` can use the new `resolveUrl` parameter to resolve relative URLs.
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-org': patch
+---
+
+Use correct `Link` in ownership card to avoid a full reload of the app while navigating.
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-scaffolder': patch
+---
+
+Fix display error when it fails to load a template (/create) page
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-search': patch
+---
+
+Add Home Page Search Bar Component, to be included in composable Home Page.
@@ -0,0 +1,5 @@
+---
+'@backstage/backend-common': patch
+---
+
+Properly export all used types.
@@ -0,0 +1,6 @@
+---
+'@backstage/cli': patch
+---
+
+Support importing font files in tests.
+This fixes remaining issues from [#7019](https://github.com/backstage/backstage/pull/7019).
@@ -0,0 +1,10 @@
+# Snyk (https://snyk.io) policy file, patches or ignores known vulnerabilities.
+version: v1.22.1
+# ignores vulnerabilities until expiry date; change duration by modifying expiry date
+ignore:
+  SNYK-JS-ANSIHTML-1296849:
+    - '@backstage/cli > webpack-dev-server > ansi-html':
+        reason: Developer tools are not a valid target for ReDoS attacks
+        expires: 2022-03-06T17:18:55.019Z
+        created: 2021-09-06T17:18:55.027Z
+patch: {}
@@ -111,20 +111,136 @@ as possible.
 Each catalog deployment has a number of processors installed. They are
 responsible for receiving unprocessed entities that the catalog decided are due
 for processing, and then running that data through a number of processing
-stages. mutating the entity and emitting auxiliary data about it. When all of
+stages, mutating the entity and emitting auxiliary data about it. When all of
 that is done, the catalog takes all of that information and stores it as the
 processed entity, and errors and relations to other entities separately. Then,
 the catalog checks to see what entities are touched by that output, and triggers
 the final assembly of those (see Stitching below).

-There are several stages involved in the processing.
+![Processing overview](../../assets/features/catalog/life-of-an-entity_processing.svg)

-> TODO: More info here
+Entities are always processed one by one, but all of your catalog service hosts
+collaborate in doing so to distribute the load. Note how each processor can
+contribute to one or more of the fixed steps in the processing pipeline. First
+all of the processors' contributions to one step are run in the order that the
+processors were registered, then all of their contributions to the next step in
+the same order, and so on.
+
+Each step has the opportunity to optionally modify the entity, and to optionally
+emit other information. For example, the processor might look at information in
+the `spec` field of the entity, and emit relations that correspond to those
+declarations. If the processor emits an entity, then that entity gets stored
+verbatim with a timestamp saying that it, too, should be processed as soon as
+possible. If errors are emitted, then that signals that something is wrong with
+the entity and that it should not replace whatever previously error-free version
+we had among the final entities. If relations are emitted, then they are put in
+a dedicated relations table to be picked up by the stitching process below.
+
+> Optional low level detail note: When entities are emitted, the catalog keeps
+> track of the edges between the emitting entity and the ones emitted. This
+> happens behind the scenes, hidden from the outside, and is used to form a
+> graph. This is _not_ the same thing as relations! The purpose of these edges,
+> is to be able to detect when an entity becomes orphaned (see below), and to be
+> able to perform eager deletions throughout the graph when a root is explicitly
+> unregistered and nothing else is keeping lower nodes alive. We will talk more
+> about orphaning and deletions later on in this article.
+
+When the final step has completed, and no errors were encountered, the processed
+entity and all of the relations are finally persisted in the database. Then the
+catalog considers this entity, and all of the entities it had relations to,
+subject for stitching.
+
+It is worth noting here that the processing does not lead to deletion or
+unregistration of entities; it can only call new entities into existence or
+update entities that it has previously called into existence. More about that
+later.

 ## Stitching

+Stitching finalizes the entity, by gathering all of the output from the previous
+steps and merging them into the final object which is what is visible from the
+catalog API. As the final entity itself gets updated, the stitcher makes sure
+that the search table gets refreshed accordingly as well.
+
+> Note: The search table mentioned here is not related to the core Search
+> feature of Backstage. It's rather the table that backs the ability to filter
+> catalog API query results.
+
+![Stitching overview](../../assets/features/catalog/life-of-an-entity_stitching.svg)
+
+The diagram shows how the stitcher reads from several sources:
+
+- The processed entity, as returned from the processing step
+- The errors, if any, that were emitted by the processing step
+- All relations that were emitted by the processing step, as well as any
+  relations emitted by _other_ entity processing steps that happen to point at
+  the current entity
+
+The last part is noteworthy: This is how the stitcher is able to collect all of
+the relation edges, both incoming and outgoing, no matter who produced them.
+
 The stitching is currently a fixed process, that cannot be modified or extended.
 This means that any modifications you want to make on the final result, has to
 happen during ingestion or processing.

-> TODO: More info here
+## Errors
+
+> TODO: Describe how errors are exposed through entities
+
+## Orphaning
+
+As mentioned earlier, entities internally form a graph. The edges go from
+processed parent entities, to child entities emitted while processing the
+parent.
+
+The processing loop runs continuously, so these edges are reconsidered over
+time. If processing a parent entity no longer emits a given child entity, then
+that former edge is severed. If that child has no other edges pointing at it
+either, it becomes _orphaned_. The end result is as follows:
+
+- The stitching process injects a `backstage.io/orphan: 'true'` annotation on
+  the child entity.
+- The child entity is _not_ removed from the catalog, but stays around until
+  explicitly deleted via the catalog API, or "reclaimed" by the original parent
+  or another parent starting to reference it.
+- The catalog page in Backstage for the child entity detects the new annotation
+  and informs users about the orphan status.
+
+Orphaning can occur in several different scenarios. One common cause is that the
+end user edited a corresponding catalog catalog-info YAML file removing the
+entity's entry. In the case of a `Location` parent entity, orphaning can happen
+if removing the target line pointing to the file containing the child entity.
+Another common cause is large batch processors such as the ones that crawl
+through remote systems looking for entities, no longer finding something that it
+used to find before. Maybe the data was moved, or deleted, in the remote system.
+So for example when a person leaves the company an LDAP org discovery processor
+might leave an orphaned `User` entity behind. Note that this only applies to
+processors - ingestion that happens using entity providers work differently,
+described below.
+
+> Note that removing a file, or accidentally corrupting a file so that it cannot
+> be read successfully, does _not_ lead to orphaning. Hard errors, including the
+> inability to find or read a distinct remote, are marked as such on the entity
+> to inform the owner that something is wrong. But processing and other
+> behaviors continue as usual.
+
+The reason that the orphaning mechanism exists instead of having an eager
+deletion triggered, is safety. Scenarios like these can happen purely by
+accident, due to the asynchronous nature of the system and the fallible nature
+of humans. In particular when external systems start consuming and relying on
+the catalog, there could be substantial consequences to suddenly dropping
+entities without explicit owner consent. The catalog therefore takes the stance
+that entities that often were added by direct user action should also be deleted
+only by direct user action.
+
+It is possible to use the catalog API to build automated "reaper" systems that
+finally delete entities that are orphaned. This is however not something that's
+provided out of the box.
+
+## Implicit Deletion
+
+> TODO: Describe the process of entity providers eagerly deleting entities
+
+## Explicit Deletion
+
+> TODO: Describe direct deletion via the catalog API
@@ -17,27 +17,28 @@
 import React from 'react';
 import Grid from '@material-ui/core/Grid';
 import {
-  RandomJokeHomePageComponent,
+  HomePageRandomJoke,
  ComponentAccordion,
  ComponentTabs,
  ComponentTab,
 } from '@backstage/plugin-home';
+import { HomePageSearchBar } from '@backstage/plugin-search';

 export const HomePage = () => (
  <Grid container spacing={3}>
-    <Grid item xs={12} md={4}>
-      <RandomJokeHomePageComponent />
+    <Grid item xs={12}>
+      <HomePageSearchBar />
    </Grid>
    <Grid item xs={12} md={4}>
-      <RandomJokeHomePageComponent
-        defaultCategory="any"
-        Renderer={ComponentAccordion}
-      />
-      <RandomJokeHomePageComponent
+      <HomePageRandomJoke />
+    </Grid>
+    <Grid item xs={12} md={4}>
+      <HomePageRandomJoke defaultCategory="any" Renderer={ComponentAccordion} />
+      <HomePageRandomJoke
        title="Another Random Joke"
        Renderer={ComponentAccordion}
      />
-      <RandomJokeHomePageComponent
+      <HomePageRandomJoke
        title="One More Random Joke"
        defaultCategory="programming"
        Renderer={ComponentAccordion}
@@ -50,7 +51,7 @@ export const HomePage = () => (
          {
            label: 'Programming',
            Component: () => (
-              <RandomJokeHomePageComponent
+              <HomePageRandomJoke
                defaultCategory="programming"
                Renderer={ComponentTab}
              />
@@ -59,7 +60,7 @@ export const HomePage = () => (
          {
            label: 'Any',
            Component: () => (
-              <RandomJokeHomePageComponent
+              <HomePageRandomJoke
                defaultCategory="any"
                Renderer={ComponentTab}
              />
@@ -9,7 +9,6 @@
 import { AzureIntegration } from '@backstage/integration';
 import { BitbucketIntegration } from '@backstage/integration';
 import { Config } from '@backstage/config';
-import { ConfigReader } from '@backstage/config';
 import cors from 'cors';
 import Docker from 'dockerode';
 import { ErrorRequestHandler } from 'express';
@@ -17,7 +16,6 @@ import express from 'express';
 import { GithubCredentialsProvider } from '@backstage/integration';
 import { GitHubIntegration } from '@backstage/integration';
 import { GitLabIntegration } from '@backstage/integration';
-import * as http from 'http';
 import { isChildPath } from '@backstage/cli-common';
 import { JsonValue } from '@backstage/config';
 import { Knex } from 'knex';
@@ -32,8 +30,6 @@ import { Server } from 'http';
 import * as winston from 'winston';
 import { Writable } from 'stream';

-// Warning: (ae-missing-release-tag) "AzureUrlReader" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export class AzureUrlReader implements UrlReader {
  constructor(
@@ -56,8 +52,6 @@ export class AzureUrlReader implements UrlReader {
  toString(): string;
 }

-// Warning: (ae-missing-release-tag) "BitbucketUrlReader" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export class BitbucketUrlReader implements UrlReader {
  constructor(
@@ -80,92 +74,82 @@ export class BitbucketUrlReader implements UrlReader {
  toString(): string;
 }

-// Warning: (ae-missing-release-tag) "CacheClient" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export interface CacheClient {
  delete(key: string): Promise<void>;
  get(key: string): Promise<JsonValue | undefined>;
-  // Warning: (ae-forgotten-export) The symbol "CacheSetOptions" needs to be exported by the entry point index.d.ts
-  set(key: string, value: JsonValue, options?: CacheSetOptions): Promise<void>;
+  set(
+    key: string,
+    value: JsonValue,
+    options?: CacheClientSetOptions,
+  ): Promise<void>;
 }

-// Warning: (ae-missing-release-tag) "CacheManager" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
+// @public (undocumented)
+export type CacheClientOptions = {
+  defaultTtl?: number;
+};
+
+// @public (undocumented)
+export type CacheClientSetOptions = {
+  ttl?: number;
+};
+
 // @public
 export class CacheManager {
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
  forPlugin(pluginId: string): PluginCacheManager;
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-  // Warning: (ae-forgotten-export) The symbol "CacheManagerOptions" needs to be exported by the entry point index.d.ts
  static fromConfig(
    config: Config,
    options?: CacheManagerOptions,
  ): CacheManager;
 }

-// Warning: (ae-missing-release-tag) "coloredFormat" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
+// @public (undocumented)
+export type CacheManagerOptions = {
+  logger?: Logger_2;
+  onError?: (err: Error) => void;
+};
+
 // @public (undocumented)
 export const coloredFormat: winston.Logform.Format;

-// Warning: (ae-missing-release-tag) "ContainerRunner" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export interface ContainerRunner {
  // (undocumented)
  runContainer(opts: RunContainerOptions): Promise<void>;
 }

-// Warning: (ae-missing-release-tag) "createDatabase" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public @deprecated
 export const createDatabase: typeof createDatabaseClient;

-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "createDatabaseClient" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function createDatabaseClient(
  dbConfig: Config,
  overrides?: Partial<Knex.Config>,
 ): Knex<any, unknown[]>;

-// Warning: (ae-missing-release-tag) "createRootLogger" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export function createRootLogger(
  options?: winston.LoggerOptions,
  env?: NodeJS.ProcessEnv,
 ): winston.Logger;

-// Warning: (ae-forgotten-export) The symbol "ServiceBuilderImpl" needs to be exported by the entry point index.d.ts
-// Warning: (ae-missing-release-tag) "createServiceBuilder" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
-export function createServiceBuilder(_module: NodeModule): ServiceBuilderImpl;
+export function createServiceBuilder(_module: NodeModule): ServiceBuilder;

-// Warning: (ae-forgotten-export) The symbol "StatusCheckRouterOptions" needs to be exported by the entry point index.d.ts
-// Warning: (ae-missing-release-tag) "createStatusCheckRouter" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
-export function createStatusCheckRouter(
-  options: StatusCheckRouterOptions,
-): Promise<express.Router>;
+export function createStatusCheckRouter(options: {
+  logger: Logger_2;
+  path?: string;
+  statusCheck?: StatusCheck;
+}): Promise<express.Router>;

-// Warning: (ae-missing-release-tag) "DatabaseManager" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export class DatabaseManager {
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
  forPlugin(pluginId: string): PluginDatabaseManager;
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
  static fromConfig(config: Config): DatabaseManager;
 }

-// Warning: (ae-missing-release-tag) "DockerContainerRunner" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export class DockerContainerRunner implements ContainerRunner {
  constructor({ dockerClient }: { dockerClient: Docker });
@@ -182,23 +166,17 @@ export class DockerContainerRunner implements ContainerRunner {
  }: RunContainerOptions): Promise<void>;
 }

-// Warning: (ae-missing-release-tag) "ensureDatabaseExists" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function ensureDatabaseExists(
  dbConfig: Config,
  ...databases: Array<string>
 ): Promise<void>;

-// Warning: (ae-missing-release-tag) "errorHandler" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function errorHandler(
  options?: ErrorHandlerOptions,
 ): ErrorRequestHandler;

-// Warning: (ae-missing-release-tag) "ErrorHandlerOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export type ErrorHandlerOptions = {
  showStackTraces?: boolean;
@@ -206,18 +184,12 @@ export type ErrorHandlerOptions = {
  logClientErrors?: boolean;
 };

-// Warning: (ae-missing-release-tag) "getRootLogger" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export function getRootLogger(): winston.Logger;

-// Warning: (ae-missing-release-tag) "getVoidLogger" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function getVoidLogger(): winston.Logger;

-// Warning: (ae-missing-release-tag) "Git" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export class Git {
  // (undocumented)
@@ -322,8 +294,6 @@ export class Git {
  resolveRef({ dir, ref }: { dir: string; ref: string }): Promise<string>;
 }

-// Warning: (ae-missing-release-tag) "GithubUrlReader" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export class GithubUrlReader implements UrlReader {
  constructor(
@@ -347,8 +317,6 @@ export class GithubUrlReader implements UrlReader {
  toString(): string;
 }

-// Warning: (ae-missing-release-tag) "GitlabUrlReader" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export class GitlabUrlReader implements UrlReader {
  constructor(
@@ -373,41 +341,31 @@ export class GitlabUrlReader implements UrlReader {

 export { isChildPath };

-// Warning: (ae-forgotten-export) The symbol "Options" needs to be exported by the entry point index.d.ts
-// Warning: (ae-missing-release-tag) "loadBackendConfig" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
-export function loadBackendConfig(options: Options): Promise<Config>;
+export function loadBackendConfig(options: {
+  logger: Logger_2;
+  argv: string[];
+}): Promise<Config>;

-// Warning: (ae-missing-release-tag) "notFoundHandler" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function notFoundHandler(): RequestHandler;

-// Warning: (ae-missing-release-tag) "PluginCacheManager" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type PluginCacheManager = {
-  getClient: (options?: ClientOptions) => CacheClient;
+  getClient: (options?: CacheClientOptions) => CacheClient;
 };

-// Warning: (ae-missing-release-tag) "PluginDatabaseManager" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export interface PluginDatabaseManager {
  getClient(): Promise<Knex>;
 }

-// Warning: (ae-missing-release-tag) "PluginEndpointDiscovery" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type PluginEndpointDiscovery = {
  getBaseUrl(pluginId: string): Promise<string>;
  getExternalBaseUrl(pluginId: string): Promise<string>;
 };

-// Warning: (ae-missing-release-tag) "ReaderFactory" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type ReaderFactory = (options: {
  config: Config;
@@ -415,8 +373,6 @@ export type ReaderFactory = (options: {
  treeResponseFactory: ReadTreeResponseFactory;
 }) => UrlReaderPredicateTuple[];

-// Warning: (ae-missing-release-tag) "ReadTreeOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type ReadTreeOptions = {
  filter?(
@@ -428,8 +384,6 @@ export type ReadTreeOptions = {
  etag?: string;
 };

-// Warning: (ae-missing-release-tag) "ReadTreeResponse" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type ReadTreeResponse = {
  files(): Promise<ReadTreeResponseFile[]>;
@@ -438,68 +392,67 @@ export type ReadTreeResponse = {
  etag: string;
 };

-// Warning: (ae-missing-release-tag) "ReadTreeResponseFactory" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
+// @public (undocumented)
+export type ReadTreeResponseDirOptions = {
+  targetDir?: string;
+};
+
 // @public (undocumented)
 export interface ReadTreeResponseFactory {
-  // Warning: (ae-forgotten-export) The symbol "FromArchiveOptions" needs to be exported by the entry point index.d.ts
-  //
  // (undocumented)
-  fromTarArchive(options: FromArchiveOptions): Promise<ReadTreeResponse>;
+  fromTarArchive(
+    options: ReadTreeResponseFactoryOptions,
+  ): Promise<ReadTreeResponse>;
  // (undocumented)
-  fromZipArchive(options: FromArchiveOptions): Promise<ReadTreeResponse>;
+  fromZipArchive(
+    options: ReadTreeResponseFactoryOptions,
+  ): Promise<ReadTreeResponse>;
 }

-// Warning: (ae-missing-release-tag) "ReadTreeResponseFile" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
+// @public (undocumented)
+export type ReadTreeResponseFactoryOptions = {
+  stream: Readable;
+  subpath?: string;
+  etag: string;
+  filter?: (
+    path: string,
+    info?: {
+      size: number;
+    },
+  ) => boolean;
+};
+
 // @public
 export type ReadTreeResponseFile = {
  path: string;
  content(): Promise<Buffer>;
 };

-// Warning: (ae-missing-release-tag) "ReadUrlOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type ReadUrlOptions = {
  etag?: string;
 };

-// Warning: (ae-missing-release-tag) "ReadUrlResponse" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type ReadUrlResponse = {
  buffer(): Promise<Buffer>;
  etag?: string;
 };

-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "requestLoggingHandler" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function requestLoggingHandler(logger?: Logger_2): RequestHandler;

-// Warning: (ae-missing-release-tag) "RequestLoggingHandlerFactory" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export type RequestLoggingHandlerFactory = (
  logger?: Logger_2,
 ) => RequestHandler;

-// Warning: (ae-missing-release-tag) "resolvePackagePath" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function resolvePackagePath(name: string, ...paths: string[]): string;

-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "resolveSafeChildPath" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function resolveSafeChildPath(base: string, path: string): string;

-// Warning: (ae-missing-release-tag) "RunContainerOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export type RunContainerOptions = {
  imageName: string;
@@ -512,39 +465,40 @@ export type RunContainerOptions = {
  pullImage?: boolean;
 };

-// Warning: (ae-missing-release-tag) "SearchOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type SearchOptions = {
  etag?: string;
 };

-// Warning: (ae-missing-release-tag) "SearchResponse" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type SearchResponse = {
  files: SearchResponseFile[];
  etag: string;
 };

-// Warning: (ae-missing-release-tag) "SearchResponseFile" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type SearchResponseFile = {
  url: string;
  content(): Promise<Buffer>;
 };

-// Warning: (ae-missing-release-tag) "ServiceBuilder" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export type ServiceBuilder = {
-  loadConfig(config: ConfigReader): ServiceBuilder;
+  loadConfig(config: Config): ServiceBuilder;
  setPort(port: number): ServiceBuilder;
  setHost(host: string): ServiceBuilder;
  setLogger(logger: Logger_2): ServiceBuilder;
  enableCors(options: cors.CorsOptions): ServiceBuilder;
-  setHttpsSettings(settings: HttpsSettings): ServiceBuilder;
+  setHttpsSettings(settings: {
+    certificate:
+      | {
+          key: string;
+          cert: string;
+        }
+      | {
+          hostname: string;
+        };
+  }): ServiceBuilder;
  addRouter(root: string, router: Router | RequestHandler): ServiceBuilder;
  setRequestLoggingHandler(
    requestLoggingHandler: RequestLoggingHandlerFactory,
@@ -552,18 +506,12 @@ export type ServiceBuilder = {
  start(): Promise<Server>;
 };

-// Warning: (ae-missing-release-tag) "setRootLogger" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export function setRootLogger(newLogger: winston.Logger): void;

-// Warning: (ae-missing-release-tag) "SingleConnectionDatabaseManager" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public @deprecated
 export const SingleConnectionDatabaseManager: typeof DatabaseManager;

-// Warning: (ae-missing-release-tag) "SingleHostDiscovery" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export class SingleHostDiscovery implements PluginEndpointDiscovery {
  static fromConfig(
@@ -578,28 +526,19 @@ export class SingleHostDiscovery implements PluginEndpointDiscovery {
  getExternalBaseUrl(pluginId: string): Promise<string>;
 }

-// Warning: (ae-missing-release-tag) "StatusCheck" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export type StatusCheck = () => Promise<any>;

-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "statusCheckHandler" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function statusCheckHandler(
  options?: StatusCheckHandlerOptions,
 ): Promise<RequestHandler>;

-// Warning: (ae-missing-release-tag) "StatusCheckHandlerOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export interface StatusCheckHandlerOptions {
  statusCheck?: StatusCheck;
 }

-// Warning: (ae-missing-release-tag) "UrlReader" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type UrlReader = {
  read(url: string): Promise<Buffer>;
@@ -608,56 +547,33 @@ export type UrlReader = {
  search(url: string, options?: SearchOptions): Promise<SearchResponse>;
 };

-// Warning: (ae-missing-release-tag) "UrlReaderPredicateTuple" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export type UrlReaderPredicateTuple = {
  predicate: (url: URL) => boolean;
  reader: UrlReader;
 };

-// Warning: (ae-missing-release-tag) "UrlReaders" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export class UrlReaders {
-  // Warning: (ae-forgotten-export) The symbol "CreateOptions" needs to be exported by the entry point index.d.ts
-  static create({ logger, config, factories }: CreateOptions): UrlReader;
-  static default({ logger, config, factories }: CreateOptions): UrlReader;
+  static create({ logger, config, factories }: UrlReadersOptions): UrlReader;
+  static default({ logger, config, factories }: UrlReadersOptions): UrlReader;
 }

-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "useHotCleanup" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
+// @public (undocumented)
+export type UrlReadersOptions = {
+  config: Config;
+  logger: Logger_2;
+  factories?: ReaderFactory[];
+};
+
 // @public
 export function useHotCleanup(
  _module: NodeModule,
  cancelEffect: () => void,
 ): void;

-// Warning: (tsdoc-undefined-tag) The TSDoc tag "@warning" is not defined in this configuration
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "useHotMemoize" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function useHotMemoize<T>(_module: NodeModule, valueFactory: () => T): T;

-// Warnings were encountered during analysis:
-//
-// src/cache/types.d.ts:34:5 - (ae-forgotten-export) The symbol "ClientOptions" needs to be exported by the entry point index.d.ts
-// src/middleware/errorHandler.d.ts:17:26 - (tsdoc-malformed-html-name) Invalid HTML element: A space is not allowed here
-// src/reading/types.d.ts:108:5 - (ae-forgotten-export) The symbol "ReadTreeResponseDirOptions" needs to be exported by the entry point index.d.ts
-// src/service/types.d.ts:12:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// src/service/types.d.ts:22:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// src/service/types.d.ts:30:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// src/service/types.d.ts:38:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// src/service/types.d.ts:47:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// src/service/types.d.ts:55:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// src/service/types.d.ts:57:5 - (ae-forgotten-export) The symbol "HttpsSettings" needs to be exported by the entry point index.d.ts
-// src/service/types.d.ts:61:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// src/service/types.d.ts:62:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// src/service/types.d.ts:70:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-
 // (No @packageDocumentation comment for this package)
 ```
@@ -22,7 +22,8 @@ type CacheClientArgs = {
  client: Keyv;
 };

-type CacheSetOptions = {
+/** @public */
+export type CacheClientSetOptions = {
  /**
   * Optional TTL in milliseconds. Defaults to the TTL provided when the client
   * was set up (or no TTL if none are provided).
@@ -33,6 +34,8 @@ type CacheSetOptions = {
 /**
 * A pre-configured, storage agnostic cache client suitable for use by
 * Backstage plugins.
+ *
+ * @public
 */
 export interface CacheClient {
  /**
@@ -46,7 +49,11 @@ export interface CacheClient {
   * optional TTL may also be provided, otherwise it defaults to the TTL that
   * was provided when the client was instantiated.
   */
-  set(key: string, value: JsonValue, options?: CacheSetOptions): Promise<void>;
+  set(
+    key: string,
+    value: JsonValue,
+    options?: CacheClientSetOptions,
+  ): Promise<void>;

  /**
   * Removes the given key from the cache store.
@@ -73,7 +80,7 @@ export class DefaultCacheClient implements CacheClient {
  async set(
    key: string,
    value: JsonValue,
-    opts: CacheSetOptions = {},
+    opts: CacheClientSetOptions = {},
  ): Promise<void> {
    const k = this.getNormalizedKey(key);
    await this.client.set(k, value, opts.ttl);
@@ -22,16 +22,14 @@ import { Logger } from 'winston';
 import { getRootLogger } from '../logging';
 import { DefaultCacheClient, CacheClient } from './CacheClient';
 import { NoStore } from './NoStore';
-import {
-  CacheManagerOptions,
-  OptionalOnError,
-  PluginCacheManager,
-} from './types';
+import { CacheManagerOptions, PluginCacheManager } from './types';

 /**
 * Implements a Cache Manager which will automatically create new cache clients
 * for plugins when requested. All requested cache clients are created with the
 * connection details provided.
+ *
+ * @public
 */
 export class CacheManager {
  /**
@@ -47,13 +45,13 @@ export class CacheManager {
  private readonly logger: Logger;
  private readonly store: keyof CacheManager['storeFactories'];
  private readonly connection: string;
-  private readonly errorHandler: OptionalOnError;
+  private readonly errorHandler: CacheManagerOptions['onError'];

  /**
   * Creates a new CacheManager instance by reading from the `backend` config
   * section, specifically the `.cache` key.
   *
-   * @param config The loaded application configuration.
+   * @param config - The loaded application configuration.
   */
  static fromConfig(
    config: Config,
@@ -74,7 +72,7 @@ export class CacheManager {
    store: string,
    connectionString: string,
    logger: Logger,
-    errorHandler: OptionalOnError,
+    errorHandler: CacheManagerOptions['onError'],
  ) {
    if (!this.storeFactories.hasOwnProperty(store)) {
      throw new Error(`Unknown cache store: ${store}`);
@@ -88,7 +86,7 @@ export class CacheManager {
  /**
   * Generates a PluginCacheManager for consumption by plugins.
   *
-   * @param pluginId The plugin that the cache manager should be created for. Plugin names should be unique.
+   * @param pluginId - The plugin that the cache manager should be created for. Plugin names should be unique.
   */
  forPlugin(pluginId: string): PluginCacheManager {
    return {
@@ -14,6 +14,10 @@
 * limitations under the License.
 */

-export type { CacheClient } from './CacheClient';
+export type { CacheClient, CacheClientSetOptions } from './CacheClient';
 export { CacheManager } from './CacheManager';
-export type { PluginCacheManager } from './types';
+export type {
+  PluginCacheManager,
+  CacheManagerOptions,
+  CacheClientOptions,
+} from './types';
@@ -17,7 +17,8 @@
 import { Logger } from 'winston';
 import { CacheClient } from './CacheClient';

-type ClientOptions = {
+/** @public */
+export type CacheClientOptions = {
  /**
   * An optional default TTL (in milliseconds) to be set when getting a client
   * instance. If not provided, data will persist indefinitely by default (or
@@ -26,8 +27,7 @@ type ClientOptions = {
  defaultTtl?: number;
 };

-export type OptionalOnError = ((err: Error) => void) | undefined;
-
+/** @public */
 export type CacheManagerOptions = {
  /**
   * An optional logger for use by the PluginCacheManager.
@@ -38,11 +38,13 @@ export type CacheManagerOptions = {
   * An optional handler for connection errors emitted from the underlying data
   * store.
   */
-  onError?: OptionalOnError;
+  onError?: (err: Error) => void;
 };

 /**
 * The PluginCacheManager manages access to cache stores that Plugins get.
+ *
+ * @public
 */
 export type PluginCacheManager = {
  /**
@@ -52,5 +54,5 @@ export type PluginCacheManager = {
   * stores so that plugins are discouraged from cache-level integration
   * and/or cache key collisions.
   */
-  getClient: (options?: ClientOptions) => CacheClient;
+  getClient: (options?: CacheClientOptions) => CacheClient;
 };
@@ -101,12 +101,6 @@ class ObservableConfigProxy implements Config {
  }
 }

-type Options = {
-  logger: Logger;
-  // process.argv or any other overrides
-  argv: string[];
-};
-
 // A global used to ensure that only a single file watcher is active at a time.
 let currentCancelFunc: () => void;

@@ -114,8 +108,14 @@ let currentCancelFunc: () => void;
 * Load configuration for a Backend.
 *
 * This function should only be called once, during the initialization of the backend.
+ *
+ * @public
 */
-export async function loadBackendConfig(options: Options): Promise<Config> {
+export async function loadBackendConfig(options: {
+  logger: Logger;
+  // process.argv or any other overrides
+  argv: string[];
+}): Promise<Config> {
  const args = parseArgs(options.argv);
  const configPaths: string[] = [args.config ?? []].flat();

@@ -31,6 +31,7 @@ function pluginPath(pluginId: string): string {
  return `plugin.${pluginId}`;
 }

+/** @public */
 export class DatabaseManager {
  /**
   * Creates a DatabaseManager from `backend.database` config.
@@ -40,7 +41,7 @@ export class DatabaseManager {
   * defaults. Optionally, a user may set `prefix` which is used to prefix generated database
   * names if config is not provided.
   *
-   * @param config The loaded application configuration.
+   * @param config - The loaded application configuration.
   */
  static fromConfig(config: Config): DatabaseManager {
    const databaseConfig = config.getConfig('backend.database');
@@ -59,7 +60,7 @@ export class DatabaseManager {
  /**
   * Generates a PluginDatabaseManager for consumption by plugins.
   *
-   * @param pluginId The plugin that the database manager should be created for. Plugin names
+   * @param pluginId - The plugin that the database manager should be created for. Plugin names
   * should be unique as they are used to look up database config overrides under
   * `backend.database.plugin`.
   */
@@ -22,6 +22,7 @@ import { DatabaseManager } from './DatabaseManager';
 * credentials provided; if the database already exists no attempt to create
 * the database will be made.
 *
+ * @public
 * @deprecated Use `DatabaseManager` from `@backend-common` instead.
 */
 export const SingleConnectionDatabaseManager = DatabaseManager;
@@ -19,6 +19,7 @@ import { merge } from 'lodash';
 /**
 * Merges database objects together
 *
+ * @public
 * @param config The base config. The input is not modified
 * @param overrides Any additional overrides
 */
@@ -40,8 +40,9 @@ const ConnectorMapping: Record<DatabaseClient, DatabaseConnector> = {
 /**
 * Creates a knex database connection
 *
- * @param dbConfig The database config
- * @param overrides Additional options to merge with the config
+ * @public
+ * @param dbConfig - The database config
+ * @param overrides - Additional options to merge with the config
 */
 export function createDatabaseClient(
  dbConfig: Config,
@@ -57,12 +58,16 @@ export function createDatabaseClient(

 /**
 * Alias for createDatabaseClient
+ *
+ * @public
 * @deprecated Use createDatabaseClient instead
 */
 export const createDatabase = createDatabaseClient;

 /**
 * Ensures that the given databases all exist, creating them if they do not.
+ *
+ * @public
 */
 export async function ensureDatabaseExists(
  dbConfig: Config,
@@ -19,6 +19,8 @@ import { Knex } from 'knex';

 /**
 * The PluginDatabaseManager manages access to databases that Plugins get.
+ *
+ * @public
 */
 export interface PluginDatabaseManager {
  /**
@@ -26,6 +26,8 @@ import { DEFAULT_PORT } from '../service/lib/ServiceBuilderImpl';
 * The deployment may be scaled horizontally, as long as the external URL
 * is the same for all instances. However, internal URLs will always be
 * resolved to the same host, so there won't be any balancing of internal traffic.
+ *
+ * @public
 */
 export class SingleHostDiscovery implements PluginEndpointDiscovery {
  /**
@@ -25,6 +25,8 @@
 * Implementations of the discovery API can be as simple as a URL pattern
 * using the pluginId, but could also have overrides for individual plugins,
 * or query a separate discovery service.
+ *
+ * @public
 */
 export type PluginEndpointDiscovery = {
  /**
@@ -46,13 +46,14 @@ function findAllAncestors(_module: NodeModule): NodeModule[] {
 *
 * Useful for cleaning intervals, timers, requests etc
 *
+ * @public
 * @example
 * ```ts
 * const intervalId = setInterval(doStuff, 1000);
 * useHotCleanup(module, () => clearInterval(intervalId));
 * ```
- * @param _module Reference to the current module where you invoke the fn
- * @param cancelEffect Fn that cleans up the ongoing effects
+ * @param _module - Reference to the current module where you invoke the fn
+ * @param cancelEffect - Fn that cleans up the ongoing effects
 */
 export function useHotCleanup(_module: NodeModule, cancelEffect: () => void) {
  if (_module.hot) {
@@ -78,16 +79,17 @@ const CURRENT_HOT_MEMOIZE_INDEX_KEY = 'backstage.io/hmr-memoize-key';
 * Memoizes a generated value across hot-module reloads. This is useful for
 * stateful parts of the backend, e.g. to retain a database.
 *
+ * @public
 * @example
 * ```ts
 * const db = useHotMemoize(module, () => createDB(dbParams));
 * ```
 *
- * @warning Don't use inside conditionals or loops,
+ * **NOTE:** Do not use inside conditionals or loops,
 * same rules as for hooks apply (https://reactjs.org/docs/hooks-rules.html)
 *
- * @param _module Reference to the current module where you invoke the fn
- * @param valueFactory Fn that returns the value you want to memoize
+ * @param _module - Reference to the current module where you invoke the fn
+ * @param valueFactory - Fn that returns the value you want to memoize
 */
 export function useHotMemoize<T>(
  _module: NodeModule,
@@ -31,6 +31,7 @@ const coloredTemplate = (info: TransformableInfo) => {
  return `${timestampColor} ${prefixColor} ${level} ${message} ${extraFields}`;
 };

+/** @public */
 export const coloredFormat = winston.format.combine(
  winston.format.timestamp(),
  winston.format.colorize({
@@ -21,14 +21,17 @@ import { coloredFormat } from './formats';

 let rootLogger: winston.Logger;

+/** @public */
 export function getRootLogger(): winston.Logger {
  return rootLogger;
 }

+/** @public */
 export function setRootLogger(newLogger: winston.Logger) {
  rootLogger = newLogger;
 }

+/** @public */
 export function createRootLogger(
  options: winston.LoggerOptions = {},
  env = process.env,
@@ -19,6 +19,8 @@ import * as winston from 'winston';

 /**
 * A logger that just throws away all messages.
+ *
+ * @public
 */
 export function getVoidLogger(): winston.Logger {
  return winston.createLogger({
@@ -28,6 +28,7 @@ import { ErrorRequestHandler, NextFunction, Request, Response } from 'express';
 import { Logger } from 'winston';
 import { getRootLogger } from '../logging';

+/** @public */
 export type ErrorHandlerOptions = {
  /**
   * Whether error response bodies should show error stack traces or not.
@@ -44,9 +45,9 @@ export type ErrorHandlerOptions = {
  logger?: Logger;

  /**
-   * Whether any error < 4XX should be logged or not.
+   * Whether any 4xx errors should be logged or not.
   *
-   * If not specified, by default log any 5xx errors.
+   * If not specified, default to only logging 5xx errors.
   */
  logClientErrors?: boolean;
 };
@@ -62,6 +63,7 @@ export type ErrorHandlerOptions = {
 * error types (such as http-error exceptions) and returns the enclosed status
 * code accordingly.
 *
+ * @public
 * @returns An Express error request handler
 */
 export function errorHandler(
@@ -22,6 +22,7 @@ import { NextFunction, Request, RequestHandler, Response } from 'express';
 * Should be used as the very last handler in the chain, as it unconditionally
 * returns a 404 status.
 *
+ * @public
 * @returns An Express request handler
 */
 export function notFoundHandler(): RequestHandler {
@@ -22,7 +22,8 @@ import { getRootLogger } from '../logging';
 /**
 * Logs incoming requests.
 *
- * @param logger An optional logger to use. If not specified, the root logger will be used.
+ * @public
+ * @param logger - An optional logger to use. If not specified, the root logger will be used.
 * @returns An Express request handler
 */
 export function requestLoggingHandler(logger?: Logger): RequestHandler {
@@ -16,8 +16,10 @@

 import { NextFunction, Request, Response, RequestHandler } from 'express';

+/** @public */
 export type StatusCheck = () => Promise<any>;

+/** @public */
 export interface StatusCheckHandlerOptions {
  /**
   * Optional status function which returns a message.
@@ -30,7 +32,8 @@ export interface StatusCheckHandlerOptions {
 *
 * This is commonly used to implement healthcheck and readiness routes.
 *
- * @param options An optional configuration object.
+ * @public
+ * @param options - An optional configuration object.
 * @returns An Express error request handler
 */
 export async function statusCheckHandler(
@@ -25,6 +25,8 @@ import { resolve as resolvePath } from 'path';
 * This is particularly useful when you want to access assets shipped with
 * your backend plugin package. When doing so, do not forget to include the assets
 * in your published package by adding them to `files` in your `package.json`.
+ *
+ * @public
 */
 export function resolvePackagePath(name: string, ...paths: string[]) {
  const req =
@@ -40,8 +42,9 @@ export function resolvePackagePath(name: string, ...paths: string[]) {
 * a path that point to or within the base path. This is useful for resolving
 * paths from user input, as it otherwise opens up for vulnerabilities.
 *
- * @param base The base directory to resolve the path from.
- * @param path The target path, relative or absolute
+ * @public
+ * @param base - The base directory to resolve the path from.
+ * @param path - The target path, relative or absolute
 * @returns A path that is guaranteed to point to or within the base path.
 */
 export function resolveSafeChildPath(base: string, path: string): string {
@@ -40,6 +40,7 @@ import {
  ReadUrlResponse,
 } from './types';

+/** @public */
 export class AzureUrlReader implements UrlReader {
  static factory: ReaderFactory = ({ config, treeResponseFactory }) => {
    const integrations = ScmIntegrations.fromConfig(config);
@@ -43,6 +43,8 @@ import {
 /**
 * A processor that adds the ability to read files from Bitbucket v1 and v2 APIs, such as
 * the one exposed by Bitbucket Cloud itself.
+ *
+ * @public
 */
 export class BitbucketUrlReader implements UrlReader {
  static factory: ReaderFactory = ({ config, treeResponseFactory }) => {
@@ -27,6 +27,8 @@ import {

 /**
 * A UrlReader that does a plain fetch of the URL.
+ *
+ * @public
 */
 export class FetchUrlReader implements UrlReader {
  /**
@@ -51,6 +51,8 @@ export type GhBlobResponse =
 /**
 * A processor that adds the ability to read files from GitHub v3 APIs, such as
 * the one exposed by GitHub itself.
+ *
+ * @public
 */
 export class GithubUrlReader implements UrlReader {
  static factory: ReaderFactory = ({ config, treeResponseFactory }) => {
@@ -38,6 +38,7 @@ import {
  ReadUrlOptions,
 } from './types';

+/** @public */
 export class GitlabUrlReader implements UrlReader {
  static factory: ReaderFactory = ({ config, treeResponseFactory }) => {
    const integrations = ScmIntegrations.fromConfig(config);
@@ -48,6 +48,7 @@ const parseURL = (
  };
 };

+/** @public */
 export class GoogleGcsUrlReader implements UrlReader {
  static factory: ReaderFactory = ({ config, logger }) => {
    if (!config.has('integrations.googleGcs')) {
@@ -27,7 +27,8 @@ import { FetchUrlReader } from './FetchUrlReader';
 import { GoogleGcsUrlReader } from './GoogleGcsUrlReader';
 import { AwsS3UrlReader } from './AwsS3UrlReader';

-type CreateOptions = {
+/** @public */
+export type UrlReadersOptions = {
  /** Root config object */
  config: Config;
  /** Logger used by all the readers */
@@ -38,12 +39,14 @@ type CreateOptions = {

 /**
 * UrlReaders provide various utilities related to the UrlReader interface.
+ *
+ * @public
 */
 export class UrlReaders {
  /**
   * Creates a UrlReader without any known types.
   */
-  static create({ logger, config, factories }: CreateOptions): UrlReader {
+  static create({ logger, config, factories }: UrlReadersOptions): UrlReader {
    const mux = new UrlReaderPredicateMux(logger);
    const treeResponseFactory = DefaultReadTreeResponseFactory.create({
      config,
@@ -65,7 +68,7 @@ export class UrlReaders {
   *
   * Any additional factories passed will be loaded before the default ones.
   */
-  static default({ logger, config, factories = [] }: CreateOptions) {
+  static default({ logger, config, factories = [] }: UrlReadersOptions) {
    return UrlReaders.create({
      logger,
      config,
@@ -24,6 +24,8 @@ export type {
  ReadTreeResponse,
  ReadTreeResponseFactory,
  ReadTreeResponseFile,
+  ReadTreeResponseDirOptions,
+  ReadTreeResponseFactoryOptions,
  ReadUrlOptions,
  ReadUrlResponse,
  SearchOptions,
@@ -33,3 +35,4 @@ export type {
  UrlReaderPredicateTuple,
 } from './types';
 export { UrlReaders } from './UrlReaders';
+export type { UrlReadersOptions } from './UrlReaders';
@@ -18,7 +18,7 @@ import os from 'os';
 import { Config } from '@backstage/config';
 import {
  ReadTreeResponse,
-  FromArchiveOptions,
+  ReadTreeResponseFactoryOptions,
  ReadTreeResponseFactory,
 } from '../types';
 import { TarArchiveResponse } from './TarArchiveResponse';
@@ -34,7 +34,9 @@ export class DefaultReadTreeResponseFactory implements ReadTreeResponseFactory {

  constructor(private readonly workDir: string) {}

-  async fromTarArchive(options: FromArchiveOptions): Promise<ReadTreeResponse> {
+  async fromTarArchive(
+    options: ReadTreeResponseFactoryOptions,
+  ): Promise<ReadTreeResponse> {
    return new TarArchiveResponse(
      options.stream,
      options.subpath ?? '',
@@ -44,7 +46,9 @@ export class DefaultReadTreeResponseFactory implements ReadTreeResponseFactory {
    );
  }

-  async fromZipArchive(options: FromArchiveOptions): Promise<ReadTreeResponse> {
+  async fromZipArchive(
+    options: ReadTreeResponseFactoryOptions,
+  ): Promise<ReadTreeResponse> {
    return new ZipArchiveResponse(
      options.stream,
      options.subpath ?? '',
@@ -20,6 +20,8 @@ import { Config } from '@backstage/config';

 /**
 * A generic interface for fetching plain data from URLs.
+ *
+ * @public
 */
 export type UrlReader = {
  /* Used to read a single file and return its content. */
@@ -39,6 +41,7 @@ export type UrlReader = {
  search(url: string, options?: SearchOptions): Promise<SearchResponse>;
 };

+/** @public */
 export type UrlReaderPredicateTuple = {
  predicate: (url: URL) => boolean;
  reader: UrlReader;
@@ -47,6 +50,8 @@ export type UrlReaderPredicateTuple = {
 /**
 * A factory function that can read config to construct zero or more
 * UrlReaders along with a predicate for when it should be used.
+ *
+ * @public
 */
 export type ReaderFactory = (options: {
  config: Config;
@@ -56,6 +61,8 @@ export type ReaderFactory = (options: {

 /**
 * An options object for readUrl operations.
+ *
+ * @public
 */
 export type ReadUrlOptions = {
  /**
@@ -74,6 +81,8 @@ export type ReadUrlOptions = {

 /**
 * A response object for readUrl operations.
+ *
+ * @public
 */
 export type ReadUrlResponse = {
  /**
@@ -90,6 +99,8 @@ export type ReadUrlResponse = {

 /**
 * An options object for readTree operations.
+ *
+ * @public
 */
 export type ReadTreeOptions = {
  /**
@@ -120,8 +131,16 @@ export type ReadTreeOptions = {
  etag?: string;
 };

+/** @public */
+export type ReadTreeResponseDirOptions = {
+  /** The directory to write files to. Defaults to the OS tmpdir or `backend.workingDirectory` if set in config */
+  targetDir?: string;
+};
+
 /**
 * A response object for readTree operations.
+ *
+ * @public
 */
 export type ReadTreeResponse = {
  /**
@@ -142,20 +161,18 @@ export type ReadTreeResponse = {
  etag: string;
 };

-export type ReadTreeResponseDirOptions = {
-  /** The directory to write files to. Defaults to the OS tmpdir or `backend.workingDirectory` if set in config */
-  targetDir?: string;
-};
-
 /**
 * Represents a single file in a readTree response.
+ *
+ * @public
 */
 export type ReadTreeResponseFile = {
  path: string;
  content(): Promise<Buffer>;
 };

-export type FromArchiveOptions = {
+/** @public */
+export type ReadTreeResponseFactoryOptions = {
  // A binary stream of a tar archive.
  stream: Readable;
  // If unset, the files at the root of the tree will be read.
@@ -167,13 +184,20 @@ export type FromArchiveOptions = {
  filter?: (path: string, info?: { size: number }) => boolean;
 };

+/** @public */
 export interface ReadTreeResponseFactory {
-  fromTarArchive(options: FromArchiveOptions): Promise<ReadTreeResponse>;
-  fromZipArchive(options: FromArchiveOptions): Promise<ReadTreeResponse>;
+  fromTarArchive(
+    options: ReadTreeResponseFactoryOptions,
+  ): Promise<ReadTreeResponse>;
+  fromZipArchive(
+    options: ReadTreeResponseFactoryOptions,
+  ): Promise<ReadTreeResponse>;
 }

 /**
 * An options object for search operations.
+ *
+ * @public
 */
 export type SearchOptions = {
  /**
@@ -192,6 +216,8 @@ export type SearchOptions = {

 /**
 * The output of a search operation.
+ *
+ * @public
 */
 export type SearchResponse = {
  /**
@@ -207,6 +233,8 @@ export type SearchResponse = {

 /**
 * Represents a single file in a search response.
+ *
+ * @public
 */
 export type SearchResponseFile = {
  /**
@@ -31,6 +31,8 @@ From : https://isomorphic-git.org/docs/en/onAuth with fix for GitHub

 Azure       'notempty'      token
 */
+
+/** @public */
 export class Git {
  private constructor(
    private readonly config: {
@@ -15,10 +15,13 @@
 */

 import { ServiceBuilderImpl } from './lib/ServiceBuilderImpl';
+import { ServiceBuilder } from './types';

 /**
 * Creates a new service builder.
+ *
+ * @public
 */
-export function createServiceBuilder(_module: NodeModule) {
+export function createServiceBuilder(_module: NodeModule): ServiceBuilder {
  return new ServiceBuilderImpl(_module);
 }
@@ -19,7 +19,8 @@ import Router from 'express-promise-router';
 import express from 'express';
 import { errorHandler, statusCheckHandler, StatusCheck } from '../middleware';

-export interface StatusCheckRouterOptions {
+/** @public */
+export async function createStatusCheckRouter(options: {
  logger: Logger;
  path?: string;
  /**
@@ -27,11 +28,7 @@ export interface StatusCheckRouterOptions {
   * Override this to implement your own logic for a health check.
   */
  statusCheck?: StatusCheck;
-}
-
-export async function createStatusCheckRouter(
-  options: StatusCheckRouterOptions,
-): Promise<express.Router> {
+}): Promise<express.Router> {
  const router = Router();
  const { path = '/healthcheck', statusCheck } = options;

@@ -14,20 +14,20 @@
 * limitations under the License.
 */

-import { ConfigReader } from '@backstage/config';
+import { Config } from '@backstage/config';
 import cors from 'cors';
 import { Router, RequestHandler } from 'express';
 import { Server } from 'http';
 import { Logger } from 'winston';
-import { HttpsSettings } from './lib/config';

+/** @public */
 export type ServiceBuilder = {
  /**
   * Sets the service parameters based on configuration.
   *
-   * @param config The configuration to read
+   * @param config - The configuration to read
   */
-  loadConfig(config: ConfigReader): ServiceBuilder;
+  loadConfig(config: Config): ServiceBuilder;

  /**
   * Sets the port to listen on.
@@ -36,7 +36,7 @@ export type ServiceBuilder = {
   * variable named PORT and use that if present, otherwise it picks a default
   * port (7000).
   *
-   * @param port The port to listen on
+   * @param port - The port to listen on
   */
  setPort(port: number): ServiceBuilder;

@@ -45,7 +45,7 @@ export type ServiceBuilder = {
   *
   * '' is express default, which listens to all interfaces.
   *
-   * @param host The host to listen on
+   * @param host - The host to listen on
   */
  setHost(host: string): ServiceBuilder;

@@ -54,7 +54,7 @@ export type ServiceBuilder = {
   *
   * If no logger is given, the default root logger is used.
   *
-   * @param logger A winston logger
+   * @param logger - A winston logger
   */
  setLogger(logger: Logger): ServiceBuilder;

@@ -64,7 +64,7 @@ export type ServiceBuilder = {
   * If this method is not called, the resulting service will not have any
   * built in CORS handling.
   *
-   * @param options Standard CORS options
+   * @param options - Standard CORS options
   */
  enableCors(options: cors.CorsOptions): ServiceBuilder;

@@ -73,15 +73,17 @@ export type ServiceBuilder = {
   *
   * If this method is not called, the resulting service will use sensible defaults
   *
-   * @param options Standard certificate options
+   * @param options - Standard certificate options
   */
-  setHttpsSettings(settings: HttpsSettings): ServiceBuilder;
+  setHttpsSettings(settings: {
+    certificate: { key: string; cert: string } | { hostname: string };
+  }): ServiceBuilder;

  /**
   * Adds a router (similar to the express .use call) to the service.
   *
-   * @param root The root URL to bind to (e.g. "/api/function1")
-   * @param router An express router
+   * @param root - The root URL to bind to (e.g. "/api/function1")
+   * @param router - An express router
   */
  addRouter(root: string, router: Router | RequestHandler): ServiceBuilder;

@@ -90,7 +92,7 @@ export type ServiceBuilder = {
   *
   * If no handler is given the default one is used
   *
-   * @param requestLoggingHandler a factory function that given a logger returns an handler
+   * @param requestLoggingHandler - a factory function that given a logger returns an handler
   */
  setRequestLoggingHandler(
    requestLoggingHandler: RequestLoggingHandlerFactory,
@@ -102,4 +104,5 @@ export type ServiceBuilder = {
  start(): Promise<Server>;
 };

+/** @public */
 export type RequestLoggingHandlerFactory = (logger?: Logger) => RequestHandler;
@@ -16,6 +16,7 @@

 import { Writable } from 'stream';

+/** @public */
 export type RunContainerOptions = {
  imageName: string;
  command?: string | string[];
@@ -27,6 +28,7 @@ export type RunContainerOptions = {
  pullImage?: boolean;
 };

+/** @public */
 export interface ContainerRunner {
  runContainer(opts: RunContainerOptions): Promise<void>;
 }
@@ -23,6 +23,7 @@ export type UserOptions = {
  User?: string;
 };

+/** @public */
 export class DockerContainerRunner implements ContainerRunner {
  private readonly dockerClient: Docker;

@@ -5,13 +5,9 @@
 ```ts
 import { Knex } from 'knex';

-// Warning: (ae-missing-release-tag) "isDockerDisabledForTests" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export function isDockerDisabledForTests(): boolean;

-// Warning: (ae-missing-release-tag) "TestDatabaseId" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type TestDatabaseId =
  | 'POSTGRES_13'
@@ -19,8 +15,6 @@ export type TestDatabaseId =
  | 'MYSQL_8'
  | 'SQLITE_3';

-// Warning: (ae-missing-release-tag) "TestDatabases" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export class TestDatabases {
  static create(options?: {
@@ -29,7 +23,6 @@ export class TestDatabases {
  }): TestDatabases;
  // (undocumented)
  eachSupportedId(): [TestDatabaseId][];
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
  init(id: TestDatabaseId): Promise<Knex>;
  // (undocumented)
  supports(id: TestDatabaseId): boolean;
@@ -31,6 +31,8 @@ import {
 /**
 * Encapsulates the creation of ephemeral test database instances for use
 * inside unit or integration tests.
+ *
+ * @public
 */
 export class TestDatabases {
  private readonly instanceById: Map<string, Instance>;
@@ -113,7 +115,7 @@ export class TestDatabases {
   * Returns a fresh, unique, empty logical database on an instance of the
   * given database ID platform.
   *
-   * @param id The ID of the database platform to use, e.g. 'POSTGRES_13'
+   * @param id - The ID of the database platform to use, e.g. 'POSTGRES_13'
   * @returns A `Knex` connection object
   */
  async init(id: TestDatabaseId): Promise<Knex> {
@@ -19,6 +19,8 @@ import { Knex } from 'knex';

 /**
 * The possible databases to test against.
+ *
+ * @public
 */
 export type TestDatabaseId =
  | 'POSTGRES_13'
@@ -14,6 +14,7 @@
 * limitations under the License.
 */

+/** @public */
 export function isDockerDisabledForTests() {
  // If we are not running in continuous integration, the default is to skip
  // the (relatively heavy, long running) docker based tests. If you want to
@@ -7,8 +7,6 @@ import { Entity } from '@backstage/catalog-model';
 import { EntityName } from '@backstage/catalog-model';
 import { Location as Location_2 } from '@backstage/catalog-model';

-// Warning: (ae-missing-release-tag) "AddLocationRequest" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export type AddLocationRequest = {
  type?: string;
@@ -17,21 +15,15 @@ export type AddLocationRequest = {
  presence?: 'optional' | 'required';
 };

-// Warning: (ae-missing-release-tag) "AddLocationResponse" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export type AddLocationResponse = {
  location: Location_2;
  entities: Entity[];
 };

-// Warning: (ae-missing-release-tag) "CATALOG_FILTER_EXISTS" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export const CATALOG_FILTER_EXISTS: unique symbol;

-// Warning: (ae-missing-release-tag) "CatalogApi" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export interface CatalogApi {
  // (undocumented)
@@ -76,8 +68,6 @@ export interface CatalogApi {
  ): Promise<void>;
 }

-// Warning: (ae-missing-release-tag) "CatalogClient" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export class CatalogClient implements CatalogApi {
  constructor(options: { discoveryApi: DiscoveryApi });
@@ -123,8 +113,6 @@ export class CatalogClient implements CatalogApi {
  ): Promise<void>;
 }

-// Warning: (ae-missing-release-tag) "CatalogEntitiesRequest" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export type CatalogEntitiesRequest = {
  filter?:
@@ -134,29 +122,24 @@ export type CatalogEntitiesRequest = {
  fields?: string[] | undefined;
 };

-// Warning: (ae-missing-release-tag) "CatalogListResponse" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export type CatalogListResponse<T> = {
  items: T[];
 };

-// Warning: (ae-missing-release-tag) "CatalogRequestOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export type CatalogRequestOptions = {
  token?: string;
 };

-// Warning: (ae-missing-release-tag) "ENTITY_STATUS_CATALOG_PROCESSING_TYPE" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
+// @public
+export type DiscoveryApi = {
+  getBaseUrl(pluginId: string): Promise<string>;
+};
+
 // @public
 export const ENTITY_STATUS_CATALOG_PROCESSING_TYPE =
  'backstage.io/catalog-processing';

-// Warnings were encountered during analysis:
-//
-// src/CatalogClient.d.ts:7:9 - (ae-forgotten-export) The symbol "DiscoveryApi" needs to be exported by the entry point index.d.ts
-
 // (No @packageDocumentation comment for this package)
 ```
@@ -36,6 +36,7 @@ import {
 } from './types/api';
 import { DiscoveryApi } from './types/discovery';

+/** @public */
 export class CatalogClient implements CatalogApi {
  private readonly discoveryApi: DiscoveryApi;

@@ -16,8 +16,10 @@

 import { Entity, EntityName, Location } from '@backstage/catalog-model';

+/** @public */
 export const CATALOG_FILTER_EXISTS = Symbol('CATALOG_FILTER_EXISTS');

+/** @public */
 export type CatalogEntitiesRequest = {
  filter?:
    | Record<string, string | symbol | (string | symbol)[]>[]
@@ -26,14 +28,17 @@ export type CatalogEntitiesRequest = {
  fields?: string[] | undefined;
 };

+/** @public */
 export type CatalogListResponse<T> = {
  items: T[];
 };

+/** @public */
 export type CatalogRequestOptions = {
  token?: string;
 };

+/** @public */
 export interface CatalogApi {
  // Entities
  getEntities(
@@ -72,6 +77,7 @@ export interface CatalogApi {
  ): Promise<void>;
 }

+/** @public */
 export type AddLocationRequest = {
  type?: string;
  target: string;
@@ -79,6 +85,7 @@ export type AddLocationRequest = {
  presence?: 'optional' | 'required';
 };

+/** @public */
 export type AddLocationResponse = {
  location: Location;
  entities: Entity[];
@@ -16,6 +16,8 @@

 /**
 * This is a copy of the core DiscoveryApi, to avoid importing core.
+ *
+ * @public
 */
 export type DiscoveryApi = {
  getBaseUrl(pluginId: string): Promise<string>;
@@ -22,5 +22,6 @@ export type {
  CatalogListResponse,
  CatalogRequestOptions,
 } from './api';
+export type { DiscoveryApi } from './discovery';
 export { CATALOG_FILTER_EXISTS } from './api';
 export { ENTITY_STATUS_CATALOG_PROCESSING_TYPE } from './status';
@@ -17,6 +17,8 @@
 /**
 * The entity `status.items[].type` for the status of the processing engine in
 * regards to an entity.
+ *
+ * @public
 */
 export const ENTITY_STATUS_CATALOG_PROCESSING_TYPE =
  'backstage.io/catalog-processing';
@@ -9,9 +9,6 @@ import { JsonValue } from '@backstage/config';
 import { SerializedError } from '@backstage/errors';
 import * as yup from 'yup';

-// Warning: (tsdoc-missing-deprecation-message) The @deprecated block must include a deprecation message, e.g. describing the recommended alternative
-// Warning: (ae-missing-release-tag) "analyzeLocationSchema" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public @deprecated (undocumented)
 export const analyzeLocationSchema: yup.ObjectSchema<
  {
@@ -20,8 +17,6 @@ export const analyzeLocationSchema: yup.ObjectSchema<
  object
 >;

-// Warning: (ae-missing-release-tag) "ApiEntityV1alpha1" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 interface ApiEntityV1alpha1 extends Entity {
  // (undocumented)
@@ -40,43 +35,24 @@ interface ApiEntityV1alpha1 extends Entity {
 export { ApiEntityV1alpha1 as ApiEntity };
 export { ApiEntityV1alpha1 };

-// Warning: (ae-missing-release-tag) "apiEntityV1alpha1Validator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export const apiEntityV1alpha1Validator: KindValidator;

-// Warning: (ae-missing-release-tag) "CommonValidatorFunctions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export class CommonValidatorFunctions {
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
  static isJsonSafe(value: unknown): boolean;
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
  static isValidDnsLabel(value: unknown): boolean;
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
  static isValidDnsSubdomain(value: unknown): boolean;
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
  static isValidPrefixAndOrSuffix(
    value: unknown,
    separator: string,
    isValidPrefix: (value: string) => boolean,
    isValidSuffix: (value: string) => boolean,
  ): boolean;
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
  static isValidString(value: unknown): boolean;
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
  static isValidUrl(value: unknown): boolean;
 }

-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-forgotten-export) The symbol "EntityRefContext" needs to be exported by the entry point index.d.ts
-// Warning: (ae-missing-release-tag) "compareEntityToRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function compareEntityToRef(
  entity: Entity,
@@ -84,8 +60,6 @@ export function compareEntityToRef(
  context?: EntityRefContext,
 ): boolean;

-// Warning: (ae-missing-release-tag) "ComponentEntityV1alpha1" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 interface ComponentEntityV1alpha1 extends Entity {
  // (undocumented)
@@ -107,13 +81,9 @@ interface ComponentEntityV1alpha1 extends Entity {
 export { ComponentEntityV1alpha1 as ComponentEntity };
 export { ComponentEntityV1alpha1 };

-// Warning: (ae-missing-release-tag) "componentEntityV1alpha1Validator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export const componentEntityV1alpha1Validator: KindValidator;

-// Warning: (ae-missing-release-tag) "DefaultNamespaceEntityPolicy" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export class DefaultNamespaceEntityPolicy implements EntityPolicy {
  constructor(namespace?: string);
@@ -121,8 +91,6 @@ export class DefaultNamespaceEntityPolicy implements EntityPolicy {
  enforce(entity: Entity): Promise<Entity>;
 }

-// Warning: (ae-missing-release-tag) "DomainEntityV1alpha1" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 interface DomainEntityV1alpha1 extends Entity {
  // (undocumented)
@@ -137,18 +105,12 @@ interface DomainEntityV1alpha1 extends Entity {
 export { DomainEntityV1alpha1 as DomainEntity };
 export { DomainEntityV1alpha1 };

-// Warning: (ae-missing-release-tag) "domainEntityV1alpha1Validator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export const domainEntityV1alpha1Validator: KindValidator;

-// Warning: (ae-missing-release-tag) "EDIT_URL_ANNOTATION" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export const EDIT_URL_ANNOTATION = 'backstage.io/edit-url';

-// Warning: (ae-missing-release-tag) "Entity" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type Entity = {
  apiVersion: string;
@@ -159,13 +121,9 @@ export type Entity = {
  status?: UNSTABLE_EntityStatus;
 };

-// Warning: (ae-missing-release-tag) "ENTITY_DEFAULT_NAMESPACE" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export const ENTITY_DEFAULT_NAMESPACE = 'default';

-// Warning: (ae-missing-release-tag) "ENTITY_META_GENERATED_FIELDS" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export const ENTITY_META_GENERATED_FIELDS: readonly [
  'uid',
@@ -173,8 +131,6 @@ export const ENTITY_META_GENERATED_FIELDS: readonly [
  'generation',
 ];

-// Warning: (ae-missing-release-tag) "EntityEnvelope" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type EntityEnvelope = {
  apiVersion: string;
@@ -185,35 +141,19 @@ export type EntityEnvelope = {
  };
 };

-// Warning: (ae-missing-release-tag) "entityEnvelopeSchemaValidator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-// Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@backstage/catalog-model" does not have an export "TypeError"
-//
 // @public
 export function entityEnvelopeSchemaValidator<
  T extends EntityEnvelope = EntityEnvelope,
 >(schema?: unknown): (data: unknown) => T;

-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "entityHasChanges" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function entityHasChanges(previous: Entity, next: Entity): boolean;

-// Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
-// Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
-// Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
-// Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
-// Warning: (ae-missing-release-tag) "entityKindSchemaValidator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-// Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@backstage/catalog-model" does not have an export "TypeError"
-//
 // @public
 export function entityKindSchemaValidator<T extends Entity>(
  schema: unknown,
 ): (data: unknown) => T | false;

-// Warning: (ae-missing-release-tag) "EntityLink" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type EntityLink = {
  url: string;
@@ -221,8 +161,6 @@ export type EntityLink = {
  icon?: string;
 };

-// Warning: (ae-missing-release-tag) "EntityMeta" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type EntityMeta = JsonObject & {
  uid?: string;
@@ -238,8 +176,6 @@ export type EntityMeta = JsonObject & {
  links?: EntityLink[];
 };

-// Warning: (ae-missing-release-tag) "EntityName" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type EntityName = {
  kind: string;
@@ -247,23 +183,17 @@ export type EntityName = {
  name: string;
 };

-// Warning: (ae-missing-release-tag) "EntityPolicies" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export const EntityPolicies: {
-  allOf(policies: EntityPolicy[]): AllEntityPolicies;
-  oneOf(policies: EntityPolicy[]): AnyEntityPolicy;
+  allOf(policies: EntityPolicy[]): EntityPolicy;
+  oneOf(policies: EntityPolicy[]): EntityPolicy;
 };

-// Warning: (ae-missing-release-tag) "EntityPolicy" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type EntityPolicy = {
  enforce(entity: Entity): Promise<Entity | undefined>;
 };

-// Warning: (ae-missing-release-tag) "EntityRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type EntityRef =
  | string
@@ -273,16 +203,18 @@ export type EntityRef =
      name: string;
    };

-// Warning: (ae-missing-release-tag) "EntityRelation" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
+// @public
+export type EntityRefContext = {
+  defaultKind?: string;
+  defaultNamespace?: string;
+};
+
 // @public
 export type EntityRelation = {
  type: string;
  target: EntityName;
 };

-// Warning: (ae-missing-release-tag) "EntityRelationSpec" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type EntityRelationSpec = {
  source: EntityName;
@@ -290,16 +222,11 @@ export type EntityRelationSpec = {
  target: EntityName;
 };

-// Warning: (ae-missing-release-tag) "entitySchemaValidator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-// Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@backstage/catalog-model" does not have an export "TypeError"
-//
 // @public
 export function entitySchemaValidator<T extends Entity = Entity>(
  schema?: unknown,
 ): (data: unknown) => T;

-// Warning: (ae-missing-release-tag) "FieldFormatEntityPolicy" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export class FieldFormatEntityPolicy implements EntityPolicy {
  constructor(validators?: Validators);
@@ -307,40 +234,24 @@ export class FieldFormatEntityPolicy implements EntityPolicy {
  enforce(entity: Entity): Promise<Entity>;
 }

-// Warning: (ae-missing-release-tag) "generateEntityEtag" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function generateEntityEtag(): string;

-// Warning: (ae-missing-release-tag) "generateEntityUid" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function generateEntityUid(): string;

-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "generateUpdatedEntity" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function generateUpdatedEntity(previous: Entity, next: Entity): Entity;

-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "getEntityName" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function getEntityName(entity: Entity): EntityName;

-// Warning: (tsdoc-characters-after-block-tag) The token "@backstage" looks like a TSDoc tag but contains an invalid character "/"; if it is not a tag, use a backslash to escape the "@"
-// Warning: (ae-missing-release-tag) "getEntitySourceLocation" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function getEntitySourceLocation(entity: Entity): {
  type: string;
  target: string;
 };

-// Warning: (ae-missing-release-tag) "GroupEntityV1alpha1" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 interface GroupEntityV1alpha1 extends Entity {
  // (undocumented)
@@ -363,28 +274,20 @@ interface GroupEntityV1alpha1 extends Entity {
 export { GroupEntityV1alpha1 as GroupEntity };
 export { GroupEntityV1alpha1 };

-// Warning: (ae-missing-release-tag) "groupEntityV1alpha1Validator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export const groupEntityV1alpha1Validator: KindValidator;

-// Warning: (ae-missing-release-tag) "JSONSchema" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export type JSONSchema = JSONSchema7 &
  {
    [key in string]?: JsonValue;
  };

-// Warning: (ae-missing-release-tag) "KindValidator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type KindValidator = {
  check(entity: Entity): Promise<boolean>;
 };

-// Warning: (ae-missing-release-tag) "KubernetesValidatorFunctions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export class KubernetesValidatorFunctions {
  // (undocumented)
@@ -405,21 +308,15 @@ export class KubernetesValidatorFunctions {
  static isValidObjectName(value: unknown): boolean;
 }

-// Warning: (ae-missing-release-tag) "Location" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 type Location_2 = {
  id: string;
 } & LocationSpec;
 export { Location_2 as Location };

-// Warning: (ae-missing-release-tag) "LOCATION_ANNOTATION" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export const LOCATION_ANNOTATION = 'backstage.io/managed-by-location';

-// Warning: (ae-missing-release-tag) "LocationEntityV1alpha1" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 interface LocationEntityV1alpha1 extends Entity {
  // (undocumented)
@@ -436,19 +333,12 @@ interface LocationEntityV1alpha1 extends Entity {
 export { LocationEntityV1alpha1 as LocationEntity };
 export { LocationEntityV1alpha1 };

-// Warning: (ae-missing-release-tag) "locationEntityV1alpha1Validator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export const locationEntityV1alpha1Validator: KindValidator;

-// Warning: (tsdoc-missing-deprecation-message) The @deprecated block must include a deprecation message, e.g. describing the recommended alternative
-// Warning: (ae-missing-release-tag) "locationSchema" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public @deprecated (undocumented)
 export const locationSchema: yup.ObjectSchema<Location_2, object>;

-// Warning: (ae-missing-release-tag) "LocationSpec" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export type LocationSpec = {
  type: string;
@@ -456,19 +346,12 @@ export type LocationSpec = {
  presence?: 'optional' | 'required';
 };

-// Warning: (tsdoc-missing-deprecation-message) The @deprecated block must include a deprecation message, e.g. describing the recommended alternative
-// Warning: (ae-missing-release-tag) "locationSpecSchema" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public @deprecated (undocumented)
 export const locationSpecSchema: yup.ObjectSchema<LocationSpec, object>;

-// Warning: (ae-missing-release-tag) "makeValidator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export function makeValidator(overrides?: Partial<Validators>): Validators;

-// Warning: (ae-missing-release-tag) "NoForeignRootFieldsEntityPolicy" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export class NoForeignRootFieldsEntityPolicy implements EntityPolicy {
  constructor(knownFields?: string[]);
@@ -476,28 +359,16 @@ export class NoForeignRootFieldsEntityPolicy implements EntityPolicy {
  enforce(entity: Entity): Promise<Entity>;
 }

-// Warning: (ae-missing-release-tag) "ORIGIN_LOCATION_ANNOTATION" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export const ORIGIN_LOCATION_ANNOTATION =
  'backstage.io/managed-by-origin-location';

-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "parseEntityName" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function parseEntityName(
  ref: EntityRef,
  context?: EntityRefContext,
 ): EntityName;

-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "parseEntityRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-// Warning: (ae-missing-release-tag) "parseEntityRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-// Warning: (ae-missing-release-tag) "parseEntityRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function parseEntityRef(
  ref: EntityRef,
@@ -535,89 +406,54 @@ export function parseEntityRef(
  name: string;
 };

-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
-// Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
-// Warning: (ae-missing-release-tag) "parseLocationReference" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function parseLocationReference(ref: string): {
  type: string;
  target: string;
 };

-// Warning: (ae-missing-release-tag) "RELATION_API_CONSUMED_BY" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export const RELATION_API_CONSUMED_BY = 'apiConsumedBy';

-// Warning: (ae-missing-release-tag) "RELATION_API_PROVIDED_BY" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export const RELATION_API_PROVIDED_BY = 'apiProvidedBy';

-// Warning: (ae-missing-release-tag) "RELATION_CHILD_OF" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export const RELATION_CHILD_OF = 'childOf';

-// Warning: (ae-missing-release-tag) "RELATION_CONSUMES_API" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export const RELATION_CONSUMES_API = 'consumesApi';

-// Warning: (ae-missing-release-tag) "RELATION_DEPENDENCY_OF" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export const RELATION_DEPENDENCY_OF = 'dependencyOf';

-// Warning: (ae-missing-release-tag) "RELATION_DEPENDS_ON" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export const RELATION_DEPENDS_ON = 'dependsOn';

-// Warning: (ae-missing-release-tag) "RELATION_HAS_MEMBER" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export const RELATION_HAS_MEMBER = 'hasMember';

-// Warning: (ae-missing-release-tag) "RELATION_HAS_PART" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export const RELATION_HAS_PART = 'hasPart';

-// Warning: (ae-missing-release-tag) "RELATION_MEMBER_OF" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export const RELATION_MEMBER_OF = 'memberOf';

-// Warning: (ae-missing-release-tag) "RELATION_OWNED_BY" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export const RELATION_OWNED_BY = 'ownedBy';

-// Warning: (ae-missing-release-tag) "RELATION_OWNER_OF" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export const RELATION_OWNER_OF = 'ownerOf';

-// Warning: (ae-missing-release-tag) "RELATION_PARENT_OF" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export const RELATION_PARENT_OF = 'parentOf';

-// Warning: (ae-missing-release-tag) "RELATION_PART_OF" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export const RELATION_PART_OF = 'partOf';

-// Warning: (ae-missing-release-tag) "RELATION_PROVIDES_API" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export const RELATION_PROVIDES_API = 'providesApi';

-// Warning: (ae-missing-release-tag) "ResourceEntityV1alpha1" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 interface ResourceEntityV1alpha1 extends Entity {
  // (undocumented)
@@ -635,22 +471,15 @@ interface ResourceEntityV1alpha1 extends Entity {
 export { ResourceEntityV1alpha1 as ResourceEntity };
 export { ResourceEntityV1alpha1 };

-// Warning: (ae-missing-release-tag) "resourceEntityV1alpha1Validator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export const resourceEntityV1alpha1Validator: KindValidator;

-// Warning: (ae-missing-release-tag) "SchemaValidEntityPolicy" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export class SchemaValidEntityPolicy implements EntityPolicy {
  // (undocumented)
  enforce(entity: Entity): Promise<Entity>;
 }

-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "serializeEntityRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public @deprecated
 export function serializeEntityRef(
  ref:
@@ -662,14 +491,9 @@ export function serializeEntityRef(
      },
 ): EntityRef;

-// Warning: (ae-missing-release-tag) "SOURCE_LOCATION_ANNOTATION" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export const SOURCE_LOCATION_ANNOTATION = 'backstage.io/source-location';

-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "stringifyEntityRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function stringifyEntityRef(
  ref:
@@ -681,19 +505,12 @@ export function stringifyEntityRef(
      },
 ): string;

-// Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
-// Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
-// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// Warning: (ae-missing-release-tag) "stringifyLocationReference" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export function stringifyLocationReference(ref: {
  type: string;
  target: string;
 }): string;

-// Warning: (ae-missing-release-tag) "SystemEntityV1alpha1" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 interface SystemEntityV1alpha1 extends Entity {
  // (undocumented)
@@ -709,13 +526,9 @@ interface SystemEntityV1alpha1 extends Entity {
 export { SystemEntityV1alpha1 as SystemEntity };
 export { SystemEntityV1alpha1 };

-// Warning: (ae-missing-release-tag) "systemEntityV1alpha1Validator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export const systemEntityV1alpha1Validator: KindValidator;

-// Warning: (ae-missing-release-tag) "TemplateEntityV1beta2" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export interface TemplateEntityV1beta2 extends Entity {
  // (undocumented)
@@ -740,8 +553,6 @@ export interface TemplateEntityV1beta2 extends Entity {
  };
 }

-// Warning: (ae-missing-release-tag) "templateEntityV1beta2Validator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export const templateEntityV1beta2Validator: KindValidator;

@@ -761,8 +572,6 @@ export type UNSTABLE_EntityStatusItem = {
 // @alpha
 export type UNSTABLE_EntityStatusLevel = 'info' | 'warning' | 'error';

-// Warning: (ae-missing-release-tag) "UserEntityV1alpha1" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 interface UserEntityV1alpha1 extends Entity {
  // (undocumented)
@@ -782,13 +591,9 @@ interface UserEntityV1alpha1 extends Entity {
 export { UserEntityV1alpha1 as UserEntity };
 export { UserEntityV1alpha1 };

-// Warning: (ae-missing-release-tag) "userEntityV1alpha1Validator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export const userEntityV1alpha1Validator: KindValidator;

-// Warning: (ae-missing-release-tag) "Validators" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export type Validators = {
  isValidApiVersion(value: unknown): boolean;
@@ -802,18 +607,12 @@ export type Validators = {
  isValidTag(value: unknown): boolean;
 };

-// Warning: (ae-missing-release-tag) "VIEW_URL_ANNOTATION" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export const VIEW_URL_ANNOTATION = 'backstage.io/view-url';

 // Warnings were encountered during analysis:
 //
-// src/EntityPolicies.d.ts:13:5 - (ae-forgotten-export) The symbol "AllEntityPolicies" needs to be exported by the entry point index.d.ts
-// src/EntityPolicies.d.ts:14:5 - (ae-forgotten-export) The symbol "AnyEntityPolicy" needs to be exported by the entry point index.d.ts
-// src/entity/Entity.d.ts:37:5 - (ae-incompatible-release-tags) The symbol "status" is marked as @public, but its signature references "UNSTABLE_EntityStatus" which is marked as @alpha
-// src/entity/policies/types.d.ts:10:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// src/kinds/types.d.ts:9:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
+// src/entity/Entity.d.ts:38:5 - (ae-incompatible-release-tags) The symbol "status" is marked as @public, but its signature references "UNSTABLE_EntityStatus" which is marked as @alpha

 // (No @packageDocumentation comment for this package)
 ```
@@ -52,11 +52,12 @@ class AnyEntityPolicy implements EntityPolicy {
  }
 }

+/** @public */
 export const EntityPolicies = {
-  allOf(policies: EntityPolicy[]) {
+  allOf(policies: EntityPolicy[]): EntityPolicy {
    return new AllEntityPolicies(policies);
  },
-  oneOf(policies: EntityPolicy[]) {
+  oneOf(policies: EntityPolicy[]): EntityPolicy {
    return new AnyEntityPolicy(policies);
  },
 };
@@ -21,6 +21,7 @@ import { UNSTABLE_EntityStatus } from './EntityStatus';
 /**
 * The parts of the format that's common to all versions/kinds of entity.
 *
+ * @public
 * @see https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/
 */
 export type Entity = {
@@ -62,6 +63,7 @@ export type Entity = {
 /**
 * Metadata fields common to all versions/kinds of entity.
 *
+ * @public
 * @see https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/#objectmeta-v1-meta
 * @see https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/
 */
@@ -166,6 +168,8 @@ export type EntityMeta = JsonObject & {

 /**
 * A relation of a specific type to another entity in the catalog.
+ *
+ * @public
 */
 export type EntityRelation = {
  /**
@@ -181,6 +185,8 @@ export type EntityRelation = {

 /**
 * Holds the relation data for entities.
+ *
+ * @public
 */
 export type EntityRelationSpec = {
  /**
@@ -201,6 +207,8 @@ export type EntityRelationSpec = {

 /**
 * A link to external information that is related to the entity.
+ *
+ * @public
 */
 export type EntityLink = {
  /**
@@ -18,6 +18,7 @@
 * The envelope skeleton parts of an entity - whatever is necessary to be able
 * to give it a ref and pass to further validation / policy checking.
 *
+ * @public
 * @see https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/
 */
 export type EntityEnvelope = {
@@ -18,6 +18,7 @@ import { SerializedError } from '@backstage/errors';

 /**
 * The current status of the entity, as claimed by various sources.
+ *
 * @alpha
 */
 export type UNSTABLE_EntityStatus = {
@@ -16,11 +16,15 @@

 /**
 * The namespace that entities without an explicit namespace fall into.
+ *
+ * @public
 */
 export const ENTITY_DEFAULT_NAMESPACE = 'default';

 /**
 * The keys of EntityMeta that are auto-generated.
+ *
+ * @public
 */
 export const ENTITY_META_GENERATED_FIELDS = [
  'uid',
@@ -30,6 +34,9 @@ export const ENTITY_META_GENERATED_FIELDS = [

 /**
 * Annotations for linking to entity from catalog pages.
+ *
+ * @public
 */
 export const VIEW_URL_ANNOTATION = 'backstage.io/view-url';
+/** @public */
 export const EDIT_URL_ANNOTATION = 'backstage.io/edit-url';
@@ -42,6 +42,7 @@ export {
  serializeEntityRef,
  stringifyEntityRef,
 } from './ref';
+export type { EntityRefContext } from './ref';
 export {
  entityHasChanges,
  generateEntityEtag,
@@ -21,6 +21,8 @@ import { Entity } from '../Entity';

 /**
 * Sets a default namespace if none was set.
+ *
+ * @public
 */
 export class DefaultNamespaceEntityPolicy implements EntityPolicy {
  private readonly namespace: string;
@@ -29,6 +29,8 @@ import { Entity } from '../Entity';
 *
 * This does not take into account machine generated fields such as uid, etag
 * and generation.
+ *
+ * @public
 */
 export class FieldFormatEntityPolicy implements EntityPolicy {
  private readonly validators: Validators;
@@ -21,6 +21,8 @@ const defaultKnownFields = ['apiVersion', 'kind', 'metadata', 'spec'];

 /**
 * Ensures that there are no foreign root fields in the entity.
+ *
+ * @public
 */
 export class NoForeignRootFieldsEntityPolicy implements EntityPolicy {
  private readonly knownFields: string[];
@@ -27,6 +27,8 @@ import { EntityPolicy } from './types';
 * This should be the first policy in the list, to ensure that other downstream
 * policies can work with a structure that is at least valid in therms of the
 * typescript type.
+ *
+ * @public
 */
 export class SchemaValidEntityPolicy implements EntityPolicy {
  private validate: ValidateFunction<Entity> | undefined;
@@ -19,12 +19,14 @@ import type { Entity } from '../Entity';
 /**
 * A policy for validation or mutation to be applied to entities as they are
 * entering the system.
+ *
+ * @public
 */
 export type EntityPolicy = {
  /**
   * Applies validation or mutation on an entity.
   *
-   * @param entity The entity, as validated/mutated so far in the policy tree
+   * @param entity - The entity, as validated/mutated so far in the policy tree
   * @returns The incoming entity, or a mutated version of the same, or
   *          undefined if this processor could not handle the entity
   * @throws An error if the entity should be rejected
@@ -41,7 +41,8 @@ function parseRefString(ref: string): {
 * Extracts the kind, namespace and name that form the name triplet of the
 * given entity.
 *
- * @param entity An entity
+ * @public
+ * @param entity - An entity
 * @returns The complete entity name
 */
 export function getEntityName(entity: Entity): EntityName {
@@ -54,8 +55,10 @@ export function getEntityName(entity: Entity): EntityName {

 /**
 * The context of defaults that entity reference parsing happens within.
+ *
+ * @public
 */
-type EntityRefContext = {
+export type EntityRefContext = {
  /** The default kind, if none is given in the reference */
  defaultKind?: string;
  /** The default namespace, if none is given in the reference */
@@ -70,8 +73,9 @@ type EntityRefContext = {
 * otherwise specified as part of the options, and will throw an error if no
 * kind was specified in the input reference and no default kind was given.
 *
- * @param ref The reference to parse
- * @param context The context of defaults that the parsing happens within
+ * @public
+ * @param ref - The reference to parse
+ * @param context - The context of defaults that the parsing happens within
 * @returns A complete entity name
 */
 export function parseEntityName(
@@ -99,8 +103,9 @@ export function parseEntityName(
 * The options object can contain default values for the kind and namespace,
 * that will be used if the input reference did not specify any.
 *
- * @param ref The reference to parse
- * @param context The context of defaults that the parsing happens within
+ * @public
+ * @param ref - The reference to parse
+ * @param context - The context of defaults that the parsing happens within
 * @returns The compound form of the reference
 */
 export function parseEntityRef(
@@ -111,6 +116,7 @@ export function parseEntityRef(
  namespace: string;
  name: string;
 };
+/** @public */
 export function parseEntityRef(
  ref: EntityRef,
  context?: { defaultKind: string },
@@ -119,6 +125,7 @@ export function parseEntityRef(
  namespace?: string;
  name: string;
 };
+/** @public */
 export function parseEntityRef(
  ref: EntityRef,
  context?: { defaultNamespace: string },
@@ -170,8 +177,9 @@ export function parseEntityRef(
 * special/reserved characters, it outputs the string form, otherwise it
 * outputs the compound form.
 *
+ * @public
 * @deprecated Use `stringifyEntityRef` instead
- * @param ref The reference to serialize
+ * @param ref - The reference to serialize
 * @returns The same reference on either string or compound form
 */
 export function serializeEntityRef(
@@ -219,7 +227,8 @@ export function serializeEntityRef(
 * all parts of the name to lowercase and inserts the default namespace if needed.
 * It is typically not the best way to represent the entity reference to the user.
 *
- * @param ref The reference to serialize
+ * @public
+ * @param ref - The reference to serialize
 * @returns The same reference on either string or compound form
 */
 export function stringifyEntityRef(
@@ -248,9 +257,10 @@ export function stringifyEntityRef(
 * The comparison is case insensitive, and all of kind, namespace, and name
 * must match (after applying the optional context to the ref).
 *
- * @param entity The entity to match
- * @param ref A string or compound entity ref
- * @param context An optional context of default kind and namespace, that apply
+ * @public
+ * @param entity - The entity to match
+ * @param ref - A string or compound entity ref
+ * @param context - An optional context of default kind and namespace, that apply
 *                to the ref if given
 * @returns True if matching, false otherwise
 */
@@ -21,6 +21,7 @@ import { Entity } from './Entity';
 /**
 * Generates a new random UID for an entity.
 *
+ * @public
 * @returns A string with enough randomness to uniquely identify an entity
 */
 export function generateEntityUid(): string {
@@ -30,6 +31,7 @@ export function generateEntityUid(): string {
 /**
 * Generates a new random Etag for an entity.
 *
+ * @public
 * @returns A string with enough randomness to uniquely identify an entity
 *          revision
 */
@@ -48,8 +50,9 @@ export function generateEntityEtag(): string {
 * account. It only compares the actual input entity data, i.e. metadata and
 * spec.
 *
- * @param previous The old state of the entity
- * @param next The new state of the entity
+ * @public
+ * @param previous - The old state of the entity
+ * @param next - The new state of the entity
 */
 export function entityHasChanges(previous: Entity, next: Entity): boolean {
  const e1 = lodash.cloneDeep(previous);
@@ -98,8 +101,9 @@ export function entityHasChanges(previous: Entity, next: Entity): boolean {
 * The previous revision is expected to be a complete model loaded from the
 * catalog, including the uid, etag and generation fields.
 *
- * @param previous The old state of the entity
- * @param next The new state of the entity
+ * @public
+ * @param previous - The old state of the entity
+ * @param next - The new state of the entity
 * @returns An entity with the merged state of both
 */
 export function generateUpdatedEntity(previous: Entity, next: Entity): Entity {
@@ -18,6 +18,7 @@ import type { Entity } from '../entity/Entity';
 import schema from '../schema/kinds/API.v1alpha1.schema.json';
 import { ajvCompiledJsonSchemaValidator } from './util';

+/** @public */
 export interface ApiEntityV1alpha1 extends Entity {
  apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1';
  kind: 'API';
@@ -30,5 +31,6 @@ export interface ApiEntityV1alpha1 extends Entity {
  };
 }

+/** @public */
 export const apiEntityV1alpha1Validator =
  ajvCompiledJsonSchemaValidator(schema);
@@ -18,6 +18,7 @@ import type { Entity } from '../entity/Entity';
 import schema from '../schema/kinds/Component.v1alpha1.schema.json';
 import { ajvCompiledJsonSchemaValidator } from './util';

+/** @public */
 export interface ComponentEntityV1alpha1 extends Entity {
  apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1';
  kind: 'Component';
@@ -33,5 +34,6 @@ export interface ComponentEntityV1alpha1 extends Entity {
  };
 }

+/** @public */
 export const componentEntityV1alpha1Validator =
  ajvCompiledJsonSchemaValidator(schema);
@@ -18,6 +18,7 @@ import type { Entity } from '../entity/Entity';
 import schema from '../schema/kinds/Domain.v1alpha1.schema.json';
 import { ajvCompiledJsonSchemaValidator } from './util';

+/** @public */
 export interface DomainEntityV1alpha1 extends Entity {
  apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1';
  kind: 'Domain';
@@ -26,5 +27,6 @@ export interface DomainEntityV1alpha1 extends Entity {
  };
 }

+/** @public */
 export const domainEntityV1alpha1Validator =
  ajvCompiledJsonSchemaValidator(schema);
@@ -18,6 +18,7 @@ import type { Entity } from '../entity/Entity';
 import schema from '../schema/kinds/Group.v1alpha1.schema.json';
 import { ajvCompiledJsonSchemaValidator } from './util';

+/** @public */
 export interface GroupEntityV1alpha1 extends Entity {
  apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1';
  kind: 'Group';
@@ -34,5 +35,6 @@ export interface GroupEntityV1alpha1 extends Entity {
  };
 }

+/** @public */
 export const groupEntityV1alpha1Validator =
  ajvCompiledJsonSchemaValidator(schema);
@@ -18,6 +18,7 @@ import type { Entity } from '../entity/Entity';
 import schema from '../schema/kinds/Location.v1alpha1.schema.json';
 import { ajvCompiledJsonSchemaValidator } from './util';

+/** @public */
 export interface LocationEntityV1alpha1 extends Entity {
  apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1';
  kind: 'Location';
@@ -28,5 +29,6 @@ export interface LocationEntityV1alpha1 extends Entity {
  };
 }

+/** @public */
 export const locationEntityV1alpha1Validator =
  ajvCompiledJsonSchemaValidator(schema);
@@ -18,6 +18,7 @@ import type { Entity } from '../entity/Entity';
 import schema from '../schema/kinds/Resource.v1alpha1.schema.json';
 import { ajvCompiledJsonSchemaValidator } from './util';

+/** @public */
 export interface ResourceEntityV1alpha1 extends Entity {
  apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1';
  kind: 'Resource';
@@ -29,5 +30,6 @@ export interface ResourceEntityV1alpha1 extends Entity {
  };
 }

+/** @public */
 export const resourceEntityV1alpha1Validator =
  ajvCompiledJsonSchemaValidator(schema);
@@ -18,6 +18,7 @@ import type { Entity } from '../entity/Entity';
 import schema from '../schema/kinds/System.v1alpha1.schema.json';
 import { ajvCompiledJsonSchemaValidator } from './util';

+/** @public */
 export interface SystemEntityV1alpha1 extends Entity {
  apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1';
  kind: 'System';
@@ -27,5 +28,6 @@ export interface SystemEntityV1alpha1 extends Entity {
  };
 }

+/** @public */
 export const systemEntityV1alpha1Validator =
  ajvCompiledJsonSchemaValidator(schema);
@@ -19,6 +19,7 @@ import type { Entity } from '../entity/Entity';
 import schema from '../schema/kinds/Template.v1beta2.schema.json';
 import { ajvCompiledJsonSchemaValidator } from './util';

+/** @public */
 export interface TemplateEntityV1beta2 extends Entity {
  apiVersion: 'backstage.io/v1beta2';
  kind: 'Template';
@@ -37,5 +38,6 @@ export interface TemplateEntityV1beta2 extends Entity {
  };
 }

+/** @public */
 export const templateEntityV1beta2Validator =
  ajvCompiledJsonSchemaValidator(schema);
@@ -18,6 +18,7 @@ import type { Entity } from '../entity/Entity';
 import schema from '../schema/kinds/User.v1alpha1.schema.json';
 import { ajvCompiledJsonSchemaValidator } from './util';

+/** @public */
 export interface UserEntityV1alpha1 extends Entity {
  apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1';
  kind: 'User';
@@ -31,5 +32,6 @@ export interface UserEntityV1alpha1 extends Entity {
  };
 }

+/** @public */
 export const userEntityV1alpha1Validator =
  ajvCompiledJsonSchemaValidator(schema);
@@ -25,40 +25,60 @@ Naming rules for relations in priority order:
 /**
 * An ownership relation where the owner is usually an organizational
 * entity (user or group), and the other entity can be anything.
+ *
+ * @public
 */
 export const RELATION_OWNED_BY = 'ownedBy';
+/** @public */
 export const RELATION_OWNER_OF = 'ownerOf';

 /**
 * A relation with an API entity, typically from a component
+ *
+ * @public
 */
 export const RELATION_CONSUMES_API = 'consumesApi';
+/** @public */
 export const RELATION_API_CONSUMED_BY = 'apiConsumedBy';
+/** @public */
 export const RELATION_PROVIDES_API = 'providesApi';
+/** @public */
 export const RELATION_API_PROVIDED_BY = 'apiProvidedBy';

 /**
 * A relation denoting a dependency on another entity.
+ *
+ * @public
 */
 export const RELATION_DEPENDS_ON = 'dependsOn';
+/** @public */
 export const RELATION_DEPENDENCY_OF = 'dependencyOf';

 /**
 * A parent/child relation to build up a tree, used for example to describe
 * the organizational structure between groups.
+ *
+ * @public
 */
 export const RELATION_PARENT_OF = 'parentOf';
+/** @public */
 export const RELATION_CHILD_OF = 'childOf';

 /**
 * A membership relation, typically for users in a group.
+ *
+ * @public
 */
 export const RELATION_MEMBER_OF = 'memberOf';
+/** @public */
 export const RELATION_HAS_MEMBER = 'hasMember';

 /**
 * A part/whole relation, typically for components in a system and systems
 * in a domain.
+ *
+ * @public
 */
 export const RELATION_PART_OF = 'partOf';
+/** @public */
 export const RELATION_HAS_PART = 'hasPart';
@@ -18,12 +18,14 @@ import { Entity } from '../entity';

 /**
 * Validates entities of a certain kind.
+ *
+ * @public
 */
 export type KindValidator = {
  /**
   * Validates the entity as a known entity kind.
   *
-   * @param entity The entity to validate
+   * @param entity - The entity to validate
   * @returns Resolves to true, if the entity was of a kind that was known and
   *   handled by this validator, and was found to be valid. Resolves to false,
   *   if the entity was not of a kind that was known by this validator.
@@ -14,8 +14,11 @@
 * limitations under the License.
 */

+/** @public */
 export const LOCATION_ANNOTATION = 'backstage.io/managed-by-location';
+/** @public */
 export const ORIGIN_LOCATION_ANNOTATION =
  'backstage.io/managed-by-origin-location';

+/** @public */
 export const SOURCE_LOCATION_ANNOTATION = 'backstage.io/source-location';
@@ -23,8 +23,9 @@ import { LOCATION_ANNOTATION, SOURCE_LOCATION_ANNOTATION } from './annotation';
 * 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.
 *
- * @param ref A string-form location reference, e.g. 'url:https://host'
- * @returns A location reference, e.g. { type: 'url', target: 'https://host' }
+ * @public
+ * @param ref - A string-form location reference, e.g. `'url:https://host'`
+ * @returns A location reference, e.g. `{ type: 'url', target: 'https://host' }`
 */
 export function parseLocationReference(ref: string): {
  type: string;
@@ -67,8 +68,9 @@ export function parseLocationReference(ref: string): {
 * 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.
 *
- * @param ref A location reference, e.g. { type: 'url', target: 'https://host' }
- * @returns A string-form location reference, e.g. 'url:https://host'
+ * @public
+ * @param ref - A location reference, e.g. `{ type: 'url', target: 'https://host' }`
+ * @returns A string-form location reference, e.g. `'url:https://host'`
 */
 export function stringifyLocationReference(ref: {
  type: string;
@@ -89,8 +91,10 @@ export function stringifyLocationReference(ref: {
 * Returns the source code location of the Entity, to the extent that one exists.
 *
 * If the returned location type is of type 'url', the target should be readable at least
- * using the UrlReader from @backstage/backend-common. If it is not of type 'url', the caller
+ * using the UrlReader from `@backstage/backend-common`. If it is not of type 'url', the caller
 * needs to have explicit handling of each location type or signal that it is not supported.
+ *
+ * @public
 */
 export function getEntitySourceLocation(entity: Entity): {
  type: string;
@@ -14,6 +14,7 @@
 * limitations under the License.
 */

+/** @public */
 export type LocationSpec = {
  type: string;
  target: string;
@@ -23,6 +24,7 @@ export type LocationSpec = {
  presence?: 'optional' | 'required';
 };

+/** @public */
 export type Location = {
  id: string;
 } & LocationSpec;
@@ -17,7 +17,10 @@
 import * as yup from 'yup';
 import { LocationSpec, Location } from './types';

-/** @deprecated */
+/**
+ * @public
+ * @deprecated Use JSONSchema or validators instead.
+ */
 export const locationSpecSchema = yup
  .object<LocationSpec>({
    type: yup.string().required(),
@@ -27,7 +30,10 @@ export const locationSpecSchema = yup
  .noUnknown()
  .required();

-/** @deprecated */
+/**
+ * @public
+ * @deprecated Use JSONSchema or validators instead.
+ */
 export const locationSchema = yup
  .object<Location>({
    id: yup.string().required(),
@@ -37,7 +43,10 @@ export const locationSchema = yup
  .noUnknown()
  .required();

-/** @deprecated */
+/**
+ * @public
+ * @deprecated Use JSONSchema or validators instead.
+ */
 export const analyzeLocationSchema = yup
  .object<{ location: LocationSpec }>({
    location: locationSpecSchema,
@@ -17,10 +17,13 @@
 import { JsonValue } from '@backstage/config';
 import { JSONSchema7 } from 'json-schema';

+/** @public */
 export type JSONSchema = JSONSchema7 & { [key in string]?: JsonValue };

 /**
 * A complete entity name, with the full kind-namespace-name triplet.
+ *
+ * @public
 */
 export type EntityName = {
  kind: string;
@@ -36,6 +39,8 @@ export type EntityName = {
 *
 * Left-out parts of the reference need to be handled by the application,
 * either by rejecting the reference or by falling back to default values.
+ *
+ * @public
 */
 export type EntityRef =
  | string
@@ -19,16 +19,18 @@ import lodash from 'lodash';
 /**
 * Contains various helper validation and normalization functions that can be
 * composed to form a Validator.
+ *
+ * @public
 */
 export class CommonValidatorFunctions {
  /**
   * Checks that the value is on the form <suffix> or <prefix><separator><suffix>, and validates
   * those parts separately.
   *
-   * @param value The value to check
-   * @param separator The separator between parts
-   * @param isValidPrefix Checks that the part before the separator is valid, if present
-   * @param isValidSuffix Checks that the part after the separator (or the entire value if there is no separator) is valid
+   * @param value - The value to check
+   * @param separator - The separator between parts
+   * @param isValidPrefix - Checks that the part before the separator is valid, if present
+   * @param isValidSuffix - Checks that the part after the separator (or the entire value if there is no separator) is valid
   */
  static isValidPrefixAndOrSuffix(
    value: unknown,
@@ -53,7 +55,7 @@ export class CommonValidatorFunctions {
  /**
   * Checks that the value can be safely transferred as JSON.
   *
-   * @param value The value to check
+   * @param value - The value to check
   */
  static isJsonSafe(value: unknown): boolean {
    try {
@@ -66,7 +68,7 @@ export class CommonValidatorFunctions {
  /**
   * Checks that the value is a valid DNS subdomain name.
   *
-   * @param value The value to check
+   * @param value - The value to check
   * @see https://tools.ietf.org/html/rfc1123
   */
  static isValidDnsSubdomain(value: unknown): boolean {
@@ -81,7 +83,7 @@ export class CommonValidatorFunctions {
  /**
   * Checks that the value is a valid DNS label.
   *
-   * @param value The value to check
+   * @param value - The value to check
   * @see https://tools.ietf.org/html/rfc1123
   */
  static isValidDnsLabel(value: unknown): boolean {
@@ -96,7 +98,7 @@ export class CommonValidatorFunctions {
  /**
   * Checks that the value is a valid URL.
   *
-   * @param value The value to check
+   * @param value - The value to check
   */
  static isValidUrl(value: unknown): boolean {
    if (typeof value !== 'string') {
@@ -115,7 +117,7 @@ export class CommonValidatorFunctions {
  /**
   * Checks that the value is a non empty string value.
   *
-   * @param value The value to check
+   * @param value - The value to check
   */
  static isValidString(value: unknown): boolean {
    return typeof value === 'string' && value?.trim()?.length >= 1;
@@ -20,6 +20,7 @@ import { CommonValidatorFunctions } from './CommonValidatorFunctions';
 * Contains validation functions that match the Kubernetes spec, usable to
 * build a catalog that is compatible with those rule sets.
 *
+ * @public
 * @see https://kubernetes.io/docs/concepts/overview/working-with-objects/names/
 * @see https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set
 * @see https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/#syntax-and-character-set
@@ -22,7 +22,7 @@ import { compileAjvSchema, throwAjvError } from './ajv';
 /**
 * Creates a validation function that takes some arbitrary data, and either
 * returns that data cast to an {@link EntityEnvelope} (or the given subtype)
- * if it matches that schema, or throws a {@link TypeError} describing the
+ * if it matches that schema, or throws a {@link globals#TypeError} describing the
 * errors.
 *
 * Note that this validator is only meant for applying the base schema checks;
@@ -38,6 +38,7 @@ import { compileAjvSchema, throwAjvError } from './ajv';
 * - EntityMeta
 * - common#<id>
 *
+ * @public
 * @see https://github.com/backstage/backstage/tree/master/packages/catalog-model/src/schema
 */
 export function entityEnvelopeSchemaValidator<
@@ -22,20 +22,20 @@ import { compileAjvSchema, throwAjvError } from './ajv';
 * Creates a validation function that takes some arbitrary data, and either
 * returns that data cast to a `T` if it matches that schema, or `false` if the
 * schema apiVersion/kind didn't apply to that data, or throws a
- * {@link TypeError} describing actual errors.
+ * {@link globals#TypeError} describing actual errors.
 *
 * This validator is highly specialized, in that it has special treatment of
 * the `kind` and `apiVersion` root keys. This only works if your schema has
 * their rule set to `"enum"`:
 *
- * <pre>
- *   "apiVersion": {
- *      "enum": ["backstage.io/v1alpha1", "backstage.io/v1beta1"]
- *   },
- *   "kind": {
- *     "enum": ["Group"]
- *   },
- * </pre>
+ * ```
+ * "apiVersion": {
+ *    "enum": ["backstage.io/v1alpha1", "backstage.io/v1beta1"]
+ * },
+ * "kind": {
+ *   "enum": ["Group"]
+ * },
+ * ```
 *
 * In the above example, the created validator will return `false` if and only
 * if the kind and/or apiVersion mismatch.
@@ -52,6 +52,7 @@ import { compileAjvSchema, throwAjvError } from './ajv';
 * - EntityMeta
 * - common#<id>
 *
+ * @public
 * @see https://github.com/backstage/backstage/tree/master/packages/catalog-model/src/schema
 */
 export function entityKindSchemaValidator<T extends Entity>(
--- a/Show More
+++ b/Show More