@servicenow/sdk-build-plugins 2.0.1 → 2.1.1

package/src/db/index.ts

@@ -1,3 +1,5 @@
 export * from './ColumnPlugins'
 export { default as TablePlugin, generateColumnExpression } from './TablePlugin'
 export { RecordPlugin } from './RecordPlugin'
+export { default as DocumentationPlugin } from './DocumentationPlugin'
+export * from './DBUtils'

package/src/index.ts

@@ -4,7 +4,7 @@ export * from './atf'
 export { default as DefaultPlugin } from './DefaultPlugin'
 export { default as ApplicationMenuPlugin } from './app/ApplicationMenuPlugin'
 export { default as PropertyPlugin } from './PropertyPlugin'
-export { default as RestApiPlugin } from './scriptedRESTAPI/RestApiPlugin'
+export { default as RestApiPlugin, RestApiPluginTechDebt } from './scriptedRESTAPI/RestApiPlugin'
 export { default as UserPreferencePlugin } from './UserPreferencePlugin'
 export { default as CrossScopePrivilegePlugin } from './CrossScopePrivilegePlugin'
 export { default as ClientScriptPlugin } from './scripts/ClientScriptPlugin'
@@ -12,5 +12,10 @@ export { default as BusinessRulePlugin } from './BusinessRulePlugin'
 export { default as ListPluginPlugin } from './ListPlugin'
 export { default as RolePlugin } from './aclAndRole/RolePlugin'
 export { default as AclPlugin } from './aclAndRole/AclPlugin'
-export { default as ScriptTemplatePlugin, UNIQUE_SCRIPT_FILES } from './ScriptTemplatePlugin'
+export { default as ScriptTemplatePlugin } from './ScriptTemplatePlugin'
 export { default as IdPlugin } from './IdPlugin'
+export { default as JsonPlugin } from './JsonPlugin'
+export { default as HtmlTemplatePlugin } from './HtmlTemplatePlugin'
+export { default as NowConfigPlugin } from './NowConfigPlugin'
+export { default as PackageJsonPlugin } from './PackageJsonPlugin'
+export { default as ServerModulePlugin } from './ServerModulePlugin'

package/src/scriptedRESTAPI/RESTDeserializationUtils.ts

@@ -21,7 +21,13 @@ import {
     RouteAttrWithOutIdSchema,
     RestRouteTransformer,
 } from './RestSchemaUtils'
-import { getArgs, potentialRecordCallRouteParams, isParamAssociated, createRecordCall } from './RestUtils'
+import {
+    getArgs,
+    potentialRecordCallRouteParams,
+    isParamAssociated,
+    createRecordCall,
+    removeNodeAndCleanUpExport,
+} from './RestUtils'
 import { Record } from '@servicenow/sdk-core/runtime/db'
 import { isEqual } from 'lodash'
 
@@ -154,14 +160,14 @@ export function transformRouteAttrs(document: Document, context: Context, argNam
             '[]'
         )
         const routeAttrIterator = new ArrayIterator(routeAttrsNode)
-        const arrayExpression = routeArrayIterator.getExpression()
+        const arrayExpression = routeAttrIterator.getExpression()
         while (routeAttrIterator.hasNext()) {
             const attrElement = routeAttrIterator.next()
             const attrId = getNodeId(attrElement.asKindOrThrow(SyntaxKind.ObjectLiteralExpression))
             const attrSysId = context.keys.explicit[attrId!]?.id
             if (attrSysId === document.guid) {
                 if (document.action === 'DELETE') {
-                    arrayExpression.removeElement(element)
+                    arrayExpression.removeElement(attrElement)
                 } else {
                     const attrEleObj = attrElement.asKindOrThrow(SyntaxKind.ObjectLiteralExpression)
                     cleanUpDefault(RouteAttrWithOutIdSchema, routeAttrData, attrEleObj)
@@ -238,7 +244,7 @@ export function transformRoutes(document: Document, context: Context, documentMa
                 const eleObj = element.asKindOrThrow(SyntaxKind.ObjectLiteralExpression)
                 transformEnforceAcl(eleObj, enforce_acl, context)
                 if (script !== undefined) {
-                    processScript(eleObj, 'script', script, document.guid, 'sys_ws_operation', context)
+                    processScript(eleObj, 'script', script)
                 }
                 cleanUpDefault(RouteSchema, parsedRouteData, eleObj)
                 mergeDataIntoObjectLiteral(eleObj, parsedRouteData)
@@ -254,7 +260,7 @@ export function transformRoutes(document: Document, context: Context, documentMa
             .asKindOrThrow(SyntaxKind.ObjectLiteralExpression)
         transformEnforceAcl(element, enforce_acl, context)
         if (script !== undefined) {
-            processScript(element, 'script', script, document.guid, 'sys_ws_operation', context)
+            processScript(element, 'script', script)
         }
         transformId(element, '$id', document.guid, 'sys_ws_operation', context)
         return true
@@ -307,7 +313,7 @@ export function transformRouteAttrsMap<T>(
             getCallExpressionName(attrDoc.node as ts.CallExpression) === Record.name
         ) {
             const attrId = getNodeId(getArgs(attrDoc))!
-            removeNode(attrDoc.node)
+            removeNodeAndCleanUpExport(attrDoc.node)
             delete context.keys.explicit[attrId]
         }
         const attrInfo = attrDoc.data!['data']
@@ -364,8 +370,9 @@ export function transformRouteAttrsMap<T>(
             if (!isHandled && document.action !== 'DELETE' && routeSysId === operationId) {
                 cleanUpDefault(RouteAttrWithOutIdSchema, parsedAttrData)
                 const element = attrExpression
-                    .addElement(stringify(parsedAttrData))
+                    .addElement(stringify({}))
                     .asKindOrThrow(SyntaxKind.ObjectLiteralExpression)
+                mergeDataIntoObjectLiteral(element, parsedAttrData)
                 const table = argName === 'headers' ? 'sys_ws_header' : 'sys_ws_query_parameter'
                 const foundAttrId = context.keys.findExplicitKeyById(attrId)
 
@@ -404,6 +411,7 @@ export function transformRouteAttrsMap<T>(
             potentialRecordCallRouteParams.has(deletedParamID)
         ) {
             createRecordCall(deletedParamID, context)
+            potentialRecordCallRouteParams.delete(deletedParamID)
         }
     }
     return true

package/src/scriptedRESTAPI/RESTSerializationUtils.ts

@@ -33,7 +33,7 @@ export function generateVersionRecords(
                 short_description: version.short_description,
                 version: version.version,
                 version_id: versionId,
-                web_service_definition: apiRecord,
+                web_service_definition: apiRecord.$id as any,
             },
         })
         versionsRecords.push(versionRecord)
@@ -76,7 +76,7 @@ export function generateRouteAttributesRecords<T extends TableName, M extends Ta
                 required: attribute.required,
                 short_description: attribute.short_description,
                 example_value: attribute.example_value,
-                web_service_definition: apiRecord,
+                web_service_definition: apiRecord.$id,
             } as Data<T>,
         })
         /**
@@ -97,8 +97,8 @@ export function generateRouteAttributesRecords<T extends TableName, M extends Ta
             table: mapping_collection,
             $id: attrMapId,
             data: {
-                web_service_operation: routeRecord,
-                [attrField]: attributeRecord,
+                web_service_operation: routeRecord.$id,
+                [attrField]: attributeRecord.$id,
             } as unknown as Data<M>,
         })
         attributeRecords.push(attrMapRecord)
@@ -150,6 +150,7 @@ export function generateRoutesAndRouteAttrRecords(
             ? `${baseOperationURI}/v${route.version}/${remOperationURI}`
             : `${baseOperationURI}/${remOperationURI}`
 
+        const version = getRestRouteVersion(route, versionMap)
         const routeRecord = Record({
             table: 'sys_ws_operation',
             $id: context.keys.registerExplicitId('sys_ws_operation', route.$id),
@@ -171,8 +172,8 @@ export function generateRoutesAndRouteAttrRecords(
                 requires_snc_internal_role: route.internalRole,
                 short_description: route.short_description,
                 request_example: route.request_example,
-                web_service_definition: apiRecord,
-                web_service_version: getRestRouteVersion(route, versionMap),
+                web_service_definition: apiRecord.$id as any,
+                web_service_version: typeof version === 'object' ? (version.$id as any) : version,
                 ...(route.policy && { sys_policy: route.policy }),
             },
         })

package/src/scriptedRESTAPI/RestApiPlugin.ts

@@ -12,9 +12,10 @@ import {
     getSysUpdateName,
     EntityData,
     ObjectData,
+    Data,
+    FluentDiagnostic,
 } from '@servicenow/sdk-build-core'
 import { RecordPlugin } from '../db/RecordPlugin'
-import { buildScriptImport, scriptInfo, type ScriptInfo } from '../scripts/scriptUtils'
 import {
     EnforceAcl,
     mergeACLIds,
@@ -47,6 +48,7 @@ import {
 } from './RestUtils'
 import * as z from 'zod'
 import { Diagnostic } from '@servicenow/sdk-project'
+import { ModuleFunctionData } from '../ServerModulePlugin'
 
 const methodsAllowedToOverrideRequests = ['PUT', 'PATCH', 'POST']
 const parseAcls = (enforce_acl: EnforceAcl, context: Context) =>
@@ -77,6 +79,30 @@ function restApiAsRecord<I extends number, V extends Version<I>>(config: RestApi
     })
 }
 
+/**
+ * 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: {
@@ -86,85 +112,70 @@ export default Plugin({
     },
     extractors: {
         entity: {
-            CallExpression: (node, context) => {
-                const result = extractCallExpression(RestApi, 'restApi', node, context, (restApi) =>
-                    context.registerExplicitId('sys_ws_definition', restApi.$id as string)
-                )
-
-                if (!result.handled || !(0 in result.data)) {
-                    return result
-                }
-
-                const restAPIEntity = result.data[0]
-                const entityData = RestApiSchema.parse(restAPIEntity.getValue())
-                const { routes, enforce_acl, consumes, produces } = entityData
-                for (const route of routes) {
-                    const { enforce_acl } = route
-                    const rawOperationScript = route.script as unknown as ScriptInfo | string
-                    route.name = route.name ? route.name : route.path
+            fluent: {
+                CallExpression: (node, context) => {
+                    const result = extractCallExpression(RestApi, 'restApi', node, context, (restApi) =>
+                        context.registerExplicitId('sys_ws_definition', restApi.$id as string)
+                    )
 
-                    if (typeof rawOperationScript !== 'string') {
-                        const { filePath, functionName, isDefault } = rawOperationScript
-                        route.script = buildScriptImport(
-                            filePath,
-                            functionName,
-                            isDefault,
-                            context,
-                            (funcName: string) => `${funcName}(request, response)\n`
-                        )
+                    if (!result.handled || !(0 in result.data)) {
+                        return result
                     }
 
-                    /** 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`)
-                    }
+                    const restApiEntity = result.data[0]
+                    const entityData = RestApiSchema.parse(restApiEntity.getValue())
+                    const { routes, enforce_acl, consumes, produces } = entityData
+                    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
+                        }
 
-                    route.consumes = route.consumes ? route.consumes : consumes
-                    route.produces = route.produces ? route.produces : produces
-                    route.enforce_acl = parseAcls(enforce_acl, context)
-                }
+                        const scriptData = routeData.getProperty('script')
+                        const scriptValue =
+                            scriptData instanceof ModuleFunctionData
+                                ? scriptData.getGlueCode((n) => `${n}(request, response)`)
+                                : scriptData.getValue()?.toString() ?? ''
 
-                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()
-                        ),
-                    ],
-                }
-            },
-        },
-        raw: {
-            FunctionDeclaration(node, context) {
-                const info = scriptInfo(node, context, RestApi.name)
-                if (!info) {
-                    return { handled: false }
-                }
+                        const route = routes[i]!
+                        route.script = scriptValue
 
-                return { handled: true, diagnostics: [], data: [info] }
-            },
+                        /** 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`)
+                        }
 
-            FunctionExpression(node, context) {
-                const info = scriptInfo(node, context, RestApi.name)
-                if (!info) {
-                    return { handled: false }
-                }
+                        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: [], data: [info] }
+                    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()
+                            ),
+                        ],
+                    }
+                },
             },
         },
     },
@@ -241,8 +252,7 @@ export default Plugin({
     arrangers: {
         record(document, context) {
             const table = document.data!['table']
-            /** skipping arrangers while serializing as we don't care about the order here. */
-            if (!restTables.includes(table) || context.mode === 'serialize') {
+            if (!restTables.includes(table) || RestApiPluginTechDebt.shouldSkipArranger(context)) {
                 return { handled: false }
             }
 
@@ -352,7 +362,7 @@ export default Plugin({
                             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
+                    const o_v_node = document.parent?.node ? document.parent!.node : restDef?.node
                     if (!o_v_node) {
                         return undefined
                     }

package/src/scriptedRESTAPI/RestUtils.ts

@@ -14,6 +14,7 @@ import {
 import { isEqual } from 'lodash'
 import { RestApi } from '@servicenow/sdk-core/runtime/rest'
 import { RecordPlugin } from '../db/RecordPlugin'
+import { SupportedNode } from '@servicenow/sdk-project'
 
 export const restTables = [
     'sys_ws_definition',
@@ -48,7 +49,7 @@ export function getRouteAttrMapResult(document: Document, restDocMap: any): Resu
      * if the given attribute map record references query parameter or routes record
      * not part of the current app we make it a record call.
      */
-    const isUnHandled = restDocMap['unHandled_records'].find((doc) => doc.id === document.guid)
+    const isUnHandled = restDocMap['unHandled_records'].find((doc) => doc.guid === document.guid)
     if (isUnHandled) {
         return { handled: false }
     }
@@ -150,6 +151,20 @@ export function getRouteAttrWithRestNodeResult(
         return { handled: true, result: { kind: 'record', guid: nodeRestId } }
     }
     if (restId === nodeRestId) {
+        /**
+         * Handles the case where the attribute associated with the rest node is not consumed by any m2m record.
+         * Probabal cause is it's being removed from the rest node and needs a separate record call.
+         */
+        if (!isConsumedByRest(restId, restDocMap, document)) {
+            deleteDocNode(document, context)
+            document['changedData'] = { data: document.data!['data'] }
+            const expKey = context.keys.findExplicitKeyById(document.guid)
+            if (expKey) {
+                delete context.keys.explicit[expKey]
+            }
+            potentialRecordCallRouteParams.delete(document.guid)
+            return { handled: false }
+        }
         return { handled: true, result: { kind: 'record', guid: restId } }
     }
     const attrName = document.data!['table'] === 'sys_ws_header' ? 'headers' : 'parameters'
@@ -179,7 +194,7 @@ export function getRouteAttrWithRestNodeResult(
 
 function isConsumed(document: Document, restDocMap: any) {
     const restId = document.data!['data']['web_service_definition']
-    const isUnHandled = restDocMap['unHandled_records'].find((doc) => doc.id === document.guid)
+    const isUnHandled = restDocMap['unHandled_records'].find((doc) => doc.guid === document.guid)
     if (isUnHandled) {
         return false
     }
@@ -213,7 +228,7 @@ export function getRouteAttrWithRecordNodeResult(
         return { handled: false }
     }
     const recordId = getNodeId(getArgs(document))!
-    removeNode(document.node!)
+    removeNodeAndCleanUpExport(document.node!)
     deleteDocNode(document, context)
     delete context.keys.explicit[recordId]
     document['changedData'] = { data: document.data!['data'] }
@@ -227,7 +242,9 @@ const getRestIdForRoute = (routeId: string, restDocMap: any) => {
         .filter((key) => key !== 'unHanlded_records' && key !== 'delete_records')
         .forEach((key) => {
             if (restDocMap[key].routes) {
-                const foundRoute = Object.values(restDocMap[key].routes).find((doc: any) => doc.id === routeId)
+                const foundRoute = Object.values(restDocMap[key].routes).find(
+                    (doc) => (doc as Document).guid === routeId
+                )
                 if (foundRoute) {
                     restId = key
                 }
@@ -277,7 +294,7 @@ export function getRouteAttrMapWithRestNodeResult(
     if (document.action === 'DELETE') {
         return { handled: true, result: { kind: 'record', guid: routeId } }
     }
-    const isUnHandled = restDocMap['unHandled_records'].find((doc) => doc.id === document.guid)
+    const isUnHandled = restDocMap['unHandled_records'].find((doc: Document) => doc.guid === document.guid)
     const attrName = document.data!['table'] === 'sys_ws_header_map' ? 'headers' : 'parameters'
     if (isUnHandled) {
         let unAssociatedId: string | undefined = undefined
@@ -328,7 +345,7 @@ export function getRouteAttrMapWithRecordNodeResult(
         return { handled: false }
     }
     const routeId = document.data!['data']['web_service_operation']
-    const isUnHandled = restDocMap['unHandled_records'].find((doc) => doc.id === document.guid)
+    const isUnHandled = restDocMap['unHandled_records'].find((doc: Document) => doc.guid === document.guid)
     if (isUnHandled) {
         return { handled: false }
     }
@@ -337,7 +354,7 @@ export function getRouteAttrMapWithRecordNodeResult(
     const paramField =
         document.data!['table'] === 'sys_ws_header_map' ? 'web_service_header' : 'web_service_query_parameter'
     potentialRecordCallRouteParams.delete(document.data!['data'][paramField])
-    removeNode(document.node!)
+    removeNodeAndCleanUpExport(document.node!)
     deleteDocNode(document, context)
     delete context.keys.explicit[recordId]
     return { handled: true, result: { kind: 'record', guid: routeId } }
@@ -357,8 +374,8 @@ export function getRouteAttrResult(document: Document, restDocMap: any): Result<
     return { handled: false }
 }
 
-const findRecInDocs = (docs: any[], id: string, table: string) => {
-    return docs?.find((doc) => doc.data!['table'] === table && doc.id == id)
+const findRecInDocs = (docs: Document[], id: string, table: string) => {
+    return docs?.find((doc) => doc.data!['table'] === table && doc.guid == id)
 }
 
 export function getRestDocumentMap(context: Context) {
@@ -372,7 +389,7 @@ export function getRestDocumentMap(context: Context) {
         const doc2Table = doc2.data!['table']
         return restTables.indexOf(doc1Table) - restTables.indexOf(doc2Table)
     })
-    const unHandledDocs: any[] = []
+    const unHandledDocs: Document[] = []
     /** filters and gets all delete records and insert_or_update records */
     const delRestDocs = allRestDocs.filter((doc) => doc.action === 'DELETE')
     const existingDocs = allRestDocs.filter((doc) => doc.action !== 'DELETE')
@@ -503,5 +520,21 @@ export function createRecordCall(paramSysId: string, context: Context) {
     document['changedData'] = { data: document.data!['data'] }
     delete document?.node
     const linkedDoc = RecordPlugin.generators.record(document as UnlinkedDocument<'record'> & Arranged, context)
-    RecordPlugin.transformers.record.CallExpression(linkedDoc)
+    RecordPlugin.transformers.record.CallExpression(linkedDoc, context)
+}
+
+export function removeNodeAndCleanUpExport(node: SupportedNode) {
+    const sourceFile = node.getSourceFile()
+    removeNode(node)
+    sourceFile
+        .getDefaultExportSymbol()
+        ?.getDeclarations()
+        .forEach((declaration) => {
+            if (
+                declaration?.isKind(ts.SyntaxKind.ExportAssignment) &&
+                declaration.getExpression()?.getText() === 'undefined'
+            ) {
+                declaration.remove()
+            }
+        })
 }