@servicenow/sdk-build-plugins 4.1.1 → 4.3.0

package/src/ui-policy-plugin.ts

@@ -0,0 +1,505 @@
+import {
+    type Compiler,
+    type Diagnostics,
+    CallExpressionShape,
+    Plugin,
+    isSNScope,
+    isGUID,
+    type Record,
+    type Shape,
+} from '@servicenow/sdk-build-core'
+import { validateClientSideScript } from './utils'
+import { NowIdShape } from './now-id-plugin'
+
+// Define table names as constants since they're not exported from the core tables
+const SYS_UI_POLICY = 'sys_ui_policy'
+const SYS_UI_POLICY_ACTION = 'sys_ui_policy_action'
+const SYS_UI_POLICY_RL_ACTION = 'sys_ui_policy_rl_action'
+const DEFAULT_SCRIPT = 'function onCondition() {\n\n}'
+
+// UI Type constant for string-to-number mapping
+const UiTypeMapping = { desktop: 0, 'mobile-or-service-portal': 1, all: 10 }
+const getUITypeFromId = (id: number): string => {
+    const entry = Object.entries(UiTypeMapping).find(([_, v]) => v === id)
+    if (!entry) {
+        throw Error(`Invalid UI Type encountered: ${id}, check XML data before transforming again.`)
+    }
+    return entry[0]
+}
+const getUITypeId = (value: keyof typeof UiTypeMapping): number => {
+    const entry = UiTypeMapping[value]
+    if (entry === undefined) {
+        throw Error(`Invalid ui_type found: ${value}`)
+    }
+    return entry
+}
+
+/**
+ * Converts ServiceNow string format ('true'/'false'/'ignore') to boolean | 'ignore'
+ * Used when reading from database (toShape)
+ */
+const stringToBoolean = (value?: string): boolean | 'ignore' | undefined => {
+    switch (value) {
+        case 'true':
+            return true
+        case 'false':
+            return false
+        case 'ignore':
+            return 'ignore'
+        default:
+            return undefined
+    }
+}
+
+/**
+ * Converts boolean | 'ignore' to ServiceNow string format ('true'/'false'/'ignore')
+ * Used when writing to database (toRecord)
+ */
+const booleanToString = (value: Shape): string => {
+    if (value?.isBoolean()) {
+        return value.getValue() ? 'true' : 'false'
+    }
+    return 'ignore'
+}
+
+/**
+ * Checks if a value is a valid action property (boolean or 'ignore')
+ * Used for validation in toRecord
+ */
+const isValidActionValue = (value: Shape): boolean => {
+    return value?.isBoolean() || (value?.isString() && value.getValue() === 'ignore')
+}
+
+// Helper to determine if a script should be included in generated Fluent code
+const isValidScript = (scriptValue: Shape) =>
+    scriptValue?.isString() && scriptValue.getValue() !== '' && scriptValue.getValue() !== DEFAULT_SCRIPT
+
+// Helper function to validate a script property for import/require statements
+const validateScriptProperty = (
+    scriptProperty: Shape | undefined,
+    compiler: Compiler,
+    diagnostics: Diagnostics
+): void => {
+    if (scriptProperty?.isString()) {
+        const scriptContent = scriptProperty.getValue()
+        if (scriptContent && !validateClientSideScript(scriptContent, compiler)) {
+            diagnostics.error(
+                scriptProperty,
+                'UI Policy scripts cannot import or require modules. Scripts run client-side in the browser.'
+            )
+        }
+    }
+}
+
+export const UiPolicyPlugin = Plugin.create({
+    name: 'UiPolicyPlugin',
+    records: {
+        [SYS_UI_POLICY]: {
+            coalesce: ['table', 'short_description'],
+            relationships: {
+                [SYS_UI_POLICY_ACTION]: {
+                    via: 'ui_policy',
+                    descendant: true,
+                },
+                [SYS_UI_POLICY_RL_ACTION]: {
+                    via: 'ui_policy',
+                    descendant: true,
+                },
+            },
+            toShape(record, { descendants }) {
+                const actions = descendants
+                    .query(SYS_UI_POLICY_ACTION)
+                    .map((action) => {
+                        const fieldValue = action.get('field')?.ifString()?.getValue()
+                        if (!fieldValue) {
+                            return null // Skip actions without a field
+                        }
+
+                        const actionObj: {
+                            field: string
+                            visible?: boolean | 'ignore'
+                            readOnly?: boolean | 'ignore'
+                            mandatory?: boolean | 'ignore'
+                            cleared?: boolean
+                            table?: string
+                            value?: string
+                            fieldMessage?: string
+                            fieldMessageType?: string
+                            valueAction?: string
+                        } = {
+                            field: fieldValue,
+                        }
+
+                        // Convert ServiceNow string format to boolean | 'ignore'
+                        const visible = stringToBoolean(action.get('visible')?.ifString()?.getValue())
+                        const disabled = stringToBoolean(action.get('disabled')?.ifString()?.getValue())
+                        const mandatory = stringToBoolean(action.get('mandatory')?.ifString()?.getValue())
+
+                        // Only include visible if it's not 'ignore'
+                        if (visible !== undefined && visible !== 'ignore') {
+                            actionObj.visible = visible
+                        }
+
+                        // Convert 'disabled' to 'readOnly'
+                        // Only include 'readOnly' if it's not 'ignore'
+                        if (disabled !== undefined && disabled !== 'ignore') {
+                            actionObj.readOnly = disabled
+                        }
+
+                        // Only include mandatory if it's not 'ignore'
+                        if (mandatory !== undefined && mandatory !== 'ignore') {
+                            actionObj.mandatory = mandatory
+                        }
+
+                        const cleared = action.get('cleared')?.ifBoolean()?.getValue()
+                        if (cleared) {
+                            actionObj.cleared = cleared
+                        }
+
+                        // Add new optional fields - only if they have meaningful values
+                        const table = action.get('table')?.ifString()?.getValue()
+                        const parentTable = record.get('table')?.ifString()?.getValue()
+                        // Only include table if it's different from the parent policy's table
+                        if (table && table !== parentTable) {
+                            actionObj.table = table
+                        }
+
+                        const value = action.get('value')?.ifString()?.getValue()
+                        if (value) {
+                            actionObj.value = value
+                        }
+
+                        const fieldMessage = action.get('field_message')?.ifString()?.getValue()
+                        if (fieldMessage) {
+                            actionObj.fieldMessage = fieldMessage
+                        }
+
+                        const fieldMessageType = action.get('field_message_type')?.ifString()?.getValue()
+                        // Only include if it's not the default value 'none'
+                        if (fieldMessageType && fieldMessageType !== 'none') {
+                            actionObj.fieldMessageType = fieldMessageType
+                        }
+
+                        const valueAction = action.get('value_action')?.ifString()?.getValue()
+                        // Only include if it's not the default value 'ignore'
+                        if (valueAction && valueAction !== 'ignore') {
+                            actionObj.valueAction = valueAction
+                        }
+
+                        // Skip actions that have no meaningful properties (all are 'ignore')
+                        if (Object.keys(actionObj).length === 1) {
+                            return null // Only 'field' property exists, skip this action
+                        }
+
+                        return actionObj
+                    })
+                    .filter((action) => action !== null) // Remove null actions
+
+                // Process related list actions
+                const relatedListActions = descendants
+                    .query(SYS_UI_POLICY_RL_ACTION)
+                    .map((rlAction) => {
+                        const rlActionObj: {
+                            list?: string
+                            visible?: boolean | 'ignore'
+                        } = {}
+
+                        const listValue = rlAction.get('list')?.ifString()?.getValue()
+                        if (listValue) {
+                            // Strip REL: prefix if present (transform ServiceNow → Fluent)
+                            // Users write plain GUIDs or table.field format in Fluent code
+                            if (listValue.startsWith('REL:')) {
+                                rlActionObj.list = listValue.substring(4) // Remove 'REL:' prefix
+                            } else {
+                                rlActionObj.list = listValue
+                            }
+                        }
+
+                        // Convert ServiceNow string format to boolean | 'ignore'
+                        const visible = stringToBoolean(rlAction.get('visible')?.ifString()?.getValue())
+                        if (visible !== undefined && visible !== 'ignore') {
+                            rlActionObj.visible = visible
+                        }
+
+                        // Skip if no meaningful properties (only $id exists)
+                        if (Object.keys(rlActionObj).length === 0) {
+                            return null
+                        }
+
+                        return rlActionObj
+                    })
+                    .filter((rlAction) => rlAction !== null) // Remove null actions
+
+                return {
+                    success: true,
+                    value: new CallExpressionShape({
+                        source: record,
+                        callee: 'UiPolicy',
+                        args: [
+                            record.transform(({ $ }) => {
+                                const scriptTrueValue = record.get('script_true')
+                                const scriptFalseValue = record.get('script_false')
+                                const runScriptsValue = record.get('run_scripts')?.toBoolean().getValue() ?? false
+                                const uiTypeValue = record.get('ui_type')
+                                const includeScriptTrue = runScriptsValue || isValidScript(scriptTrueValue)
+                                const includeScriptFalse = runScriptsValue || isValidScript(scriptFalseValue)
+
+                                return {
+                                    $id: $.val(NowIdShape.from(record)),
+                                    table: $.from('table').def(''),
+                                    shortDescription: $.from('short_description'),
+                                    active: $.toBoolean().def(true),
+                                    global: $.toBoolean().def(true),
+                                    onLoad: $.from('on_load').toBoolean().def(true),
+                                    reverseIfFalse: $.from('reverse_if_false').toBoolean().def(true),
+                                    inherit: $.toBoolean().def(false),
+                                    isolateScript: $.from('isolate_script').toBoolean().def(false),
+                                    conditions: $.def(''),
+                                    runScripts: $.from('run_scripts').toBoolean().def(false),
+
+                                    scriptTrue: $.val(
+                                        includeScriptTrue ? (scriptTrueValue?.getValue() ?? DEFAULT_SCRIPT) : undefined
+                                    ),
+                                    scriptFalse: $.val(
+                                        includeScriptFalse
+                                            ? (scriptFalseValue?.getValue() ?? DEFAULT_SCRIPT)
+                                            : undefined
+                                    ),
+                                    // uiType is REQUIRED when runScripts is true, should be omitted when false
+                                    uiType: $.val(
+                                        runScriptsValue
+                                            ? getUITypeFromId(uiTypeValue?.toNumber().getValue() ?? 0)
+                                            : undefined
+                                    ),
+                                    description: $.from('description').def(''),
+                                    modelId: $.from('model_id').def(''),
+                                    modelTable: $.from('model_table').def(''),
+                                    order: $.from('order').toNumber().def(100),
+                                    setValues: $.from('set_values').def(''),
+                                    view: $.from('view').def(''),
+                                    actions: $.val(actions.length > 0 ? actions : undefined),
+                                    relatedListActions: $.val(
+                                        relatedListActions.length > 0 ? relatedListActions : undefined
+                                    ),
+                                }
+                            }),
+                        ],
+                    }),
+                }
+            },
+        },
+        [SYS_UI_POLICY_ACTION]: {
+            coalesce: ['ui_policy', 'field'],
+        },
+        [SYS_UI_POLICY_RL_ACTION]: {
+            coalesce: ['ui_policy', 'list'],
+        },
+    },
+    shapes: [
+        {
+            shape: CallExpressionShape,
+            fileTypes: ['fluent'],
+            async toRecord(callExpression, { config, factory, diagnostics, compiler }) {
+                if (callExpression.getCallee()?.toString() !== 'UiPolicy') {
+                    return { success: false }
+                }
+
+                const arg = callExpression.getArgument(0)
+                if (!arg?.isObject()) {
+                    return { success: false }
+                }
+
+                const shortDescription = arg.get('shortDescription')
+                if (shortDescription?.isString() && shortDescription.getValue().trim() === '') {
+                    diagnostics.error(shortDescription, 'shortDescription cannot be empty or contain only whitespace')
+                    return { success: false }
+                }
+
+                // Validate table scope prefix for scoped apps
+                const tableValue = arg.get('table')
+                if (tableValue?.isString() && config?.scope) {
+                    const tableName = tableValue.getValue()
+                    const scopeName = config.scope
+
+                    if (!tableName.startsWith(`${scopeName}_`) && !isSNScope(scopeName) && scopeName !== 'global') {
+                        diagnostics.error(
+                            arg.get('table'),
+                            `'table' property should start with scope prefix '${scopeName}_'. UI Policies in scoped apps can only be created for tables within the same scope.`
+                        )
+                    }
+                }
+
+                // Validate scripts for import statements
+                const scriptTrue = arg.get('scriptTrue')
+                const scriptFalse = arg.get('scriptFalse')
+                validateScriptProperty(scriptTrue, compiler, diagnostics)
+                validateScriptProperty(scriptFalse, compiler, diagnostics)
+                const runScripts = arg.get('runScripts')
+                if (runScripts.isUndefined() || runScripts.ifBoolean()?.equals(false)) {
+                    ;[scriptTrue, scriptFalse]
+                        .filter((shape) => shape.isDefined() && !shape.equals(DEFAULT_SCRIPT))
+                        .forEach((shape) =>
+                            diagnostics.info(shape, `This script will not execute unless runScripts is set to true`)
+                        )
+                }
+
+                // Convert uiType value to ID (TypeScript enforces valid values at compile time)
+                const uiTypeValue = arg.get('uiType')
+                const uiTypeId = uiTypeValue?.isString()
+                    ? getUITypeId(uiTypeValue.getValue() as keyof typeof UiTypeMapping)
+                    : UiTypeMapping.desktop // default
+
+                // Create the UI Policy record
+                const policyRecord = await factory.createRecord({
+                    source: callExpression,
+                    table: SYS_UI_POLICY,
+                    explicitId: arg.get('$id'),
+                    properties: arg.transform(({ $ }) => ({
+                        table: $.from('table').def(''),
+                        short_description: $.from('shortDescription'),
+                        active: $.from('active').def(true),
+                        global: $.from('global').def(true),
+                        on_load: $.from('onLoad').def(true),
+                        reverse_if_false: $.from('reverseIfFalse').def(true),
+                        inherit: $.from('inherit').def(false),
+                        isolate_script: $.from('isolateScript').def(false),
+                        conditions: $.from('conditions').def(''),
+                        run_scripts: $.from('runScripts').def(false),
+                        script_true: $.from('scriptTrue').toCdata().def(DEFAULT_SCRIPT),
+                        script_false: $.from('scriptFalse').toCdata().def(DEFAULT_SCRIPT),
+                        description: $.from('description').def(''),
+                        model_id: $.from('modelId').def(''),
+                        model_table: $.from('modelTable').def(''),
+                        order: $.from('order').toNumber().def(100),
+                        set_values: $.from('setValues').def(''),
+                        ui_type: $.val(uiTypeId),
+                        view: $.from('view').def(''),
+                    })),
+                })
+
+                // Process actions if they exist
+                const actions = arg.get('actions')
+                const actionRecords: Record[] = []
+
+                if (actions?.isArray()) {
+                    const elements = actions.getElements()
+
+                    // Process each action in the array
+                    for (let i = 0; i < elements.length; i++) {
+                        const action = elements[i]
+                        if (!action?.isObject()) {
+                            continue
+                        }
+
+                        const field = action.get('field')
+
+                        // Validate at least one action property exists
+                        const hasVisibleProp = isValidActionValue(action.get('visible'))
+                        const hasReadOnlyProp = isValidActionValue(action.get('readOnly'))
+                        const hasMandatoryProp = isValidActionValue(action.get('mandatory'))
+                        const hasClearedProp = action.get('cleared')?.isBoolean() || false
+
+                        if (!hasVisibleProp && !hasReadOnlyProp && !hasMandatoryProp && !hasClearedProp) {
+                            diagnostics.error(
+                                action,
+                                `Action at index ${i} must specify at least one of: visible, readOnly, mandatory, or cleared`
+                            )
+                            continue
+                        }
+
+                        const actionRecord = await factory.createRecord({
+                            source: action, // Use the action as source instead of callExpression
+                            table: SYS_UI_POLICY_ACTION,
+                            properties: action.transform(({ $ }) => ({
+                                ui_policy: $.val(policyRecord.getId()),
+                                table: $.from('table').def(arg.get('table')?.getValue() || ''),
+                                field: $.val(field.getValue()),
+                                visible: $.val(booleanToString(action.get('visible'))),
+                                disabled: $.val(booleanToString(action.get('readOnly'))),
+                                mandatory: $.val(booleanToString(action.get('mandatory'))),
+                                cleared: $.from('cleared').toBoolean().def(false),
+                                field_message: $.from('fieldMessage').def(''),
+                                field_message_type: $.from('fieldMessageType').def('none'),
+                                value: $.from('value').def(''),
+                                value_action: $.from('valueAction').def('ignore'),
+                            })),
+                        })
+
+                        actionRecords.push(actionRecord)
+                    }
+                }
+
+                // Create related list action records (optional) - AST approach
+                const relatedListActionRecords: Record[] = []
+                const relatedListActions = arg.get('relatedListActions')
+                if (relatedListActions?.isArray()) {
+                    const rlElements = relatedListActions.getElements()
+
+                    // Process each related list action in the array (similar to actions)
+                    for (let i = 0; i < rlElements.length; i++) {
+                        const rlAction = rlElements[i]
+                        if (!rlAction?.isObject()) {
+                            continue
+                        }
+
+                        // Validate and process the list property
+                        const list = rlAction.get('list')
+                        let listValue = ''
+
+                        if (list) {
+                            if (list.isRecord()) {
+                                listValue = `REL:${list.getId().getValue()}`
+                            } else if (list.isString()) {
+                                const listStr = list.getValue()
+
+                                if (isGUID(listStr)) {
+                                    listValue = `REL:${listStr}`
+                                } else if (listStr.includes('.')) {
+                                    const [table, field] = listStr.split('.')
+                                    if (!table || !field || listStr.split('.').length !== 2) {
+                                        diagnostics.error(
+                                            list,
+                                            `Related list action at index ${i}: 'list' property must be in 'table.field' format (e.g., 'incident.caller_id')`
+                                        )
+                                        continue
+                                    }
+                                    listValue = listStr
+                                } else {
+                                    diagnostics.error(
+                                        list,
+                                        `Related list action at index ${i}: 'list' property must be either a Record<'sys_relationship'>, a GUID, or in 'table.field' format (e.g., 'incident.caller_id')`
+                                    )
+                                    continue
+                                }
+                            }
+                        }
+
+                        // At least one property must be specified (visible or list)
+                        const hasVisibleProp = isValidActionValue(rlAction.get('visible'))
+                        if (!hasVisibleProp && !listValue) {
+                            diagnostics.error(
+                                rlAction,
+                                `Related list action at index ${i} must specify at least one of: list or visible`
+                            )
+                            continue
+                        }
+
+                        const rlActionRecord = await factory.createRecord({
+                            source: rlAction,
+                            table: SYS_UI_POLICY_RL_ACTION,
+                            properties: rlAction.transform(({ $ }) => ({
+                                list: $.val(listValue),
+                                ui_policy: $.val(policyRecord.getId()),
+                                visible: $.val(booleanToString(rlAction.get('visible'))),
+                            })),
+                        })
+
+                        relatedListActionRecords.push(rlActionRecord)
+                    }
+                }
+
+                return { success: true, value: policyRecord.with(...actionRecords, ...relatedListActionRecords) }
+            },
+        },
+    ],
+})

package/src/utils.ts

@@ -1,4 +1,11 @@
-import { ts, type Shape, type ObjectShape, type Diagnostics } from '@servicenow/sdk-build-core'
+import {
+    ts,
+    type Shape,
+    type ObjectShape,
+    type Diagnostics,
+    type Compiler,
+    type PluginApiDoc,
+} from '@servicenow/sdk-build-core'
 
 export function toReference(shape: Shape) {
     return shape.ifRecord()?.getId() ?? shape.ifString()?.getValue() ?? ''
@@ -67,3 +74,45 @@ export function generateDeprecatedDiagnostics(object: ObjectShape, diagnostics:
         }
     })
 }
+
+/**
+ * Helper function to check if a call expression is a require statement
+ */
+function isRequire(callExpression: ts.CallExpression): boolean {
+    const expression = callExpression.getExpression()
+    return ts.Node.isIdentifier(expression) && expression.getText() === 'require'
+}
+
+/**
+ * Validates that client-side scripts (Client Scripts and UI Policy scripts) don't contain
+ * import or require statements. These scripts run in the browser and cannot use module imports.
+ *
+ * @param script - The script content to validate
+ * @param compiler - The TypeScript compiler instance
+ * @returns true if the script is valid (no imports/requires), false otherwise
+ */
+export function validateClientSideScript(script: string, compiler: Compiler): boolean {
+    const source = compiler.createSourceFile('tmp-script.ts', script)
+    const hasImports = source.getDescendantsOfKind(ts.SyntaxKind.ImportDeclaration).length > 0
+    const hasRequires = source.getDescendantsOfKind(ts.SyntaxKind.CallExpression).some(isRequire)
+    const isValid = !(hasImports || hasRequires)
+    compiler.removeSourceFile(source)
+
+    return isValid
+}
+
+/**
+ * Creates a documentation entry for first-party SDK plugins.
+ * Using this helper ensures apiName and docPath are always in sync.
+ *
+ * @param apiName - The API name (e.g., 'BusinessRule', 'Acl')
+ * @param tags - Keywords for categorization (typically includes the ServiceNow table name)
+ * @returns A complete PluginApiDoc entry
+ */
+export function createSdkDocEntry(apiName: string, tags: string[]): PluginApiDoc {
+    return {
+        apiName,
+        docPath: `@servicenow/sdk/docs/${apiName}/${apiName}.md`,
+        tags,
+    }
+}