@servicenow/sdk-build-plugins 3.0.3 → 4.0.1

package/src/business-rule-plugin.ts

@@ -0,0 +1,266 @@
+import { CallExpressionShape, type ObjectShape, Plugin, type ArrayShape, type Shape } from '@servicenow/sdk-build-core'
+import { ModuleFunctionShape } from './server-module-plugin'
+import { NowIdShape } from './now-id-plugin'
+import { generateDeprecatedDiagnostics } from './utils'
+
+// Similar to lodash's groupBy, but simply stores the last element of each group
+function groupByExistence<T>(collection: T[] | undefined, keyProvider: (element: T) => string): { [key: string]: T } {
+    return (
+        collection?.reduce((groups, e) => {
+            groups[keyProvider(e)] = e
+            return groups
+        }, {}) ?? {}
+    )
+}
+
+const createBidiMap = (pairs: [string, string][]) => {
+    const map = new Map(pairs)
+    const reverseMap = new Map(pairs.map(([k, v]) => [v, k] as const))
+    return {
+        get: (key: string): string | undefined => map.get(key),
+        reverseLookUp: (value: string): string | undefined => reverseMap.get(value),
+    }
+}
+
+const whenBidiMap = createBidiMap([
+    ['async', 'async_always'],
+    ['async_deprecated', 'async'],
+    ['display', 'before_display'],
+    ['before', 'before'],
+    ['after', 'after'],
+])
+
+const brAliases = {
+    addMessage: ['add_message'],
+    abortAction: ['abort_action'],
+    setFieldValue: ['set_field_value'],
+    filterCondition: ['filter_condition'],
+    roleConditions: ['role_conditions'],
+    protectionPolicy: ['sys_policy'],
+}
+
+export const BusinessRulePlugin = Plugin.create({
+    name: 'BusinessRulePlugin',
+    records: {
+        sys_script: {
+            toShape(record) {
+                return {
+                    success: true,
+                    value: new CallExpressionShape({
+                        source: record,
+                        callee: 'BusinessRule',
+                        args: [
+                            record
+                                .transform(({ $ }) => ({
+                                    $id: $.val(NowIdShape.from(record)),
+                                    name: $,
+                                    table: $.from('collection'),
+                                    order: $.toNumber().def(100),
+                                    active: $.toBoolean().def(true),
+                                    when: $.map((v) => {
+                                        return v.ifString() ? whenBidiMap.reverseLookUp(v.asString().getValue()) : v
+                                    }),
+                                    action: $.val(getActionsArray(record)),
+                                    message: $.def(''),
+                                    addMessage: $.from('add_message').toBoolean().def(false),
+                                    condition: $.def(''),
+                                    filterCondition: $.from('filter_condition').def(''),
+                                    description: $.def(''),
+                                    setFieldValue: $.from('template').def(''),
+                                    abortAction: $.from('abort_action').toBoolean().def(false),
+                                    roleConditions: $.from('role_conditions').map((v) =>
+                                        v.ifString()?.ifNotEmpty()?.getValue().split(',')
+                                    ),
+                                    script: $.def(DEFAULT_SCRIPT),
+                                    priority: $.map((p) => p.ifNumber()?.asNumber()).def(100),
+
+                                    changeFields: $.from('change_fields').toBoolean().def(false),
+                                    clientCallable: $.from('client_callable').toBoolean().def(false),
+                                    executeFunction: $.from('execute_function').toBoolean().def(false),
+                                    access: $.toString().def('package_private'),
+
+                                    rest: $.from(
+                                        'is_rest',
+                                        'rest_variables',
+                                        'rest_method',
+                                        'rest_method_text',
+                                        'rest_service',
+                                        'rest_service_text'
+                                    )
+                                        .def({
+                                            webService: false,
+                                            variables: '',
+                                            method: '',
+                                            methodText: '',
+                                            service: '',
+                                            serviceText: '',
+                                        })
+                                        .map(
+                                            (
+                                                is_rest,
+                                                rest_variables,
+                                                rest_method,
+                                                rest_method_text,
+                                                rest_service,
+                                                rest_service_text
+                                            ) => ({
+                                                webService: is_rest.ifDefined()?.toBoolean(),
+                                                variables: rest_variables.toString(),
+                                                method: rest_method.toString(),
+                                                methodText: rest_method_text.toString(),
+                                                service: rest_service.toString(),
+                                                serviceText: rest_service_text.toString(),
+                                            })
+                                        ),
+
+                                    protectionPolicy: $.from('sys_policy').def(''),
+                                }))
+                                .withAliasedKeys(brAliases),
+                        ],
+                    }),
+                }
+            },
+        },
+    },
+    shapes: [
+        {
+            shape: CallExpressionShape,
+            fileTypes: ['fluent'],
+            async toRecord(callExpression, { factory, config, diagnostics }) {
+                if (callExpression.getCallee() !== 'BusinessRule') {
+                    return { success: false }
+                }
+
+                const arg = callExpression.getArgument(0).asObject().withAliasedKeys(brAliases)
+                const rest = arg.get('rest').ifDefined()?.asObject()
+
+                generateDeprecatedDiagnostics(arg, diagnostics)
+
+                if (arg.get('script').isUnresolved()) {
+                    diagnostics.error(
+                        arg.get('script').getOriginalNode(),
+                        `Unable to resolve the script reference, ensure the imported module is within the ${config.serverModulesDir} directory.`
+                    )
+                }
+
+                return {
+                    success: true,
+                    value: arg.pipe((br) =>
+                        factory.createRecord({
+                            source: callExpression,
+                            table: 'sys_script',
+                            explicitId: br.get('$id'),
+                            properties: br.transform(({ $, merge }) => ({
+                                name: $,
+                                order: $.def(100),
+                                active: $.def(true),
+                                message: $,
+                                add_message: $.from('addMessage').map((v) => {
+                                    return (
+                                        v.ifBoolean()?.getValue() ??
+                                        (($._('message').val as Shape).getValue() !== undefined ? true : false)
+                                    )
+                                }),
+                                condition: $,
+                                filter_condition: $.from('filterCondition'),
+                                description: $,
+                                advanced: $.val(
+                                    br
+                                        .get('script')
+                                        .pipe((script) => script.isDefined() && script.getValue() !== DEFAULT_SCRIPT)
+                                ),
+                                script: $.map(
+                                    (v) =>
+                                        v
+                                            .if(ModuleFunctionShape)
+                                            ?.toString((n) => `${n}({{PARAMS}})`, ['current', 'previous']) ?? v
+                                )
+                                    .toCdata()
+                                    .def(DEFAULT_SCRIPT),
+                                collection: $.from('table'),
+                                when: $.map((v) => (v.ifString() ? whenBidiMap.get(v.asString().getValue()) : v)).def(
+                                    'before'
+                                ),
+                                [merge]: $.from('action').map((v) => {
+                                    const { insertAction, updateAction, deleteAction, queryAction } = groupByExistence(
+                                        v.ifArray()?.getElements(),
+                                        (action) => `${action.asString().getValue()}Action`
+                                    )
+
+                                    return {
+                                        action_insert: !!insertAction,
+                                        action_update: !!updateAction,
+                                        action_query: !!queryAction,
+                                        action_delete: !!deleteAction,
+                                    }
+                                }),
+                                template: $.from('setFieldValue'),
+                                role_conditions: $.from('roleConditions').map((v) => getRolesString(v.ifArray())),
+                                abort_action: $.from('abortAction').def(false),
+                                priority: $.def(100),
+
+                                is_rest: $.val(rest?.get('webService')).def(false),
+                                rest_variables: $.val(rest?.get('variables')),
+                                rest_method: $.val(rest?.get('method')),
+                                rest_method_text: $.val(rest?.get('methodText')),
+                                rest_service: $.val(rest?.get('service')),
+                                rest_service_text: $.val(rest?.get('serviceText')),
+
+                                change_fields: $.from('changeFields').def(false),
+                                client_callable: $.from('clientCallable').def(false),
+                                execute_function: $.from('executeFunction').def(false),
+                                access: $.def('package_private'),
+                                sys_policy: $.from('protectionPolicy'),
+                            })),
+                        })
+                    ),
+                }
+            },
+        },
+    ],
+})
+
+type Action = 'insert' | 'update' | 'delete' | 'query'
+function getActionsArray(recordData: ObjectShape): Action[] {
+    const actions: Action[] = []
+    if (recordData.get('action_update').toBoolean().equals(true)) {
+        actions.push('update')
+    }
+
+    if (recordData.get('action_delete').toBoolean().equals(true)) {
+        actions.push('delete')
+    }
+
+    if (recordData.get('action_insert').toBoolean().equals(true)) {
+        actions.push('insert')
+    }
+
+    if (recordData.get('action_query').toBoolean().equals(true)) {
+        actions.push('query')
+    }
+
+    return actions
+}
+
+function getRolesString(roles: ArrayShape | undefined): string | undefined {
+    if (!roles) {
+        return undefined
+    }
+
+    const uniqueRoles = [
+        ...new Set(
+            roles
+                .getElements()
+                .map((role) => (role.isRecord() ? role.get('name').asString().getValue() : role.asString().getValue()))
+        ),
+    ]
+
+    return uniqueRoles.join(',')
+}
+
+// This is the default script on the instance. We should provide
+// it in the case they don't define a script, as they may later want
+// to add a script on the instance and it's a better experience to
+// have a starting script available.
+export const DEFAULT_SCRIPT =
+    '(function executeRule(current, previous /*null when async*/) {\n\n\t// Add your code here\n\n})(current, previous);'

package/src/call-expression-plugin.ts

@@ -0,0 +1,202 @@
+import { ts, Plugin, CallExpressionShape, type Shape, type Compiler } from '@servicenow/sdk-build-core'
+import { Record } from '@servicenow/sdk-core/runtime/db'
+import { getCallExpressionName } from './utils'
+
+export const CallExpressionPlugin = Plugin.create({
+    name: 'CallExpressionPlugin',
+    nodes: [
+        {
+            node: 'CallExpression',
+            fileTypes: ['fluent'],
+            entryPoint: true,
+            async toShape(node, { transform }) {
+                const args: Shape[] = []
+                for (const arg of node.getArguments()) {
+                    const result = await transform.toShape(arg)
+                    if (!result.success) {
+                        return { success: false }
+                    }
+
+                    args.push(result.value)
+                }
+
+                return {
+                    success: true,
+                    value: new CallExpressionShape({
+                        source: node,
+                        callee: getCallExpressionName(node),
+                        args,
+                    }),
+                }
+            },
+        },
+    ],
+    shapes: [
+        {
+            shape: CallExpressionShape,
+            async commit(shape, target, { commit, compiler }) {
+                if (target.isKind(ts.SyntaxKind.ExpressionStatement)) {
+                    target = target.getExpression()
+                }
+
+                if (!ts.Node.isCallExpression(target)) {
+                    target.replaceWithText(shape.getCode())
+                    return { success: true }
+                }
+
+                const callee = target.getExpression()
+                if (callee.getText() !== shape.getCallee()) {
+                    callee.replaceWithText(shape.getCallee())
+                }
+
+                // Trim any excess arguments
+                const targetArguments = target.getArguments()
+                const shapeArguments = shape.getArguments(false)
+                const excess = targetArguments.length - shapeArguments.length
+                for (let i = 1; i <= excess; i++) {
+                    target.removeArgument(targetArguments.length - i)
+                }
+
+                // Commit existing arguments after trimming
+                for (const [i, targetElement] of target.getArguments().entries()) {
+                    await commit(shape.getArgument(i, false), targetElement)
+                }
+
+                // Add new arguments all at once
+                const argumentsToAdd = shapeArguments.slice(target.getArguments().length).map((e) => e.getCode())
+                if (argumentsToAdd.length > 0) {
+                    target.addArguments(argumentsToAdd)
+                }
+
+                if (shape.getCallee() === Record.name) {
+                    fixCallExpressionArgTypes(compiler, target)
+                }
+
+                return { success: true }
+            },
+        },
+    ],
+})
+
+function fixCallExpressionArgTypes(compiler: Compiler, node: ts.CallExpression) {
+    if (node.wasForgotten()) {
+        return
+    }
+
+    node.getSourceFile().fixMissingImports()
+    const signature = compiler.getTypeChecker().getResolvedSignature(node)
+    if (!signature) {
+        return
+    }
+
+    signature.getParameters().forEach((param, idx) => {
+        const argType = param.getTypeAtLocation(node)
+        const argNode = node.getArguments()[idx]?.asKind(ts.SyntaxKind.ObjectLiteralExpression)
+        if (!argType || !argNode) {
+            return
+        }
+        fixCallExpressionArgType(node, argNode, argType)
+    })
+}
+
+function fixCallExpressionArgType(
+    node: ts.CallExpression,
+    argNode: ts.ObjectLiteralExpression | ts.PropertyAssignment,
+    argType: ts.Type
+) {
+    if (argNode.getType().isObject()) {
+        const objectLiteral = argNode.isKind(ts.SyntaxKind.ObjectLiteralExpression)
+            ? argNode
+            : argNode.getInitializerIfKind(ts.SyntaxKind.ObjectLiteralExpression)
+        argType.getApparentProperties().forEach((prop) => {
+            const propNode = objectLiteral?.getProperty(prop.getName())?.asKind(ts.SyntaxKind.PropertyAssignment)
+            if (!propNode) {
+                return
+            }
+            fixCallExpressionArgType(node, propNode, prop.getTypeAtLocation(node))
+        })
+    } else if (argNode.isKind(ts.SyntaxKind.PropertyAssignment)) {
+        const nodeType = argNode.getType()
+        if (
+            nodeType.isAssignableTo(argType) ||
+            canAssignString(argNode, argType) ||
+            canCastAndAssignBoolean(argNode, argType) ||
+            canCastAndAssignNumber(argNode, argType)
+        ) {
+            return
+        }
+
+        // cast 'as any' for other types
+        const argValue = argNode.getInitializer()?.getText()
+        argNode.setInitializer(`${argValue} as any`)
+    }
+}
+
+function canCastAndAssignBoolean(argNode: ts.PropertyAssignment, argType: ts.Type): boolean {
+    const booleanTypes = getBooleanTypes(argType)
+    const booleanValue = getBooleanValue(argNode)
+    if (booleanValue && booleanTypes.length > 0) {
+        const isAssignable = booleanTypes.some((type) => {
+            return (
+                (type.isBoolean() && (booleanValue === 'true' || booleanValue === 'false')) ||
+                type.getText() === booleanValue
+            )
+        })
+        if (isAssignable) {
+            argNode.setInitializer(`${booleanValue}`)
+            return true
+        }
+    }
+    return false
+}
+
+function canCastAndAssignNumber(argNode: ts.PropertyAssignment, argType: ts.Type): boolean {
+    const numberTypes = getNumberTypes(argType)
+    const numberValue = getNumberValue(argNode)
+    if (numberValue && numberTypes.length > 0) {
+        const isAssignable = numberTypes.some((type) => {
+            return type.isNumber() || `${type.getLiteralValue()}` === numberValue
+        })
+        if (isAssignable) {
+            argNode.setInitializer(`${numberValue}`)
+            return true
+        }
+    }
+    return false
+}
+
+function canAssignString(argNode: ts.PropertyAssignment, argType: ts.Type): boolean {
+    const stringTypes = getStringTypes(argType)
+    const stringValue = getStringValue(argNode)
+    return stringTypes.some((type) => {
+        return type.isString() || type.getLiteralValue() === stringValue
+    })
+}
+
+function getBooleanValue(argNode: ts.PropertyAssignment): string | undefined {
+    return argNode.getInitializerIfKind(ts.SyntaxKind.StringLiteral)?.getLiteralValue()
+}
+
+function getBooleanTypes(argType: ts.Type) {
+    const type = argType.isUnion() ? argType.getUnionTypes() : [argType]
+    return type.filter((type) => type.isBoolean() || type.isBooleanLiteral())
+}
+
+function getNumberValue(argNode: ts.PropertyAssignment): string | undefined {
+    const numStrVal = argNode.getInitializerIfKind(ts.SyntaxKind.StringLiteral)?.getLiteralValue()
+    return numStrVal && !isNaN(Number(numStrVal)) ? `${numStrVal}` : undefined
+}
+
+function getNumberTypes(argType: ts.Type) {
+    const type = argType.isUnion() ? argType.getUnionTypes() : [argType]
+    return type.filter((type) => type.isNumber() || type.isNumberLiteral())
+}
+
+function getStringValue(argNode: ts.PropertyAssignment): string | undefined {
+    return argNode.getInitializerIfKind(ts.SyntaxKind.StringLiteral)?.getLiteralValue()
+}
+
+function getStringTypes(argType: ts.Type) {
+    const type = argType.isUnion() ? argType.getUnionTypes() : [argType]
+    return type.filter((type) => type.isString() || type.isStringLiteral())
+}

package/src/client-script-plugin.ts

@@ -0,0 +1,179 @@
+import { type Compiler, ts, CallExpressionShape, Plugin } from '@servicenow/sdk-build-core'
+import { NowIdShape } from './now-id-plugin'
+import { generateDeprecatedDiagnostics } from './utils'
+
+enum UITypeMapping {
+    desktop = 0,
+    mobile_or_service_portal = 1,
+    all = 10,
+}
+
+const clientScriptAliases = {
+    appliesExtended: ['applies_extended'],
+    isolateScript: ['isolate_script'],
+    uiType: ['ui_type'],
+}
+
+/**
+ * Creates a Client Script (`sys_script_client`).
+ *
+ * @see https://docs.servicenow.com/csh?topicname=client-script-api-now-ts.html&version=latest
+ *
+ * @param config - an object containing the following properties:
+ *   * **$id** - unique id for the record, typically using `Now.ID["value"]`
+ *   * **name** - name of the client script
+ *   * **table** - name of the table on which the client script runs
+ *   * **type** - type of client script, which defines when it runs
+ *   * **uiType** - user interface to which the client script applies
+ *   * **active**? - whether the record is enabled
+ *   * **appliesExtended**? - indicates whether the client script applies to tables extended from the specified table
+ *   * **description**? - description of the functionality and purpose of the client script
+ *   * **field**? - field on the table that the client script applies to.
+ *     This property applies only when the type property is set to `onChange` or `onCellEdit`.
+ *   * **global**? - indicates which views of the table the client script runs.
+ *     `true`: the script runs on all views
+ *     `false`: the script runs only on specified views
+ *   * **isolateScript**? - indicates whether scripts run in strict mode, with
+ *     access to direct DOM, `jQuery`, `prototype`, and the `window` object turned off
+ *   * **messages**? - strings that are available to the client script as localized messages using `getmessage('[message]')`.
+ *     For more information, see [Translate a client script message](https://docs.servicenow.com/csh?topicname=t_TranslateAClientScriptMessage.html&version=latest)
+ *   * **script**? - inline script preceded by a `script` tagged template literal.
+ *   * **view**? - views of the table on which the client script runs. This
+ *     property applies only when the `global` property is set to `false`
+ */
+export const ClientScriptPlugin = Plugin.create({
+    name: 'ClientScriptPlugin',
+    records: {
+        sys_script_client: {
+            toShape(record) {
+                return {
+                    success: true,
+                    value: new CallExpressionShape({
+                        source: record,
+                        callee: 'ClientScript',
+                        args: [
+                            record
+                                .transform(({ $, merge }) => ({
+                                    $id: $.val(NowIdShape.from(record)),
+                                    type: $.def(''),
+                                    table: $,
+                                    appliesExtended: $.from('applies_extended').toBoolean().def(false),
+                                    isolateScript: $.from('isolate_script').toBoolean().def(false),
+                                    script: $,
+                                    name: $,
+                                    description: $.def(''),
+                                    messages: $.def(''),
+                                    global: $.toBoolean().def(true),
+                                    active: $.toBoolean().def(true),
+                                    view: $.def(''),
+                                    uiType: $.from('ui_type')
+                                        .map((v) => getUITypeFromId(v.toNumber().getValue()))
+                                        .def('desktop'),
+                                    [merge]: $.from('field', 'type').map((field, type) => {
+                                        if (
+                                            type.isString() &&
+                                            ['onChange', 'onCellEdit'].includes(type.getValue()) &&
+                                            !field.ifString()?.isEmpty()
+                                        ) {
+                                            return { field }
+                                        }
+                                        return {}
+                                    }),
+                                }))
+                                .withAliasedKeys(clientScriptAliases),
+                        ],
+                    }),
+                }
+            },
+        },
+    },
+    shapes: [
+        {
+            shape: CallExpressionShape,
+            fileTypes: ['fluent'],
+            async toRecord(callExpression, { diagnostics, factory, compiler }) {
+                if (callExpression.getCallee() !== 'ClientScript') {
+                    return { success: false }
+                }
+
+                const clientScript = callExpression.getArgument(0).asObject().withAliasedKeys(clientScriptAliases)
+                generateDeprecatedDiagnostics(clientScript, diagnostics)
+
+                const script = clientScript.get('script').ifDefined()?.toString().getValue()
+                const type = clientScript.get('type').ifString()?.getValue()
+                const field = clientScript.get('field').ifString()?.getValue()
+
+                if (field && !type) {
+                    diagnostics.error(
+                        clientScript.get('field'),
+                        `Field values are allowed only when type is set to onChange or onCellEdit`
+                    )
+                }
+
+                if (script && !validateClientSideScripts(script, compiler)) {
+                    diagnostics.error(
+                        clientScript.get('script'),
+                        `Client side scripts cannot import or require modules.`
+                    )
+                }
+
+                return {
+                    success: true,
+                    value: factory.createRecord({
+                        source: callExpression,
+                        table: 'sys_script_client',
+                        explicitId: clientScript.get('$id'),
+                        properties: clientScript.transform(({ $ }) => ({
+                            table: $,
+                            global: $.def(true),
+                            view: $,
+                            field: $,
+                            script: $.toCdata(),
+                            type: $,
+                            name: $,
+                            active: $.def(true),
+                            applies_extended: $.from('appliesExtended').def(false),
+                            description: $,
+                            messages: $,
+                            isolate_script: $.from('isolateScript').def(false),
+                            ui_type: $.from('uiType')
+                                .map((v) => (v.isString() ? getUITypeId(v.getValue()) : undefined))
+                                .def(0),
+                        })),
+                    }),
+                }
+            },
+        },
+    ],
+})
+
+function validateClientSideScripts(script: string, compiler: Compiler) {
+    const source = compiler.createSourceFile('tmp-file.ts', script)
+    const importDeclarations = source.getDescendantsOfKind(ts.SyntaxKind.ImportDeclaration)
+    const requireCalls = source.getDescendantsOfKind(ts.SyntaxKind.CallExpression).filter((callExpression) => {
+        return isRequire(callExpression)
+    })
+    const isValid = !(importDeclarations.length > 0 || requireCalls.length > 0)
+    compiler.removeSourceFile(source)
+    return isValid
+}
+
+function getUITypeFromId(id: number) {
+    const type = UITypeMapping[id]
+    if (!type) {
+        throw Error('Invalid UI Type encountered, check XML data before transforming again.')
+    }
+    return type
+}
+
+function getUITypeId(value: string) {
+    if (value in UITypeMapping) {
+        return UITypeMapping[value]
+    }
+    throw Error('Invalid ui_type found in xml')
+}
+
+function isRequire(callExpression: ts.CallExpression): boolean {
+    const expression = callExpression.getExpression()
+    return ts.Node.isIdentifier(expression) && expression.getText() === 'require'
+}