@servicenow/sdk-build-plugins 2.0.1

package/src/atf/TestPlugin.ts

@@ -0,0 +1,119 @@
+import { CallExpression } from 'ts-morph'
+import {
+    ConfigEntity,
+    ConfigurationFunctionExtractor,
+    Context,
+    EntityData,
+    LinkedDocument,
+    ObjectData,
+    Plugin,
+    recordXml,
+    unloadBuilder,
+} from '@servicenow/sdk-build-core'
+import { ATF, getRecordIdIfRecord } from './ATFComposer'
+import { RecordPlugin } from '../db/RecordPlugin'
+import { Record } from '@servicenow/sdk-core/runtime/db'
+
+export default Plugin({
+    name: 'Test',
+    extractors: {
+        entity: {
+            CallExpression: (node: CallExpression, context: Context) => {
+                // This constructs an entity of kind 'test' and returns it. This entity is then parsed by the composer
+                const configExtractor = new ConfigurationFunctionExtractor(node, context, ATF)
+                const result = configExtractor.extractConfigFunction('test', context.logger)
+                if (!result) {
+                    return { handled: false }
+                }
+
+                return {
+                    handled: true,
+                    diagnostics: [],
+                    data: [result],
+                }
+            },
+        },
+    },
+    composers: {
+        entity: {
+            test(entity, context) {
+                const node = entity.getNode()
+                const data = entity.getValue()
+                const dataType: ConfigEntity = data as any
+                const stepCreator = new ATF(dataType.inputObject as any, context)
+                // Iterate over all steps parsed from the AST and call their corresponding implementation in the ATF Composer
+                const configEntries = dataType.configEntries
+                for (const index of Object.keys(configEntries)) {
+                    const step = configEntries[index]
+                    if (step.name != 'constructor' && stepCreator[step.name]) {
+                        try {
+                            stepCreator[step.name](step.info)
+                            // Step incrementation is handled here so that you do not need to be concerned when adding new step
+                            stepCreator.incrementOrder()
+                        } catch (e) {
+                            context.logger.error(`Caught error composing step '${step.name}': `, e)
+                            throw e
+                        }
+                    }
+                }
+                // Add test to return data
+                const returnData: LinkedDocument[] = context.composeEntities(
+                    [
+                        new EntityData(
+                            'record',
+                            context.registerExplicitId('sys_atf_test', stepCreator.test.$id as string),
+                            ObjectData.fromObjectValue(stepCreator.test, node),
+                            node
+                        ),
+                    ],
+                    [RecordPlugin]
+                )
+
+                // Add steps and their variables to return data
+                stepCreator.stepRecords.forEach((step) => {
+                    const stepID = getRecordIdIfRecord(step, context)
+                    returnData.push({
+                        guid: stepID,
+                        kind: 'step',
+                        node,
+                        data: {
+                            step,
+                            data: stepCreator.records[stepID],
+                        },
+                    })
+                })
+                return returnData
+            },
+        },
+    },
+    serializers: {
+        step(document, context) {
+            const data: {
+                step: Record<'sys_atf_step'>
+                data: (Record<'sys_variable_value'> | Record<'sys_element_mapping'>)[]
+            } = document.data as any
+            const builder = unloadBuilder(context)
+            // First create the step xml
+            const stepNode = recordXml(builder.xml, 'sys_atf_step', getRecordIdIfRecord(data.step, context) as string)
+            Object.keys(data.step.data).forEach((key) => {
+                stepNode.field(key, getRecordIdIfRecord(data.step.data[key], context))
+            })
+
+            // Then add all variables and element mappings associated with the step
+            data.data.forEach((varRecord) => {
+                const varNode = recordXml(builder.xml, varRecord.table, getRecordIdIfRecord(varRecord, context))
+                Object.keys(varRecord.data).forEach((key) => {
+                    const value = getRecordIdIfRecord(varRecord.data[key], context)
+                    varNode.field(key, typeof value === 'undefined' ? '' : value)
+                })
+            })
+
+            // Return the entire thing as a bundle
+            return {
+                name: `sys_atf_step_${document.guid}.xml`,
+                directory: 'update',
+                content: builder.end(),
+            }
+        },
+    },
+})

package/src/atf/index.ts

@@ -0,0 +1 @@
+export { default as TestPlugin } from './TestPlugin'

package/src/db/ColumnPlugins.ts

@@ -0,0 +1,117 @@
+import * as db from '@servicenow/sdk-core/runtime/db'
+import { EntityData, FluentDiagnostic, ObjectData, Plugin, extractCallExpression } from '@servicenow/sdk-build-core'
+
+const validFunctions = [
+    'add',
+    'coalesce',
+    'concat',
+    'datediff',
+    'dayofweek',
+    'distance_sphere',
+    'divide',
+    'greatest',
+    'least',
+    'length',
+    'multiply',
+    'position',
+    'substring',
+    'subtract',
+]
+
+const regExp = new RegExp(`^glidefunction:(${validFunctions.join('|')})[(].*?[)]$`, 'g')
+
+function ColumnPlugin<
+    const A extends unknown[],
+    const E extends A extends [infer T extends Record<string, unknown>] ? T : never,
+    const K extends string,
+>(fn: (...args: A) => E, entityKind: K) {
+    return Plugin({
+        name: `${entityKind}Column`,
+        extractors: {
+            entity: {
+                CallExpression(node, context) {
+                    const result = extractCallExpression(
+                        fn,
+                        `${entityKind}Column`,
+                        node,
+                        context,
+                        () => 'NO_GUID_GENERATED' // TODO: We shouldn't need to generate any GUID here but maybe should provide something unique to be on the safe side
+                    )
+                    if (!result.handled || !(0 in result.data)) {
+                        return result
+                    }
+
+                    const entity = result.data[0]
+                    const diagnostics = result.diagnostics
+                    const functionDefinition = entity.getProperty('function_definition')?.getValue()
+                    if (functionDefinition) {
+                        if (typeof functionDefinition !== 'string' || !functionDefinition.match(regExp)) {
+                            diagnostics.push(
+                                new FluentDiagnostic(
+                                    node,
+                                    `'function_definition' must start with 'glidefunction:' and include a single function call to a predefined function:\n${validFunctions.join(
+                                        '\n'
+                                    )}`
+                                )
+                            )
+                        }
+                    }
+
+                    return {
+                        handled: true,
+                        diagnostics,
+                        data: [
+                            new EntityData(
+                                entity.getKind(),
+                                entity.getGuid(),
+                                ObjectData.fromObjectValue(
+                                    {
+                                        ...entity.getValue(),
+                                        entityKind,
+                                    },
+                                    entity.getNode()
+                                ),
+                                entity.getNode()
+                            ),
+                        ],
+                    }
+                },
+            },
+        },
+    })
+}
+
+export const StringColumnPlugin = ColumnPlugin(db.StringColumn, 'string')
+export const BooleanColumnPlugin = ColumnPlugin(db.BooleanColumn, 'boolean')
+export const IntegerColumnPlugin = ColumnPlugin(db.IntegerColumn, 'integer')
+export const BasicImageColumnPlugin = ColumnPlugin(db.BasicImageColumn, 'basicImage')
+export const ConditionsColumnPlugin = ColumnPlugin(db.ConditionsColumn, 'conditions')
+export const ChoiceColumnPlugin = ColumnPlugin(db.ChoiceColumn, 'choice')
+export const DecimalColumnPlugin = ColumnPlugin(db.DecimalColumn, 'decimal')
+export const DocumentIdColumnPlugin = ColumnPlugin(db.DocumentIdColumn, 'documentId')
+export const DomainIdColumnPlugin = ColumnPlugin(db.DomainIdColumn, 'domainId')
+export const DomainPathColumnPlugin = ColumnPlugin(db.DomainPathColumn, 'domainPath')
+export const ListColumnPlugin = ColumnPlugin(db.ListColumn, 'list')
+export const ReferenceColumnPlugin = ColumnPlugin(db.ReferenceColumn, 'reference')
+export const RadioColumnPlugin = ColumnPlugin(db.RadioColumn, 'radio')
+export const ScriptColumnPlugin = ColumnPlugin(db.ScriptColumn, 'script')
+export const SystemClassNameColumnPlugin = ColumnPlugin(db.SystemClassNameColumn, 'systemClassName')
+export const TableNameColumnPlugin = ColumnPlugin(db.TableNameColumn, 'tableName')
+export const TranslatedFieldColumnPlugin = ColumnPlugin(db.TranslatedFieldColumn, 'translatedField')
+export const TranslatedTextColumnPlugin = ColumnPlugin(db.TranslatedTextColumn, 'translatedText')
+export const UserRolesColumnPlugin = ColumnPlugin(db.UserRolesColumn, 'userRoles')
+export const VersionColumnPlugin = ColumnPlugin(db.VersionColumn, 'version')
+export const FieldNameColumnPlugin = ColumnPlugin(db.FieldNameColumn, 'fieldName')
+
+// Date columns
+export const DateColumnPlugin = ColumnPlugin(db.DateColumn, 'glide_date')
+export const DateTimeColumnPlugin = ColumnPlugin(db.DateTimeColumn, 'glide_date_time')
+export const CalendarDateTimeColumnPlugin = ColumnPlugin(db.CalendarDateTimeColumn, 'calendar_date_time')
+export const BasicDateTimeColumnPlugin = ColumnPlugin(db.BasicDateTimeColumn, 'datetime')
+export const DueDateColumnPlugin = ColumnPlugin(db.DueDateColumn, 'due_date')
+export const IntegerDateColumnPlugin = ColumnPlugin(db.IntegerDateColumn, 'integer_date')
+export const ScheduleDateTimeColumnPlugin = ColumnPlugin(db.ScheduleDateTimeColumn, 'schedule_date_time')
+export const OtherDateColumnPlugin = ColumnPlugin(db.OtherDateColumn, 'date')
+
+// Catch all column type which keys of off 'internal_type'
+export const GenericColumnPlugin = ColumnPlugin(db.GenericColumn, 'generic')

package/src/db/RecordPlugin.ts

@@ -0,0 +1,391 @@
+import { Record, TableName } from '@servicenow/sdk-core/runtime/db'
+import {
+    Context,
+    Plugin,
+    getCallExpressionName,
+    isGUID,
+    removeNode,
+    transformFunctionArguments,
+    unloadBuilder,
+    linkDocument,
+    generateCallExpressionExportForDocument,
+    getOrCreateEntitySourceFile,
+    XmlData,
+    FluentDiagnostic,
+    ExtractionResult,
+    EntityData,
+    extractCallExpression,
+    ObjectData,
+} from '@servicenow/sdk-build-core'
+import { z } from 'zod'
+import { CallExpression, SyntaxKind } from 'ts-morph'
+
+// TODO: This schema should live with the Record entity function itself
+export const RecordEntitySchema = z.object({
+    $id: z.string().or(z.number()),
+    data: z.record(z.any()),
+    table: z.string(),
+})
+
+type RecordData = z.output<typeof RecordEntitySchema>
+type Data = { [key: string]: string | number | boolean }
+
+const RecordUpdate = z.object({
+    record_update: z.record(z.any()),
+})
+
+const RecordUpdateTableSchema = z.object({
+    '@_table': z.string(),
+})
+
+export const TextStringSchema = z.object({ '#text': z.string() }).transform((val) => val['#text'])
+export const TextBooleanSchema = z.object({ '#text': z.boolean() }).transform((val) => val['#text'])
+export const TextNumberSchema = z.object({ '#text': z.number().or(z.literal('')) }).transform((val) => val['#text'])
+
+const SysJournalFieldSchema = z.object({
+    element: TextStringSchema,
+    element_id: TextStringSchema,
+    name: TextStringSchema,
+    sys_id: TextStringSchema,
+    value: TextStringSchema,
+})
+
+export type SysJournalField = z.infer<typeof SysJournalFieldSchema>
+
+const ignoreTables = ['sys_metadata_link', 'sys_module', 'sys_ux_lib_asset', 'sys_app', 'sys_store_app']
+const ignoreFields = [
+    'sys_created_by',
+    'sys_created_on',
+    'sys_updated_by',
+    'sys_updated_on',
+    'sys_mod_count',
+    'sys_class_name',
+    'sys_id',
+    'sys_package',
+    'sys_policy',
+    'sys_scope',
+    'sys_update_name',
+]
+const ignoreXMLElement = ['sys_translated_text', 'sys_es_latest_script']
+
+export const RecordXmlSchema = z
+    .object({
+        '@_action': z.union([z.literal('INSERT_OR_UPDATE'), z.literal('DELETE'), z.literal('delete_multiple')]),
+        sys_id: z.object({
+            '#text': z.string().min(32).max(32),
+        }),
+    })
+    .catchall(
+        z.intersection(
+            z.object({
+                '#text': z.union([z.string(), z.boolean(), z.number(), z.undefined()]),
+            }),
+            z.record(z.any()) // capture all attributes
+        )
+    )
+
+export const RecordDocumentSchema = z.object({
+    data: z.record(z.union([z.string(), z.number(), z.boolean(), z.undefined(), z.null()])),
+    table: z.string(),
+})
+
+function cleanRecordUpdate(recordUpdate: globalThis.Record<string, unknown>) {
+    ignoreXMLElement.forEach((element) => delete recordUpdate[element])
+    return recordUpdate
+}
+
+export const RecordPlugin = Plugin({
+    name: 'Record',
+    extractors: {
+        entity: {
+            CallExpression: (node, context) => {
+                const result = extractCallExpression(
+                    Record,
+                    'record',
+                    node,
+                    context,
+                    (record) => {
+                        // Take the guid from the id property, a sys_id property, or generate one
+                        if ('sys_id' in record.data) {
+                            return record.data['sys_id'] as string
+                        } else if (isGUID(record.$id as string)) {
+                            return record.$id as string
+                        } else {
+                            return context.keys.registerExplicitId(record.table, record.$id as string)
+                        }
+                    },
+                    (record): record is Record => RecordEntitySchema.safeParse(record).success
+                )
+
+                if (!result.handled || !(0 in result.data)) {
+                    return result
+                }
+
+                const record = result.data[0]
+                const diagnostics = result.diagnostics
+                const tableName = record.getProperty('table').getValue()
+                const pluginInfo = context.getPluginForTable(tableName)
+
+                if (pluginInfo) {
+                    const { logLevel, api } = pluginInfo
+                    const tableNode = node
+                        .getFirstChildByKindOrThrow(SyntaxKind.ObjectLiteralExpression)
+                        .getPropertyOrThrow('table')
+
+                    diagnostics.push(
+                        new FluentDiagnostic(
+                            tableNode,
+                            `${tableName} should not be created by the Record API. Please use the ${api} API.`,
+                            { level: logLevel }
+                        )
+                    )
+                }
+
+                // TODO: Get this out of the RecordPlugin somehow. Maybe need to provide a new mechanism for
+                // plugins to add diagnostics for entities extracted by other plugins?
+                if (tableName === 'sys_ui_view') {
+                    const viewName = record.getProperty('data').getProperty('name')?.getValue()
+                    const viewDataNode = node
+                        .getFirstChildByKindOrThrow(SyntaxKind.ObjectLiteralExpression)
+                        .getPropertyOrThrow('data')
+                        .asKindOrThrow(SyntaxKind.PropertyAssignment)
+                        .getInitializerIfKind(SyntaxKind.ObjectLiteralExpression)
+
+                    const viewNameNode = viewDataNode?.getPropertyOrThrow('name')
+                    const nameRegex = new RegExp(`^[a-zA-Z0-9_]+$`)
+
+                    if (typeof viewName !== 'string' || !viewName.match(nameRegex)) {
+                        diagnostics.push(
+                            new FluentDiagnostic(viewNameNode!, `View name can only contain alphanumeric characters`)
+                        )
+                    }
+                }
+
+                return {
+                    handled: true,
+                    diagnostics,
+                    data: [record],
+                }
+            },
+        },
+        xml(xml, context) {
+            // Parse out record_Update info
+            const recordUpdateResult = RecordUpdate.safeParse(xml.data)
+            if (!recordUpdateResult.success) {
+                return undefined
+            }
+
+            // Parse root level @_table from record_update
+            const recordUpdate = cleanRecordUpdate(recordUpdateResult.data.record_update)
+            let tableRecord, recordTable
+            const table = RecordUpdateTableSchema.safeParse(recordUpdate)
+            if (!table.success) {
+                // TODO A record plugin should only handle 1 table record?
+                // Taking the first one for now. Shouldn't assume this is the right one
+                recordTable = Object.keys(recordUpdate)[0] as string
+                tableRecord = recordUpdate[recordTable]
+            } else {
+                recordTable = table.data['@_table']
+                tableRecord = recordUpdate[table.data['@_table']]
+            }
+            const ignoreTableList = [...context.app.config.ignoreTransformTableList, ...ignoreTables]
+            if (!tableRecord || ignoreTableList.includes(recordTable)) {
+                return undefined
+            }
+            const recordParse = RecordXmlSchema.safeParse(tableRecord)
+            if (!recordParse.success) {
+                return undefined
+            }
+
+            if (
+                tableRecord['@_action'] !== 'DELETE' &&
+                Object.keys(recordUpdate).some((k) => k !== recordTable && !k.startsWith('@_'))
+            ) {
+                // Record contains other entries in the file that cannot be processed
+                return undefined
+            }
+
+            try {
+                const {
+                    '@_action': action,
+                    sys_id: { '#text': sysId },
+                    ...rest
+                } = tableRecord
+
+                const record = Object.entries(rest).reduce((out, [k, v]) => {
+                    out[k] = v ? v['#text'] : undefined
+                    return out
+                }, {})
+
+                return new XmlData(
+                    {
+                        id: sysId,
+                        table: recordTable,
+                        data: record,
+                    },
+                    xml.filePath,
+                    'record',
+                    action
+                )
+            } catch (err) {
+                return undefined // TODO: What are we catching here?
+            }
+        },
+    },
+    composers: {
+        entity: {
+            record(entity, context) {
+                const { $id, ...record } = RecordEntitySchema.parse(entity.getValue())
+                const fixedData = Object.entries(record.data).reduce((out, [c, v]) => {
+                    if (!v || typeof v !== 'object') {
+                        out[c] = v
+                        return out
+                    }
+
+                    const record = RecordEntitySchema.safeParse(v)
+                    if (record.success) {
+                        // User can override hashing w/ explicit sys_id
+                        if ('sys_id' in record.data.data) {
+                            out[c] = record.data.data['sys_id']
+                        } else if (isGUID(record.data.$id)) {
+                            out[c] = record.data.$id
+                        } else {
+                            out[c] = context.keys.registerExplicitId(record.data.table, record.data.$id)
+                        }
+                        return out
+                    }
+
+                    throw Error(`Unknown object assigned to '${c}' column: ${JSON.stringify(v, undefined, 4)}`)
+                }, {})
+
+                const data: RecordData = {
+                    table: record.table,
+                    $id, //preserve the original id if set
+                    data: fixedData,
+                }
+
+                return {
+                    kind: 'record',
+                    node: entity.getNode(),
+                    guid: entity.getGuid(),
+                    data,
+                }
+            },
+        },
+        xml: {
+            record(xml) {
+                const table = xml.data['table'] as string
+                const sysId = xml.data['id'] as string
+
+                return {
+                    action: xml.action,
+                    guid: sysId,
+                    kind: 'record',
+                    data: { table, data: xml.data['data'] },
+                }
+            },
+        },
+    },
+    serializers: {
+        record(document, context) {
+            const { table, data } = RecordDocumentSchema.parse(document.data)
+            const recordBuilder = unloadBuilder(context)
+            const builder = recordBuilder.record(table, document.guid, document.action)
+
+            Object.entries(data)
+                .filter(([c, v]) => typeof v !== 'undefined' && c !== 'sys_id')
+                .forEach(([c, v]) => builder.field(c, v))
+
+            return {
+                name: `${table}_${document.guid}.xml`,
+                directory: 'update',
+                content: recordBuilder.end(),
+            }
+        },
+    },
+    generators: {
+        record(document, context) {
+            return linkDocument(
+                document,
+                generateCallExpressionExportForDocument(
+                    context,
+                    {
+                        sourceFile: getOrCreateEntitySourceFile(
+                            context,
+                            `${document.data?.['table']}_${document.guid}`
+                        ),
+                        moduleSpecifier: '@servicenow/sdk/core',
+                    },
+                    Record,
+                    { $id: document.guid }
+                ).getExpressionIfKindOrThrow(SyntaxKind.CallExpression)
+            )
+        },
+    },
+    transformers: {
+        record: {
+            CallExpression(document) {
+                if (getCallExpressionName(document.node) !== Record.name) {
+                    return false
+                }
+
+                if (document.action === 'DELETE') {
+                    removeNode(document.node)
+                    return true
+                }
+
+                if (!document.changedData) {
+                    return false
+                }
+
+                const { table } = document.data as RecordData
+                const data = (document.changedData as any).data as Data
+
+                const properties = Object.keys(data).reduce((out, key) => {
+                    if (ignoreFields.includes(key)) {
+                        return out
+                    }
+
+                    if (data[key] !== '' && data[key] !== undefined) {
+                        out[key] = data[key]
+                    }
+
+                    return out
+                }, {} as Record)
+
+                transformFunctionArguments(document.node, Record, {
+                    table,
+                    data: properties,
+                })
+
+                return true
+            },
+        },
+    },
+})
+
+export function extractCallExpressionAsRecord<
+    const A extends unknown[],
+    const E extends A extends [infer T extends globalThis.Record<string, unknown>] ? T : never,
+    const T extends TableName,
+>(
+    fn: (...args: A) => E,
+    asRecord: (entity: E) => Record<T>,
+    guid: (entity: E) => string,
+    node: CallExpression,
+    context: Context
+): ExtractionResult<EntityData<Record<T>>> {
+    const result = extractCallExpression(fn, 'record', node, context, guid)
+    if (!result.handled) {
+        return result
+    }
+
+    return {
+        handled: true,
+        diagnostics: result.diagnostics,
+        // data: result.data.map((d) => new EntityData(context, node, 'record', d.guid, asRecord(d.data))),
+        data: result.data.map(
+            (d) => new EntityData('record', d.getGuid(), ObjectData.fromObjectValue(asRecord(d.getValue()), node), node)
+        ),
+    }
+}