@servicenow/sdk-build-plugins 3.0.2 → 4.0.0

package/src/now-id-plugin.ts

@@ -0,0 +1,78 @@
+import { ts, Plugin, type Source, type Record, ElementAccessExpressionShape } from '@servicenow/sdk-build-core'
+
+export class NowIdShape extends ElementAccessExpressionShape {
+    constructor({ source, id }: { source: Source; id: string | number }) {
+        super({ source, callee: 'Now.ID', arg: id })
+    }
+
+    override getValue(): string | number {
+        return this.getArg().getValue()
+    }
+
+    static override from(record: Record): NowIdShape {
+        const id = record.getId().getNowIdKey() ?? record.getId().getValue()
+
+        return new NowIdShape({ source: record, id })
+    }
+
+    override getCode(): string {
+        return `Now.ID[${this.getArg().getCode()}]`
+    }
+}
+
+export const NowIdPlugin = Plugin.create({
+    name: 'NowIdPlugin',
+    shapes: [
+        {
+            shape: ElementAccessExpressionShape,
+            fileTypes: ['fluent'],
+            toSubclass(expression, { diagnostics }) {
+                if (expression.getCallee() !== 'Now.ID') {
+                    return { success: false }
+                }
+
+                const arg = expression.getArg()
+                if (!arg.isString() && !arg.isNumber()) {
+                    diagnostics.error(arg, 'Now.ID argument must be a string or number')
+                    return { success: false }
+                }
+
+                return {
+                    success: true,
+                    value: new NowIdShape({ source: expression, id: arg.getValue().toString() }),
+                }
+            },
+        },
+    ],
+    nodes: [
+        {
+            node: 'PropertyAccessExpression',
+            fileTypes: ['fluent'],
+            async toShape(node, { transform }) {
+                if (node.getName() !== '$id') {
+                    return { success: false }
+                }
+
+                const identifier = node.getExpressionIfKind(ts.SyntaxKind.Identifier)
+                if (!identifier) {
+                    return { success: false }
+                }
+
+                const result = await transform.toShape(identifier)
+                if (!result.success || !result.value.isIdentifier()) {
+                    return { success: false }
+                }
+
+                const record = result.value.resolve()
+                if (!record.isRecord()) {
+                    return { success: false }
+                }
+
+                return {
+                    success: true,
+                    value: record.getId(),
+                }
+            },
+        },
+    ],
+})

package/src/now-include-plugin.ts

@@ -0,0 +1,140 @@
+import {
+    type ts,
+    path as pathModule,
+    CallExpressionShape,
+    Plugin,
+    type ProjectFile,
+    type Source,
+    StringShape,
+    Shape,
+} from '@servicenow/sdk-build-core'
+import { CallExpressionPlugin } from './call-expression-plugin'
+
+export class NowIncludeShape extends CallExpressionShape {
+    private readonly includedFile: ProjectFile
+
+    constructor({ source, path, includedFile }: { source: Source; path: string; includedFile: ProjectFile }) {
+        super({ source, callee: 'Now.include', args: [path] })
+        this.includedFile = includedFile
+    }
+
+    getPath(): string {
+        return this.getArgument(0).asString().getValue()
+    }
+
+    getAbsolutePath(): string {
+        return this.getIncludedFile().getPath()
+    }
+
+    getRelativePathFrom(node: ts.Node): string {
+        return pathModule.relative(pathModule.dirname(node.getSourceFile().getFilePath()), this.getAbsolutePath())
+    }
+
+    getIncludedFile(): ProjectFile {
+        return this.includedFile
+    }
+
+    override getValue(): string {
+        return this.getIncludedFile().getContent()
+    }
+
+    override toString(): StringShape {
+        return Shape.from(this, this.getValue()).asString().withContentType('cdata')
+    }
+}
+
+export const NowIncludePlugin = Plugin.create({
+    name: 'NowIncludePlugin',
+    shapes: [
+        {
+            shape: CallExpressionShape,
+            fileTypes: ['fluent'],
+            toSubclass(callExpression, { diagnostics, project }) {
+                if (callExpression.getCallee() !== 'Now.include') {
+                    return { success: false }
+                }
+
+                const arg = callExpression.getArgument(0)
+                if (!arg.isString()) {
+                    diagnostics.error(arg, 'Now.include() must have a string argument')
+                    return { success: false }
+                }
+
+                const path = arg.getValue()
+
+                if (!/^\.\.?\/.*$/.test(path.trim()) && path.includes('/')) {
+                    diagnostics.error(arg, 'Now.include() argument must be a relative path')
+                    return { success: false }
+                }
+
+                const absolutePath = pathModule.resolve(pathModule.dirname(callExpression.getOriginalFilePath()), path)
+                if (!project.isInRootDir(absolutePath)) {
+                    diagnostics.error(arg, `Included file path is not within project: ${absolutePath}`)
+                    return { success: false }
+                }
+
+                let includedFile: ProjectFile
+                try {
+                    includedFile = project.addFile(absolutePath, {
+                        resolveDependencies: false,
+                        excludeFromCompiler: true,
+                    })
+                } catch (e) {
+                    diagnostics.error(arg, `Failed to include file. Reason: ${e instanceof Error ? e.message : e}`)
+                    return { success: false }
+                }
+
+                return {
+                    success: true,
+                    value: new NowIncludeShape({ source: callExpression, path, includedFile }),
+                }
+            },
+        },
+        {
+            shape: NowIncludeShape,
+            async commit(shape, target, { transform, commit }) {
+                const targetResult = await transform.toShape(target)
+                if (!targetResult.success) {
+                    return { success: false }
+                }
+
+                const { value: targetShape } = targetResult
+                if (targetShape.is(NowIncludeShape)) {
+                    if (targetShape.getAbsolutePath() === shape.getAbsolutePath()) {
+                        // It's already a Now.include() call pointing to the same file, so nothing to do
+                        return { success: true }
+                    }
+                } else {
+                    if (targetShape.equals(shape.getIncludedFile().getContent())) {
+                        // It's not a Now.include() call, but it's equivalent to the content, so leave it (probably an inline string literal)
+                        return { success: true }
+                    }
+                }
+
+                await commit(shape, target, CallExpressionPlugin)
+                return { success: true }
+            },
+        },
+        {
+            shape: StringShape,
+            async commit(shape, target, { transform }) {
+                const targetResult = await transform.toShape(target)
+                if (!targetResult.success) {
+                    return { success: false }
+                }
+
+                const targetShape = targetResult.value.ifIdentifier()?.resolve() ?? targetResult.value
+                if (!targetShape.is(NowIncludeShape)) {
+                    return { success: false }
+                }
+
+                const file = targetShape.getIncludedFile()
+                if (!shape.equals(file.getContent())) {
+                    file.setContent(shape.getValue())
+                }
+
+                return { success: true }
+            },
+        },
+    ],
+})

package/src/now-ref-plugin.ts

@@ -0,0 +1,48 @@
+import { Plugin, CallExpressionShape, StringShape, ObjectShape } from '@servicenow/sdk-build-core'
+import { CallExpressionPlugin } from './call-expression-plugin'
+
+export const NowRefPlugin = Plugin.create({
+    name: 'NowRefPlugin',
+    nodes: [
+        {
+            node: 'CallExpression',
+            async toShape(node, { transform, factory }) {
+                const result = await transform.toShape(node, CallExpressionPlugin)
+                if (
+                    !result.success ||
+                    !result.value.is(CallExpressionShape) ||
+                    result.value.getCallee() !== 'Now.ref'
+                ) {
+                    return { success: false }
+                }
+
+                const callExpression = result.value
+                const table = callExpression
+                    .getArgument(0)
+                    .asString('The first argument to Now.ref() must be a table name')
+                const guidOrKeys = callExpression
+                    .getArgument(1)
+                    .as(
+                        [StringShape, ObjectShape],
+                        'The second argument to Now.ref() must be a GUID or a coalesce keys object'
+                    )
+                const maybeKeys = callExpression.hasArgument(2)
+                    ? callExpression
+                          .getArgument(2)
+                          .asObject('The third argument to Now.ref() must be a coalesce keys object')
+                    : undefined
+
+                const [guid, keys] = maybeKeys
+                    ? [guidOrKeys.asString(), maybeKeys] // Now.ref(table, guid, keys)
+                    : guidOrKeys.isString()
+                      ? [guidOrKeys.asString(), undefined] // Now.ref(table, guid)
+                      : [undefined, guidOrKeys.asObject()] // Now.ref(table, keys)
+
+                return {
+                    success: true,
+                    value: factory.createReference({ source: node, table, guid, keys }),
+                }
+            },
+        },
+    ],
+})

package/src/now-unresolved-plugin.ts

@@ -0,0 +1,30 @@
+import { Plugin, UnresolvedShape } from '@servicenow/sdk-build-core'
+
+export const NowUnresolvedPlugin = Plugin.create({
+    name: 'NowUnresolvedPlugin',
+    shapes: [
+        {
+            shape: UnresolvedShape,
+            commit(shape, target) {
+                target.replaceWithText(shape.getCode())
+                return { success: true }
+            },
+        },
+    ],
+    nodes: [
+        {
+            node: 'PropertyAccessExpression',
+            fileTypes: ['fluent'],
+            toShape(node) {
+                if (node.getText() !== UnresolvedShape.CODE) {
+                    return { success: false }
+                }
+
+                return {
+                    success: true,
+                    value: new UnresolvedShape({ source: node }),
+                }
+            },
+        },
+    ],
+})

package/src/package-json-plugin.ts

@@ -0,0 +1,87 @@
+import {
+    type FileSystem,
+    type Logger,
+    path as pathModule,
+    Plugin,
+    type ObjectShape,
+    Shape,
+} from '@servicenow/sdk-build-core'
+import { RepackService } from './repack'
+import { JsonFileShape } from './json-plugin'
+
+export const PackageJsonPlugin = Plugin.create({
+    name: 'PackageJsonPlugin',
+    shapes: [
+        {
+            shape: JsonFileShape,
+            async toRecord(file, { config, packageJson, project, factory, fs, logger }) {
+                if (file.getBaseName() !== 'package.json') {
+                    return { success: false }
+                }
+
+                const relativePath = pathModule.relative(project.getRootDir(), file.getPath())
+                const sysModulePath = pathModule.join(config.scope, packageJson.name, packageJson.version, relativePath)
+
+                const sbomRecord = factory.createRecord({
+                    source: file,
+                    table: 'sys_module',
+                    explicitId: 'bom_json',
+                    properties: {
+                        path: pathModule.join(config.scope, packageJson.name, packageJson.version, 'bom.json'),
+                        external_source: false,
+                    },
+                })
+
+                return {
+                    success: true,
+                    value: factory
+                        .createRecord({
+                            source: file,
+                            table: 'sys_module',
+                            explicitId: relativePath.replaceAll(/[./\\]/g, '_'),
+                            properties: {
+                                // Module resolution at runtime requires this format
+                                path: sysModulePath,
+                                content: Shape.from(
+                                    file,
+                                    await fixDependencyVersion(file.getJson(), {
+                                        fs,
+                                        logger,
+                                        rootDir: project.getRootDir(),
+                                    })
+                                )
+                                    .asString()
+                                    .withContentType('cdata'),
+                                external_source: false,
+                                sys_name: sysModulePath,
+                            },
+                        })
+                        .with(sbomRecord),
+                }
+            },
+        },
+    ],
+})
+
+async function fixDependencyVersion(json: ObjectShape, context: { fs: FileSystem; logger: Logger; rootDir: string }) {
+    const deps = json.get('dependencies').ifObject()
+    if (!deps) {
+        return JSON.stringify(json.getValue(), null, 2)
+    }
+
+    const repack = await RepackService.create(context.logger, context.fs, context.rootDir)
+    const resolvedDeps = {}
+    for (const dep of deps.keys()) {
+        const { name, version } = await repack.getResolvedDepDetails(dep)
+        resolvedDeps[name] = version
+    }
+
+    return JSON.stringify(
+        {
+            ...json.getValue(),
+            dependencies: resolvedDeps,
+        },
+        null,
+        2
+    )
+}

package/src/property-plugin.ts

@@ -0,0 +1,118 @@
+import { isSNScope } from '@servicenow/sdk-build-core'
+import { CallExpressionShape, Plugin, type Shape } from '@servicenow/sdk-build-core'
+import { NowIdShape } from './now-id-plugin'
+
+const getRolesArray = (roles: string): Array<string> => {
+    return roles
+        .split(',')
+        .map((role) => role.trim())
+        .filter((role) => role)
+}
+
+export const PropertyPlugin = Plugin.create({
+    name: 'PropertyPlugin',
+    records: {
+        sys_properties: {
+            toShape(record, { config }) {
+                return {
+                    success: true,
+                    value: new CallExpressionShape({
+                        source: record,
+                        callee: 'Property',
+                        args: [
+                            record.transform(({ $ }) => ({
+                                $id: $.val(NowIdShape.from(record)),
+                                name: $.from('name', 'suffix').map(
+                                    (name, suffix) =>
+                                        name.ifString() ??
+                                        (config.scope === 'global'
+                                            ? suffix
+                                            : `${config.scope}.${suffix.asString().getValue()}`)
+                                ),
+                                value: $,
+                                description: $.def(''),
+                                type: $.def('string'),
+                                choices: $.map((c) => {
+                                    const value = c.toString().getValue()
+                                    return value
+                                        .split(/[,\n]/)
+                                        .map((v) => v.trim())
+                                        .filter((v) => v)
+                                }).def([]),
+                                isPrivate: $.from('is_private').toBoolean().def(false),
+                                ignoreCache: $.from('ignore_cache').toBoolean().def(false),
+                                roles: $.from('read_roles', 'write_roles')
+                                    .def({ read: [], write: [] })
+                                    .map((r, w) => ({
+                                        read: r.ifString()?.pipe((v) => getRolesArray(v.getValue())),
+                                        write: w.ifString()?.pipe((v) => getRolesArray(v.getValue())),
+                                    })),
+                            })),
+                        ],
+                    }),
+                }
+            },
+        },
+    },
+    shapes: [
+        {
+            shape: CallExpressionShape,
+            fileTypes: ['fluent'],
+            async toRecord(callExpression, { config, diagnostics, factory }) {
+                if (callExpression.getCallee() !== 'Property') {
+                    return { success: false }
+                }
+
+                const prop = callExpression.getArgument(0).asObject()
+                const scope = config.scope
+                const name = prop.get('name').asString()
+
+                if (!isSNScope(scope) && config.scope !== 'global' && !name.asString().startsWith(`${scope}.`)) {
+                    diagnostics.error(name.getOriginalNode(), `Property name must begin with '${scope}.'`)
+                }
+
+                return {
+                    success: true,
+                    value: factory.createRecord({
+                        source: callExpression,
+                        table: 'sys_properties',
+                        explicitId: prop.get('$id'),
+                        properties: prop.transform(({ $, merge }) => ({
+                            name: $,
+                            suffix: $.from('name').map((v) =>
+                                v.asString().replace(new RegExp(`^${config.scope}\\.`), '')
+                            ),
+                            description: $,
+                            type: $.def('string'),
+                            value: $.toString(), // TODO: Should be allowed to assign non-strings to string properties
+                            is_private: $.from('isPrivate').def(false),
+                            ignore_cache: $.from('ignoreCache').def(false),
+                            choices: $.map((v) => v.ifArray()?.getValue().join(',')),
+                            [merge]: $.from('roles')
+                                .def({ read_roles: '', write_roles: '' })
+                                .map((v) =>
+                                    v
+                                        .ifObject()
+                                        ?.transform(({ $ }) => ({
+                                            read_roles: $.from('read').map((r) => getRolesString(r)),
+                                            write_roles: $.from('write').map((r) => getRolesString(r)),
+                                        }))
+                                        .properties()
+                                ),
+                        })),
+                    }),
+                }
+            },
+        },
+    ],
+})
+
+function getRolesString(roles: Shape): string | undefined {
+    return roles
+        .ifArray()
+        ?.pipe((r) =>
+            Array.from(new Set(r.getElements().map((r) => r.ifRecord()?.get('name').getValue() ?? r.getValue()))).join(
+                ','
+            )
+        )
+}

package/src/record-plugin.ts

@@ -0,0 +1,171 @@
+import { CallExpressionShape, Plugin } from '@servicenow/sdk-build-core'
+import { unloadBuilder } from '@servicenow/sdk-build-core'
+import { NowIdShape } from './now-id-plugin'
+import {
+    Acl,
+    ApplicationMenu,
+    BusinessRule,
+    CrossScopePrivilege,
+    Property,
+    Role,
+    Test,
+    UserPreference,
+} from '@servicenow/sdk-core/runtime/app'
+import {
+    SPWidget,
+    SPAngularProvider,
+    SPWidgetDependency,
+    CssInclude,
+    JsInclude,
+} from '@servicenow/sdk-core/runtime/service-portal'
+import { ClientScript } from '@servicenow/sdk-core/runtime/clientscript'
+import { ScriptAction, ScriptInclude } from '@servicenow/sdk-core/runtime/sys'
+import { List } from '@servicenow/sdk-core/runtime/ui'
+import { Table } from '@servicenow/sdk-core/runtime/db'
+import { RestApi } from '@servicenow/sdk-core/runtime/rest'
+import { UiAction, UiPage } from '@servicenow/sdk-core/runtime/ui'
+
+export const RecordPlugin = Plugin.create({
+    name: 'RecordPlugin',
+    records: {
+        '*': {
+            toShape(record) {
+                return {
+                    success: true,
+                    value: new CallExpressionShape({
+                        source: record,
+                        callee: 'Record',
+                        args: [
+                            {
+                                $id: NowIdShape.from(record),
+                                table: record.getTable(),
+                                data: record.transform(
+                                    ({ $ }) =>
+                                        Object.fromEntries(
+                                            record
+                                                .keys()
+                                                .map((key) => [key, record.get(key).isString() ? $.def('') : $])
+                                        ) //to avoid writing empty string values to the code
+                                ),
+                            },
+                        ],
+                    }),
+                }
+            },
+            toFile(record, { config }) {
+                const recordBuilder = unloadBuilder(config)
+                const table = record.getTable()
+                const guid = record.getId().getValue()
+                const builder = recordBuilder.record(record)
+
+                record
+                    .entries()
+                    .sort(([a], [b]) => a.localeCompare(b)) // Sort keys to make outputs more deterministic
+                    .forEach(([prop, shape]) => builder.field(prop, shape))
+
+                return {
+                    success: true,
+                    value: {
+                        name: `${table}_${guid}.xml`,
+                        category: record.getInstallCategory(),
+                        content: recordBuilder.end(),
+                    },
+                }
+            },
+        },
+    },
+    shapes: [
+        {
+            shape: CallExpressionShape,
+            fileTypes: ['fluent'],
+            toRecord(callExpression, { factory, diagnostics }) {
+                if (callExpression.getCallee() !== 'Record') {
+                    return { success: false }
+                }
+
+                const record = callExpression.getArgument(0).asObject()
+                const table = record.get('table').asString().getValue()
+                const tableOwningPlugin = TableOwnership[table]
+                if (tableOwningPlugin) {
+                    diagnostics.hint(
+                        callExpression,
+                        `For a better experience, consider using the ${tableOwningPlugin} API`
+                    )
+                }
+                return {
+                    success: true,
+                    value: factory.createRecord({
+                        source: callExpression,
+                        table,
+                        explicitId: record.get('$id'),
+                        properties: record.get('data').asObject(),
+                    }),
+                }
+            },
+        },
+    ],
+    files: [
+        {
+            matcher: /\.xml$/,
+            toRecord(file, { parser, logger }) {
+                try {
+                    const [first, ...rest] = parser.parsePayload(file)
+
+                    if (!first) {
+                        return { success: false }
+                    }
+
+                    return {
+                        success: true,
+                        value: first.with(...rest),
+                    }
+                } catch (e) {
+                    logger.debug(e)
+                    return { success: false }
+                }
+            },
+        },
+    ],
+})
+
+export const TableOwnership = {
+    sys_security_acl: Acl.name,
+    sys_security_acl_role: Acl.name,
+    sys_app_application: ApplicationMenu.name,
+    sys_script: BusinessRule.name,
+    sys_script_client: ClientScript.name,
+    sys_scope_privilege: CrossScopePrivilege.name,
+    sys_ui_list_element: List.name,
+    sys_ui_list: List.name,
+    sys_properties: Property.name,
+    sys_user_role: Role.name,
+    sys_user_role_contains: Role.name,
+    sys_script_include: ScriptInclude.name,
+    sp_widget: SPWidget.name,
+    m2m_sp_widget_dependency: SPWidget.name,
+    m2m_sp_ng_pro_sp_widget: SPWidget.name,
+    sp_ng_template: SPWidget.name,
+    sp_dependency: SPWidgetDependency.name,
+    m2m_sp_dependency_css_include: SPWidgetDependency.name,
+    m2m_sp_dependency_js_include: SPWidgetDependency.name,
+    sp_css_include: CssInclude.name,
+    sp_js_include: JsInclude.name,
+    sp_angular_provider: SPAngularProvider.name,
+    m2m_sp_ng_pro_sp_ng_pro: SPAngularProvider.name,
+    sys_atf_test: Test.name,
+    sys_ws_header_map: RestApi.name,
+    sys_ws_query_parameter_map: RestApi.name,
+    sys_ws_definition: RestApi.name,
+    sys_ws_operation: RestApi.name,
+    sys_ws_version: RestApi.name,
+    sys_ws_header: RestApi.name,
+    sys_ws_query_parameter: RestApi.name,
+    sys_user_preference: UserPreference.name,
+    sys_ui_page: UiPage.name,
+    sys_ui_action: UiAction.name,
+    sys_ui_action_role: UiAction.name,
+    sys_ui_action_view: UiAction.name,
+    sysevent_script_action: ScriptAction.name,
+    sys_db_object: Table.name,
+    sys_dictionary: Table.name,
+}