@backstage/plugin-techdocs-node 1.12.12-next.1 → 1.12.12

package/dist/stages/generate/techdocs.cjs.js

@@ -0,0 +1,169 @@
+'use strict';
+
+var path = require('path');
+var integration = require('@backstage/integration');
+var helpers = require('./helpers.cjs.js');
+var mkdocsPatchers = require('./mkdocsPatchers.cjs.js');
+var errors = require('@backstage/errors');
+var DockerContainerRunner = require('./DockerContainerRunner.cjs.js');
+
+function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e : { default: e }; }
+
+var path__default = /*#__PURE__*/_interopDefaultCompat(path);
+
+class TechdocsGenerator {
+  /**
+   * The default docker image (and version) used to generate content. Public
+   * and static so that techdocs-node consumers can use the same version.
+   */
+  static defaultDockerImage = "spotify/techdocs:v1.2.4";
+  logger;
+  containerRunner;
+  options;
+  scmIntegrations;
+  /**
+   * 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);
+    return new TechdocsGenerator({
+      logger,
+      containerRunner,
+      config,
+      scmIntegrations
+    });
+  }
+  constructor(options) {
+    this.logger = options.logger;
+    this.options = readGeneratorConfig(options.config, options.logger);
+    this.containerRunner = options.containerRunner;
+    this.scmIntegrations = options.scmIntegrations;
+  }
+  /** {@inheritDoc GeneratorBase.run} */
+  async run(options) {
+    const {
+      inputDir,
+      outputDir,
+      parsedLocationAnnotation,
+      etag,
+      logger: childLogger,
+      logStream,
+      siteOptions,
+      runAsDefaultUser
+    } = options;
+    const { path: mkdocsYmlPath, content } = await helpers.getMkdocsYml(
+      inputDir,
+      siteOptions
+    );
+    const docsDir = await helpers.validateMkdocsYaml(inputDir, content);
+    if (parsedLocationAnnotation) {
+      await mkdocsPatchers.patchMkdocsYmlPreBuild(
+        mkdocsYmlPath,
+        childLogger,
+        parsedLocationAnnotation,
+        this.scmIntegrations
+      );
+    }
+    if (this.options.legacyCopyReadmeMdToIndexMd) {
+      await helpers.patchIndexPreBuild({ inputDir, logger: childLogger, docsDir });
+    }
+    const defaultPlugins = this.options.defaultPlugins ?? [];
+    if (!this.options.omitTechdocsCoreMkdocsPlugin && !defaultPlugins.includes("techdocs-core")) {
+      defaultPlugins.push("techdocs-core");
+    }
+    await mkdocsPatchers.patchMkdocsYmlWithPlugins(mkdocsYmlPath, childLogger, defaultPlugins);
+    const mountDirs = {
+      [inputDir]: "/input",
+      [outputDir]: "/output"
+    };
+    try {
+      switch (this.options.runIn) {
+        case "local":
+          await helpers.runCommand({
+            command: "mkdocs",
+            args: ["build", "-d", outputDir, "-v"],
+            options: {
+              cwd: inputDir
+            },
+            logStream
+          });
+          childLogger.info(
+            `Successfully generated docs from ${inputDir} into ${outputDir} using local mkdocs`
+          );
+          break;
+        case "docker": {
+          const containerRunner = this.containerRunner || new DockerContainerRunner.DockerContainerRunner();
+          await containerRunner.runContainer({
+            imageName: this.options.dockerImage ?? TechdocsGenerator.defaultDockerImage,
+            args: ["build", "-d", "/output"],
+            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,
+            defaultUser: runAsDefaultUser
+          });
+          childLogger.info(
+            `Successfully generated docs from ${inputDir} into ${outputDir} using techdocs-container`
+          );
+          break;
+        }
+        default:
+          throw new Error(
+            `Invalid config value "${this.options.runIn}" provided in 'techdocs.generators.techdocs'.`
+          );
+      }
+    } catch (error) {
+      this.logger.debug(
+        `Failed to generate docs from ${inputDir} into ${outputDir}`
+      );
+      throw new errors.ForwardedError(
+        `Failed to generate docs from ${inputDir} into ${outputDir}`,
+        error
+      );
+    }
+    await helpers.createOrUpdateMetadata(
+      path__default.default.join(outputDir, "techdocs_metadata.json"),
+      childLogger
+    );
+    if (etag) {
+      await helpers.storeEtagMetadata(
+        path__default.default.join(outputDir, "techdocs_metadata.json"),
+        etag
+      );
+    }
+  }
+}
+function readGeneratorConfig(config, logger) {
+  const legacyGeneratorType = config.getOptionalString(
+    "techdocs.generators.techdocs"
+  );
+  if (legacyGeneratorType) {
+    logger.warn(
+      `The 'techdocs.generators.techdocs' configuration key is deprecated and will be removed in the future. Please use 'techdocs.generator' instead. See here https://backstage.io/docs/features/techdocs/configuration`
+    );
+  }
+  return {
+    runIn: legacyGeneratorType ?? config.getOptionalString("techdocs.generator.runIn") ?? "docker",
+    dockerImage: config.getOptionalString("techdocs.generator.dockerImage"),
+    pullImage: config.getOptionalBoolean("techdocs.generator.pullImage"),
+    omitTechdocsCoreMkdocsPlugin: config.getOptionalBoolean(
+      "techdocs.generator.mkdocs.omitTechdocsCorePlugin"
+    ),
+    legacyCopyReadmeMdToIndexMd: config.getOptionalBoolean(
+      "techdocs.generator.mkdocs.legacyCopyReadmeMdToIndexMd"
+    ),
+    defaultPlugins: config.getOptionalStringArray(
+      "techdocs.generator.mkdocs.defaultPlugins"
+    )
+  };
+}
+
+exports.TechdocsGenerator = TechdocsGenerator;
+exports.readGeneratorConfig = readGeneratorConfig;
+//# sourceMappingURL=techdocs.cjs.js.map

package/dist/stages/generate/techdocs.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"techdocs.cjs.js","sources":["../../../src/stages/generate/techdocs.ts"],"sourcesContent":["/*\n * Copyright 2020 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Config } from '@backstage/config';\nimport path from 'path';\nimport {\n  ScmIntegrationRegistry,\n  ScmIntegrations,\n} from '@backstage/integration';\nimport {\n  createOrUpdateMetadata,\n  getMkdocsYml,\n  patchIndexPreBuild,\n  runCommand,\n  storeEtagMetadata,\n  validateMkdocsYaml,\n} from './helpers';\n\nimport {\n  patchMkdocsYmlPreBuild,\n  patchMkdocsYmlWithPlugins,\n} from './mkdocsPatchers';\nimport {\n  GeneratorBase,\n  GeneratorConfig,\n  GeneratorOptions,\n  GeneratorRunInType,\n  GeneratorRunOptions,\n} from './types';\nimport { ForwardedError } from '@backstage/errors';\nimport { DockerContainerRunner } from './DockerContainerRunner';\nimport { LoggerService } from '@backstage/backend-plugin-api';\nimport { TechDocsContainerRunner } from './types';\n\n/**\n * Generates documentation files\n * @public\n */\nexport class TechdocsGenerator implements GeneratorBase {\n  /**\n   * The default docker image (and version) used to generate content. Public\n   * and static so that techdocs-node consumers can use the same version.\n   */\n  public static readonly defaultDockerImage = 'spotify/techdocs:v1.2.4';\n  private readonly logger: LoggerService;\n  private readonly containerRunner?: TechDocsContainerRunner;\n  private readonly options: GeneratorConfig;\n  private readonly scmIntegrations: ScmIntegrationRegistry;\n\n  /**\n   * Returns a instance of TechDocs generator\n   * @param config - A Backstage configuration\n   * @param options - Options to configure the generator\n   */\n  static fromConfig(config: Config, options: GeneratorOptions) {\n    const { containerRunner, logger } = options;\n    const scmIntegrations = ScmIntegrations.fromConfig(config);\n    return new TechdocsGenerator({\n      logger,\n      containerRunner,\n      config,\n      scmIntegrations,\n    });\n  }\n\n  constructor(options: {\n    logger: LoggerService;\n    containerRunner?: TechDocsContainerRunner;\n    config: Config;\n    scmIntegrations: ScmIntegrationRegistry;\n  }) {\n    this.logger = options.logger;\n    this.options = readGeneratorConfig(options.config, options.logger);\n    this.containerRunner = options.containerRunner;\n    this.scmIntegrations = options.scmIntegrations;\n  }\n\n  /** {@inheritDoc GeneratorBase.run} */\n  public async run(options: GeneratorRunOptions): Promise<void> {\n    const {\n      inputDir,\n      outputDir,\n      parsedLocationAnnotation,\n      etag,\n      logger: childLogger,\n      logStream,\n      siteOptions,\n      runAsDefaultUser,\n    } = options;\n\n    // Do some updates to mkdocs.yml before generating docs e.g. adding repo_url\n    const { path: mkdocsYmlPath, content } = await getMkdocsYml(\n      inputDir,\n      siteOptions,\n    );\n\n    // validate the docs_dir first\n    const docsDir = await validateMkdocsYaml(inputDir, content);\n\n    if (parsedLocationAnnotation) {\n      await patchMkdocsYmlPreBuild(\n        mkdocsYmlPath,\n        childLogger,\n        parsedLocationAnnotation,\n        this.scmIntegrations,\n      );\n    }\n\n    if (this.options.legacyCopyReadmeMdToIndexMd) {\n      await patchIndexPreBuild({ inputDir, logger: childLogger, docsDir });\n    }\n\n    // patch the list of mkdocs plugins\n    const defaultPlugins = this.options.defaultPlugins ?? [];\n\n    if (\n      !this.options.omitTechdocsCoreMkdocsPlugin &&\n      !defaultPlugins.includes('techdocs-core')\n    ) {\n      defaultPlugins.push('techdocs-core');\n    }\n\n    await patchMkdocsYmlWithPlugins(mkdocsYmlPath, childLogger, defaultPlugins);\n\n    // Directories to bind on container\n    const mountDirs = {\n      [inputDir]: '/input',\n      [outputDir]: '/output',\n    };\n\n    try {\n      switch (this.options.runIn) {\n        case 'local':\n          await runCommand({\n            command: 'mkdocs',\n            args: ['build', '-d', outputDir, '-v'],\n            options: {\n              cwd: inputDir,\n            },\n            logStream,\n          });\n          childLogger.info(\n            `Successfully generated docs from ${inputDir} into ${outputDir} using local mkdocs`,\n          );\n          break;\n        case 'docker': {\n          const containerRunner =\n            this.containerRunner || new DockerContainerRunner();\n          await containerRunner.runContainer({\n            imageName:\n              this.options.dockerImage ?? TechdocsGenerator.defaultDockerImage,\n            args: ['build', '-d', '/output'],\n            logStream,\n            mountDirs,\n            workingDir: '/input',\n            // Set the home directory inside the container as something that applications can\n            // write to, otherwise they will just fail trying to write to /\n            envVars: { HOME: '/tmp' },\n            pullImage: this.options.pullImage,\n            defaultUser: runAsDefaultUser,\n          });\n          childLogger.info(\n            `Successfully generated docs from ${inputDir} into ${outputDir} using techdocs-container`,\n          );\n          break;\n        }\n        default:\n          throw new Error(\n            `Invalid config value \"${this.options.runIn}\" provided in 'techdocs.generators.techdocs'.`,\n          );\n      }\n    } catch (error) {\n      this.logger.debug(\n        `Failed to generate docs from ${inputDir} into ${outputDir}`,\n      );\n      throw new ForwardedError(\n        `Failed to generate docs from ${inputDir} into ${outputDir}`,\n        error,\n      );\n    }\n\n    /**\n     * Post Generate steps\n     */\n\n    // Add build timestamp and files to techdocs_metadata.json\n    // Creates techdocs_metadata.json if file does not exist.\n    await createOrUpdateMetadata(\n      path.join(outputDir, 'techdocs_metadata.json'),\n      childLogger,\n    );\n\n    // Add etag of the prepared tree to techdocs_metadata.json\n    // Assumes that the file already exists.\n    if (etag) {\n      await storeEtagMetadata(\n        path.join(outputDir, 'techdocs_metadata.json'),\n        etag,\n      );\n    }\n  }\n}\n\nexport function readGeneratorConfig(\n  config: Config,\n  logger: LoggerService,\n): GeneratorConfig {\n  const legacyGeneratorType = config.getOptionalString(\n    'techdocs.generators.techdocs',\n  ) as GeneratorRunInType;\n\n  if (legacyGeneratorType) {\n    logger.warn(\n      `The 'techdocs.generators.techdocs' configuration key is deprecated and will be removed in the future. Please use 'techdocs.generator' instead. ` +\n        `See here https://backstage.io/docs/features/techdocs/configuration`,\n    );\n  }\n\n  return {\n    runIn:\n      legacyGeneratorType ??\n      config.getOptionalString('techdocs.generator.runIn') ??\n      'docker',\n    dockerImage: config.getOptionalString('techdocs.generator.dockerImage'),\n    pullImage: config.getOptionalBoolean('techdocs.generator.pullImage'),\n    omitTechdocsCoreMkdocsPlugin: config.getOptionalBoolean(\n      'techdocs.generator.mkdocs.omitTechdocsCorePlugin',\n    ),\n    legacyCopyReadmeMdToIndexMd: config.getOptionalBoolean(\n      'techdocs.generator.mkdocs.legacyCopyReadmeMdToIndexMd',\n    ),\n    defaultPlugins: config.getOptionalStringArray(\n      'techdocs.generator.mkdocs.defaultPlugins',\n    ),\n  };\n}\n"],"names":["ScmIntegrations","getMkdocsYml","validateMkdocsYaml","patchMkdocsYmlPreBuild","patchIndexPreBuild","patchMkdocsYmlWithPlugins","runCommand","DockerContainerRunner","ForwardedError","createOrUpdateMetadata","path","storeEtagMetadata"],"mappings":"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"}

package/dist/stages/prepare/dir.cjs.js

@@ -0,0 +1,63 @@
+'use strict';
+
+var errors = require('@backstage/errors');
+var integration = require('@backstage/integration');
+var pluginTechdocsCommon = require('@backstage/plugin-techdocs-common');
+var helpers = require('../../helpers.cjs.js');
+
+class DirectoryPreparer {
+  scmIntegrations;
+  reader;
+  /**
+   * Returns a directory preparer instance
+   * @param config - A backstage config
+   * @param options - A directory preparer options containing a logger and reader
+   */
+  static fromConfig(config, options) {
+    return new DirectoryPreparer(config, options.logger, options.reader);
+  }
+  constructor(config, _logger, reader) {
+    this.reader = reader;
+    this.scmIntegrations = integration.ScmIntegrations.fromConfig(config);
+  }
+  /** {@inheritDoc PreparerBase.shouldCleanPreparedDirectory} */
+  shouldCleanPreparedDirectory() {
+    return false;
+  }
+  /** {@inheritDoc PreparerBase.prepare} */
+  async prepare(entity, options) {
+    const annotation = helpers.parseReferenceAnnotation(pluginTechdocsCommon.TECHDOCS_ANNOTATION, entity);
+    const { type, target } = helpers.transformDirLocation(
+      entity,
+      annotation,
+      this.scmIntegrations
+    );
+    switch (type) {
+      case "url": {
+        options?.logger?.debug(`Reading files from ${target}`);
+        const response = await this.reader.readTree(target, {
+          etag: options?.etag
+        });
+        const preparedDir = await response.dir();
+        options?.logger?.debug(`Tree downloaded and stored at ${preparedDir}`);
+        return {
+          preparedDir,
+          etag: response.etag
+        };
+      }
+      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: ""
+        };
+      }
+      default:
+        throw new errors.InputError(`Unable to resolve location type ${type}`);
+    }
+  }
+}
+
+exports.DirectoryPreparer = DirectoryPreparer;
+//# sourceMappingURL=dir.cjs.js.map

package/dist/stages/prepare/dir.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dir.cjs.js","sources":["../../../src/stages/prepare/dir.ts"],"sourcesContent":["/*\n * Copyright 2020 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Entity } from '@backstage/catalog-model';\nimport { Config } from '@backstage/config';\nimport { InputError } from '@backstage/errors';\nimport {\n  ScmIntegrationRegistry,\n  ScmIntegrations,\n} from '@backstage/integration';\nimport { TECHDOCS_ANNOTATION } from '@backstage/plugin-techdocs-common';\nimport { parseReferenceAnnotation, transformDirLocation } from '../../helpers';\nimport {\n  PreparerBase,\n  PreparerConfig,\n  PreparerOptions,\n  PreparerResponse,\n} from './types';\nimport { LoggerService, UrlReaderService } from '@backstage/backend-plugin-api';\n\n/**\n * Preparer used to retrieve documentation files from a local directory\n * @public\n */\nexport class DirectoryPreparer implements PreparerBase {\n  private readonly scmIntegrations: ScmIntegrationRegistry;\n  private readonly reader: UrlReaderService;\n\n  /**\n   * Returns a directory preparer instance\n   * @param config - A backstage config\n   * @param options - A directory preparer options containing a logger and reader\n   */\n  static fromConfig(\n    config: Config,\n    options: PreparerConfig,\n  ): DirectoryPreparer {\n    return new DirectoryPreparer(config, options.logger, options.reader);\n  }\n\n  private constructor(\n    config: Config,\n    _logger: LoggerService | null,\n    reader: UrlReaderService,\n  ) {\n    this.reader = reader;\n    this.scmIntegrations = ScmIntegrations.fromConfig(config);\n  }\n\n  /** {@inheritDoc PreparerBase.shouldCleanPreparedDirectory} */\n  shouldCleanPreparedDirectory() {\n    return false;\n  }\n\n  /** {@inheritDoc PreparerBase.prepare} */\n  async prepare(\n    entity: Entity,\n    options?: PreparerOptions,\n  ): Promise<PreparerResponse> {\n    const annotation = parseReferenceAnnotation(TECHDOCS_ANNOTATION, entity);\n    const { type, target } = transformDirLocation(\n      entity,\n      annotation,\n      this.scmIntegrations,\n    );\n\n    switch (type) {\n      case 'url': {\n        options?.logger?.debug(`Reading files from ${target}`);\n        // the target is an absolute url since it has already been transformed\n        const response = await this.reader.readTree(target, {\n          etag: options?.etag,\n        });\n        const preparedDir = await response.dir();\n\n        options?.logger?.debug(`Tree downloaded and stored at ${preparedDir}`);\n\n        return {\n          preparedDir,\n          etag: response.etag,\n        };\n      }\n\n      case 'dir': {\n        return {\n          // the transformation already validated that the target is in a safe location\n          preparedDir: target,\n          // Instead of supporting caching on local sources, use techdocs-cli for local development and debugging.\n          etag: '',\n        };\n      }\n\n      default:\n        throw new InputError(`Unable to resolve location type ${type}`);\n    }\n  }\n}\n"],"names":["ScmIntegrations","parseReferenceAnnotation","TECHDOCS_ANNOTATION","transformDirLocation","InputError"],"mappings":";;;;;;;AAqCO,MAAM,iBAA0C,CAAA;AAAA,EACpC,eAAA,CAAA;AAAA,EACA,MAAA,CAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOjB,OAAO,UACL,CAAA,MAAA,EACA,OACmB,EAAA;AACnB,IAAA,OAAO,IAAI,iBAAkB,CAAA,MAAA,EAAQ,OAAQ,CAAA,MAAA,EAAQ,QAAQ,MAAM,CAAA,CAAA;AAAA,GACrE;AAAA,EAEQ,WAAA,CACN,MACA,EAAA,OAAA,EACA,MACA,EAAA;AACA,IAAA,IAAA,CAAK,MAAS,GAAA,MAAA,CAAA;AACd,IAAK,IAAA,CAAA,eAAA,GAAkBA,2BAAgB,CAAA,UAAA,CAAW,MAAM,CAAA,CAAA;AAAA,GAC1D;AAAA;AAAA,EAGA,4BAA+B,GAAA;AAC7B,IAAO,OAAA,KAAA,CAAA;AAAA,GACT;AAAA;AAAA,EAGA,MAAM,OACJ,CAAA,MAAA,EACA,OAC2B,EAAA;AAC3B,IAAM,MAAA,UAAA,GAAaC,gCAAyB,CAAAC,wCAAA,EAAqB,MAAM,CAAA,CAAA;AACvE,IAAM,MAAA,EAAE,IAAM,EAAA,MAAA,EAAW,GAAAC,4BAAA;AAAA,MACvB,MAAA;AAAA,MACA,UAAA;AAAA,MACA,IAAK,CAAA,eAAA;AAAA,KACP,CAAA;AAEA,IAAA,QAAQ,IAAM;AAAA,MACZ,KAAK,KAAO,EAAA;AACV,QAAA,OAAA,EAAS,MAAQ,EAAA,KAAA,CAAM,CAAsB,mBAAA,EAAA,MAAM,CAAE,CAAA,CAAA,CAAA;AAErD,QAAA,MAAM,QAAW,GAAA,MAAM,IAAK,CAAA,MAAA,CAAO,SAAS,MAAQ,EAAA;AAAA,UAClD,MAAM,OAAS,EAAA,IAAA;AAAA,SAChB,CAAA,CAAA;AACD,QAAM,MAAA,WAAA,GAAc,MAAM,QAAA,CAAS,GAAI,EAAA,CAAA;AAEvC,QAAA,OAAA,EAAS,MAAQ,EAAA,KAAA,CAAM,CAAiC,8BAAA,EAAA,WAAW,CAAE,CAAA,CAAA,CAAA;AAErE,QAAO,OAAA;AAAA,UACL,WAAA;AAAA,UACA,MAAM,QAAS,CAAA,IAAA;AAAA,SACjB,CAAA;AAAA,OACF;AAAA,MAEA,KAAK,KAAO,EAAA;AACV,QAAO,OAAA;AAAA;AAAA,UAEL,WAAa,EAAA,MAAA;AAAA;AAAA,UAEb,IAAM,EAAA,EAAA;AAAA,SACR,CAAA;AAAA,OACF;AAAA,MAEA;AACE,QAAA,MAAM,IAAIC,iBAAA,CAAW,CAAmC,gCAAA,EAAA,IAAI,CAAE,CAAA,CAAA,CAAA;AAAA,KAClE;AAAA,GACF;AACF;;;;"}

package/dist/stages/prepare/preparers.cjs.js

@@ -0,0 +1,54 @@
+'use strict';
+
+var pluginTechdocsCommon = require('@backstage/plugin-techdocs-common');
+var helpers = require('../../helpers.cjs.js');
+var dir = require('./dir.cjs.js');
+var url = require('./url.cjs.js');
+
+class Preparers {
+  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, options) {
+    const preparers = new Preparers();
+    const urlPreparer = url.UrlPreparer.fromConfig({
+      reader: options.reader,
+      logger: options.logger
+    });
+    preparers.register("url", urlPreparer);
+    const directoryPreparer = dir.DirectoryPreparer.fromConfig(backstageConfig, {
+      reader: options.reader,
+      logger: options.logger
+    });
+    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 } = helpers.parseReferenceAnnotation(pluginTechdocsCommon.TECHDOCS_ANNOTATION, entity);
+    const preparer = this.preparerMap.get(type);
+    if (!preparer) {
+      throw new Error(`No preparer registered for type: "${type}"`);
+    }
+    return preparer;
+  }
+}
+
+exports.Preparers = Preparers;
+//# sourceMappingURL=preparers.cjs.js.map

package/dist/stages/prepare/preparers.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preparers.cjs.js","sources":["../../../src/stages/prepare/preparers.ts"],"sourcesContent":["/*\n * Copyright 2020 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport { Entity } from '@backstage/catalog-model';\nimport { Config } from '@backstage/config';\nimport { TECHDOCS_ANNOTATION } from '@backstage/plugin-techdocs-common';\nimport { parseReferenceAnnotation } from '../../helpers';\nimport { DirectoryPreparer } from './dir';\nimport { UrlPreparer } from './url';\nimport {\n  PreparerBase,\n  PreparerBuilder,\n  PreparerConfig,\n  RemoteProtocol,\n} from './types';\n\n/**\n * Collection of docs preparers (dir and url)\n * @public\n */\nexport class Preparers implements PreparerBuilder {\n  private preparerMap = new Map<RemoteProtocol, PreparerBase>();\n\n  /**\n   * Returns a generators instance containing a generator for TechDocs\n   * @public\n   * @param backstageConfig - A Backstage configuration\n   * @param preparerConfig - Options to configure preparers\n   */\n  static async fromConfig(\n    backstageConfig: Config,\n    options: PreparerConfig,\n  ): Promise<PreparerBuilder> {\n    const preparers = new Preparers();\n\n    const urlPreparer = UrlPreparer.fromConfig({\n      reader: options.reader,\n      logger: options.logger,\n    });\n    preparers.register('url', urlPreparer);\n\n    /**\n     * Dir preparer is a syntactic sugar for users to define techdocs-ref annotation.\n     * When using dir preparer, the docs will be fetched using URL Reader.\n     */\n    const directoryPreparer = DirectoryPreparer.fromConfig(backstageConfig, {\n      reader: options.reader,\n      logger: options.logger,\n    });\n    preparers.register('dir', directoryPreparer);\n\n    return preparers;\n  }\n\n  /**\n   * Register a preparer in the preparers collection\n   * @param protocol - url or dir to associate with preparer\n   * @param preparer - The preparer instance to set\n   */\n  register(protocol: RemoteProtocol, preparer: PreparerBase) {\n    this.preparerMap.set(protocol, preparer);\n  }\n\n  /**\n   * Returns the preparer for a given TechDocs entity\n   * @param entity - A TechDocs entity instance\n   * @returns\n   */\n  get(entity: Entity): PreparerBase {\n    const { type } = parseReferenceAnnotation(TECHDOCS_ANNOTATION, entity);\n    const preparer = this.preparerMap.get(type);\n\n    if (!preparer) {\n      throw new Error(`No preparer registered for type: \"${type}\"`);\n    }\n\n    return preparer;\n  }\n}\n"],"names":["UrlPreparer","DirectoryPreparer","parseReferenceAnnotation","TECHDOCS_ANNOTATION"],"mappings":";;;;;;;AAgCO,MAAM,SAAqC,CAAA;AAAA,EACxC,WAAA,uBAAkB,GAAkC,EAAA,CAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQ5D,aAAa,UACX,CAAA,eAAA,EACA,OAC0B,EAAA;AAC1B,IAAM,MAAA,SAAA,GAAY,IAAI,SAAU,EAAA,CAAA;AAEhC,IAAM,MAAA,WAAA,GAAcA,gBAAY,UAAW,CAAA;AAAA,MACzC,QAAQ,OAAQ,CAAA,MAAA;AAAA,MAChB,QAAQ,OAAQ,CAAA,MAAA;AAAA,KACjB,CAAA,CAAA;AACD,IAAU,SAAA,CAAA,QAAA,CAAS,OAAO,WAAW,CAAA,CAAA;AAMrC,IAAM,MAAA,iBAAA,GAAoBC,qBAAkB,CAAA,UAAA,CAAW,eAAiB,EAAA;AAAA,MACtE,QAAQ,OAAQ,CAAA,MAAA;AAAA,MAChB,QAAQ,OAAQ,CAAA,MAAA;AAAA,KACjB,CAAA,CAAA;AACD,IAAU,SAAA,CAAA,QAAA,CAAS,OAAO,iBAAiB,CAAA,CAAA;AAE3C,IAAO,OAAA,SAAA,CAAA;AAAA,GACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,QAAA,CAAS,UAA0B,QAAwB,EAAA;AACzD,IAAK,IAAA,CAAA,WAAA,CAAY,GAAI,CAAA,QAAA,EAAU,QAAQ,CAAA,CAAA;AAAA,GACzC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,IAAI,MAA8B,EAAA;AAChC,IAAA,MAAM,EAAE,IAAA,EAAS,GAAAC,gCAAA,CAAyBC,0CAAqB,MAAM,CAAA,CAAA;AACrE,IAAA,MAAM,QAAW,GAAA,IAAA,CAAK,WAAY,CAAA,GAAA,CAAI,IAAI,CAAA,CAAA;AAE1C,IAAA,IAAI,CAAC,QAAU,EAAA;AACb,MAAA,MAAM,IAAI,KAAA,CAAM,CAAqC,kCAAA,EAAA,IAAI,CAAG,CAAA,CAAA,CAAA,CAAA;AAAA,KAC9D;AAEA,IAAO,OAAA,QAAA,CAAA;AAAA,GACT;AACF;;;;"}

package/dist/stages/prepare/url.cjs.js

@@ -0,0 +1,46 @@
+'use strict';
+
+var errors = require('@backstage/errors');
+var helpers = require('../../helpers.cjs.js');
+
+class UrlPreparer {
+  logger;
+  reader;
+  /**
+   * Returns a directory preparer instance
+   * @param config - A URL preparer config containing the a logger and reader
+   */
+  static fromConfig(options) {
+    return new UrlPreparer(options.reader, options.logger);
+  }
+  constructor(reader, logger) {
+    this.logger = logger;
+    this.reader = reader;
+  }
+  /** {@inheritDoc PreparerBase.shouldCleanPreparedDirectory} */
+  shouldCleanPreparedDirectory() {
+    return true;
+  }
+  /** {@inheritDoc PreparerBase.prepare} */
+  async prepare(entity, options) {
+    try {
+      return await helpers.getDocFilesFromRepository(this.reader, entity, {
+        etag: options?.etag,
+        logger: this.logger
+      });
+    } catch (error) {
+      errors.assertError(error);
+      if (error.name === "NotModifiedError") {
+        this.logger.debug(`Cache is valid for etag ${options?.etag}`);
+      } else {
+        this.logger.debug(
+          `Unable to fetch files for building docs ${error.message}`
+        );
+      }
+      throw error;
+    }
+  }
+}
+
+exports.UrlPreparer = UrlPreparer;
+//# sourceMappingURL=url.cjs.js.map

package/dist/stages/prepare/url.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.cjs.js","sources":["../../../src/stages/prepare/url.ts"],"sourcesContent":["/*\n * Copyright 2020 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { assertError } from '@backstage/errors';\nimport { Entity } from '@backstage/catalog-model';\nimport { getDocFilesFromRepository } from '../../helpers';\nimport {\n  PreparerBase,\n  PreparerConfig,\n  PreparerOptions,\n  PreparerResponse,\n} from './types';\nimport { LoggerService, UrlReaderService } from '@backstage/backend-plugin-api';\n\n/**\n * Preparer used to retrieve documentation files from a remote repository\n * @public\n */\nexport class UrlPreparer implements PreparerBase {\n  private readonly logger: LoggerService;\n  private readonly reader: UrlReaderService;\n\n  /**\n   * Returns a directory preparer instance\n   * @param config - A URL preparer config containing the a logger and reader\n   */\n  static fromConfig(options: PreparerConfig): UrlPreparer {\n    return new UrlPreparer(options.reader, options.logger);\n  }\n\n  private constructor(reader: UrlReaderService, logger: LoggerService) {\n    this.logger = logger;\n    this.reader = reader;\n  }\n\n  /** {@inheritDoc PreparerBase.shouldCleanPreparedDirectory} */\n  shouldCleanPreparedDirectory() {\n    return true;\n  }\n\n  /** {@inheritDoc PreparerBase.prepare} */\n  async prepare(\n    entity: Entity,\n    options?: PreparerOptions,\n  ): Promise<PreparerResponse> {\n    try {\n      return await getDocFilesFromRepository(this.reader, entity, {\n        etag: options?.etag,\n        logger: this.logger,\n      });\n    } catch (error) {\n      assertError(error);\n      // NotModifiedError means that etag based cache is still valid.\n      if (error.name === 'NotModifiedError') {\n        this.logger.debug(`Cache is valid for etag ${options?.etag}`);\n      } else {\n        this.logger.debug(\n          `Unable to fetch files for building docs ${error.message}`,\n        );\n      }\n\n      throw error;\n    }\n  }\n}\n"],"names":["getDocFilesFromRepository","assertError"],"mappings":";;;;;AA+BO,MAAM,WAAoC,CAAA;AAAA,EAC9B,MAAA,CAAA;AAAA,EACA,MAAA,CAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMjB,OAAO,WAAW,OAAsC,EAAA;AACtD,IAAA,OAAO,IAAI,WAAA,CAAY,OAAQ,CAAA,MAAA,EAAQ,QAAQ,MAAM,CAAA,CAAA;AAAA,GACvD;AAAA,EAEQ,WAAA,CAAY,QAA0B,MAAuB,EAAA;AACnE,IAAA,IAAA,CAAK,MAAS,GAAA,MAAA,CAAA;AACd,IAAA,IAAA,CAAK,MAAS,GAAA,MAAA,CAAA;AAAA,GAChB;AAAA;AAAA,EAGA,4BAA+B,GAAA;AAC7B,IAAO,OAAA,IAAA,CAAA;AAAA,GACT;AAAA;AAAA,EAGA,MAAM,OACJ,CAAA,MAAA,EACA,OAC2B,EAAA;AAC3B,IAAI,IAAA;AACF,MAAA,OAAO,MAAMA,iCAAA,CAA0B,IAAK,CAAA,MAAA,EAAQ,MAAQ,EAAA;AAAA,QAC1D,MAAM,OAAS,EAAA,IAAA;AAAA,QACf,QAAQ,IAAK,CAAA,MAAA;AAAA,OACd,CAAA,CAAA;AAAA,aACM,KAAO,EAAA;AACd,MAAAC,kBAAA,CAAY,KAAK,CAAA,CAAA;AAEjB,MAAI,IAAA,KAAA,CAAM,SAAS,kBAAoB,EAAA;AACrC,QAAA,IAAA,CAAK,MAAO,CAAA,KAAA,CAAM,CAA2B,wBAAA,EAAA,OAAA,EAAS,IAAI,CAAE,CAAA,CAAA,CAAA;AAAA,OACvD,MAAA;AACL,QAAA,IAAA,CAAK,MAAO,CAAA,KAAA;AAAA,UACV,CAAA,wCAAA,EAA2C,MAAM,OAAO,CAAA,CAAA;AAAA,SAC1D,CAAA;AAAA,OACF;AAEA,MAAM,MAAA,KAAA,CAAA;AAAA,KACR;AAAA,GACF;AACF;;;;"}