@servicenow/sdk-build-plugins 2.0.1

package/src/ListPlugin.ts

@@ -0,0 +1,497 @@
+import { List } from '@servicenow/sdk-core/runtime/ui'
+import {
+    Plugin,
+    PrimitiveData,
+    extractCallExpression,
+    generateCallExpressionExportForDocument,
+    getCallExpressionName,
+    getOrCreateEntitySourceFile,
+    linkDocument,
+    recordXml,
+    removeNode,
+    unloadBuilder,
+    getOrCreatePropertyAssignment,
+    setPropertyAssignmentValue,
+    getSysUpdateName,
+    XmlData,
+    writePropertyAsReference,
+    getPropertyAssignment,
+    addDefaultImportIfAbsent,
+    addNamedImportIfAbsent,
+} from '@servicenow/sdk-build-core'
+import { RecordXmlSchema } from './db/RecordPlugin'
+import * as z from 'zod'
+import { SyntaxKind, Node, PropertyAssignment, CallExpression, VariableDeclaration } from 'ts-morph'
+import * as path from 'path'
+import { Diagnostic } from '@servicenow/sdk-project'
+
+const DEFAULT_VIEW = 'Default view'
+
+type View = {
+    id: string
+    name: string
+    title: string
+}
+
+type TransformData = {
+    sys_id: string
+    view: View
+    list: Omit<List, 'columns'>
+    table: string
+    elements: SysUIListElementXml
+}
+
+export default Plugin({
+    name: 'List',
+    ownedTables: {
+        sys_ui_list: { diagnosticLevel: Diagnostic.Level.Warn },
+    },
+    extractors: {
+        entity: {
+            CallExpression(node, context) {
+                return extractCallExpression(List, 'list', node, context, (list) =>
+                    context.keys.registerExplicitId('sys_ui_list', list.$id as string)
+                )
+            },
+        },
+        xml(xml) {
+            const result = SysUIListXmlSchema.safeParse(xml.data['record_update'])
+            if (!result.success) {
+                return undefined
+            }
+
+            const {
+                data: {
+                    sys_ui_list: { sys_ui_list, sys_ui_list_element },
+                    sys_metadata_delete,
+                },
+            } = result
+
+            //Delete only gets set on the top level sys_ui_list action attribute, not on sub nodes
+            const isDelete = result.data.sys_ui_list['@_action'] === 'DELETE'
+            const list = xmlElementToObject(sys_ui_list)
+            const elements = toArray(sys_ui_list_element).map(xmlElementToObject)
+            let updateName = list['sys_update_name']
+            // sys_update_name is not present on the list element, but is present on the delete element on delete payload
+            if (isDelete && sys_metadata_delete) {
+                const metadataDelete = xmlElementToObject(sys_metadata_delete)
+                updateName = metadataDelete['sys_update_name']
+            }
+
+            const viewName = sys_ui_list['view']['@_name']
+            const view = {
+                title: sys_ui_list['view']['@_display_value'],
+                name: viewName === 'NULL' ? 'default_view' : viewName,
+                id: sys_ui_list['view']['#text'],
+            }
+
+            return new XmlData(
+                {
+                    updateName,
+                    sys_id: list['sys_id'],
+                    view,
+                    elements,
+                    table: list['name'],
+                },
+                xml.filePath,
+                'list',
+                isDelete ? 'DELETE' : list['@_action']
+            )
+        },
+    },
+    composers: {
+        entity: {
+            list(entity, context) {
+                const node = entity.getNode()
+                const guid = entity.getGuid()
+                const data = entity.getValue()
+                const { view, columns, table } = data as List
+
+                const viewInfo: View = {
+                    id:
+                        view.$id === DEFAULT_VIEW
+                            ? view.$id
+                            : context.keys.registerExplicitId('sys_ui_view', view.$id as unknown as string),
+                    name: view.data.name,
+                    title: view.data.title,
+                }
+
+                return {
+                    kind: 'list',
+                    node,
+                    guid: getListUpdateName(viewInfo, table),
+                    data: {
+                        id: guid,
+                        table,
+                        view: viewInfo,
+                        elements: columns,
+                    },
+                }
+            },
+        },
+        xml: {
+            list(xml) {
+                const { sys_id, view, elements, table } = xml.data as TransformData
+                return {
+                    action: xml.action,
+                    kind: xml.kind,
+                    guid: xml.data['updateName'] as string,
+                    data: {
+                        id: sys_id,
+                        table,
+                        view,
+                        elements,
+                    },
+                }
+            },
+        },
+    },
+    transformers: {
+        list: {
+            CallExpression(document, context) {
+                const expressionName = getCallExpressionName(document.node)
+                if (expressionName !== List.name) {
+                    return false
+                }
+
+                if (document.action === 'DELETE') {
+                    removeNode(document.node)
+                    return true
+                }
+                if (document.action !== 'INSERT_OR_UPDATE') {
+                    return false
+                }
+                const [listArgument] = document.node.getArguments()
+                if (!Node.isObjectLiteralExpression(listArgument)) {
+                    return false
+                }
+
+                const { elements, view, table } = document.xmlData as TransformData
+                updateView(context, listArgument, view)
+
+                //create the table reference for now, user will need to fix to proper import
+                const tableProperty = getOrCreatePropertyAssignment(listArgument, 'table', '')
+                setPropertyAssignmentValue(tableProperty, table)
+
+                const arrayElements = toArray(elements)
+
+                //update the columns
+                const columnsProperty = getOrCreatePropertyAssignment(listArgument, 'columns', '[]')
+                const columns = arrayElements.sort((a, b) => (a['position'] as number) - (b['position'] as number))
+                setColumnsList(columnsProperty, columns)
+
+                return true
+            },
+        },
+    },
+    generators: {
+        list(document, context) {
+            const { id } = document.data as any
+            return linkDocument(
+                document,
+                generateCallExpressionExportForDocument(
+                    context,
+                    {
+                        sourceFile: getOrCreateEntitySourceFile(context, getSysUpdateName(document, 'sys_ui_list')),
+                        moduleSpecifier: '@servicenow/sdk/core',
+                    },
+                    List,
+                    { $id: id }
+                ).getExpressionIfKindOrThrow(SyntaxKind.CallExpression)
+            )
+        },
+    },
+    serializers: {
+        list(document, context) {
+            const {
+                id: listId,
+                elements: columns,
+                table,
+                view,
+            } = document.data as {
+                id: string
+                elements: Array<any>
+                table: string
+                view: View
+            }
+            const xmlBuilder = unloadBuilder(context)
+            /**
+             * Structure that needs to be built for sys_ui_list
+             * <sys_ui_list>
+             *  <sys_ui_list_element>
+             *    <sys_id/>
+             *  </sys_ui_list_element>
+             *  <sys_ui_list>
+             *   <sys_id/>
+             *   <view/>
+             *  </sys_ui_list>
+             * </sys_ui_list>
+             */
+
+            const listBuilder = xmlBuilder.xml.addJsonObj('sys_ui_list', undefined, {
+                table: table,
+                view: view.id === DEFAULT_VIEW ? '' : view.name,
+            })
+
+            columns.forEach((column, index) => {
+                let elementProperties = column
+
+                if (typeof column === 'string') {
+                    elementProperties = {
+                        element: column,
+                        position: index,
+                    }
+                }
+
+                if (elementProperties.position === undefined) {
+                    elementProperties.position = index
+                }
+
+                const childNode = recordXml(
+                    listBuilder,
+                    'sys_ui_list_element',
+                    context.keys.registerCompositeId('sys_ui_list_element', {
+                        list: listId,
+                        element: elementProperties.element,
+                    })
+                )
+
+                childNode.field('list_id', listId, {
+                    display_value: table,
+                    view: view.id,
+                })
+
+                Object.entries(elementProperties)
+                    .filter(([, v]) => typeof v !== 'undefined')
+                    .forEach(([n, v]) => childNode.field(n, v))
+            })
+
+            const sysUIList = recordXml(listBuilder, 'sys_ui_list', listId)
+            sysUIList.addSysScope(context)
+            sysUIList.field('view', view.id, {
+                display_value: view.title,
+                name: view.name,
+            })
+            sysUIList.field('name', table)
+
+            return {
+                name: `${document.guid}.xml`,
+                directory: 'update',
+                content: xmlBuilder.end(),
+            }
+        },
+    },
+})
+
+/*
+ * Update the view property of the list argument
+ * If the view is the default view, write view as a reference from the core package
+ * If the view is a record, look for a record entity and write the view as a reference
+ *
+ * **Note:** View Cannot be updated using list layout on the instance,
+ * if the view is updated directly from sys_ui_list table, then update name changes and a new List entity is created
+ *
+ */
+const updateView = (context, listArgument, view) => {
+    const viewAssignment = getPropertyAssignment(listArgument, 'view')
+    if (viewAssignment) {
+        return
+    }
+    const viewRecord = context.getDocument(view.id)
+
+    if (view.id === DEFAULT_VIEW) {
+        writePropertyAsReference(listArgument, 'view', '', view.name)
+    } else if (viewRecord) {
+        const nodeSource = listArgument.getSourceFile()
+        const viewNode = viewRecord.node
+        const viewPath = getImportPath(nodeSource.getFilePath(), viewNode.getSourceFile().getFilePath())
+
+        if (!viewPath) {
+            const identifier = getIdentifier(viewNode)
+            if (identifier) {
+                listArgument.addPropertyAssignment({ name: 'view', initializer: identifier })
+                return
+            }
+            context.logger.warn(
+                `Could not find identifier for view ${view.name}, consider adding one to use as a reference`
+            )
+            listArgument.addPropertyAssignment({ name: 'view', initializer: view.name })
+            return
+        }
+
+        // If the view record is not in the same file, add a reference to the view record
+        const viewExport = getExportTypeAndName(viewNode)
+
+        if (!viewExport.exported) {
+            context.logger.warn(
+                `View record is defined in ${path.normalize(viewNode.getSourceFile().getFilePath())} and is not exported`
+            )
+            listArgument.addPropertyAssignment({ name: 'view', initializer: view.name })
+            return
+        }
+
+        // Add a reference to the view record and add an import statement
+        if (viewExport.type === 'Default') {
+            listArgument.addPropertyAssignment({ name: 'view', initializer: view.name })
+            addDefaultImportIfAbsent(nodeSource, viewPath, view.name)
+        } else {
+            listArgument.addPropertyAssignment({ name: 'view', initializer: viewExport.identifier })
+            addNamedImportIfAbsent(context, nodeSource, viewPath, viewExport.identifier)
+        }
+    } else {
+        listArgument.addPropertyAssignment({ name: 'view', initializer: view.name })
+    }
+}
+
+type ExportsInfo =
+    | { exported: false; identifier?: string }
+    | { exported: true; identifier: string; type: 'Named' }
+    | { exported: true; type: 'Default' }
+
+const getExportTypeAndName = (sourceNode: CallExpression): ExportsInfo => {
+    // const defaultExports = sourceNode.getSourceFile().getExportSymbols()
+    const parentNode = sourceNode.getParent()
+
+    // export declarations are blocked by fluent-diagnostics
+    switch (parentNode?.getKind()) {
+        case SyntaxKind.ExportAssignment:
+            return { exported: true, type: 'Default' }
+        case SyntaxKind.VariableDeclaration: {
+            const identifier = getIdentifier(parentNode as VariableDeclaration)!
+
+            const variableStmt = parentNode.getParentIfKind(SyntaxKind.VariableStatement)
+            const exportKeyword = variableStmt?.getFirstChildByKind(SyntaxKind.ExportKeyword)
+
+            if (exportKeyword) {
+                return { exported: true, type: 'Named', identifier }
+            }
+            return { exported: false, identifier }
+        }
+
+        case SyntaxKind.ExpressionStatement:
+        default:
+            return { exported: false }
+    }
+}
+
+const getIdentifier = (sourceNode: CallExpression | VariableDeclaration): string | undefined => {
+    const variableDeclaration =
+        sourceNode.getKind() === SyntaxKind.CallExpression
+            ? sourceNode.getParentIfKind(SyntaxKind.VariableDeclaration)
+            : sourceNode
+
+    return variableDeclaration?.getFirstChildByKind(SyntaxKind.Identifier)?.getText()
+}
+
+const getImportPath = (listSourcePath, viewSourcePath): string | undefined => {
+    if (listSourcePath === viewSourcePath) {
+        return
+    }
+
+    const viewFilePath = path.parse(viewSourcePath)
+    const listFilePath = path.parse(listSourcePath)
+    const relativePath = path.posix.join(path.relative(listFilePath.dir, viewFilePath.dir), viewFilePath.name)
+    // relativePath = relativePath.replace(path.extname(relativePath), '')
+    return relativePath.startsWith('.') ? relativePath : `./${relativePath}`
+}
+
+const setColumnsList = (columnsProperty: PropertyAssignment, elements: SysUIListElementXml) => {
+    const [array] = columnsProperty.getChildrenOfKind(SyntaxKind.ArrayLiteralExpression)
+    let serializeValue: string = '[]'
+    if (array) {
+        const elementSyntaxList = array.getChildAtIndexIfKind(1, SyntaxKind.SyntaxList)
+
+        //If the columns are defined as objects or need to be expressed that way due to additional properties set on instance
+        if (
+            !!elementSyntaxList?.getChildrenOfKind(SyntaxKind.ObjectLiteralExpression).length ||
+            columnsNeedObjectLiterals(elements)
+        ) {
+            const newElements = elements.map((element, index) => {
+                let newValue: Record<string, unknown>
+
+                if (typeof element === 'string') {
+                    newValue = element
+                } else {
+                    newValue = {
+                        element: element['element'],
+                        position: element['position'] ?? index,
+                    }
+                    if (element['average_value']) {
+                        newValue['average_value'] = true
+                    }
+                    if (element['max_value']) {
+                        newValue['max_value'] = true
+                    }
+                    if (element['min_value']) {
+                        newValue['min_value'] = true
+                    }
+                    if (element['sum']) {
+                        newValue['sum'] = true
+                    }
+                }
+
+                return newValue
+            })
+
+            serializeValue = JSON.stringify(newElements)
+        } else {
+            serializeValue = JSON.stringify(elements.map((e) => e['element']))
+        }
+    }
+    columnsProperty?.replaceWithText(`columns: ${serializeValue}`)
+}
+
+const columnsNeedObjectLiterals = (elements: SysUIListElementXml) => {
+    return elements.some((element) => {
+        return Object.keys(element)
+            .filter((key) => !key.startsWith('sys_') && !key.startsWith('@_'))
+            .some((key) => {
+                switch (key) {
+                    case 'position':
+                    case 'list_id':
+                    case 'element':
+                        return false
+                    case 'average_value':
+                    case 'max_value':
+                    case 'sum':
+                    case 'min_value':
+                        return !!element[key]
+                    default: //Non default properties are unknown so just return true
+                        return true
+                }
+            })
+    })
+}
+
+const xmlElementToObject = (element: PrimitiveData) => {
+    return Object.entries(element).reduce((out, [k, v]) => {
+        out[k] = typeof v === 'string' ? v : v ? v['#text'] : ''
+        return out
+    }, {})
+}
+
+const getListUpdateName = (view: View, table: string) => {
+    const viewName = view.title === DEFAULT_VIEW ? 'null' : view.name
+    return `sys_ui_list_${table}_${viewName}` //This name matches the generated
+}
+
+const SysUIListXmlSchema = z.object({
+    sys_ui_list: z.object({
+        '@_action': z.union([z.literal('DELETE'), z.literal('INSERT_OR_UPDATE')]).optional(),
+        '@_table': z.string(),
+        '@_view': z.string(),
+        sys_ui_list: RecordXmlSchema,
+        sys_ui_list_element: z.union([z.array(RecordXmlSchema), RecordXmlSchema]),
+    }),
+    sys_metadata_delete: z
+        .object({
+            sys_update_name: z.object({
+                '#text': z.string(),
+            }),
+        })
+        .optional(),
+})
+
+const toArray = (value: unknown) => (Array.isArray(value) ? value : [value])
+
+type SysUIListElementXml = z.infer<typeof RecordXmlSchema>[]