From fde85888bdc18d25c8511dc6151ff7ebcfb1546b Mon Sep 17 00:00:00 2001
From: Shahed Nasser <shahednasser@gmail.com>
Date: Mon, 7 Apr 2025 14:00:08 +0300
Subject: [PATCH] docs-util: handle workflows with intersection hook types
 (#12099)

---
 .../src/resources/helpers/workflow-hooks.ts   | 45 ++++++++++++-------
 .../typedoc-plugin-workflows/src/plugin.ts    | 33 +++++++++++---
 www/utils/packages/utils/src/hooks-util.ts    | 33 ++++++++++++++
 3 files changed, 87 insertions(+), 24 deletions(-)

diff --git a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-hooks.ts b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-hooks.ts
index c445c11143..ed0339e5d8 100644
--- a/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-hooks.ts
+++ b/www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-hooks.ts
@@ -1,7 +1,7 @@
 import { MarkdownTheme } from "../../theme.js"
 import Handlebars from "handlebars"
 import { DeclarationReflection, SignatureReflection } from "typedoc"
-import { cleanUpHookInput, getProjectChild } from "utils"
+import { cleanUpHookInput, getHookChildren, getProjectChild } from "utils"
 import beautifyCode from "../../utils/beautify-code.js"
 
 export default function (theme: MarkdownTheme) {
@@ -25,28 +25,39 @@ export default function (theme: MarkdownTheme) {
       Handlebars.helpers.incrementCurrentTitleLevel()
 
       const hooksTitleLevel = Handlebars.helpers.titleLevel()
-      const hookChildrenProperty = this.parent?.getChildByName("hooks")
-      const hookChildren =
-        hookChildrenProperty instanceof DeclarationReflection &&
-        hookChildrenProperty.type?.type === "reflection"
-          ? hookChildrenProperty.type.declaration.children || []
-          : []
+      const hookChildren = getHookChildren(this.parent)
 
       hooks.forEach((hook) => {
         const hookReflection =
-          hookChildren.find(
-            (child) => child.name === hook.name && child.signatures?.length
-          ) ||
+          hookChildren.find((child) => {
+            if (child.name !== hook.name) {
+              return false
+            }
+
+            if (child.signatures?.length) {
+              return true
+            }
+
+            return (
+              child.type?.type === "reflection" &&
+              child.type.declaration.signatures?.length
+            )
+          }) ||
           ((this.parent.getChildByName(hook.name) ||
-            getProjectChild(
-              theme.project!,
-              hook.name
-            )) as DeclarationReflection)
+            getProjectChild(theme.project!, hook.name)) as
+            | DeclarationReflection
+            | undefined)
+
+        const signatures =
+          hookReflection?.signatures ||
+          (hookReflection?.type?.type === "reflection"
+            ? hookReflection.type.declaration.signatures
+            : [])
 
         if (
           !hookReflection ||
-          !hookReflection.signatures?.length ||
-          !hookReflection.signatures[0].parameters?.length
+          !signatures?.length ||
+          !signatures[0].parameters?.length
         ) {
           return
         }
@@ -75,7 +86,7 @@ export default function (theme: MarkdownTheme) {
         str += `Handlers consuming this hook accept the following input.\n\n`
 
         str += Handlebars.helpers.parameterComponent.call(
-          cleanUpHookInput(hookReflection.signatures[0].parameters),
+          cleanUpHookInput(signatures[0].parameters),
           {
             hash: {
               sectionTitle: hook.name,
diff --git a/www/utils/packages/typedoc-plugin-workflows/src/plugin.ts b/www/utils/packages/typedoc-plugin-workflows/src/plugin.ts
index 2b5690d637..5f6959beff 100644
--- a/www/utils/packages/typedoc-plugin-workflows/src/plugin.ts
+++ b/www/utils/packages/typedoc-plugin-workflows/src/plugin.ts
@@ -493,12 +493,32 @@ class WorkflowsPlugin {
     workflowComments?: CommentTag[]
     workflowReflection: DeclarationReflection
   }): DeclarationReflection {
-    const declarationReflection = context.createDeclarationReflection(
-      ReflectionKind.Function,
-      undefined,
-      undefined,
-      stepId
-    )
+    const hooksProperty = workflowReflection.getChildByName("hooks")
+    let declarationReflection: DeclarationReflection | undefined
+    if (
+      hooksProperty?.isDeclaration() &&
+      hooksProperty.type?.type === "intersection"
+    ) {
+      hooksProperty.type.types.some((hookType) => {
+        if (hookType.type !== "reflection") {
+          return
+        }
+
+        declarationReflection = hookType.declaration.children?.find((child) => {
+          return child.name === stepId
+        })
+
+        return declarationReflection !== undefined
+      })
+    }
+    if (!declarationReflection) {
+      declarationReflection = context.createDeclarationReflection(
+        ReflectionKind.Function,
+        undefined,
+        undefined,
+        stepId
+      )
+    }
 
     declarationReflection.comment = new Comment()
 
@@ -579,7 +599,6 @@ class WorkflowsPlugin {
       ])
     )
 
-    const hooksProperty = workflowReflection.getChildByName("hooks")
     if (
       hooksProperty?.isDeclaration() &&
       hooksProperty.type?.type === "reflection"
diff --git a/www/utils/packages/utils/src/hooks-util.ts b/www/utils/packages/utils/src/hooks-util.ts
index 47246c3e12..87abd24eb1 100644
--- a/www/utils/packages/utils/src/hooks-util.ts
+++ b/www/utils/packages/utils/src/hooks-util.ts
@@ -5,6 +5,39 @@ import {
   Reflection,
 } from "typedoc"
 
+export function getHookChildren(
+  reflection?: DeclarationReflection
+): DeclarationReflection[] {
+  const hookChildren: DeclarationReflection[] = []
+  if (!reflection) {
+    return hookChildren
+  }
+
+  const hookChildrenProperty = reflection.getChildByName("hooks")
+  if (!(hookChildrenProperty instanceof DeclarationReflection)) {
+    return hookChildren
+  }
+
+  switch (hookChildrenProperty.type?.type) {
+    case "reflection":
+      hookChildren.push(
+        ...(hookChildrenProperty.type.declaration.children || [])
+      )
+      break
+    case "intersection":
+      hookChildrenProperty.type.types.forEach((type) => {
+        if (type.type !== "reflection") {
+          return
+        }
+
+        hookChildren.push(...(type.declaration.children || []))
+      })
+      break
+  }
+
+  return hookChildren
+}
+
 export function cleanUpHookInput(
   parameters: ParameterReflection[]
 ): ParameterReflection[] {