@servicenow/sdk-build-plugins 3.0.3 → 4.0.0

package/src/scriptedRESTAPI/RestApiPlugin.ts

@@ -1,469 +0,0 @@
-import { RestApi, RestApiConfig, RestApiSchema, Version } from '@servicenow/sdk-core/runtime/rest'
-import { Record, RecordWithLegacyId } from '@servicenow/sdk-core/runtime/db'
-import { additionalProperties } from '@servicenow/sdk-core/runtime/util'
-import {
-    linkDocument,
-    Context,
-    Plugin,
-    Document,
-    extractCallExpression,
-    getCallExpressionName,
-    generateCallExpressionExportForDocument,
-    getOrCreateEntitySourceFile,
-    getSysUpdateName,
-    EntityData,
-    ObjectData,
-    Data,
-    FluentDiagnostic,
-} from '@servicenow/sdk-build-core'
-import { RecordPlugin } from '../db/RecordPlugin'
-import {
-    EnforceAcl,
-    mergeACLIds,
-    generateVersionRecords,
-    generateRoutesAndRouteAttrRecords,
-} from './RESTSerializationUtils'
-import {
-    transformDefinition,
-    transformRestAttrs,
-    transformRouteAttrs,
-    transformRouteAttrsMap,
-    transformRoutes,
-} from './RESTDeserializationUtils'
-import { RestRouteHeaderMap, RestRouteQueryMap } from './RestSchemaUtils'
-import {
-    getRestDocumentMap,
-    getRouteAttrResult,
-    getRouteAttrMapResult,
-    getRouteAttrWithRecordNodeResult,
-    getRouteAttrWithRestNodeResult,
-    getRouteAttrMapWithRecordNodeResult,
-    getRouteAttrMapWithRestNodeResult,
-    handleAndReturnResult,
-    createRecordCall,
-    restTables,
-    unHandledIds,
-    completelyUnassociatedParamIds,
-    potentialRecordCallRouteParams,
-    extractNestedIds,
-} from './RestUtils'
-import * as z from 'zod'
-import { Diagnostic, ts, tsc } from '@servicenow/sdk-project'
-import { ModuleFunctionData } from '../ServerModulePlugin'
-
-const methodsAllowedToOverrideRequests = ['PUT', 'PATCH', 'POST']
-const parseAcls = (enforce_acl: EnforceAcl, context: Context) =>
-    enforce_acl.map((acl) => (typeof acl === 'string' ? acl : context.keys.registerExplicitId(acl.table, acl.$id)))
-
-function restApiAsRecord<I extends number, V extends Version<I>>(config: RestApiConfig<I, V>) {
-    const api = RestApiSchema.parse(config)
-    const rest = additionalProperties(config, RestApiSchema)
-
-    return Record({
-        table: 'sys_ws_definition',
-        $id: api.$id,
-        data: {
-            active: api.active,
-            name: api.name,
-            consumes: api.consumes,
-            consumes_customized: api.consumes === RestApiSchema.shape.consumes._def.defaultValue() ? false : true,
-            produces: api.produces,
-            produces_customized: api.produces === RestApiSchema.shape.produces._def.defaultValue() ? false : true,
-            default_version: '',
-            doc_link: api.doc_link,
-            is_versioned: false,
-            service_id: api.service_id,
-            short_description: api.short_description,
-            base_uri: '',
-            namespace: '',
-            enforce_acl: api.enforce_acl as any,
-            ...(api.policy && { sys_policy: api.policy }),
-            ...rest,
-        },
-    })
-}
-
-/**
- * TODO: Apparently the REST API plugin's arranger actually has pretty severe side effects such as
- * transforming code and dropping keys from the registry. I failed to unravel the web of code spread
- * across all the REST API "utils" files to understand how and why it is doing this. For some reason
- * this is only an issue when doing a regular build and not during bidirectional sync... For now I'm
- * preserving the existing behavior of skipping the arranger during regular builds and putting that
- * logic here in this namespace so we can easily find it and rip it out later.
- *
- * @deprecated
- */
-export namespace RestApiPluginTechDebt {
-    export function applyArrangerSkipFlag(context: Context) {
-        context['skipRestApiArranger'] = true
-    }
-
-    export function removeArrangerSkipFlag(context: Context) {
-        delete context['skipRestApiArranger']
-    }
-
-    export function shouldSkipArranger(context: Context) {
-        return context['skipRestApiArranger'] === true
-    }
-}
-
-export default Plugin({
-    name: 'RestApi',
-    ownedTables: {
-        sys_ws_definition: { diagnosticLevel: Diagnostic.Level.Warn },
-        sys_ws_version: { diagnosticLevel: Diagnostic.Level.Warn },
-        sys_ws_operation: { diagnosticLevel: Diagnostic.Level.Warn },
-    },
-    extractors: {
-        entity: {
-            fluent: {
-                CallExpression: (node, context) => {
-                    const result = extractCallExpression(RestApi, 'restApi', node, context, (restApi) =>
-                        context.registerExplicitId('sys_ws_definition', restApi.$id as string)
-                    )
-
-                    if (!result.handled || !result.data) {
-                        return result
-                    }
-
-                    const restApiEntity = result.data
-                    const restExplicitIds = extractNestedIds(restApiEntity)
-                    const entityData = RestApiSchema.and(z.any()).parse(restApiEntity.getValue())
-                    const service_id = restApiEntity.getProperty('service_id')
-                    const { routes, enforce_acl, consumes, produces } = entityData
-                    const serviceIdRegex = new RegExp(`^[a-z0-9_]*[a-z0-9]$`)
-
-                    if (!service_id.getValue().match(serviceIdRegex)) {
-                        result.diagnostics.push(
-                            new FluentDiagnostic(
-                                service_id.getNode(),
-                                `Rest service_id must only contain lowercase letters, numbers, and underscores and end with a letter or number`
-                            )
-                        )
-                    }
-
-                    const routesData = restApiEntity.getProperty('routes', 'array')?.getElements() ?? []
-                    for (let i = 0; i < routesData.length; i++) {
-                        const routeData = routesData[i]!
-                        if (!Data.isObject(routeData)) {
-                            result.diagnostics.push(new FluentDiagnostic(routeData.getNode(), 'Invalid route value'))
-                            continue
-                        }
-
-                        const scriptData = routeData.getProperty('script')
-                        const scriptValue =
-                            scriptData instanceof ModuleFunctionData
-                                ? scriptData.getGlueCode((n) => `${n}(request, response)`)
-                                : scriptData.getValue()?.toString() ?? ''
-
-                        const route = routes[i]!
-                        route.script = scriptValue
-
-                        /** allow users to override consumes for allowed http methods*/
-                        if (
-                            route.consumes &&
-                            route.consumes !== consumes &&
-                            !methodsAllowedToOverrideRequests.includes(route.method)
-                        ) {
-                            throw Error(`Cannot override consumer type for ${route.method} method`)
-                        }
-
-                        route.name = route.name ? route.name : route.path
-                        route.consumes = route.consumes ? route.consumes : consumes
-                        route.produces = route.produces ? route.produces : produces
-                        route.enforce_acl = parseAcls(route.enforce_acl, context)
-                    }
-
-                    return {
-                        handled: true,
-                        diagnostics: result.diagnostics,
-                        data: new EntityData(
-                            restApiEntity.getKind(),
-                            restApiEntity.getGuid(),
-                            ObjectData.fromObjectValue(
-                                {
-                                    ...entityData,
-                                    enforce_acl: parseAcls(enforce_acl, context),
-                                },
-                                restApiEntity.getNode()
-                            ),
-                            restApiEntity.getNode(),
-                            restApiEntity.getInstallMethod(),
-                            restExplicitIds
-                        ),
-                    }
-                },
-            },
-        },
-    },
-    composers: {
-        entity: {
-            restApi(entity, context) {
-                const restEntity = entity.getValue()
-                const parsedEntity = RestApiSchema.safeParse(restEntity)
-                if (!parsedEntity.success) {
-                    return Promise.resolve(undefined)
-                }
-
-                const { routes, versions, enforce_acl } = parsedEntity.data
-                const defaultVersions = versions.filter((version) => version.is_default)
-                if (defaultVersions.length > 1) {
-                    Promise.reject(`Multiple versions cannot be set to default.`)
-                }
-
-                const {
-                    app: {
-                        config: { scope },
-                    },
-                } = context
-                const restRecord = restApiAsRecord(restEntity as any) as RecordWithLegacyId<'sys_ws_definition'>
-                const apiData = { ...restRecord.data }
-
-                apiData.base_uri = `/api/${scope}/${apiData.service_id}`
-                apiData.namespace = scope
-                apiData.default_version =
-                    defaultVersions.length > 0 ? `v${defaultVersions[0]!.version}` : 'No active default version'
-                apiData.enforce_acl = mergeACLIds(enforce_acl) as any
-                apiData.is_versioned = versions.length > 0 ? true : false
-
-                /** generates sys_ws_definition record */
-                const updatedRestRecord = Record({
-                    table: 'sys_ws_definition',
-                    $id: entity.getGuid(),
-                    data: apiData,
-                })
-
-                /** generates the sys_ws_version record */
-                const versionRecordsAndMap = generateVersionRecords(
-                    context,
-                    apiData.default_version,
-                    versions,
-                    updatedRestRecord
-                )
-
-                /** generates the sys_ws_operation, sys_ws_header, sys_ws_header_map, sys_ws_query_paramter, sys_ws_query_parameter_map records */
-                const routesAndRouteAttrRecords = generateRoutesAndRouteAttrRecords(
-                    context,
-                    restRecord.$id,
-                    routes,
-                    apiData,
-                    updatedRestRecord,
-                    versionRecordsAndMap.mapping
-                )
-
-                return context.composeEntities(
-                    [updatedRestRecord, ...versionRecordsAndMap.records, ...routesAndRouteAttrRecords].map(
-                        (r) =>
-                            new EntityData(
-                                'record',
-                                r.$id as string,
-                                ObjectData.fromObjectValue(r, entity.getNode()),
-                                entity.getNode(),
-                                entity.getInstallMethod()
-                            )
-                    ),
-                    [RecordPlugin]
-                )
-            },
-        },
-    },
-    arrangers: {
-        record(document, context) {
-            const table = document.data!['table']
-            if (!restTables.includes(table) || RestApiPluginTechDebt.shouldSkipArranger(context)) {
-                return { handled: false }
-            }
-
-            /** generates rest document map and validates the params and their mapping records */
-            const restDocMap = getRestDocumentMap(context)
-            switch (table) {
-                case 'sys_ws_operation':
-                case 'sys_ws_version':
-                    return {
-                        handled: true,
-                        result: {
-                            kind: 'record',
-                            guid: document.data!['data']['web_service_definition'],
-                        },
-                    }
-                case 'sys_ws_header':
-                case 'sys_ws_query_parameter':
-                    if (!document.node) {
-                        /** handles case where the incoming xml doesn't have any node associated with it. */
-                        return handleAndReturnResult(getRouteAttrResult(document, restDocMap), document)
-                    } else {
-                        const docNode = document.node as ts.CallExpression
-                        if (getCallExpressionName(docNode) === Record.name) {
-                            /** handles case where the incoming xml is currently associated with record call */
-                            return handleAndReturnResult(
-                                getRouteAttrWithRecordNodeResult(document, context, restDocMap),
-                                document
-                            )
-                        } else {
-                            /** handles case where the incoming xml is currently associated with rest call */
-                            return handleAndReturnResult(
-                                getRouteAttrWithRestNodeResult(document, context, restDocMap),
-                                document
-                            )
-                        }
-                    }
-                case 'sys_ws_header_map':
-                case 'sys_ws_query_parameter_map':
-                    if (!document.node) {
-                        /** handles case where the incoming xml doesn't have any node associated with it. */
-                        return handleAndReturnResult(getRouteAttrMapResult(document, restDocMap), document)
-                    } else {
-                        const docNode = document.node as ts.CallExpression
-                        if (getCallExpressionName(docNode) === Record.name) {
-                            /** handles case where the incoming xml is currently associated with record call */
-                            return handleAndReturnResult(
-                                getRouteAttrMapWithRecordNodeResult(document, context, restDocMap),
-                                document
-                            )
-                        } else {
-                            /** handles case where the incoming xml is currently associated with rest call */
-                            return handleAndReturnResult(
-                                getRouteAttrMapWithRestNodeResult(document, context, restDocMap),
-                                document
-                            )
-                        }
-                    }
-                default:
-                    return { handled: true, result: undefined }
-            }
-        },
-    },
-    generators: {
-        record(document, context, linkedDocuments) {
-            const table = document.data!['table']
-            /**
-             * Edge case: m2m record maps non-app rest causing you to unassociate the only associated
-             * param record to rest. May require creation of record call for unassociated param if not consumed
-             * by any
-             */
-            completelyUnassociatedParamIds.forEach((id) => {
-                if (potentialRecordCallRouteParams.has(id)) {
-                    createRecordCall(id, context)
-                    potentialRecordCallRouteParams.delete(id)
-                }
-            })
-            completelyUnassociatedParamIds.clear()
-            /** unHandledIds contains rest record ids for which we need to create record call */
-            if (!restTables.includes(table) || unHandledIds.includes(document.guid)) {
-                return undefined
-            }
-
-            switch (table) {
-                case 'sys_ws_definition':
-                    // eslint-disable-next-line no-case-declarations
-                    const linkedDoc = linkDocument(
-                        document,
-                        generateCallExpressionExportForDocument(
-                            context,
-                            {
-                                sourceFile: getOrCreateEntitySourceFile(
-                                    context,
-                                    getSysUpdateName(document, 'sys_ws_definition')
-                                ),
-                                moduleSpecifier: '@servicenow/sdk/core',
-                            },
-                            RestApi,
-                            {}
-                        ).getExpressionIfKindOrThrow(ts.SyntaxKind.CallExpression)
-                    )
-                    return linkedDoc
-                case 'sys_ws_operation':
-                case 'sys_ws_version':
-                case 'sys_ws_header':
-                case 'sys_ws_query_parameter':
-                    // eslint-disable-next-line no-case-declarations
-                    const restDef = linkedDocuments.find(
-                        (doc) =>
-                            (doc.data as any).table === 'sys_ws_definition' &&
-                            doc.guid === (document.data as any).data.web_service_definition
-                    )
-                    // eslint-disable-next-line no-case-declarations
-                    const o_v_node = document.parent?.node ? document.parent!.node : restDef?.node
-                    if (!o_v_node) {
-                        return undefined
-                    }
-                    return linkDocument(document, o_v_node as ts.CallExpression<tsc.CallExpression>)
-                case 'sys_ws_header_map':
-                case 'sys_ws_query_parameter_map':
-                    // eslint-disable-next-line no-case-declarations
-                    const operationDef = linkedDocuments.find(
-                        (doc) =>
-                            (doc.data as any).table === 'sys_ws_operation' &&
-                            doc.guid === (document.data as any).data.web_service_operation
-                    )
-                    // eslint-disable-next-line no-case-declarations
-                    const h_q_node = document.parent?.node ? document.parent?.node : operationDef?.node
-                    if (!h_q_node) {
-                        return undefined
-                    }
-                    return linkDocument(document, h_q_node as ts.CallExpression<tsc.CallExpression>)
-            }
-            return undefined
-        },
-    },
-    transformers: {
-        record: {
-            CallExpression(document, context) {
-                if (!shouldHandle(document)) {
-                    return false
-                }
-
-                const documentMap = context.getDocumentMap()
-                const table = document.data!['table']
-                switch (table) {
-                    case 'sys_ws_definition':
-                        return transformDefinition(document, context)
-                    case 'sys_ws_version':
-                        return transformRestAttrs(document, context)
-                    case 'sys_ws_operation':
-                        return transformRoutes(document, context, documentMap!)
-                    case 'sys_ws_header':
-                        return transformRouteAttrs(document, context, 'headers')
-                    case 'sys_ws_query_parameter':
-                        return transformRouteAttrs(document, context, 'parameters')
-                    case 'sys_ws_query_parameter_map':
-                        return transformRouteAttrsMap(
-                            document,
-                            context,
-                            documentMap!,
-                            RestRouteQueryMap,
-                            'parameters',
-                            (data: z.infer<typeof RestRouteQueryMap>) => {
-                                return {
-                                    operationId: data.web_service_operation,
-                                    attrId: data.web_service_query_parameter,
-                                }
-                            }
-                        )
-                    case 'sys_ws_header_map':
-                        return transformRouteAttrsMap(
-                            document,
-                            context,
-                            documentMap!,
-                            RestRouteHeaderMap,
-                            'headers',
-                            (data: z.infer<typeof RestRouteHeaderMap>) => {
-                                return { operationId: data.web_service_operation, attrId: data.web_service_header }
-                            }
-                        )
-                }
-                return false
-            },
-        },
-    },
-})
-
-function shouldHandle(document: Document): boolean {
-    const docNode = document.node as ts.CallExpression
-    return !docNode.wasForgotten() &&
-        getCallExpressionName(docNode) === RestApi.name &&
-        document.data!['table'] &&
-        docNode.getArguments()[0]
-        ? true
-        : false
-}

package/src/scriptedRESTAPI/RestSchemaUtils.ts

@@ -1,72 +0,0 @@
-import {
-    BaseRestApiSchema,
-    BaseRouteSchema,
-    RouteAttributeSchema,
-    VersionSchema,
-} from '@servicenow/sdk-core/runtime/rest'
-import { z } from 'zod'
-
-export const RestRouteHeaderMap = z.object({
-    web_service_operation: z.string(),
-    web_service_header: z.string(),
-})
-
-export const RestRouteQueryMap = z.object({
-    web_service_operation: z.string(),
-    web_service_query_parameter: z.string(),
-})
-
-export const RouteAttrWithOutIdSchema = RouteAttributeSchema.omit({ $id: true })
-
-export const VersionWithOutIdSchema = VersionSchema.omit({ $id: true })
-
-const RestDefinitionSchema = BaseRestApiSchema.omit({ $id: true }).extend({
-    enforce_acl: z.string().default(''),
-    sys_policy: z.enum(['', 'read', 'protected']).default(''),
-})
-
-export const RestDefinitionTransformer = RestDefinitionSchema.partial().transform((data) => {
-    const { sys_policy, enforce_acl, ...rest } = data
-    return {
-        ...rest,
-        ...(enforce_acl !== undefined && { enforce_acl: enforce_acl ? enforce_acl.split(',') : [] }),
-        ...(sys_policy && { policy: sys_policy }),
-    }
-})
-
-const RestRouteSchema = BaseRouteSchema.omit({ $id: true }).extend({
-    operation_script: z.string().default(''),
-    http_method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']).default('GET'),
-    relative_path: z.string().default('/'),
-    requires_acl_authorization: z.boolean().default(true),
-    requires_authentication: z.boolean().default(true),
-    requires_snc_internal_role: z.boolean().default(true),
-    sys_policy: z.enum(['', 'read', 'protected']).default(''),
-    enforce_acl: z.string().default(''),
-    web_service_version: z.string().default(''),
-})
-
-export const RestRouteTransformer = RestRouteSchema.partial().transform((data) => {
-    const {
-        operation_script,
-        http_method,
-        relative_path,
-        requires_acl_authorization,
-        requires_authentication,
-        requires_snc_internal_role,
-        sys_policy,
-        enforce_acl,
-        ...rest
-    } = data
-    return {
-        ...rest,
-        ...(enforce_acl !== undefined && { enforce_acl: enforce_acl ? enforce_acl.split(',') : [] }),
-        ...(operation_script !== undefined && { script: operation_script }),
-        ...(http_method && { method: http_method }),
-        ...(relative_path && { path: relative_path }),
-        ...(requires_acl_authorization !== undefined && { authorization: requires_acl_authorization }),
-        ...(requires_authentication !== undefined && { authentication: requires_authentication }),
-        ...(requires_snc_internal_role !== undefined && { internalRole: requires_snc_internal_role }),
-        ...(sys_policy && { policy: sys_policy }),
-    }
-})