@servicenow/sdk-build-plugins 4.2.0 → 4.4.0

package/src/flow/flow-logic/flow-logic-diagnostics.ts

@@ -0,0 +1,591 @@
+import type { FlowLogicInstanceShape, DoInParallelInstanceShape } from './flow-logic-shapes'
+import {
+    ts,
+    PropertyAccessShape,
+    TemplateExpressionShape,
+    IdentifierShape,
+    ArrayShape,
+    ObjectShape,
+    CallExpressionShape,
+    type Diagnostics,
+} from '@servicenow/sdk-build-core'
+import { FLOW_LOGIC } from './flow-logic-constants'
+import { getCallExpressionName } from '../../utils'
+import { findAncestorByCalleeName } from '../utils/utils'
+import { isDoInParallelShape, isSetFlowVariablesShape, isAssignSubflowOutputsShape } from './flow-logic-plugin-helpers'
+import { PillShape } from '../utils/data-pill-shapes'
+import { ARRAY_FLOW_DATA_TYPES, type ArrayFlowDataType } from '@servicenow/sdk-core/runtime/flow'
+import { FDInlineScriptCallShape } from '../plugins/inline-script-plugin'
+
+type FlowLogicValidator = (expr: FlowLogicInstanceShape) => string | undefined
+
+const FLOW_LOGIC_VALIDATORS: { [K in FLOW_LOGIC]: FlowLogicValidator } = {
+    [FLOW_LOGIC.GOBACKTO]: validateGoBackTo,
+    [FLOW_LOGIC.IF]: validateIf,
+    [FLOW_LOGIC.ELSEIF]: validateIf,
+    [FLOW_LOGIC.ELSE]: validateIf,
+    [FLOW_LOGIC.ENDFLOW]: validateEndFlow,
+    [FLOW_LOGIC.EXITLOOP]: validateExitLoop,
+    [FLOW_LOGIC.SKIP_ITERATION]: validateSkipIteration,
+    [FLOW_LOGIC.WAIT_FOR_A_DURATION]: validateWaitForADuration,
+    [FLOW_LOGIC.FOR_EACH]: validateForEach,
+    [FLOW_LOGIC.DO_IN_PARALLEL]: validateDoInParallel,
+    [FLOW_LOGIC.TRY_CATCH]: () => undefined,
+    [FLOW_LOGIC.SET_FLOW_VARIABLES]: validateSetFlowVariables,
+    [FLOW_LOGIC.ASSIGN_SUBFLOW_OUTPUTS]: validateAssignSubflowOutputs,
+}
+
+/**
+ * Main validation function for flow logic instances.
+ * Validates placement rules and context requirements for different flow logic types.
+ *
+ * @param expr - The flow logic instance shape to validate
+ * @returns Error message if validation fails, undefined if valid
+ */
+export function validateFlowLogic(expr: FlowLogicInstanceShape, diagnostics: Diagnostics): string | undefined {
+    const conditionType = expr.getCallee()
+    const node = expr.getOriginalNode()
+    const parent = node.getFirstAncestorByKind(ts.SyntaxKind.CallExpression)
+
+    if (!parent) {
+        return `'${conditionType}' can only be used inside a Flow() or Subflow() body`
+    }
+    const callExprName = getCallExpressionName(parent)
+
+    const allowedCallExprNames = ['Flow', 'Subflow', ...Object.values(FLOW_LOGIC)]
+
+    if (!allowedCallExprNames.includes(callExprName)) {
+        return `'${conditionType}' can only be used inside a Flow() or Subflow() body`
+    }
+
+    // Validate sibling relationships for ElseIf/Else BEFORE running type-specific validators
+    if (conditionType === FLOW_LOGIC.ELSEIF || conditionType === FLOW_LOGIC.ELSE) {
+        const sibling = node
+            .getParent()
+            ?.getPreviousSibling((n) => !ts.Node.isCommentStatement(n))
+            ?.asKind(ts.SyntaxKind.ExpressionStatement)
+            ?.getExpression()
+            .asKind(ts.SyntaxKind.CallExpression)
+
+        const siblingError = validateSibling(expr, sibling)
+        if (siblingError) {
+            return siblingError
+        }
+    }
+
+    const validator = FLOW_LOGIC_VALIDATORS[conditionType as FLOW_LOGIC]
+
+    if (!validator) {
+        diagnostics.error(expr, `Unsupported flow logic type for validation: ${conditionType}`)
+        return
+    }
+
+    return validator(expr)
+}
+
+function validateGoBackTo(expr: FlowLogicInstanceShape): string | undefined {
+    const placementError = validateGoBackToPlacement(expr)
+    if (placementError) {
+        return placementError
+    }
+    return undefined
+}
+
+/**
+ * Validates GoBackTo placement according to ServiceNow rules.
+ *
+ * Valid Go back to placement rules:
+ * - The Go back to flow logic must be within a branch of a parent flow logic block:
+ *   - Then branch of If, Else If, or Else flow logic
+ *   - Catch branch of Try flow logic
+ *   - Case branch of Decision flow logic
+ * - The Go back to flow logic must be outside of the Error handler section
+ *
+ * @param expr - The GoBackTo flow logic instance shape
+ * @returns Error message if placement is invalid, undefined if valid
+ */
+function validateGoBackToPlacement(expr: FlowLogicInstanceShape): string | undefined {
+    const node = expr.getOriginalNode()
+
+    // Check if GoBackTo is within a branch of a parent flow logic block
+    const parentLogic = findParentFlowLogic(node)
+    if (!parentLogic) {
+        return 'GoBackTo must be within a branch of a parent flow logic block (If/Else/Decision/Try/Catch)'
+    }
+
+    // Check if GoBackTo is outside of Error handler section
+    if (isWithinErrorHandler(node)) {
+        return 'GoBackTo must be outside of the Error handler section'
+    }
+
+    return undefined
+}
+
+/**
+ * Finds the nearest parent flow logic block (If/Else/Decision/Try/Catch/Parallel) in the AST.
+ * Used to validate GoBackTo placement within proper flow logic branches.
+ *
+ * @param node - The AST node to start searching from
+ * @returns The parent flow logic CallExpression, or undefined if not found
+ */
+function findParentFlowLogic(node: ts.Node | undefined): ts.CallExpression | undefined {
+    const current = node?.getFirstAncestorByKind(ts.SyntaxKind.CallExpression)
+
+    if (!current) {
+        return undefined
+    }
+
+    const callName = getCallExpressionName(current)
+
+    if ([FLOW_LOGIC.IF, FLOW_LOGIC.ELSEIF, FLOW_LOGIC.ELSE, 'TryCatch', 'MakeADecision'].includes(callName)) {
+        if (callName === 'TryCatch') {
+            // For TryCatch, GoBackTo should only be in the catch block, not in try block
+            if (!isInCatchBlock(node)) {
+                return undefined // Invalid placement - not in catch block
+            }
+        }
+
+        return current
+    }
+
+    return undefined
+}
+
+/**
+ * Checks if a node is within the catch block of a TryCatch flow logic.
+ * GoBackTo is only allowed in the catch block, not in the try block.
+ *
+ * @param node - The AST node to check
+ * @returns True if within catch block, false otherwise
+ */
+function isInCatchBlock(node: ts.Node | undefined): boolean {
+    const current = node
+        ?.getFirstAncestorByKind(ts.SyntaxKind.ArrowFunction)
+        ?.getParentIfKind(ts.SyntaxKind.PropertyAssignment)
+    if (current && current.getName() === 'catch') {
+        return true
+    }
+    return false
+}
+
+/**
+ * Checks if a node is within an Error handler section.
+ * GoBackTo flow logic must be outside of Error handler sections per ServiceNow rules.
+ *
+ * @param node - The AST node to check
+ * @returns True if within an Error handler, false otherwise
+ */
+function isWithinErrorHandler(_node: ts.Node | undefined): boolean {
+    // TODO: Add implementation when Error handler is added in Flow
+    return false
+}
+
+/**
+ * Validates sibling relationships for conditional flow logic (If/Else/ElseIf).
+ * Ensures proper chaining and structure of conditional blocks.
+ *
+ * @param expr - The flow logic instance shape
+ * @param sibling - The sibling CallExpression to validate against
+ * @returns Error message if sibling relationship is invalid, undefined if valid
+ */
+export function validateSibling(
+    expr: FlowLogicInstanceShape,
+    sibling: ts.CallExpression | undefined
+): string | undefined {
+    const conditionType = expr.getCallee()
+
+    const isElseClause = conditionType === FLOW_LOGIC.ELSE
+    const isElseIfClause = conditionType === FLOW_LOGIC.ELSEIF
+    const siblingName = sibling ? getCallExpressionName(sibling) : undefined
+
+    if (isElseClause || isElseIfClause) {
+        if (!sibling) {
+            return `${conditionType} clause must follow an If or ElseIf clause.`
+        }
+
+        const validPredecessors = [FLOW_LOGIC.IF, FLOW_LOGIC.ELSEIF]
+        if (!validPredecessors.includes(siblingName as FLOW_LOGIC)) {
+            return `${conditionType} clause must follow an If or ElseIf clause, but found ${siblingName}.`
+        }
+    }
+
+    return undefined
+}
+function validateIf(expr: FlowLogicInstanceShape): string | undefined {
+    const conditionType = expr.getCallee()
+
+    // If and ElseIf require a condition parameter, Else does not
+    if (conditionType === FLOW_LOGIC.IF || conditionType === FLOW_LOGIC.ELSEIF) {
+        const config = expr.getConfig()
+        const condition = config.get('condition')
+
+        if (!condition || condition.isUndefined()) {
+            return `${conditionType} requires a 'condition' field in the configuration object.`
+        }
+    }
+
+    return undefined
+}
+
+function validateEndFlow(expr: FlowLogicInstanceShape): string | undefined {
+    const placementError = validateEndFlowPlacement(expr)
+    if (placementError) {
+        return placementError
+    }
+    return undefined
+}
+
+function validateExitLoop(expr: FlowLogicInstanceShape): string | undefined {
+    return validateLoopPlacement(expr, 'Exit Loop')
+}
+
+function validateSkipIteration(expr: FlowLogicInstanceShape): string | undefined {
+    return validateLoopPlacement(expr, 'Skip Iteration')
+}
+
+function validateWaitForADuration(expr: FlowLogicInstanceShape): string | undefined {
+    const args = expr.getArguments()
+
+    if (args.length !== 1) {
+        return `Expected 2 arguments for ${expr.getCallee()}, but received ${args.length}`
+    }
+    return undefined
+}
+
+function validateForEach(expr: FlowLogicInstanceShape): string | undefined {
+    // Validate that forEach has the correct number of arguments
+    const args = expr.getArguments()
+    if (args.length < 2 || args.length > 3) {
+        return `ForEach requires 2-3 arguments (items, config, optional body), but received ${args.length}`
+    }
+
+    // Validate config argument
+    try {
+        expr.getSysId()
+    } catch (error) {
+        return 'ForEach: Second argument (config) must be an object with valid $id property'
+    }
+
+    // Validate items argument (first argument) - must be an array type
+    const itemsArg = expr.getArgument(0, false)
+    if (!itemsArg || itemsArg.isUndefined()) {
+        return 'ForEach: First argument (items) is required and cannot be undefined'
+    }
+
+    // Valid array types - imported from core package to ensure consistency
+
+    // Helper to validate type hint
+    const validateTypeHint = (typeHint: string): string | undefined => {
+        if (!ARRAY_FLOW_DATA_TYPES.includes(typeHint as ArrayFlowDataType)) {
+            return `ForEach requires an array type. The dataPill type '${typeHint}' is not an array type. Use array types like 'array.object', 'array.string', 'records', etc.`
+        }
+        return undefined
+    }
+
+    // Check if items is a PillShape (most common case - after DataPillPlugin transformation)
+    if (itemsArg instanceof PillShape) {
+        const typeHint = itemsArg.getType()
+        if (typeHint) {
+            const error = validateTypeHint(typeHint)
+            if (error) {
+                return error
+            }
+        }
+    }
+
+    // Check if items is a CallExpressionShape (before DataPillPlugin transformation)
+    if (itemsArg instanceof CallExpressionShape) {
+        const callee = itemsArg.getCallee()
+        if (callee === 'wfa.dataPill') {
+            const dataPillArgs = itemsArg.getArguments()
+            if (dataPillArgs.length >= 2 && dataPillArgs[1]?.isString()) {
+                const typeHint = dataPillArgs[1].asString().getValue()
+                const error = validateTypeHint(typeHint)
+                if (error) {
+                    return error
+                }
+            }
+        }
+    }
+
+    return undefined
+}
+
+function validateDoInParallel(expr: FlowLogicInstanceShape): string | undefined {
+    if (isDoInParallelShape(expr)) {
+        const doInParallelExpr = expr as DoInParallelInstanceShape
+        const originalNode = doInParallelExpr.getOriginalNode()
+
+        // Check for nested DoInParallel
+        const parentDoInParallel = findAncestorByCalleeName(originalNode, FLOW_LOGIC.DO_IN_PARALLEL)
+        if (parentDoInParallel) {
+            return 'Nested DoInParallel calls are not allowed. DoInParallel cannot be used within another DoInParallel block.'
+        }
+    }
+
+    return undefined
+}
+
+/**
+ * Validates SetFlowVariables flow logic instance.
+ * Performs comprehensive validation of arguments, types, and structure.
+ *
+ * **Validations performed:**
+ * 1. Argument count: Must have exactly 3 arguments
+ * 2. Config object: Must contain required $id property
+ * 3. Schema argument: Must be params.flowVariables (schema reference)
+ * 4. Values object: Must be non-empty
+ * 5. Variable names: Cannot be empty or whitespace
+ * 6. Variable values: Must be valid types (string, number, boolean, or datapill)
+ *
+ * **Valid value types:**
+ * - String literals: "hello"
+ * - Numbers: 42, 3.14
+ * - Booleans: true, false
+ * - Objects: { a: "value", b: 42 } (ObjectShape - for FlowObject types)
+ * - Arrays: [1, 2, 3] (ArrayShape - for FlowArray types)
+ * - Datapills: params.trigger.name, params.complexObject (PropertyAccessShape)
+ * - Template expressions: `Hello ${params.trigger.name}` (TemplateExpressionShape)
+ *
+ * @param expr - The SetFlowVariables flow logic instance shape
+ * @returns Error message if validation fails, undefined if valid
+ *
+ * @example
+ * // Valid usage
+ * wfa.flowLogic.setFlowVariables(
+ *   { $id: Now.ID['...'] },
+ *   params.flowVariables,  // ← Schema reference (2nd argument)
+ *   { user: params.trigger.name, count: 42, active: true }
+ * )
+ */
+function validateSetFlowVariables(expr: FlowLogicInstanceShape): string | undefined {
+    if (!isSetFlowVariablesShape(expr)) {
+        return undefined
+    }
+
+    // Validate argument count
+    const args = expr.getArguments()
+    if (args.length !== 3) {
+        return `SetFlowVariables requires exactly 3 arguments (config, schema, values), but received ${args.length}`
+    }
+
+    // Validate config argument
+    try {
+        expr.getSysId()
+    } catch (error) {
+        return 'SetFlowVariables: First argument (config) must be an object with valid $id property'
+    }
+
+    // Validate values argument (third argument)
+    const valuesArg = expr.getVariablesToSet()
+    if (!valuesArg || valuesArg.isUndefined()) {
+        return 'SetFlowVariables: Third argument (values) is required'
+    }
+
+    if (!valuesArg.isObject()) {
+        return 'SetFlowVariables: Third argument (values) must be an object'
+    }
+
+    // Validate that values object is not empty
+    const entries = Array.from(valuesArg.entries({ resolve: false }))
+    if (entries.length === 0) {
+        return 'SetFlowVariables: Values object cannot be empty - at least one variable must be set'
+    }
+
+    // Validate each value in the object
+    for (const [key, valueShape] of entries) {
+        if (!key || key.trim() === '') {
+            return 'SetFlowVariables: Variable names cannot be empty'
+        }
+
+        // Check if value is valid (string, datapill, template expression, or inline script)
+        if (valueShape.isUndefined()) {
+            return `SetFlowVariables: Variable '${key}' has undefined value`
+        }
+
+        // Values can be: strings, numbers, booleans, objects, arrays, datapills, template expressions, or inline scripts
+        const isDatapill = valueShape instanceof PropertyAccessShape || valueShape instanceof TemplateExpressionShape
+        const isInlineScript = valueShape instanceof FDInlineScriptCallShape
+        const isIdentifier = valueShape instanceof IdentifierShape
+        const isArrayOrObject = valueShape instanceof ArrayShape || valueShape instanceof ObjectShape
+        const isValidType =
+            valueShape.isString() ||
+            valueShape.isNumber() ||
+            valueShape.isBoolean() ||
+            isDatapill ||
+            isArrayOrObject ||
+            isInlineScript
+
+        if (!isValidType) {
+            // Provide specific error message for unsupported types
+            if (isIdentifier) {
+                return `SetFlowVariables: Variable '${key}' cannot use local variable references. Use direct values (literals) or datapills (e.g., params.someField) instead`
+            }
+            return `SetFlowVariables: Variable '${key}' has invalid value type. Expected string, number, boolean, object, array, or datapill expression`
+        }
+    }
+
+    return undefined
+}
+
+/**
+ * Validates AssignSubflowOutputs flow logic instance.
+ * Performs comprehensive validation of arguments, types, structure, and placement.
+ *
+ * **Validations performed:**
+ * 1. Placement: Must be within a Subflow or SubflowDefinition (not in regular Flow)
+ * 2. Argument count: Must have exactly 3 arguments
+ * 3. Config object: Must contain required $id property
+ * 4. Schema argument: Must be params.outputs (schema reference)
+ * 5. Values object: Must be non-empty
+ * 6. Output names: Cannot be empty or whitespace
+ * 7. Output values: Must be valid types (string, number, boolean, or datapill)
+ *
+ * **Valid value types:**
+ * - String literals: "success"
+ * - Numbers: 42, 3.14
+ * - Booleans: true, false
+ * - Objects: { a: "value", b: 42 } (ObjectShape - for FlowObject types)
+ * - Arrays: [1, 2, 3] (ArrayShape - for FlowArray types)
+ * - Datapills: params.action.result, params.complexObject (PropertyAccessShape)
+ * - Template expressions: `Result: ${params.action.result}` (TemplateExpressionShape)
+ *
+ * **Important:** AssignSubflowOutputs can ONLY be used within Subflow or SubflowDefinition.
+ * Using it in a regular Flow will result in a validation error.
+ *
+ * @param expr - The AssignSubflowOutputs flow logic instance shape
+ * @returns Error message if validation fails, undefined if valid
+ *
+ * @example
+ * // Valid usage (within Subflow)
+ * Subflow({
+ *   outputs: { result: StringColumn(...) }
+ * }, (params) => {
+ *   wfa.flowLogic.assignSubflowOutputs(
+ *     { $id: Now.ID['...'] },
+ *     params.outputs,  // ← Schema reference (2nd argument)
+ *     { result: params.action.data, status: "complete" }
+ *   )
+ * })
+ */
+function validateAssignSubflowOutputs(expr: FlowLogicInstanceShape): string | undefined {
+    if (!isAssignSubflowOutputsShape(expr)) {
+        return undefined
+    }
+
+    // Validate that this is called within a SubflowDefinition or Subflow
+    const node = expr.getOriginalNode()
+    const subflowAncestor =
+        findAncestorByCalleeName(node, 'SubflowDefinition') || findAncestorByCalleeName(node, 'Subflow')
+    if (!subflowAncestor) {
+        return 'AssignSubflowOutputs can only be used within a SubflowDefinition or Subflow'
+    }
+
+    // Validate argument count
+    const args = expr.getArguments()
+    if (args.length !== 3) {
+        return `AssignSubflowOutputs requires exactly 3 arguments (config, schema, values), but received ${args.length}`
+    }
+
+    // Validate config argument
+    try {
+        expr.getSysId()
+    } catch (error) {
+        return 'AssignSubflowOutputs: First argument (config) must be an object with valid $id property'
+    }
+
+    // Validate values argument (third argument)
+    const valuesArg = expr.getAssignedSubflowOutputs()
+    if (!valuesArg || valuesArg.isUndefined()) {
+        return 'AssignSubflowOutputs: Third argument (values) is required'
+    }
+
+    if (!valuesArg.isObject()) {
+        return 'AssignSubflowOutputs: Third argument (values) must be an object'
+    }
+
+    // Validate that values object is not empty
+    const entries = Array.from(valuesArg.entries({ resolve: false }))
+    if (entries.length === 0) {
+        return 'AssignSubflowOutputs: Values object cannot be empty - at least one output must be assigned'
+    }
+
+    // Validate each value in the object
+    for (const [key, valueShape] of entries) {
+        if (!key || key.trim() === '') {
+            return 'AssignSubflowOutputs: Output names cannot be empty'
+        }
+
+        // Check if value is valid (string, datapill, template expression, or inline script)
+        if (valueShape.isUndefined()) {
+            return `AssignSubflowOutputs: Output '${key}' has undefined value`
+        }
+
+        // Values can be: strings, numbers, booleans, objects, arrays, datapills, template expressions, or inline scripts
+        const isDatapill = valueShape instanceof PropertyAccessShape || valueShape instanceof TemplateExpressionShape
+        const isInlineScript = valueShape instanceof FDInlineScriptCallShape
+        const isIdentifier = valueShape instanceof IdentifierShape
+        const isArrayOrObject = valueShape instanceof ArrayShape || valueShape instanceof ObjectShape
+        const isValidType =
+            valueShape.isString() ||
+            valueShape.isNumber() ||
+            valueShape.isBoolean() ||
+            isDatapill ||
+            isArrayOrObject ||
+            isInlineScript
+
+        if (!isValidType) {
+            // Provide specific error message for unsupported types
+            if (isIdentifier) {
+                return `AssignSubflowOutputs: Output '${key}' cannot use local variable references. Use direct values (literals) or datapills (e.g., params.someField) instead`
+            }
+            return `AssignSubflowOutputs: Output '${key}' has invalid value type. Expected string, number, boolean, object, array, or datapill expression`
+        }
+    }
+
+    return undefined
+}
+
+/**
+ * Validates that a loop control flow logic (Exit Loop or Skip Iteration) is within a valid loop construct.
+ *
+ * @param expr - The flow logic instance shape to validate
+ * @param logicName - The name of the logic for error messages (e.g., 'Exit Loop', 'Skip Iteration')
+ * @returns Error message if placement is invalid, undefined if valid
+ */
+function validateLoopPlacement(expr: FlowLogicInstanceShape, logicName: string): string | undefined {
+    const node = expr.getOriginalNode()
+
+    // Loop constructs that loop control flow logic can be used within
+    const LOOP_CONSTRUCTS = [
+        FLOW_LOGIC.FOR_EACH,
+        // TODO: Add FLOW_LOGIC.DO_UNTIL when implemented
+    ]
+
+    const parentLoop = findAncestorByCalleeName(node, ...LOOP_CONSTRUCTS)
+    if (!parentLoop) {
+        return `${logicName} must be used within a Do Until or For Each loop`
+    }
+
+    return undefined
+}
+
+function validateEndFlowPlacement(expr: FlowLogicInstanceShape): string | undefined {
+    const node = expr.getOriginalNode()
+
+    // Block constructs that End Flow can be used within
+    const END_FLOW_BLOCKS = [
+        FLOW_LOGIC.FOR_EACH,
+        FLOW_LOGIC.IF,
+        FLOW_LOGIC.ELSEIF,
+        FLOW_LOGIC.ELSE,
+        // TODO: Add FLOW_LOGIC.DO_UNTIL when implemented
+    ]
+
+    const parentBlock = findAncestorByCalleeName(node, ...END_FLOW_BLOCKS)
+    if (!parentBlock) {
+        return 'End Flow must be used within a Do Until, For Each, or If block'
+    }
+
+    return undefined
+}