@servicenow/sdk-build-plugins 2.0.1

package/src/aclAndRole/AclPlugin.ts

@@ -0,0 +1,410 @@
+import {
+    Acl,
+    TableAcl,
+    NamedAcl,
+    AclAttributes,
+    AclBase,
+    AclOperations,
+    AclTypes,
+} from '@servicenow/sdk-core/runtime/app'
+import {
+    Context,
+    Plugin,
+    extractCallExpression,
+    generateCallExpressionExportForDocument,
+    getOrCreateEntitySourceFile,
+    getSysUpdateName,
+    linkDocument,
+    removeNode,
+    transformFunctionArguments,
+    FluentDiagnostic,
+    findObjectPropertyValue,
+    EntityData,
+    ObjectData,
+} from '@servicenow/sdk-build-core'
+import { addObjectToArrayById, removeObjectFromArrayById } from './Util'
+import { Record as DBRecord, TableName } from '@servicenow/sdk-core/runtime/db'
+import { scriptInfo, ScriptInfo, buildScriptImport, except } from '../scripts/scriptUtils'
+import * as ts from 'ts-morph'
+import { AclNamedTypes } from '@servicenow/sdk-core/runtime/app'
+import { processScript } from '../ScriptTemplatePlugin'
+import { Diagnostic } from '@servicenow/sdk-project'
+
+type AclDoc = {
+    table: string
+    data: {
+        sys_id: string
+    }
+}
+
+type AclRole = {
+    table: string
+    data: {
+        sys_security_acl: string
+        sys_user_role: string
+    }
+}
+
+type AclData = AclBase & {
+    name: string
+    type: keyof typeof AclTypes
+}
+
+const ExecuteOnlyTypes = new Set([
+    'client_callable_flow_object',
+    'client_callable_script_include',
+    'graphql',
+    'processor',
+    'rest_endpoint',
+])
+
+function aclAsRecord<T extends TableName>(config: Acl<T>) {
+    const tableConfig = config as TableAcl<T>
+    const namedConfig = config as NamedAcl
+
+    const field = String(tableConfig.field || '')
+    const name = namedConfig.name || (field ? `${tableConfig.table}.${field}` : tableConfig.table)
+    if (!name) {
+        throw new Error(`ACL of type ${config.type} and $id '${config.$id}' has no name or associated table`)
+    }
+
+    if (config.operation === 'execute' && !ExecuteOnlyTypes.has(config.type)) {
+        throw new Error(`ACL ${name} cannot use operation 'execute', because it is of type '${config.type}'`)
+    }
+    if (config.script && config.type === 'graphql') {
+        throw new Error(`ACL ${name} does not support scripts, because it is of type ${config.type}`)
+    }
+    if (tableConfig.applies_to && tableConfig.type !== 'record') {
+        throw new Error(`ACL ${name} cannot set applies_to unless its type is 'record'`)
+    }
+    if (tableConfig.operation === 'add_to_list' && (config.script || config.condition)) {
+        throw new Error(`ACL ${name} cannot have a script or condition due to its 'add_to_list' operation`)
+    }
+
+    return DBRecord({
+        table: 'sys_security_acl',
+        $id: config.$id,
+        data: {
+            name,
+            active: config.active ?? true,
+            type: AclTypes[config.type ?? 'record'],
+            operation: AclOperations[config.operation as keyof typeof AclOperations] || config.operation || '',
+            decision_type: config.decision_type ?? 'allow',
+            description: config.description || '',
+            local_or_existing: config.local_or_existing || 'Local',
+            admin_overrides: config.admin_overrides ?? true,
+            advanced: !!config.script,
+            condition: config.condition ?? '',
+            applies_to: tableConfig.applies_to ?? '',
+            script: config.script as any,
+            security_attribute:
+                (config.security_attribute && AclAttributes[config.security_attribute as keyof typeof AclAttributes]) ||
+                config.security_attribute ||
+                '',
+        },
+    })
+}
+
+export default Plugin({
+    name: 'Acl',
+    ownedTables: {
+        sys_security_acl: { diagnosticLevel: Diagnostic.Level.Warn },
+    },
+    extractors: {
+        entity: {
+            CallExpression(node, context) {
+                const result = extractCallExpression(Acl, 'record', node, context, (acl) =>
+                    context.registerExplicitId('sys_security_acl', acl.$id)
+                )
+
+                if (!result.handled || !(0 in result.data)) {
+                    return result
+                }
+
+                const acl = result.data[0]
+                const scriptVal = getScript(acl, context)
+                const aclRecord = aclAsRecord(acl.getValue())
+
+                const m2mRoleToAcl =
+                    acl
+                        .getProperty('roles')
+                        ?.getValue()
+                        ?.map((role) => {
+                            const roleId = typeof role === 'string' ? role : role.$id
+
+                            const aclId = context.keys.registerExplicitId('sys_security_acl', aclRecord.$id)
+                            const roleSysId =
+                                typeof role === 'string' ? role : context.registerExplicitId('sys_user_role', role.$id)
+                            const guid = context.keys.registerCompositeId('sys_security_acl_role', {
+                                sys_security_acl: aclRecord.$id,
+                                sys_user_role: roleId,
+                            })
+
+                            return new EntityData(
+                                'record',
+                                guid,
+                                ObjectData.fromObjectValue(
+                                    DBRecord({
+                                        table: 'sys_security_acl_role',
+                                        $id: guid,
+                                        data: {
+                                            sys_security_acl: aclId,
+                                            sys_user_role: roleSysId,
+                                        },
+                                    }),
+                                    node
+                                ),
+                                node
+                            )
+                        }) || []
+
+                const diagnostics = performDiagnosticChecksOnSecurityAttribute(
+                    node,
+                    acl.getValue(),
+                    m2mRoleToAcl,
+                    context.mode
+                )
+
+                const aclWithScript = { ...aclRecord, data: { ...aclRecord.data, script: scriptVal || '' } }
+                const aclEntityData = new EntityData(
+                    'record',
+                    acl.getGuid(),
+                    ObjectData.fromObjectValue(aclWithScript, node),
+                    node
+                )
+
+                return {
+                    handled: true,
+                    diagnostics: [...result.diagnostics, ...diagnostics],
+                    data: [aclEntityData, ...m2mRoleToAcl],
+                }
+            },
+        },
+        raw: {
+            FunctionDeclaration(node, context) {
+                const info = scriptInfo(node, context, Acl.name)
+                if (!info) {
+                    return { handled: false }
+                }
+
+                return { handled: true, diagnostics: [], data: [info] }
+            },
+
+            FunctionExpression(node, context) {
+                const info = scriptInfo(node, context, Acl.name)
+                if (!info) {
+                    return { handled: false }
+                }
+
+                return { handled: true, diagnostics: [], data: [info] }
+            },
+        },
+    },
+    arrangers: {
+        record(document, context) {
+            if ((document.data as any).table !== 'sys_security_acl_role') {
+                return { handled: false }
+            }
+
+            const aclId = (document.data as any).data.sys_security_acl
+            const aclDoc = context.getDocument(aclId, 'record')
+            const aclDeleted = aclDoc && aclDoc.action === 'DELETE'
+            if (aclDeleted && document.action === 'INSERT_OR_UPDATE') {
+                throw new Error(
+                    `Existing sys_security_acl_role with id ${document.guid} is referencing deleted ACL ${aclId}. This can be fixed by either deleting the sys_security_acl_role record or updating its sys_security_acl reference.`
+                )
+            }
+
+            return {
+                handled: true,
+                result: aclId ? { kind: 'record', guid: aclId } : undefined,
+            }
+        },
+    },
+    generators: {
+        record(document, context, linkedDocuments) {
+            const documentType = (document.data as any)?.table
+            if (documentType === 'sys_security_acl_role') {
+                if (!document.parent) {
+                    return undefined
+                }
+                const acl = linkedDocuments.find(
+                    (doc) =>
+                        (doc.data as AclDoc).table === 'sys_security_acl' &&
+                        doc.guid === (document.data as AclRole).data.sys_security_acl
+                )
+
+                return acl && acl.node ? { ...document, node: acl.node } : undefined
+            }
+
+            if (documentType !== 'sys_security_acl') {
+                return undefined
+            }
+
+            return linkDocument(
+                document,
+                generateCallExpressionExportForDocument(
+                    context,
+                    {
+                        sourceFile: getOrCreateEntitySourceFile(
+                            context,
+                            getSysUpdateName(document, 'sys_security_acl')
+                        ),
+                        moduleSpecifier: '@servicenow/sdk/core',
+                    },
+                    Acl,
+                    { $id: document.guid }
+                ).getExpressionIfKindOrThrow(ts.SyntaxKind.CallExpression)
+            )
+        },
+    },
+    transformers: {
+        record: {
+            CallExpression(document, context) {
+                const documentType = (document.data as any)?.table
+
+                const [args] = document.node.getArguments()
+                if (!ts.Node.isObjectLiteralExpression(args)) {
+                    return false
+                }
+
+                if (documentType === 'sys_security_acl_role') {
+                    if (!document.parent) {
+                        return true
+                    }
+                    const acl2Role = (document.data as AclRole).data
+                    if (document.action === 'DELETE') {
+                        const roleId = acl2Role.sys_user_role
+                        if (roleId) {
+                            removeObjectFromArrayById(document, 'roles', context)
+                        }
+                        return true
+                    }
+
+                    addObjectToArrayById(document, 'roles', acl2Role.sys_user_role, context)
+                    return true
+                }
+
+                if (document.action === 'DELETE') {
+                    removeNode(document.node)
+                    return true
+                }
+
+                if (documentType !== 'sys_security_acl' || !document.changedData) {
+                    return false
+                }
+
+                const modifiedAclData = (document.changedData as any).data as AclBase
+                const unmodifiedAclData = (document.data as any).data as AclData
+                const type = reverseLookup(AclTypes, unmodifiedAclData.type)
+
+                const aclData = {
+                    ...except(
+                        modifiedAclData,
+                        (key) =>
+                            key.startsWith('sys_') ||
+                            key === 'advanced' ||
+                            key === 'name' ||
+                            key === 'operation' ||
+                            key === 'script'
+                    ),
+                    ...getTableOrName(type, unmodifiedAclData.name),
+                    security_attribute:
+                        reverseLookup(AclAttributes, unmodifiedAclData.security_attribute) ||
+                        unmodifiedAclData.security_attribute,
+                    operation: reverseLookup(AclOperations, unmodifiedAclData.operation) || unmodifiedAclData.operation,
+                    type,
+                } as any
+
+                const { script } = modifiedAclData as { script?: string }
+                if (script !== undefined) {
+                    processScript(args, 'script', script, document.guid, 'sys_security_acl', context)
+                }
+
+                return transformFunctionArguments(document.node, Acl, aclData)
+            },
+        },
+    },
+})
+
+// security_attribute.is_localizsed ? 'Local' : 'Existing'
+function performDiagnosticChecksOnSecurityAttribute<T>(
+    callExpression: ts.CallExpression,
+    aclData: AclBase,
+    roles: Array<T>,
+    mode: 'serialize' | 'transform'
+) {
+    const diagnostics: FluentDiagnostic[] = []
+
+    if (roles.length < 1) {
+        const attributeRecord = aclData.security_attribute as DBRecord<'sys_security_attribute'>
+        if (!aclData.security_attribute && !aclData.script && !aclData.condition) {
+            diagnostics.push(
+                new FluentDiagnostic(
+                    callExpression,
+                    'ACLs must have at least one of the following: roles, security_attribute, condition, or script',
+                    { level: mode === 'transform' ? Diagnostic.Level.Warn : Diagnostic.Level.Error }
+                )
+            )
+        } else if (attributeRecord && attributeRecord.data) {
+            if (
+                aclData.local_or_existing === 'Existing' &&
+                (attributeRecord.data.type !== 'compound' || attributeRecord.data.is_localized)
+            ) {
+                diagnostics.push(
+                    new FluentDiagnostic(
+                        findObjectPropertyValue(callExpression, 'security_attribute'),
+                        `Invalid ACL with 'Existing' sys_security_attribute: Must have a security_attribute with a type of 'compound' and is_localized set to false.`
+                    )
+                )
+            } else if (
+                (!aclData.local_or_existing || aclData.local_or_existing === 'Local') &&
+                !attributeRecord.data.is_localized
+            ) {
+                diagnostics.push(
+                    new FluentDiagnostic(
+                        findObjectPropertyValue(callExpression, 'security_attribute'),
+                        `Invalid ACL with 'Local' security_attribute: security_attribute must have is_localized set to true`
+                    )
+                )
+            }
+        }
+    }
+    return diagnostics
+}
+
+function getTableOrName(type: keyof typeof AclTypes, name: string) {
+    if (AclNamedTypes[type]) {
+        return { name }
+    }
+    const tablePathParts = name.split('.')
+    const table = tablePathParts[0] || ''
+    const field = tablePathParts[1] || ''
+
+    return { table, field }
+}
+
+// TODO: The casting and type guards in this function are a bit of a mess and prone to errors.
+function getScript(acl: EntityData, context: Context) {
+    const scriptData = acl.getProperty('script')?.getValue() as ScriptInfo
+    let scriptVal: string
+    if (scriptData && scriptData.filePath) {
+        const { filePath, functionName, isDefault } = scriptData
+        scriptVal = buildScriptImport(
+            filePath,
+            functionName,
+            isDefault,
+            context,
+            (funcName) => `answer = ${funcName}(current)\n`
+        )
+    } else {
+        scriptVal = scriptData as unknown as string
+    }
+    return scriptVal
+}
+
+function reverseLookup<T extends object>(obj: T, sysId): keyof T {
+    return (Object.entries(obj)
+        .filter(([_, id]) => id === sysId)
+        .map(([key]) => key)[0] || '') as keyof T
+}

package/src/aclAndRole/RolePlugin.ts

@@ -0,0 +1,225 @@
+import { Role, RoleConfig, roleSchema } from '@servicenow/sdk-core/runtime/app'
+import {
+    Context,
+    Plugin,
+    linkDocument,
+    extractCallExpression,
+    FluentDiagnostic,
+    findObjectPropertyValue,
+    EntityData,
+    ObjectData,
+    Data,
+} from '@servicenow/sdk-build-core'
+import { Record } from '@servicenow/sdk-core/runtime/db'
+import {
+    generateCallExpressionExportForDocument,
+    getOrCreateEntitySourceFile,
+    transformFunctionArguments,
+    getSysUpdateName,
+    removeNode,
+} from '@servicenow/sdk-build-core'
+import { addObjectToArrayById, removeObjectFromArrayById } from './Util'
+import { SyntaxKind, Node } from 'ts-morph'
+import { except } from '../scripts/scriptUtils'
+import { RecordPlugin } from '../db/RecordPlugin'
+import { Diagnostic } from '@servicenow/sdk-project'
+
+function mapRoleToRole(context, roleId, containedRoleId) {
+    const m2mId = context.keys.registerCompositeId('sys_user_role_contains', {
+        role: roleId,
+        contains: containedRoleId,
+    })
+    return Record({
+        table: 'sys_user_role_contains',
+        $id: m2mId,
+        data: {
+            contains: containedRoleId,
+            role: roleId,
+        },
+    })
+}
+
+type RoleDoc = {
+    table: string
+    data: {
+        sys_id: string
+    }
+}
+
+type RoleContainsDoc = {
+    table: string
+    data: {
+        role: string
+        contains: string
+    }
+}
+
+export default Plugin({
+    name: 'Role',
+    ownedTables: {
+        sys_user_role: { diagnosticLevel: Diagnostic.Level.Error },
+    },
+    extractors: {
+        entity: {
+            CallExpression: (node, context) => {
+                const result = extractCallExpression(
+                    Role as (role: RoleConfig) => RoleConfig,
+                    'role',
+                    node,
+                    context,
+                    ({ $id }) => context.registerExplicitId('sys_user_role', $id as string)
+                )
+
+                if (!result.handled || !(0 in result.data)) {
+                    return result
+                }
+
+                const role = result.data[0]
+                const diagnostics = result.diagnostics
+                const scope = context.app?.config?.scope
+                const name = role.getProperty('name').getValue()
+                if (!name.startsWith(`${scope}.`)) {
+                    const nameValue = findObjectPropertyValue(node, 'name')
+                    diagnostics.push(new FluentDiagnostic(nameValue, `Role name must begin with '${scope}.'`))
+                }
+
+                return {
+                    handled: true,
+                    diagnostics,
+                    data: [role],
+                }
+            },
+        },
+    },
+    composers: {
+        entity: {
+            role(entity, context) {
+                const scope = context.app?.config?.scope
+                const guid = entity.getGuid()
+                const node = entity.getNode()
+
+                const role = roleSchema.safeParse(entity.getValue())
+                if (!role.success) {
+                    return undefined
+                }
+
+                const { $id: _, name, contains_roles, ...rest } = role.data
+
+                const roleToRoles: Record<'sys_user_role_contains'>[] = []
+                const containsRoles = entity.getProperty('contains_roles')
+                if (Data.isArray(containsRoles)) {
+                    for (const containedRole of containsRoles.getElements()) {
+                        const containedRoleSysId = Data.isEntity(containedRole)
+                            ? containedRole.getGuid()
+                            : containedRole.getValue() // Should be a string
+
+                        roleToRoles.push(mapRoleToRole(context, guid, containedRoleSysId))
+                    }
+                }
+
+                const suffix = name.replace(new RegExp(`^${scope}\\.`), '')
+
+                const roleRecord = Record({
+                    table: 'sys_user_role',
+                    $id: guid,
+                    data: {
+                        name,
+                        suffix,
+                        ...rest,
+                    },
+                })
+
+                return context.composeEntities(
+                    [roleRecord, ...roleToRoles].map(
+                        (r) => new EntityData('record', r.$id.toString(), ObjectData.fromObjectValue(r, node), node)
+                    ),
+                    [RecordPlugin]
+                )
+            },
+        },
+    },
+    arrangers: {
+        record(document) {
+            if ((document.data as any).table !== 'sys_user_role_contains') {
+                return { handled: false }
+            }
+
+            const roleId = (document.data as any).data.role
+            return {
+                handled: true,
+                result: roleId ? { kind: 'record', guid: roleId } : undefined,
+            }
+        },
+    },
+    generators: {
+        record(document, context: Context, linkedDocuments) {
+            const documentType = (document.data as any)?.table
+            if (documentType === 'sys_user_role_contains') {
+                const role = linkedDocuments.find(
+                    (doc) =>
+                        (doc.data as RoleDoc).table === 'sys_user_role' &&
+                        doc.guid === (document.data as RoleContainsDoc).data.role
+                )
+                return role && role.node ? { ...document, node: role.node } : undefined
+            }
+
+            if (documentType !== 'sys_user_role') {
+                return undefined
+            }
+
+            return linkDocument(
+                document,
+                generateCallExpressionExportForDocument(
+                    context,
+                    {
+                        sourceFile: getOrCreateEntitySourceFile(context, getSysUpdateName(document, 'sys_user_role')),
+                        moduleSpecifier: '@servicenow/sdk/core',
+                    },
+                    Role,
+                    { $id: document.guid }
+                ).getExpressionIfKindOrThrow(SyntaxKind.CallExpression)
+            )
+        },
+    },
+    transformers: {
+        record: {
+            CallExpression(document, context) {
+                const documentType = (document.data as any)?.table
+                if (documentType === 'sys_user_role_contains') {
+                    const [args] = document.node.getArguments()
+                    if (!Node.isObjectLiteralExpression(args) || !document.parent) {
+                        return false
+                    }
+                    if (document.action === 'DELETE') {
+                        removeObjectFromArrayById(document, 'contains_roles', context)
+                        return true
+                    }
+                    const m2mData = (document.data as RoleContainsDoc).data
+                    addObjectToArrayById(document, 'contains_roles', m2mData.contains, context)
+                    return true
+                }
+
+                if (documentType !== 'sys_user_role') {
+                    return false
+                }
+
+                if (document.action === 'DELETE') {
+                    removeNode(document.node)
+                    return true
+                }
+
+                const rawRoleData = (document.changedData as any).data
+                const roleData = except(
+                    rawRoleData,
+                    (key) =>
+                        key.startsWith('sys_') ||
+                        key === 'requires_subscription' ||
+                        key === 'suffix' ||
+                        key === 'includes_roles'
+                )
+
+                return transformFunctionArguments(document.node, Role, roleData)
+            },
+        },
+    },
+})