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

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

@@ -0,0 +1,99 @@
+'use strict';
+
+var Docker = require('dockerode');
+var fs = require('fs-extra');
+var errors = require('@backstage/errors');
+var stream = require('stream');
+var util = require('util');
+
+function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e : { default: e }; }
+
+var Docker__default = /*#__PURE__*/_interopDefaultCompat(Docker);
+var fs__default = /*#__PURE__*/_interopDefaultCompat(fs);
+
+const pipeline = util.promisify(stream.pipeline);
+class DockerContainerRunner {
+  dockerClient;
+  constructor() {
+    this.dockerClient = new Docker__default.default();
+  }
+  async runContainer(options) {
+    const {
+      imageName,
+      command,
+      args,
+      logStream = new stream.PassThrough(),
+      mountDirs = {},
+      workingDir,
+      envVars = {},
+      pullImage = true,
+      defaultUser = false
+    } = options;
+    try {
+      await this.dockerClient.ping();
+    } catch (e) {
+      throw new errors.ForwardedError(
+        "This operation requires Docker. Docker does not appear to be available. Docker.ping() failed with",
+        e
+      );
+    }
+    if (pullImage) {
+      await new Promise((resolve, reject) => {
+        this.dockerClient.pull(imageName, {}, (err, stream) => {
+          if (err) {
+            reject(err);
+          } else if (!stream) {
+            reject(
+              new Error(
+                "Unexpeected error: no stream returned from Docker while pulling image"
+              )
+            );
+          } else {
+            pipeline(stream, logStream, { end: false }).then(resolve).catch(reject);
+          }
+        });
+      });
+    }
+    const userOptions = {};
+    if (!defaultUser && process.getuid && process.getgid) {
+      userOptions.User = `${process.getuid()}:${process.getgid()}`;
+    }
+    const Volumes = {};
+    for (const containerDir of Object.values(mountDirs)) {
+      Volumes[containerDir] = {};
+    }
+    const Binds = [];
+    for (const [hostDir, containerDir] of Object.entries(mountDirs)) {
+      const realHostDir = await fs__default.default.realpath(hostDir);
+      Binds.push(`${realHostDir}:${containerDir}`);
+    }
+    const Env = new Array();
+    for (const [key, value] of Object.entries(envVars)) {
+      Env.push(`${key}=${value}`);
+    }
+    const [{ Error: error, StatusCode: statusCode }] = await this.dockerClient.run(imageName, args, logStream, {
+      Volumes,
+      HostConfig: {
+        AutoRemove: true,
+        Binds
+      },
+      ...workingDir ? { WorkingDir: workingDir } : {},
+      Entrypoint: command,
+      Env,
+      ...userOptions
+    });
+    if (error) {
+      throw new Error(
+        `Docker failed to run with the following error message: ${error}`
+      );
+    }
+    if (statusCode !== 0) {
+      throw new Error(
+        `Docker container returned a non-zero exit code (${statusCode})`
+      );
+    }
+  }
+}
+
+exports.DockerContainerRunner = DockerContainerRunner;
+//# sourceMappingURL=DockerContainerRunner.cjs.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"DockerContainerRunner.cjs.js","sources":["../../../src/stages/generate/DockerContainerRunner.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 Docker from 'dockerode';\nimport fs from 'fs-extra';\nimport { ForwardedError } from '@backstage/errors';\nimport { PassThrough } from 'stream';\nimport { pipeline as pipelineStream } from 'stream';\nimport { promisify } from 'util';\nimport { TechDocsContainerRunner } from './types';\nimport { Writable } from 'stream';\n\nconst pipeline = promisify(pipelineStream);\n\nexport type UserOptions = {\n  User?: string;\n};\n\n/**\n * @internal\n */\nexport class DockerContainerRunner implements TechDocsContainerRunner {\n  private readonly dockerClient: Docker;\n\n  constructor() {\n    this.dockerClient = new Docker();\n  }\n\n  async runContainer(options: {\n    imageName: string;\n    command?: string | string[];\n    args: string[];\n    logStream?: Writable;\n    mountDirs?: Record<string, string>;\n    workingDir?: string;\n    envVars?: Record<string, string>;\n    pullImage?: boolean;\n    defaultUser?: boolean;\n  }) {\n    const {\n      imageName,\n      command,\n      args,\n      logStream = new PassThrough(),\n      mountDirs = {},\n      workingDir,\n      envVars = {},\n      pullImage = true,\n      defaultUser = false,\n    } = options;\n\n    // Show a better error message when Docker is unavailable.\n    try {\n      await this.dockerClient.ping();\n    } catch (e) {\n      throw new ForwardedError(\n        'This operation requires Docker. Docker does not appear to be available. Docker.ping() failed with',\n        e,\n      );\n    }\n\n    if (pullImage) {\n      await new Promise<void>((resolve, reject) => {\n        this.dockerClient.pull(imageName, {}, (err, stream) => {\n          if (err) {\n            reject(err);\n          } else if (!stream) {\n            reject(\n              new Error(\n                'Unexpeected error: no stream returned from Docker while pulling image',\n              ),\n            );\n          } else {\n            pipeline(stream, logStream, { end: false })\n              .then(resolve)\n              .catch(reject);\n          }\n        });\n      });\n    }\n\n    const userOptions: UserOptions = {};\n    if (!defaultUser && process.getuid && process.getgid) {\n      // Files that are created inside the Docker container will be owned by\n      // root on the host system on non Mac systems, because of reasons. Mainly the fact that\n      // volume sharing is done using NFS on Mac and actual mounts in Linux world.\n      // So we set the user in the container as the same user and group id as the host.\n      // On Windows we don't have process.getuid nor process.getgid\n      userOptions.User = `${process.getuid()}:${process.getgid()}`;\n    }\n\n    // Initialize volumes to mount based on mountDirs map\n    const Volumes: { [T: string]: object } = {};\n    for (const containerDir of Object.values(mountDirs)) {\n      Volumes[containerDir] = {};\n    }\n\n    // Create bind volumes\n    const Binds: string[] = [];\n    for (const [hostDir, containerDir] of Object.entries(mountDirs)) {\n      // Need to use realpath here as Docker mounting does not like\n      // symlinks for binding volumes\n      const realHostDir = await fs.realpath(hostDir);\n      Binds.push(`${realHostDir}:${containerDir}`);\n    }\n\n    // Create docker environment variables array\n    const Env = new Array<string>();\n    for (const [key, value] of Object.entries(envVars)) {\n      Env.push(`${key}=${value}`);\n    }\n\n    const [{ Error: error, StatusCode: statusCode }] =\n      await this.dockerClient.run(imageName, args, logStream, {\n        Volumes,\n        HostConfig: {\n          AutoRemove: true,\n          Binds,\n        },\n        ...(workingDir ? { WorkingDir: workingDir } : {}),\n        Entrypoint: command,\n        Env,\n        ...userOptions,\n      } as Docker.ContainerCreateOptions);\n\n    if (error) {\n      throw new Error(\n        `Docker failed to run with the following error message: ${error}`,\n      );\n    }\n\n    if (statusCode !== 0) {\n      throw new Error(\n        `Docker container returned a non-zero exit code (${statusCode})`,\n      );\n    }\n  }\n}\n"],"names":["promisify","pipelineStream","Docker","PassThrough","ForwardedError","fs"],"mappings":"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"}

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

@@ -0,0 +1,42 @@
+'use strict';
+
+var helpers = require('./helpers.cjs.js');
+var techdocs = require('./techdocs.cjs.js');
+
+class Generators {
+  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 = options.customGenerator ?? techdocs.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 = helpers.getGeneratorKey(entity);
+    const generator = this.generatorMap.get(generatorKey);
+    if (!generator) {
+      throw new Error(`No generator registered for entity: "${generatorKey}"`);
+    }
+    return generator;
+  }
+}
+
+exports.Generators = Generators;
+//# sourceMappingURL=generators.cjs.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"generators.cjs.js","sources":["../../../src/stages/generate/generators.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 { getGeneratorKey } from './helpers';\nimport { TechdocsGenerator } from './techdocs';\nimport {\n  GeneratorBase,\n  GeneratorBuilder,\n  SupportedGeneratorKey,\n} from './types';\nimport { LoggerService } from '@backstage/backend-plugin-api';\nimport { TechDocsContainerRunner } from './types';\n\n/**\n * Collection of docs generators\n * @public\n */\nexport class Generators implements GeneratorBuilder {\n  private generatorMap = new Map<SupportedGeneratorKey, GeneratorBase>();\n\n  /**\n   * Returns a generators instance containing a generator for TechDocs\n   * @param config - A Backstage configuration\n   * @param options - Options to configure the TechDocs generator\n   */\n  static async fromConfig(\n    config: Config,\n    options: {\n      logger: LoggerService;\n      containerRunner?: TechDocsContainerRunner;\n      customGenerator?: TechdocsGenerator;\n    },\n  ): Promise<GeneratorBuilder> {\n    const generators = new Generators();\n\n    const techdocsGenerator =\n      options.customGenerator ?? TechdocsGenerator.fromConfig(config, options);\n    generators.register('techdocs', techdocsGenerator);\n\n    return generators;\n  }\n\n  /**\n   * Register a generator in the generators collection\n   * @param generatorKey - Unique identifier for the generator\n   * @param generator - The generator instance to register\n   */\n  register(generatorKey: SupportedGeneratorKey, generator: GeneratorBase) {\n    this.generatorMap.set(generatorKey, generator);\n  }\n\n  /**\n   * Returns the generator for a given TechDocs entity\n   * @param entity - A TechDocs entity instance\n   */\n  get(entity: Entity): GeneratorBase {\n    const generatorKey = getGeneratorKey(entity);\n    const generator = this.generatorMap.get(generatorKey);\n\n    if (!generator) {\n      throw new Error(`No generator registered for entity: \"${generatorKey}\"`);\n    }\n\n    return generator;\n  }\n}\n"],"names":["TechdocsGenerator","getGeneratorKey"],"mappings":";;;;;AAgCO,MAAM,UAAuC,CAAA;AAAA,EAC1C,YAAA,uBAAmB,GAA0C,EAAA,CAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOrE,aAAa,UACX,CAAA,MAAA,EACA,OAK2B,EAAA;AAC3B,IAAM,MAAA,UAAA,GAAa,IAAI,UAAW,EAAA,CAAA;AAElC,IAAA,MAAM,oBACJ,OAAQ,CAAA,eAAA,IAAmBA,0BAAkB,CAAA,UAAA,CAAW,QAAQ,OAAO,CAAA,CAAA;AACzE,IAAW,UAAA,CAAA,QAAA,CAAS,YAAY,iBAAiB,CAAA,CAAA;AAEjD,IAAO,OAAA,UAAA,CAAA;AAAA,GACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,QAAA,CAAS,cAAqC,SAA0B,EAAA;AACtE,IAAK,IAAA,CAAA,YAAA,CAAa,GAAI,CAAA,YAAA,EAAc,SAAS,CAAA,CAAA;AAAA,GAC/C;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,IAAI,MAA+B,EAAA;AACjC,IAAM,MAAA,YAAA,GAAeC,wBAAgB,MAAM,CAAA,CAAA;AAC3C,IAAA,MAAM,SAAY,GAAA,IAAA,CAAK,YAAa,CAAA,GAAA,CAAI,YAAY,CAAA,CAAA;AAEpD,IAAA,IAAI,CAAC,SAAW,EAAA;AACd,MAAA,MAAM,IAAI,KAAA,CAAM,CAAwC,qCAAA,EAAA,YAAY,CAAG,CAAA,CAAA,CAAA,CAAA;AAAA,KACzE;AAEA,IAAO,OAAA,SAAA,CAAA;AAAA,GACT;AACF;;;;"}

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

@@ -0,0 +1,265 @@
+'use strict';
+
+var backendPluginApi = require('@backstage/backend-plugin-api');
+var errors = require('@backstage/errors');
+var child_process = require('child_process');
+var fs = require('fs-extra');
+var gitUrlParse = require('git-url-parse');
+var yaml = require('js-yaml');
+var path = require('path');
+var stream = require('stream');
+var helpers = require('../publish/helpers.cjs.js');
+
+function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e : { default: e }; }
+
+var fs__default = /*#__PURE__*/_interopDefaultCompat(fs);
+var gitUrlParse__default = /*#__PURE__*/_interopDefaultCompat(gitUrlParse);
+var yaml__default = /*#__PURE__*/_interopDefaultCompat(yaml);
+var path__default = /*#__PURE__*/_interopDefaultCompat(path);
+
+function getGeneratorKey(entity) {
+  if (!entity) {
+    throw new Error("No entity provided");
+  }
+  return "techdocs";
+}
+const runCommand = async ({
+  command,
+  args,
+  options,
+  logStream = new stream.PassThrough()
+}) => {
+  await new Promise((resolve, reject) => {
+    const process = child_process.spawn(command, args, options);
+    process.stdout.on("data", (stream) => {
+      logStream.write(stream);
+    });
+    process.stderr.on("data", (stream) => {
+      logStream.write(stream);
+    });
+    process.on("error", (error) => {
+      return reject(error);
+    });
+    process.on("close", (code) => {
+      if (code !== 0) {
+        return reject(`Command ${command} failed, exit code: ${code}`);
+      }
+      return resolve();
+    });
+  });
+};
+const getRepoUrlFromLocationAnnotation = (parsedLocationAnnotation, scmIntegrations, docsFolder = "docs") => {
+  const { type: locationType, target } = parsedLocationAnnotation;
+  if (locationType === "url") {
+    const integration = scmIntegrations.byUrl(target);
+    if (integration && ["github", "gitlab", "bitbucketServer", "harness"].includes(
+      integration.type
+    )) {
+      const { filepathtype } = gitUrlParse__default.default(target);
+      if (filepathtype === "") {
+        return { repo_url: target };
+      }
+      const sourceFolder = integration.resolveUrl({
+        url: `./${docsFolder}`,
+        base: target.endsWith("/") ? target : `${target}/`
+      });
+      return {
+        repo_url: target,
+        edit_uri: integration.resolveEditUrl(sourceFolder)
+      };
+    }
+  }
+  return {};
+};
+class UnknownTag {
+  constructor(data, type) {
+    this.data = data;
+    this.type = type;
+  }
+}
+const MKDOCS_SCHEMA = yaml.DEFAULT_SCHEMA.extend([
+  new yaml.Type("", {
+    kind: "scalar",
+    multi: true,
+    representName: (o) => o.type,
+    represent: (o) => o.data ?? "",
+    instanceOf: UnknownTag,
+    construct: (data, type) => new UnknownTag(data, type)
+  }),
+  new yaml.Type("tag:", {
+    kind: "mapping",
+    multi: true,
+    representName: (o) => o.type,
+    represent: (o) => o.data ?? "",
+    instanceOf: UnknownTag,
+    construct: (data, type) => new UnknownTag(data, type)
+  }),
+  new yaml.Type("", {
+    kind: "sequence",
+    multi: true,
+    representName: (o) => o.type,
+    represent: (o) => o.data ?? "",
+    instanceOf: UnknownTag,
+    construct: (data, type) => new UnknownTag(data, type)
+  })
+]);
+const generateMkdocsYml = async (inputDir, siteOptions) => {
+  try {
+    const mkdocsYmlPath = path__default.default.join(inputDir, "mkdocs.yml");
+    const defaultSiteName = siteOptions?.name ?? "Documentation Site";
+    const defaultMkdocsContent = {
+      site_name: defaultSiteName,
+      docs_dir: "docs",
+      plugins: ["techdocs-core"]
+    };
+    await fs__default.default.writeFile(
+      mkdocsYmlPath,
+      yaml__default.default.dump(defaultMkdocsContent, { schema: MKDOCS_SCHEMA })
+    );
+  } catch (error) {
+    throw new errors.ForwardedError("Could not generate mkdocs.yml file", error);
+  }
+};
+const getMkdocsYml = async (inputDir, options) => {
+  let mkdocsYmlPath;
+  let mkdocsYmlFileString;
+  try {
+    if (options?.mkdocsConfigFileName) {
+      mkdocsYmlPath = path__default.default.join(inputDir, options.mkdocsConfigFileName);
+      if (!await fs__default.default.pathExists(mkdocsYmlPath)) {
+        throw new Error(`The specified file ${mkdocsYmlPath} does not exist`);
+      }
+      mkdocsYmlFileString = await fs__default.default.readFile(mkdocsYmlPath, "utf8");
+      return {
+        path: mkdocsYmlPath,
+        content: mkdocsYmlFileString,
+        configIsTemporary: false
+      };
+    }
+    mkdocsYmlPath = path__default.default.join(inputDir, "mkdocs.yaml");
+    if (await fs__default.default.pathExists(mkdocsYmlPath)) {
+      mkdocsYmlFileString = await fs__default.default.readFile(mkdocsYmlPath, "utf8");
+      return {
+        path: mkdocsYmlPath,
+        content: mkdocsYmlFileString,
+        configIsTemporary: false
+      };
+    }
+    mkdocsYmlPath = path__default.default.join(inputDir, "mkdocs.yml");
+    if (await fs__default.default.pathExists(mkdocsYmlPath)) {
+      mkdocsYmlFileString = await fs__default.default.readFile(mkdocsYmlPath, "utf8");
+      return {
+        path: mkdocsYmlPath,
+        content: mkdocsYmlFileString,
+        configIsTemporary: false
+      };
+    }
+    await generateMkdocsYml(inputDir, options);
+    mkdocsYmlFileString = await fs__default.default.readFile(mkdocsYmlPath, "utf8");
+  } catch (error) {
+    throw new errors.ForwardedError(
+      "Could not read MkDocs YAML config file mkdocs.yml or mkdocs.yaml or default for validation",
+      error
+    );
+  }
+  return {
+    path: mkdocsYmlPath,
+    content: mkdocsYmlFileString,
+    configIsTemporary: true
+  };
+};
+const validateMkdocsYaml = async (inputDir, mkdocsYmlFileString) => {
+  const mkdocsYml = yaml__default.default.load(mkdocsYmlFileString, {
+    schema: MKDOCS_SCHEMA
+  });
+  if (mkdocsYml === null || typeof mkdocsYml !== "object") {
+    return void 0;
+  }
+  const parsedMkdocsYml = mkdocsYml;
+  if (parsedMkdocsYml.docs_dir && !backendPluginApi.isChildPath(inputDir, path.resolve(inputDir, parsedMkdocsYml.docs_dir))) {
+    throw new Error(
+      `docs_dir configuration value in mkdocs can't be an absolute directory or start with ../ for security reasons.
+       Use relative paths instead which are resolved relative to your mkdocs.yml file location.`
+    );
+  }
+  return parsedMkdocsYml.docs_dir;
+};
+const patchIndexPreBuild = async ({
+  inputDir,
+  logger,
+  docsDir = "docs"
+}) => {
+  const docsPath = path__default.default.join(inputDir, docsDir);
+  const indexMdPath = path__default.default.join(docsPath, "index.md");
+  if (await fs__default.default.pathExists(indexMdPath)) {
+    return;
+  }
+  logger.warn(`${path__default.default.join(docsDir, "index.md")} not found.`);
+  const fallbacks = [
+    path__default.default.join(docsPath, "README.md"),
+    path__default.default.join(docsPath, "readme.md"),
+    path__default.default.join(inputDir, "README.md"),
+    path__default.default.join(inputDir, "readme.md")
+  ];
+  await fs__default.default.ensureDir(docsPath);
+  for (const filePath of fallbacks) {
+    try {
+      await fs__default.default.copyFile(filePath, indexMdPath);
+      return;
+    } catch (error) {
+      logger.warn(`${path__default.default.relative(inputDir, filePath)} not found.`);
+    }
+  }
+  logger.warn(
+    `Could not find any techdocs' index file. Please make sure at least one of ${[
+      indexMdPath,
+      ...fallbacks
+    ].join(" ")} exists.`
+  );
+};
+const createOrUpdateMetadata = async (techdocsMetadataPath, logger) => {
+  const techdocsMetadataDir = techdocsMetadataPath.split(path__default.default.sep).slice(0, -1).join(path__default.default.sep);
+  try {
+    await fs__default.default.access(techdocsMetadataPath, fs__default.default.constants.F_OK);
+  } catch (err) {
+    await fs__default.default.writeJson(techdocsMetadataPath, JSON.parse("{}"));
+  }
+  let json;
+  try {
+    json = await fs__default.default.readJson(techdocsMetadataPath);
+  } catch (err) {
+    errors.assertError(err);
+    const message = `Invalid JSON at ${techdocsMetadataPath} with error ${err.message}`;
+    logger.error(message);
+    throw new Error(message);
+  }
+  json.build_timestamp = Date.now();
+  try {
+    json.files = (await helpers.getFileTreeRecursively(techdocsMetadataDir)).map(
+      (file) => file.replace(`${techdocsMetadataDir}${path__default.default.sep}`, "")
+    );
+  } catch (err) {
+    errors.assertError(err);
+    json.files = [];
+    logger.warn(`Unable to add files list to metadata: ${err.message}`);
+  }
+  await fs__default.default.writeJson(techdocsMetadataPath, json);
+  return;
+};
+const storeEtagMetadata = async (techdocsMetadataPath, etag) => {
+  const json = await fs__default.default.readJson(techdocsMetadataPath);
+  json.etag = etag;
+  await fs__default.default.writeJson(techdocsMetadataPath, json);
+};
+
+exports.MKDOCS_SCHEMA = MKDOCS_SCHEMA;
+exports.createOrUpdateMetadata = createOrUpdateMetadata;
+exports.generateMkdocsYml = generateMkdocsYml;
+exports.getGeneratorKey = getGeneratorKey;
+exports.getMkdocsYml = getMkdocsYml;
+exports.getRepoUrlFromLocationAnnotation = getRepoUrlFromLocationAnnotation;
+exports.patchIndexPreBuild = patchIndexPreBuild;
+exports.runCommand = runCommand;
+exports.storeEtagMetadata = storeEtagMetadata;
+exports.validateMkdocsYaml = validateMkdocsYaml;
+//# sourceMappingURL=helpers.cjs.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.cjs.js","sources":["../../../src/stages/generate/helpers.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 { isChildPath, LoggerService } from '@backstage/backend-plugin-api';\nimport { Entity } from '@backstage/catalog-model';\nimport { assertError, ForwardedError } from '@backstage/errors';\nimport { ScmIntegrationRegistry } from '@backstage/integration';\nimport { SpawnOptionsWithoutStdio, spawn } from 'child_process';\nimport fs from 'fs-extra';\nimport gitUrlParse from 'git-url-parse';\nimport yaml, { DEFAULT_SCHEMA, Type } from 'js-yaml';\nimport path, { resolve as resolvePath } from 'path';\nimport { PassThrough, Writable } from 'stream';\nimport { ParsedLocationAnnotation } from '../../helpers';\nimport { DefaultMkdocsContent, SupportedGeneratorKey } from './types';\nimport { getFileTreeRecursively } from '../publish/helpers';\n\n// TODO: Implement proper support for more generators.\nexport function getGeneratorKey(entity: Entity): SupportedGeneratorKey {\n  if (!entity) {\n    throw new Error('No entity provided');\n  }\n\n  return 'techdocs';\n}\n\nexport type RunCommandOptions = {\n  /** command to run */\n  command: string;\n  /** arguments to pass the command */\n  args: string[];\n  /** options to pass to spawn */\n  options: SpawnOptionsWithoutStdio;\n  /** stream to capture stdout and stderr output */\n  logStream?: Writable;\n};\n\n/**\n * Run a command in a sub-process, normally a shell command.\n */\nexport const runCommand = async ({\n  command,\n  args,\n  options,\n  logStream = new PassThrough(),\n}: RunCommandOptions) => {\n  await new Promise<void>((resolve, reject) => {\n    const process = spawn(command, args, options);\n\n    process.stdout.on('data', stream => {\n      logStream.write(stream);\n    });\n\n    process.stderr.on('data', stream => {\n      logStream.write(stream);\n    });\n\n    process.on('error', error => {\n      return reject(error);\n    });\n\n    process.on('close', code => {\n      if (code !== 0) {\n        return reject(`Command ${command} failed, exit code: ${code}`);\n      }\n      return resolve();\n    });\n  });\n};\n\n/**\n * Return the source url for MkDocs based on the backstage.io/techdocs-ref annotation.\n * Depending on the type of target, it can either return a repo_url, an edit_uri, both, or none.\n *\n * @param parsedLocationAnnotation - Object with location url and type\n * @param scmIntegrations - the scmIntegration to do url transformations\n * @param docsFolder - the configured docs folder in the mkdocs.yml (defaults to 'docs')\n * @returns the settings for the mkdocs.yml\n */\nexport const getRepoUrlFromLocationAnnotation = (\n  parsedLocationAnnotation: ParsedLocationAnnotation,\n  scmIntegrations: ScmIntegrationRegistry,\n  docsFolder: string = 'docs',\n): { repo_url?: string; edit_uri?: string } => {\n  const { type: locationType, target } = parsedLocationAnnotation;\n\n  if (locationType === 'url') {\n    const integration = scmIntegrations.byUrl(target);\n\n    // We only support it for github, gitlab, bitbucketServer and harness for now as the edit_uri\n    // is not properly supported for others yet.\n    if (\n      integration &&\n      ['github', 'gitlab', 'bitbucketServer', 'harness'].includes(\n        integration.type,\n      )\n    ) {\n      // handle the case where a user manually writes url:https://github.com/backstage/backstage i.e. without /blob/...\n      const { filepathtype } = gitUrlParse(target);\n      if (filepathtype === '') {\n        return { repo_url: target };\n      }\n\n      const sourceFolder = integration.resolveUrl({\n        url: `./${docsFolder}`,\n        base: target.endsWith('/') ? target : `${target}/`,\n      });\n      return {\n        repo_url: target,\n        edit_uri: integration.resolveEditUrl(sourceFolder),\n      };\n    }\n  }\n\n  return {};\n};\n\nclass UnknownTag {\n  constructor(public readonly data: any, public readonly type?: string) {}\n}\n\nexport const MKDOCS_SCHEMA = DEFAULT_SCHEMA.extend([\n  new Type('', {\n    kind: 'scalar',\n    multi: true,\n    representName: o => (o as UnknownTag).type,\n    represent: o => (o as UnknownTag).data ?? '',\n    instanceOf: UnknownTag,\n    construct: (data: string, type?: string) => new UnknownTag(data, type),\n  }),\n  new Type('tag:', {\n    kind: 'mapping',\n    multi: true,\n    representName: o => (o as UnknownTag).type,\n    represent: o => (o as UnknownTag).data ?? '',\n    instanceOf: UnknownTag,\n    construct: (data: string, type?: string) => new UnknownTag(data, type),\n  }),\n  new Type('', {\n    kind: 'sequence',\n    multi: true,\n    representName: o => (o as UnknownTag).type,\n    represent: o => (o as UnknownTag).data ?? '',\n    instanceOf: UnknownTag,\n    construct: (data: string, type?: string) => new UnknownTag(data, type),\n  }),\n]);\n\n/**\n * Generates a mkdocs.yml configuration file\n *\n * @param inputDir - base dir to where the mkdocs.yml file will be created\n * @param siteOptions - options for the site: `name` property will be used in mkdocs.yml for the\n * required `site_name` property, default value is \"Documentation Site\"\n */\nexport const generateMkdocsYml = async (\n  inputDir: string,\n  siteOptions?: { name?: string },\n) => {\n  try {\n    // TODO(awanlin): Use a provided default mkdocs.yml\n    // from config or some specified location. If this is\n    // not provided then fall back to generating bare\n    // minimum mkdocs.yml file\n\n    const mkdocsYmlPath = path.join(inputDir, 'mkdocs.yml');\n    const defaultSiteName = siteOptions?.name ?? 'Documentation Site';\n    const defaultMkdocsContent: DefaultMkdocsContent = {\n      site_name: defaultSiteName,\n      docs_dir: 'docs',\n      plugins: ['techdocs-core'],\n    };\n\n    await fs.writeFile(\n      mkdocsYmlPath,\n      yaml.dump(defaultMkdocsContent, { schema: MKDOCS_SCHEMA }),\n    );\n  } catch (error) {\n    throw new ForwardedError('Could not generate mkdocs.yml file', error);\n  }\n};\n\n/**\n * Finds and loads the contents of an mkdocs.yml, mkdocs.yaml file, a file\n * with a specified name or an ad-hoc created file with minimal config.\n * @public\n *\n * @param inputDir - base dir to be searched for either an mkdocs.yml or mkdocs.yaml file.\n * @param options - name: default mkdocs site_name to be used with a ad hoc file default value is \"Documentation Site\"\n *                  mkdocsConfigFileName (optional): a non-default file name to be used as the config\n */\nexport const getMkdocsYml = async (\n  inputDir: string,\n  options?: { name?: string; mkdocsConfigFileName?: string },\n): Promise<{ path: string; content: string; configIsTemporary: boolean }> => {\n  let mkdocsYmlPath: string;\n  let mkdocsYmlFileString: string;\n  try {\n    if (options?.mkdocsConfigFileName) {\n      mkdocsYmlPath = path.join(inputDir, options.mkdocsConfigFileName);\n      if (!(await fs.pathExists(mkdocsYmlPath))) {\n        throw new Error(`The specified file ${mkdocsYmlPath} does not exist`);\n      }\n\n      mkdocsYmlFileString = await fs.readFile(mkdocsYmlPath, 'utf8');\n      return {\n        path: mkdocsYmlPath,\n        content: mkdocsYmlFileString,\n        configIsTemporary: false,\n      };\n    }\n\n    mkdocsYmlPath = path.join(inputDir, 'mkdocs.yaml');\n    if (await fs.pathExists(mkdocsYmlPath)) {\n      mkdocsYmlFileString = await fs.readFile(mkdocsYmlPath, 'utf8');\n      return {\n        path: mkdocsYmlPath,\n        content: mkdocsYmlFileString,\n        configIsTemporary: false,\n      };\n    }\n\n    mkdocsYmlPath = path.join(inputDir, 'mkdocs.yml');\n    if (await fs.pathExists(mkdocsYmlPath)) {\n      mkdocsYmlFileString = await fs.readFile(mkdocsYmlPath, 'utf8');\n      return {\n        path: mkdocsYmlPath,\n        content: mkdocsYmlFileString,\n        configIsTemporary: false,\n      };\n    }\n\n    // No mkdocs file, generate it\n    await generateMkdocsYml(inputDir, options);\n    mkdocsYmlFileString = await fs.readFile(mkdocsYmlPath, 'utf8');\n  } catch (error) {\n    throw new ForwardedError(\n      'Could not read MkDocs YAML config file mkdocs.yml or mkdocs.yaml or default for validation',\n      error,\n    );\n  }\n\n  return {\n    path: mkdocsYmlPath,\n    content: mkdocsYmlFileString,\n    configIsTemporary: true,\n  };\n};\n\n/**\n * Validating mkdocs config file for incorrect/insecure values\n * Throws on invalid configs\n *\n * @param inputDir - base dir to be used as a docs_dir path validity check\n * @param mkdocsYmlFileString - The string contents of the loaded\n *   mkdocs.yml or equivalent of a docs site\n * @returns the parsed docs_dir or undefined\n */\nexport const validateMkdocsYaml = async (\n  inputDir: string,\n  mkdocsYmlFileString: string,\n): Promise<string | undefined> => {\n  const mkdocsYml = yaml.load(mkdocsYmlFileString, {\n    schema: MKDOCS_SCHEMA,\n  });\n\n  if (mkdocsYml === null || typeof mkdocsYml !== 'object') {\n    return undefined;\n  }\n\n  const parsedMkdocsYml: Record<string, any> = mkdocsYml;\n  if (\n    parsedMkdocsYml.docs_dir &&\n    !isChildPath(inputDir, resolvePath(inputDir, parsedMkdocsYml.docs_dir))\n  ) {\n    throw new Error(\n      `docs_dir configuration value in mkdocs can't be an absolute directory or start with ../ for security reasons.\n       Use relative paths instead which are resolved relative to your mkdocs.yml file location.`,\n    );\n  }\n  return parsedMkdocsYml.docs_dir;\n};\n\n/**\n * Update docs/index.md file before TechDocs generator uses it to generate docs site,\n * falling back to docs/README.md or README.md in case a default docs/index.md\n * is not provided.\n */\nexport const patchIndexPreBuild = async ({\n  inputDir,\n  logger,\n  docsDir = 'docs',\n}: {\n  inputDir: string;\n  logger: LoggerService;\n  docsDir?: string;\n}) => {\n  const docsPath = path.join(inputDir, docsDir);\n  const indexMdPath = path.join(docsPath, 'index.md');\n\n  if (await fs.pathExists(indexMdPath)) {\n    return;\n  }\n  logger.warn(`${path.join(docsDir, 'index.md')} not found.`);\n  const fallbacks = [\n    path.join(docsPath, 'README.md'),\n    path.join(docsPath, 'readme.md'),\n    path.join(inputDir, 'README.md'),\n    path.join(inputDir, 'readme.md'),\n  ];\n\n  await fs.ensureDir(docsPath);\n  for (const filePath of fallbacks) {\n    try {\n      await fs.copyFile(filePath, indexMdPath);\n      return;\n    } catch (error) {\n      logger.warn(`${path.relative(inputDir, filePath)} not found.`);\n    }\n  }\n\n  logger.warn(\n    `Could not find any techdocs' index file. Please make sure at least one of ${[\n      indexMdPath,\n      ...fallbacks,\n    ].join(' ')} exists.`,\n  );\n};\n\n/**\n * Create or update the techdocs_metadata.json. Values initialized/updated are:\n * - The build_timestamp (now)\n * - The list of files generated\n *\n * @param techdocsMetadataPath - File path to techdocs_metadata.json\n */\nexport const createOrUpdateMetadata = async (\n  techdocsMetadataPath: string,\n  logger: LoggerService,\n): Promise<void> => {\n  const techdocsMetadataDir = techdocsMetadataPath\n    .split(path.sep)\n    .slice(0, -1)\n    .join(path.sep);\n  // check if file exists, create if it does not.\n  try {\n    await fs.access(techdocsMetadataPath, fs.constants.F_OK);\n  } catch (err) {\n    // Bootstrap file with empty JSON\n    await fs.writeJson(techdocsMetadataPath, JSON.parse('{}'));\n  }\n  // check if valid Json\n  let json;\n  try {\n    json = await fs.readJson(techdocsMetadataPath);\n  } catch (err) {\n    assertError(err);\n    const message = `Invalid JSON at ${techdocsMetadataPath} with error ${err.message}`;\n    logger.error(message);\n    throw new Error(message);\n  }\n\n  json.build_timestamp = Date.now();\n\n  // Get and write generated files to the metadata JSON. Each file string is in\n  // a form appropriate for invalidating the associated object from cache.\n  try {\n    json.files = (await getFileTreeRecursively(techdocsMetadataDir)).map(file =>\n      file.replace(`${techdocsMetadataDir}${path.sep}`, ''),\n    );\n  } catch (err) {\n    assertError(err);\n    json.files = [];\n    logger.warn(`Unable to add files list to metadata: ${err.message}`);\n  }\n\n  await fs.writeJson(techdocsMetadataPath, json);\n  return;\n};\n\n/**\n * Update the techdocs_metadata.json to add etag of the prepared tree (e.g. commit SHA or actual Etag of the resource).\n * This is helpful to check if a TechDocs site in storage has gone outdated, without maintaining an in-memory build info\n * per Backstage instance.\n *\n * @param techdocsMetadataPath - File path to techdocs_metadata.json\n * @param etag - The ETag to use\n */\nexport const storeEtagMetadata = async (\n  techdocsMetadataPath: string,\n  etag: string,\n): Promise<void> => {\n  const json = await fs.readJson(techdocsMetadataPath);\n  json.etag = etag;\n  await fs.writeJson(techdocsMetadataPath, json);\n};\n"],"names":["PassThrough","spawn","gitUrlParse","DEFAULT_SCHEMA","Type","path","fs","yaml","ForwardedError","isChildPath","resolvePath","assertError","getFileTreeRecursively"],"mappings":"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"}

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

@@ -0,0 +1,15 @@
+'use strict';
+
+require('path');
+require('@backstage/integration');
+var helpers = require('./helpers.cjs.js');
+require('fs-extra');
+require('js-yaml');
+require('@backstage/errors');
+require('./DockerContainerRunner.cjs.js');
+
+const getMkDocsYml = helpers.getMkdocsYml;
+
+exports.getMkdocsYml = helpers.getMkdocsYml;
+exports.getMkDocsYml = getMkDocsYml;
+//# sourceMappingURL=index.cjs.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs.js","sources":["../../../src/stages/generate/index.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 */\nexport { TechdocsGenerator } from './techdocs';\nexport { Generators } from './generators';\nexport { getMkdocsYml } from './helpers';\nexport type {\n  GeneratorBase,\n  GeneratorOptions,\n  GeneratorBuilder,\n  GeneratorRunOptions,\n  SupportedGeneratorKey,\n  TechDocsContainerRunner,\n} from './types';\nimport { getMkdocsYml } from './helpers';\n/**\n * @public\n * @deprecated\n * Deprecated in favor of getMkdocsYml (lowercase 'd')\n */\nexport const getMkDocsYml = getMkdocsYml;\n"],"names":["getMkdocsYml"],"mappings":";;;;;;;;;;AAgCO,MAAM,YAAeA,GAAAA;;;;;"}

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

@@ -0,0 +1,96 @@
+'use strict';
+
+var fs = require('fs-extra');
+var yaml = require('js-yaml');
+var helpers = require('./helpers.cjs.js');
+var errors = require('@backstage/errors');
+
+function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e : { default: e }; }
+
+var fs__default = /*#__PURE__*/_interopDefaultCompat(fs);
+var yaml__default = /*#__PURE__*/_interopDefaultCompat(yaml);
+
+const patchMkdocsFile = async (mkdocsYmlPath, logger, updateAction) => {
+  let didEdit = false;
+  let mkdocsYmlFileString;
+  try {
+    mkdocsYmlFileString = await fs__default.default.readFile(mkdocsYmlPath, "utf8");
+  } catch (error) {
+    errors.assertError(error);
+    logger.warn(
+      `Could not read MkDocs YAML config file ${mkdocsYmlPath} before running the generator: ${error.message}`
+    );
+    return;
+  }
+  let mkdocsYml;
+  try {
+    mkdocsYml = yaml__default.default.load(mkdocsYmlFileString, { schema: helpers.MKDOCS_SCHEMA });
+    if (typeof mkdocsYml === "string" || typeof mkdocsYml === "undefined") {
+      throw new Error("Bad YAML format.");
+    }
+  } catch (error) {
+    errors.assertError(error);
+    logger.warn(
+      `Error in parsing YAML at ${mkdocsYmlPath} before running the generator. ${error.message}`
+    );
+    return;
+  }
+  didEdit = updateAction(mkdocsYml);
+  try {
+    if (didEdit) {
+      await fs__default.default.writeFile(
+        mkdocsYmlPath,
+        yaml__default.default.dump(mkdocsYml, { schema: helpers.MKDOCS_SCHEMA }),
+        "utf8"
+      );
+    }
+  } catch (error) {
+    errors.assertError(error);
+    logger.warn(
+      `Could not write to ${mkdocsYmlPath} after updating it before running the generator. ${error.message}`
+    );
+    return;
+  }
+};
+const patchMkdocsYmlPreBuild = async (mkdocsYmlPath, logger, parsedLocationAnnotation, scmIntegrations) => {
+  await patchMkdocsFile(mkdocsYmlPath, logger, (mkdocsYml) => {
+    if (!("repo_url" in mkdocsYml) || !("edit_uri" in mkdocsYml)) {
+      const result = helpers.getRepoUrlFromLocationAnnotation(
+        parsedLocationAnnotation,
+        scmIntegrations,
+        mkdocsYml.docs_dir
+      );
+      if (result.repo_url || result.edit_uri) {
+        mkdocsYml.repo_url = mkdocsYml.repo_url || result.repo_url;
+        mkdocsYml.edit_uri = mkdocsYml.edit_uri || result.edit_uri;
+        logger.info(
+          `Set ${JSON.stringify(
+            result
+          )}. You can disable this feature by manually setting 'repo_url' or 'edit_uri' according to the MkDocs documentation at https://www.mkdocs.org/user-guide/configuration/#repo_url`
+        );
+        return true;
+      }
+    }
+    return false;
+  });
+};
+const patchMkdocsYmlWithPlugins = async (mkdocsYmlPath, logger, defaultPlugins = ["techdocs-core"]) => {
+  await patchMkdocsFile(mkdocsYmlPath, logger, (mkdocsYml) => {
+    if (!("plugins" in mkdocsYml)) {
+      mkdocsYml.plugins = defaultPlugins;
+      return true;
+    }
+    let changesMade = false;
+    defaultPlugins.forEach((dp) => {
+      if (!(mkdocsYml.plugins.includes(dp) || mkdocsYml.plugins.some((p) => p.hasOwnProperty(dp)))) {
+        mkdocsYml.plugins = [.../* @__PURE__ */ new Set([...mkdocsYml.plugins, dp])];
+        changesMade = true;
+      }
+    });
+    return changesMade;
+  });
+};
+
+exports.patchMkdocsYmlPreBuild = patchMkdocsYmlPreBuild;
+exports.patchMkdocsYmlWithPlugins = patchMkdocsYmlWithPlugins;
+//# sourceMappingURL=mkdocsPatchers.cjs.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mkdocsPatchers.cjs.js","sources":["../../../src/stages/generate/mkdocsPatchers.ts"],"sourcesContent":["/*\n * Copyright 2022 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 fs from 'fs-extra';\nimport yaml from 'js-yaml';\nimport { ParsedLocationAnnotation } from '../../helpers';\nimport { getRepoUrlFromLocationAnnotation, MKDOCS_SCHEMA } from './helpers';\nimport { assertError } from '@backstage/errors';\nimport { ScmIntegrationRegistry } from '@backstage/integration';\nimport { LoggerService } from '@backstage/backend-plugin-api';\n\ntype MkDocsObject = {\n  plugins?: string[];\n  docs_dir: string;\n  repo_url?: string;\n  edit_uri?: string;\n};\n\nconst patchMkdocsFile = async (\n  mkdocsYmlPath: string,\n  logger: LoggerService,\n  updateAction: (mkdocsYml: MkDocsObject) => boolean,\n) => {\n  // We only want to override the mkdocs.yml if it has actually changed. This is relevant if\n  // used with a 'dir' location on the file system as this would permanently update the file.\n  let didEdit = false;\n\n  let mkdocsYmlFileString;\n  try {\n    mkdocsYmlFileString = await fs.readFile(mkdocsYmlPath, 'utf8');\n  } catch (error) {\n    assertError(error);\n    logger.warn(\n      `Could not read MkDocs YAML config file ${mkdocsYmlPath} before running the generator: ${error.message}`,\n    );\n    return;\n  }\n\n  let mkdocsYml: any;\n  try {\n    mkdocsYml = yaml.load(mkdocsYmlFileString, { schema: MKDOCS_SCHEMA });\n\n    // mkdocsYml should be an object type after successful parsing.\n    // But based on its type definition, it can also be a string or undefined, which we don't want.\n    if (typeof mkdocsYml === 'string' || typeof mkdocsYml === 'undefined') {\n      throw new Error('Bad YAML format.');\n    }\n  } catch (error) {\n    assertError(error);\n    logger.warn(\n      `Error in parsing YAML at ${mkdocsYmlPath} before running the generator. ${error.message}`,\n    );\n    return;\n  }\n\n  didEdit = updateAction(mkdocsYml);\n\n  try {\n    if (didEdit) {\n      await fs.writeFile(\n        mkdocsYmlPath,\n        yaml.dump(mkdocsYml, { schema: MKDOCS_SCHEMA }),\n        'utf8',\n      );\n    }\n  } catch (error) {\n    assertError(error);\n    logger.warn(\n      `Could not write to ${mkdocsYmlPath} after updating it before running the generator. ${error.message}`,\n    );\n    return;\n  }\n};\n\n/**\n * Update the mkdocs.yml file before TechDocs generator uses it to generate docs site.\n *\n * List of tasks:\n * - Add repo_url or edit_uri if it does not exists\n * If mkdocs.yml has a repo_url, the generated docs site gets an Edit button on the pages by default.\n * If repo_url is missing in mkdocs.yml, we will use techdocs annotation of the entity to possibly get\n * the repository URL.\n *\n * This function will not throw an error since this is not critical to the whole TechDocs pipeline.\n * Instead it will log warnings if there are any errors in reading, parsing or writing YAML.\n *\n * @param mkdocsYmlPath - Absolute path to mkdocs.yml or equivalent of a docs site\n * @param logger - A logger instance\n * @param parsedLocationAnnotation - Object with location url and type\n * @param scmIntegrations - the scmIntegration to do url transformations\n */\nexport const patchMkdocsYmlPreBuild = async (\n  mkdocsYmlPath: string,\n  logger: LoggerService,\n  parsedLocationAnnotation: ParsedLocationAnnotation,\n  scmIntegrations: ScmIntegrationRegistry,\n) => {\n  await patchMkdocsFile(mkdocsYmlPath, logger, mkdocsYml => {\n    if (!('repo_url' in mkdocsYml) || !('edit_uri' in mkdocsYml)) {\n      // Add edit_uri and/or repo_url to mkdocs.yml if it is missing.\n      // This will enable the Page edit button generated by MkDocs.\n      // If the either has been set, keep the original value\n      const result = getRepoUrlFromLocationAnnotation(\n        parsedLocationAnnotation,\n        scmIntegrations,\n        mkdocsYml.docs_dir,\n      );\n\n      if (result.repo_url || result.edit_uri) {\n        mkdocsYml.repo_url = mkdocsYml.repo_url || result.repo_url;\n        mkdocsYml.edit_uri = mkdocsYml.edit_uri || result.edit_uri;\n\n        logger.info(\n          `Set ${JSON.stringify(\n            result,\n          )}. You can disable this feature by manually setting 'repo_url' or 'edit_uri' according to the MkDocs documentation at https://www.mkdocs.org/user-guide/configuration/#repo_url`,\n        );\n        return true;\n      }\n    }\n    return false;\n  });\n};\n\n/**\n * Update the mkdocs.yml file before TechDocs generator uses it to generate docs site.\n *\n * List of tasks:\n * - Add all provided default plugins\n *\n * This function will not throw an error since this is not critical to the whole TechDocs pipeline.\n * Instead it will log warnings if there are any errors in reading, parsing or writing YAML.\n *\n * @param mkdocsYmlPath - Absolute path to mkdocs.yml or equivalent of a docs site\n * @param logger - A logger instance\n * @param defaultPlugins - List of default mkdocs plugins\n */\nexport const patchMkdocsYmlWithPlugins = async (\n  mkdocsYmlPath: string,\n  logger: LoggerService,\n  defaultPlugins: string[] = ['techdocs-core'],\n) => {\n  await patchMkdocsFile(mkdocsYmlPath, logger, mkdocsYml => {\n    // Modify mkdocs.yaml to contain the required default plugins.\n    // If no plugins are defined we can just return the defaults.\n    if (!('plugins' in mkdocsYml)) {\n      mkdocsYml.plugins = defaultPlugins;\n      return true;\n    }\n\n    // Otherwise, check each default plugin and include it if necessary.\n    let changesMade = false;\n\n    defaultPlugins.forEach(dp => {\n      // if the plugin isn't there as a string, and isn't there as an object (which may itself contain extra config)\n      // then we need to add it\n      if (\n        !(\n          mkdocsYml.plugins!.includes(dp) ||\n          mkdocsYml.plugins!.some(p => p.hasOwnProperty(dp))\n        )\n      ) {\n        mkdocsYml.plugins = [...new Set([...mkdocsYml.plugins!, dp])];\n        changesMade = true;\n      }\n    });\n\n    return changesMade;\n  });\n};\n"],"names":["fs","assertError","yaml","MKDOCS_SCHEMA","getRepoUrlFromLocationAnnotation"],"mappings":";;;;;;;;;;;;AA8BA,MAAM,eAAkB,GAAA,OACtB,aACA,EAAA,MAAA,EACA,YACG,KAAA;AAGH,EAAA,IAAI,OAAU,GAAA,KAAA,CAAA;AAEd,EAAI,IAAA,mBAAA,CAAA;AACJ,EAAI,IAAA;AACF,IAAA,mBAAA,GAAsB,MAAMA,mBAAA,CAAG,QAAS,CAAA,aAAA,EAAe,MAAM,CAAA,CAAA;AAAA,WACtD,KAAO,EAAA;AACd,IAAAC,kBAAA,CAAY,KAAK,CAAA,CAAA;AACjB,IAAO,MAAA,CAAA,IAAA;AAAA,MACL,CAA0C,uCAAA,EAAA,aAAa,CAAkC,+BAAA,EAAA,KAAA,CAAM,OAAO,CAAA,CAAA;AAAA,KACxG,CAAA;AACA,IAAA,OAAA;AAAA,GACF;AAEA,EAAI,IAAA,SAAA,CAAA;AACJ,EAAI,IAAA;AACF,IAAA,SAAA,GAAYC,sBAAK,IAAK,CAAA,mBAAA,EAAqB,EAAE,MAAA,EAAQC,uBAAe,CAAA,CAAA;AAIpE,IAAA,IAAI,OAAO,SAAA,KAAc,QAAY,IAAA,OAAO,cAAc,WAAa,EAAA;AACrE,MAAM,MAAA,IAAI,MAAM,kBAAkB,CAAA,CAAA;AAAA,KACpC;AAAA,WACO,KAAO,EAAA;AACd,IAAAF,kBAAA,CAAY,KAAK,CAAA,CAAA;AACjB,IAAO,MAAA,CAAA,IAAA;AAAA,MACL,CAA4B,yBAAA,EAAA,aAAa,CAAkC,+BAAA,EAAA,KAAA,CAAM,OAAO,CAAA,CAAA;AAAA,KAC1F,CAAA;AACA,IAAA,OAAA;AAAA,GACF;AAEA,EAAA,OAAA,GAAU,aAAa,SAAS,CAAA,CAAA;AAEhC,EAAI,IAAA;AACF,IAAA,IAAI,OAAS,EAAA;AACX,MAAA,MAAMD,mBAAG,CAAA,SAAA;AAAA,QACP,aAAA;AAAA,QACAE,sBAAK,IAAK,CAAA,SAAA,EAAW,EAAE,MAAA,EAAQC,uBAAe,CAAA;AAAA,QAC9C,MAAA;AAAA,OACF,CAAA;AAAA,KACF;AAAA,WACO,KAAO,EAAA;AACd,IAAAF,kBAAA,CAAY,KAAK,CAAA,CAAA;AACjB,IAAO,MAAA,CAAA,IAAA;AAAA,MACL,CAAsB,mBAAA,EAAA,aAAa,CAAoD,iDAAA,EAAA,KAAA,CAAM,OAAO,CAAA,CAAA;AAAA,KACtG,CAAA;AACA,IAAA,OAAA;AAAA,GACF;AACF,CAAA,CAAA;AAmBO,MAAM,sBAAyB,GAAA,OACpC,aACA,EAAA,MAAA,EACA,0BACA,eACG,KAAA;AACH,EAAM,MAAA,eAAA,CAAgB,aAAe,EAAA,MAAA,EAAQ,CAAa,SAAA,KAAA;AACxD,IAAA,IAAI,EAAE,UAAA,IAAc,SAAc,CAAA,IAAA,EAAE,cAAc,SAAY,CAAA,EAAA;AAI5D,MAAA,MAAM,MAAS,GAAAG,wCAAA;AAAA,QACb,wBAAA;AAAA,QACA,eAAA;AAAA,QACA,SAAU,CAAA,QAAA;AAAA,OACZ,CAAA;AAEA,MAAI,IAAA,MAAA,CAAO,QAAY,IAAA,MAAA,CAAO,QAAU,EAAA;AACtC,QAAU,SAAA,CAAA,QAAA,GAAW,SAAU,CAAA,QAAA,IAAY,MAAO,CAAA,QAAA,CAAA;AAClD,QAAU,SAAA,CAAA,QAAA,GAAW,SAAU,CAAA,QAAA,IAAY,MAAO,CAAA,QAAA,CAAA;AAElD,QAAO,MAAA,CAAA,IAAA;AAAA,UACL,OAAO,IAAK,CAAA,SAAA;AAAA,YACV,MAAA;AAAA,WACD,CAAA,8KAAA,CAAA;AAAA,SACH,CAAA;AACA,QAAO,OAAA,IAAA,CAAA;AAAA,OACT;AAAA,KACF;AACA,IAAO,OAAA,KAAA,CAAA;AAAA,GACR,CAAA,CAAA;AACH,EAAA;AAeO,MAAM,4BAA4B,OACvC,aAAA,EACA,QACA,cAA2B,GAAA,CAAC,eAAe,CACxC,KAAA;AACH,EAAM,MAAA,eAAA,CAAgB,aAAe,EAAA,MAAA,EAAQ,CAAa,SAAA,KAAA;AAGxD,IAAI,IAAA,EAAE,aAAa,SAAY,CAAA,EAAA;AAC7B,MAAA,SAAA,CAAU,OAAU,GAAA,cAAA,CAAA;AACpB,MAAO,OAAA,IAAA,CAAA;AAAA,KACT;AAGA,IAAA,IAAI,WAAc,GAAA,KAAA,CAAA;AAElB,IAAA,cAAA,CAAe,QAAQ,CAAM,EAAA,KAAA;AAG3B,MAAA,IACE,EACE,SAAA,CAAU,OAAS,CAAA,QAAA,CAAS,EAAE,CAC9B,IAAA,SAAA,CAAU,OAAS,CAAA,IAAA,CAAK,CAAK,CAAA,KAAA,CAAA,CAAE,cAAe,CAAA,EAAE,CAAC,CAEnD,CAAA,EAAA;AACA,QAAU,SAAA,CAAA,OAAA,GAAU,CAAC,mBAAO,IAAA,GAAA,CAAI,CAAC,GAAG,SAAU,CAAA,OAAA,EAAU,EAAE,CAAC,CAAC,CAAA,CAAA;AAC5D,QAAc,WAAA,GAAA,IAAA,CAAA;AAAA,OAChB;AAAA,KACD,CAAA,CAAA;AAED,IAAO,OAAA,WAAA,CAAA;AAAA,GACR,CAAA,CAAA;AACH;;;;;"}