docs-util: add support for workflows in markdown theme (#8485)

* add template for workflows

* initial changes

* added support for parallel steps

* added support for when

* added merge options

* fix merge options

* fix to tooltip

* clean up

* remove redirects

* fixes

* theme fixes + added merge options

* generate hook examples + fixes

* changed namespaces

* add custom autogenerator

* change type of additional data

www/utils/packages/utils/src/hooks-util.ts

@@ -0,0 +1,63 @@
+import {
+  DeclarationReflection,
+  IntrinsicType,
+  ParameterReflection,
+  Reflection,
+} from "typedoc"
+
+export function cleanUpHookInput(
+  parameters: ParameterReflection[]
+): ParameterReflection[] {
+  return parameters.map((parameter) => {
+    if (parameter.type?.type !== "reference" || !parameter.type.reflection) {
+      return parameter
+    }
+
+    cleanUpReflectionType(parameter.type.reflection)
+
+    if (
+      parameter.type.reflection &&
+      parameter.type.reflection instanceof DeclarationReflection &&
+      parameter.type.reflection.children
+    ) {
+      parameter.type.reflection.children.forEach(cleanUpReflectionType)
+    }
+
+    return parameter
+  })
+}
+
+function cleanUpReflectionType(reflection: Reflection): Reflection {
+  if (
+    !(reflection instanceof DeclarationReflection) &&
+    !(reflection instanceof ParameterReflection)
+  ) {
+    return reflection
+  }
+  if (
+    reflection.type?.type === "reference" &&
+    reflection.type.name === "WorkflowData" &&
+    reflection.type.typeArguments?.length
+  ) {
+    reflection.type = reflection.type.typeArguments[0]
+  }
+
+  if (reflection.defaultValue) {
+    delete reflection.defaultValue
+  }
+
+  if (reflection.name === "additional_data") {
+    reflection.type = new IntrinsicType("Record<string, unknown> | undefined")
+  } else if (
+    reflection.type?.type === "intersection" &&
+    reflection.type.types.length >= 2
+  ) {
+    reflection.type = reflection.type.types[1]
+  }
+
+  if (reflection instanceof DeclarationReflection && reflection.children) {
+    reflection.children.forEach(cleanUpReflectionType)
+  }
+
+  return reflection
+}

www/utils/packages/utils/src/index.ts

@@ -2,6 +2,7 @@ export * from "./dml-utils"
 export * from "./get-type-children"
 export * from "./get-project-child"
 export * from "./get-type-str"
+export * from "./hooks-util"
 export * from "./step-utils"
 export * from "./str-formatting"
 export * from "./str-utils"

www/utils/packages/utils/src/step-utils.ts

@@ -1,5 +1,7 @@
 import { ArrayType, SignatureReflection, SomeType, UnionType } from "typedoc"
 
+const disallowedIntrinsicTypeNames = ["unknown", "void", "any", "never"]
+
 export function isWorkflowStep(reflection: SignatureReflection): boolean {
   return (
     reflection.parent?.children?.some((child) => child.name === "__step__") ||
@@ -10,11 +12,7 @@ export function isWorkflowStep(reflection: SignatureReflection): boolean {
 export function getStepInputType(
   reflection: SignatureReflection
 ): SomeType | undefined {
-  if (!isWorkflowStep(reflection)) {
-    return
-  }
-
-  if (!reflection.parameters?.length) {
+  if (!isWorkflowStep(reflection) || !reflection.parameters?.length) {
     return
   }
 
@@ -28,6 +26,13 @@ export function getStepOutputType(
     return
   }
 
+  if (
+    reflection.type?.type === "intrinsic" &&
+    disallowedIntrinsicTypeNames.includes(reflection.type.name)
+  ) {
+    return
+  }
+
   if (reflection.type?.type !== "intersection") {
     return reflection.type
   }
@@ -52,6 +57,12 @@ function cleanUpType(itemType: SomeType | undefined): SomeType | undefined {
       return cleanUpUnionType(itemType)
     case "array":
       return cleanUpArrayType(itemType)
+    case "intrinsic":
+      if (disallowedIntrinsicTypeNames.includes(itemType.name)) {
+        return undefined
+      }
+
+      return itemType
     default:
       return itemType
   }

www/utils/packages/utils/src/workflow-utils.ts

@@ -1,4 +1,4 @@
-import { SignatureReflection } from "typedoc"
+import { ReferenceType, SignatureReflection, SomeType } from "typedoc"
 
 export function isWorkflow(reflection: SignatureReflection): boolean {
   return (
@@ -6,3 +6,57 @@ export function isWorkflow(reflection: SignatureReflection): boolean {
     false
   )
 }
+
+export function getWorkflowInputType(
+  reflection: SignatureReflection
+): SomeType | undefined {
+  const exportedWorkflowType = getExportedWorkflowType(reflection)
+
+  const inputType = exportedWorkflowType?.typeArguments![0]
+
+  return isAllowedType(inputType) ? inputType : undefined
+}
+
+export function getWorkflowOutputType(
+  reflection: SignatureReflection
+): SomeType | undefined {
+  const exportedWorkflowType = getExportedWorkflowType(reflection)
+
+  const outputType = exportedWorkflowType?.typeArguments![1]
+
+  return isAllowedType(outputType) ? outputType : undefined
+}
+
+function getExportedWorkflowType(
+  reflection: SignatureReflection
+): ReferenceType | undefined {
+  if (
+    !isWorkflow(reflection) ||
+    reflection.type?.type !== "intersection" ||
+    reflection.type.types.length < 2
+  ) {
+    return
+  }
+
+  const exportedWorkflowType = reflection.type.types[1]
+
+  if (
+    exportedWorkflowType.type !== "reference" ||
+    exportedWorkflowType.name !== "ExportedWorkflow" ||
+    (exportedWorkflowType.typeArguments?.length || 0) < 1
+  ) {
+    return
+  }
+
+  return exportedWorkflowType
+}
+
+const disallowedIntrinsicTypeNames = ["unknown", "void", "any", "never"]
+
+function isAllowedType(type: SomeType | undefined): boolean {
+  return (
+    type !== undefined &&
+    (type.type !== "intrinsic" ||
+      !disallowedIntrinsicTypeNames.includes(type.name))
+  )
+}