@backstage/repo-tools 0.12.1 → 0.12.2-next.1

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @backstage/repo-tools
 
+## 0.12.2-next.1
+
+### Patch Changes
+
+- 58ec9e7: Removed older versions of React packages as a preparatory step for upgrading to React 19. This commit does not introduce any functional changes, but removes dependencies on previous React versions, allowing for a cleaner upgrade path in subsequent commits.
+- Updated dependencies
+  - @backstage/backend-plugin-api@1.2.0-next.0
+  - @backstage/catalog-model@1.7.3
+  - @backstage/cli-common@0.1.15
+  - @backstage/cli-node@0.2.13-next.0
+  - @backstage/config-loader@1.9.6-next.0
+  - @backstage/errors@1.2.7
+
+## 0.12.2-next.0
+
+### Patch Changes
+
+- 98ddf05: The `api-reports` command is now also able to generate SQL reports, enabled by the `--sql-reports` flag.
+- cb76663: Internal refactor to support native ESM.
+- ecd01a9: Internal refactor of API report generation.
+- Updated dependencies
+  - @backstage/cli-node@0.2.13-next.0
+  - @backstage/config-loader@1.9.6-next.0
+  - @backstage/backend-plugin-api@1.2.0-next.0
+  - @backstage/catalog-model@1.7.3
+  - @backstage/cli-common@0.1.15
+  - @backstage/errors@1.2.7
+
 ## 0.12.1
 
 ### Patch Changes

package/dist/commands/api-reports/api-reports/buildDocs.cjs.js

@@ -0,0 +1,443 @@
+'use strict';
+
+var path = require('path');
+var fs = require('fs-extra');
+var tsdoc = require('@microsoft/tsdoc');
+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 _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e : { default: e }; }
+
+var fs__default = /*#__PURE__*/_interopDefaultCompat(fs);
+
+class ExcerptTokenMatcher {
+  #tokens;
+  constructor(tokens) {
+    this.#tokens = tokens.slice();
+  }
+  nextContent() {
+    const token = this.#tokens.shift();
+    if (token?.kind === "Content") {
+      return token.text;
+    }
+    return void 0;
+  }
+  matchContent(expectedText) {
+    const text = this.nextContent();
+    return text !== expectedText;
+  }
+  getTokensUntilArrow() {
+    const tokens = [];
+    for (; ; ) {
+      const token = this.#tokens.shift();
+      if (token === void 0) {
+        return void 0;
+      }
+      if (token.kind === "Content" && token.text === ") => ") {
+        return tokens;
+      }
+      tokens.push(token);
+    }
+  }
+  getComponentReturnTokens() {
+    const first = this.#tokens.shift();
+    if (!first) {
+      return void 0;
+    }
+    const second = this.#tokens.shift();
+    if (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;
+  }
+}
+class ApiModelTransforms {
+  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 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 this.makeComponentMember(member, ret, props);
+      }
+    } else if (declStart === "() => ") {
+      const ret = tokens.getComponentReturnTokens();
+      if (ret) {
+        return this.makeComponentMember(member, ret);
+      }
+    }
+    return member;
+  };
+  static makeComponentMember(member, ret, props) {
+    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: member.docComment ?? "",
+      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
+    };
+  }
+  static 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
+      ])
+    );
+  }
+  class DocFrontMatter extends tsdoc.DocNode {
+    static kind = "DocFrontMatter";
+    values;
+    constructor(parameters) {
+      super(parameters);
+      this.values = parameters.values;
+    }
+    /** @override */
+    get kind() {
+      return DocFrontMatter.kind;
+    }
+  }
+  class DocCodeSpanLink extends tsdoc.DocLinkTag {
+    static kind = "DocCodeSpanLink";
+    /** @override */
+    get kind() {
+      return DocCodeSpanLink.kind;
+    }
+  }
+  class CustomCustomMarkdownEmitter extends CustomMarkdownEmitter.CustomMarkdownEmitter {
+    // Until https://github.com/microsoft/rushstack/issues/2914 gets fixed or we change markdown renderer we need a fix
+    // to render pipe | character correctly.
+    getEscapedText(text) {
+      return text.replace(/\\/g, "\\\\").replace(/[*#[\]_`~]/g, (x) => `\\${x}`).replace(/---/g, "\\-\\-\\-").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/\|/g, "&#124;");
+    }
+    /** @override */
+    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}: "${String(value).replace(/\"/g, "")}"`
+              );
+            }
+          }
+          context.writer.writeLine("---");
+          context.writer.writeLine();
+          break;
+        }
+        case "BlockTag": {
+          const node = docNode;
+          if (node.tagName === "@config") {
+            context.writer.writeLine("## Related config ");
+          }
+          break;
+        }
+        case DocCodeSpanLink.kind: {
+          const node = docNode;
+          if (node.codeDestination) {
+            super.writeLinkTagWithCodeDestination(node, context);
+          } else if (node.urlDestination) {
+            const linkText = node.linkText !== void 0 ? node.linkText : node.urlDestination;
+            const encodedLinkText = this.getEscapedText(
+              linkText.replace(/\s+/g, " ")
+            );
+            context.writer.write("[");
+            context.writer.write(`\`${encodedLinkText}\``);
+            context.writer.write(`](${node.urlDestination})`);
+          } else if (node.linkText) {
+            this.writePlainText(node.linkText, context);
+          }
+          break;
+        }
+        default:
+          super.writeNode(docNode, context, docNodeSiblings);
+      }
+    }
+    /** @override */
+    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.registerDocNodes("@backstage/docs", [
+        { docNodeKind: DocCodeSpanLink.kind, constructor: DocCodeSpanLink }
+      ]);
+      this._tsdocConfiguration.docNodeManager.registerAllowableChildren("Paragraph", [
+        DocFrontMatter.kind,
+        DocCodeSpanLink.kind
+      ]);
+      const def = {
+        tagName: "@config",
+        syntaxKind: tsdoc.TSDocTagSyntaxKind.BlockTag,
+        tagNameWithUpperCase: "@CONFIG",
+        standardization: tsdoc.Standardization.Extended,
+        allowMultiple: false
+      };
+      this._tsdocConfiguration.addTagDefinition(def);
+      this._tsdocConfiguration.setSupportForTag(
+        def,
+        true
+      );
+      this._markdownEmitter = new CustomCustomMarkdownEmitter(newModel);
+    }
+    _getFilenameForApiItem(apiItem) {
+      const filename = super._getFilenameForApiItem(apiItem);
+      if (filename.includes(".html.")) {
+        return filename.replace(/\.html\./g, "._html.");
+      }
+      return filename;
+    }
+    // We don't really get many chances to modify the generated AST
+    // so we hook in wherever we can. In this case we add the front matter
+    // just before writing the breadcrumbs at the top.
+    /** @override */
+    _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
+          }
+        })
+      );
+      const configuration = this._tsdocConfiguration;
+      output.appendNodeInParagraph(
+        new tsdoc.DocLinkTag({
+          configuration,
+          tagName: "@link",
+          linkText: "Home",
+          urlDestination: this._getLinkFilenameForApiItem(this._apiModel)
+        })
+      );
+      for (const hierarchyItem of apiItem.getHierarchy()) {
+        switch (hierarchyItem.kind) {
+          case apiExtractorModel.ApiItemKind.Model:
+          case apiExtractorModel.ApiItemKind.EntryPoint:
+            break;
+          default:
+            output.appendNodesInParagraph([
+              new tsdoc.DocPlainText({
+                configuration,
+                text: " > "
+              }),
+              new DocCodeSpanLink({
+                configuration,
+                tagName: "@link",
+                linkText: hierarchyItem.displayName,
+                urlDestination: this._getLinkFilenameForApiItem(hierarchyItem)
+              })
+            ]);
+        }
+      }
+      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",
+      // De ba dålig kod
+      configFilePath: "",
+      configFile: {}
+    },
+    outputFolder: outputDir
+  });
+  await fs__default.default.remove(outputDir);
+  await fs__default.default.ensureDir(outputDir);
+  documenter.generateFiles();
+}
+
+exports.buildDocs = buildDocs;
+//# sourceMappingURL=buildDocs.cjs.js.map

package/dist/commands/api-reports/api-reports/createTemporaryTsConfig.cjs.js

@@ -0,0 +1,37 @@
+'use strict';
+
+var fs = require('fs-extra');
+var path = require('path');
+var paths = require('../../../lib/paths.cjs.js');
+
+function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e : { default: e }; }
+
+var fs__default = /*#__PURE__*/_interopDefaultCompat(fs);
+
+async function createTemporaryTsConfig(includedPackageDirs) {
+  const path$1 = paths.paths.resolveTargetRoot("tsconfig.tmp.json");
+  process.once("exit", () => {
+    fs__default.default.removeSync(path$1);
+  });
+  let assetTypeFile = [];
+  try {
+    assetTypeFile = [
+      require.resolve("@backstage/cli/asset-types/asset-types.d.ts")
+    ];
+  } catch {
+  }
+  await fs__default.default.writeJson(path$1, {
+    extends: "./tsconfig.json",
+    include: [
+      // These two contain global definitions that are needed for stable API report generation
+      ...assetTypeFile,
+      ...includedPackageDirs.map((dir) => path.join(dir, "src"))
+    ],
+    // we don't exclude node_modules so that we can use the asset-types.d.ts file
+    exclude: []
+  });
+  return path$1;
+}
+
+exports.createTemporaryTsConfig = createTemporaryTsConfig;
+//# sourceMappingURL=createTemporaryTsConfig.cjs.js.map

package/dist/commands/api-reports/{generateTypeDeclarations.cjs.js → api-reports/generateTypeDeclarations.cjs.js}

@@ -2,7 +2,7 @@
 
 var fs = require('fs-extra');
 var child_process = require('child_process');
-var paths = require('../../lib/paths.cjs.js');
+var paths = require('../../../lib/paths.cjs.js');
 
 function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e : { default: e }; }
 

package/dist/commands/api-reports/api-reports/patchApiReportGeneration.cjs.js

@@ -0,0 +1,95 @@
+'use strict';
+
+var tryRunPrettier = require('../common/tryRunPrettier.cjs.js');
+
+let applied = false;
+function patchApiReportGeneration() {
+  if (applied) {
+    return;
+  }
+  applied = true;
+  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) => {
+          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}"`
+            );
+          }
+          let localName = sourceFile.identifiers?.get(symbolName);
+          if (!localName) {
+            const [, trimmedSymbolName] = symbolName.match(/(.*)_\d+/) || [];
+            localName = sourceFile.identifiers?.get(
+              trimmedSymbolName
+            );
+          }
+          if (!localName) {
+            throw new Error(
+              `Unable to find local name of "${symbolName}" in ${sourceFile.fileName}`
+            );
+          }
+          const local = sourceFile.locals?.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 = type.aliasSymbol?.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?.tagName.text === "ignore");
+          });
+          return !isIgnored;
+        });
+      }
+    );
+    const content = originalGenerateReviewFileContent.call(
+      this,
+      collector,
+      ...moreArgs
+    );
+    return tryRunPrettier.tryRunPrettier(content);
+  };
+}
+
+exports.patchApiReportGeneration = patchApiReportGeneration;
+//# sourceMappingURL=patchApiReportGeneration.cjs.js.map