@backstage/repo-tools 0.1.0-next.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @backstage/repo-tools
+
+## 0.1.0-next.0
+
+### Minor Changes
+
+- 99713fd671: Introducing repo-tools package
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/errors@1.1.4-next.0

package/README.md

@@ -0,0 +1,11 @@
+# @backstage/repo-tools
+
+This package provides a CLI for backstage repo tooling.
+
+## Installation
+
+Install the package via Yarn:
+
+```sh
+yarn add @backstage/repo-tools
+```

package/bin/backstage-repo-tools

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+/*
+ * Copyright 2022 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+const path = require('path');
+
+// Figure out whether we're running inside the backstage repo or as an installed dependency
+/* eslint-disable-next-line no-restricted-syntax */
+const isLocal = require('fs').existsSync(path.resolve(__dirname, '../src'));
+
+if (!isLocal || process.env.BACKSTAGE_E2E_CLI_TEST) {
+  require('..');
+} else {
+  require('ts-node').register({
+    transpileOnly: true,
+    /* eslint-disable-next-line no-restricted-syntax */
+    project: path.resolve(__dirname, '../../../tsconfig.json'),
+    compilerOptions: {
+      module: 'CommonJS',
+    },
+  });
+
+  require('../src');
+}

package/dist/cjs/api-reports-3c013a5f.cjs.js

@@ -0,0 +1,1018 @@
+'use strict';
+
+var path = require('path');
+var fs = require('fs-extra');
+var child_process = require('child_process');
+var prettier = require('prettier');
+var apiExtractor = require('@microsoft/api-extractor');
+var tsdoc = require('@microsoft/tsdoc');
+var tsdocConfig = require('@microsoft/tsdoc-config');
+var apiExtractorModel = require('@microsoft/api-extractor-model');
+var MarkdownDocumenter = require('@microsoft/api-documenter/lib/documenters/MarkdownDocumenter');
+var DocTable = require('@microsoft/api-documenter/lib/nodes/DocTable');
+var DocTableRow = require('@microsoft/api-documenter/lib/nodes/DocTableRow');
+var DocHeading = require('@microsoft/api-documenter/lib/nodes/DocHeading');
+var CustomMarkdownEmitter = require('@microsoft/api-documenter/lib/markdown/CustomMarkdownEmitter');
+
+function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
+
+var fs__default = /*#__PURE__*/_interopDefaultLegacy(fs);
+var prettier__default = /*#__PURE__*/_interopDefaultLegacy(prettier);
+
+var __accessCheck = (obj, member, msg) => {
+  if (!member.has(obj))
+    throw TypeError("Cannot " + msg);
+};
+var __privateGet = (obj, member, getter) => {
+  __accessCheck(obj, member, "read from private field");
+  return getter ? getter.call(obj) : member.get(obj);
+};
+var __privateAdd = (obj, member, value) => {
+  if (member.has(obj))
+    throw TypeError("Cannot add the same private member more than once");
+  member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
+};
+var __privateSet = (obj, member, value, setter) => {
+  __accessCheck(obj, member, "write to private field");
+  setter ? setter.call(obj, value) : member.set(obj, value);
+  return value;
+};
+var _tokens;
+const tmpDir = path.resolve(
+  process.cwd(),
+  "./node_modules/.cache/api-extractor"
+);
+const {
+  PackageJsonLookup
+} = require("@rushstack/node-core-library/lib/PackageJsonLookup");
+const old = PackageJsonLookup.prototype.tryGetPackageJsonFilePathFor;
+PackageJsonLookup.prototype.tryGetPackageJsonFilePathFor = function tryGetPackageJsonFilePathForPatch(path$1) {
+  if (path$1.includes("@material-ui") && !path.dirname(path$1).endsWith("@material-ui")) {
+    return void 0;
+  }
+  return old.call(this, path$1);
+};
+const {
+  ApiReportGenerator
+} = require("@microsoft/api-extractor/lib/generators/ApiReportGenerator");
+function patchFileMessageFetcher(router, transform) {
+  const {
+    fetchAssociatedMessagesForReviewFile,
+    fetchUnassociatedMessagesForReviewFile
+  } = router;
+  router.fetchAssociatedMessagesForReviewFile = function patchedFetchAssociatedMessagesForReviewFile(ast) {
+    const messages = fetchAssociatedMessagesForReviewFile.call(this, ast);
+    return transform(messages, ast);
+  };
+  router.fetchUnassociatedMessagesForReviewFile = function patchedFetchUnassociatedMessagesForReviewFile() {
+    const messages = fetchUnassociatedMessagesForReviewFile.call(this);
+    return transform(messages);
+  };
+}
+const originalGenerateReviewFileContent = ApiReportGenerator.generateReviewFileContent;
+ApiReportGenerator.generateReviewFileContent = function decoratedGenerateReviewFileContent(collector, ...moreArgs) {
+  const program = collector.program;
+  patchFileMessageFetcher(
+    collector.messageRouter,
+    (messages) => {
+      return messages.filter((message) => {
+        var _a, _b, _c;
+        if (message.messageId !== "ae-forgotten-export") {
+          return true;
+        }
+        const symbolMatch = message.text.match(/The symbol "([^"]+)"/);
+        if (!symbolMatch) {
+          throw new Error(
+            `Failed to extract symbol name from message "${message.text}"`
+          );
+        }
+        const [, symbolName] = symbolMatch;
+        const sourceFile = message.sourceFilePath && program.getSourceFile(message.sourceFilePath);
+        if (!sourceFile) {
+          throw new Error(
+            `Failed to find source file in program at path "${message.sourceFilePath}"`
+          );
+        }
+        const localName = (_a = sourceFile.identifiers) == null ? void 0 : _a.get(symbolName);
+        if (!localName) {
+          throw new Error(
+            `Unable to find local name of "${symbolName}" in ${sourceFile.fileName}`
+          );
+        }
+        const local = (_b = sourceFile.locals) == null ? void 0 : _b.get(localName);
+        if (!local) {
+          return true;
+        }
+        const type = program.getTypeChecker().getDeclaredTypeOfSymbol(local);
+        if (!type) {
+          throw new Error(
+            `Unable to find type declaration of "${symbolName}" in ${sourceFile.fileName}`
+          );
+        }
+        const declarations = (_c = type.aliasSymbol) == null ? void 0 : _c.declarations;
+        if (!declarations || declarations.length === 0) {
+          return true;
+        }
+        const isIgnored = declarations.some((declaration) => {
+          const tags = [declaration.jsDoc].flat().filter(Boolean).flatMap((tagNode) => tagNode.tags);
+          return tags.some((tag) => (tag == null ? void 0 : tag.tagName.text) === "ignore");
+        });
+        return !isIgnored;
+      });
+    }
+  );
+  const content = originalGenerateReviewFileContent.call(
+    this,
+    collector,
+    ...moreArgs
+  );
+  return prettier__default["default"].format(content, {
+    ...require("@spotify/prettier-config"),
+    parser: "markdown"
+  });
+};
+const PACKAGE_ROOTS = ["packages", "plugins"];
+const ALLOW_WARNINGS = [
+  "packages/core-components",
+  "plugins/catalog",
+  "plugins/catalog-import",
+  "plugins/git-release-manager",
+  "plugins/jenkins",
+  "plugins/kubernetes"
+];
+async function resolvePackagePath(packagePath) {
+  const projectRoot = path.resolve(process.cwd());
+  const fullPackageDir = path.resolve(projectRoot, packagePath);
+  const stat = await fs__default["default"].stat(fullPackageDir);
+  if (!stat.isDirectory()) {
+    return void 0;
+  }
+  try {
+    const packageJsonPath = path.join(fullPackageDir, "package.json");
+    await fs__default["default"].access(packageJsonPath);
+  } catch (_) {
+    return void 0;
+  }
+  return path.relative(projectRoot, fullPackageDir);
+}
+async function findSpecificPackageDirs(unresolvedPackageDirs) {
+  const packageDirs = new Array();
+  for (const unresolvedPackageDir of unresolvedPackageDirs) {
+    const packageDir = await resolvePackagePath(unresolvedPackageDir);
+    if (!packageDir) {
+      throw new Error(`'${unresolvedPackageDir}' is not a valid package path`);
+    }
+    packageDirs.push(packageDir);
+  }
+  if (packageDirs.length === 0) {
+    return void 0;
+  }
+  return packageDirs;
+}
+async function findPackageDirs() {
+  const packageDirs = new Array();
+  const projectRoot = path.resolve(process.cwd());
+  for (const packageRoot of PACKAGE_ROOTS) {
+    const dirs = await fs__default["default"].readdir(path.resolve(projectRoot, packageRoot));
+    for (const dir of dirs) {
+      const packageDir = await resolvePackagePath(path.join(packageRoot, dir));
+      if (!packageDir) {
+        continue;
+      }
+      packageDirs.push(packageDir);
+    }
+  }
+  return packageDirs;
+}
+async function createTemporaryTsConfig(includedPackageDirs) {
+  const path$1 = path.resolve(process.cwd(), "tsconfig.tmp.json");
+  process.once("exit", () => {
+    fs__default["default"].removeSync(path$1);
+  });
+  await fs__default["default"].writeJson(path$1, {
+    extends: "./tsconfig.json",
+    include: [
+      "packages/cli/asset-types/asset-types.d.ts",
+      ...includedPackageDirs.map((dir) => path.join(dir, "src"))
+    ]
+  });
+  return path$1;
+}
+async function countApiReportWarnings(projectFolder) {
+  const path$1 = path.resolve(projectFolder, "api-report.md");
+  try {
+    const content = await fs__default["default"].readFile(path$1, "utf8");
+    const lines = content.split("\n");
+    const lineWarnings = lines.filter(
+      (line) => line.includes("// Warning:")
+    ).length;
+    const trailerStart = lines.findIndex(
+      (line) => line === "// Warnings were encountered during analysis:"
+    );
+    const trailerWarnings = trailerStart === -1 ? 0 : lines.length - trailerStart - 4;
+    return lineWarnings + trailerWarnings;
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return 0;
+    }
+    throw error;
+  }
+}
+async function getTsDocConfig() {
+  const tsdocConfigFile = await tsdocConfig.TSDocConfigFile.loadFile(
+    require.resolve("@microsoft/api-extractor/extends/tsdoc-base.json")
+  );
+  tsdocConfigFile.addTagDefinition({
+    tagName: "@ignore",
+    syntaxKind: tsdoc.TSDocTagSyntaxKind.ModifierTag
+  });
+  tsdocConfigFile.setSupportForTag("@ignore", true);
+  return tsdocConfigFile;
+}
+function logApiReportInstructions() {
+  console.log("");
+  console.log(
+    "*************************************************************************************"
+  );
+  console.log(
+    "* You have uncommitted changes to the public API of a package.                      *"
+  );
+  console.log(
+    "* To solve this, run `yarn build:api-reports` and commit all api-report.md changes. *"
+  );
+  console.log(
+    "*************************************************************************************"
+  );
+  console.log("");
+}
+async function runApiExtraction({
+  packageDirs,
+  outputDir,
+  isLocalBuild,
+  tsconfigFilePath
+}) {
+  await fs__default["default"].remove(outputDir);
+  const entryPoints = packageDirs.map((packageDir) => {
+    return path.resolve(
+      process.cwd(),
+      `./dist-types/${packageDir}/src/index.d.ts`
+    );
+  });
+  let compilerState = void 0;
+  const warnings = new Array();
+  for (const packageDir of packageDirs) {
+    console.log(`## Processing ${packageDir}`);
+    const projectFolder = path.resolve(process.cwd(), packageDir);
+    const packageFolder = path.resolve(
+      process.cwd(),
+      "./dist-types",
+      packageDir
+    );
+    const warningCountBefore = await countApiReportWarnings(projectFolder);
+    const extractorConfig = apiExtractor.ExtractorConfig.prepare({
+      configObject: {
+        mainEntryPointFilePath: path.resolve(packageFolder, "src/index.d.ts"),
+        bundledPackages: [],
+        compiler: {
+          tsconfigFilePath
+        },
+        apiReport: {
+          enabled: true,
+          reportFileName: "api-report.md",
+          reportFolder: projectFolder,
+          reportTempFolder: path.resolve(outputDir, "<unscopedPackageName>")
+        },
+        docModel: {
+          enabled: true,
+          apiJsonFilePath: path.resolve(
+            outputDir,
+            "<unscopedPackageName>.api.json"
+          )
+        },
+        dtsRollup: {
+          enabled: false
+        },
+        tsdocMetadata: {
+          enabled: false
+        },
+        messages: {
+          compilerMessageReporting: {
+            default: {
+              logLevel: "none"
+            }
+          },
+          extractorMessageReporting: {
+            default: {
+              logLevel: "warning",
+              addToApiReportFile: true
+            }
+          },
+          tsdocMessageReporting: {
+            default: {
+              logLevel: "warning",
+              addToApiReportFile: true
+            }
+          }
+        },
+        newlineKind: "lf",
+        projectFolder
+      },
+      configObjectFullPath: projectFolder,
+      packageJsonFullPath: path.resolve(projectFolder, "package.json"),
+      tsdocConfigFile: await getTsDocConfig()
+    });
+    extractorConfig.packageFolder = packageFolder;
+    if (!compilerState) {
+      compilerState = apiExtractor.CompilerState.create(extractorConfig, {
+        additionalEntryPoints: entryPoints
+      });
+    }
+    apiExtractor.Extractor._checkCompilerCompatibility = () => {
+    };
+    let shouldLogInstructions = false;
+    let conflictingFile = void 0;
+    const extractorResult = apiExtractor.Extractor.invoke(extractorConfig, {
+      localBuild: isLocalBuild,
+      showVerboseMessages: false,
+      showDiagnostics: false,
+      messageCallback(message) {
+        if (message.text.includes(
+          "You have changed the public API signature for this project."
+        )) {
+          shouldLogInstructions = true;
+          const match = message.text.match(
+            /Please copy the file "(.*)" to "api-report\.md"/
+          );
+          if (match) {
+            conflictingFile = match[1];
+          }
+        }
+      },
+      compilerState
+    });
+    if (!extractorResult.succeeded) {
+      if (shouldLogInstructions) {
+        logApiReportInstructions();
+        if (conflictingFile) {
+          console.log("");
+          console.log(
+            `The conflicting file is ${path.relative(
+              tmpDir,
+              conflictingFile
+            )}, with the following content:`
+          );
+          console.log("");
+          const content = await fs__default["default"].readFile(conflictingFile, "utf8");
+          console.log(content);
+          logApiReportInstructions();
+        }
+      }
+      throw new Error(
+        `API Extractor completed with ${extractorResult.errorCount} errors and ${extractorResult.warningCount} warnings`
+      );
+    }
+    const warningCountAfter = await countApiReportWarnings(projectFolder);
+    if (warningCountAfter > 0 && !ALLOW_WARNINGS.includes(packageDir)) {
+      throw new Error(
+        `The API Report for ${packageDir} is not allowed to have warnings`
+      );
+    }
+    if (warningCountAfter === 0 && ALLOW_WARNINGS.includes(packageDir)) {
+      console.log(
+        `No need to allow warnings for ${packageDir}, it does not have any`
+      );
+    }
+    if (warningCountAfter > warningCountBefore) {
+      warnings.push(
+        `The API Report for ${packageDir} introduces new warnings. Please fix these warnings in order to keep the API Reports tidy.`
+      );
+    }
+  }
+  if (warnings.length > 0) {
+    console.warn();
+    for (const warning of warnings) {
+      console.warn(warning);
+    }
+    console.warn();
+  }
+}
+class ExcerptTokenMatcher {
+  constructor(tokens) {
+    __privateAdd(this, _tokens, void 0);
+    __privateSet(this, _tokens, tokens.slice());
+  }
+  nextContent() {
+    const token = __privateGet(this, _tokens).shift();
+    if ((token == null ? void 0 : token.kind) === "Content") {
+      return token.text;
+    }
+    return void 0;
+  }
+  matchContent(expectedText) {
+    const text = this.nextContent();
+    return text !== expectedText;
+  }
+  getTokensUntilArrow() {
+    const tokens = [];
+    for (; ; ) {
+      const token = __privateGet(this, _tokens).shift();
+      if (token === void 0) {
+        return void 0;
+      }
+      if (token.kind === "Content" && token.text === ") => ") {
+        return tokens;
+      }
+      tokens.push(token);
+    }
+  }
+  getComponentReturnTokens() {
+    const first = __privateGet(this, _tokens).shift();
+    if (!first) {
+      return void 0;
+    }
+    const second = __privateGet(this, _tokens).shift();
+    if (__privateGet(this, _tokens).length !== 0) {
+      return void 0;
+    }
+    if (first.kind !== "Reference" || first.text !== "JSX.Element") {
+      return void 0;
+    }
+    if (!second) {
+      return [first];
+    } else if (second.kind === "Content" && second.text === " | null") {
+      return [first, second];
+    }
+    return void 0;
+  }
+}
+_tokens = new WeakMap();
+const _ApiModelTransforms = class {
+  static deserializeWithTransforms(serialized, transforms) {
+    if (serialized.kind !== "Package") {
+      throw new Error(
+        `Unexpected root kind in serialized ApiPackage, ${serialized.kind}`
+      );
+    }
+    if (serialized.members.length !== 1) {
+      throw new Error(
+        `Unexpected members in serialized ApiPackage, [${serialized.members.map((m) => m.kind).join(" ")}]`
+      );
+    }
+    const [entryPoint] = serialized.members;
+    if (entryPoint.kind !== "EntryPoint") {
+      throw new Error(
+        `Unexpected kind in serialized ApiPackage member, ${entryPoint.kind}`
+      );
+    }
+    const transformed = {
+      ...serialized,
+      members: [
+        {
+          ...entryPoint,
+          members: entryPoint.members.map(
+            (member) => transforms.reduce((m, t) => t(m), member)
+          )
+        }
+      ]
+    };
+    return apiExtractorModel.ApiPackage.deserialize(
+      transformed,
+      transformed.metadata
+    );
+  }
+  static makeComponentMember(member, ret, props) {
+    var _a;
+    const declTokens = props ? [
+      {
+        kind: "Content",
+        text: `export declare function ${member.name}(props: `
+      },
+      ...props,
+      {
+        kind: "Content",
+        text: "): "
+      }
+    ] : [
+      {
+        kind: "Content",
+        text: `export declare function ${member.name}(): `
+      }
+    ];
+    return {
+      kind: "Function",
+      name: member.name,
+      releaseTag: member.releaseTag,
+      docComment: (_a = member.docComment) != null ? _a : "",
+      canonicalReference: member.canonicalReference,
+      excerptTokens: [...declTokens, ...ret],
+      returnTypeTokenRange: {
+        startIndex: declTokens.length,
+        endIndex: declTokens.length + ret.length
+      },
+      parameters: props ? [
+        {
+          parameterName: "props",
+          parameterTypeTokenRange: {
+            startIndex: 1,
+            endIndex: 1 + props.length
+          }
+        }
+      ] : [],
+      overloadIndex: 1
+    };
+  }
+};
+let ApiModelTransforms = _ApiModelTransforms;
+ApiModelTransforms.transformArrowComponents = (member) => {
+  if (member.kind !== "Variable") {
+    return member;
+  }
+  const { name, excerptTokens } = member;
+  const [firstChar] = name;
+  if (firstChar.toLocaleUpperCase("en-US") !== firstChar) {
+    return member;
+  }
+  const tokens = new ExcerptTokenMatcher(excerptTokens);
+  if (tokens.nextContent() !== `${name}: `) {
+    return member;
+  }
+  const declStart = tokens.nextContent();
+  if (declStart === "(props: " || declStart === "(_props: ") {
+    const props = tokens.getTokensUntilArrow();
+    const ret = tokens.getComponentReturnTokens();
+    if (props && ret) {
+      return _ApiModelTransforms.makeComponentMember(member, ret, props);
+    }
+  } else if (declStart === "() => ") {
+    const ret = tokens.getComponentReturnTokens();
+    if (ret) {
+      return _ApiModelTransforms.makeComponentMember(member, ret);
+    }
+  }
+  return member;
+};
+ApiModelTransforms.transformTrimDeclare = (member) => {
+  const { excerptTokens } = member;
+  const firstContent = new ExcerptTokenMatcher(excerptTokens).nextContent();
+  if (firstContent && firstContent.startsWith("export declare ")) {
+    return {
+      ...member,
+      excerptTokens: [
+        {
+          kind: "Content",
+          text: firstContent.slice("export declare ".length)
+        },
+        ...excerptTokens.slice(1)
+      ]
+    };
+  }
+  return member;
+};
+async function buildDocs({
+  inputDir,
+  outputDir
+}) {
+  const parseFile = async (filename) => {
+    console.log(`Reading ${filename}`);
+    return fs__default["default"].readJson(path.resolve(inputDir, filename));
+  };
+  const filenames = await fs__default["default"].readdir(inputDir);
+  const serializedPackages = await Promise.all(
+    filenames.filter((filename) => filename.match(/\.api\.json$/i)).map(parseFile)
+  );
+  const newModel = new apiExtractorModel.ApiModel();
+  for (const serialized of serializedPackages) {
+    newModel.addMember(
+      ApiModelTransforms.deserializeWithTransforms(serialized, [
+        ApiModelTransforms.transformArrowComponents,
+        ApiModelTransforms.transformTrimDeclare
+      ])
+    );
+  }
+  const _DocFrontMatter = class extends tsdoc.DocNode {
+    constructor(parameters) {
+      super(parameters);
+      this.values = parameters.values;
+    }
+    get kind() {
+      return _DocFrontMatter.kind;
+    }
+  };
+  let DocFrontMatter = _DocFrontMatter;
+  DocFrontMatter.kind = "DocFrontMatter";
+  class CustomCustomMarkdownEmitter extends CustomMarkdownEmitter.CustomMarkdownEmitter {
+    getEscapedText(text) {
+      return text.replace(/\\/g, "\\\\").replace(/[*#[\]_`~]/g, (x) => `\\${x}`).replace(/---/g, "\\-\\-\\-").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/\|/g, "&#124;");
+    }
+    writeNode(docNode, context, docNodeSiblings) {
+      switch (docNode.kind) {
+        case DocFrontMatter.kind: {
+          const node = docNode;
+          context.writer.writeLine("---");
+          for (const [name, value] of Object.entries(node.values)) {
+            if (value) {
+              context.writer.writeLine(`${name}: ${value}`);
+            }
+          }
+          context.writer.writeLine("---");
+          context.writer.writeLine();
+          break;
+        }
+        default:
+          super.writeNode(docNode, context, docNodeSiblings);
+      }
+    }
+    emit(stringBuilder, docNode, options) {
+      stringBuilder._chunks.length = 0;
+      return super.emit(stringBuilder, docNode, options);
+    }
+  }
+  class CustomMarkdownDocumenter extends MarkdownDocumenter.MarkdownDocumenter {
+    constructor(options) {
+      super(options);
+      this._tsdocConfiguration.docNodeManager.registerDocNodes(
+        "@backstage/docs",
+        [{ docNodeKind: DocFrontMatter.kind, constructor: DocFrontMatter }]
+      );
+      this._tsdocConfiguration.docNodeManager.registerAllowableChildren(
+        "Paragraph",
+        [DocFrontMatter.kind]
+      );
+      this._markdownEmitter = new CustomCustomMarkdownEmitter(newModel);
+    }
+    _getFilenameForApiItem(apiItem) {
+      const filename = super._getFilenameForApiItem(apiItem);
+      if (filename.includes(".html.")) {
+        return filename.replace(/\.html\./g, "._html.");
+      }
+      return filename;
+    }
+    _writeBreadcrumb(output, apiItem) {
+      let title;
+      let description;
+      const name = apiItem.getScopedNameWithinPackage();
+      if (name) {
+        title = name;
+        description = `API reference for ${apiItem.getScopedNameWithinPackage()}`;
+      } else if (apiItem.kind === "Model") {
+        title = "Package Index";
+        description = "Index of all Backstage Packages";
+      } else if (apiItem.name) {
+        title = apiItem.name;
+        description = `API Reference for ${apiItem.name}`;
+      } else {
+        title = apiItem.displayName;
+        description = `API Reference for ${apiItem.displayName}`;
+      }
+      output.appendNodeInParagraph(
+        new DocFrontMatter({
+          configuration: this._tsdocConfiguration,
+          values: {
+            id: this._getFilenameForApiItem(apiItem).slice(0, -3),
+            title,
+            description
+          }
+        })
+      );
+      super._writeBreadcrumb(output, apiItem);
+      const oldAppendNode = output.appendNode;
+      output.appendNode = () => {
+        output.appendNode = oldAppendNode;
+      };
+    }
+    _writeModelTable(output, apiModel) {
+      const configuration = this._tsdocConfiguration;
+      const packagesTable = new DocTable.DocTable({
+        configuration,
+        headerTitles: ["Package", "Description"]
+      });
+      const pluginsTable = new DocTable.DocTable({
+        configuration,
+        headerTitles: ["Package", "Description"]
+      });
+      for (const apiMember of apiModel.members) {
+        const row = new DocTableRow.DocTableRow({ configuration }, [
+          this._createTitleCell(apiMember),
+          this._createDescriptionCell(apiMember)
+        ]);
+        if (apiMember.kind === "Package") {
+          this._writeApiItemPage(apiMember);
+          if (apiMember.name.startsWith("@backstage/plugin-")) {
+            pluginsTable.addRow(row);
+          } else {
+            packagesTable.addRow(row);
+          }
+        }
+      }
+      if (packagesTable.rows.length > 0) {
+        output.appendNode(
+          new DocHeading.DocHeading({
+            configuration: this._tsdocConfiguration,
+            title: "Packages"
+          })
+        );
+        output.appendNode(packagesTable);
+      }
+      if (pluginsTable.rows.length > 0) {
+        output.appendNode(
+          new DocHeading.DocHeading({
+            configuration: this._tsdocConfiguration,
+            title: "Plugins"
+          })
+        );
+        output.appendNode(pluginsTable);
+      }
+    }
+  }
+  const documenter = new CustomMarkdownDocumenter({
+    apiModel: newModel,
+    documenterConfig: {
+      outputTarget: "markdown",
+      newlineKind: "\n",
+      configFilePath: "",
+      configFile: {}
+    },
+    outputFolder: outputDir
+  });
+  await fs__default["default"].remove(outputDir);
+  await fs__default["default"].ensureDir(outputDir);
+  documenter.generateFiles();
+}
+async function categorizePackageDirs(projectRoot, packageDirs) {
+  const dirs = packageDirs.slice();
+  const tsPackageDirs = new Array();
+  const cliPackageDirs = new Array();
+  await Promise.all(
+    Array(10).fill(0).map(async () => {
+      var _a;
+      for (; ; ) {
+        const dir = dirs.pop();
+        if (!dir) {
+          return;
+        }
+        const pkgJson = await fs__default["default"].readJson(path.resolve(projectRoot, dir, "package.json")).catch((error) => {
+          if (error.code === "ENOENT") {
+            return void 0;
+          }
+          throw error;
+        });
+        const role = (_a = pkgJson == null ? void 0 : pkgJson.backstage) == null ? void 0 : _a.role;
+        if (!role) {
+          throw new Error(`No backstage.role in ${dir}/package.json`);
+        }
+        if (role === "cli") {
+          cliPackageDirs.push(dir);
+        } else if (role !== "frontend" && role !== "backend") {
+          tsPackageDirs.push(dir);
+        }
+      }
+    })
+  );
+  return { tsPackageDirs, cliPackageDirs };
+}
+function createBinRunner(cwd, path) {
+  return async (...command) => new Promise((resolve, reject) => {
+    child_process.execFile(
+      "node",
+      [path, ...command],
+      {
+        cwd,
+        shell: true,
+        timeout: 6e4,
+        maxBuffer: 1024 * 1024
+      },
+      (err, stdout, stderr) => {
+        if (err) {
+          reject(new Error(`${err.message}
+${stderr}`));
+        } else if (stderr) {
+          reject(new Error(`Command printed error output: ${stderr}`));
+        } else {
+          resolve(stdout);
+        }
+      }
+    );
+  });
+}
+function parseHelpPage(helpPageContent) {
+  var _a;
+  const [, usage] = (_a = helpPageContent.match(/^\s*Usage: (.*)$/im)) != null ? _a : [];
+  const lines = helpPageContent.split(/\r?\n/);
+  let options = new Array();
+  let commands = new Array();
+  while (lines.length > 0) {
+    while (lines.length > 0 && !lines[0].endsWith(":")) {
+      lines.shift();
+    }
+    if (lines.length > 0) {
+      const sectionName = lines.shift();
+      const sectionEndIndex = lines.findIndex(
+        (line) => line && !line.match(/^\s/)
+      );
+      const sectionLines = lines.slice(0, sectionEndIndex);
+      lines.splice(0, sectionLines.length);
+      const sectionItems = sectionLines.map((line) => {
+        var _a2;
+        return (_a2 = line.match(/^\s{1,8}(.*?)\s\s+/)) == null ? void 0 : _a2[1];
+      }).filter(Boolean);
+      if ((sectionName == null ? void 0 : sectionName.toLocaleLowerCase("en-US")) === "options:") {
+        options = sectionItems;
+      } else if ((sectionName == null ? void 0 : sectionName.toLocaleLowerCase("en-US")) === "commands:") {
+        commands = sectionItems;
+      } else {
+        throw new Error(`Unknown CLI section: ${sectionName}`);
+      }
+    }
+  }
+  return {
+    usage,
+    options,
+    commands
+  };
+}
+async function exploreCliHelpPages(run) {
+  const helpPages = new Array();
+  async function exploreHelpPage(...path) {
+    const content = await run(...path, "--help");
+    const parsed = parseHelpPage(content);
+    helpPages.push({ path, ...parsed });
+    await Promise.all(
+      parsed.commands.map(async (fullCommand) => {
+        const command = fullCommand.split(/[|\s]/)[0];
+        if (command !== "help") {
+          await exploreHelpPage(...path, command);
+        }
+      })
+    );
+  }
+  await exploreHelpPage();
+  helpPages.sort((a, b) => a.path.join(" ").localeCompare(b.path.join(" ")));
+  return helpPages;
+}
+function generateCliReport(name, models) {
+  var _a;
+  const content = [
+    `## CLI Report file for "${name}"`,
+    "",
+    "> Do not edit this file. It is a report generated by `yarn build:api-reports`",
+    ""
+  ];
+  for (const model of models) {
+    for (const helpPage of model.helpPages) {
+      content.push(
+        `### \`${[model.name, ...helpPage.path].join(" ")}\``,
+        "",
+        "```",
+        `Usage: ${(_a = helpPage.usage) != null ? _a : "<none>"}`
+      );
+      if (helpPage.options.length > 0) {
+        content.push("", "Options:", ...helpPage.options.map((l) => `  ${l}`));
+      }
+      if (helpPage.commands.length > 0) {
+        content.push("", "Commands:", ...helpPage.commands.map((l) => `  ${l}`));
+      }
+      content.push("```", "");
+    }
+  }
+  return content.join("\n");
+}
+async function runCliExtraction({
+  projectRoot,
+  packageDirs,
+  isLocalBuild
+}) {
+  for (const packageDir of packageDirs) {
+    console.log(`## Processing ${packageDir}`);
+    const fullDir = path.resolve(projectRoot, packageDir);
+    const pkgJson = await fs__default["default"].readJson(path.resolve(fullDir, "package.json"));
+    if (!pkgJson.bin) {
+      throw new Error(`CLI Package in ${packageDir} has no bin field`);
+    }
+    const models = new Array();
+    if (typeof pkgJson.bin === "string") {
+      const run = createBinRunner(fullDir, pkgJson.bin);
+      const helpPages = await exploreCliHelpPages(run);
+      models.push({ name: path.basename(pkgJson.bin), helpPages });
+    } else {
+      for (const [name, path] of Object.entries(pkgJson.bin)) {
+        const run = createBinRunner(fullDir, path);
+        const helpPages = await exploreCliHelpPages(run);
+        models.push({ name, helpPages });
+      }
+    }
+    const report = generateCliReport(pkgJson.name, models);
+    const reportPath = path.resolve(fullDir, "cli-report.md");
+    const existingReport = await fs__default["default"].readFile(reportPath, "utf8").catch((error) => {
+      if (error.code === "ENOENT") {
+        return void 0;
+      }
+      throw error;
+    });
+    if (existingReport !== report) {
+      if (isLocalBuild) {
+        console.warn(`CLI report changed for ${packageDir}`);
+        await fs__default["default"].writeFile(reportPath, report);
+      } else {
+        logApiReportInstructions();
+        if (existingReport) {
+          console.log("");
+          console.log(
+            `The conflicting file is ${path.relative(
+              projectRoot,
+              reportPath
+            )}, expecting the following content:`
+          );
+          console.log("");
+          console.log(report);
+          logApiReportInstructions();
+        }
+        throw new Error(`CLI report changed for ${packageDir}, `);
+      }
+    }
+  }
+}
+
+var apiReports = async (paths, opts) => {
+  const tmpDir = path.resolve(
+    process.cwd(),
+    "./node_modules/.cache/api-extractor"
+  );
+  const projectRoot = path.resolve(process.cwd());
+  const isCiBuild = opts.ci;
+  const isDocsBuild = opts.docs;
+  const runTsc = opts.tsc;
+  const selectedPackageDirs = await findSpecificPackageDirs(paths);
+  if (selectedPackageDirs && isCiBuild) {
+    throw new Error(
+      "Package path arguments are not supported together with the --ci flag"
+    );
+  }
+  if (!selectedPackageDirs && !isCiBuild && !isDocsBuild) {
+    console.log("");
+    console.log(
+      "TIP: You can generate api-reports for select packages by passing package paths:"
+    );
+    console.log("");
+    console.log(
+      "       yarn build:api-reports packages/config packages/core-plugin-api"
+    );
+    console.log("");
+  }
+  let temporaryTsConfigPath;
+  if (selectedPackageDirs) {
+    temporaryTsConfigPath = await createTemporaryTsConfig(selectedPackageDirs);
+  }
+  const tsconfigFilePath = temporaryTsConfigPath != null ? temporaryTsConfigPath : path.resolve(projectRoot, "tsconfig.json");
+  if (runTsc) {
+    await fs__default["default"].remove(path.resolve(projectRoot, "dist-types"));
+    const { status } = child_process.spawnSync(
+      "yarn",
+      [
+        "tsc",
+        ["--project", tsconfigFilePath],
+        ["--skipLibCheck", "false"],
+        ["--incremental", "false"]
+      ].flat(),
+      {
+        stdio: "inherit",
+        shell: true,
+        cwd: projectRoot
+      }
+    );
+    if (status !== 0) {
+      process.exit(status || void 0);
+    }
+  }
+  const packageDirs = selectedPackageDirs != null ? selectedPackageDirs : await findPackageDirs();
+  const { tsPackageDirs, cliPackageDirs } = await categorizePackageDirs(
+    projectRoot,
+    packageDirs
+  );
+  if (tsPackageDirs.length > 0) {
+    console.log("# Generating package API reports");
+    await runApiExtraction({
+      packageDirs: tsPackageDirs,
+      outputDir: tmpDir,
+      isLocalBuild: !isCiBuild,
+      tsconfigFilePath
+    });
+  }
+  if (cliPackageDirs.length > 0) {
+    console.log("# Generating package CLI reports");
+    await runCliExtraction({
+      projectRoot,
+      packageDirs: cliPackageDirs,
+      isLocalBuild: !isCiBuild
+    });
+  }
+  if (isDocsBuild) {
+    console.log("# Generating package documentation");
+    await buildDocs({
+      inputDir: tmpDir,
+      outputDir: path.resolve(projectRoot, "docs/reference")
+    });
+  }
+};
+
+exports["default"] = apiReports;
+//# sourceMappingURL=api-reports-3c013a5f.cjs.js.map

package/dist/index.cjs.js

@@ -0,0 +1,78 @@
+'use strict';
+
+var commander = require('commander');
+var chalk = require('chalk');
+var errors = require('@backstage/errors');
+
+function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
+
+var chalk__default = /*#__PURE__*/_interopDefaultLegacy(chalk);
+
+class CustomError extends Error {
+  get name() {
+    return this.constructor.name;
+  }
+}
+class ExitCodeError extends CustomError {
+  constructor(code, command) {
+    super(
+      command ? `Command '${command}' exited with code ${code}` : `Child exited with code ${code}`
+    );
+    this.code = code;
+  }
+}
+function exitWithError(error) {
+  if (error instanceof ExitCodeError) {
+    process.stderr.write(`
+${chalk__default["default"].red(error.message)}
+
+`);
+    process.exit(error.code);
+  } else {
+    process.stderr.write(`
+${chalk__default["default"].red(`${error}`)}
+
+`);
+    process.exit(1);
+  }
+}
+
+function registerCommands(program) {
+  program.command("api-reports [path...]").option("--ci", "CI run checks that there is no changes on API reports").option("--tsc", "executes the tsc compilation before extracting the APIs").option("--docs", "generates the api documentation").description("Generate an API report for selected packages").action(
+    lazy(() => Promise.resolve().then(function () { return require('./cjs/api-reports-3c013a5f.cjs.js'); }).then((m) => m.default))
+  );
+}
+function lazy(getActionFunc) {
+  return async (...args) => {
+    try {
+      const actionFunc = await getActionFunc();
+      await actionFunc(...args);
+      process.exit(0);
+    } catch (error) {
+      errors.assertError(error);
+      exitWithError(error);
+    }
+  };
+}
+
+const main = (argv) => {
+  commander.program.name("backstage-repo-tools").version("1.0");
+  registerCommands(commander.program);
+  commander.program.on("command:*", () => {
+    console.log();
+    console.log(chalk__default["default"].red(`Invalid command: ${commander.program.args.join(" ")}`));
+    console.log();
+    commander.program.outputHelp();
+    process.exit(1);
+  });
+  commander.program.parse(argv);
+};
+process.on("unhandledRejection", (rejection) => {
+  if (rejection instanceof Error) {
+    exitWithError(rejection);
+  } else {
+    exitWithError(new Error(`Unknown rejection: '${rejection}'`));
+  }
+});
+main(process.argv);
+//# sourceMappingURL=index.cjs.js.map

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@backstage/repo-tools",
+  "description": "CLI for Backstage repo tooling ",
+  "version": "0.1.0-next.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "backstage": {
+    "role": "cli"
+  },
+  "homepage": "https://backstage.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/backstage/backstage",
+    "directory": "packages/repo-tools"
+  },
+  "keywords": [
+    "backstage"
+  ],
+  "license": "Apache-2.0",
+  "main": "dist/index.cjs.js",
+  "scripts": {
+    "build": "backstage-cli package build",
+    "lint": "backstage-cli package lint",
+    "test": "backstage-cli package test",
+    "clean": "backstage-cli package clean",
+    "start": "nodemon --"
+  },
+  "bin": {
+    "backstage-repo-tools": "bin/backstage-repo-tools"
+  },
+  "dependencies": {
+    "@backstage/errors": "^1.1.4-next.0",
+    "@microsoft/api-documenter": "^7.17.11",
+    "@microsoft/api-extractor": "^7.23.0",
+    "@microsoft/api-extractor-model": "^7.17.2",
+    "@microsoft/tsdoc": "0.14.1",
+    "chalk": "^4.0.0",
+    "commander": "^9.1.0",
+    "fs-extra": "10.1.0",
+    "ts-node": "^10.0.0"
+  },
+  "files": [
+    "bin",
+    "dist/**/*.js"
+  ],
+  "nodemonConfig": {
+    "watch": "./src",
+    "exec": "bin/backstage-repo-tools",
+    "ext": "ts"
+  }
+}