Migrate API Doc Preview

.github/shared/cmd/api-doc-preview.js

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+// @ts-check
+
+import { mkdir, writeFile } from "fs/promises";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+import { parseArgs } from "util";
+
+import { getChangedFilesStatuses, swagger } from "../src/changed-files.js";
+
+import {
+  getSwaggersToProcess,
+  indexMd,
+  mappingJSONTemplate,
+  repoJSONTemplate,
+} from "../src/doc-preview.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+function usage() {
+  console.log(`Usage:
+npx api-doc-preview --output <output-dir>
+
+parameters:
+  --output <output-dir>       Directory to write documentation artifacts to.
+  --build-id <build-id>       Build ID, used in the documentation index. Defaults to BUILD_BUILDID environment variable.
+  --spec-repo-name <name>     Name of the repository containing the swagger files of the form <org>/<repo-name>. Defaults to BUILD_REPOSITORY_NAME environment variable.
+  --spec-repo-pr-number <pr-number>  PR number of the repository containing the swagger files. Defaults to SYSTEM_PULLREQUEST_PULLREQUESTNUMBER environment variable.
+  --spec-repo-root <path>     Root path of the repository containing the swagger files. Defaults to the root of the repository containing this script.`);
+}
+
+const {
+  values: {
+    output: outputDir,
+    "build-id": buildId,
+    "spec-repo-name": specRepoName,
+    "spec-repo-pr-number": specRepoPrNumber,
+    "spec-repo-root": specRepoRoot,
+  },
+} = parseArgs({
+  options: {
+    output: { type: "string", default: "" },
+    "build-id": {
+      type: "string",
+      default: process.env.BUILD_BUILDID || "",
+    },
+    "spec-repo-name": {
+      type: "string",
+      default: process.env.BUILD_REPOSITORY_NAME || "",
+    },
+    "spec-repo-pr-number": {
+      type: "string",
+      default: process.env.SYSTEM_PULLREQUEST_PULLREQUESTNUMBER || "",
+    },
+    "spec-repo-root": {
+      type: "string",
+      default: resolve(__dirname, "../../../"),
+    },
+  },
+  allowPositionals: false,
+});
+
+let validArgs = true;
+
+if (!outputDir) {
+  console.log(`Missing required parameter --output. Value given: ${outputDir || "<empty>"}`);
+  validArgs = false;
+}
+
+if (!specRepoName) {
+  console.log(
+    `Missing required parameter --spec-repo-name. Value given: ${specRepoName || "<empty>"}`,
+  );
+  validArgs = false;
+}
+
+if (!specRepoPrNumber) {
+  console.log(
+    `Missing required parameter --spec-repo-pr-number. Value given: ${specRepoPrNumber || "<empty>"}`,
+  );
+  validArgs = false;
+}
+
+if (!specRepoRoot) {
+  console.log(`Invalid parameter --spec-repo-root. Value given: ${specRepoRoot || "<empty>"}`);
+  validArgs = false;
+}
+
+if (!validArgs) {
+  usage();
+  process.exit(1);
+}
+
+// Get selected version and swaggers to process
+
+const changedFileStatuses = await getChangedFilesStatuses({
+  cwd: specRepoRoot,
+  paths: ["specification"],
+});
+
+// Exclude deleted files as they are not relevant for generating documentation.
+const changedFiles = [
+  ...changedFileStatuses.additions,
+  ...changedFileStatuses.modifications,
+  // Current names of renamed files are interesting, previous names are not.
+  ...changedFileStatuses.renames.map((r) => r.to),
+];
+console.log(`Found ${changedFiles.length} relevant changed files in ${specRepoRoot}`);
+console.log("Changed files:");
+changedFiles.forEach((file) => console.log(`  - ${file}`));
+const swaggerPaths = changedFiles.filter(swagger);
+
+if (swaggerPaths.length === 0) {
+  console.log("No eligible swagger files found. No documentation artifacts will be written.");
+  process.exit(0);
+}
+
+const { selectedVersion, swaggersToProcess } = getSwaggersToProcess(swaggerPaths);
+
+const repoName = specRepoName;
+const prNumber = specRepoPrNumber;
+
+await mkdir(outputDir, { recursive: true });
+await writeFile(
+  join(outputDir, "repo.json"),
+  JSON.stringify(repoJSONTemplate(repoName, prNumber), null, 2),
+);
+await writeFile(
+  join(outputDir, "mapping.json"),
+  JSON.stringify(mappingJSONTemplate(swaggersToProcess), null, 2),
+);
+await writeFile(join(outputDir, "index.md"), indexMd(buildId, repoName, prNumber));
+console.log(`Documentation preview artifacts written to ${outputDir}`);
+
+console.log(`Doc preview for API version ${selectedVersion} includes:`);
+swaggersToProcess.forEach((swagger) => console.log(`  - ${swagger}`));
+console.log(`Artifacts written to: ${outputDir}`);

.github/shared/package.json

@@ -1,3 +1,3 @@
 {
   "name": "@azure-tools/specs-shared",
   "private": "true",
@@ -23,7 +23,8 @@
     "./test/examples": "./test/examples.js"
   },
   "bin": {
-    "spec-model": "./cmd/spec-model.js"
+    "spec-model": "./cmd/spec-model.js",
+    "api-doc-preview": "./cmd/api-doc-preview.js"
   },
   "_comments": {
     "dependencies": "Runtime dependencies must be kept to an absolute minimum for performance, ideally with no transitive dependencies",

.github/shared/src/changed-files.js

@@ -1,3 +1,3 @@
 // @ts-check
 
 import debug from "debug";
@@ -8,6 +8,8 @@
 debug.enable("simple-git");
 
 /**
+ * Get a list of changed files in a git repository
+ *
  * @param {Object} [options]
  * @param {string} [options.baseCommitish] Default: "HEAD^".
  * @param {string} [options.cwd] Current working directory.  Default: process.cwd().
@@ -32,7 +34,6 @@
   const result = await simpleGit(cwd).diff(["--name-only", baseCommitish, headCommitish, ...paths]);
 
   const files = result.trim().split("\n");
-
   logger?.info("Changed Files:");
   for (const file of files) {
     logger?.info(`  ${file}`);
@@ -43,6 +44,10 @@
 }
 
 /**
+ * Get a list of changed files in a git repository with statuses for additions,
+ * modifications, deletions, and renames. Warning: rename behavior can vary
+ * based on the git client's configuration of diff.renames.
+ *
  * @param {Object} [options]
  * @param {string} [options.baseCommitish] Default: "HEAD^".
  * @param {string} [options.cwd] Current working directory.  Default: process.cwd().
@@ -210,6 +215,14 @@
   );
 }
 
+/**
+ * @param {string} [file]
+ * @returns {boolean}
+ */
+export function quickstartTemplate(file) {
+  return typeof file === "string" && json(file) && file.includes("/quickstart-templates/");
+}
+
 /**
  * @param {string} [file]
  * @returns {boolean}
@@ -220,6 +233,7 @@
     json(file) &&
     (dataPlane(file) || resourceManager(file)) &&
     !example(file) &&
+    !quickstartTemplate(file) &&
     !scenario(file)
   );
 }

.github/shared/src/doc-preview.js

@@ -0,0 +1,167 @@
+// @ts-check
+const DOCS_NAMESPACE = "_swagger_specs";
+const SPEC_FILE_REGEX =
+  "(specification/)+(.*)/(resourcemanager|resource-manager|dataplane|data-plane|control-plane)/(.*)/(preview|stable|privatepreview)/(.*?)/(example)?(.*)";
+
+/**
+ * @typedef {Object} SwaggerFileMetadata
+ * @property {string} path
+ * @property {string} serviceName
+ * @property {string} serviceType
+ * @property {string} resourceProvider
+ * @property {string} releaseState
+ * @property {string} apiVersion
+ * @property {string} fileName
+ */
+
+/**
+ * @typedef {Object} RepoJSONTemplate
+ * @property {Object[]} repo
+ * @property {string} repo[].url
+ * @property {string} repo[].prNumber
+ * @property {string} repo[].name
+ */
+
+/**
+ * @typedef {Object} MappingJSONStructure
+ * @property {string} target_api_root_dir
+ * @property {boolean} enable_markdown_fragment
+ * @property {string} markdown_fragment_folder
+ * @property {boolean} use_yaml_toc
+ * @property {boolean} formalize_url
+ * @property {string[]} version_list
+ * @property {Object[]} organizations
+ * @property {string} organizations[].index
+ * @property {string} organizations[].default_toc_title
+ * @property {string} organizations[].version
+ * @property {Object[]} organizations[].services
+ * @property {string} organizations[].services[].toc_title
+ * @property {string} organizations[].services[].url_group
+ * @property {Object[]} organizations[].services[].swagger_files
+ * @property {string} organizations[].services[].swagger_files[].source
+ */
+
+/**
+ * Extract swagger file metadata from path.
+ * @param {string} specPath
+ * @returns {SwaggerFileMetadata}
+ */
+export function parseSwaggerFilePath(specPath) {
+  const m = specPath.match(SPEC_FILE_REGEX);
+  if (!m) {
+    throw new Error(`Path "${specPath}" does not match expected swagger file pattern.`);
+  }
+  const [path, , serviceName, serviceType, resourceProvider, releaseState, apiVersion, , fileName] =
+    m;
+  return {
+    path,
+    serviceName,
+    serviceType,
+    resourceProvider,
+    releaseState,
+    apiVersion,
+    fileName,
+  };
+}
+
+/**
+ * @param {string} repoName
+ * @param {string} prNumber
+ * @returns {object}
+ */
+export function repoJSONTemplate(repoName, prNumber) {
+  return {
+    repo: [
+      {
+        url: `https://github.com/${repoName}`,
+        prNumber: prNumber,
+        name: DOCS_NAMESPACE,
+      },
+    ],
+  };
+}
+
+/**
+ * @param {string[]} files
+ * @returns {MappingJSONStructure}
+ */
+export function mappingJSONTemplate(files) {
+  return {
+    target_api_root_dir: "structured",
+    enable_markdown_fragment: true,
+    markdown_fragment_folder: "authored",
+    use_yaml_toc: true,
+    formalize_url: true,
+    version_list: ["default"],
+    organizations: [
+      {
+        index: "index.md",
+        default_toc_title: "Getting Started",
+        version: "default",
+        services: [
+          {
+            toc_title: "Documentation Preview",
+            url_group: "documentation-preview",
+            swagger_files: files.map((source) => ({
+              source: `${DOCS_NAMESPACE}/${source}`,
+            })),
+          },
+        ],
+      },
+    ],
+  };
+}
+
+/**
+ * @param {string} buildId
+ * @param {string} repoName
+ * @param {string} prNumber
+ * @returns {string}
+ */
+export function indexMd(buildId, repoName, prNumber) {
+  return `# Documentation Preview for swagger pipeline build #${buildId}
+
+Welcome to documentation preview for ${repoName}/pull/${prNumber} 
+created via the swagger pipeline.
+
+Your documentation may be viewed in the menu on the left hand side.
+
+If you have issues around documentation generation, please feel free to contact 
+us in the [Docs Support Teams Channel](https://aka.ms/ci-fix/api-docs-help)`;
+}
+
+/**
+ * Given a list of changed swagger files, select an API version and a list of
+ * swagger files in that API version to process.
+ * @param {string[]} swaggerFiles
+ **/
+export function getSwaggersToProcess(swaggerFiles) {
+  const swaggerFileObjs = swaggerFiles.map(parseSwaggerFilePath);
+
+  const versions = swaggerFileObjs.map((obj) => obj.apiVersion).filter(Boolean);
+  if (versions.length === 0) {
+    throw new Error("No new API versions found in eligible swagger files.");
+  }
+  const uniqueVersions = Array.from(new Set(versions));
+
+  let selectedVersion;
+  if (uniqueVersions.length === 1) {
+    selectedVersion = uniqueVersions[0];
+    console.log(`Single API version found: ${selectedVersion}`);
+  } else {
+    // This sorting logic is ported from the original code which sorts only the
+    // strings and doesn't attempt to parse versions for more semantically-aware
+    // sorting.
+    const sortedVersions = [...uniqueVersions].sort();
+    selectedVersion = sortedVersions[sortedVersions.length - 1];
+    console.log(
+      `Multiple API versions found: ${JSON.stringify(sortedVersions)}. Selected version: ${selectedVersion}`,
+    );
+  }
+
+  const swaggersToProcess = swaggerFileObjs
+    .filter((obj) => obj.apiVersion === selectedVersion)
+    .map((obj) => obj.path);
+
+  return { selectedVersion, swaggersToProcess };
+}