@servicenow/sdk-build-plugins 2.0.1

package/src/scripts/ClientScriptPlugin.ts

@@ -0,0 +1,251 @@
+import { ClientScript } from '@servicenow/sdk-core/runtime/clientscript'
+import {
+    Context,
+    Plugin,
+    extractCallExpression,
+    getCallExpressionName,
+    removeNode,
+    getOrCreateEntitySourceFile,
+    generateCallExpressionExportForDocument,
+    linkDocument,
+    mergeDataIntoObjectLiteral,
+    writeCustomProperty,
+    stringify,
+    getSysUpdateName,
+    FluentDiagnostic,
+    EntityData,
+    ObjectData,
+} from '@servicenow/sdk-build-core'
+import { Record } from '@servicenow/sdk-core/runtime/db'
+import { ClientScriptSchema } from '@servicenow/sdk-core/runtime/clientscript'
+import { z } from 'zod'
+import * as ts from 'ts-morph'
+import { processScript } from '../ScriptTemplatePlugin'
+import { Diagnostic } from '@servicenow/sdk-project'
+import { except } from './scriptUtils'
+
+const UITypeMapping = {
+    desktop: 0,
+    mobile_or_service_portal: 1,
+    all: 10,
+}
+const ClientScriptXmlSchema = ClientScriptSchema.extend({
+    table: z.string(),
+    ui_type: z.union([z.literal(0), z.literal(1), z.literal(10)]),
+    sys_class_name: z.literal('sys_script_client'),
+})
+const PartialClientScriptXMLSchema = ClientScriptXmlSchema.partial()
+
+type ClientScriptSchema = z.infer<typeof ClientScriptSchema>
+type PatialClientScriptConfig = z.infer<typeof PartialClientScriptXMLSchema>
+
+export default Plugin({
+    name: 'ClientScript',
+    ownedTables: {
+        sys_script_client: { diagnosticLevel: Diagnostic.Level.Warn },
+    },
+    extractors: {
+        entity: {
+            CallExpression: (node, context) => {
+                const result = extractCallExpression(ClientScript, 'clientScript', node, context, (script) =>
+                    context.registerExplicitId('sys_script_client', script.$id as string)
+                )
+
+                if (!result.handled || !(0 in result.data)) {
+                    return result
+                }
+
+                const clientScriptEntityData = result.data[0]
+                const args = node.getArguments()[0] as ts.ObjectLiteralExpression
+
+                if (!args) {
+                    result.diagnostics.push(new FluentDiagnostic(node, 'Client script arguments are missing'))
+                    return result
+                }
+
+                const diagnostics = result.diagnostics
+                const data = ClientScriptSchema.parse(clientScriptEntityData.getValue())
+                const { script, type, field } = data
+
+                if (field && !type) {
+                    diagnostics.push(
+                        new FluentDiagnostic(
+                            args.getProperty('field')!,
+                            `Field values are allowed only when type is set to onChange or onCellEdit`
+                        )
+                    )
+                }
+
+                if (script && !validateClientSideScripts(script, context)) {
+                    diagnostics.push(
+                        new FluentDiagnostic(
+                            args.getProperty('script')!,
+                            `Client side scripts cannot import or require modules.`
+                        )
+                    )
+                }
+
+                /**
+                 * Removing this diagnostic : Currently on instance if you empty script field and click update, it would show basic template set
+                 * for the field but the xml is not updated. Only after saving it again the xml gets updated with basic template.
+                 */
+                // if (type && !script) {
+                //     diagnostics.push(
+                //         new FluentDiagnostic(
+                //             args.getProperty('type')!,
+                //             `Cannot have empty script value for type: ${type}`
+                //         )
+                //     )
+                // }
+
+                const record = createClientScriptRecord(data, script)
+
+                return {
+                    handled: true,
+                    diagnostics,
+                    data: [
+                        new EntityData(
+                            'record',
+                            clientScriptEntityData.getGuid(),
+                            ObjectData.fromObjectValue(record, node),
+                            node
+                        ),
+                    ],
+                }
+            },
+        },
+    },
+
+    generators: {
+        record(document, context) {
+            if (!ClientScriptXmlSchema.safeParse(document.data!['data']).success) {
+                return undefined
+            }
+
+            return linkDocument(
+                document,
+                generateCallExpressionExportForDocument(
+                    context,
+                    {
+                        sourceFile: getOrCreateEntitySourceFile(
+                            context,
+                            getSysUpdateName(document, 'sys_script_client')
+                        ),
+                        moduleSpecifier: '@servicenow/sdk/core',
+                    },
+                    ClientScript,
+                    {
+                        $id: document.guid,
+                    }
+                ).getExpressionIfKindOrThrow(ts.SyntaxKind.CallExpression)
+            )
+        },
+    },
+
+    transformers: {
+        record: {
+            CallExpression(document, context) {
+                if (getCallExpressionName(document.node) !== ClientScript.name) {
+                    return false
+                }
+
+                if (document.action === 'DELETE') {
+                    removeNode(document.node)
+                    return true
+                }
+
+                const modifiedClientScriptProps = ClientScriptXmlSchema.partial().safeParse(
+                    (document.changedData as any).data
+                )
+
+                if (!modifiedClientScriptProps.success) {
+                    return false
+                }
+
+                return transformClientScriptArguments(
+                    document.guid,
+                    document.node,
+                    context,
+                    except(modifiedClientScriptProps.data, (key) => key === 'sys_class_name')
+                )
+            },
+        },
+    },
+})
+
+function validateClientSideScripts(script: string, context: Context) {
+    const source = context.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)
+    context.compiler.removeSourceFile(source)
+    return isValid
+}
+
+function getUITypeFromId(id: number) {
+    const type = Object.keys(UITypeMapping).find((e) => UITypeMapping[e] === id)
+    if (!type) {
+        throw Error('Invalid UI Type encountered, check XML data before transforming again.')
+    }
+    return type
+}
+
+function transformClientScriptArguments(
+    documentId: string,
+    node: ts.CallExpression,
+    context: Context,
+    data: PatialClientScriptConfig
+) {
+    const argNode = node.getArguments()[0]!.asKindOrThrow(ts.SyntaxKind.ObjectLiteralExpression)
+    const { script, table, ui_type, type, ...rest } = data
+
+    if (type !== undefined) {
+        if (type) {
+            writeCustomProperty(argNode, 'type', '', stringify(type))
+        } else {
+            argNode.getProperty('type')?.remove()
+        }
+    }
+
+    if (Object.values(UITypeMapping).some((value) => value === ui_type)) {
+        const uiType = getUITypeFromId(ui_type!)
+        writeCustomProperty(argNode, 'ui_type', '', stringify(uiType))
+    }
+
+    if (table) {
+        writeCustomProperty(argNode, 'table', '{}', stringify(table))
+    }
+
+    if (script !== undefined) {
+        processScript(argNode, 'script', script, documentId, 'sys_script_client', context)
+    }
+
+    mergeDataIntoObjectLiteral(argNode, rest)
+
+    return true
+}
+
+function createClientScriptRecord(data: ClientScriptSchema, script: string) {
+    data.script = script as any
+    const { $id, ...csData } = ClientScriptSchema.parse(data)
+    csData.ui_type = getUITypeId(csData.ui_type)
+    return Record({
+        table: 'sys_script_client',
+        $id,
+        data: csData as any,
+    })
+}
+
+function getUITypeId(value: string) {
+    if (value in UITypeMapping) {
+        return UITypeMapping[value]
+    }
+    throw Error('Invalid ui_type found in xml')
+}
+
+export function isRequire(callExpression: ts.CallExpression): boolean {
+    const expression = callExpression.getExpression()
+    return ts.Node.isIdentifier(expression) && expression.getText() === 'require'
+}

package/src/scripts/scriptUtils.ts

@@ -0,0 +1,81 @@
+import { CURRENT_CALL_EXPRESSION, Context, ObjectData } from '@servicenow/sdk-build-core'
+import * as path from 'path'
+import { SyntaxKind, Node } from 'ts-morph'
+
+export type ScriptInfo = {
+    filePath: string
+    functionName: string
+    isDefault: boolean
+    event?: string
+}
+
+export function scriptInfo(node: Node, context: Context, pluginName: string) {
+    if (!context.store) {
+        return
+    }
+
+    if (context.store[CURRENT_CALL_EXPRESSION] !== pluginName) {
+        if (pluginName !== 'Table' && (context.store[CURRENT_CALL_EXPRESSION] as string).includes('Column')) {
+            return
+        }
+    }
+
+    if (node.isKind(SyntaxKind.FunctionDeclaration)) {
+        return ObjectData.fromObjectValue(
+            {
+                filePath: path.normalize(node.getSourceFile().getFilePath()),
+                functionName: node.getName(),
+                isDefault: node.isDefaultExport(),
+            },
+            node
+        )
+    }
+
+    if (node.isKind(SyntaxKind.FunctionExpression)) {
+        const parent = node.getParentIfKind(SyntaxKind.VariableDeclaration)
+        if (!parent) {
+            return
+        }
+
+        return ObjectData.fromObjectValue(
+            {
+                filePath: path.normalize(node.getSourceFile().getFilePath()),
+                functionName: parent.getName(),
+                isDefault: parent.isDefaultExport(),
+            },
+            node
+        )
+    }
+
+    return
+}
+
+export function except(obj: object, excludePredicate: (string) => boolean) {
+    return Object.keys(obj)
+        .filter((k) => !excludePredicate(k))
+        .reduce((acc, k) => ({ ...acc, [k]: obj[k] }), {})
+}
+
+export function buildScriptImport(
+    scriptFileImport: string,
+    importName: string,
+    isDefault: boolean,
+    context: Context,
+    codeFunc: (funcName: string) => string
+) {
+    scriptFileImport = scriptFileImport.replace(/\.ts$/, '.js')
+    const func_name = importName ?? path.basename(scriptFileImport, '.js')
+    let relativeImport = scriptFileImport.replace(context.app.rootDir, '')
+    relativeImport = relativeImport.replace(context.app.config.sourceDir, context.app.config.transpiledSourceDir)
+    relativeImport = relativeImport.replaceAll(path.sep, path.posix.sep)
+    if (relativeImport.startsWith(path.posix.sep)) {
+        relativeImport = relativeImport.substring(1)
+    }
+
+    if (isDefault) {
+        scriptFileImport = `const ${func_name} = require('./${relativeImport}').default\n` + codeFunc(func_name)
+    } else {
+        scriptFileImport = `const { ${func_name} } = require('./${relativeImport}')\n` + codeFunc(func_name)
+    }
+    return scriptFileImport
+}

package/src/uxf/ExperiencePlugin.ts

@@ -0,0 +1,64 @@
+import { Experience, ExperienceSchema } from '@servicenow/sdk-core/runtime/experience'
+import { Record } from '@servicenow/sdk-core/runtime/db'
+import { EntityData, ObjectData, Plugin, extractCallExpression } from '@servicenow/sdk-build-core'
+import { PARENT_APP_SHELL_ID, WORKSPACE_APP_SHELL_ID } from './constants'
+import { RecordPlugin } from '../db/RecordPlugin'
+import { Diagnostic } from '@servicenow/sdk-project'
+
+export default Plugin({
+    name: 'Experience',
+    ownedTables: {
+        sys_ux_app_config: { diagnosticLevel: Diagnostic.Level.Warn },
+    },
+    extractors: {
+        entity: {
+            CallExpression: (node, context) =>
+                extractCallExpression(Experience, 'experience', node, context, (experience) =>
+                    context.registerExplicitId('sys_ux_app_config', experience.$id as string)
+                ),
+        },
+    },
+    composers: {
+        entity: {
+            experience(entity, context) {
+                const node = entity.getNode()
+                const data = entity.getValue()
+                const guid = entity.getGuid()
+                const recordData = ExperienceSchema.parse(data)
+
+                const appConfig = Record({
+                    table: 'sys_ux_app_config',
+                    $id: guid,
+                    data: {
+                        name: recordData.name,
+                        active: recordData.active,
+                        base_url_path: recordData.baseUrlPath,
+                        landing_path: recordData.landingPath,
+                        description: recordData.description,
+                    },
+                })
+
+                const pageRegistry = Record({
+                    table: 'sys_ux_page_registry',
+                    $id: context.registerExplicitId('sys_ux_page_registry', `${guid}_registry`),
+                    data: {
+                        title: recordData.name,
+                        active: recordData.active,
+                        admin_panel: appConfig,
+                        admin_panel_table: 'sys_ux_app_config',
+                        parent_app: PARENT_APP_SHELL_ID,
+                        path: recordData.baseUrlPath,
+                        root_macroponent: WORKSPACE_APP_SHELL_ID,
+                    },
+                })
+
+                return context.composeEntities(
+                    [appConfig, pageRegistry].map(
+                        (r) => new EntityData('record', r.$id as string, ObjectData.fromObjectValue(r, node), node)
+                    ),
+                    [RecordPlugin]
+                )
+            },
+        },
+    },
+})

package/src/uxf/RoutesPlugin.ts

@@ -0,0 +1,215 @@
+import { BaseUXRouteSchema, ExperienceSchema, Routes } from '@servicenow/sdk-core/runtime/experience'
+import { Record } from '@servicenow/sdk-core/runtime/db'
+import { SdkError } from '@servicenow/sdk-metrics'
+import { EntityData, ObjectData, Plugin, extractCallExpression } from '@servicenow/sdk-build-core'
+import { parser as uxValueParser, cleanUxValue } from './UxfFormulaParser'
+import { idGenerator } from './tectonicIdGenerator'
+import { WORKSPACE_APP_SHELL_ID } from './constants'
+import { RecordPlugin } from '../db/RecordPlugin'
+import { Diagnostic } from '@servicenow/sdk-project'
+
+const PAGE_TEMPLATE_SYS_ID = '19be392623033300f4b4c50947bf65ba'
+type Component = Routes['routes'][string]['component']
+
+type RouteParts = {
+    pathname: string
+    parameters: {
+        required: string[]
+        optional: string[]
+    }
+}
+
+function getRouteParts(route: string): RouteParts {
+    const chunks = route.split('/').filter((chunk) => chunk && chunk.length > 0)
+    if (chunks.length === 0) {
+        throw new SdkError('Invalid route - routes may not be empty', { type: 'plugin_error' })
+    }
+
+    const parts: RouteParts = {
+        pathname: chunks[0] || '',
+        parameters: {
+            required: [],
+            optional: [],
+        },
+    }
+
+    chunks.forEach((part) => {
+        if (part.startsWith(':')) {
+            if (part.endsWith('?')) {
+                parts.parameters.optional.push(part.slice(1, -1))
+            } else {
+                parts.parameters.required.push(part.slice(1))
+            }
+        }
+    })
+
+    return parts
+}
+
+const HARDCODED_LAYOUT = {
+    default: {
+        children: null,
+        items: [{ element_id: 'x', styles: {} }],
+        root: null,
+        rules: null,
+        styles: { 'flex-direction': 'column' },
+        templateId: '5832fd4d53c31010e6bcddeeff7b12db',
+        type: 'flex',
+    },
+    version: '3.0.0',
+}
+
+const createComposition = (component: Component) => {
+    const { tagName, properties = {} } = component
+    const componentId = idGenerator(tagName)
+
+    const UxfFormulaParser = new uxValueParser()
+    const propertyValues = Object.keys(properties).reduce((newObj, key) => {
+        const parseResult = UxfFormulaParser.parse(properties[key])
+        if (parseResult.errors.length) {
+            throw new SdkError('Failed to parse formula.', { type: 'plugin_error' })
+        }
+        newObj[key] = cleanUxValue(parseResult.result.uxValue)
+        return newObj
+    }, {})
+
+    return [
+        {
+            definition: { id: componentId, type: 'MACROPONENT' },
+            elementId: 'x',
+            elementLabel: tagName,
+            eventMappings: [],
+            isHidden: { type: 'JSON_LITERAL', value: null },
+            preset: null,
+            propertyValues,
+            slot: null,
+            styles: null,
+        },
+    ]
+}
+
+export default Plugin({
+    name: 'Routes',
+    ownedTables: {
+        sys_ux_app_route: { diagnosticLevel: Diagnostic.Level.Warn },
+    },
+    extractors: {
+        entity: {
+            // TODO: This needs to extract separate entities for each route and the experience. Currently it is extracting an
+            // anonymous "container" entity which goes against the design of the plugin architecture.
+            CallExpression: (node, context) =>
+                extractCallExpression(Routes, 'routes', node, context, () => 'NO_GUID_GENERATED'), // TODO: Generate GUID
+        },
+    },
+    composers: {
+        entity: {
+            routes(entity, context) {
+                const node = entity.getNode()
+                const data = entity.getValue()
+                const { experience, routes } = data as Routes
+
+                const { $id: appConfigId } = ExperienceSchema.parse(experience)
+                const appConfigSysId = context.registerExplicitId('sys_ux_app_config', appConfigId)
+
+                const records: Record[] = []
+                for (const [path, route] of Object.entries(routes)) {
+                    const { $id: routeId, name, component, active, description } = BaseUXRouteSchema.parse(route)
+                    const routeParts = getRouteParts(path)
+
+                    const screenType = Record({
+                        table: 'sys_ux_screen_type',
+                        $id: `${routeId}_screen_type`,
+                        data: {
+                            name,
+                        },
+                    })
+
+                    const routeRecord = Record({
+                        table: 'sys_ux_app_route',
+                        $id: routeId,
+                        data: {
+                            name,
+                            app_config: appConfigSysId,
+                            route_type: routeParts.pathname,
+                            fields: routeParts.parameters.required.join(','),
+                            optional_parameters: routeParts.parameters.optional.join(','),
+                            screen_type: screenType,
+                        },
+                    })
+
+                    const routeParameters = [...routeParts.parameters.required, ...routeParts.parameters.optional]
+                    const screenMcp = Record({
+                        table: 'sys_ux_macroponent',
+                        $id: `${routeId}_page`,
+                        data: {
+                            category: 'page',
+                            composition: JSON.stringify(createComposition(component), null, 2),
+                            extends: PAGE_TEMPLATE_SYS_ID,
+                            internal_event_mappings: JSON.stringify({}),
+                            layout: JSON.stringify(HARDCODED_LAYOUT, null, 2),
+                            name: `${name} - Page`,
+                            // Injecting Route parameters as props of the page, so that they can be passed into the
+                            // component in the composition.
+                            props: JSON.stringify(
+                                routeParameters.map((param) => {
+                                    return {
+                                        defaultValue: '',
+                                        description: null,
+                                        disabled: false,
+                                        fieldType: 'string',
+                                        label: param,
+                                        mandatory: false,
+                                        name: param,
+                                        readOnly: true,
+                                        selectable: false,
+                                        typeMetadata: null,
+                                        valueType: 'string',
+                                    }
+                                }),
+                                null,
+                                2
+                            ),
+                            schema_version: '1.0.0',
+                        },
+                    })
+
+                    // TODO(patrick): Still a lot of hardcoded stuff in here - needs
+                    //  to be represented in the config, at least optionally.
+                    const screen = Record({
+                        table: 'sys_ux_screen',
+                        $id: `${routeId}_screen`,
+                        data: {
+                            active: active!,
+                            app_config: appConfigSysId,
+                            description: description!,
+                            disable_auto_reflow: false,
+                            event_mappings: JSON.stringify([]),
+                            macroponent: screenMcp,
+                            macroponent_config: JSON.stringify({}),
+                            name: `${name} - Default`,
+                            order: 0,
+                            parent_macroponent: WORKSPACE_APP_SHELL_ID,
+                            required_translations: JSON.stringify([]),
+                            screen_type: screenType,
+                        },
+                    })
+
+                    records.push(screenType, routeRecord, screenMcp, screen)
+                }
+
+                return context.composeEntities(
+                    records.map(
+                        (r) =>
+                            new EntityData(
+                                'record',
+                                context.registerExplicitId(r.table, r.$id as string),
+                                ObjectData.fromObjectValue(r, node),
+                                node
+                            )
+                    ),
+                    [RecordPlugin]
+                )
+            },
+        },
+    },
+})

package/src/uxf/UxfFormulaParser/cleanUxValue.ts

@@ -0,0 +1,73 @@
+// Copied from sn-uxf-formula-parser-library - https://code.devsnc.com/dev/uxf-formula-parser
+
+/**
+ * https://code.devsnc.com/dev/uxf-formula-parser/blob/ci/master/src/uxf-formula-parser/clean/cleanUxValue.js
+ */
+
+export const cleanUxValue = (uxValue) => {
+    switch (uxValue?.type) {
+        case 'JSON_LITERAL':
+            return { type: uxValue.type, value: uxValue.value }
+
+        case 'CONTEXT_BINDING':
+        case 'DATA_OUTPUT_BINDING':
+        case 'STATE_BINDING':
+        case 'EVENT_PAYLOAD_BINDING':
+        case 'ELEMENT_BINDING':
+        case 'REPEATER_ITEM_BINDING':
+        case 'ENV_BINDING':
+            return { type: uxValue.type, binding: uxValue.binding }
+
+        case 'CLIENT_TRANSFORM':
+            return {
+                type: uxValue.type,
+                transform: {
+                    operator: uxValue.transform.operator,
+                    operands: cleanUxValue(uxValue.transform.operands),
+                },
+            }
+
+        case 'UNARY':
+            return {
+                type: uxValue.type,
+                operation: {
+                    ...uxValue.operation,
+                    operand: cleanUxValue(uxValue.operation.operand),
+                },
+            }
+
+        case 'BINARY':
+            return {
+                type: uxValue.type,
+                operation: {
+                    ...uxValue.operation,
+                    operator: uxValue.operation.operator,
+                    left: cleanUxValue(uxValue.operation.left),
+                    right: cleanUxValue(uxValue.operation.right),
+                },
+            }
+
+        case 'LIST_CONTAINER':
+            return {
+                type: uxValue.type,
+                container: uxValue.container.map((item) => cleanUxValue(item)),
+            }
+
+        case 'MAP_CONTAINER':
+            return {
+                type: uxValue.type,
+                container: Object.entries(uxValue.container).reduce(
+                    (acc, [key, item]) => ({
+                        ...acc,
+                        [key]: cleanUxValue(item),
+                    }),
+                    {}
+                ),
+            }
+
+        case 'TRANSLATION_LITERAL':
+            return { type: uxValue.type, value: uxValue.value }
+    }
+
+    return uxValue
+}