@servicenow/sdk-build-plugins 4.1.1 → 4.3.0

package/src/flow/plugins/flow-diagnostics-plugin.ts

@@ -0,0 +1,280 @@
+/**
+ * Flow Diagnostics Plugin
+ *
+ * This plugin validates that flow-related constructs (wfa.action, wfa.subflow, wfa.flowLogic.*)
+ * are only used inside Flow or Subflow bodies, not at the top level or outside flow context.
+ */
+
+import {
+    Plugin,
+    CallExpressionShape,
+    ts,
+    StringShape,
+    ObjectShape,
+    UndefinedShape,
+    Record,
+    TemplateExpressionShape,
+    PropertyAccessShape,
+    IdentifierShape,
+    type Shape,
+} from '@servicenow/sdk-build-core'
+import { isDataPillShape } from '../flow-logic/flow-logic-plugin-helpers'
+
+/**
+ * Checks if a shape contains actual datapill references
+ * Unlike isDataPillShape, this only returns true for TemplateExpressionShape if it has substitutions
+ */
+function containsDataPill(shape: Shape): boolean {
+    if (shape instanceof PropertyAccessShape || shape instanceof IdentifierShape) {
+        return true
+    }
+    if (shape instanceof TemplateExpressionShape) {
+        return shape.hasSubstitution()
+    }
+    return false
+}
+import { findAncestorByCalleeName } from '../utils/utils'
+import { getCallExpressionName } from '../../utils'
+import { ActionSubflowInstanceShape } from '../utils/flow-shapes'
+
+import {
+    ACTION_INSTANCE_API_NAME,
+    SUBFLOW_INSTANCE_API_NAME,
+    FLOW_API_NAME,
+    SUBFLOW_API_NAME,
+    TRIGGER_INSTANCE_API_NAME,
+    ACTION_DEFINITION_API_NAME,
+    TRIGGER_DEFINITION_API_NAME,
+} from '../utils/flow-constants'
+
+// sendEmail action sys_id for validation
+const SEND_EMAIL_ACTION_SYS_ID = 'c1806bf4a70323008299b39f087901cb'
+
+import { FLOW_LOGIC } from '../flow-logic/flow-logic-constants'
+import { createFlowLogicInstanceShape } from '../flow-logic/flow-logic-shapes'
+
+/**
+ * Helper function to check if a node is inside a Flow or Subflow body
+ */
+function isInsideFlowOrSubflowBody(node: ts.Node): boolean {
+    const ancestorFlowOrSubflow = findAncestorByCalleeName(node, ...[FLOW_API_NAME, SUBFLOW_API_NAME])
+    if (ancestorFlowOrSubflow) {
+        return true
+    }
+    return false
+}
+
+function isInsideFlowContext(node: ts.Node): boolean {
+    const ancestor = findAncestorByCalleeName(
+        node,
+        ...[FLOW_API_NAME, SUBFLOW_API_NAME, ACTION_DEFINITION_API_NAME, TRIGGER_DEFINITION_API_NAME]
+    )
+    if (ancestor) {
+        return true
+    }
+    return false
+}
+
+/**
+ * Flow Placement Diagnostics Plugin
+ *
+ * Validates placement of:
+ * - wfa.action
+ * - wfa.subflow
+ * - wfa.trigger (must be within Flow)
+ * - wfa.flowLogic.if
+ * - wfa.flowLogic.elseIf
+ * - wfa.flowLogic.else
+ * - wfa.flowLogic.forEach
+ * - wfa.flowLogic.waitForADuration
+ * - wfa.flowLogic.goBackTo
+ * - wfa.flowLogic.tryCatch
+ * - wfa.flowLogic.doInParallel
+ * - FlowObject (must be within Flow/Subflow/ActionDefinition/SubflowDefinition/TriggerDefinition)
+ * - FlowArray (must be within Flow/Subflow/ActionDefinition/SubflowDefinition/TriggerDefinition)
+ */
+export const FlowDiagnosticsPlugin = Plugin.create({
+    name: 'FlowDiagnosticsPlugin',
+    shapes: [
+        {
+            shape: CallExpressionShape,
+            fileTypes: ['fluent'],
+            toSubclass(expr, { diagnostics }) {
+                const callee = expr.getCallee()
+                const instanceType =
+                    callee === ACTION_INSTANCE_API_NAME || callee === SUBFLOW_INSTANCE_API_NAME ? callee : undefined
+                if (!instanceType) {
+                    return { success: false }
+                }
+
+                // Validate that action/subflow is inside a Flow or Subflow body
+                const node = expr.getOriginalNode()
+                if (!isInsideFlowOrSubflowBody(node)) {
+                    diagnostics.error(
+                        expr,
+                        `${callee} must be used inside a Flow or Subflow body, not at the top level or outside flow context`
+                    )
+                    return { success: false }
+                }
+
+                const args = expr.getArguments()
+                if (args.length !== 3) {
+                    diagnostics.error(expr, `Expected 3 arguments for ${instanceType}, but received ${args.length}`)
+                    return { success: false }
+                }
+
+                try {
+                    const definition = args[0]?.isString() ? args[0].as(StringShape) : args[0]?.as(Record)
+                    const inputs = args[2]?.as(ObjectShape)
+
+                    if (!args[1]?.isObject()) {
+                        diagnostics.error(expr, `Expected config object as second argument for ${instanceType}`)
+                        return { success: false }
+                    }
+
+                    const configObj = args[1].as(ObjectShape)
+                    // Validate that annotation field does not contain datapills
+                    const configEntries = configObj.entries({ resolve: false })
+                    const annotationEntry = configEntries.find(([key]) => key === 'annotation')
+                    const shape = annotationEntry?.[1]
+
+                    if (shape && !shape.if(UndefinedShape)) {
+                        if (isDataPillShape(shape)) {
+                            diagnostics.error(
+                                shape.getOriginalNode(),
+                                'Datapills are not allowed in the annotation field. Please use a static string value.'
+                            )
+                            return { success: false }
+                        }
+                    }
+
+                    // Validate that ah_body field does not contain datapills for sendEmail action
+                    const actionId =
+                        definition instanceof StringShape ? definition.getValue() : definition?.getId()?.getValue()
+
+                    if (actionId === SEND_EMAIL_ACTION_SYS_ID && inputs) {
+                        const ahBodyShape = inputs.get('ah_body', false)
+
+                        if (!ahBodyShape.if(UndefinedShape) && containsDataPill(ahBodyShape)) {
+                            diagnostics.error(
+                                ahBodyShape.getOriginalNode(),
+                                'Datapills are not allowed in the ah_body field of sendEmail action. Please use a static string value.'
+                            )
+                            return { success: false }
+                        }
+                    }
+
+                    return {
+                        success: true,
+                        value: new ActionSubflowInstanceShape({
+                            source: expr,
+                            instanceDefinition: definition,
+                            instanceProps: inputs,
+                            instanceType, // "Action" | "Subflow"
+                            configObject: configObj,
+                        }),
+                    }
+                } catch (e) {
+                    diagnostics.error(
+                        expr,
+                        `Failed to parse value for ${instanceType}: ${e instanceof Error ? e.message : e}`
+                    )
+                    return { success: false }
+                }
+            },
+        },
+        {
+            shape: CallExpressionShape,
+            fileTypes: ['fluent'],
+            toSubclass(expr, { diagnostics }) {
+                const callee = expr.getCallee()
+                // Validate that the logic name is a valid FLOW_LOGIC value
+                if (!Object.values(FLOW_LOGIC).includes(callee as FLOW_LOGIC)) {
+                    return { success: false }
+                }
+                // Validate that flow logic is inside a Flow or Subflow body
+                const node = expr.getOriginalNode()
+                if (!isInsideFlowOrSubflowBody(node)) {
+                    const logicName = callee.replace('wfa.flowLogic.', '')
+                    diagnostics.error(
+                        expr,
+                        `${logicName} must be used inside a Flow or Subflow body, not at the top level or outside flow context`
+                    )
+                    return { success: false }
+                }
+
+                // Validate sibling relationships for ElseIf/Else
+                if (callee === FLOW_LOGIC.ELSEIF || callee === FLOW_LOGIC.ELSE) {
+                    const sibling = node
+                        .getParent()
+                        ?.getPreviousSibling((n) => !ts.Node.isCommentStatement(n))
+                        ?.asKind(ts.SyntaxKind.ExpressionStatement)
+                        ?.getExpression()
+                        .asKind(ts.SyntaxKind.CallExpression)
+
+                    const siblingCallName = sibling ? getCallExpressionName(sibling) : undefined
+
+                    // Capitalize the logic type for the error message (ElseIf -> ElseIf, else -> Else)
+                    const logicType = callee === FLOW_LOGIC.ELSEIF ? 'ElseIf' : 'Else'
+                    if (!sibling) {
+                        diagnostics.error(expr, `${logicType} clause must follow an If or ElseIf clause.`)
+                        return { success: false }
+                    }
+
+                    const validPredecessors = [FLOW_LOGIC.IF, FLOW_LOGIC.ELSEIF]
+                    if (siblingCallName && !validPredecessors.includes(siblingCallName as FLOW_LOGIC)) {
+                        diagnostics.error(
+                            expr,
+                            `${logicType} clause must follow an If or ElseIf clause, but found ${siblingCallName}.`
+                        )
+                        return { success: false }
+                    }
+                }
+
+                const args = expr.getArguments(false)
+                return {
+                    success: true,
+                    value: createFlowLogicInstanceShape(expr, callee, args),
+                }
+            },
+        },
+        {
+            shape: CallExpressionShape,
+            fileTypes: ['fluent'],
+            toSubclass(expr, { diagnostics }) {
+                const callee = expr.getCallee()
+                // Validate wfa.trigger placement
+                if (callee !== TRIGGER_INSTANCE_API_NAME) {
+                    return { success: false }
+                }
+                const node = expr.getOriginalNode()
+                // Check if trigger is directly passed as Flow's 2nd argument
+                const parentFlow = findAncestorByCalleeName(node, FLOW_API_NAME)
+                if (parentFlow) {
+                    return { success: false }
+                }
+
+                diagnostics.error(expr, 'Trigger must be defined within a Flow. Orphan triggers are not allowed.')
+                return { success: false }
+            },
+        },
+        {
+            shape: CallExpressionShape,
+            fileTypes: ['fluent'],
+            toSubclass(expr, { diagnostics }) {
+                const callee = expr.getCallee()
+                // Validate FlowObject and FlowArray placement
+                if (callee !== 'FlowObject' && callee !== 'FlowArray') {
+                    return { success: false }
+                }
+                const node = expr.getOriginalNode()
+                if (!isInsideFlowContext(node)) {
+                    diagnostics.error(expr, `${callee} can only be used within Flow, Subflow contexts.`)
+                    return { success: false }
+                }
+
+                return { success: false }
+            },
+        },
+    ],
+})