@servicenow/sdk-build-plugins 4.1.1 → 4.3.0

package/src/flow/utils/utils.ts

@@ -0,0 +1,395 @@
+import {
+    CallExpressionShape,
+    type Database,
+    type Diagnostics,
+    type IdentifierShape,
+    type Logger,
+    type ObjectShape,
+    type PropertyAccessShape,
+    type Record,
+    type Shape,
+    type TemplateExpressionShape,
+    type Transform,
+    ts,
+    VariableStatementShape,
+} from '@servicenow/sdk-build-core'
+import { PillShape, PillTemplateShape } from '../utils/data-pill-shapes'
+import { DataPillPlugin } from '../plugins/flow-data-pill-plugin'
+import { TriggerInstancePlugin } from '../plugins/flow-trigger-instance-plugin'
+import { CallExpressionPlugin } from '../../call-expression-plugin'
+import { FlowLogicPlugin } from '../flow-logic/flow-logic-plugin'
+import { FlowInstancePlugin } from '../plugins/flow-instance-plugin'
+import { FDInstanceShape } from './flow-shapes'
+import { CORE_ACTIONS_PREFIX, CORE_ACTIONS_SYS_ID_NAME_MAP, UNSUPPORTED_FLOW_DESCENDANTS } from './flow-constants'
+
+export function sysIdToUuid(id: string): string {
+    return id.length === 32
+        ? `${id.slice(0, 8)}-${id.slice(8, 12)}-${id.slice(12, 16)}-${id.slice(16, 20)}-${id.slice(20)}`
+        : id // already UUID or unexpected
+}
+
+export function uuidToSysId(id: string): string {
+    return id.includes('-') ? id.replace(/-/g, '') : id // already sys_id or unexpected
+}
+
+/**
+ * Get the identifier name from an original source (TypeScript node)
+ * Searches for a VariableDeclaration ancestor and extracts the identifier name
+ *
+ * @param originalSource - The original TypeScript source node
+ * @returns The identifier name if found, undefined otherwise
+ */
+export function getIdentifierFromSource(originalSource: unknown): string | undefined {
+    if (ts.Node.isNode(originalSource)) {
+        const node = originalSource as ts.Node
+        const varDecl = node.getFirstAncestorByKind(ts.SyntaxKind.VariableDeclaration)
+        const idNode = varDecl?.getNameNode()
+        if (idNode) {
+            return idNode.getText()
+        }
+    }
+    return undefined
+}
+
+/**
+ * Get the identifier name for an action/subflow instance from its original source
+ * Only checks if this node is DIRECTLY wrapped in a VariableDeclaration (not any ancestor)
+ * This prevents scope collisions where inner actions inherit parent Subflow/Flow variable names
+ *
+ * Use this specifically for preserving action/subflow variable names during transform
+ *
+ * @param originalSource - The original source to extract the identifier from
+ * @returns The identifier name if found, undefined otherwise
+ */
+export function getDirectVariableIdentifier(originalSource: unknown): string | undefined {
+    if (!ts.Node.isNode(originalSource)) {
+        return undefined
+    }
+
+    const node = originalSource as ts.Node
+
+    // Only check immediate parent, not any ancestor
+    // This prevents actions inside Subflow/Flow bodies from inheriting the Subflow/Flow's variable name
+    const varDecl = node.getParentIfKind(ts.SyntaxKind.VariableDeclaration)
+    if (!varDecl) {
+        return undefined
+    }
+
+    const idNode = varDecl.getNameNode()
+    return idNode?.getText()
+}
+
+/**
+ * Get the identifier name from a record's original source
+ * Convenience wrapper around getIdentifierFromSource for Record types
+ *
+ * @param record - The record to extract the identifier from
+ * @returns The identifier name if found, undefined otherwise
+ */
+export function getIdentifierFromRecord(record: Record): string | undefined {
+    return getIdentifierFromSource(record.getOriginalSource())
+}
+
+/**
+ * Get the identifier name from a shape's original source
+ * Convenience wrapper around getIdentifierFromSource for Shape types
+ *
+ * @param shape - The shape to extract the identifier from
+ * @returns The identifier name if found, undefined otherwise
+ */
+export function getIdentifierFromShape(shape: Shape): string | undefined {
+    return getIdentifierFromSource(shape.getOriginalSource())
+}
+
+/**
+ * Set of allowed FlowValueType helper function names for flow variable validation
+ *
+ * @constant {Set<string>}
+ * @example
+ * ```typescript
+ * // Supported types: StringColumn, IntegerColumn, DecimalColumn, ReferenceColumn,
+ * // DateTimeColumn, BooleanColumn, GenericColumn, FlowObject, FlowArray
+ * if (ALLOWED_VARIABLE_CALLEES.has('StringColumn')) {
+ *   // StringColumn is supported
+ * }
+ * ```
+ */
+export const ALLOWED_VARIABLE_CALLEES = new Set([
+    'StringColumn',
+    'IntegerColumn',
+    'DecimalColumn',
+    'ReferenceColumn',
+    'DateTimeColumn',
+    'BooleanColumn',
+    'FloatColumn',
+    'JsonColumn',
+    'GenericColumn',
+    'FlowObject',
+    'FlowArray',
+])
+
+export const ALLOWED_VARIABLE_CALLEES_IN_FLOW_OBJECT = new Set([
+    'StringColumn',
+    'IntegerColumn',
+    'DecimalColumn',
+    'DateTimeColumn',
+    'BooleanColumn',
+    'FlowObject',
+    'FlowArray',
+])
+
+/**
+ * Validates a single flow variable call expression for type safety and correctness
+ *
+ * @param variableCall - The CallExpressionShape representing the variable definition
+ * @param path - The path/name of the variable for error reporting
+ * @param diagnostics - Diagnostics object for reporting validation errors
+ *
+ * @example
+ * ```typescript
+ * // Validates allowed types, GenericColumn columnType (json/float only),
+ * // and recursively validates FlowArray/FlowObject structures
+ * validateFlowVariableCall(StringColumn({ label: 'Name' }), 'flow_variables.userName', diagnostics)
+ * ```
+ */
+export function validateFlowVariableCall(variableCall: CallExpressionShape, path: string, diagnostics: Diagnostics) {
+    const callee = variableCall.getCallee()
+
+    if (!ALLOWED_VARIABLE_CALLEES.has(callee)) {
+        diagnostics.error(
+            variableCall.getOriginalNode(),
+            `${path} uses unsupported type '${callee}'. Only FlowValueType helpers are allowed.`
+        )
+    } else if (callee === 'GenericColumn') {
+        const arg0 = variableCall.getArgument(0)
+        const colTypeNode = arg0.ifObject()?.get('columnType')
+        const colType = colTypeNode?.ifString()?.asString().getValue()
+        if (colType && colType !== 'json' && colType !== 'float') {
+            diagnostics.error(
+                colTypeNode!.getOriginalNode(),
+                `${path} GenericColumn supports only columnType 'json' or 'float'. Found '${colType}'.`
+            )
+        }
+    } else if (callee === 'FlowArray') {
+        // Validate FlowArray structure recursively
+        // Primitive types (StringColumn, IntegerColumn, etc.) are now supported as elementType
+        const arg0 = variableCall.getArgument(0)
+        const elementTypeNode = arg0.ifObject()?.get('elementType')
+        if (elementTypeNode?.if(CallExpressionShape)) {
+            const elementTypeCall = elementTypeNode.as(CallExpressionShape)
+            const elementTypeCallee = elementTypeCall.getCallee()
+
+            // Recursively validate if elementType is FlowObject or FlowArray
+            if (elementTypeCallee === 'FlowObject') {
+                validateFlowObjectFields(elementTypeCall, `${path}.elementType`, diagnostics)
+            } else if (elementTypeCallee === 'FlowArray') {
+                validateFlowVariableCall(elementTypeCall, `${path}.elementType`, diagnostics)
+            }
+            // Primitive column types (StringColumn, IntegerColumn, etc.) are allowed - no validation needed
+        }
+    } else if (callee === 'FlowObject') {
+        validateFlowObjectFields(variableCall, path, diagnostics)
+    }
+}
+
+/**
+ * Recursively validates FlowObject fields for nested FlowArray violations and other type validations
+ *
+ * @param flowObjectCall - The CallExpressionShape representing the FlowObject definition
+ * @param path - The path/name of the variable for error reporting
+ * @param diagnostics - Diagnostics object for reporting validation errors
+ *
+ * @example
+ * ```typescript
+ * // Validates all field types are allowed, recursively validates nested
+ * // FlowArray/FlowObject structures, and checks GenericColumn columnType
+ * FlowObject({ fields: { name: StringColumn({...}), data: FlowArray({...}) } })
+ * ```
+ */
+export function validateFlowObjectFields(flowObjectCall: CallExpressionShape, path: string, diagnostics: Diagnostics) {
+    const arg0 = flowObjectCall.getArgument(0)
+    if (arg0.ifObject()) {
+        const fieldsNode = arg0.asObject().get('fields')
+        fieldsNode
+            ?.ifObject()
+            ?.entries()
+            .forEach(([fieldName, fieldValue]) => {
+                if (fieldValue.if(CallExpressionShape)) {
+                    const fieldCall = fieldValue.as(CallExpressionShape)
+                    const fieldPath = `${path}.${fieldName}`
+                    const fieldCallee = fieldCall.getCallee()
+
+                    if (!ALLOWED_VARIABLE_CALLEES.has(fieldCallee)) {
+                        diagnostics.error(
+                            fieldValue.getOriginalNode(),
+                            `${fieldPath} uses unsupported type '${fieldCallee}'. Only FlowValueType helpers are allowed.`
+                        )
+                        return
+                    }
+
+                    // work around until DEF0797916 is fixed : Check if ReferenceColumn, JSONColumn, FloatColumn is used inside a FlowObject in flow variables
+                    if (!ALLOWED_VARIABLE_CALLEES_IN_FLOW_OBJECT.has(fieldCallee)) {
+                        diagnostics.error(
+                            fieldValue.getOriginalNode(),
+                            `Unsupported type '${fieldCallee}' inside flow object in the flow variable is not allowed for flow variables at ${fieldPath}.`
+                        )
+                        return
+                    }
+
+                    validateFlowVariableCall(fieldCall, fieldPath, diagnostics)
+                } else {
+                    diagnostics.error(
+                        fieldValue.getOriginalNode(),
+                        `${path}.${fieldName} is not a valid variable expression.`
+                    )
+                }
+            })
+    }
+}
+
+/**
+ * Recursively searches ancestors of a node to find a CallExpression
+ * with any of the given callee names.
+ *
+ * @param node - The starting node
+ * @param calleeNames - One or more function names to match against
+ * @returns The CallExpression if found, otherwise undefined
+ */
+export function findAncestorByCalleeName(
+    node: ts.Node | undefined,
+    ...calleeNames: string[]
+): ts.CallExpression | undefined {
+    if (!node) {
+        return undefined
+    }
+    if (ts.Node.isCallExpression(node)) {
+        const expr = node.getExpression()
+        // Handle simple identifiers: Flow, Subflow, etc.
+        if (ts.Node.isIdentifier(expr) && calleeNames.includes(expr.getText())) {
+            return node
+        }
+        // Handle property access expressions: wfa.flowLogic.if, wfa.flowLogic.forEach, etc.
+        if (ts.Node.isPropertyAccessExpression(expr) && calleeNames.includes(expr.getText())) {
+            return node
+        }
+    }
+    // recurse upwards
+    return findAncestorByCalleeName(node.getFirstAncestorByKind(ts.SyntaxKind.CallExpression), ...calleeNames)
+}
+
+/**
+ * Resolves a data pill shape by transforming it and handling trigger pills
+ * @param shape - The shape to resolve (PropertyAccessShape, TemplateExpressionShape, or IdentifierShape)
+ * @param transform - The transform instance
+ * @returns The resolved value or the original shape value if not a data pill
+ */
+export async function resolveDataPillShape(
+    shape: PillShape | PropertyAccessShape | TemplateExpressionShape | IdentifierShape,
+    transform: Transform
+): Promise<unknown> {
+    const mayBePills = await transform.toSubclass(shape, DataPillPlugin)
+    if (mayBePills.success) {
+        let processedShape = mayBePills.value
+
+        // Magical code to handle trigger pills :) as they do not follow the same pattern as other pills
+        // subflow inputs will be {{subflow.<pill-name>}}, flow variable {{flow_variable.<pill-name>}} but for triggers {{Created_1.<pill-name>}}
+        if (processedShape instanceof PillShape && processedShape.getRootIdentifier() === 'trigger') {
+            processedShape = await resolveTriggerPills(processedShape, transform)
+        }
+        // Magical code to handle PillTemplateShape with trigger pills
+        else if (processedShape.is(PillTemplateShape)) {
+            // Process each pill shape in the template
+            const pillShapes = processedShape.getParts()
+            const elements = pillShapes.getElements(false)
+
+            for (const shapePart of elements) {
+                if (shapePart instanceof PillShape && shapePart.getRootIdentifier() === 'trigger') {
+                    await resolveTriggerPills(shapePart, transform) // mutates shapePart
+                }
+            }
+        }
+
+        return processedShape.getValue()
+    }
+
+    return shape.getValue()
+}
+
+async function resolveTriggerPills(shape: PillShape, transform: Transform) {
+    const flowCallExpression = findAncestorByCalleeName(shape.getOriginalNode(), 'Flow')
+    if (flowCallExpression instanceof ts.CallExpression) {
+        if (flowCallExpression?.getArguments()?.length > 2) {
+            const triggerExpression = flowCallExpression?.getArguments()[1]
+            const triggerRecord = triggerExpression
+                ? await transform.toRecord(triggerExpression, CallExpressionPlugin, TriggerInstancePlugin)
+                : { success: false, value: undefined }
+
+            if (triggerRecord.success && triggerRecord.value?.isRecord()) {
+                const triggerName = triggerRecord.value.asRecord().get('name')?.getValue() as string
+                shape.setRootIdentifier(triggerName.concat('_1')) // <-- TODO: Temp code to match what UI does now, but raised a defect against FD team to fix it in the app itself.
+                return shape
+            }
+        }
+    }
+    return shape
+}
+
+/**
+ * Function to get the record by transforming the FDInstanceShape
+ * @param shape - The shape to transform (VariableStatementShape, CallExpressionShape)
+ * @param transform - The transform instance
+ * @returns The instance record of the FDInstanceShape
+ */
+export async function getRecordFromFlowInstaceShape(shape: Shape, transform: Transform) {
+    let instanceRecord: Record | undefined
+    const callExpressionShape = shape.is(VariableStatementShape) ? shape.getInitializer() : shape
+    if (callExpressionShape.is(CallExpressionShape)) {
+        //Get the Flow Instance Shape using toSubclass() utility
+        const flowInstanceShape = await transform.toSubclass(callExpressionShape, FlowLogicPlugin, FlowInstancePlugin)
+        if (flowInstanceShape.success && flowInstanceShape.value.is(FDInstanceShape)) {
+            //Get the Flow Instance Record using toRecord() utility
+            const flowInstanceRecord = await transform.toRecord(
+                flowInstanceShape.value,
+                FlowLogicPlugin,
+                FlowInstancePlugin
+            )
+            if (flowInstanceRecord.success) {
+                instanceRecord = flowInstanceRecord.value
+            }
+        }
+    }
+    return instanceRecord
+}
+
+export function checkForUnsupportedFlowDescendants(descendants: Database, record: Record, logger: Logger): boolean {
+    if (descendants) {
+        for (const tableName of UNSUPPORTED_FLOW_DESCENDANTS) {
+            const descendantRecords = descendants.query(tableName)
+
+            if (descendantRecords?.length > 0) {
+                logger.warn(
+                    `Unsupported flow descendant tables found, falling back to Record() api. Flow = ${record.getId().getValue()}, table = ${tableName}`
+                )
+
+                return true
+            }
+        }
+    }
+    return false
+}
+
+export const getCoreActionIdentifier = (sysId: string) => {
+    const actionName = CORE_ACTIONS_SYS_ID_NAME_MAP[sysId]
+    return actionName ? `${CORE_ACTIONS_PREFIX}.${actionName}` : undefined
+}
+
+/**
+ * Extracts the order value from a record for sorting purposes.
+ * Converts the 'order' field to a number, defaulting to 0 if not present or invalid.
+ *
+ * @param record - The record containing the order field
+ * @returns The numeric order value
+ */
+export function getOrder(x: ObjectShape) {
+    return Number(x.get('order').asString()?.getValue() ?? 0)
+}