diff --git a/packages/techdocs-common/api-report.md b/packages/techdocs-common/api-report.md index 53d107bd17..3997a5d03d 100644 --- a/packages/techdocs-common/api-report.md +++ b/packages/techdocs-common/api-report.md @@ -17,36 +17,42 @@ import { ScmIntegrationRegistry } from '@backstage/integration'; import { UrlReader } from '@backstage/backend-common'; import { Writable } from 'stream'; +// @public +export type DirectoryFactory = { + reader: UrlReader; +}; + // @public export class DirectoryPreparer implements PreparerBase { // @deprecated constructor(config: Config, _logger: Logger_2 | null, reader: UrlReader); - // Warning: (ae-forgotten-export) The symbol "DirectoryPreparerOptions" needs to be exported by the entry point index.d.ts - // - // (undocumented) - static fromConfig(options: DirectoryPreparerOptions): DirectoryPreparer; - // Warning: (ae-forgotten-export) The symbol "PreparerOptions" needs to be exported by the entry point index.d.ts - // Warning: (ae-forgotten-export) The symbol "PreparerResponse" needs to be exported by the entry point index.d.ts - // - // (undocumented) + static fromConfig( + config: Config, + options: DirectoryFactory, + ): DirectoryPreparer; prepare(entity: Entity, options?: PreparerOptions): Promise; } -// Warning: (ae-missing-release-tag) "GeneratorBase" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public +export type ETag = string; + +// @public export type GeneratorBase = { run(opts: GeneratorRunOptions): Promise; }; -// Warning: (ae-missing-release-tag) "GeneratorBuilder" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export type GeneratorBuilder = { register(protocol: SupportedGeneratorKey, generator: GeneratorBase): void; get(entity: Entity): GeneratorBase; }; +// @public +export type GeneratorFactory = { + containerRunner: ContainerRunner; + logger: Logger_2; +}; + // @public export type GeneratorRunOptions = { inputDir: string; @@ -57,11 +63,8 @@ export type GeneratorRunOptions = { logStream?: Writable; }; -// Warning: (ae-missing-release-tag) "Generators" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export class Generators implements GeneratorBuilder { - // (undocumented) static fromConfig( config: Config, options: { @@ -69,15 +72,11 @@ export class Generators implements GeneratorBuilder { containerRunner: ContainerRunner; }, ): Promise; - // (undocumented) get(entity: Entity): GeneratorBase; - // (undocumented) register(generatorKey: SupportedGeneratorKey, generator: GeneratorBase): void; } -// Warning: (ae-missing-release-tag) "getDocFilesFromRepository" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export const getDocFilesFromRepository: ( reader: UrlReader, entity: Entity, @@ -89,78 +88,74 @@ export const getDocFilesFromRepository: ( | undefined, ) => Promise; -// Warning: (ae-missing-release-tag) "getLocationForEntity" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export const getLocationForEntity: ( entity: Entity, scmIntegration: ScmIntegrationRegistry, ) => ParsedLocationAnnotation; -// Warning: (ae-missing-release-tag) "ParsedLocationAnnotation" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public +export type MigrateRequest = { + removeOriginal?: boolean; + concurrency?: number; +}; + +// @public export type ParsedLocationAnnotation = { type: RemoteProtocol; target: string; }; -// Warning: (ae-missing-release-tag) "parseReferenceAnnotation" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export const parseReferenceAnnotation: ( annotationName: string, entity: Entity, ) => ParsedLocationAnnotation; -// Warning: (ae-missing-release-tag) "PreparerBase" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export type PreparerBase = { - prepare( - entity: Entity, - options?: { - logger?: Logger_2; - etag?: string; - }, - ): Promise; + prepare(entity: Entity, options?: PreparerOptions): Promise; }; -// Warning: (ae-missing-release-tag) "PreparerBuilder" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export type PreparerBuilder = { register(protocol: RemoteProtocol, preparer: PreparerBase): void; get(entity: Entity): PreparerBase; }; -// Warning: (ae-missing-release-tag) "Preparers" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public +export type PreparerFactory = { + logger: Logger_2; + reader: UrlReader; +}; + +// @public +export type PreparerOptions = { + logger?: Logger_2; + etag?: ETag; +}; + +// @public +export type PreparerResponse = { + preparedDir: string; + etag: ETag; +}; + +// @public export class Preparers implements PreparerBuilder { - // Warning: (ae-forgotten-export) The symbol "factoryOptions" needs to be exported by the entry point index.d.ts - // - // (undocumented) static fromConfig( config: Config, - { logger, reader }: factoryOptions, + { logger, reader }: PreparerFactory, ): Promise; - // (undocumented) get(entity: Entity): PreparerBase; - // (undocumented) register(protocol: RemoteProtocol, preparer: PreparerBase): void; } -// Warning: (ae-missing-release-tag) "Publisher" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export class Publisher { - // Warning: (ae-forgotten-export) The symbol "factoryOptions" needs to be exported by the entry point index.d.ts - // - // (undocumented) static fromConfig( config: Config, - { logger, discovery }: factoryOptions_2, + { logger, discovery }: PublisherFactory, ): Promise; } @@ -170,15 +165,16 @@ export interface PublisherBase { fetchTechDocsMetadata(entityName: EntityName): Promise; getReadiness(): Promise; hasDocsBeenGenerated(entityName: Entity): Promise; - // Warning: (ae-forgotten-export) The symbol "MigrateRequest" needs to be exported by the entry point index.d.ts migrateDocsCase?(migrateRequest: MigrateRequest): Promise; - // Warning: (ae-forgotten-export) The symbol "PublishRequest" needs to be exported by the entry point index.d.ts - // Warning: (ae-forgotten-export) The symbol "PublishResponse" needs to be exported by the entry point index.d.ts publish(request: PublishRequest): Promise; } -// Warning: (ae-missing-release-tag) "PublisherType" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// +// @public +export type PublisherFactory = { + logger: Logger_2; + discovery: PluginEndpointDiscovery; +}; + // @public export type PublisherType = | 'local' @@ -187,37 +183,40 @@ export type PublisherType = | 'azureBlobStorage' | 'openStackSwift'; +// @public +export type PublishRequest = { + entity: Entity; + directory: string; +}; + +// @public +export type PublishResponse = { + remoteUrl?: string; + objects?: string[]; +} | void; + // @public export type ReadinessResponse = { isAvailable: boolean; }; -// Warning: (ae-missing-release-tag) "RemoteProtocol" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export type RemoteProtocol = 'url' | 'dir'; -// Warning: (ae-missing-release-tag) "TechDocsDocument" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public +export type SupportedGeneratorKey = 'techdocs' | string; + +// @public export interface TechDocsDocument extends IndexableDocument { - // (undocumented) kind: string; - // (undocumented) lifecycle: string; - // (undocumented) name: string; - // (undocumented) namespace: string; - // (undocumented) owner: string; - // (undocumented) path: string; } -// Warning: (ae-missing-release-tag) "TechdocsGenerator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export class TechdocsGenerator implements GeneratorBase { constructor(options: { logger: Logger_2; @@ -226,20 +225,13 @@ export class TechdocsGenerator implements GeneratorBase { scmIntegrations: ScmIntegrationRegistry; }); static readonly defaultDockerImage = 'spotify/techdocs:v0.3.7'; - // (undocumented) static fromConfig( config: Config, - options: { - containerRunner: ContainerRunner; - logger: Logger_2; - }, + options: GeneratorFactory, ): TechdocsGenerator; - // (undocumented) run(options: GeneratorRunOptions): Promise; } -// Warning: (ae-missing-release-tag) "TechDocsMetadata" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export type TechDocsMetadata = { site_name: string; @@ -249,8 +241,6 @@ export type TechDocsMetadata = { files?: string[]; }; -// Warning: (ae-missing-release-tag) "transformDirLocation" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export const transformDirLocation: ( entity: Entity, @@ -261,12 +251,14 @@ export const transformDirLocation: ( target: string; }; -// Warning: (ae-missing-release-tag) "UrlPreparer" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public +export type UrlFactory = PreparerFactory; + +// @public export class UrlPreparer implements PreparerBase { + // @deprecated constructor(reader: UrlReader, logger: Logger_2); - // (undocumented) + static fromConfig(options: UrlFactory): UrlPreparer; prepare( entity: Entity, options?: { @@ -274,8 +266,4 @@ export class UrlPreparer implements PreparerBase { }, ): Promise; } - -// Warnings were encountered during analysis: -// -// src/stages/generate/types.d.ts:45:5 - (ae-forgotten-export) The symbol "SupportedGeneratorKey" needs to be exported by the entry point index.d.ts ``` diff --git a/packages/techdocs-common/config.d.ts b/packages/techdocs-common/config.d.ts deleted file mode 100644 index 54e76c1a1c..0000000000 --- a/packages/techdocs-common/config.d.ts +++ /dev/null @@ -1,195 +0,0 @@ -/* - * Copyright 2022 The Backstage Authors - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -export interface Config { - app: { - baseUrl: string; // defined in core, but repeated here without doc - }; - - backend: { - /** Backend configuration for when request authentication is enabled */ - auth?: { - /** Keys shared by all backends for signing and validating backend tokens. */ - keys: { - /** - * Secret for generating tokens. Should be a base64 string, recommended - * length is 24 bytes. - * - * @visibility secret - */ - secret: string; - }[]; - }; - - baseUrl: string; // defined in core, but repeated here without doc - - /** Address that the backend should listen to. */ - listen: - | string - | { - /** Address of the interface that the backend should bind to. */ - host?: string; - /** Port that the backend should listen to. */ - port?: string | number; - }; - - /** - * HTTPS configuration for the backend. If omitted the backend will serve HTTP. - * - * Setting this to `true` will cause self-signed certificates to be generated, which - * can be useful for local development or other non-production scenarios. - */ - https?: - | true - | { - /** Certificate configuration */ - certificate?: { - /** PEM encoded certificate. Use $file to load in a file */ - cert: string; - /** - * PEM encoded certificate key. Use $file to load in a file. - * @visibility secret - */ - key: string; - }; - }; - - /** Database connection configuration, select base database type using the `client` field */ - database: { - /** Default database client to use */ - client: 'sqlite3' | 'pg'; - /** - * Base database connection string or Knex object - * @secret - */ - connection: string | object; - /** Database name prefix override */ - prefix?: string; - /** - * Whether to ensure the given database exists by creating it if it does not. - * Defaults to true if unspecified. - */ - ensureExists?: boolean; - /** - * How plugins databases are managed/divided in the provided database instance. - * - * `database` -> Plugins are each given their own database to manage their schemas/tables. - * - * `schema` -> Plugins will be given their own schema (in the specified/default database) - * to manage their tables. - * - * NOTE: Currently only supported by the `pg` client. - * - * @default database - */ - pluginDivisionMode?: 'database' | 'schema'; - /** - * Arbitrary config object to pass to knex when initializing - * (https://knexjs.org/#Installation-client). Most notable is the debug - * and asyncStackTraces booleans - */ - knexConfig?: object; - /** Plugin specific database configuration and client override */ - plugin?: { - [pluginId: string]: { - /** Database client override */ - client?: 'sqlite3' | 'pg'; - /** - * Database connection string or Knex object override - * @secret - */ - connection?: string | object; - /** - * Whether to ensure the given database exists by creating it if it does not. - * Defaults to base config if unspecified. - */ - ensureExists?: boolean; - /** - * Arbitrary config object to pass to knex when initializing - * (https://knexjs.org/#Installation-client). Most notable is the - * debug and asyncStackTraces booleans. - * - * This is merged recursively into the base knexConfig - */ - knexConfig?: object; - }; - }; - }; - - /** Cache connection configuration, select cache type using the `store` field */ - cache?: - | { - store: 'memory'; - } - | { - store: 'memcache'; - /** - * A memcache connection string in the form `user:pass@host:port`. - * @secret - */ - connection: string; - }; - - cors?: { - origin?: string | string[]; - methods?: string | string[]; - allowedHeaders?: string | string[]; - exposedHeaders?: string | string[]; - credentials?: boolean; - maxAge?: number; - preflightContinue?: boolean; - optionsSuccessStatus?: number; - }; - - /** - * Configuration related to URL reading, used for example for reading catalog info - * files, scaffolder templates, and techdocs content. - */ - reading?: { - /** - * A list of targets to allow outgoing requests to. Users will be able to make - * requests on behalf of the backend to the targets that are allowed by this list. - */ - allow?: Array<{ - /** - * A host to allow outgoing requests to, being either a full host or - * a subdomain wildcard pattern with a leading `*`. For example `example.com` - * and `*.example.com` are valid values, `prod.*.example.com` is not. - * The host may also contain a port, for example `example.com:8080`. - */ - host: string; - - /** - * An optional list of paths. In case they are present only targets matching - * any of them will are allowed. You can use trailing slashes to make sure only - * subdirectories are allowed, for example `/mydir/` will allow targets with - * paths like `/mydir/a` but will block paths like `/mydir2`. - */ - paths?: string[]; - }>; - }; - - /** - * Content Security Policy options. - * - * The keys are the plain policy ID, e.g. "upgrade-insecure-requests". The - * values are on the format that the helmet library expects them, as an - * array of strings. There is also the special value false, which means to - * remove the default value that Backstage puts in place for that policy. - */ - csp?: { [policyId: string]: string[] | false }; - }; -}