docs: change process for generating docblocks through actions (#6237)

This PR changes the original process of generating docblocks through actions. The process now is:

1. When a PR is merged for the branch `changeset-release/develop`, the docblock generator tool us used to generate docblocks for the changed files. The changed files are determined by retrieving all comments since the last release and the files in each of those commits.
2. If there are changes after using the docblock generator tool, a PR is opened in the branch `chore/generate-tsdocs`.
3. Once the `chore/generate-tsdocs` is merged, it triggers an action that generates the references for the docs. This changes the previous behaviour of generating references on a new release.

Both actions (that runs the docblock generator tool and that generates references for the docs) can also be triggered manually.

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

docs-util/packages/docblock-generator/src/classes/git-manager.ts

@@ -0,0 +1,75 @@
+import { Octokit } from "octokit"
+
+type Options = {
+  owner?: string
+  repo?: string
+  authToken?: string
+}
+
+export class GitManager {
+  private owner: string
+  private repo: string
+  private authToken: string
+  private octokit: Octokit
+  private gitApiVersion = "2022-11-28"
+
+  constructor(options?: Options) {
+    this.owner = options?.owner || process.env.GIT_OWNER || ""
+    this.repo = options?.repo || process.env.GIT_REPO || ""
+    this.authToken = options?.authToken || process.env.GITHUB_TOKEN || ""
+
+    this.octokit = new Octokit({
+      auth: this.authToken,
+    })
+  }
+
+  async getCommitFilesSinceLastRelease() {
+    // list releases to get the latest two releases
+    const { data: release } = await this.octokit.request(
+      "GET /repos/{owner}/{repo}/releases/latest",
+      {
+        owner: this.owner,
+        repo: this.repo,
+        headers: {
+          "X-GitHub-Api-Version": this.gitApiVersion,
+        },
+      }
+    )
+
+    // get commits between the last two releases
+    const commits = await this.octokit.paginate(
+      "GET /repos/{owner}/{repo}/commits",
+      {
+        owner: this.owner,
+        repo: this.repo,
+        since: release.published_at || undefined,
+        per_page: 100,
+      }
+    )
+
+    // get files of each of the commits
+    const files = new Set<string>()
+
+    await Promise.all(
+      commits.map(async (commit) => {
+        const {
+          data: { files: commitFiles },
+        } = await this.octokit.request(
+          "GET /repos/{owner}/{repo}/commits/{ref}",
+          {
+            owner: this.owner,
+            repo: this.repo,
+            ref: commit.sha,
+            headers: {
+              "X-GitHub-Api-Version": this.gitApiVersion,
+            },
+          }
+        )
+
+        commitFiles?.forEach((commitFile) => files.add(commitFile.filename))
+      })
+    )
+
+    return [...files]
+  }
+}

docs-util/packages/docblock-generator/src/commands/run-release.ts

@@ -0,0 +1,38 @@
+import filterFiles from "../utils/filter-files.js"
+import path from "path"
+import DocblockGenerator from "../classes/docblock-generator.js"
+import getMonorepoRoot from "../utils/get-monorepo-root.js"
+import { GitManager } from "../classes/git-manager.js"
+
+export default async function () {
+  const gitManager = new GitManager()
+
+  console.log("Get files in commits since last release")
+
+  const files = await gitManager.getCommitFilesSinceLastRelease()
+
+  // filter changed files
+  let filteredFiles = filterFiles(files)
+
+  if (!filteredFiles.length) {
+    console.log("No applicable files changed. Canceling...")
+    return
+  }
+
+  console.log(
+    `${filteredFiles.length} files have changed. Running generator on them...`
+  )
+
+  filteredFiles = filteredFiles.map((filePath) =>
+    path.resolve(getMonorepoRoot(), filePath)
+  )
+
+  // generate docblocks for each of the files.
+  const docblockGenerator = new DocblockGenerator({
+    paths: filteredFiles,
+  })
+
+  await docblockGenerator.run()
+
+  console.log(`Finished generating docs for ${filteredFiles.length} files.`)
+}

docs-util/packages/docblock-generator/src/index.ts

@@ -4,6 +4,7 @@ import { Command } from "commander"
 import run from "./commands/run.js"
 import runGitChanges from "./commands/run-git-changes.js"
 import runGitCommit from "./commands/run-git-commit.js"
+import runRelease from "./commands/run-release.js"
 
 const program = new Command()
 
@@ -30,4 +31,11 @@ program
   .argument("<commitSha>", "The SHA of a commit.")
   .action(runGitCommit)
 
+program
+  .command("run:release")
+  .description(
+    "Generate TSDoc doc-blocks for files part of the latest release. It will retrieve the files of commits between the latest two releases."
+  )
+  .action(runRelease)
+
 program.parse()