refactor(techdocs-common): apply review suggestions

Signed-off-by: Camila Belo <camilaibs@gmail.com>

packages/techdocs-common/api-report.md

@@ -17,18 +17,13 @@ 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);
   static fromConfig(
     config: Config,
-    options: DirectoryFactory,
+    { logger, reader }: PreparerConfig,
   ): DirectoryPreparer;
   prepare(entity: Entity, options?: PreparerOptions): Promise<PreparerResponse>;
 }
@@ -48,7 +43,7 @@ export type GeneratorBuilder = {
 };
 
 // @public
-export type GeneratorFactory = {
+export type GeneratorOptions = {
   containerRunner: ContainerRunner;
   logger: Logger_2;
 };
@@ -124,7 +119,7 @@ export type PreparerBuilder = {
 };
 
 // @public
-export type PreparerFactory = {
+export type PreparerConfig = {
   logger: Logger_2;
   reader: UrlReader;
 };
@@ -144,8 +139,8 @@ export type PreparerResponse = {
 // @public
 export class Preparers implements PreparerBuilder {
   static fromConfig(
-    config: Config,
-    { logger, reader }: PreparerFactory,
+    backstageConfig: Config,
+    { logger, reader }: PreparerConfig,
   ): Promise<PreparerBuilder>;
   get(entity: Entity): PreparerBase;
   register(protocol: RemoteProtocol, preparer: PreparerBase): void;
@@ -227,7 +222,7 @@ export class TechdocsGenerator implements GeneratorBase {
   static readonly defaultDockerImage = 'spotify/techdocs:v0.3.7';
   static fromConfig(
     config: Config,
-    options: GeneratorFactory,
+    options: GeneratorOptions,
   ): TechdocsGenerator;
   run(options: GeneratorRunOptions): Promise<void>;
 }
@@ -251,19 +246,11 @@ export const transformDirLocation: (
   target: string;
 };
 
-// @public
-export type UrlFactory = PreparerFactory;
-
 // @public
 export class UrlPreparer implements PreparerBase {
   // @deprecated
   constructor(reader: UrlReader, logger: Logger_2);
-  static fromConfig(options: UrlFactory): UrlPreparer;
-  prepare(
-    entity: Entity,
-    options?: {
-      etag?: string;
-    },
-  ): Promise<PreparerResponse>;
+  static fromConfig({ reader, logger }: PreparerConfig): UrlPreparer;
+  prepare(entity: Entity, options?: PreparerOptions): Promise<PreparerResponse>;
 }
 ```

packages/techdocs-common/src/helpers.ts

@@ -39,7 +39,7 @@ export type ParsedLocationAnnotation = {
  * Returns a parset locations annotation
  * @public
  * @param annotationName - The name of the annotation in the entity metadata
- * @param entity - A Tech Docs entity instance
+ * @param entity - A TechDocs entity instance
  */
 export const parseReferenceAnnotation = (
   annotationName: string,
@@ -112,9 +112,9 @@ export const transformDirLocation = (
 };
 
 /**
- * Returns a entity reference based on the Tech Docs annotation type
+ * Returns a entity reference based on the TechDocs annotation type
  * @public
- * @param entity - A Tech Docs instance
+ * @param entity - A TechDocs instance
  * @param scmIntegration - An implementation for  SCM integration API
  */
 export const getLocationForEntity = (
@@ -140,7 +140,7 @@ export const getLocationForEntity = (
  * Returns a preparer response {@link PreparerResponse}
  * @public
  * @param reader - Read a tree of files from a repository
- * @param entity - A Tech Docs entity instance
+ * @param entity - A TechDocs entity instance
  * @param opts - Options for configuring the reader, e.g. logger, etag, etc.
  */
 export const getDocFilesFromRepository = async (

packages/techdocs-common/src/stages/generate/generators.ts

@@ -34,9 +34,9 @@ export class Generators implements GeneratorBuilder {
   private generatorMap = new Map<SupportedGeneratorKey, GeneratorBase>();
 
   /**
-   * Returns a generators instance containing a generator for Tech Docs
+   * Returns a generators instance containing a generator for TechDocs
    * @param config - A Backstage configuration
-   * @param options - Options to configure the Tech Docs generator
+   * @param options - Options to configure the TechDocs generator
    */
   static async fromConfig(
     config: Config,
@@ -60,8 +60,8 @@ export class Generators implements GeneratorBuilder {
   }
 
   /**
-   * Returns the generator for a given Tech Docs entity
-   * @param entity - A Tech Docs entity instance
+   * Returns the generator for a given TechDocs entity
+   * @param entity - A TechDocs entity instance
    */
   get(entity: Entity): GeneratorBase {
     const generatorKey = getGeneratorKey(entity);

packages/techdocs-common/src/stages/generate/index.ts

@@ -17,8 +17,8 @@ export { TechdocsGenerator } from './techdocs';
 export { Generators } from './generators';
 export type {
   GeneratorBase,
+  GeneratorOptions,
   GeneratorBuilder,
-  GeneratorFactory,
   GeneratorRunOptions,
   SupportedGeneratorKey,
 } from './types';

packages/techdocs-common/src/stages/generate/techdocs.ts

@@ -34,11 +34,11 @@ import {
 import {
   GeneratorBase,
   GeneratorConfig,
+  GeneratorOptions,
   GeneratorRunInType,
   GeneratorRunOptions,
 } from './types';
 import { ForwardedError } from '@backstage/errors';
-import { GeneratorFactory } from './types';
 
 /**
  * Generates documentation files
@@ -56,11 +56,11 @@ export class TechdocsGenerator implements GeneratorBase {
   private readonly scmIntegrations: ScmIntegrationRegistry;
 
   /**
-   * Returns a instance of Tech Docs generator
+   * Returns a instance of TechDocs generator
    * @param config - A Backstage configuration
    * @param options - Options to configure the generator
    */
-  static fromConfig(config: Config, options: GeneratorFactory) {
+  static fromConfig(config: Config, options: GeneratorOptions) {
     const { containerRunner, logger } = options;
     const scmIntegrations = ScmIntegrations.fromConfig(config);
     return new TechdocsGenerator({

packages/techdocs-common/src/stages/generate/types.ts

@@ -27,7 +27,7 @@ export type GeneratorRunInType = 'docker' | 'local';
  * Options for building generators
  * @public
  */
-export type GeneratorFactory = {
+export type GeneratorOptions = {
   containerRunner: ContainerRunner;
   logger: Logger;
 };

packages/techdocs-common/src/stages/prepare/dir.ts

@@ -26,9 +26,9 @@ import { Logger } from 'winston';
 import { parseReferenceAnnotation, transformDirLocation } from '../../helpers';
 import {
   PreparerBase,
+  PreparerConfig,
   PreparerOptions,
   PreparerResponse,
-  DirectoryFactory,
 } from './types';
 
 /**
@@ -48,13 +48,13 @@ export class DirectoryPreparer implements PreparerBase {
   /**
    * Returns a directory preparer instance
    * @param config - A backstage config
-   * @param options - A directory preparer options containing the URL reader
+   * @param options - A directory preparer options containing a logger and reader
    */
   static fromConfig(
     config: Config,
-    options: DirectoryFactory,
+    { logger, reader }: PreparerConfig,
   ): DirectoryPreparer {
-    return new DirectoryPreparer(config, null, options.reader);
+    return new DirectoryPreparer(config, logger, reader);
   }
 
   /** {@inheritDoc PreparerBase.prepare} */

packages/techdocs-common/src/stages/prepare/index.ts

@@ -19,11 +19,9 @@ export { Preparers } from './preparers';
 export type {
   PreparerBase,
   PreparerBuilder,
-  PreparerFactory,
+  PreparerConfig,
   PreparerOptions,
   PreparerResponse,
-  DirectoryFactory,
-  UrlFactory,
   RemoteProtocol,
   ETag,
 } from './types';

packages/techdocs-common/src/stages/prepare/preparers.ts

@@ -21,26 +21,26 @@ import { UrlPreparer } from './url';
 import {
   PreparerBase,
   PreparerBuilder,
-  PreparerFactory,
+  PreparerConfig,
   RemoteProtocol,
 } from './types';
 
 /**
- * Collection of docs preparers
+ * Collection of docs preparers (dir and url)
  * @public
  */
 export class Preparers implements PreparerBuilder {
   private preparerMap = new Map<RemoteProtocol, PreparerBase>();
 
   /**
-   * Returns a generators instance containing a generator for Tech Docs
+   * Returns a generators instance containing a generator for TechDocs
    * @public
-   * @param config - A Backstage configuration
-   * @param options - Options to configure the URL preparer
+   * @param backstageConfig - A Backstage configuration
+   * @param preparerConfig - Options to configure preparers
    */
   static async fromConfig(
-    config: Config,
-    { logger, reader }: PreparerFactory,
+    backstageConfig: Config,
+    { logger, reader }: PreparerConfig,
   ): Promise<PreparerBuilder> {
     const preparers = new Preparers();
 
@@ -51,7 +51,11 @@ export class Preparers implements PreparerBuilder {
      * Dir preparer is a syntactic sugar for users to define techdocs-ref annotation.
      * When using dir preparer, the docs will be fetched using URL Reader.
      */
-    const directoryPreparer = new DirectoryPreparer(config, logger, reader);
+    const directoryPreparer = new DirectoryPreparer(
+      backstageConfig,
+      logger,
+      reader,
+    );
     preparers.register('dir', directoryPreparer);
 
     return preparers;
@@ -67,8 +71,8 @@ export class Preparers implements PreparerBuilder {
   }
 
   /**
-   * Returns the preparer for a given Tech Docs entity
-   * @param entity - A Tech Docs entity instance
+   * Returns the preparer for a given TechDocs entity
+   * @param entity - A TechDocs entity instance
    * @returns
    */
   get(entity: Entity): PreparerBase {

packages/techdocs-common/src/stages/prepare/types.ts

@@ -18,35 +18,21 @@ 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 building preparers
+ * @public
+ */
+export type PreparerConfig = {
+  logger: Logger;
+  reader: UrlReader;
+};
+
 /**
  * Options for configuring the content preparation process.
  * @public
@@ -78,7 +64,7 @@ export type PreparerResponse = {
 };
 
 /**
- * Definition of a Tech Docs preparer
+ * Definition of a TechDocs preparer
  * @public
  */
 export type PreparerBase = {
@@ -95,7 +81,7 @@ export type PreparerBase = {
 };
 
 /**
- * Definition for a Tech Docs preparer builder
+ * Definition for a TechDocs preparer builder
  * @public
  */
 export type PreparerBuilder = {

packages/techdocs-common/src/stages/prepare/url.ts

@@ -19,7 +19,12 @@ import { UrlReader } from '@backstage/backend-common';
 import { Entity } from '@backstage/catalog-model';
 import { Logger } from 'winston';
 import { getDocFilesFromRepository } from '../../helpers';
-import { PreparerBase, PreparerResponse, UrlFactory } from './types';
+import {
+  PreparerBase,
+  PreparerConfig,
+  PreparerOptions,
+  PreparerResponse,
+} from './types';
 
 /**
  * Preparer used to retrieve documentation files from a remote repository
@@ -37,17 +42,16 @@ export class UrlPreparer implements PreparerBase {
 
   /**
    * Returns a directory preparer instance
-   * @param config - A backstage config
-   * @param options - A directory preparer options containing the URL reader
+   * @param config - A URL preparer config containing the a logger and reader
    */
-  static fromConfig(options: UrlFactory): UrlPreparer {
-    return new UrlPreparer(options.reader, options.logger);
+  static fromConfig({ reader, logger }: PreparerConfig): UrlPreparer {
+    return new UrlPreparer(reader, logger);
   }
 
   /** {@inheritDoc PreparerBase.prepare} */
   async prepare(
     entity: Entity,
-    options?: { etag?: string },
+    options?: PreparerOptions,
   ): Promise<PreparerResponse> {
     try {
       return await getDocFilesFromRepository(this.reader, entity, {

packages/techdocs-common/src/stages/publish/publish.ts

@@ -29,7 +29,7 @@ import { PublisherFactory, PublisherBase, PublisherType } from './types';
  */
 export class Publisher {
   /**
-   * Returns a instance of Tech Docs publisher
+   * Returns a instance of TechDocs publisher
    * @param config - A Backstage configuration
    * @param options - Options for configuring the publisher factory
    */

packages/techdocs-common/src/stages/publish/types.ts

@@ -89,7 +89,7 @@ export type TechDocsMetadata = {
 };
 
 /**
- * Tech Docs entity triplet migration request
+ * TechDocs entity triplet migration request
  * @public
  */
 export type MigrateRequest = {

packages/techdocs-common/src/techdocsTypes.ts

@@ -17,7 +17,7 @@
 import { IndexableDocument } from '@backstage/search-common';
 
 /**
- * Tech Docs indexable document interface
+ * TechDocs indexable document interface
  * @public
  */
 export interface TechDocsDocument extends IndexableDocument {