docs-util: added workflows typedoc plugin (#8463)

* initial changes

* finish workflow plugin

* add comments

* remove todo

www/utils/packages/utils/package.json

@@ -11,7 +11,8 @@
   "scripts": {
     "build": "yarn clean && tsc",
     "lint": "eslint --ext .ts src",
-    "clean": "rimraf dist"
+    "clean": "rimraf dist",
+    "watch": "tsc --watch"
   },
   "peerDependencies": {
     "typedoc": "0.26.x"

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

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

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

@@ -0,0 +1,79 @@
+import { ArrayType, SignatureReflection, SomeType, UnionType } from "typedoc"
+
+export function isWorkflowStep(reflection: SignatureReflection): boolean {
+  return (
+    reflection.parent?.children?.some((child) => child.name === "__step__") ||
+    false
+  )
+}
+
+export function getStepInputType(
+  reflection: SignatureReflection
+): SomeType | undefined {
+  if (!isWorkflowStep(reflection)) {
+    return
+  }
+
+  if (!reflection.parameters?.length) {
+    return
+  }
+
+  return cleanUpType(reflection.parameters[0].type)
+}
+
+export function getStepOutputType(
+  reflection: SignatureReflection
+): SomeType | undefined {
+  if (!isWorkflowStep(reflection)) {
+    return
+  }
+
+  if (reflection.type?.type !== "intersection") {
+    return reflection.type
+  }
+
+  if (reflection.type.types.length <= 3) {
+    return
+  }
+
+  const returnType = reflection.type.types
+    .slice(0, 3)
+    .find(
+      (itemType) =>
+        itemType.type !== "reflection" || itemType.declaration.name !== "__type"
+    )
+
+  return cleanUpType(returnType)
+}
+
+function cleanUpType(itemType: SomeType | undefined): SomeType | undefined {
+  switch (itemType?.type) {
+    case "union":
+      return cleanUpUnionType(itemType)
+    case "array":
+      return cleanUpArrayType(itemType)
+    default:
+      return itemType
+  }
+}
+
+function cleanUpUnionType(unionType: UnionType): SomeType {
+  const cleanedUpTypes = unionType.types.filter(
+    (itemType) =>
+      itemType.type !== "reference" || itemType.name !== "WorkflowData"
+  )
+
+  return cleanedUpTypes.length === 1
+    ? cleanedUpTypes[0]
+    : new UnionType(cleanedUpTypes)
+}
+
+function cleanUpArrayType(arrayType: ArrayType): SomeType {
+  const cleanedUpType = cleanUpType(arrayType.elementType)
+
+  if (!cleanedUpType) {
+    return arrayType
+  }
+
+  return new ArrayType(cleanedUpType)
+}

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

@@ -0,0 +1,8 @@
+import { SignatureReflection } from "typedoc"
+
+export function isWorkflow(reflection: SignatureReflection): boolean {
+  return (
+    reflection.parent.children?.some((child) => child.name === "runAsStep") ||
+    false
+  )
+}