@itwin/build-tools/scripts/extract-api-summary.js

Bentley build tools

/*---------------------------------------------------------------------------------------------
* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
* See LICENSE.md in the project root for license terms and full copyright notice.
*--------------------------------------------------------------------------------------------*/

"use strict";

// The script parses api.md files, generated by the extract-api.js script (and subsequently the api-extractor.com tool), and extracts the high level API items
// into a csv format for easier review.

const path = require('path');
const argv = require("yargs").argv;
const fs = require("fs-extra");

if (undefined === argv.apiSignature) {
  console.log("Missing apiSignature argument.");
  return;
}

if (!fs.existsSync(argv.apiSignature)) {
  console.log("The api signature file does not exist.")
  return;
}

if (undefined === argv.outDir) {
  console.log("Missing outDir argument.");
  return;
}

fs.ensureDir(path.normalize(argv.outDir));

let shouldGenerateFullReport = false;
if (undefined !== argv.gatherFullReport)
  shouldGenerateFullReport = true;

// create output file
const apiSignatureFileName = path.parse(argv.apiSignature).name;
const sigFileName = apiSignatureFileName.substring(0, apiSignatureFileName.lastIndexOf('.'));
const sigFilePath = path.join(argv.outDir, `${shouldGenerateFullReport ? "summary" : sigFileName}.exports.csv`);

const outputLines = [];
if (shouldGenerateFullReport) {
  if (fs.existsSync(sigFilePath))
    outputLines.push("");
  else {
    outputLines.push("sep=;");
    outputLines.push("Package Name;Release Tag;API Item Type;API Item Name");
  }
} else {
  fs.createFileSync(sigFilePath);
  outputLines.push("sep=;");
  outputLines.push("Release Tag;API Item Type;API Item Name");
}

// Open up the signature file
fs.readFile(argv.apiSignature, function (error, data) {
  if (error) { throw error; }

  let previousLines = [];
  data.toString().split("\n").forEach(function (line, index, arr) {
    if (index === arr.length - 1 && line === "") { return; }

    if (previousLines.length !== 0) {
      const matches = line.match(/export.+?(class|interface|type|function|const|enum|namespace) (\w+)/);
      if (matches) {
        for (const previousLine of previousLines) {
          const line = `${previousLine};${matches[1]};${matches[2]}`;
          outputLines.push(shouldGenerateFullReport ? `${sigFileName};${line}` : line);
        }
      }

      previousLines = [];
      return;
    }

    let match = line.match(/\s@(beta|alpha|public|internal)/);
    if (null === match) {
      previousLines = [];
      return;
    }

    previousLines.push(match[1]);

    // handle deprecated and preview separately since they can be used together with the other release tags
    match = line.match(/\s@(deprecated|preview)/);
    if (null !== match) {
      previousLines.push(match[1]);
      return;
    }
  });

  shouldGenerateFullReport ? fs.appendFileSync(sigFilePath, outputLines.join("\n")) : fs.writeFileSync(sigFilePath, outputLines.join("\n"));
});