docs: various improvements and fixes (#14257)

www/utils/packages/typedoc-config/tsdoc.json

@@ -73,6 +73,10 @@
     {
       "tagName": "@workflowEvent",
       "syntaxKind": "block"
+    },
+    {
+      "tagName": "@workflowLock",
+      "syntaxKind": "block"
     }
   ]
 }

www/utils/packages/typedoc-plugin-markdown-medusa/src/render-utils.ts

@@ -195,12 +195,12 @@ export function registerHelpers(theme: MarkdownTheme) {
   signatureCommentHelper()
   versionHelper()
   sourceCodeLinkHelper()
-  workflowExamplesHelper(theme)
+  workflowExamplesHelper()
   stepExamplesHelper()
   ifEventsReferenceHelper(theme)
   eventsListingHelper()
   workflowEventsHelper()
   getAllChildrenHelper(theme)
   reflectionBadgesHelper()
-  workflowNotes(theme)
+  workflowNotes()
 }

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/comments.ts

@@ -11,6 +11,7 @@ const EXCLUDED_TAGS = [
   "@tags",
   "@summary",
   "@workflowEvent",
+  "@workflowLock",
 ]
 
 export default function () {

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-examples.ts

@@ -2,27 +2,26 @@ import Handlebars from "handlebars"
 import { DeclarationReflection, SignatureReflection } from "typedoc"
 import { getReflectionTypeFakeValueStr, getWorkflowInputType } from "utils"
 import beautifyCode from "../../utils/beautify-code.js"
-import { MarkdownTheme } from "../../theme.js"
-import { getPageFrontmatter } from "../../utils/frontmatter.js"
 
-export default function (theme: MarkdownTheme) {
+export default function () {
   Handlebars.registerHelper(
     "workflowExamples",
     function (this: SignatureReflection): string {
-      const frontmatter = getPageFrontmatter({
-        frontmatterData:
-          theme.getFormattingOptionsForLocation().frontmatterData,
-        reflection: this,
-      })
-      const hasLocking =
-        frontmatter?.tags?.some((tag) => {
-          return typeof tag === "string"
-            ? tag === "locking"
-            : tag.name === "locking"
-        }) ?? false
       const workflowReflection = this.parent
-      const exampleStr: string[] = []
+      // prepare locking data
+      const workflowLockingTag = workflowReflection.comment?.blockTags.find(
+        (tag) => tag.tag === "@workflowLock"
+      )
+      const workflowLockingContentSplit =
+        workflowLockingTag?.content[0]?.text.split("---")
+      const lockingData = workflowLockingContentSplit
+        ? {
+            step: workflowLockingContentSplit[1].trim(),
+            key: workflowLockingContentSplit[0].trim(),
+          }
+        : undefined
 
+      const exampleStr: string[] = []
       const exampleTags = workflowReflection.comment?.blockTags.filter(
         (tag) => tag.tag === "@example"
       )
@@ -32,7 +31,7 @@ export default function (theme: MarkdownTheme) {
           getExecutionCodeTabs({
             exampleCode: generateWorkflowExample(workflowReflection),
             workflowName: workflowReflection.name,
-            hasLocking,
+            locking: lockingData,
           })
         )
       } else {
@@ -56,7 +55,7 @@ export default function (theme: MarkdownTheme) {
               getExecutionCodeTabs({
                 exampleCode: part.text,
                 workflowName: workflowReflection.name,
-                hasLocking,
+                locking: lockingData,
               })
             )
           })
@@ -73,11 +72,14 @@ export default function (theme: MarkdownTheme) {
 function getExecutionCodeTabs({
   exampleCode,
   workflowName,
-  hasLocking,
+  locking,
 }: {
   exampleCode: string
   workflowName: string
-  hasLocking: boolean
+  locking?: {
+    step: string
+    key: string
+  }
 }): string {
   exampleCode = exampleCode.replace("```ts\n", "").replace("\n```", "")
 
@@ -156,13 +158,19 @@ import { ${workflowName} } from "@medusajs/medusa/core-flows"
 
 const myWorkflow = createWorkflow(
   "my-workflow",
-  () => {${hasLocking ? "\n    // Acquire lock from nested workflow here" : ""}
+  () => {${
+    locking
+      ? `\n    // Acquire lock from nested workflow here\n    // ${locking.step}`
+      : ""
+  }
     ${exampleCode
       .replace(`{ result }`, "result")
       .replace(`await `, "")
       .replace(`(container)`, "")
       .replace(".run(", ".runAsStep(")}${
-      hasLocking ? "\n    // Release lock here" : ""
+      locking
+        ? `\n    // Release lock here\n    // releaseLockStep({ key: ${locking.key} })`
+        : ""
     }
   }
 )`)}

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-notes.ts

@@ -1,24 +1,14 @@
 import Handlebars from "handlebars"
 import { SignatureReflection } from "typedoc"
-import { MarkdownTheme } from "../../theme.js"
-import { getPageFrontmatter } from "../../utils/frontmatter.js"
 
-export default function (theme: MarkdownTheme) {
+export default function () {
   Handlebars.registerHelper(
     "workflowNotes",
     function (this: SignatureReflection): string {
       const notes: string[] = []
-      const frontmatter = getPageFrontmatter({
-        frontmatterData:
-          theme.getFormattingOptionsForLocation().frontmatterData,
-        reflection: this,
-      })
-      const hasLocking =
-        frontmatter?.tags?.some((tag) => {
-          return typeof tag === "string"
-            ? tag === "locking"
-            : tag.name === "locking"
-        }) ?? false
+      const hasLocking = this.parent.comment?.blockTags.some(
+        (tag) => tag.tag === "@workflowLock"
+      )
 
       if (hasLocking) {
         notes.push(

www/utils/packages/typedoc-plugin-workflows/src/plugin.ts

@@ -149,7 +149,7 @@ class WorkflowsPlugin {
       }
     }
 
-    this.handleAddTagsAfterParsing(context)
+    this.addTagsAfterParsingWorkflows(context)
   }
 
   /**
@@ -242,6 +242,10 @@ class WorkflowsPlugin {
 
     this.updateWorkflowsTagsMap(workflowId, uniqueResources)
     this.attachEvents(parentReflection)
+    this.attachLocksInWorkflow({
+      workflowReflection: parentReflection,
+      context,
+    })
   }
 
   /**
@@ -843,7 +847,7 @@ class WorkflowsPlugin {
     this.workflowsTagsMap.set(workflowId, existingItems)
   }
 
-  handleAddTagsAfterParsing(context: Context) {
+  addTagsAfterParsingWorkflows(context: Context) {
     let keys = Object.keys(this.addTagsAfterParsing)
 
     const handleForWorkflow = (
@@ -960,6 +964,89 @@ class WorkflowsPlugin {
       })
     )
   }
+
+  attachLocksInWorkflow({
+    workflowReflection,
+    context,
+  }: {
+    workflowReflection: DeclarationReflection
+    context: Context
+  }) {
+    const { initializer: workflowInitializer } =
+      this.helper.getReflectionSymbolAndInitializer({
+        project: context.project,
+        reflection: workflowReflection,
+      }) || {}
+    // check if the workflow acquires a lock
+    // for simplicity we'll assume the workflow acquires a lock
+    // with acquireLockStep only once
+    const checkHasAcquireLockStep = (
+      documents: DocumentReflection[]
+    ): boolean => {
+      return documents.some((child) => {
+        if (child.name === "acquireLockStep") {
+          return true
+        }
+
+        if (child.children) {
+          return checkHasAcquireLockStep(child.children)
+        }
+      })
+    }
+
+    if (workflowReflection.name === "completeCartWorkflow") {
+      console.log("here")
+    }
+    const hasAcquireLockStep = checkHasAcquireLockStep(
+      workflowReflection.documents || []
+    )
+
+    if (!hasAcquireLockStep) {
+      return
+    }
+
+    // use regex to get acquireLockStep call
+    const workflowText = workflowInitializer
+      ? workflowInitializer.getText()
+      : ""
+
+    const acquireLockStepRegex = /acquireLockStep\s*\(\s*\{[\s\S]*?\}\s*\)/g
+
+    // catch one match only
+    const match = acquireLockStepRegex.exec(workflowText)
+
+    if (!match) {
+      return
+    }
+
+    // remove extra spaces after new lines
+    const acquireLockStepCall = match[0]
+      .replace(/\n\s\s/g, "")
+      .replace(/\s{2,}/g, "  ")
+
+    // extract the key
+    const keyRegex = /key:\s*([^,}\n]+)/g
+    const keyMatch = keyRegex.exec(acquireLockStepCall)
+
+    if (!keyMatch) {
+      return
+    }
+
+    const lockKey = keyMatch[1].trim()
+
+    const comment = workflowReflection.comment || new Comment()
+
+    comment.blockTags.push(
+      new CommentTag(`@workflowLock`, [
+        {
+          kind: "text",
+          text: `${lockKey} --- ${acquireLockStepCall}`,
+        },
+      ])
+    )
+
+    workflowReflection.comment = comment
+  }
 }
 
 export default WorkflowsPlugin