docs-util: infer resolved resources in workflow + steps (#10637)

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

@@ -4,7 +4,7 @@ import { stringify } from "yaml"
 import { replaceTemplateVariables } from "../../utils/reflection-template-strings"
 import { Reflection } from "typedoc"
 import { FrontmatterData } from "types"
-import { getTagComments, getTagsAsArray } from "utils"
+import { getTagComments, getTagsAsArray, getUniqueStrArray } from "utils"
 
 export default function (theme: MarkdownTheme) {
   Handlebars.registerHelper("frontmatter", function (this: Reflection) {
@@ -29,6 +29,11 @@ export default function (theme: MarkdownTheme) {
       const tagContent = getTagsAsArray(tag)
       resolvedFrontmatter["tags"]?.push(...tagContent)
     })
+    if (resolvedFrontmatter["tags"]?.length) {
+      resolvedFrontmatter["tags"] = getUniqueStrArray(
+        resolvedFrontmatter["tags"]
+      )
+    }
 
     return `---\n${stringify(resolvedFrontmatter).trim()}\n---\n\n`
   })

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

@@ -14,13 +14,21 @@ import {
 } from "typedoc"
 import ts, { SyntaxKind, VariableStatement } from "typescript"
 import { WorkflowManager, WorkflowDefinition } from "@medusajs/orchestration"
-import Helper from "./utils/helper"
-import { findReflectionInNamespaces, isWorkflow, isWorkflowStep } from "utils"
+import Helper, { WORKFLOW_AS_STEP_SUFFIX } from "./utils/helper"
+import {
+  findReflectionInNamespaces,
+  isWorkflow,
+  isWorkflowStep,
+  addTagsToReflection,
+  getResolvedResourcesOfStep,
+  getUniqueStrArray,
+} from "utils"
 import { StepType } from "./types"
 
 type ParsedStep = {
   stepReflection: DeclarationReflection
   stepType: StepType
+  resources: string[]
 }
 
 /**
@@ -30,10 +38,19 @@ type ParsedStep = {
 class WorkflowsPlugin {
   protected app: Application
   protected helper: Helper
+  protected workflowsTagsMap: Map<string, string[]>
+  protected addTagsAfterParsing: {
+    [k: string]: {
+      id: string
+      workflowIds: string[]
+    }
+  }
 
   constructor(app: Application) {
     this.app = app
     this.helper = new Helper()
+    this.workflowsTagsMap = new Map()
+    this.addTagsAfterParsing = {}
 
     this.registerOptions()
     this.registerEventHandlers()
@@ -110,6 +127,7 @@ class WorkflowsPlugin {
           constructorFn: initializer.arguments[1],
           context,
           parentReflection: reflection.parent,
+          workflowReflection: reflection,
         })
 
         if (!reflection.comment && reflection.parent.comment) {
@@ -121,6 +139,8 @@ class WorkflowsPlugin {
         }
       }
     }
+
+    this.handleAddTagsAfterParsing(context)
   }
 
   /**
@@ -133,15 +153,18 @@ class WorkflowsPlugin {
     constructorFn,
     context,
     parentReflection,
+    workflowReflection,
   }: {
     workflowId: string
     constructorFn: ts.ArrowFunction | ts.FunctionExpression
     context: Context
     parentReflection: DeclarationReflection
+    workflowReflection: SignatureReflection
   }) {
     // use the workflow manager to check whether something in the constructor
     // body is a step/hook
     const workflow = WorkflowManager.getWorkflow(workflowId)
+    const resources: string[] = []
 
     if (!ts.isBlock(constructorFn.body)) {
       return
@@ -165,19 +188,22 @@ class WorkflowsPlugin {
       )
 
       if (initializerName === "when") {
-        this.parseWhenStep({
+        const { resources: whenResources } = this.parseWhenStep({
           initializer,
           parentReflection,
           context,
           workflow,
           stepDepth,
+          workflowReflection,
         })
+        resources.push(...whenResources)
       } else {
         const steps = this.parseSteps({
           initializer,
           context,
           workflow,
           workflowVarName: parentReflection.name,
+          workflowReflection,
         })
 
         if (!steps.length) {
@@ -190,11 +216,15 @@ class WorkflowsPlugin {
             depth: stepDepth,
             parentReflection,
           })
+          resources.push(...step.resources)
         })
       }
 
       stepDepth++
     })
+
+    const uniqueResources = addTagsToReflection(parentReflection, resources)
+    this.updateWorkflowsTagsMap(workflowId, uniqueResources)
   }
 
   /**
@@ -208,11 +238,13 @@ class WorkflowsPlugin {
     context,
     workflow,
     workflowVarName,
+    workflowReflection,
   }: {
     initializer: ts.CallExpression
     context: Context
     workflow?: WorkflowDefinition
     workflowVarName: string
+    workflowReflection: SignatureReflection
   }): ParsedStep[] {
     const steps: ParsedStep[] = []
     const initializerName = this.helper.normalizeName(
@@ -235,13 +267,15 @@ class WorkflowsPlugin {
             context,
             workflow,
             workflowVarName,
+            workflowReflection,
           })
         )
       })
     } else {
       let stepId: string | undefined
       let stepReflection: DeclarationReflection | undefined
       let stepType = this.helper.getStepType(initializer)
+      const resources: string[] = []
 
       if (stepType === "hook" && "symbol" in initializer.arguments[1]) {
         // get the hook's name from the first argument
@@ -281,6 +315,12 @@ class WorkflowsPlugin {
           "step",
           true
         )
+        const stepResources = getResolvedResourcesOfStep(
+          originalInitializer,
+          stepId
+        )
+
+        resources.push(...stepResources)
         stepType = this.helper.getStepType(originalInitializer)
         stepReflection = initializerReflection
       }
@@ -295,7 +335,14 @@ class WorkflowsPlugin {
         steps.push({
           stepReflection,
           stepType,
+          resources,
         })
+        if (stepId?.endsWith(WORKFLOW_AS_STEP_SUFFIX)) {
+          this.updateAddTagsAfterParsingMap(workflowReflection, {
+            id: workflow.id,
+            workflowId: stepId,
+          })
+        }
       }
     }
 
@@ -313,13 +360,18 @@ class WorkflowsPlugin {
     context,
     workflow,
     stepDepth,
+    workflowReflection,
   }: {
     initializer: ts.CallExpression
     parentReflection: DeclarationReflection
     context: Context
     workflow?: WorkflowDefinition
     stepDepth: number
-  }) {
+    workflowReflection: SignatureReflection
+  }): {
+    resources: string[]
+  } {
+    const resources: string[] = []
     const whenInitializer = (initializer.expression as ts.CallExpression)
       .expression as ts.CallExpression
     const thenInitializer = initializer
@@ -332,7 +384,9 @@ class WorkflowsPlugin {
       (!ts.isFunctionExpression(thenInitializer.arguments[0]) &&
         !ts.isArrowFunction(thenInitializer.arguments[0]))
     ) {
-      return
+      return {
+        resources,
+      }
     }
 
     const whenCondition = whenInitializer.arguments[1].body.getText()
@@ -378,18 +432,25 @@ class WorkflowsPlugin {
         context,
         workflow,
         workflowVarName: parentReflection.name,
+        workflowReflection,
       }).forEach((step) => {
         this.createStepDocumentReflection({
           ...step,
           depth: stepDepth,
           parentReflection: documentReflection,
         })
+
+        resources.push(...step.resources)
       })
     })
 
     if (documentReflection.children?.length) {
       parentReflection.documents?.push(documentReflection)
     }
+
+    return {
+      resources: getUniqueStrArray(resources),
+    }
   }
 
   /**
@@ -473,6 +534,7 @@ class WorkflowsPlugin {
   createStepDocumentReflection({
     stepType,
     stepReflection,
+    resources,
     depth,
     parentReflection,
   }: ParsedStep & {
@@ -498,6 +560,7 @@ class WorkflowsPlugin {
         },
       ])
     )
+    addTagsToReflection(stepReflection, resources)
 
     if (parentReflection.isDocument()) {
       parentReflection.addChild(documentReflection)
@@ -605,6 +668,71 @@ class WorkflowsPlugin {
 
     return initializer
   }
+
+  updateAddTagsAfterParsingMap(
+    reflection: SignatureReflection,
+    {
+      id,
+      workflowId,
+    }: {
+      id: string
+      workflowId: string
+    }
+  ) {
+    const existingItem = this.addTagsAfterParsing[`${reflection.id}`] || {
+      id,
+      workflowIds: [],
+    }
+    existingItem.workflowIds.push(
+      workflowId.replace(WORKFLOW_AS_STEP_SUFFIX, "")
+    )
+    this.addTagsAfterParsing[`${reflection.id}`] = existingItem
+  }
+
+  updateWorkflowsTagsMap(workflowId: string, tags: string[]) {
+    const existingItems = this.workflowsTagsMap.get(workflowId) || []
+    existingItems.push(...tags)
+    this.workflowsTagsMap.set(workflowId, existingItems)
+  }
+
+  handleAddTagsAfterParsing(context: Context) {
+    let keys = Object.keys(this.addTagsAfterParsing)
+
+    const handleForWorkflow = (
+      key: string,
+      {
+        id,
+        workflowIds,
+      }: {
+        id: string
+        workflowIds: string[]
+      }
+    ) => {
+      const resources: string[] = []
+      workflowIds.forEach((workflowId) => {
+        // check if it exists in keys
+        const existingKey = keys.find(
+          (k) => this.addTagsAfterParsing[k].id === workflowId
+        )
+        if (existingKey) {
+          handleForWorkflow(existingKey, this.addTagsAfterParsing[existingKey])
+        }
+        resources.push(...(this.workflowsTagsMap.get(workflowId) || []))
+      })
+
+      const reflection = context.project.getReflectionById(parseInt(key))
+      if (reflection) {
+        const uniqueTags = addTagsToReflection(reflection, resources)
+        this.updateWorkflowsTagsMap(id, uniqueTags)
+      }
+      delete this.addTagsAfterParsing[key]
+      keys = Object.keys(this.addTagsAfterParsing)
+    }
+
+    do {
+      handleForWorkflow(keys[0], this.addTagsAfterParsing[keys[0]])
+    } while (keys.length > 0)
+  }
 }
 
 export default WorkflowsPlugin

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

@@ -7,6 +7,8 @@ import ts from "typescript"
 import { StepModifier, StepType } from "../types"
 import { capitalize, findReflectionInNamespaces } from "utils"
 
+export const WORKFLOW_AS_STEP_SUFFIX = `-as-step`
+
 /**
  * A class of helper methods.
  */
@@ -126,7 +128,7 @@ export default class Helper {
       stepId = this._getStepOrWorkflowIdFromArrowFunction(initializer, type)
     }
 
-    return isWorkflowStep ? `${stepId}-as-step` : stepId
+    return isWorkflowStep ? `${stepId}${WORKFLOW_AS_STEP_SUFFIX}` : stepId
   }
 
   private _getStepOrWorkflowIdFromArrowFunction(