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

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @backstage/plugin-techdocs-node
 
+## 1.14.5-next.2
+
+### Patch Changes
+
+- 482ceed: Migrated from `assertError` to `toError` for error handling.
+- Updated dependencies
+  - @backstage/errors@1.3.0-next.0
+  - @backstage/integration@2.0.1-next.0
+  - @backstage/backend-plugin-api@1.9.0-next.2
+  - @backstage/catalog-model@1.7.8-next.0
+  - @backstage/config@1.3.7-next.0
+  - @backstage/integration-aws-node@0.1.21-next.0
+  - @backstage/plugin-search-common@1.2.23-next.0
+
+## 1.14.5-next.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/backend-plugin-api@1.9.0-next.1
+
 ## 1.14.5-next.0
 
 ### Patch Changes

package/dist/index.cjs.js

@@ -5,11 +5,11 @@ var dir = require('./stages/prepare/dir.cjs.js');
 var url = require('./stages/prepare/url.cjs.js');
 var preparers = require('./stages/prepare/preparers.cjs.js');
 var publish = require('./stages/publish/publish.cjs.js');
-var helpers$1 = require('./helpers.cjs.js');
+var helpers = require('./helpers.cjs.js');
 var extensions = require('./extensions.cjs.js');
-var techdocs = require('./stages/generate/techdocs.cjs.js');
 var generators = require('./stages/generate/generators.cjs.js');
-var helpers = require('./stages/generate/helpers.cjs.js');
+var techdocs = require('./stages/generate/techdocs.cjs.js');
+var helpers$1 = require('./stages/generate/helpers.cjs.js');
 
 
 
@@ -18,15 +18,15 @@ exports.DirectoryPreparer = dir.DirectoryPreparer;
 exports.UrlPreparer = url.UrlPreparer;
 exports.Preparers = preparers.Preparers;
 exports.Publisher = publish.Publisher;
-exports.getDocFilesFromRepository = helpers$1.getDocFilesFromRepository;
-exports.getLocationForEntity = helpers$1.getLocationForEntity;
-exports.parseReferenceAnnotation = helpers$1.parseReferenceAnnotation;
-exports.transformDirLocation = helpers$1.transformDirLocation;
+exports.getDocFilesFromRepository = helpers.getDocFilesFromRepository;
+exports.getLocationForEntity = helpers.getLocationForEntity;
+exports.parseReferenceAnnotation = helpers.parseReferenceAnnotation;
+exports.transformDirLocation = helpers.transformDirLocation;
 exports.techdocsBuildsExtensionPoint = extensions.techdocsBuildsExtensionPoint;
 exports.techdocsGeneratorExtensionPoint = extensions.techdocsGeneratorExtensionPoint;
 exports.techdocsPreparerExtensionPoint = extensions.techdocsPreparerExtensionPoint;
 exports.techdocsPublisherExtensionPoint = extensions.techdocsPublisherExtensionPoint;
-exports.TechdocsGenerator = techdocs.TechdocsGenerator;
 exports.Generators = generators.Generators;
-exports.getMkdocsYml = helpers.getMkdocsYml;
+exports.TechdocsGenerator = techdocs.TechdocsGenerator;
+exports.getMkdocsYml = helpers$1.getMkdocsYml;
 //# sourceMappingURL=index.cjs.js.map

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

@@ -278,8 +278,7 @@ const createOrUpdateMetadata = async (techdocsMetadataPath, logger) => {
   try {
     json = await fs__default.default.readJson(techdocsMetadataPath);
   } catch (err) {
-    errors.assertError(err);
-    const message = `Invalid JSON at ${techdocsMetadataPath} with error ${err.message}`;
+    const message = `Invalid JSON at ${techdocsMetadataPath} with error ${errors.toError(err).message}`;
     logger.error(message);
     throw new Error(message);
   }
@@ -289,9 +288,10 @@ const createOrUpdateMetadata = async (techdocsMetadataPath, logger) => {
       (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}`);
+    logger.warn(
+      `Unable to add files list to metadata: ${errors.toError(err).message}`
+    );
   }
   await fs__default.default.writeJson(techdocsMetadataPath, json);
   return;

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

@@ -1 +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 { NotAllowedError } from '@backstage/errors';\nimport { Entity } from '@backstage/catalog-model';\nimport { assertError, ForwardedError } from '@backstage/errors';\nimport { ScmIntegrationRegistry } from '@backstage/integration';\nimport { SpawnOptionsWithoutStdio, spawn } from 'node: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 'node:path';\nimport { PassThrough, Writable } from 'node: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  public readonly data: any;\n  public readonly type?: string;\n\n  constructor(data: any, type?: string) {\n    this.data = data;\n    this.type = type;\n  }\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 * Allowlist of MkDocs configuration keys supported by TechDocs.\n *\n * @see https://www.mkdocs.org/user-guide/configuration/\n */\nexport const ALLOWED_MKDOCS_KEYS = new Set([\n  // Site information\n  'site_name',\n  'site_url',\n  'site_description',\n  'site_author',\n  // Repository\n  'repo_url',\n  'repo_name',\n  'edit_uri',\n  'edit_uri_template',\n  // Build directories\n  'docs_dir',\n  'site_dir',\n  // Documentation layout\n  'nav',\n  'exclude_docs',\n  'not_in_nav',\n  // Build settings\n  'theme',\n  'plugins',\n  'markdown_extensions',\n  'extra',\n  'extra_css',\n  'extra_templates',\n  // Preview controls\n  'use_directory_urls',\n  'strict',\n  'dev_addr',\n  'watch',\n  // Metadata\n  'copyright',\n  'remote_branch',\n  'remote_name',\n  'validation',\n  // Deprecated\n  'google_analytics',\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\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 * Validates that the docs directory doesn't contain symlinks pointing outside\n * the input directory. This prevents path traversal attacks where malicious\n * symlinks could be used to read arbitrary files from the host filesystem.\n *\n * @param docsDir - The docs directory to validate (absolute path)\n * @param inputDir - The root input directory that symlinks must stay within\n */\nexport const validateDocsDirectory = async (\n  docsDir: string,\n  inputDir: string,\n): Promise<void> => {\n  const files = await getFileTreeRecursively(docsDir);\n\n  for (const file of files) {\n    if (!isChildPath(inputDir, file)) {\n      throw new NotAllowedError(\n        `Path ${file} is not allowed to refer to a location outside ${inputDir}`,\n      );\n    }\n  }\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","getFileTreeRecursively","NotAllowedError","assertError"],"mappings":"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"}
+{"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 { ForwardedError, NotAllowedError, toError } from '@backstage/errors';\nimport { ScmIntegrationRegistry } from '@backstage/integration';\nimport { SpawnOptionsWithoutStdio, spawn } from 'node: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 'node:path';\nimport { PassThrough, Writable } from 'node: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  public readonly data: any;\n  public readonly type?: string;\n\n  constructor(data: any, type?: string) {\n    this.data = data;\n    this.type = type;\n  }\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 * Allowlist of MkDocs configuration keys supported by TechDocs.\n *\n * @see https://www.mkdocs.org/user-guide/configuration/\n */\nexport const ALLOWED_MKDOCS_KEYS = new Set([\n  // Site information\n  'site_name',\n  'site_url',\n  'site_description',\n  'site_author',\n  // Repository\n  'repo_url',\n  'repo_name',\n  'edit_uri',\n  'edit_uri_template',\n  // Build directories\n  'docs_dir',\n  'site_dir',\n  // Documentation layout\n  'nav',\n  'exclude_docs',\n  'not_in_nav',\n  // Build settings\n  'theme',\n  'plugins',\n  'markdown_extensions',\n  'extra',\n  'extra_css',\n  'extra_templates',\n  // Preview controls\n  'use_directory_urls',\n  'strict',\n  'dev_addr',\n  'watch',\n  // Metadata\n  'copyright',\n  'remote_branch',\n  'remote_name',\n  'validation',\n  // Deprecated\n  'google_analytics',\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\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 * Validates that the docs directory doesn't contain symlinks pointing outside\n * the input directory. This prevents path traversal attacks where malicious\n * symlinks could be used to read arbitrary files from the host filesystem.\n *\n * @param docsDir - The docs directory to validate (absolute path)\n * @param inputDir - The root input directory that symlinks must stay within\n */\nexport const validateDocsDirectory = async (\n  docsDir: string,\n  inputDir: string,\n): Promise<void> => {\n  const files = await getFileTreeRecursively(docsDir);\n\n  for (const file of files) {\n    if (!isChildPath(inputDir, file)) {\n      throw new NotAllowedError(\n        `Path ${file} is not allowed to refer to a location outside ${inputDir}`,\n      );\n    }\n  }\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    const message = `Invalid JSON at ${techdocsMetadataPath} with error ${\n      toError(err).message\n    }`;\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    json.files = [];\n    logger.warn(\n      `Unable to add files list to metadata: ${toError(err).message}`,\n    );\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","getFileTreeRecursively","NotAllowedError","toError"],"mappings":"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"}

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

@@ -16,9 +16,8 @@ const patchMkdocsFile = async (mkdocsYmlPath, logger, updateAction) => {
   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}`
+      `Could not read MkDocs YAML config file ${mkdocsYmlPath} before running the generator: ${errors.toError(error).message}`
     );
     return;
   }
@@ -29,9 +28,8 @@ const patchMkdocsFile = async (mkdocsYmlPath, logger, updateAction) => {
       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}`
+      `Error in parsing YAML at ${mkdocsYmlPath} before running the generator. ${errors.toError(error).message}`
     );
     return;
   }
@@ -45,9 +43,8 @@ const patchMkdocsFile = async (mkdocsYmlPath, logger, updateAction) => {
       );
     }
   } catch (error) {
-    errors.assertError(error);
     logger.warn(
-      `Could not write to ${mkdocsYmlPath} after updating it before running the generator. ${error.message}`
+      `Could not write to ${mkdocsYmlPath} after updating it before running the generator. ${errors.toError(error).message}`
     );
     return;
   }

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

@@ -1 +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 {\n  ALLOWED_MKDOCS_KEYS,\n  getRepoUrlFromLocationAnnotation,\n  MKDOCS_SCHEMA,\n} 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\n/**\n * Sanitize mkdocs.yml by keeping only allowed configuration keys.\n *\n * TechDocs only supports a subset of MkDocs configuration options.\n * This function reconstructs the config with only allowed keys,\n * discarding everything else. This approach ensures that any unknown\n * or potentially dangerous configuration options are not passed to MkDocs.\n *\n * The file is always rewritten to ensure YAML features like merge keys\n * and anchors are resolved into plain configuration.\n *\n * @param mkdocsYmlPath - Absolute path to mkdocs.yml or equivalent of a docs site\n * @param logger - A logger instance\n * @param additionalAllowedKeys - Optional array of additional keys to allow beyond the default allowlist\n */\nexport const sanitizeMkdocsYml = async (\n  mkdocsYmlPath: string,\n  logger: LoggerService,\n  additionalAllowedKeys?: string[],\n) => {\n  await patchMkdocsFile(mkdocsYmlPath, logger, mkdocsYml => {\n    // Combine default allowed keys with additional keys\n    const allowedKeys = new Set(ALLOWED_MKDOCS_KEYS);\n    if (additionalAllowedKeys && additionalAllowedKeys.length > 0) {\n      logger.warn(\n        `DANGEROUS: Allowing additional MkDocs configuration keys beyond the default safe allowlist: ${additionalAllowedKeys.join(\n          ', ',\n        )}. This may introduce security vulnerabilities. Only use in trusted environments.`,\n      );\n      additionalAllowedKeys.forEach(key => allowedKeys.add(key));\n    }\n\n    // Identify keys that will be removed for logging\n    const removedKeys = Object.keys(mkdocsYml).filter(\n      key => !allowedKeys.has(key),\n    );\n\n    if (removedKeys.length > 0) {\n      logger.warn(\n        `Removed the following unsupported configuration keys from mkdocs.yml: ${removedKeys.join(\n          ', ',\n        )}. ` +\n          `TechDocs only supports a subset of MkDocs configuration options.`,\n      );\n    }\n\n    // Build a new object with only allowed keys\n    const sanitized: Record<string, unknown> = {};\n    for (const key of allowedKeys) {\n      if (key in mkdocsYml) {\n        sanitized[key] = (mkdocsYml as Record<string, unknown>)[key];\n      }\n    }\n\n    // Clear the original object and copy sanitized values back\n    for (const key of Object.keys(mkdocsYml)) {\n      delete (mkdocsYml as Record<string, unknown>)[key];\n    }\n    Object.assign(mkdocsYml, sanitized);\n\n    // Always rewrite to ensure clean YAML output (resolves merge keys, anchors, etc.)\n    return true;\n  });\n};\n"],"names":["fs","assertError","yaml","MKDOCS_SCHEMA","getRepoUrlFromLocationAnnotation","ALLOWED_MKDOCS_KEYS"],"mappings":"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"}
+{"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 {\n  ALLOWED_MKDOCS_KEYS,\n  getRepoUrlFromLocationAnnotation,\n  MKDOCS_SCHEMA,\n} from './helpers';\nimport { toError } 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    logger.warn(\n      `Could not read MkDocs YAML config file ${mkdocsYmlPath} before running the generator: ${\n        toError(error).message\n      }`,\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    logger.warn(\n      `Error in parsing YAML at ${mkdocsYmlPath} before running the generator. ${\n        toError(error).message\n      }`,\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    logger.warn(\n      `Could not write to ${mkdocsYmlPath} after updating it before running the generator. ${\n        toError(error).message\n      }`,\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\n/**\n * Sanitize mkdocs.yml by keeping only allowed configuration keys.\n *\n * TechDocs only supports a subset of MkDocs configuration options.\n * This function reconstructs the config with only allowed keys,\n * discarding everything else. This approach ensures that any unknown\n * or potentially dangerous configuration options are not passed to MkDocs.\n *\n * The file is always rewritten to ensure YAML features like merge keys\n * and anchors are resolved into plain configuration.\n *\n * @param mkdocsYmlPath - Absolute path to mkdocs.yml or equivalent of a docs site\n * @param logger - A logger instance\n * @param additionalAllowedKeys - Optional array of additional keys to allow beyond the default allowlist\n */\nexport const sanitizeMkdocsYml = async (\n  mkdocsYmlPath: string,\n  logger: LoggerService,\n  additionalAllowedKeys?: string[],\n) => {\n  await patchMkdocsFile(mkdocsYmlPath, logger, mkdocsYml => {\n    // Combine default allowed keys with additional keys\n    const allowedKeys = new Set(ALLOWED_MKDOCS_KEYS);\n    if (additionalAllowedKeys && additionalAllowedKeys.length > 0) {\n      logger.warn(\n        `DANGEROUS: Allowing additional MkDocs configuration keys beyond the default safe allowlist: ${additionalAllowedKeys.join(\n          ', ',\n        )}. This may introduce security vulnerabilities. Only use in trusted environments.`,\n      );\n      additionalAllowedKeys.forEach(key => allowedKeys.add(key));\n    }\n\n    // Identify keys that will be removed for logging\n    const removedKeys = Object.keys(mkdocsYml).filter(\n      key => !allowedKeys.has(key),\n    );\n\n    if (removedKeys.length > 0) {\n      logger.warn(\n        `Removed the following unsupported configuration keys from mkdocs.yml: ${removedKeys.join(\n          ', ',\n        )}. ` +\n          `TechDocs only supports a subset of MkDocs configuration options.`,\n      );\n    }\n\n    // Build a new object with only allowed keys\n    const sanitized: Record<string, unknown> = {};\n    for (const key of allowedKeys) {\n      if (key in mkdocsYml) {\n        sanitized[key] = (mkdocsYml as Record<string, unknown>)[key];\n      }\n    }\n\n    // Clear the original object and copy sanitized values back\n    for (const key of Object.keys(mkdocsYml)) {\n      delete (mkdocsYml as Record<string, unknown>)[key];\n    }\n    Object.assign(mkdocsYml, sanitized);\n\n    // Always rewrite to ensure clean YAML output (resolves merge keys, anchors, etc.)\n    return true;\n  });\n};\n"],"names":["fs","toError","yaml","MKDOCS_SCHEMA","getRepoUrlFromLocationAnnotation","ALLOWED_MKDOCS_KEYS"],"mappings":"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"}

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

@@ -29,12 +29,12 @@ class UrlPreparer {
         logger: this.logger
       });
     } catch (error) {
-      errors.assertError(error);
-      if (error.name === "NotModifiedError") {
+      const err = errors.toError(error);
+      if (err.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}`
+          `Unable to fetch files for building docs ${err.message}`
         );
       }
       throw error;

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

@@ -1 +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,WAAA,CAAoC;AAAA,EAC9B,MAAA;AAAA,EACA,MAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMjB,OAAO,WAAW,OAAA,EAAsC;AACtD,IAAA,OAAO,IAAI,WAAA,CAAY,OAAA,CAAQ,MAAA,EAAQ,QAAQ,MAAM,CAAA;AAAA,EACvD;AAAA,EAEQ,WAAA,CAAY,QAA0B,MAAA,EAAuB;AACnE,IAAA,IAAA,CAAK,MAAA,GAAS,MAAA;AACd,IAAA,IAAA,CAAK,MAAA,GAAS,MAAA;AAAA,EAChB;AAAA;AAAA,EAGA,4BAAA,GAA+B;AAC7B,IAAA,OAAO,IAAA;AAAA,EACT;AAAA;AAAA,EAGA,MAAM,OAAA,CACJ,MAAA,EACA,OAAA,EAC2B;AAC3B,IAAA,IAAI;AACF,MAAA,OAAO,MAAMA,iCAAA,CAA0B,IAAA,CAAK,MAAA,EAAQ,MAAA,EAAQ;AAAA,QAC1D,MAAM,OAAA,EAAS,IAAA;AAAA,QACf,QAAQ,IAAA,CAAK;AAAA,OACd,CAAA;AAAA,IACH,SAAS,KAAA,EAAO;AACd,MAAAC,kBAAA,CAAY,KAAK,CAAA;AAEjB,MAAA,IAAI,KAAA,CAAM,SAAS,kBAAA,EAAoB;AACrC,QAAA,IAAA,CAAK,MAAA,CAAO,KAAA,CAAM,CAAA,wBAAA,EAA2B,OAAA,EAAS,IAAI,CAAA,CAAE,CAAA;AAAA,MAC9D,CAAA,MAAO;AACL,QAAA,IAAA,CAAK,MAAA,CAAO,KAAA;AAAA,UACV,CAAA,wCAAA,EAA2C,MAAM,OAAO,CAAA;AAAA,SAC1D;AAAA,MACF;AAEA,MAAA,MAAM,KAAA;AAAA,IACR;AAAA,EACF;AACF;;;;"}
+{"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 { toError } 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      const err = toError(error);\n      // NotModifiedError means that etag based cache is still valid.\n      if (err.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 ${err.message}`,\n        );\n      }\n\n      throw error;\n    }\n  }\n}\n"],"names":["getDocFilesFromRepository","toError"],"mappings":";;;;;AA+BO,MAAM,WAAA,CAAoC;AAAA,EAC9B,MAAA;AAAA,EACA,MAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMjB,OAAO,WAAW,OAAA,EAAsC;AACtD,IAAA,OAAO,IAAI,WAAA,CAAY,OAAA,CAAQ,MAAA,EAAQ,QAAQ,MAAM,CAAA;AAAA,EACvD;AAAA,EAEQ,WAAA,CAAY,QAA0B,MAAA,EAAuB;AACnE,IAAA,IAAA,CAAK,MAAA,GAAS,MAAA;AACd,IAAA,IAAA,CAAK,MAAA,GAAS,MAAA;AAAA,EAChB;AAAA;AAAA,EAGA,4BAAA,GAA+B;AAC7B,IAAA,OAAO,IAAA;AAAA,EACT;AAAA;AAAA,EAGA,MAAM,OAAA,CACJ,MAAA,EACA,OAAA,EAC2B;AAC3B,IAAA,IAAI;AACF,MAAA,OAAO,MAAMA,iCAAA,CAA0B,IAAA,CAAK,MAAA,EAAQ,MAAA,EAAQ;AAAA,QAC1D,MAAM,OAAA,EAAS,IAAA;AAAA,QACf,QAAQ,IAAA,CAAK;AAAA,OACd,CAAA;AAAA,IACH,SAAS,KAAA,EAAO;AACd,MAAA,MAAM,GAAA,GAAMC,eAAQ,KAAK,CAAA;AAEzB,MAAA,IAAI,GAAA,CAAI,SAAS,kBAAA,EAAoB;AACnC,QAAA,IAAA,CAAK,MAAA,CAAO,KAAA,CAAM,CAAA,wBAAA,EAA2B,OAAA,EAAS,IAAI,CAAA,CAAE,CAAA;AAAA,MAC9D,CAAA,MAAO;AACL,QAAA,IAAA,CAAK,MAAA,CAAO,KAAA;AAAA,UACV,CAAA,wCAAA,EAA2C,IAAI,OAAO,CAAA;AAAA,SACxD;AAAA,MACF;AAEA,MAAA,MAAM,KAAA;AAAA,IACR;AAAA,EACF;AACF;;;;"}

package/dist/stages/publish/awsS3.cjs.js

@@ -327,9 +327,8 @@ class AwsS3Publish {
       );
       existingFiles = (response.Contents || []).map((f) => f.Key || "").filter((f) => !!f);
     } catch (e) {
-      errors.assertError(e);
       this.logger.error(
-        `Unable to list files for Entity ${entity.metadata.name}: ${e.message}`
+        `Unable to list files for Entity ${entity.metadata.name}: ${errors.toError(e).message}`
       );
     }
     let absoluteFilesToUpload;
@@ -495,9 +494,8 @@ class AwsS3Publish {
           );
           resolve(techdocsMetadata);
         } catch (err) {
-          errors.assertError(err);
-          this.logger.error(err.message);
-          reject(new Error(err.message));
+          this.logger.error(errors.toError(err).message);
+          reject(new Error(errors.toError(err).message));
         }
       });
     } catch (e) {
@@ -541,9 +539,8 @@ class AwsS3Publish {
           }
         }).pipe(res);
       } catch (err) {
-        errors.assertError(err);
         this.logger.warn(
-          `TechDocs S3 router failed to serve static files from bucket ${this.bucketName} at key ${filePath}: ${err.message}`
+          `TechDocs S3 router failed to serve static files from bucket ${this.bucketName} at key ${filePath}: ${errors.toError(err).message}`
         );
         res.status(404).send("File Not Found");
       }
@@ -588,8 +585,7 @@ class AwsS3Publish {
           try {
             newPath = helpers.lowerCaseEntityTripletInStoragePath(file);
           } catch (e) {
-            errors.assertError(e);
-            this.logger.warn(e.message);
+            this.logger.warn(errors.toError(e).message);
             return;
           }
           if (file === newPath) {
@@ -613,8 +609,9 @@ class AwsS3Publish {
               );
             }
           } catch (e) {
-            errors.assertError(e);
-            this.logger.warn(`Unable to migrate ${file}: ${e.message}`);
+            this.logger.warn(
+              `Unable to migrate ${file}: ${errors.toError(e).message}`
+            );
           }
         }, f)
       )