@servicenow/sdk-build-plugins 3.0.2 → 4.0.0

package/src/service-portal/angular-provider-plugin.ts

@@ -0,0 +1,83 @@
+import { CallExpressionShape, Plugin } from '@servicenow/sdk-build-core'
+import { NowIdShape } from '../now-id-plugin'
+
+export const SPAngularProviderPlugin = Plugin.create({
+    name: 'SPAngularProviderPlugin',
+    records: {
+        sp_angular_provider: {
+            relationships: {
+                m2m_sp_ng_pro_sp_ng_pro: { via: 'required_by', descendant: true },
+            },
+            toShape(record, { descendants }) {
+                const requiredProviders = descendants.query('m2m_sp_ng_pro_sp_ng_pro').map((p) => p.get('requires'))
+
+                return {
+                    success: true,
+                    value: new CallExpressionShape({
+                        source: record,
+                        callee: 'SPAngularProvider',
+                        args: [
+                            record.transform(({ $ }) => ({
+                                $id: $.val(NowIdShape.from(record)),
+                                name: $,
+                                type: $,
+                                script: $.def(''),
+                                requires: $.val(requiredProviders.length > 0 ? requiredProviders : undefined),
+                            })),
+                        ],
+                    }),
+                }
+            },
+        },
+        m2m_sp_ng_pro_sp_ng_pro: {
+            coalesce: ['required_by', 'requires'],
+        },
+    },
+    shapes: [
+        {
+            shape: CallExpressionShape,
+            fileTypes: ['fluent'],
+            async toRecord(callExpression, { factory, diagnostics }) {
+                if (callExpression.getCallee() !== 'SPAngularProvider') {
+                    return { success: false }
+                }
+
+                const providerObj = callExpression.getArgument(0).asObject()
+                const providerId = providerObj.get('$id')
+
+                const requires = providerObj.get('requires').ifArray()?.getElements() || []
+
+                requires
+                    .filter((provider) => provider.equals(providerId))
+                    .forEach((provider) => diagnostics.error(provider, 'recursive dependency detected'))
+
+                const providerRecord = factory.createRecord({
+                    source: callExpression,
+                    table: 'sp_angular_provider',
+                    explicitId: providerObj.get('$id'),
+                    properties: providerObj.transform(({ $ }) => ({
+                        name: $,
+                        type: $.def('directive'),
+                        script: $.def(''),
+                    })),
+                })
+
+                return {
+                    success: true,
+                    value: providerRecord.with(
+                        ...requires.map((child) => {
+                            return factory.createRecord({
+                                source: providerObj,
+                                table: 'm2m_sp_ng_pro_sp_ng_pro',
+                                properties: {
+                                    required_by: providerRecord.getId(),
+                                    requires: child.ifString()?.getValue() ?? child.ifRecord()?.getId(),
+                                },
+                            })
+                        })
+                    ),
+                }
+            },
+        },
+    ],
+})

package/src/service-portal/dependency-plugin.ts

@@ -0,0 +1,284 @@
+import {
+    CallExpressionShape,
+    type Diagnostics,
+    type Factory,
+    Plugin,
+    type Record,
+    type Shape,
+    type RecordId,
+} from '@servicenow/sdk-build-core'
+import { toReference } from '../utils'
+import { NowIdShape } from '../now-id-plugin'
+
+export const SPWidgetDependencyPlugin = Plugin.create({
+    name: 'SPWidgetDependencyPlugin',
+    records: {
+        sp_dependency: {
+            relationships: {
+                m2m_sp_dependency_css_include: { via: 'sp_dependency', descendant: true },
+                m2m_sp_dependency_js_include: { via: 'sp_dependency', descendant: true },
+            },
+            toShape(record, { descendants }) {
+                const cssIncludeRecords = descendants.query('m2m_sp_dependency_css_include')
+                const cssIncludes = cssIncludeRecords
+                    .map((m2m) => ({ order: m2m.get('order').toNumber(), include: m2m.get('sp_css_include') }))
+                    .sort((a, b) => a.order.getValue() - b.order.getValue())
+
+                const jsIncludeRecords = descendants.query('m2m_sp_dependency_js_include')
+                const jsIncludes = jsIncludeRecords
+                    .map((m2m) => ({ order: m2m.get('order').toNumber(), include: m2m.get('sp_js_include') }))
+                    .sort((a, b) => a.order.getValue() - b.order.getValue())
+
+                return {
+                    success: true,
+                    value: new CallExpressionShape({
+                        source: record,
+                        callee: 'SPWidgetDependency',
+                        args: [
+                            record.transform(({ $ }) => ({
+                                $id: $.val(NowIdShape.from(record)),
+                                name: $,
+                                angularModuleName: $.from('module'),
+                                cssIncludes: $.val(cssIncludes.length > 0 ? cssIncludes : undefined),
+                                jsIncludes: $.val(jsIncludes.length > 0 ? jsIncludes : undefined),
+                            })),
+                        ],
+                    }),
+                }
+            },
+        },
+        sp_js_include: {
+            relationships: {
+                m2m_sp_dependency_js_include: { via: 'sp_js_include', descendant: true },
+            },
+            toShape(record) {
+                return {
+                    success: true,
+                    value: new CallExpressionShape({
+                        source: record,
+                        callee: 'JsInclude',
+                        args: [
+                            record.transform(({ $ }) => ({
+                                $id: $.val(NowIdShape.from(record)),
+                                name: $.from('display_name'),
+                                url: $.def(''),
+                                sysUiScript: $.from('sys_ui_script').def(''),
+                            })),
+                        ],
+                    }),
+                }
+            },
+        },
+        sp_css_include: {
+            relationships: {
+                m2m_sp_dependency_css_include: { via: 'sp_css_include', descendant: true },
+            },
+            toShape(record) {
+                return {
+                    success: true,
+                    value: new CallExpressionShape({
+                        source: record,
+                        callee: 'CssInclude',
+                        args: [
+                            record.transform(({ $ }) => ({
+                                $id: $.val(NowIdShape.from(record)),
+                                name: $,
+                                url: record.get('url').getValue() ? $ : undefined,
+                                spCss: $.from('sp_css').def(''),
+                                lazyLoad: $.from('lazy_load').toBoolean().def(false),
+                                rtlCssUrl: $.from('rtl_css_file_url').def(''),
+                            })),
+                        ],
+                    }),
+                }
+            },
+        },
+        m2m_sp_dependency_css_include: {
+            coalesce: ['sp_css_include', 'sp_dependency'],
+        },
+        m2m_sp_dependency_js_include: {
+            coalesce: ['sp_js_include', 'sp_dependency'],
+        },
+    },
+    shapes: [
+        {
+            shape: CallExpressionShape,
+            fileTypes: ['fluent'],
+            async toRecord(callExpression, { diagnostics, factory }) {
+                if (callExpression.getCallee() !== 'JsInclude') {
+                    return { success: false }
+                }
+
+                const jsInclude = callExpression.getArgument(0).asObject()
+                const jsIncludeId = jsInclude.get('$id')
+                const urlDefined = jsInclude.get('url').isDefined()
+                const uiScriptDefined = jsInclude.get('sysUiScript').isDefined()
+                const source = urlDefined ? 'url' : 'local'
+                if ((!urlDefined && !uiScriptDefined) || (urlDefined && uiScriptDefined)) {
+                    diagnostics.error(
+                        jsInclude,
+                        `JsInclude must define either a url or sysUiScript property, but not both`
+                    )
+                }
+
+                return {
+                    success: true,
+                    value: factory.createRecord({
+                        source: callExpression,
+                        table: 'sp_js_include',
+                        explicitId: jsIncludeId,
+                        properties: jsInclude.transform(({ $ }) => ({
+                            display_name: $.from('name'),
+                            source: $.val(source),
+                            sys_ui_script: $.from('sysUiScript').map(toReference),
+                            url: $.from('url').def(''),
+                        })),
+                    }),
+                }
+            },
+        },
+        {
+            shape: CallExpressionShape,
+            fileTypes: ['fluent'],
+            async toRecord(callExpression, { diagnostics, factory }) {
+                if (callExpression.getCallee() !== 'CssInclude') {
+                    return { success: false }
+                }
+
+                const cssInclude = callExpression.getArgument(0).asObject()
+                const cssIncludeId = cssInclude.get('$id')
+                const urlDefined = cssInclude.get('url').isDefined()
+                const cssDefined = cssInclude.get('spCss').isDefined()
+                if ((!urlDefined && !cssDefined) || (urlDefined && cssDefined)) {
+                    diagnostics.error(cssInclude, `CssInclude must define either a url or spCss property, but not both`)
+                }
+                const source = urlDefined ? 'url' : 'local'
+
+                return {
+                    success: true,
+                    value: factory.createRecord({
+                        source: callExpression,
+                        table: 'sp_css_include',
+                        explicitId: cssIncludeId,
+                        properties: cssInclude.transform(({ $ }) => ({
+                            lazy_load: $.from('lazyLoad').def(false),
+                            name: $,
+                            rtl_css_file_url: $.from('rtlCssUrl').def(''),
+                            source: $.val(source),
+                            sp_css: $.from('spCss').map(toReference),
+                            url: $.from('url').def(''),
+                        })),
+                    }),
+                }
+            },
+        },
+        {
+            shape: CallExpressionShape,
+            fileTypes: ['fluent'],
+            async toRecord(callExpression, { diagnostics, factory }) {
+                if (callExpression.getCallee() !== 'SPWidgetDependency') {
+                    return { success: false }
+                }
+
+                const dependency = callExpression.getArgument(0).asObject()
+                const portals =
+                    (dependency
+                        .get('portalsForPageLoad')
+                        ?.ifArray()
+                        ?.map((p) => {
+                            if (p.isString()) {
+                                return p.getValue()
+                            }
+
+                            if (p.isRecord()) {
+                                return p.getId()
+                            }
+
+                            diagnostics.error(p, `Must be a sys_id or Record<'sp_portal'>`)
+                            return undefined
+                        })
+                        .filter((guid) => guid) as string[]) || []
+
+                const dependencyRecord = factory.createRecord({
+                    source: callExpression,
+                    table: 'sp_dependency',
+                    explicitId: dependency.get('$id'),
+                    properties: dependency.transform(({ $ }) => ({
+                        name: $,
+                        module: $.from('angularModuleName').def(''),
+                        page_load: $.from('includeOnPageLoad').def(false),
+                        sp_portals: $.val(portals.toString()),
+                    })),
+                })
+
+                const cssIncludes = getIncludeRecords(
+                    dependency.get('cssIncludes'),
+                    dependencyRecord.getId(),
+                    factory,
+                    'm2m_sp_dependency_css_include',
+                    'sp_css_include',
+                    diagnostics
+                )
+
+                const jsIncludes = getIncludeRecords(
+                    dependency.get('jsIncludes'),
+                    dependencyRecord.getId(),
+                    factory,
+                    'm2m_sp_dependency_js_include',
+                    'sp_js_include',
+                    diagnostics
+                )
+
+                return {
+                    success: true,
+                    value: dependencyRecord.with(...cssIncludes, ...jsIncludes),
+                }
+            },
+        },
+    ],
+})
+
+function getIncludeRecords(
+    shape: Shape,
+    dependencyId: Shape,
+    factory: Factory,
+    m2mTable: string,
+    includeTable: string,
+    diagnostics: Diagnostics
+) {
+    return (
+        (shape
+            ?.ifArray()
+            ?.map((include) => {
+                const includeProps = include.ifObject()?.get('include')
+
+                let includeId: string | RecordId
+                if (includeProps?.isString()) {
+                    includeId = includeProps.toString().getValue()
+                } else if (includeProps?.isRecord()) {
+                    includeId = includeProps.getId()
+                } else {
+                    const necessaryPlugin = includeTable === 'sp_js_include' ? 'JsInclude' : 'CssInclude'
+                    diagnostics.error(
+                        includeProps!,
+                        `include must contain a valid ${necessaryPlugin}, Record<'${includeTable}'> or sys_id'`
+                    )
+                    return undefined
+                }
+
+                const m2mProps = {
+                    [includeTable]: includeId,
+                    sp_dependency: dependencyId,
+                }
+                return factory.createRecord({
+                    source: shape,
+                    table: m2mTable,
+                    properties: {
+                        order: include.ifObject()?.get('order').asNumber().getValue() || 100,
+                        ...m2mProps,
+                    },
+                })
+            })
+            .filter((rec) => rec) as Record[]) || []
+    )
+}

package/src/service-portal/widget-plugin.ts

@@ -0,0 +1,263 @@
+import { CallExpressionShape, isGUID, Plugin, type Shape } from '@servicenow/sdk-build-core'
+import { noThrow, reverseObject } from '../utils'
+import { type SPTemplate, WidgetCategories } from '@servicenow/sdk-core/runtime/service-portal'
+import { NowIdShape } from '../now-id-plugin'
+import { NowIncludeShape } from '../now-include-plugin'
+
+export const SPWidgetPlugin = Plugin.create({
+    name: 'SPWidgetPlugin',
+    records: {
+        sp_widget: {
+            relationships: {
+                m2m_sp_widget_dependency: { via: 'sp_widget', descendant: true },
+                m2m_sp_ng_pro_sp_widget: { via: 'sp_widget', descendant: true },
+                sp_ng_template: { via: 'sp_widget', descendant: true },
+            },
+            toShape(record, { descendants }) {
+                const dependencies = descendants.query('m2m_sp_widget_dependency')
+                const angularProviders = descendants.query('m2m_sp_ng_pro_sp_widget')
+                const templates = descendants.query('sp_ng_template').map((template) => {
+                    return {
+                        $id: template.getId(),
+                        id: template.get('id'),
+                        htmlTemplate: template.get('template'),
+                    }
+                })
+
+                const category = reverseObject(WidgetCategories)[record.get('category').ifString()?.getValue() || '']
+
+                return {
+                    success: true,
+                    value: new CallExpressionShape({
+                        source: record,
+                        callee: 'SPWidget',
+                        args: [
+                            record.transform(({ $ }) => ({
+                                $id: $.val(NowIdShape.from(record)),
+                                name: $,
+                                category: $.val(category).def('custom'),
+                                clientScript: $.from('client_script').def(''),
+                                serverScript: $.from('script').def(''),
+                                controllerAs: $.from('controller_as').def('c'),
+                                htmlTemplate: $.from('template').def(''),
+                                customCss: $.from('css').def(''),
+                                dataTable: $.from('data_table').def('sp_instance'),
+                                demoData: $.from('demo_data')
+                                    .map((d) => {
+                                        const json = d.ifString()?.getValue()
+
+                                        const parsed = noThrow(() => json && JSON.parse(json))
+                                        return parsed instanceof Error ? json : parsed
+                                    })
+                                    .def(''),
+                                description: $.def(''),
+                                docs: $.def(''),
+                                fields: $.from('field_list')
+                                    .map((fields) => {
+                                        const fieldStr = fields.ifString()?.getValue()
+                                        return fieldStr && fieldStr.split(',')
+                                    })
+                                    .def(''),
+                                hasPreview: $.from('has_preview').toBoolean().def(false),
+                                id: $.def(''),
+                                internal: $.toBoolean().def(false),
+                                linkScript: $.from('link').def(''),
+                                roles: $.map((role) => {
+                                    const roleStr = role.ifString()?.getValue()
+                                    return roleStr && roleStr.split(',')
+                                }).def(''),
+                                servicenow: $.toBoolean().def(false),
+                                optionSchema: $.from('option_schema')
+                                    .map((v) => {
+                                        const json = v.ifString()?.getValue()
+                                        const parsed = noThrow(() => json && JSON.parse(json))
+                                        return parsed instanceof Error ? json : parsed
+                                    })
+                                    .def(''),
+                                public: $.toBoolean().def(false),
+                                dependencies: $.val(
+                                    dependencies.length > 0
+                                        ? dependencies.map((dep) => dep.get('sp_dependency'))
+                                        : undefined
+                                ),
+                                angularProviders: $.val(
+                                    angularProviders.length > 0
+                                        ? angularProviders.map((ap) => ap.get('sp_angular_provider'))
+                                        : undefined
+                                ),
+                                templates: $.val(templates.length > 0 ? templates : undefined),
+                            })),
+                        ],
+                    }),
+                }
+            },
+        },
+        m2m_sp_widget_dependency: {
+            coalesce: ['sp_widget', 'sp_dependency'],
+        },
+        m2m_sp_ng_pro_sp_widget: {
+            coalesce: ['sp_widget', 'sp_angular_provider'],
+        },
+    },
+    shapes: [
+        {
+            shape: CallExpressionShape,
+            fileTypes: ['fluent'],
+            async toRecord(callExpression, { diagnostics, factory, config }) {
+                if (callExpression.getCallee() !== 'SPWidget') {
+                    return { success: false }
+                }
+
+                const widget = callExpression.getArgument(0).asObject()
+                const dependencies =
+                    widget
+                        .get('dependencies')
+                        .ifArray()
+                        ?.map((dep) => (dep.isString() ? dep.getValue() : dep.ifRecord()?.getId())) || []
+                const angularProviders =
+                    widget
+                        .get('angularProviders')
+                        .ifArray()
+                        ?.map((ap) => (ap.isString() ? ap.getValue() : ap.ifRecord()?.getId())) || []
+
+                const templates =
+                    widget
+                        .get('templates')
+                        .ifArray()
+                        ?.map((shp) => shp.getValue() as SPTemplate) || []
+                const widgetId = widget.get('id').ifString()
+                if (widgetId && !/^[a-zA-Z0-9_-]+$/g.test(widgetId.getValue())) {
+                    diagnostics.error(
+                        widgetId.getOriginalNode(),
+                        `Invalid value: must contain only alphanumeric, -, or _ characters`
+                    )
+                }
+
+                const roles = widget
+                    .get('roles')
+                    .ifArray()
+                    ?.map((role) => {
+                        if (role.isString()) {
+                            return role
+                        }
+                        if (role.isRecord()) {
+                            return role.get('name')
+                        }
+
+                        return undefined
+                    })
+                    .filter((role) => role) as Shape[] | undefined
+
+                if (roles) {
+                    roles
+                        .filter((role) => isGUID(role.getValue() as string))
+                        .forEach((role) =>
+                            diagnostics.error(
+                                role!.getOriginalNode(),
+                                `expecting role names or role records created by the Role or Record plugins, not sys_ids`
+                            )
+                        )
+                }
+
+                const controller = widget.get('controllerAs').ifString()?.getValue() || 'c'
+                const servicenow =
+                    (widget.get('servicenow').ifBoolean()?.getValue() &&
+                        (config.scope.startsWith('sn_') || config.scope.startsWith('snc_'))) ||
+                    false
+
+                const widgetRecord = factory.createRecord({
+                    source: callExpression,
+                    table: 'sp_widget',
+                    explicitId: widget.get('$id'),
+                    properties: widget.transform(({ $ }) => ({
+                        name: $,
+                        category: $.map((v) => WidgetCategories[v.ifString()?.getValue() || '']).def('custom'),
+                        client_script: $.from('clientScript').def(getDefaultClientScript(controller)),
+                        script: $.from('serverScript').def(SP_WIDGET_DEFAULT_SERVER_SCRIPT),
+                        controller_as: $.from('controllerAs').def('c'),
+                        template: $.from('htmlTemplate').def(SP_WIDGET_DEFAULT_HTML_TEMPLATE),
+                        css: $.from('customCss').def(''),
+                        data_table: $.from('dataTable').def('sp_instance'),
+                        demo_data: $.from('demoData')
+                            .map((v) =>
+                                v.ifString() || v instanceof NowIncludeShape ? v : JSON.stringify(v.getValue())
+                            )
+                            .def(''),
+                        description: $.def(''),
+                        docs: $.map((v) => (v.isString() ? v : v.ifRecord()?.getId())),
+                        field_list: $.from('fields')
+                            .map((v) => v.getValue()?.toString())
+                            .def(''),
+                        has_preview: $.from('hasPreview').toBoolean().def(false),
+                        id: $.def(''),
+                        internal: $.def(false),
+                        servicenow: $.val(servicenow),
+                        link: $.from('linkScript').def(SP_WIDGET_DEFAULT_LINK_SCRIPT),
+                        roles: $.val(roles?.map((r) => r.getValue()).toString()).def(''),
+                        option_schema: $.from('optionSchema')
+                            .map((v) => {
+                                const json = v.getValue()
+                                return json && JSON.stringify(json)
+                            })
+                            .def(''),
+                        public: $.def(false),
+                    })),
+                })
+
+                return {
+                    success: true,
+                    value: widgetRecord.with(
+                        ...templates.map((template: SPTemplate) => {
+                            return factory.createRecord({
+                                source: widget,
+                                table: 'sp_ng_template',
+                                explicitId: template.$id as string,
+                                properties: {
+                                    id: template.id,
+                                    sp_widget: widgetRecord.getId(),
+                                    template: template.htmlTemplate,
+                                },
+                            })
+                        }),
+                        ...dependencies.map((dep) => {
+                            return factory.createRecord({
+                                source: widget,
+                                table: 'm2m_sp_widget_dependency',
+                                properties: {
+                                    sp_dependency: dep!,
+                                    sp_widget: widgetRecord.getId(),
+                                },
+                            })
+                        }),
+                        ...angularProviders.map((ap) => {
+                            return factory.createRecord({
+                                source: widget,
+                                table: 'm2m_sp_ng_pro_sp_widget',
+                                properties: {
+                                    sp_angular_provider: ap!,
+                                    sp_widget: widgetRecord.getId(),
+                                },
+                            })
+                        })
+                    ),
+                }
+            },
+        },
+    ],
+})
+
+export const getDefaultClientScript = (controller: string) => `api.controller = function () {
+    /* widget controller */
+    var ${controller} = this;
+};
+`
+
+export const SP_WIDGET_DEFAULT_LINK_SCRIPT = `function link(scope, element, attrs, controller) {
+}`
+
+export const SP_WIDGET_DEFAULT_SERVER_SCRIPT = `(function () {
+    /* populate the 'data' object */
+    /* e.g., data.table = $sp.getValue('table'); */
+})();`
+
+export const SP_WIDGET_DEFAULT_HTML_TEMPLATE = `<div><!-- your widget template --></div>`