@backstage/plugin-techdocs-node 1.12.10 → 1.12.11-next.0

package/dist/index.d.ts

@@ -2,14 +2,13 @@
 import { Entity, CompoundEntityRef } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
 import * as _backstage_backend_plugin_api from '@backstage/backend-plugin-api';
-import { UrlReaderService } from '@backstage/backend-plugin-api';
-import * as winston from 'winston';
-import { Logger } from 'winston';
-import { ContainerRunner, PluginEndpointDiscovery } from '@backstage/backend-common';
+import { LoggerService, UrlReaderService, DiscoveryService } from '@backstage/backend-plugin-api';
+import { Writable } from 'stream';
 import express from 'express';
 import { ScmIntegrationRegistry } from '@backstage/integration';
 import { IndexableDocument } from '@backstage/plugin-search-common';
-import { Writable } from 'stream';
+import * as winston from 'winston';
+import { Logger } from 'winston';
 
 /**
  * A unique identifier of the tree blob, usually the commit SHA or etag from the target.
@@ -21,7 +20,7 @@ type ETag = string;
  * @public
  */
 type PreparerConfig = {
-    logger: Logger;
+    logger: LoggerService;
     reader: UrlReaderService;
 };
 /**
@@ -32,7 +31,7 @@ type PreparerOptions = {
     /**
      * An instance of the logger
      */
-    logger?: Logger;
+    logger?: LoggerService;
     /**
      * see {@link ETag}
      */
@@ -95,7 +94,7 @@ type ParsedLocationAnnotation = {
     target: string;
 };
 /**
- * Returns a parset locations annotation
+ * Returns a parsed locations annotation
  * @public
  * @param annotationName - The name of the annotation in the entity metadata
  * @param entity - A TechDocs entity instance
@@ -120,7 +119,7 @@ declare const transformDirLocation: (entity: Entity, dirAnnotation: ParsedLocati
     target: string;
 };
 /**
- * Returns a entity reference based on the TechDocs annotation type
+ * Returns an entity reference based on the TechDocs annotation type
  * @public
  * @param entity - A TechDocs instance
  * @param scmIntegration - An implementation for  SCM integration API
@@ -135,20 +134,180 @@ declare const getLocationForEntity: (entity: Entity, scmIntegration: ScmIntegrat
  */
 declare const getDocFilesFromRepository: (reader: UrlReaderService, entity: Entity, opts?: {
     etag?: string;
-    logger?: Logger;
+    logger?: LoggerService;
 }) => Promise<PreparerResponse>;
 
+/**
+ * Options for building publishers
+ * @public
+ */
+type PublisherFactory = {
+    logger: LoggerService;
+    discovery: DiscoveryService;
+    customPublisher?: PublisherBase | undefined;
+};
+/**
+ * Key for all the different types of TechDocs publishers that are supported.
+ * @public
+ */
+type PublisherType = 'local' | 'googleGcs' | 'awsS3' | 'azureBlobStorage' | 'openStackSwift';
+/**
+ * Request publish definition
+ * @public
+ */
+type PublishRequest = {
+    entity: Entity;
+    directory: string;
+};
+/**
+ * Response containing metadata about where files were published and what may
+ * have been published or updated.
+ * @public
+ */
+type PublishResponse = {
+    /**
+     * The URL which serves files from the local publisher's static directory.
+     */
+    remoteUrl?: string;
+    /**
+     * The list of objects (specifically their paths) that were published.
+     * Objects do not have a preceding slash, and match how one would load the
+     * object over the `/static/docs/*` TechDocs Backend Plugin endpoint.
+     */
+    objects?: string[];
+} | void;
+/**
+ * Result for the validation check.
+ * @public
+ */
+type ReadinessResponse = {
+    /** If true, the publisher is able to interact with the backing storage. */
+    isAvailable: boolean;
+};
+/**
+ * Type to hold metadata found in techdocs_metadata.json and associated with each site
+ * @param etag - ETag of the resource used to generate the site. Usually the latest commit sha of the source repository.
+ * @public
+ */
+type TechDocsMetadata = {
+    site_name: string;
+    site_description: string;
+    etag: string;
+    build_timestamp: number;
+    files?: string[];
+};
+/**
+ * TechDocs entity triplet migration request
+ * @public
+ */
+type MigrateRequest = {
+    /**
+     * Whether or not to remove the source file. Defaults to false (acting like a
+     * copy instead of a move).
+     */
+    removeOriginal?: boolean;
+    /**
+     * Maximum number of files/objects to migrate at once. Defaults to 25.
+     */
+    concurrency?: number;
+};
+/**
+ * Base class for a TechDocs publisher (e.g. Local, Google GCS Bucket, AWS S3, etc.)
+ * The publisher handles publishing of the generated static files after the prepare and generate steps of TechDocs.
+ * It also provides APIs to communicate with the storage service.
+ *
+ * @public
+ */
+interface PublisherBase {
+    /**
+     * Check if the publisher is ready. This check tries to perform certain checks to see if the
+     * publisher is configured correctly and can be used to publish or read documentations.
+     * The different implementations might e.g. use the provided service credentials to access the
+     * target or check if a folder/bucket is available.
+     */
+    getReadiness(): Promise<ReadinessResponse>;
+    /**
+     * Store the generated static files onto a storage service (either local filesystem or external service).
+     *
+     * @param request - Object containing the entity from the service
+     *                  catalog, and the directory that contains the generated static files from TechDocs.
+     */
+    publish(request: PublishRequest): Promise<PublishResponse>;
+    /**
+     * Retrieve TechDocs Metadata about a site e.g. name, contributors, last updated, etc.
+     * This API uses the techdocs_metadata.json file that co-exists along with the generated docs.
+     */
+    fetchTechDocsMetadata(entityName: CompoundEntityRef): Promise<TechDocsMetadata>;
+    /**
+     * Route middleware to serve static documentation files for an entity.
+     */
+    docsRouter(): express.Handler;
+    /**
+     * Check if the index.html is present for the Entity at the Storage location.
+     */
+    hasDocsBeenGenerated(entityName: Entity): Promise<boolean>;
+    /**
+     * Migrates documentation objects with case sensitive entity triplets to
+     * lowercase entity triplets. This was (will be) a change introduced in
+     * `techdocs-cli` version `{0.x.y}` and `techdocs-backend` version `{0.x.y}`.
+     *
+     * Implementation of this method is unnecessary in publishers introduced
+     * after version `{0.x.y}` of `techdocs-node`.
+     */
+    migrateDocsCase?(migrateRequest: MigrateRequest): Promise<void>;
+}
+/**
+ * Definition for a TechDocs publisher builder
+ * @public
+ */
+type PublisherBuilder = {
+    register(type: PublisherType, publisher: PublisherBase): void;
+    get(config: Config): PublisherBase;
+};
+/**
+ * Handles the running of containers, on behalf of others.
+ *
+ * @public
+ */
+interface TechDocsContainerRunner {
+    /**
+     * Runs a container image to completion.
+     */
+    runContainer(opts: {
+        imageName: string;
+        command?: string | string[];
+        args: string[];
+        logStream?: Writable;
+        mountDirs?: Record<string, string>;
+        workingDir?: string;
+        envVars?: Record<string, string>;
+        pullImage?: boolean;
+        defaultUser?: boolean;
+        pullOptions?: {
+            authconfig?: {
+                username?: string;
+                password?: string;
+                auth?: string;
+                email?: string;
+                serveraddress?: string;
+                [key: string]: unknown;
+            };
+            [key: string]: unknown;
+        };
+    }): Promise<void>;
+}
+
 /**
  * Options for building generators
  * @public
  */
 type GeneratorOptions = {
-    logger: Logger;
+    logger: LoggerService;
     /**
      * @deprecated containerRunner is now instantiated in
      * the generator and this option will be removed in the future
      */
-    containerRunner?: ContainerRunner;
+    containerRunner?: TechDocsContainerRunner;
 };
 /**
  * The values that the generator will receive.
@@ -220,8 +379,8 @@ declare class TechdocsGenerator implements GeneratorBase {
      */
     static fromConfig(config: Config, options: GeneratorOptions): TechdocsGenerator;
     constructor(options: {
-        logger: Logger;
-        containerRunner?: ContainerRunner;
+        logger: LoggerService;
+        containerRunner?: TechDocsContainerRunner;
         config: Config;
         scmIntegrations: ScmIntegrationRegistry;
     });
@@ -241,8 +400,8 @@ declare class Generators implements GeneratorBuilder {
      * @param options - Options to configure the TechDocs generator
      */
     static fromConfig(config: Config, options: {
-        logger: Logger;
-        containerRunner?: ContainerRunner;
+        logger: LoggerService;
+        containerRunner?: TechDocsContainerRunner;
         customGenerator?: TechdocsGenerator;
     }): Promise<GeneratorBuilder>;
     /**
@@ -356,134 +515,6 @@ declare class Preparers implements PreparerBuilder {
     get(entity: Entity): PreparerBase;
 }
 
-/**
- * Options for building publishers
- * @public
- */
-type PublisherFactory = {
-    logger: Logger;
-    discovery: PluginEndpointDiscovery;
-    customPublisher?: PublisherBase | undefined;
-};
-/**
- * Key for all the different types of TechDocs publishers that are supported.
- * @public
- */
-type PublisherType = 'local' | 'googleGcs' | 'awsS3' | 'azureBlobStorage' | 'openStackSwift';
-/**
- * Request publish definition
- * @public
- */
-type PublishRequest = {
-    entity: Entity;
-    directory: string;
-};
-/**
- * Response containing metadata about where files were published and what may
- * have been published or updated.
- * @public
- */
-type PublishResponse = {
-    /**
-     * The URL which serves files from the local publisher's static directory.
-     */
-    remoteUrl?: string;
-    /**
-     * The list of objects (specifically their paths) that were published.
-     * Objects do not have a preceding slash, and match how one would load the
-     * object over the `/static/docs/*` TechDocs Backend Plugin endpoint.
-     */
-    objects?: string[];
-} | void;
-/**
- * Result for the validation check.
- * @public
- */
-type ReadinessResponse = {
-    /** If true, the publisher is able to interact with the backing storage. */
-    isAvailable: boolean;
-};
-/**
- * Type to hold metadata found in techdocs_metadata.json and associated with each site
- * @param etag - ETag of the resource used to generate the site. Usually the latest commit sha of the source repository.
- * @public
- */
-type TechDocsMetadata = {
-    site_name: string;
-    site_description: string;
-    etag: string;
-    build_timestamp: number;
-    files?: string[];
-};
-/**
- * TechDocs entity triplet migration request
- * @public
- */
-type MigrateRequest = {
-    /**
-     * Whether or not to remove the source file. Defaults to false (acting like a
-     * copy instead of a move).
-     */
-    removeOriginal?: boolean;
-    /**
-     * Maximum number of files/objects to migrate at once. Defaults to 25.
-     */
-    concurrency?: number;
-};
-/**
- * Base class for a TechDocs publisher (e.g. Local, Google GCS Bucket, AWS S3, etc.)
- * The publisher handles publishing of the generated static files after the prepare and generate steps of TechDocs.
- * It also provides APIs to communicate with the storage service.
- *
- * @public
- */
-interface PublisherBase {
-    /**
-     * Check if the publisher is ready. This check tries to perform certain checks to see if the
-     * publisher is configured correctly and can be used to publish or read documentations.
-     * The different implementations might e.g. use the provided service credentials to access the
-     * target or check if a folder/bucket is available.
-     */
-    getReadiness(): Promise<ReadinessResponse>;
-    /**
-     * Store the generated static files onto a storage service (either local filesystem or external service).
-     *
-     * @param request - Object containing the entity from the service
-     *                  catalog, and the directory that contains the generated static files from TechDocs.
-     */
-    publish(request: PublishRequest): Promise<PublishResponse>;
-    /**
-     * Retrieve TechDocs Metadata about a site e.g. name, contributors, last updated, etc.
-     * This API uses the techdocs_metadata.json file that co-exists along with the generated docs.
-     */
-    fetchTechDocsMetadata(entityName: CompoundEntityRef): Promise<TechDocsMetadata>;
-    /**
-     * Route middleware to serve static documentation files for an entity.
-     */
-    docsRouter(): express.Handler;
-    /**
-     * Check if the index.html is present for the Entity at the Storage location.
-     */
-    hasDocsBeenGenerated(entityName: Entity): Promise<boolean>;
-    /**
-     * Migrates documentation objects with case sensitive entity triplets to
-     * lowercase entity triplets. This was (will be) a change introduced in
-     * `techdocs-cli` version `{0.x.y}` and `techdocs-backend` version `{0.x.y}`.
-     *
-     * Implementation of this method is unnecessary in publishers introduced
-     * after version `{0.x.y}` of `techdocs-node`.
-     */
-    migrateDocsCase?(migrateRequest: MigrateRequest): Promise<void>;
-}
-/**
- * Definition for a TechDocs publisher builder
- * @public
- */
-type PublisherBuilder = {
-    register(type: PublisherType, publisher: PublisherBase): void;
-    get(config: Config): PublisherBase;
-};
-
 /**
  * Factory class to create a TechDocs publisher based on defined publisher type in app config.
  * Uses `techdocs.publisher.type`.
@@ -543,7 +574,7 @@ interface DocsBuildStrategy {
 }
 
 /**
- * Extension point type for configuring Techdocs builds.
+ * Extension point type for configuring TechDocs builds.
  *
  * @public
  */
@@ -552,13 +583,13 @@ interface TechdocsBuildsExtensionPoint {
     setBuildLogTransport(transport: winston.transport): void;
 }
 /**
- * Extension point for configuring Techdocs builds.
+ * Extension point for configuring TechDocs builds.
  *
  * @public
  */
 declare const techdocsBuildsExtensionPoint: _backstage_backend_plugin_api.ExtensionPoint<TechdocsBuildsExtensionPoint>;
 /**
- * Extension point type for configuring a custom Techdocs generator
+ * Extension point type for configuring a custom TechDocs generator
  *
  * @public
  */
@@ -566,13 +597,13 @@ interface TechdocsGeneratorExtensionPoint {
     setTechdocsGenerator(generator: TechdocsGenerator): void;
 }
 /**
- * Extension point for configuring a custom Techdocs generator
+ * Extension point for configuring a custom TechDocs generator
  *
  * @public
  */
 declare const techdocsGeneratorExtensionPoint: _backstage_backend_plugin_api.ExtensionPoint<TechdocsGeneratorExtensionPoint>;
 /**
- * Extension point type for configuring a custom Techdocs preparer
+ * Extension point type for configuring a custom TechDocs preparer
  *
  * @public
  */
@@ -580,13 +611,13 @@ interface TechdocsPreparerExtensionPoint {
     registerPreparer(protocol: RemoteProtocol, preparer: PreparerBase): void;
 }
 /**
- * Extension point for configuring a custom Techdocs preparer
+ * Extension point for configuring a custom TechDocs preparer
  *
  * @public
  */
 declare const techdocsPreparerExtensionPoint: _backstage_backend_plugin_api.ExtensionPoint<TechdocsPreparerExtensionPoint>;
 /**
- * Extension point type for configuring a custom Techdocs publisher
+ * Extension point type for configuring a custom TechDocs publisher
  *
  * @public
  */
@@ -594,10 +625,10 @@ interface TechdocsPublisherExtensionPoint {
     registerPublisher(type: PublisherType, publisher: PublisherBase): void;
 }
 /**
- * Extension point for configuring a custom Techdocs publisher
+ * Extension point for configuring a custom TechDocs publisher
  *
  * @public
  */
 declare const techdocsPublisherExtensionPoint: _backstage_backend_plugin_api.ExtensionPoint<TechdocsPublisherExtensionPoint>;
 
-export { DirectoryPreparer, type DocsBuildStrategy, type ETag, type GeneratorBase, type GeneratorBuilder, type GeneratorOptions, type GeneratorRunOptions, Generators, type MigrateRequest, type ParsedLocationAnnotation, type PreparerBase, type PreparerBuilder, type PreparerConfig, type PreparerOptions, type PreparerResponse, Preparers, type PublishRequest, type PublishResponse, Publisher, type PublisherBase, type PublisherBuilder, type PublisherFactory, type PublisherType, type ReadinessResponse, type RemoteProtocol, type SupportedGeneratorKey, type TechDocsDocument, type TechDocsMetadata, type TechdocsBuildsExtensionPoint, TechdocsGenerator, type TechdocsGeneratorExtensionPoint, type TechdocsPreparerExtensionPoint, type TechdocsPublisherExtensionPoint, UrlPreparer, getDocFilesFromRepository, getLocationForEntity, getMkDocsYml, getMkdocsYml, parseReferenceAnnotation, techdocsBuildsExtensionPoint, techdocsGeneratorExtensionPoint, techdocsPreparerExtensionPoint, techdocsPublisherExtensionPoint, transformDirLocation };
+export { DirectoryPreparer, type DocsBuildStrategy, type ETag, type GeneratorBase, type GeneratorBuilder, type GeneratorOptions, type GeneratorRunOptions, Generators, type MigrateRequest, type ParsedLocationAnnotation, type PreparerBase, type PreparerBuilder, type PreparerConfig, type PreparerOptions, type PreparerResponse, Preparers, type PublishRequest, type PublishResponse, Publisher, type PublisherBase, type PublisherBuilder, type PublisherFactory, type PublisherType, type ReadinessResponse, type RemoteProtocol, type SupportedGeneratorKey, type TechDocsContainerRunner, type TechDocsDocument, type TechDocsMetadata, type TechdocsBuildsExtensionPoint, TechdocsGenerator, type TechdocsGeneratorExtensionPoint, type TechdocsPreparerExtensionPoint, type TechdocsPublisherExtensionPoint, UrlPreparer, getDocFilesFromRepository, getLocationForEntity, getMkDocsYml, getMkdocsYml, parseReferenceAnnotation, techdocsBuildsExtensionPoint, techdocsGeneratorExtensionPoint, techdocsPreparerExtensionPoint, techdocsPublisherExtensionPoint, transformDirLocation };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/plugin-techdocs-node",
-  "version": "1.12.10",
+  "version": "1.12.11-next.0",
   "description": "Common node.js functionalities for TechDocs, to be shared between techdocs-backend plugin and techdocs-cli",
   "backstage": {
     "role": "node-library",
@@ -53,8 +53,7 @@
     "@aws-sdk/types": "^3.347.0",
     "@azure/identity": "^4.0.0",
     "@azure/storage-blob": "^12.5.0",
-    "@backstage/backend-common": "^0.24.1",
-    "@backstage/backend-plugin-api": "^0.8.1",
+    "@backstage/backend-plugin-api": "^0.9.0-next.0",
     "@backstage/catalog-model": "^1.6.0",
     "@backstage/config": "^1.2.0",
     "@backstage/errors": "^1.2.4",
@@ -79,8 +78,8 @@
     "winston": "^3.2.1"
   },
   "devDependencies": {
-    "@backstage/backend-test-utils": "^0.5.1",
-    "@backstage/cli": "^0.27.0",
+    "@backstage/backend-test-utils": "^0.6.0-next.0",
+    "@backstage/cli": "^0.27.1-next.0",
     "@types/fs-extra": "^11.0.0",
     "@types/js-yaml": "^4.0.0",
     "@types/mime-types": "^2.1.0",