@servicenow/sdk-build-plugins 4.2.0 → 4.4.0

package/src/flow/utils/datapill-transformer.ts

@@ -0,0 +1,632 @@
+import {
+    CallExpressionShape,
+    type IdentifierShape,
+    type Record,
+    Shape,
+    VariableStatementShape,
+    ObjectShape,
+    type Diagnostics,
+    type Logger,
+} from '@servicenow/sdk-build-core'
+import { ArrowFunctionShape } from '../../arrow-function-plugin'
+import { FLOW_LOGIC, FLOW_LOGIC_PREFIX } from '../flow-logic/flow-logic-constants'
+
+/**
+ * Result of datapill transformation
+ */
+export interface DatapillTransformResult {
+    shape: Shape
+    propsChanged: boolean
+}
+
+/**
+ * Information about a flow instance shape for processing
+ */
+export interface FlowInstanceShapeInfo {
+    callExpression: CallExpressionShape
+    variableStatement: VariableStatementShape | CallExpressionShape
+}
+
+/**
+ * Flow logic types that have outputs and can be assigned to a variable
+ */
+/**
+ * TODO: Extend this list as more flow logics with outputs are added also try to create map to identify arguments dynamically
+ * e.g., flow logic like waitForADuration has config at arg 0 and outputs, while others may have different positions
+ */
+
+const FLOW_LOGIC_WITH_OUTPUTS = [FLOW_LOGIC.WAIT_FOR_A_DURATION]
+
+// Module-level map to store UUID-to-Record mapping for forEach detection
+// This is populated by buildUuidToIdentifierMap and used by isForEachParameter
+export const uuidToRecordMap = new Map<string, Record>()
+
+/**
+ * Build a map of UUID to variable identifiers from instance records and shapes
+ * This map is used to transform UUID-based datapills into property access expressions
+ * Uses ui_id from records (not $id from config) because datapills reference ui_id
+ *
+ * @param recordToShapeMap - Map of instance records to their corresponding shapes
+ * @returns Map of UUID strings (ui_id) to IdentifierShapes
+ */
+export function buildUuidToIdentifierMap(recordToShapeMap: Map<Record, Shape>): Map<string, IdentifierShape> {
+    const uuidToIdentifierMap = new Map<string, IdentifierShape>()
+
+    // Clear and rebuild the module-level UUID-to-Record map
+    uuidToRecordMap.clear()
+
+    for (const [record, instanceShape] of recordToShapeMap.entries()) {
+        // Extract ui_id from the record (this is what datapills reference)
+        const uiId = record.get('ui_id')?.getValue() as string | undefined
+
+        if (!uiId) {
+            continue
+        }
+
+        // Handle VariableStatementShape (actions/subflows with variable assignments)
+        if (instanceShape instanceof VariableStatementShape) {
+            const variableStatement = instanceShape.as(VariableStatementShape)
+            const variableName = variableStatement.getVariableName()
+            const callExpression = variableStatement.getInitializer().as(CallExpressionShape)
+
+            const callee = callExpression.getCallee()
+
+            // For flow logic with outputs (e.g., waitForADuration), config is at position 0
+            // For actions/subflows, config is at position 1
+            const isFlowLogicWithOutputs = FLOW_LOGIC_WITH_OUTPUTS.includes(callee as FLOW_LOGIC)
+            const configArgIndex = isFlowLogicWithOutputs ? 0 : 1
+            const configArg = callExpression.getArgument(configArgIndex)?.asObject()
+
+            if (configArg) {
+                const uuid = configArg.get('uuid')?.ifString()?.getValue()
+                if (uuid && variableName) {
+                    uuidToIdentifierMap.set(uuid, variableName)
+                    uuidToRecordMap.set(uuid, record)
+                }
+            }
+        }
+        // Handle CallExpressionShape (flow logic like forEach)
+        else if (instanceShape instanceof CallExpressionShape) {
+            const callExpression = instanceShape.as(CallExpressionShape)
+            const callee = callExpression.getCallee()
+
+            if (callee === 'wfa.flowLogic.forEach') {
+                // Get the arrow function body (3rd argument for forEach)
+                // NOTE: For nested forEach, parameter names are order-based (item_0, item_1, item_2, etc.)
+                // This allows distinguishing which parent forEach an 'item' reference belongs to
+                // Example:
+                //   forEach at order 0: (item_0) => { ... }
+                //   forEach at order 1: (item_1) => { ... }
+                // In XML, datapills are stored as {{forEachUUID.item.field}}
+                // which gets transformed to item_0.field, item_1.field, etc. based on the UUID mapping
+                const bodyArg = callExpression.getArgument(2)
+                if (bodyArg?.if(ArrowFunctionShape)) {
+                    const arrowFunc = bodyArg.as(ArrowFunctionShape)
+                    const params = arrowFunc.getParameters()
+                    // getParameters() returns IdentifierShape[] - use directly
+                    if (params && params.length > 0) {
+                        const paramIdentifier = params[0]
+                        if (paramIdentifier) {
+                            uuidToIdentifierMap.set(uiId, paramIdentifier)
+                            uuidToRecordMap.set(uiId, record)
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    return uuidToIdentifierMap
+}
+
+/**
+ * Extract CallExpression and VariableStatement from an instance shape
+ * Handles both VariableStatementShape (for Action/Subflow) and bare CallExpressionShape (for flow logic)
+ *
+ * @param instanceShape - The shape to extract from
+ * @returns Object containing callExpression and variableStatement
+ */
+export function extractInstanceShapeInfo(instanceShape: Shape): FlowInstanceShapeInfo {
+    let callExpression: CallExpressionShape
+    let variableStatement: VariableStatementShape | CallExpressionShape
+
+    if (instanceShape instanceof VariableStatementShape) {
+        callExpression = instanceShape.getInitializer().as(CallExpressionShape)
+        variableStatement = instanceShape
+    } else {
+        callExpression = instanceShape.as(CallExpressionShape)
+        variableStatement = callExpression
+    }
+
+    return { callExpression, variableStatement }
+}
+
+/**
+ * Rebuild a CallExpressionShape with transformed properties
+ * Creates a new CallExpression with the transformed props and cleaned config
+ *
+ * @param originalCallExpression - The original CallExpression
+ * @param transformedProps - The transformed properties object
+ * @param configShape - The config shape (possibly cleaned)
+ * @param record - The source record for shape creation
+ * @returns New CallExpressionShape with transformed properties
+ */
+export function rebuildCallExpressionWithDatapills(
+    originalCallExpression: CallExpressionShape,
+    transformedProps: { [key: string]: Shape },
+    configShape: Shape,
+    record: Record
+): CallExpressionShape {
+    const originalActionDef = originalCallExpression.getArgument(0, false)
+    const newPropsArg = Shape.from(record, transformedProps)
+
+    return new CallExpressionShape({
+        source: originalCallExpression.getSource(),
+        callee: originalCallExpression.getCallee(),
+        args: [originalActionDef, configShape, newPropsArg],
+    })
+}
+
+/**
+ * Rebuild an instance shape (VariableStatement or CallExpression) with transformed datapills
+ *
+ * @param instanceShape - The original instance shape
+ * @param newCallExpression - The new CallExpression with transformed properties
+ * @param instanceShapeInfo - Information extracted from the instance shape
+ * @returns Rebuilt VariableStatementShape or the new CallExpression
+ */
+export function rebuildInstanceWithDatapills(
+    instanceShape: Shape,
+    newCallExpression: CallExpressionShape,
+    instanceShapeInfo: FlowInstanceShapeInfo
+): Shape {
+    const { variableStatement } = instanceShapeInfo
+
+    if (instanceShape instanceof VariableStatementShape) {
+        return new VariableStatementShape({
+            source: variableStatement.getSource(),
+            variableName:
+                variableStatement instanceof VariableStatementShape
+                    ? variableStatement.getVariableName()
+                    : 'dummyVariable_removeLater', // For flow logic that returns outputs
+            initializer: newCallExpression,
+            isExported: false,
+        })
+    }
+
+    // Return the CallExpression directly for non-variable statements (flow logic)
+    return newCallExpression
+}
+
+/**
+ * Check if a callee string represents a flow logic call
+ * @param callee - The callee string (e.g., 'wfa.flowLogic.if', 'wfa.action')
+ * @returns true if the callee is a flow logic call
+ */
+export function isFlowLogicCallee(callee: string): boolean {
+    return callee.startsWith(FLOW_LOGIC_PREFIX)
+}
+
+/**
+ * Check if a flow logic type has a body (arrow function)
+ * @param callee - The flow logic callee (e.g., 'wfa.flowLogic.if')
+ * @returns true if the flow logic has a body
+ */
+export function flowLogicHasBody(callee: string): boolean {
+    // Flow logic with bodies: if, elseIf, else, forEach, tryCatch, doInParallel
+    // Flow logic without bodies: goBackTo, waitForADuration, exitLoop, endFlow, skipIteration
+    return [
+        FLOW_LOGIC.IF,
+        FLOW_LOGIC.ELSEIF,
+        FLOW_LOGIC.ELSE,
+        FLOW_LOGIC.FOR_EACH,
+        FLOW_LOGIC.TRY_CATCH,
+        FLOW_LOGIC.DO_IN_PARALLEL,
+    ].includes(callee as FLOW_LOGIC)
+}
+
+/**
+ * Extract arrow function bodies from a flow logic call expression
+ * Different flow logic types have bodies in different positions:
+ * - If/ElseIf/Else: Single body at argument 1
+ * - ForEach: Body at argument 2 (arg 0 is items, arg 1 is config)
+ * - TryCatch: Object with 'try' and 'catch' properties containing arrow functions
+ * - DoInParallel: Variadic functions starting from argument 1
+ *
+ * @param callExpression - The flow logic call expression
+ * @param callee - The flow logic callee
+ * @returns Array of arrow function shapes
+ */
+export function extractFlowLogicBodies(callExpression: CallExpressionShape, callee: string): ArrowFunctionShape[] {
+    const bodies: ArrowFunctionShape[] = []
+
+    if (callee === FLOW_LOGIC.TRY_CATCH) {
+        // TryCatch: { try: () => {...}, catch: () => {...} }
+        const handlers = callExpression.getArgument(1)?.asObject()
+        if (handlers) {
+            const tryHandler = handlers.get('try')
+            const catchHandler = handlers.get('catch')
+            if (tryHandler?.if(ArrowFunctionShape)) {
+                bodies.push(tryHandler.as(ArrowFunctionShape))
+            }
+            if (catchHandler?.if(ArrowFunctionShape)) {
+                bodies.push(catchHandler.as(ArrowFunctionShape))
+            }
+        }
+    } else if (callee === FLOW_LOGIC.DO_IN_PARALLEL) {
+        // DoInParallel: config, fn1, fn2, fn3, ...
+        const allArgs = callExpression.getArguments()
+        for (let i = 1; i < allArgs.length; i++) {
+            const arg = callExpression.getArgument(i)
+            if (arg?.if(ArrowFunctionShape)) {
+                bodies.push(arg.as(ArrowFunctionShape))
+            }
+        }
+    } else if (callee === FLOW_LOGIC.FOR_EACH) {
+        // ForEach: items, config, body
+        const bodyArg = callExpression.getArgument(2)
+        if (bodyArg?.if(ArrowFunctionShape)) {
+            bodies.push(bodyArg.as(ArrowFunctionShape))
+        }
+    } else {
+        // If/ElseIf/Else: config, body
+        const bodyArg = callExpression.getArgument(1)
+        if (bodyArg?.if(ArrowFunctionShape)) {
+            bodies.push(bodyArg.as(ArrowFunctionShape))
+        }
+    }
+
+    return bodies
+}
+
+/**
+ * Rebuild a flow logic call expression with transformed config and bodies
+ * @param callExpression - Original call expression
+ * @param transformedConfig - Transformed config object
+ * @param transformedBodies - Transformed arrow function bodies
+ * @param callee - The flow logic callee
+ * @param record - The source record
+ * @returns Rebuilt CallExpressionShape
+ */
+export function rebuildFlowLogicWithDatapills(
+    callExpression: CallExpressionShape,
+    transformedConfig: ObjectShape,
+    transformedBodies: ArrowFunctionShape[],
+    callee: string,
+    record: Record,
+    transformedItemsArg?: Shape
+): CallExpressionShape {
+    if (callee === FLOW_LOGIC.TRY_CATCH) {
+        // TryCatch: config, { try: fn1, catch: fn2 }
+        const handlersObj = Shape.from(record, {
+            try: transformedBodies[0],
+            catch: transformedBodies[1],
+        })
+        return new CallExpressionShape({
+            source: callExpression.getSource(),
+            callee: callExpression.getCallee(),
+            args: [transformedConfig, handlersObj],
+        })
+    }
+
+    if (callee === 'wfa.flowLogic.doInParallel') {
+        // DoInParallel: config, fn1, fn2, ...
+        return new CallExpressionShape({
+            source: callExpression.getSource(),
+            callee: callExpression.getCallee(),
+            args: [transformedConfig, ...transformedBodies],
+        })
+    }
+
+    if (callee === 'wfa.flowLogic.forEach') {
+        // ForEach: items, config, body
+        // Use transformed items if available, otherwise use original
+        const itemsArg = transformedItemsArg || callExpression.getArgument(0, false)
+        return new CallExpressionShape({
+            source: callExpression.getSource(),
+            callee: callExpression.getCallee(),
+            args: [itemsArg, transformedConfig, transformedBodies[0]],
+        })
+    }
+
+    // If/ElseIf/Else: config, body
+    return new CallExpressionShape({
+        source: callExpression.getSource(),
+        callee: callExpression.getCallee(),
+        args: [transformedConfig, transformedBodies[0]],
+    })
+}
+
+/**
+ * Type for config cleanup callback function
+ * Used to clean up Action/Subflow configs after transformation
+ */
+export type ConfigCleanupCallback = (configShape: Shape, instanceSource: Shape) => Shape
+
+/**
+ * Recursively process an instance shape (Action, Subflow, or Flow Logic) to transform datapills
+ * This is the main entry point for datapill transformation that handles all instance types
+ *
+ * @param instanceShape - The instance shape to process (VariableStatementShape or CallExpressionShape)
+ * @param uuidToIdentifierMap - Map of UUID to variable identifiers for UUID-based datapills
+ * @param record - The source record for shape creation
+ * @param diagnostics - Diagnostics for error reporting
+ * @param paramName - Parameter name for semantic datapills (e.g., 'params')
+ * @param processShapeForDatapills - Recursive helper to process nested structures (objects/arrays)
+ * @param cleanupConfig - Optional callback to clean up Action/Subflow configs
+ * @returns DatapillTransformResult with transformed shape and change tracking
+ */
+export function processInstanceForDatapills(
+    instanceShape: Shape,
+    uuidToIdentifierMap: Map<string, IdentifierShape>,
+    record: Record,
+    diagnostics: Diagnostics,
+    paramName: string,
+    logger: Logger,
+    processShapeForDatapills: (
+        value: Shape,
+        uuidToIdentifierMap: Map<string, IdentifierShape>,
+        source: Record,
+        diagnostics: Diagnostics,
+        logger: Logger,
+        parameterName?: string
+    ) => DatapillTransformResult,
+    cleanupConfig?: ConfigCleanupCallback
+): DatapillTransformResult {
+    // Step 1: Extract call expression and variable statement
+    const { callExpression, variableStatement } = extractInstanceShapeInfo(instanceShape)
+    const callee = callExpression.getCallee()
+    const isFlowLogic = isFlowLogicCallee(callee)
+
+    // Step 2: Determine which properties to transform based on instance type
+    let propsArg: Shape | undefined
+    let configArgIndex: number
+
+    if (isFlowLogic) {
+        // For SetFlowVariables and AssignSubflowOutputs, transform the values object (3rd argument)
+        // For ForEach, transform the config (2nd argument)
+        // For other flow logic, transform the config (1st argument)
+        if (callee === FLOW_LOGIC.SET_FLOW_VARIABLES || callee === FLOW_LOGIC.ASSIGN_SUBFLOW_OUTPUTS) {
+            configArgIndex = 2
+            propsArg = callExpression.getArgument(2)
+        } else if (callee === FLOW_LOGIC.FOR_EACH) {
+            configArgIndex = 1
+            propsArg = callExpression.getArgument(1)
+        } else {
+            configArgIndex = 0
+            propsArg = callExpression.getArgument(0)
+        }
+    } else {
+        // For Action/Subflow, we transform the inputs (3rd argument)
+        configArgIndex = 2
+        propsArg = callExpression.getArgument(configArgIndex)
+    }
+
+    let overallChanged = false
+
+    if (!propsArg.isDefined()) {
+        return { shape: instanceShape, propsChanged: false }
+    }
+
+    // Step 3: Transform schema argument for SetFlowVariables and AssignSubflowOutputs
+    // The schema argument (arg 1) contains PropertyAccessShape with placeholder identifier (_params)
+    // that needs to be resolved to the actual parameter name
+    let transformedSchemaArg: Shape | undefined
+    if (callee === FLOW_LOGIC.SET_FLOW_VARIABLES || callee === FLOW_LOGIC.ASSIGN_SUBFLOW_OUTPUTS) {
+        const schemaArg = callExpression.getArgument(1)
+        if (schemaArg) {
+            const schemaResult = processShapeForDatapills(
+                schemaArg,
+                uuidToIdentifierMap,
+                record,
+                diagnostics,
+                logger,
+                paramName
+            )
+            transformedSchemaArg = schemaResult.shape
+            if (schemaResult.propsChanged) {
+                overallChanged = true
+            }
+        }
+    }
+
+    // Step 3.5: Transform items argument for ForEach
+    // The items argument (arg 0) contains data pill strings like "{{trigger.array_field}}"
+    // that need to be converted to PropertyAccessShape with the correct parameter name
+    let transformedItemsArg: Shape | undefined
+    if (callee === FLOW_LOGIC.FOR_EACH) {
+        const itemsArg = callExpression.getArgument(0)
+        if (itemsArg) {
+            const itemsResult = processShapeForDatapills(
+                itemsArg,
+                uuidToIdentifierMap,
+                record,
+                diagnostics,
+                logger,
+                paramName
+            )
+            transformedItemsArg = itemsResult.shape
+            if (itemsResult.propsChanged) {
+                overallChanged = true
+            }
+        }
+    }
+
+    // Note: goBackTo step ID should remain as UUID string for XML serialization
+    // It will be resolved to an identifier during the flow-logic-plugin-helpers.ts transformation
+
+    // Step 4: Transform properties in config/inputs/values
+    let transformedConfig: ObjectShape | undefined
+    if (propsArg.isObject()) {
+        const propsObj = propsArg.asObject()
+        const propsEntries = propsObj.entries()
+        const transformedProps: { [key: string]: Shape } = {}
+        let propsChanged = false
+
+        for (const [key, value] of propsEntries) {
+            const result = processShapeForDatapills(value, uuidToIdentifierMap, record, diagnostics, logger, paramName)
+            transformedProps[key] = result.shape
+
+            if (result.propsChanged) {
+                propsChanged = true
+            }
+        }
+
+        if (propsChanged) {
+            transformedConfig = new ObjectShape({
+                source: propsArg.getSource(),
+                properties: transformedProps,
+            })
+            overallChanged = true
+        } else {
+            transformedConfig = propsObj
+        }
+
+        // Check if config cleanup would make changes (before overallChanged check)
+        // This ensures we don't early-return when cleanup is needed
+        if (cleanupConfig) {
+            // For Action/Subflow instances, check config (argument 1)
+            if (!isFlowLogic) {
+                const originalConfig = callExpression.getArgument(1)
+                if (originalConfig) {
+                    const cleanedConfig = cleanupConfig(originalConfig, instanceShape)
+                    if (cleanedConfig !== originalConfig) {
+                        overallChanged = true
+                    }
+                }
+            }
+
+            // For flow logic with outputs (e.g., WaitForADuration), check config (argument 0)
+            const isFlowLogicWithOutputs = FLOW_LOGIC_WITH_OUTPUTS.includes(callee as FLOW_LOGIC)
+            if (isFlowLogicWithOutputs && transformedConfig) {
+                const cleanedConfig = cleanupConfig(transformedConfig, callExpression)
+                if (cleanedConfig !== transformedConfig) {
+                    overallChanged = true
+                }
+            }
+        }
+    }
+
+    // Step 4: Handle flow logic with bodies (recursive processing of child instances)
+    const transformedBodies: ArrowFunctionShape[] = []
+    if (isFlowLogic && flowLogicHasBody(callee)) {
+        const bodies = extractFlowLogicBodies(callExpression, callee)
+
+        for (const body of bodies) {
+            const childInstances = body.getStatements()
+            const transformedChildren: Shape[] = []
+            let anyChildChanged = false
+
+            // Recursively process each child instance
+            for (const childInstance of childInstances) {
+                const childResult = processInstanceForDatapills(
+                    childInstance,
+                    uuidToIdentifierMap,
+                    record,
+                    diagnostics,
+                    paramName,
+                    logger,
+                    processShapeForDatapills,
+                    cleanupConfig
+                )
+                transformedChildren.push(childResult.shape)
+
+                if (childResult.propsChanged) {
+                    anyChildChanged = true
+                }
+            }
+
+            // Rebuild body if children changed
+            const transformedBody = anyChildChanged
+                ? new ArrowFunctionShape({
+                      source: body.getSource(),
+                      parameters: body.getParameters(),
+                      statements: transformedChildren,
+                  })
+                : body
+
+            transformedBodies.push(transformedBody)
+
+            if (anyChildChanged) {
+                overallChanged = true
+            }
+        }
+    }
+
+    // Step 5: Rebuild instance if anything changed
+    if (!overallChanged) {
+        return {
+            shape: instanceShape,
+            propsChanged: false,
+        }
+    }
+
+    // Rebuild the call expression
+    let newCallExpression: CallExpressionShape
+
+    if (isFlowLogic && transformedBodies.length > 0 && transformedConfig) {
+        // Rebuild flow logic with transformed config and bodies
+        newCallExpression = rebuildFlowLogicWithDatapills(
+            callExpression,
+            transformedConfig,
+            transformedBodies,
+            callee,
+            record,
+            transformedItemsArg // Pass transformed items for ForEach
+        )
+    } else {
+        // Rebuild Action/Subflow or flow logic without body
+        const originalActionDef = callExpression.getArgument(0, false)
+        let originalConfig = callExpression.getArgument(1)
+
+        // Apply config cleanup for Action/Subflow instances
+        if (!isFlowLogic && cleanupConfig && originalConfig) {
+            originalConfig = cleanupConfig(originalConfig, instanceShape)
+        }
+
+        const isFlowLogicWithOutputs = FLOW_LOGIC_WITH_OUTPUTS.includes(callee as FLOW_LOGIC)
+        if (isFlowLogicWithOutputs && cleanupConfig && transformedConfig) {
+            transformedConfig = cleanupConfig(transformedConfig, callExpression).asObject()
+        }
+
+        const newArgs: Shape[] = []
+
+        if (configArgIndex === 2) {
+            // Action/Subflow OR SetFlowVariables/AssignSubflowOutputs: definition/config, schema/config, inputs/values
+            newArgs.push(originalActionDef)
+            // For SetFlowVariables/AssignSubflowOutputs, use transformed schema arg if available
+            if (transformedSchemaArg) {
+                newArgs.push(transformedSchemaArg)
+            } else if (originalConfig) {
+                newArgs.push(originalConfig)
+            }
+            newArgs.push(Shape.from(record, transformedConfig))
+        } else if (configArgIndex === 1 && transformedConfig) {
+            // ForEach: items, config
+            // Use transformed items if available, otherwise use original
+            const itemsArg = transformedItemsArg || callExpression.getArgument(0, false)
+            newArgs.push(itemsArg)
+            newArgs.push(transformedConfig)
+        } else if (configArgIndex === 0 && transformedConfig) {
+            // Flow logic without body: just config
+            newArgs.push(transformedConfig)
+        }
+
+        newCallExpression = new CallExpressionShape({
+            source: callExpression.getSource(),
+            callee: callExpression.getCallee(),
+            args: newArgs,
+        })
+    }
+
+    // Rebuild instance (VariableStatement or CallExpression)
+    const rebuiltInstance = rebuildInstanceWithDatapills(instanceShape, newCallExpression, {
+        callExpression,
+        variableStatement,
+    })
+
+    return {
+        shape: rebuiltInstance,
+        propsChanged: true,
+    }
+}