@backstage/plugin-techdocs-node 1.4.4-next.0 → 1.4.4-next.2

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @backstage/plugin-techdocs-node
 
+## 1.4.4-next.2
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/backend-common@0.18.0-next.1
+  - @backstage/catalog-model@1.1.5-next.1
+  - @backstage/config@1.0.6-next.0
+  - @backstage/errors@1.1.4
+  - @backstage/integration@1.4.2-next.0
+  - @backstage/integration-aws-node@0.1.1-next.0
+  - @backstage/plugin-search-common@1.2.1-next.0
+
+## 1.4.4-next.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/backend-common@0.18.0-next.0
+  - @backstage/config@1.0.6-next.0
+  - @backstage/catalog-model@1.1.5-next.1
+  - @backstage/errors@1.1.4
+  - @backstage/integration@1.4.2-next.0
+  - @backstage/integration-aws-node@0.1.1-next.0
+  - @backstage/plugin-search-common@1.2.1-next.0
+
 ## 1.4.4-next.0
 
 ### Patch Changes

package/dist/index.cjs.js

@@ -106,6 +106,7 @@ const getCloudPathForLocalPath = (entity, localPath = "", useLegacyPathCasing =
   const relativeFilePathTriplet = `${entityRootDir}/${relativeFilePathPosix}`;
   const destination = useLegacyPathCasing ? relativeFilePathTriplet : lowerCaseEntityTriplet(relativeFilePathTriplet);
   const destinationWithRoot = [
+    // The extra filter prevents unintended double slashes and prefixes.
     ...externalStorageRootPath.split(path__default["default"].posix.sep).filter((s) => s !== ""),
     destination
   ].join("/");
@@ -383,6 +384,11 @@ const pathMkdocsYmlWithTechdocsPlugin = async (mkdocsYmlPath, logger) => {
 };
 
 const _TechdocsGenerator = class {
+  /**
+   * Returns a instance of TechDocs generator
+   * @param config - A Backstage configuration
+   * @param options - Options to configure the generator
+   */
   static fromConfig(config, options) {
     const { containerRunner, logger } = options;
     const scmIntegrations = integration.ScmIntegrations.fromConfig(config);
@@ -399,6 +405,7 @@ const _TechdocsGenerator = class {
     this.containerRunner = options.containerRunner;
     this.scmIntegrations = options.scmIntegrations;
   }
+  /** {@inheritDoc GeneratorBase.run} */
   async run(options) {
     var _a;
     const {
@@ -456,6 +463,8 @@ const _TechdocsGenerator = class {
             logStream,
             mountDirs,
             workingDir: "/input",
+            // Set the home directory inside the container as something that applications can
+            // write to, otherwise they will just fail trying to write to /
             envVars: { HOME: "/tmp" },
             pullImage: this.options.pullImage
           });
@@ -490,6 +499,10 @@ const _TechdocsGenerator = class {
   }
 };
 let TechdocsGenerator = _TechdocsGenerator;
+/**
+ * The default docker image (and version) used to generate content. Public
+ * and static so that techdocs-node consumers can use the same version.
+ */
 TechdocsGenerator.defaultDockerImage = "spotify/techdocs:v1.1.0";
 function readGeneratorConfig(config, logger) {
   var _a;
@@ -518,15 +531,29 @@ class Generators {
   constructor() {
     this.generatorMap = /* @__PURE__ */ new Map();
   }
+  /**
+   * Returns a generators instance containing a generator for TechDocs
+   * @param config - A Backstage configuration
+   * @param options - Options to configure the TechDocs generator
+   */
   static async fromConfig(config, options) {
     const generators = new Generators();
     const techdocsGenerator = TechdocsGenerator.fromConfig(config, options);
     generators.register("techdocs", techdocsGenerator);
     return generators;
   }
+  /**
+   * Register a generator in the generators collection
+   * @param generatorKey - Unique identifier for the generator
+   * @param generator - The generator instance to register
+   */
   register(generatorKey, generator) {
     this.generatorMap.set(generatorKey, generator);
   }
+  /**
+   * Returns the generator for a given TechDocs entity
+   * @param entity - A TechDocs entity instance
+   */
   get(entity) {
     const generatorKey = getGeneratorKey(entity);
     const generator = this.generatorMap.get(generatorKey);
@@ -609,6 +636,11 @@ const getDocFilesFromRepository = async (reader, entity, opts) => {
 };
 
 class DirectoryPreparer {
+  /**
+   * Returns a directory preparer instance
+   * @param config - A backstage config
+   * @param options - A directory preparer options containing a logger and reader
+   */
   static fromConfig(config, { logger, reader }) {
     return new DirectoryPreparer(config, logger, reader);
   }
@@ -616,6 +648,7 @@ class DirectoryPreparer {
     this.reader = reader;
     this.scmIntegrations = integration.ScmIntegrations.fromConfig(config);
   }
+  /** {@inheritDoc PreparerBase.prepare} */
   async prepare(entity, options) {
     var _a, _b;
     const annotation = parseReferenceAnnotation(
@@ -642,7 +675,9 @@ class DirectoryPreparer {
       }
       case "dir": {
         return {
+          // the transformation already validated that the target is in a safe location
           preparedDir: target,
+          // Instead of supporting caching on local sources, use techdocs-cli for local development and debugging.
           etag: ""
         };
       }
@@ -653,6 +688,10 @@ class DirectoryPreparer {
 }
 
 class UrlPreparer {
+  /**
+   * Returns a directory preparer instance
+   * @param config - A URL preparer config containing the a logger and reader
+   */
   static fromConfig({ reader, logger }) {
     return new UrlPreparer(reader, logger);
   }
@@ -660,6 +699,7 @@ class UrlPreparer {
     this.logger = logger;
     this.reader = reader;
   }
+  /** {@inheritDoc PreparerBase.prepare} */
   async prepare(entity, options) {
     try {
       return await getDocFilesFromRepository(this.reader, entity, {
@@ -684,6 +724,12 @@ class Preparers {
   constructor() {
     this.preparerMap = /* @__PURE__ */ new Map();
   }
+  /**
+   * Returns a generators instance containing a generator for TechDocs
+   * @public
+   * @param backstageConfig - A Backstage configuration
+   * @param preparerConfig - Options to configure preparers
+   */
   static async fromConfig(backstageConfig, { logger, reader }) {
     const preparers = new Preparers();
     const urlPreparer = UrlPreparer.fromConfig({ reader, logger });
@@ -695,9 +741,19 @@ class Preparers {
     preparers.register("dir", directoryPreparer);
     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, preparer) {
     this.preparerMap.set(protocol, preparer);
   }
+  /**
+   * Returns the preparer for a given TechDocs entity
+   * @param entity - A TechDocs entity instance
+   * @returns
+   */
   get(entity) {
     const { type } = parseReferenceAnnotation(
       "backstage.io/techdocs-ref",
@@ -818,6 +874,10 @@ class AwsS3Publish {
     }
     return explicitCredentials;
   }
+  /**
+   * Check if the defined bucket exists. Being able to connect means the configuration is good
+   * and the storage client will work.
+   */
   async getReadiness() {
     try {
       await this.storageClient.send(
@@ -837,6 +897,10 @@ class AwsS3Publish {
       };
     }
   }
+  /**
+   * Upload all the files from the generated `directory` to the S3 bucket.
+   * Directory structure used in the bucket is - entityNamespace/entityKind/entityName/index.html
+   */
   async publish({
     entity,
     directory
@@ -964,6 +1028,9 @@ class AwsS3Publish {
       throw new errors.ForwardedError("TechDocs metadata fetch failed", e);
     }
   }
+  /**
+   * Express route middleware to serve static files on a route in techdocs-backend.
+   */
   docsRouter() {
     return async (req, res) => {
       const decodedUri = decodeURI(req.path.replace(/^\//, ""));
@@ -990,6 +1057,10 @@ class AwsS3Publish {
       }
     };
   }
+  /**
+   * A helper function which checks if index.html of an Entity's docs site is available. This
+   * can be used to verify if there are any pre-generated docs available to serve.
+   */
   async hasDocsBeenGenerated(entity) {
     try {
       const entityTriplet = `${entity.metadata.namespace}/${entity.kind}/${entity.metadata.name}`;
@@ -1051,6 +1122,9 @@ class AwsS3Publish {
       )
     );
   }
+  /**
+   * Returns a list of all object keys from the configured bucket.
+   */
   async getAllObjectsFromBucket({ prefix } = { prefix: "" }) {
     const objects = [];
     let nextContinuation;
@@ -1146,6 +1220,10 @@ class AzureBlobStoragePublish {
     );
     return { isAvailable: false };
   }
+  /**
+   * Upload all the files from the generated `directory` to the Azure Blob Storage container.
+   * Directory structure used in the container is - entityNamespace/entityKind/entityName/index.html
+   */
   async publish({
     entity,
     directory
@@ -1275,6 +1353,9 @@ class AzureBlobStoragePublish {
       throw new errors.ForwardedError("TechDocs metadata fetch failed", e);
     }
   }
+  /**
+   * Express route middleware to serve static files on a route in techdocs-backend.
+   */
   docsRouter() {
     return (req, res) => {
       const decodedUri = decodeURI(req.path.replace(/^\//, ""));
@@ -1296,6 +1377,10 @@ class AzureBlobStoragePublish {
       });
     };
   }
+  /**
+   * A helper function which checks if index.html of an Entity's docs site is available. This
+   * can be used to verify if there are any pre-generated docs available to serve.
+   */
   hasDocsBeenGenerated(entity) {
     const entityTriplet = `${entity.metadata.namespace}/${entity.kind}/${entity.metadata.name}`;
     const entityRootDir = this.legacyPathCasing ? entityTriplet : lowerCaseEntityTriplet(entityTriplet);
@@ -1467,6 +1552,10 @@ class GoogleGCSPublish {
       bucketRootPath
     });
   }
+  /**
+   * Check if the defined bucket exists. Being able to connect means the configuration is good
+   * and the storage client will work.
+   */
   async getReadiness() {
     try {
       await this.storageClient.bucket(this.bucketName).getMetadata();
@@ -1485,6 +1574,10 @@ class GoogleGCSPublish {
       return { isAvailable: false };
     }
   }
+  /**
+   * Upload all the files from the generated `directory` to the GCS bucket.
+   * Directory structure used in the bucket is - entityNamespace/entityKind/entityName/index.html
+   */
   async publish({
     entity,
     directory
@@ -1577,6 +1670,9 @@ class GoogleGCSPublish {
       });
     });
   }
+  /**
+   * Express route middleware to serve static files on a route in techdocs-backend.
+   */
   docsRouter() {
     return (req, res) => {
       const decodedUri = decodeURI(req.path.replace(/^\//, ""));
@@ -1598,6 +1694,10 @@ class GoogleGCSPublish {
       }).pipe(res);
     };
   }
+  /**
+   * A helper function which checks if index.html of an Entity's docs site is available. This
+   * can be used to verify if there are any pre-generated docs available to serve.
+   */
   async hasDocsBeenGenerated(entity) {
     return new Promise((resolve) => {
       const entityTriplet = `${entity.metadata.namespace}/${entity.kind}/${entity.metadata.name}`;
@@ -1775,6 +1875,7 @@ class LocalPublish {
     });
     router.use(
       express__default["default"].static(this.staticDocsDir, {
+        // Handle content-type header the same as all other publishers.
         setHeaders: (res, filePath) => {
           const fileExtension = path__default["default"].extname(filePath);
           const headers = getHeadersForFileExtension(fileExtension);
@@ -1809,6 +1910,10 @@ class LocalPublish {
       return false;
     }
   }
+  /**
+   * This code will never run in practice. It is merely here to illustrate how
+   * to implement this method for other storage providers.
+   */
   async migrateDocsCase({
     removeOriginal = false,
     concurrency = 25
@@ -1842,6 +1947,9 @@ class LocalPublish {
       )
     );
   }
+  /**
+   * Utility wrapper around path.join(), used to control legacy case logic.
+   */
   staticEntityPathJoin(...allParts) {
     let staticEntityPath = this.staticDocsDir;
     allParts.map((part) => part.split(path__default["default"].sep)).flat().forEach((part, index) => {
@@ -1904,6 +2012,10 @@ class OpenStackSwiftPublish {
     });
     return new OpenStackSwiftPublish({ storageClient, containerName, logger });
   }
+  /*
+   * Check if the defined container exists. Being able to connect means the configuration is good
+   * and the storage client will work.
+   */
   async getReadiness() {
     try {
       const container = await this.storageClient.getContainerMetadata(
@@ -1931,6 +2043,10 @@ class OpenStackSwiftPublish {
       };
     }
   }
+  /**
+   * Upload all the files from the generated `directory` to the OpenStack Swift container.
+   * Directory structure used in the bucket is - entityNamespace/entityKind/entityName/index.html
+   */
   async publish({
     entity,
     directory
@@ -2000,6 +2116,9 @@ class OpenStackSwiftPublish {
       }
     });
   }
+  /**
+   * Express route middleware to serve static files on a route in techdocs-backend.
+   */
   docsRouter() {
     return async (req, res) => {
       const filePath = decodeURI(req.path.replace(/^\//, ""));
@@ -2033,6 +2152,10 @@ class OpenStackSwiftPublish {
       }
     };
   }
+  /**
+   * A helper function which checks if index.html of an Entity's docs site is available. This
+   * can be used to verify if there are any pre-generated docs available to serve.
+   */
   async hasDocsBeenGenerated(entity) {
     const entityRootDir = `${entity.metadata.namespace}/${entity.kind}/${entity.metadata.name}`;
     try {
@@ -2089,6 +2212,9 @@ class OpenStackSwiftPublish {
       )
     );
   }
+  /**
+   * Returns a list of all object keys from the configured container.
+   */
   async getAllObjectsFromContainer({ prefix } = { prefix: "" }) {
     let objects = [];
     const OSS_MAX_LIMIT = Math.pow(2, 31) - 1;
@@ -2103,6 +2229,11 @@ class OpenStackSwiftPublish {
 }
 
 class Publisher {
+  /**
+   * Returns a instance of TechDocs publisher
+   * @param config - A Backstage configuration
+   * @param options - Options for configuring the publisher factory
+   */
   static async fromConfig(config, { logger, discovery }) {
     var _a;
     const publisherType = (_a = config.getOptionalString(