From 2f16b943c925ce62a74bf4cc5943474184fa089a Mon Sep 17 00:00:00 2001 From: Camila Belo Date: Wed, 23 Feb 2022 14:28:23 +0100 Subject: [PATCH] refactor(techdocs-common): clean up preparer api Signed-off-by: Camila Belo --- .../techdocs-common/src/stages/prepare/dir.ts | 40 +++++------ .../src/stages/prepare/index.ts | 12 +++- .../src/stages/prepare/preparers.ts | 36 +++++++--- .../src/stages/prepare/types.ts | 70 +++++++++++++++++-- .../techdocs-common/src/stages/prepare/url.ts | 17 ++++- 5 files changed, 137 insertions(+), 38 deletions(-) diff --git a/packages/techdocs-common/src/stages/prepare/dir.ts b/packages/techdocs-common/src/stages/prepare/dir.ts index c8b8943266..0b43a459de 100644 --- a/packages/techdocs-common/src/stages/prepare/dir.ts +++ b/packages/techdocs-common/src/stages/prepare/dir.ts @@ -24,42 +24,40 @@ import { } from '@backstage/integration'; import { Logger } from 'winston'; import { parseReferenceAnnotation, transformDirLocation } from '../../helpers'; -import { PreparerBase, PreparerResponse } from './types'; - -export type DirectoryPreparerOptions = { - config: Config; - reader: UrlReader; -}; - -export type PreparerOptions = { logger?: Logger; etag?: string }; +import { + PreparerBase, + PreparerOptions, + PreparerResponse, + DirectoryFactory, +} from './types'; /** - * Prepares files before building documentation - * + * Preparer used to retrieve documentation files from a local directory * @public */ export class DirectoryPreparer implements PreparerBase { private readonly scmIntegrations: ScmIntegrationRegistry; private readonly reader: UrlReader; - /** - * @deprecated use static fromConfig method instead. - */ + /** @deprecated use static fromConfig method instead */ constructor(config: Config, _logger: Logger | null, reader: UrlReader) { this.reader = reader; this.scmIntegrations = ScmIntegrations.fromConfig(config); } - static fromConfig(options: DirectoryPreparerOptions): DirectoryPreparer { - return new DirectoryPreparer(options.config, null, options.reader); + /** + * Returns a directory preparer instance + * @param config - A backstage config + * @param options - A directory preparer options containing the URL reader + */ + static fromConfig( + config: Config, + options: DirectoryFactory, + ): DirectoryPreparer { + return new DirectoryPreparer(config, null, options.reader); } - /** - * - * @param entity - The parts of the format that's common to all versions/kinds of entity - * @param options - Optional logger and etag - * @returns - */ + /** {@inheritDoc PreparerBase.prepare} */ async prepare( entity: Entity, options?: PreparerOptions, diff --git a/packages/techdocs-common/src/stages/prepare/index.ts b/packages/techdocs-common/src/stages/prepare/index.ts index f129bf5315..c78e1082e2 100644 --- a/packages/techdocs-common/src/stages/prepare/index.ts +++ b/packages/techdocs-common/src/stages/prepare/index.ts @@ -16,4 +16,14 @@ export { DirectoryPreparer } from './dir'; export { UrlPreparer } from './url'; export { Preparers } from './preparers'; -export type { PreparerBuilder, PreparerBase, RemoteProtocol } from './types'; +export type { + PreparerBase, + PreparerBuilder, + PreparerFactory, + PreparerOptions, + PreparerResponse, + DirectoryFactory, + UrlFactory, + RemoteProtocol, + ETag, +} from './types'; diff --git a/packages/techdocs-common/src/stages/prepare/preparers.ts b/packages/techdocs-common/src/stages/prepare/preparers.ts index 75c9a7f23b..90207c1a1a 100644 --- a/packages/techdocs-common/src/stages/prepare/preparers.ts +++ b/packages/techdocs-common/src/stages/prepare/preparers.ts @@ -13,26 +13,34 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -import { UrlReader } from '@backstage/backend-common'; import { Entity } from '@backstage/catalog-model'; import { Config } from '@backstage/config'; -import { Logger } from 'winston'; import { parseReferenceAnnotation } from '../../helpers'; import { DirectoryPreparer } from './dir'; import { UrlPreparer } from './url'; -import { PreparerBase, PreparerBuilder, RemoteProtocol } from './types'; - -type factoryOptions = { - logger: Logger; - reader: UrlReader; -}; +import { + PreparerBase, + PreparerBuilder, + PreparerFactory, + RemoteProtocol, +} from './types'; +/** + * Collection of docs preparers + * @public + */ export class Preparers implements PreparerBuilder { private preparerMap = new Map(); + /** + * Returns a generators instance containing a generator for Tech Docs + * @public + * @param config - A Backstage configuration + * @param options - Options to configure the URL preparer + */ static async fromConfig( config: Config, - { logger, reader }: factoryOptions, + { logger, reader }: PreparerFactory, ): Promise { const preparers = new Preparers(); @@ -49,10 +57,20 @@ export class Preparers implements PreparerBuilder { return preparers; } + /** + * Register a preparer in the preparers collection + * @param protocol - url or dir to associate with preparer + * @param preparer - The preparer instance to set + */ register(protocol: RemoteProtocol, preparer: PreparerBase) { this.preparerMap.set(protocol, preparer); } + /** + * Returns the preparer for a given Tech Docs entity + * @param entity - A Tech Docs entity instance + * @returns + */ get(entity: Entity): PreparerBase { const { type } = parseReferenceAnnotation( 'backstage.io/techdocs-ref', diff --git a/packages/techdocs-common/src/stages/prepare/types.ts b/packages/techdocs-common/src/stages/prepare/types.ts index 5c219752fa..ed3d20c2dd 100644 --- a/packages/techdocs-common/src/stages/prepare/types.ts +++ b/packages/techdocs-common/src/stages/prepare/types.ts @@ -15,19 +15,72 @@ */ import type { Entity } from '@backstage/catalog-model'; +import { UrlReader } from '@backstage/backend-common'; import { Logger } from 'winston'; +/** + * Options for building preparers + * @public + */ +export type PreparerFactory = { + logger: Logger; + reader: UrlReader; +}; + +/** + * Options to configure a directory preparer. + * @public + */ +export type DirectoryFactory = { + reader: UrlReader; +}; + +/** + * Options to configure a url preparer. + * @public + */ +export type UrlFactory = PreparerFactory; + +/** + * A unique identifier of the tree blob, usually the commit SHA or etag from the target. + * @public + */ +export type ETag = string; + +/** + * Options for configuring the content preparation process. + * @public + */ +export type PreparerOptions = { + /** + * An instance of the logger + */ + logger?: Logger; + /** + * see {@link ETag} + */ + etag?: ETag; +}; + +/** + * Result of the preparation step. + * @public + */ export type PreparerResponse = { /** * The path to directory where the tree is downloaded. */ preparedDir: string; /** - * A unique identifier of the tree blob, usually the commit SHA or etag from the target. + * see {@link ETag} */ - etag: string; + etag: ETag; }; +/** + * Definition of a Tech Docs preparer + * @public + */ export type PreparerBase = { /** * Given an Entity definition from the Software Catalog, go and prepare a directory @@ -38,15 +91,20 @@ export type PreparerBase = { * updated since the last build. * @throws `NotModifiedError` when the prepared directory has not been changed since the last build. */ - prepare( - entity: Entity, - options?: { logger?: Logger; etag?: string }, - ): Promise; + prepare(entity: Entity, options?: PreparerOptions): Promise; }; +/** + * Definition for a Tech Docs preparer builder + * @public + */ export type PreparerBuilder = { register(protocol: RemoteProtocol, preparer: PreparerBase): void; get(entity: Entity): PreparerBase; }; +/** + * Location where documentation files are stored + * @public + */ export type RemoteProtocol = 'url' | 'dir'; diff --git a/packages/techdocs-common/src/stages/prepare/url.ts b/packages/techdocs-common/src/stages/prepare/url.ts index cd4a8860e4..75f10b64d5 100644 --- a/packages/techdocs-common/src/stages/prepare/url.ts +++ b/packages/techdocs-common/src/stages/prepare/url.ts @@ -19,17 +19,32 @@ import { UrlReader } from '@backstage/backend-common'; import { Entity } from '@backstage/catalog-model'; import { Logger } from 'winston'; import { getDocFilesFromRepository } from '../../helpers'; -import { PreparerBase, PreparerResponse } from './types'; +import { PreparerBase, PreparerResponse, UrlFactory } from './types'; +/** + * Preparer used to retrieve documentation files from a remote repository + * @public + */ export class UrlPreparer implements PreparerBase { private readonly logger: Logger; private readonly reader: UrlReader; + /** @deprecated use static fromConfig method instead */ constructor(reader: UrlReader, logger: Logger) { this.logger = logger; this.reader = reader; } + /** + * Returns a directory preparer instance + * @param config - A backstage config + * @param options - A directory preparer options containing the URL reader + */ + static fromConfig(options: UrlFactory): UrlPreparer { + return new UrlPreparer(options.reader, options.logger); + } + + /** {@inheritDoc PreparerBase.prepare} */ async prepare( entity: Entity, options?: { etag?: string },