@servicenow/sdk-build-plugins 4.2.0 → 4.4.0

package/src/flow/plugins/flow-action-definition-plugin.ts

@@ -0,0 +1,295 @@
+import { CallExpressionShape, deleteMultipleDiff, Plugin, Record, UndefinedShape } from '@servicenow/sdk-build-core'
+import { buildVariableRecords, complexObjectMatchesIoRecord } from '../utils/flow-io-to-record'
+import { generateXML } from '../utils/flow-to-xml'
+import { slugifyString } from '../utils/flow-constants'
+import { ArrowFunctionShape } from '../../arrow-function-plugin'
+import { StepInstanceShape } from './step-instance-plugin'
+
+const actionDefRelationships = {
+    sys_hub_step_instance: {
+        via: 'action',
+        descendant: true,
+        relationships: {
+            sys_variable_value: {
+                via: 'document_key',
+                descendant: true,
+            },
+            sys_element_mapping: {
+                via: 'id',
+                descendant: true,
+            },
+            sys_hub_step_ext_input: {
+                via: 'model_id',
+                descendant: true,
+                relationships: {
+                    sys_documentation: {
+                        via: { name: 'name', element: 'element' },
+                        descendant: true,
+                    },
+                },
+            },
+            sys_hub_step_ext_output: {
+                via: 'model_id',
+                descendant: true,
+                relationships: {
+                    sys_documentation: {
+                        via: { name: 'name', element: 'element' },
+                        descendant: true,
+                    },
+                },
+            },
+            sys_hub_input_scripts: {
+                via: 'instance',
+                descendant: true,
+            },
+        },
+    },
+    sys_hub_action_input: {
+        via: 'model',
+        descendant: true,
+        relationships: {
+            sys_documentation: {
+                via: { name: 'name', element: 'element' },
+                descendant: true,
+            },
+            sys_choice: {
+                via: { name: 'name', element: 'element' },
+                descendant: true,
+            },
+            sys_variable_value: {
+                via: 'variable',
+                descendant: true,
+            },
+            sys_complex_object: {
+                via: [complexObjectMatchesIoRecord],
+                descendant: true,
+                inverse: true,
+            },
+        },
+    },
+    sys_hub_action_output: {
+        via: 'model',
+        descendant: true,
+        relationships: {
+            sys_documentation: {
+                via: { name: 'name', element: 'element' },
+                descendant: true,
+            },
+            sys_choice: {
+                via: { name: 'name', element: 'element' },
+                descendant: true,
+            },
+            sys_variable_value: {
+                via: 'variable',
+                descendant: true,
+            },
+            sys_complex_object: {
+                via: [complexObjectMatchesIoRecord],
+                descendant: true,
+                inverse: true,
+            },
+            sys_hub_input_scripts: {
+                via: 'instance',
+                descendant: true,
+            },
+        },
+    },
+    sys_hub_action_status_metadata: {
+        via: 'action_type_id',
+        descendant: true,
+        relationships: {
+            sys_hub_status_condition: {
+                via: 'action_status_metadata_id',
+                descendant: true,
+            },
+        },
+    },
+}
+
+export const ActionDefinitionPlugin = Plugin.create({
+    name: 'ActionDefinitionPlugin',
+    records: {
+        sys_hub_action_type_definition: {
+            relationships: {
+                ...actionDefRelationships,
+                sys_hub_action_type_snapshot: {
+                    via: 'parent_action',
+                    descendant: true,
+                    relationships: {
+                        ...actionDefRelationships,
+                        sys_element_mapping: {
+                            via: 'id',
+                            descendant: true,
+                        },
+                        sys_hub_step_ext_input: {
+                            via: 'model',
+                            descendant: true,
+                        },
+                        sys_hub_step_ext_output: {
+                            via: 'model',
+                            descendant: true,
+                        },
+                        sys_translated_text: {
+                            via: 'documentkey',
+                            descendant: true,
+                        },
+                    },
+                },
+                sys_hub_action_plan: {
+                    via: 'action_id',
+                    descendant: true,
+                },
+                sys_element_mapping: {
+                    via: 'id',
+                    descendant: true,
+                },
+                sys_translated_text: {
+                    via: 'documentkey',
+                    descendant: true,
+                },
+            },
+            toShape(record, { logger }) {
+                logger.warn(`Unsupported record type: ${record.getTable()}, Action definition is not implemented yet`)
+                return { success: false }
+                // TODO Uncomment this in next release
+                // const inputs = buildVariableShapes(descendants.query('sys_hub_action_input'), descendants)
+                // const outputs = buildVariableShapes(descendants.query('sys_hub_action_output'), descendants)
+
+                // // Create the CallExpressionShape for the action definition
+                // const callExpression = new CallExpressionShape({
+                //     source: record,
+                //     callee: 'ActionDefinition',
+                //     args: [
+                //         record.transform(({ $ }) => ({
+                //             $id: $.val(NowIdShape.from(record)),
+                //             name: $,
+                //             annotation: $.def(''),
+                //             description: $.def(''),
+                //             natlang: $.def(''),
+                //             access: $.def('public'),
+                //             category: $.def(''),
+                //             protection: $.from('sys_policy').def(''),
+                //             inputs: $.val(inputs),
+                //             outputs: $.val(outputs),
+                //         })),
+                //     ],
+                // })
+
+                // // Try to get the existing identifier from the record source, fallback to slugified name
+                // const actionName =
+                //     getIdentifierFromRecord(record) ??
+                //     slugifyString(String(record.get('internal_name')?.getValue() || record.get('name')?.getValue()))
+
+                // return {
+                //     success: true,
+                //     value: new VariableStatementShape({
+                //         source: record,
+                //         variableName: actionName,
+                //         initializer: callExpression,
+                //         isExported: true,
+                //     }),
+                // }
+            },
+            async diff(existing, incoming, descendants, context) {
+                return deleteMultipleDiff(existing, incoming, descendants, context)
+            },
+            toFile(record, { config, database }) {
+                return generateXML(record, { config, database })
+            },
+        },
+        sys_hub_action_input: {
+            coalesce: ['model', 'element'],
+        },
+        sys_hub_action_output: {
+            coalesce: ['model', 'element'],
+        },
+        sys_variable_value: {
+            coalesce: ['document_key', 'variable'],
+        },
+        sys_complex_object: {
+            coalesce: ['name'],
+        },
+    },
+    shapes: [
+        {
+            shape: CallExpressionShape,
+            fileTypes: ['fluent'],
+            async toRecord(callExpression, { factory, diagnostics }) {
+                if (callExpression.getCallee() !== 'ActionDefinition') {
+                    return { success: false }
+                }
+                const relatedRecords: Record[] = []
+                const actionConfiguration = callExpression.getArgument(0).asObject()
+                const actionDefinitionRecord = await factory.createRecord({
+                    source: callExpression,
+                    table: 'sys_hub_action_type_definition',
+                    explicitId: actionConfiguration.get('$id'),
+                    properties: actionConfiguration.transform(({ $ }) => ({
+                        name: $,
+                        internal_name: $.from('name').map((n) => slugifyString(n.getValue())),
+                        annotation: $.def(''),
+                        description: $.def(''),
+                        access: $.def('public'),
+                        category: $.def(''),
+                        sys_policy: $.from('protection').def(''),
+                        active: $.val(true),
+                        state: $.val('draft'),
+                        system_level: $.val(false),
+                    })),
+                })
+
+                const inputsConfig = actionConfiguration.get('inputs').ifObject()?.asObject()
+                if (inputsConfig) {
+                    const { variableRecords: inputRecords, complexObjectRecords: inputComplexObjects } =
+                        await buildVariableRecords({
+                            variablesConfig: inputsConfig,
+                            parentRecord: actionDefinitionRecord,
+                            factory,
+                            diagnostics,
+                            parentTable: 'sys_hub_action_type_definition',
+                            varTable: 'sys_hub_action_input',
+                        })
+                    relatedRecords.push(...inputRecords, ...inputComplexObjects)
+                }
+
+                const outputsConfig = actionConfiguration.get('outputs').ifObject()?.asObject()
+
+                if (outputsConfig) {
+                    const { variableRecords: outputRecords, complexObjectRecords: outputComplexObjects } =
+                        await buildVariableRecords({
+                            variablesConfig: outputsConfig,
+                            parentRecord: actionDefinitionRecord,
+                            factory,
+                            diagnostics,
+                            parentTable: 'sys_hub_action_type_definition',
+                            varTable: 'sys_hub_action_output',
+                            isOutput: true,
+                        })
+                    relatedRecords.push(...outputRecords, ...outputComplexObjects)
+                }
+
+                let actionBody: ArrowFunctionShape | undefined
+                actionBody = !callExpression.getArgument(1)?.if(UndefinedShape)
+                    ? callExpression.getArgument(1)?.as(ArrowFunctionShape)
+                    : undefined
+                const allInstances = actionBody?.getStatements()
+
+                for (const [, v] of (allInstances ?? []).entries()) {
+                    const source = v.getSource()
+                    if (source instanceof StepInstanceShape) {
+                        const instanceRecord = v.as(Record)
+                        const record = instanceRecord.merge({
+                            action: actionDefinitionRecord.getId().getValue(),
+                        })
+                        relatedRecords.push(record)
+                    }
+                }
+
+                return {
+                    success: true,
+                    value: actionDefinitionRecord.with(...relatedRecords),
+                }
+            },
+        },
+    ],
+})

package/src/flow/plugins/flow-data-pill-plugin.ts

@@ -0,0 +1,258 @@
+import {
+    type Diagnostics,
+    type Result,
+    IdentifierShape,
+    Plugin,
+    PropertyAccessShape,
+    Record,
+    TemplateExpressionShape,
+    ts,
+    UnresolvedShape,
+} from '@servicenow/sdk-build-core'
+import { FDInstanceShape } from '../utils/flow-shapes'
+import { ForEachItemShape, PillShape, PillTemplateShape } from '../utils/data-pill-shapes'
+import { FLOW_LOGIC } from '../flow-logic/flow-logic-constants'
+import { getCallExpressionName } from '../../utils'
+import { findAncestorByCalleeName, getRecordFromFlowInstaceShape } from '../utils/utils'
+
+function handleRecordType(
+    value: Record,
+    propertyAccessShape: PropertyAccessShape,
+    propertyNames: string[],
+    diagnostics: Diagnostics
+): Result<PropertyAccessShape> {
+    if (!(value.getSource() instanceof FDInstanceShape)) {
+        diagnostics.error(
+            propertyAccessShape,
+            'Invalid data pill: Record references must come from a flow action or subflow output'
+        )
+        return { success: false as const }
+    }
+    const pathStr = propertyNames.slice(1).join('.')
+
+    return {
+        success: true,
+        value: new PillShape({
+            source: propertyAccessShape,
+            uiId: value.as(Record).get('ui_id').asString().getValue(),
+            path: pathStr,
+        }),
+    }
+}
+
+function handleUnresolvedShape(
+    value: UnresolvedShape,
+    propertyAccessShape: PropertyAccessShape,
+    propertyNames: string[],
+    diagnostics: Diagnostics
+): Result<PropertyAccessShape> {
+    const source = value.getSource()
+    if (!(source instanceof ts.Node)) {
+        diagnostics.error(propertyAccessShape, 'Invalid root source for pill expression')
+        return { success: false as const }
+    }
+
+    // Todo: if it is any other, below code will take care of it
+    const { rootIdentifier, pathStr } = determineRootIdentifierAndPath(propertyNames, diagnostics, propertyAccessShape)
+
+    if (!rootIdentifier) {
+        const forEachParamName = getForEachParameterName(propertyAccessShape.getElement(0))
+        if (forEachParamName) {
+            return {
+                success: true,
+                value: new PillShape({
+                    source: propertyAccessShape,
+                    uiId: 'forEach',
+                    path: [forEachParamName, ...propertyNames.slice(1)].join('.'),
+                }),
+            }
+        }
+
+        diagnostics.error(propertyAccessShape, 'Invalid pill reference')
+        return { success: false }
+    }
+
+    return {
+        success: true,
+        value: new PillShape({
+            source: source,
+            uiId: rootIdentifier,
+            path: pathStr,
+        }),
+    }
+}
+
+export function determineRootIdentifierAndPath(
+    propertyNames: string[],
+    diagnostics: Diagnostics,
+    propertyAccessShape: PropertyAccessShape
+) {
+    let rootIdentifier = ''
+    let pathStr = ''
+
+    switch (propertyNames[1]) {
+        case 'inputs':
+            rootIdentifier = 'subflow' // <-- Hardcoded: But need to handle if this input is in action/subflow body when we do action body impl.
+            pathStr = propertyNames.slice(2).join('.')
+            break
+        case 'flowVariables':
+            // For params.flowVariables (schema reference), use 'flowVariables' as identifier with empty path
+            // For params.flowVariables.someVar (property access), use 'flow_variable' as identifier
+            if (propertyNames.length === 2) {
+                // Schema reference: params.flowVariables → {{flowVariables}}
+                rootIdentifier = 'flowVariables'
+                pathStr = ''
+            } else {
+                // Property access: params.flowVariables.someVar → {{flow_variable.someVar}}
+                rootIdentifier = 'flow_variable'
+                pathStr = propertyNames.slice(2).join('.')
+            }
+            break
+        case 'trigger':
+            rootIdentifier = 'trigger'
+            pathStr = propertyNames.slice(2).join('.')
+            break
+        case 'outputs':
+            // For params.outputs (schema reference in assignSubflowOutputs context), allow it
+            // For params.outputs.someOutput (property access), reject it
+            if (propertyNames.length === 2) {
+                // Schema reference: params.outputs → {{outputs}}
+                rootIdentifier = 'outputs'
+                pathStr = ''
+            } else {
+                // Property access: params.outputs.someOutput → error (not allowed)
+                diagnostics.error(
+                    propertyAccessShape,
+                    'Invalid pill reference: Subflow outputs are not allowed as datapills'
+                )
+                return { rootIdentifier: null, pathStr: null }
+            }
+            break
+        default:
+            return { rootIdentifier: null, pathStr: null }
+    }
+
+    return { rootIdentifier, pathStr }
+}
+
+/**
+ * Get the parameter name from a forEach arrow function
+ * Returns the actual parameter name (e.g., 'dept', 'category', 'item') instead of generic 'item'
+ * Returns null if the identifier is not a forEach parameter
+ */
+function getForEachParameterName(identifierShape: IdentifierShape): string | null {
+    const param = identifierShape.getOriginalNode().asKind(ts.SyntaxKind.Identifier)?.getDefinitionNodes()?.[0]
+    const parentLogicNode = param
+        ?.getParentIfKind(ts.SyntaxKind.ArrowFunction)
+        ?.getParentIfKind(ts.SyntaxKind.CallExpression)
+
+    if (!parentLogicNode || getCallExpressionName(parentLogicNode) !== FLOW_LOGIC.FOR_EACH) {
+        return null
+    }
+
+    // Get the actual parameter name from the identifier
+    return identifierShape.getName()
+}
+
+export const DataPillPlugin = Plugin.create({
+    name: 'DataPillPlugin',
+    shapes: [
+        {
+            shape: PropertyAccessShape,
+            fileTypes: ['fluent'],
+            async toSubclass(propertyAccessShape, { diagnostics, transform }): Promise<Result<PropertyAccessShape>> {
+                // Decompose PropertyAccessExpression into root identifier and remaining path
+                const ancestor = findAncestorByCalleeName(propertyAccessShape.getOriginalNode(), 'wfa.dataPill')
+                if (!ancestor) {
+                    diagnostics.error(propertyAccessShape, 'Datapill reference must be inside a wfa.dataPill call')
+                    return { success: false }
+                }
+                const propertyNames: string[] = []
+                propertyAccessShape.getElements().forEach((element) => {
+                    if (element instanceof IdentifierShape) {
+                        propertyNames.push(element.getName())
+                    }
+                })
+
+                const value = propertyAccessShape.getElement(0).resolve()
+                if (value.is(UnresolvedShape)) {
+                    return handleUnresolvedShape(value, propertyAccessShape, propertyNames, diagnostics)
+                }
+                const record = await getRecordFromFlowInstaceShape(value, transform)
+
+                if (record?.is(Record)) {
+                    return handleRecordType(record, propertyAccessShape, propertyNames, diagnostics)
+                }
+
+                return { success: false }
+            },
+        },
+        {
+            shape: TemplateExpressionShape,
+            fileTypes: ['fluent'],
+            async toSubclass(shape: TemplateExpressionShape, { transform }): Promise<Result<TemplateExpressionShape>> {
+                const parts: (string | PillShape)[] = []
+                const head = shape.getLiteralText()
+                const leadingText = head
+
+                if (leadingText.length > 0) {
+                    parts.push(leadingText)
+                }
+
+                for (const span of shape.getSpans()) {
+                    const expr = span.getExpression()
+                    const literalText = span.getLiteralText()
+
+                    const pillShapeResult = expr.is([PropertyAccessShape, IdentifierShape])
+                        ? await transform.toSubclass(expr, DataPillPlugin) // In case of PropertyAccessShape call the toSubclass() again, which calls above handler
+                        : { success: false, value: undefined }
+
+                    if (pillShapeResult.success) {
+                        const pillShape = pillShapeResult.value
+                        if (pillShape instanceof PillShape) {
+                            // do not call getValue() for trigger, as this will be handled in flow-instance-plugin
+                            if (pillShape.getRootIdentifier() === 'trigger') {
+                                parts.push(pillShape)
+                            } else {
+                                parts.push(pillShape.getValue())
+                            }
+                            parts.push(literalText)
+                        }
+
+                        if (pillShape instanceof ForEachItemShape) {
+                            parts.push(pillShape.getValue())
+                            parts.push(literalText)
+                        }
+                    }
+                }
+
+                return {
+                    success: true,
+                    value: new PillTemplateShape({
+                        source: shape,
+                        parts,
+                    }),
+                }
+            },
+        },
+        {
+            shape: IdentifierShape,
+            fileTypes: ['fluent'],
+            async toSubclass(identifierShape) {
+                const forEachParamName = getForEachParameterName(identifierShape)
+                if (!forEachParamName) {
+                    return { success: false }
+                }
+
+                return {
+                    success: true,
+                    value: new ForEachItemShape({
+                        source: identifierShape,
+                        uiId: 'forEach',
+                        path: forEachParamName,
+                    }),
+                }
+            },
+        },
+    ],
+})