@servicenow/sdk-build-plugins 4.0.2 → 4.1.0

package/src/claims-plugin.ts

@@ -0,0 +1,116 @@
+import { Plugin, type Project, type NowConfig, type Record } from '@servicenow/sdk-build-core'
+import { JsonFileShape } from './json-plugin'
+export const CLAIMS_FILE = '.claims.json'
+
+function getClaimsPath(project: Project, config: NowConfig): string {
+    return project.resolvePath(config.generatedDir, CLAIMS_FILE)
+}
+
+export const ClaimsPlugin = Plugin.create({
+    name: 'ClaimsPlugin',
+    files: [
+        {
+            entryPoint: true,
+            matcher: (path, { project, config }) => path === getClaimsPath(project, config),
+        },
+    ],
+    records: {
+        sys_claim: {
+            coalesce: ['claim_owner_scope', 'previous_claim_scope', 'metadata_update_name'],
+            toFile() {
+                // Claims don't get their own file, they're appended to the corresponding record's payload
+                return { success: true, value: [] }
+            },
+            toShape(root, { descendants, database, project, config }) {
+                descendants.insert(...database.query('sys_claim')) // Adding them as descendants will mark them as handled so they don't get reprocessed
+                const unsorted: globalThis.Record<string, string[]> = {}
+                for (const claim of descendants) {
+                    const updateName = claim.get('metadata_update_name').asString().getValue().trim()
+                    const timestamp = claim.get('claim_timestamp').asString().getValue().trim()
+                    const ownerScope = claim.get('claim_owner_scope').asString().getValue().trim()
+                    const previousScope = claim.get('previous_claim_scope').asString().getValue().trim()
+                    const previousVersion = claim.get('previous_claim_app_version').ifString()?.getValue().trim() ?? ''
+
+                    const array = (unsorted[updateName] ??= [])
+                    array.push(`${timestamp};${ownerScope};${previousScope};${previousVersion}`)
+                }
+
+                const sorted = Object.fromEntries(
+                    Object.entries(unsorted).map(([updateName, claims]) => [updateName, claims.sort()])
+                )
+
+                return {
+                    success: true,
+                    value: new JsonFileShape({
+                        source: root,
+                        path: getClaimsPath(project, config),
+                        content: JSON.stringify(sorted),
+                        json: sorted,
+                    }),
+                }
+            },
+        },
+    },
+    shapes: [
+        {
+            shape: JsonFileShape,
+            async toRecord(file, { project, config, factory }) {
+                if (file.getPath() !== getClaimsPath(project, config)) {
+                    return { success: false }
+                }
+
+                const allClaims = file.getJson()
+                const records: Record[] = []
+                for (const [updateName, claims] of allClaims.entries()) {
+                    for (const claim of claims
+                        .asArray(
+                            `Claims entry for ${updateName} is malformed. Expected array, but received: ${claims.getDescription()}`
+                        )
+                        .getElements()) {
+                        const [timestamp, ownerScope, previousScope, previousVersion] = claim
+                            .asString(
+                                `Claim for ${updateName} is malformed. Expected string, but received: ${claim.getDescription()}`
+                            )
+                            .split(';')
+                            .map((part) => part.trim())
+
+                        if (!timestamp) {
+                            throw new Error(
+                                `Claim for ${updateName} is malformed. Expected timestamp at first position.`
+                            )
+                        }
+
+                        if (!ownerScope) {
+                            throw new Error(
+                                `Claim for ${updateName} is malformed. Expected owner scope at second position.`
+                            )
+                        }
+
+                        if (!previousScope) {
+                            throw new Error(
+                                `Claim for ${updateName} is malformed. Expected previous scope at third position.`
+                            )
+                        }
+
+                        records.push(
+                            await factory.createRecord({
+                                source: file,
+                                table: 'sys_claim',
+                                properties: {
+                                    metadata_update_name: updateName,
+                                    claim_timestamp: timestamp,
+                                    claim_owner_scope: ownerScope,
+                                    previous_claim_scope: previousScope,
+                                    previous_claim_app_version: previousVersion || undefined,
+                                },
+                            })
+                        )
+                    }
+                }
+
+                const [first, ...rest] = records
+                return first ? { success: true, value: first.with(...rest) } : { success: false }
+            },
+        },
+    ],
+})

package/src/client-script-plugin.ts

@@ -119,7 +119,7 @@ export const ClientScriptPlugin = Plugin.create({
 
                 return {
                     success: true,
-                    value: factory.createRecord({
+                    value: await factory.createRecord({
                         source: callExpression,
                         table: 'sys_script_client',
                         explicitId: clientScript.get('$id'),

package/src/column/column-to-record.ts

@@ -3,12 +3,13 @@ import {
     type CallExpressionShape,
     type Diagnostics,
     type Factory,
+    type Record,
     StringShape,
 } from '@servicenow/sdk-build-core'
 import { generateDeprecatedDiagnostics } from '../utils'
 import { generatePlural } from '../column-plugin'
 
-export function getDocumentationRecords(
+export async function getDocumentationRecords(
     callExpression: CallExpressionShape,
     aliasedKeys: globalThis.Record<string, string[]>,
     factory: Factory,
@@ -20,7 +21,7 @@ export function getDocumentationRecords(
     const columnName = column.get('name')
     if (!documentation.if([ArrayShape, StringShape])) {
         return [
-            factory.createRecord({
+            await factory.createRecord({
                 source: callExpression,
                 table: 'sys_documentation',
                 properties: column.transform(({ $ }) => ({
@@ -39,30 +40,30 @@ export function getDocumentationRecords(
     }
 
     if (documentation.ifArray()) {
-        return (
-            documentation
-                .asArray()
-                .getElements()
-                .map((documentation) => {
-                    const docObject = documentation.asObject().withAliasedKeys(aliasedKeys)
-                    generateDeprecatedDiagnostics(docObject, diagnostics)
-                    return factory.createRecord({
-                        source: callExpression,
-                        table: 'sys_documentation',
-                        properties: docObject.transform(({ $ }) => ({
-                            name: $.val(column.get('table')),
-                            element: $.val(column.get('name')),
-                            language: $,
-                            hint: $,
-                            help: $,
-                            label: $,
-                            plural: $,
-                            url: $,
-                            url_target: $.from('urlTarget'),
-                        })),
-                    })
-                }) ?? []
-        )
+        const docRecords: Record[] = []
+        for (const doc of documentation.asArray().getElements()) {
+            const docObject = doc.asObject().withAliasedKeys(aliasedKeys)
+            generateDeprecatedDiagnostics(docObject, diagnostics)
+            docRecords.push(
+                await factory.createRecord({
+                    source: callExpression,
+                    table: 'sys_documentation',
+                    properties: docObject.transform(({ $ }) => ({
+                        name: $.val(column.get('table')),
+                        element: $.val(column.get('name')),
+                        language: $,
+                        hint: $,
+                        help: $,
+                        label: $,
+                        plural: $,
+                        url: $,
+                        url_target: $.from('urlTarget'),
+                    })),
+                })
+            )
+        }
+
+        return docRecords
     }
 
     if (!generateDefaultDoc) {
@@ -70,7 +71,7 @@ export function getDocumentationRecords(
     }
 
     return [
-        factory.createRecord({
+        await factory.createRecord({
             source: callExpression,
             table: 'sys_documentation',
             properties: column.transform(({ $ }) => ({
@@ -86,7 +87,7 @@ export function getDocumentationRecords(
     ]
 }
 
-export function getChoiceRecords(
+export async function getChoiceRecords(
     callExpression: CallExpressionShape,
     aliasedKeys: globalThis.Record<string, string[]>,
     factory: Factory,
@@ -98,34 +99,39 @@ export function getChoiceRecords(
         return []
     }
 
-    return Object.keys(choiceArg.getValue()).map((choiceValue) => {
+    const records: Record[] = []
+    for (const choiceValue of Object.keys(choiceArg.getValue())) {
         // TODO Should have proper type here
         const choice = choiceArg.get(choiceValue)
         if (choice.isObject()) {
             generateDeprecatedDiagnostics(choice.withAliasedKeys(aliasedKeys), diagnostics)
         }
-        return factory.createRecord({
-            source: callExpression,
-            table: 'sys_choice',
-            properties: choice.isString()
-                ? {
-                      name: column.get('table').asString().getValue(),
-                      element: column.get('name').asString().getValue(),
-                      label: choice,
-                      value: choiceValue,
-                  }
-                : choice.asObject().transform(({ $ }) => ({
-                      name: $.val(column.get('table')),
-                      element: $.val(column.get('name')),
-                      label: $,
-                      value: $.val(choiceValue),
-                      sequence: $,
-                      dependent_value: $.from('dependentValue'),
-                      hint: $,
-                      inactive: $.toBoolean().def(false),
-                      inactive_on_update: $.from('inactiveOnUpdate').toBoolean().def(false),
-                      language: $.def('en'),
-                  })),
-        })
-    })
+        records.push(
+            await factory.createRecord({
+                source: callExpression,
+                table: 'sys_choice',
+                properties: choice.isString()
+                    ? {
+                          name: column.get('table').asString().getValue(),
+                          element: column.get('name').asString().getValue(),
+                          label: choice,
+                          value: choiceValue,
+                      }
+                    : choice.asObject().transform(({ $ }) => ({
+                          name: $.val(column.get('table')),
+                          element: $.val(column.get('name')),
+                          label: $,
+                          value: $.val(choiceValue),
+                          sequence: $,
+                          dependent_value: $.from('dependentValue'),
+                          hint: $,
+                          inactive: $.toBoolean().def(false),
+                          inactive_on_update: $.from('inactiveOnUpdate').toBoolean().def(false),
+                          language: $.def('en'),
+                      })),
+            })
+        )
+    }
+
+    return records
 }

package/src/column-plugin.ts

@@ -10,6 +10,7 @@ import {
 } from './column/column-helper'
 import { ModuleFunctionShape } from './server-module-plugin'
 import { generateDeprecatedDiagnostics } from './utils'
+import { create } from 'xmlbuilder2'
 
 const PLURAL_EQUALS_LABEL = [
     's',
@@ -63,8 +64,80 @@ const documentationAliases = {
 export const ColumnPlugin = Plugin.create({
     name: 'ColumnPlugin',
     records: {
-        sys_choice: { coalesce: ['name', 'element', 'value'] },
-        sys_documentation: { coalesce: ['name', 'element', 'language'] },
+        sys_choice: {
+            coalesce: ['name', 'element', 'value'],
+            getUpdateName: (record) => ({
+                success: true,
+                value: `sys_choice_${record.get('name').getValue()}_${record.get('element').getValue()}`,
+            }),
+        },
+        sys_choice_set: {
+            coalesce: ['name', 'element'],
+            relationships: {
+                sys_choice: {
+                    via: {
+                        name: 'name',
+                        element: 'element',
+                    },
+                    descendant: true,
+                },
+            },
+            getUpdateName: (record) => ({
+                success: true,
+                // Seems odd, but according to UpdateName.java, sys_choice and sys_choice_set share the same update naming logic
+                value: `sys_choice_${record.get('name').getValue()}_${record.get('element').getValue()}`,
+            }),
+            async toFile(choiceSet, { config, descendants, transform }) {
+                if (config.tableOutputFormat === 'bootstrap') {
+                    // Defer to table plugin
+                    return { success: false }
+                }
+
+                const tableName = choiceSet.get('name').asString().getValue()
+                const elementName = choiceSet.get('element').asString().getValue()
+                const xml = create().ele('record_update')
+                const root = xml.ele('sys_choice_set', { table: tableName })
+                descendants.query('sys_choice').forEach((choice) => {
+                    const child = root.ele('sys_choice', { action: choice.getAction() })
+                    child.ele('sys_id').txt(choice.getId().getValue())
+                    child.ele('name').txt(tableName)
+                    child.ele('element').txt(elementName)
+
+                    for (const prop of [
+                        'label',
+                        'value',
+                        'sequence',
+                        'dependent_value',
+                        'hint',
+                        'inactive',
+                        'inactive_on_update',
+                        'language',
+                    ]) {
+                        choice
+                            .get(prop)
+                            .ifDefined()
+                            ?.toString()
+                            .pipe((p) => child.ele(prop).txt(p.getValue()))
+                    }
+                })
+
+                const child = root.ele('sys_choice_set', { action: choiceSet.getAction() })
+                child.ele('sys_id').txt(choiceSet.getId().getValue())
+                child.ele('sys_scope', { display_value: config.scope }).txt(config.scopeId)
+                child.ele('name').txt(tableName)
+                child.ele('element').txt(elementName)
+
+                return {
+                    success: true,
+                    value: {
+                        source: choiceSet,
+                        name: `${await transform.getUpdateName(choiceSet)}.xml`,
+                        category: choiceSet.getInstallCategory(),
+                        content: xml.end({ prettyPrint: true }),
+                    },
+                }
+            },
+        },
     },
     shapes: [
         {
@@ -82,20 +155,32 @@ export const ColumnPlugin = Plugin.create({
                     return { success: false }
                 }
 
-                const documentationRecords = getDocumentationRecords(
+                const documentationRecords = await getDocumentationRecords(
                     callExpression,
                     documentationAliases,
                     factory,
                     diagnostics,
                     true
                 )
-                const choiceRecords = getChoiceRecords(callExpression, choiceAliases, factory, diagnostics)
-
+                const choiceRecords = await getChoiceRecords(callExpression, choiceAliases, factory, diagnostics)
+                const choiceSetRecords: Record[] = []
+                if (choiceRecords.length > 0) {
+                    choiceSetRecords.push(
+                        await factory.createRecord({
+                            source: callExpression,
+                            table: 'sys_choice_set',
+                            properties: {
+                                name: column.get('table').asString().getValue(),
+                                element: column.get('name').asString().getValue(),
+                            },
+                        })
+                    )
+                }
                 const columnType = COLUMN_API_TO_TYPE[callee] ?? column.get('columnType').asString().getValue()
                 return {
                     success: true,
-                    value: factory
-                        .createRecord({
+                    value: (
+                        await factory.createRecord({
                             source: callExpression,
                             table: 'sys_dictionary',
                             properties: column.transform(({ $ }) => ({
@@ -241,7 +326,7 @@ export const ColumnPlugin = Plugin.create({
                                 xml_view: $.from('xmlView').toBoolean().def(false),
                             })),
                         })
-                        .with(...documentationRecords, ...choiceRecords),
+                    ).with(...documentationRecords, ...choiceRecords, ...choiceSetRecords),
                 }
             },
         },

package/src/cross-scope-privilege-plugin.ts

@@ -25,6 +25,12 @@ export const CrossScopePrivilegePlugin = Plugin.create({
     name: 'CrossScopePrivilegePlugin',
     records: {
         sys_scope_privilege: {
+            relationships: {
+                sys_scope: {
+                    via: 'target_scope',
+                    inverse: true,
+                },
+            },
             toShape(record) {
                 return {
                     success: true,
@@ -52,7 +58,7 @@ export const CrossScopePrivilegePlugin = Plugin.create({
         {
             shape: CallExpressionShape,
             fileTypes: ['fluent'],
-            toRecord(callExpression, { factory, config, diagnostics }) {
+            async toRecord(callExpression, { factory, config, diagnostics }) {
                 if (callExpression.getCallee() !== 'CrossScopePrivilege') {
                     return { success: false }
                 }
@@ -60,9 +66,18 @@ export const CrossScopePrivilegePlugin = Plugin.create({
                 const csp = callExpression.getArgument(0).asObject().withAliasedKeys(crossScopeAliases)
                 generateDeprecatedDiagnostics(csp, diagnostics)
 
+                const targetScope = csp.get('targetScope')
+                const targetScopeRef = targetScope.isString()
+                    ? await factory.createReference({
+                          source: targetScope,
+                          table: 'sys_scope',
+                          guid: targetScope,
+                      })
+                    : undefined
+
                 return {
                     success: true,
-                    value: factory.createRecord({
+                    value: await factory.createRecord({
                         source: callExpression,
                         table: 'sys_scope_privilege',
                         explicitId: csp.get('$id'),
@@ -70,7 +85,7 @@ export const CrossScopePrivilegePlugin = Plugin.create({
                             operation: $,
                             status: $,
                             target_name: $.from('targetName'),
-                            target_scope: $.from('targetScope'),
+                            target_scope: $.val(targetScopeRef),
                             target_type: $.from('targetType'),
                             source_scope: $.val(config.scopeId),
                         })),

package/src/html-import-plugin.ts

@@ -1,4 +1,4 @@
-import { path as pathModule, Plugin, Shape, StringShape, ts } from '@servicenow/sdk-build-core'
+import { path as pathModule, Plugin, type ProjectFile, Shape, StringShape, ts } from '@servicenow/sdk-build-core'
 import { applyPathMappings } from './utils'
 
 const HTML_IMPORT_PREFIX = `<!-- @fluent-import-html`
@@ -66,7 +66,17 @@ export const HtmlImportPlugin = Plugin.create({
                 }
 
                 const mappedPath = applyPathMappings(projectRelativePath, config.staticContentPaths)
-                const htmlFile = project.addFile(mappedPath, { resolveDependencies: false, excludeFromCompiler: true })
+
+                let htmlFile: ProjectFile
+                try {
+                    htmlFile = project.addFile(mappedPath, { resolveDependencies: false, excludeFromCompiler: true })
+                } catch (e) {
+                    diagnostics.error(
+                        importDeclaration,
+                        `failed to add HTML file: ${e instanceof Error ? e.message : String(e)}`
+                    )
+                    return { success: false }
+                }
 
                 return {
                     success: true,

package/src/index.ts

@@ -33,7 +33,8 @@ export * from './rest-api-plugin'
 export * from './html-import-plugin'
 export * from './static-content-plugin'
 export * from './script-action-plugin'
+export * from './claims-plugin'
 
 // non-plugins
 export * from './atf/step-configs'
-export { REPACK_OUTPUT_DIR } from './repack'
+export { REPACK_OUTPUT_DIR, checkModuleExists } from './repack'

package/src/json-plugin.ts

@@ -27,9 +27,14 @@ export class JsonStringifyShape extends CallExpressionShape {
 export class JsonFileShape extends SourceFileShape {
     private readonly json: ObjectShape
 
-    constructor(file: SourceFileShape, json: ObjectShape) {
-        super({ file: file.getSource() })
-        this.json = json
+    constructor({
+        source,
+        json,
+        path,
+        content,
+    }: { source: Source; json: unknown; path: string | Shape; content: string | Shape }) {
+        super({ source, path, content })
+        this.json = Shape.from(source, json).asObject('Expected JSON file content to be a JSON object')
     }
 
     getJson(): ObjectShape {
@@ -43,23 +48,38 @@ export const JsonPlugin = Plugin.create({
         {
             shape: SourceFileShape,
             fileTypes: ['json'],
-            toSubclass(file) {
-                const rawContent = file.getContent().trim()
-                const jsonContent = rawContent || '{}'
+            async toSubclass(file, { compiler, transform }) {
+                const actualFile = compiler.getSourceFile(file.getPath())
+                if (!actualFile) {
+                    return {
+                        success: true,
+                        value: new JsonFileShape({
+                            source: file,
+                            path: file.getPath(),
+                            content: file.getContent(),
+                            json: JSON5.parse(file.getContent()),
+                        }),
+                    }
+                }
 
-                let json: ObjectShape
-                try {
-                    json = Shape.from(
-                        file.getSource().getFirstDescendantByKind(ts.SyntaxKind.ObjectLiteralExpression) ?? file,
-                        JSON5.parse(jsonContent)
-                    ).asObject('Expected JSON file content to be a JSON object')
-                } catch (e) {
-                    throw new Error(`Failed to parse JSON content from file (${file.getPath()})`, { cause: e })
+                const root = actualFile.getFirstDescendantByKind(ts.SyntaxKind.ObjectLiteralExpression)
+                if (!root) {
+                    return { success: false }
+                }
+
+                const json = await transform.toShape(root)
+                if (!json.success) {
+                    return { success: false }
                 }
 
                 return {
                     success: true,
-                    value: new JsonFileShape(file, json),
+                    value: new JsonFileShape({
+                        source: file,
+                        json: json.value,
+                        path: file.getPath(),
+                        content: file.getContent(),
+                    }),
                 }
             },
         },