docs-util: fix release scripts (#6353)

- Fix GitHub action to run on push and check if the commit message is "chore: Release". Only then are TSDocs generated and a PR is opened.
- Add an option to pass to the `run:release` method of the docblock generator a release tag. This is helpful in cases when the GitHub action fails for any reason.
- Add scripts that checks the message of a commit.

.github/workflows/generate-docblocks.yml

@@ -1,16 +1,13 @@
 name: Generate Docblocks [Automated]
 
 on:
-  pull_request:
+  push:
     branches:
       - develop
-    types:
-      - closed
   workflow_dispatch:
 
 jobs:
   generate:
-    if: github.event_name == 'workflow_dispatch' || (startsWith(github.head_ref, 'changeset-release/develop') && github.event.pull_request.merged == true)
     name: Generated TSDoc PRs
     runs-on: ubuntu-latest
     steps:
@@ -33,7 +30,17 @@ jobs:
         run: yarn build
         working-directory: docs-util
       
+      - name: Check Commit
+        id: check-commit
+        run: 'yarn check:release-commit ${{ github.sha }}'
+        working-directory: docs-util/packages/scripts
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GIT_OWNER: ${{ github.repository_owner }}
+          GIT_REPO: medusa
+
       - name: Run docblock generator
+        if: steps.check-commit.outputs.is_release_commit == true
         run: "yarn start run:release"
         working-directory: docs-util/packages/docblock-generator
         env:
@@ -42,6 +49,7 @@ jobs:
           GIT_REPO: medusa
 
       - name: Create Pull Request
+        if: steps.check-commit.outputs.is_release_commit == true
         uses: peter-evans/create-pull-request@v5
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

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

@@ -26,6 +26,22 @@ export class GitManager {
     })
   }
 
+  async getCommitFilesSinceRelease(tagName: string) {
+    const { data: release } = await this.octokit.request(
+      "GET /repos/{owner}/{repo}/releases/tags/{tag}",
+      {
+        owner: this.owner,
+        repo: this.repo,
+        tag: tagName,
+        headers: {
+          "X-GitHub-Api-Version": this.gitApiVersion,
+        },
+      }
+    )
+
+    return this.getCommitsFiles(release.published_at)
+  }
+
   async getCommitFilesSinceLastRelease() {
     // list releases to get the latest two releases
     const { data: release } = await this.octokit.request(
@@ -39,13 +55,17 @@ export class GitManager {
       }
     )
 
+    return this.getCommitsFiles(release.published_at)
+  }
+
+  async getCommitsFiles(date?: string | null) {
     // 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,
+        since: date || undefined,
         per_page: 100,
       }
     )

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

@@ -4,12 +4,18 @@ 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 () {
+type Options = {
+  tag?: string
+}
+
+export default async function ({ tag }: Options) {
   const gitManager = new GitManager()
 
-  console.log("Get files in commits since last release")
+  console.log(`Get files in commits since ${tag || "last release"}`)
 
-  const files = await gitManager.getCommitFilesSinceLastRelease()
+  const files = tag
+    ? await gitManager.getCommitFilesSinceRelease(tag)
+    : await gitManager.getCommitFilesSinceLastRelease()
 
   // filter changed files
   let filteredFiles = filterFiles(files)

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

@@ -36,6 +36,10 @@ program
   .description(
     "Generate TSDoc doc-blocks for files part of the latest release. It will retrieve the files of commits between the latest two releases."
   )
+  .option(
+    "--tag <tag>",
+    "Specify a release tag to use rather than the latest release."
+  )
   .action(runRelease)
 
 program.parse()

docs-util/packages/scripts/check-release-commit.ts

@@ -0,0 +1,38 @@
+import { Octokit } from "@octokit/core"
+import * as core from "@actions/core"
+
+const commitSha = process.argv.length >= 3 ? process.argv[2] : null
+
+const octokit = new Octokit({
+  auth: process.env.GH_TOKEN,
+})
+
+async function checkReleaseCommit() {
+  if (!commitSha) {
+    throw new Error("Commit SHA is required.")
+  }
+
+  // retrieve commit by the SHA
+  const { data: commit } = await octokit.request(
+    "GET /repos/{owner}/{repo}/commits/{ref}",
+    {
+      owner: process.env.GIT_OWNER || "",
+      repo: process.env.GIT_REPO || "",
+      ref: commitSha,
+      headers: {
+        "X-GitHub-Api-Version": "2022-11-28",
+      },
+    }
+  )
+
+  if (!commit) {
+    throw new Error("Commit doesn't exist.")
+  }
+
+  core.setOutput(
+    "is_release_commit",
+    commit.commit.message === "chore: Release"
+  )
+}
+
+void checkReleaseCommit()

docs-util/packages/scripts/package.json

@@ -6,11 +6,13 @@
     "access": "public"
   },
   "scripts": {
+    "build": "tsc",
     "generate:announcement": "ts-node ./doc-change-release.ts",
     "generate:reference": "ts-node ./generate-reference.ts",
     "merge:references": "yarn generate:reference merge",
     "check:freshness": "ts-node ./freshness-check.ts",
-    "generate:message": "ts-node ./get-generate-diff-message.ts"
+    "generate:message": "ts-node ./get-generate-diff-message.ts",
+    "check:release-commit": "node ./dist/check-release-commit.js"
   },
   "version": "0.0.0",
   "type": "module",

docs-util/packages/scripts/tsconfig.json

@@ -4,6 +4,7 @@
     "outDir": "./dist",
     "module": "ESNext",
     "moduleResolution": "node",
+    "rootDir": ".",
   },
   "include": ["*.ts"],
   "ts-node": {