@servicenow/sdk-build-plugins 4.6.0 → 4.7.0

package/src/ui-action-plugin.ts

@@ -6,13 +6,12 @@ import {
     type Shape,
     type StringShape,
 } from '@servicenow/sdk-build-core'
+import type { UiAction } from '@servicenow/sdk-core/runtime/ui'
 import { NowIdShape } from './now-id-plugin'
 import { ModuleFunctionShape } from './server-module-plugin'
-import { createSdkDocEntry } from './utils'
 
 export const UiActionPlugin = Plugin.create({
     name: 'UiActionPlugin',
-    docs: [createSdkDocEntry('UiAction', ['sys_ui_action'])],
     records: {
         sys_ui_action: {
             relationships: {
@@ -161,7 +160,7 @@ export const UiActionPlugin = Plugin.create({
                                 order: $.map((o) => (o.ifString()?.getValue() === '' ? 100 : o))
                                     .toNumber()
                                     .def(100),
-                                overrides: $.def(''),
+                                overrides: $.from('sys_overrides').def(''),
                                 showQuery: $.from('show_query').toBoolean().def(false),
                                 showUpdate: $.from('show_update').toBoolean(),
                                 showInsert: $.from('show_insert').toBoolean(),
@@ -195,6 +194,18 @@ export const UiActionPlugin = Plugin.create({
                 const arg = callExpression.getArgument(0).asObject()
                 const isClient = arg.get(['client', 'isClient'])
 
+                const form = arg.get('form')?.getValue() as UiAction<string>['form']
+                const isFormAction = form?.showButton || form?.showLink || form?.showContextMenu
+
+                const list = arg.get('list').getValue() as UiAction<string>['list']
+                const isListAction =
+                    list?.showButton ||
+                    list?.showBannerButton ||
+                    list?.showContextMenu ||
+                    list?.showListChoice ||
+                    list?.showLink ||
+                    list?.showSaveWithFormButton
+
                 const uiAction = await factory.createRecord({
                     source: callExpression,
                     table: 'sys_ui_action',
@@ -212,8 +223,8 @@ export const UiActionPlugin = Plugin.create({
                                 ? arg.get('messages').asArray().getValue().join('\n')
                                 : arg.get('messages')
                         ).def([]),
-                        list_style: $.val(arg.get(['list', 'style'])),
-                        form_style: $.val(arg.get(['form', 'style'])),
+                        list_style: $.val(list?.style),
+                        form_style: $.val(form?.style),
                         condition: $.def(''),
                         script: $.map(
                             (v) => v.if(ModuleFunctionShape)?.toString((n) => `${n}({{PARAMS}})`, ['current']) ?? v
@@ -222,24 +233,26 @@ export const UiActionPlugin = Plugin.create({
                             .toCdata(),
                         hint: $.def(''),
                         order: $.toNumber().def(100),
-                        overrides: $.def(''),
-                        form_button: $.val(arg.get(['form', 'showButton'])).def(false),
-                        list_button: $.val(arg.get(['list', 'showButton'])).def(false),
-                        form_link: $.val(arg.get(['form', 'showLink'])).def(false),
-                        list_link: $.val(arg.get(['list', 'showLink'])).def(false),
-                        form_context_menu: $.val(arg.get(['form', 'showContextMenu'])).def(false),
-                        list_context_menu: $.val(arg.get(['list', 'showContextMenu'])).def(false),
+                        sys_overrides: $.from('overrides').def(''),
+                        form_action: $.val(isFormAction).def(false),
+                        list_action: $.val(isListAction).def(false),
+                        form_button: $.val(form?.showButton).def(false),
+                        list_button: $.val(list?.showButton).def(false),
+                        form_link: $.val(form?.showLink).def(false),
+                        list_link: $.val(list?.showLink).def(false),
+                        form_context_menu: $.val(form?.showContextMenu).def(false),
+                        list_context_menu: $.val(list?.showContextMenu).def(false),
                         show_query: $.from('showQuery').toBoolean().def(false),
                         show_insert: $.from('showInsert').toBoolean().def(false).def(true),
                         show_multiple_update: $.from('showMultipleUpdate').toBoolean().def(false),
                         show_update: $.from('showUpdate').toBoolean().def(true),
-                        list_choice: $.val(arg.get(['list', 'showListChoice'])).def(false),
-                        list_banner_button: $.val(arg.get(['list', 'showBannerButton'])).def(false),
-                        list_save_with_form_button: $.val(arg.get(['list', 'showSaveWithFormButton'])).def(false),
+                        list_choice: $.val(list?.showListChoice).def(false),
+                        list_banner_button: $.val(list?.showBannerButton).def(false),
+                        list_save_with_form_button: $.val(list?.showSaveWithFormButton).def(false),
                         isolate_script: $.from('isolateScript').toBoolean().def(false),
                         ui11_compatible: $.val(arg.get(['client', 'isUi11Compatible'])).def(false),
-                        ui16_compatible: $.val(arg.get(['client', 'isUi16Compatible'])),
-                        client_script_v2: $.val(arg.get(['workspace', 'clientScriptV2'])),
+                        ui16_compatible: $.val(arg.get(['client', 'isUi16Compatible'])).def(false),
+                        client_script_v2: $.val(arg.get(['workspace', 'clientScriptV2'])).toCdata(),
                         form_button_v2: $.val(arg.get(['workspace', 'showFormButtonV2'])).def(false),
                         form_menu_button_v2: $.val(arg.get(['workspace', 'showFormMenuButtonV2'])).def(false),
                         format_for_configurable_workspace: $.val(arg.get(['workspace', 'isConfigurableWorkspace'])).def(

package/src/ui-page-plugin.ts

@@ -8,6 +8,7 @@ import {
     isSNScope,
     zipSync,
     unzipSync,
+    ts,
     type Logger,
     type Diagnostics,
     type Project,
@@ -21,9 +22,10 @@ import { parseDocument, DomUtils } from 'htmlparser2'
 import { XMLParser, XMLBuilder, type X2jOptions, type XmlBuilderOptions } from 'fast-xml-parser'
 import { create } from 'xmlbuilder2'
 import { NowIdShape } from './now-id-plugin'
+import { NowIncludeShape } from './now-include-plugin'
 import { CHUNK_SIZE, chunkData, generateId } from './static-content-plugin'
 import { sha256 } from './now-attach-plugin'
-import { createSdkDocEntry } from './utils'
+import { TRANSLATIONS_SUFFIX } from '@servicenow/isomorphic-rollup'
 
 const parserOptions: X2jOptions = {
     ignoreAttributes: false,
@@ -157,6 +159,50 @@ const SOURCE_ARTIFACT_RELATIONSHIPS = {
 
 const parser = new XMLParser(parserOptions)
 
+const escapeHtml = (s: string): string => s.replace(/&/g, '&')
+
+const escapeSingle = (s: string): string => escapeHtml(s).replace(/\\/g, '\\\\').replace(/'/g, "\\'")
+
+const escapeDouble = (s: string): string => escapeHtml(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"')
+
+const getTranslationMessages = (
+    fs: FileSystem,
+    config: NowConfig,
+    rootDir: string,
+    htmlRelPathFromClientDir: string
+): string[] => {
+    // The rollup plugin emits `<stem>.translations.json` next to each bundled html, preserving
+    // the html's subdirectory structure under clientDir. So a source html at
+    // `<clientDir>/admin/page.html` produces `<staticContentDir>/admin/page.translations.json`.
+    if (htmlRelPathFromClientDir.startsWith('..')) {
+        return []
+    }
+    const translationsRelPath = htmlRelPathFromClientDir.replace(/\.html$/, TRANSLATIONS_SUFFIX)
+    const translationsPath = path.join(rootDir, config.staticContentDir, translationsRelPath)
+    try {
+        fs.accessSync(translationsPath)
+    } catch {
+        return []
+    }
+    try {
+        const content = fs.readFileSync(translationsPath, { encoding: 'utf-8' })
+        const parsed = JSON.parse(content) as { messages: Array<string | { [key: string]: string }> }
+        return parsed.messages.map((entry) => (typeof entry === 'string' ? entry : (entry['code'] ?? '')))
+    } catch {
+        return []
+    }
+}
+
+const translationsJellyScript = (scope: string, messages: string[]): string => `
+<script type="text/javascript">
+    'use strict';
+
+    window.__TRANSLATIONS__ = {
+        ${messages.map((message) => `'${escapeSingle(message)}': '\${NS,JS:sn_i18n.Message.getMessage("${escapeDouble(scope)}", "${escapeDouble(message)}")}'`).join(',\n        ')}
+    };
+</script>
+`
+
 // TODO: Remove this shim tag once we've shipped Glide support for this feature.
 const nowUxGlobals = (themeId: string = POLARIS_APPSHELL_THEME_ID) => {
     return parser.parse(`<!-- @sdk:now-ux-globals -->
@@ -216,7 +262,6 @@ const nodeTransformer = (nodes: any[]) => {
 
 export const UiPagePlugin = Plugin.create({
     name: 'UiPagePlugin',
-    docs: [createSdkDocEntry('UiPage', ['sys_ui_page'])],
     records: {
         sys_ui_page: {
             composite: true,
@@ -271,7 +316,7 @@ export const UiPagePlugin = Plugin.create({
                 }
             },
 
-            async toFile(uiPage, { config, descendants, transform }) {
+            async toFile(uiPage, { config, database, descendants, transform }) {
                 if (!uiPage.has('endpoint') && !uiPage.has('name')) {
                     return { success: false }
                 }
@@ -296,6 +341,7 @@ export const UiPagePlugin = Plugin.create({
 
                 const result = await serializeWithArtifact(uiPage, uiPagePropsToSerialize, {
                     config,
+                    database,
                     descendants,
                     transform,
                 })
@@ -410,9 +456,29 @@ export const UiPagePlugin = Plugin.create({
                     diagnostics.error(endpoint.getOriginalNode(), 'endpoint must include a page name before .do')
                     return { success: false }
                 }
-                let html = arg.get('html').toString().getValue()
+                const htmlShape = arg.get('html')
+                let html = htmlShape.toString().getValue()
                 let sourceFilePaths: string[] = []
                 let assetNames: string[] = []
+                let vendorAssetNames: string[] = []
+                let htmlRelPathFromClientDir: string | undefined
+
+                const clientAbsDir = path.join(project.getRootDir(), config.clientDir)
+                const computeRelFromClientDir = (htmlIncludePath: string): string => {
+                    const sourceFileDir = path.dirname(callExpression.getOriginalNode().getSourceFile().getFilePath())
+                    const absoluteHtmlPath = path.resolve(sourceFileDir, htmlIncludePath)
+                    return path.relative(clientAbsDir, absoluteHtmlPath).replace(/\\/g, '/')
+                }
+
+                // `html: Now.include('../ui/hello.html')` resolves to a NowIncludeShape whose path
+                // we can read directly. The included content has no HTML_IMPORT_PREFIX, so detect
+                // this case before the prefix check below.
+                if (htmlShape.is(NowIncludeShape)) {
+                    const includePath = htmlShape.as(NowIncludeShape).getPath()
+                    if (includePath.endsWith('.html')) {
+                        htmlRelPathFromClientDir = computeRelFromClientDir(includePath)
+                    }
+                }
 
                 // HtmlImportPlugin (which runs before toRecord) resolves `html: _html` identifiers
                 // to the file content and prepends an HTML_IMPORT_PREFIX warning comment.
@@ -421,16 +487,23 @@ export const UiPagePlugin = Plugin.create({
                 // An inline string (e.g. `html: '<h1>...</h1>'`) never gets the prefix, so an
                 // unrelated `.html` import in the same file does NOT trigger artifact creation.
                 if (html.trimStart().startsWith(HTML_IMPORT_PREFIX)) {
-                    const originalNode = callExpression.getOriginalNode()
-                    const sourceFile = originalNode.getSourceFile()
-                    // biome-ignore lint/suspicious/noExplicitAny: ts-morph ImportDeclaration type not exported
-                    const htmlImport = (sourceFile.getImportDeclarations() as any[]).find((imp) =>
-                        imp.getModuleSpecifierValue().endsWith('.html')
-                    )
-                    if (htmlImport) {
-                        const relativeHtmlPath = htmlImport.getModuleSpecifierValue()
-                        const sourceFileDir = path.dirname(sourceFile.getFilePath())
-                        const absoluteHtmlPath = path.resolve(sourceFileDir, relativeHtmlPath)
+                    // Resolve the import declaration from the specific identifier passed as the
+                    // `html` argument — NOT the first .html import in the file. A single .now.ts
+                    // may declare several UiPages with different html imports, and each one must
+                    // pick up only the manifest/translations for the file it actually imports.
+                    const htmlNode = htmlShape.getOriginalNode()
+                    const moduleSpecifier = ts.Node.isIdentifier(htmlNode)
+                        ? htmlNode
+                              .getSymbol()
+                              ?.getDeclarations()[0]
+                              ?.getParent()
+                              ?.asKind(ts.SyntaxKind.ImportDeclaration)
+                              ?.getModuleSpecifierValue()
+                        : undefined
+                    if (moduleSpecifier?.endsWith('.html')) {
+                        htmlRelPathFromClientDir = computeRelFromClientDir(moduleSpecifier)
+                        const sourceFileDir = path.dirname(htmlNode.getSourceFile().getFilePath())
+                        const absoluteHtmlPath = path.resolve(sourceFileDir, moduleSpecifier)
                         const manifest = getUIPageSourceFilePaths(
                             absoluteHtmlPath,
                             fs,
@@ -440,6 +513,7 @@ export const UiPagePlugin = Plugin.create({
                         )
                         sourceFilePaths = manifest.files
                         assetNames = manifest.assetNames
+                        vendorAssetNames = manifest.vendorAssetNames
                     }
                 }
 
@@ -458,6 +532,17 @@ export const UiPagePlugin = Plugin.create({
                         }
                         return { success: false }
                     }
+                    if (htmlRelPathFromClientDir) {
+                        const messages = getTranslationMessages(
+                            fs,
+                            config,
+                            project.getRootDir(),
+                            htmlRelPathFromClientDir
+                        )
+                        if (messages.length > 0) {
+                            html += translationsJellyScript(config.scope, messages)
+                        }
+                    }
                 }
 
                 const record = await factory.createRecord({
@@ -503,6 +588,28 @@ export const UiPagePlugin = Plugin.create({
                         assetNames
                     )
 
+                    // Link this page's source artifact to each vendor chunk it depends on.
+                    // Emitted for both configuration and package builds: configuration
+                    // deploys need the M2Ms so the platform knows which vendor chunks belong
+                    // to this page; package builds need them so vendor refs are tracked in
+                    // keys.ts and not flagged as deletes on the next sync.
+                    if (vendorAssetNames.length > 0) {
+                        const artifactRecord = sourceArtifactRecords.find(
+                            (r) => r.getTable() === 'sn_glider_source_artifact'
+                        )
+                        if (artifactRecord) {
+                            const vendorM2ms = await Promise.all(
+                                vendorAssetNames.map((name) =>
+                                    createAssetArtifactM2mRecord(artifactRecord, name, record, {
+                                        factory,
+                                        config,
+                                    })
+                                )
+                            )
+                            sourceArtifactRecords.push(...vendorM2ms)
+                        }
+                    }
+
                     if (sourceArtifactRecords.length > 0) {
                         record.with(...sourceArtifactRecords)
                     } else {
@@ -523,17 +630,18 @@ export const UiPagePlugin = Plugin.create({
 })
 
 /**
- * Reads source file paths from the UI source manifest file.
+ * Reads source file paths and vendor asset names from the UI source manifest file.
  *
  * The manifest is generated by isomorphic-rollup's sourceManifest plugin during build.
- * It's a JSON file with the structure: { html, entry, files: string[] }
+ * It's a JSON file with the structure:
+ *   { html, entry, files: string[], vendors: [fileName, contentHash][] }
  *
  * @param htmlFilePath - Path to the HTML file
  * @param fs - File system interface
  * @param logger - Logger for diagnostics
  * @param config - NowConfig with staticContentDir
  * @param rootDir - Project root directory
- * @returns Array of source file paths (empty array if manifest not found)
+ * @returns Source file paths, entry asset names, and vendor asset names
  */
 const getUIPageSourceFilePaths = (
     htmlFilePath: string,
@@ -541,8 +649,8 @@ const getUIPageSourceFilePaths = (
     logger: Logger,
     config: NowConfig,
     rootDir: string
-): { files: string[]; assetNames: string[] } => {
-    const empty = { files: [], assetNames: [] }
+): { files: string[]; assetNames: string[]; vendorAssetNames: string[] } => {
+    const empty = { files: [], assetNames: [], vendorAssetNames: [] }
     try {
         // Derive manifest path from HTML path by mirroring the directory structure
         // from clientDir into staticContentDir and swapping the extension.
@@ -596,7 +704,30 @@ const getUIPageSourceFilePaths = (
             // no source map in this build output — skip
         }
 
-        return { files: manifest.files, assetNames }
+        // Derive vendor asset names from the manifest's vendors field.
+        // Each vendor entry is [fileName, contentHash], e.g.
+        //   ["vendor-react-dom--d217b640.jsdbx", "d217b640"]
+        // The asset name mirrors static-content-plugin's formula:
+        //   path.join(scope, fileNameWithoutExt)
+        const vendorAssetNames: string[] = []
+        const vendors: [string, string][] = manifest.vendors ?? []
+        for (const [fileName] of vendors) {
+            const ext = path.extname(fileName)
+            const nameWithoutExt = fileName.substring(0, fileName.length - ext.length)
+            const vendorAssetName = path.join(config.scope, nameWithoutExt).replace(/\\/g, '/')
+            vendorAssetNames.push(vendorAssetName)
+
+            // Check for vendor sourcemap
+            const vendorMapPath = path.join(staticContentAbsDir, `${nameWithoutExt}.jsdbx.map`)
+            try {
+                fs.accessSync(vendorMapPath)
+                vendorAssetNames.push(path.join(config.scope, `${nameWithoutExt}.js.map`).replace(/\\/g, '/'))
+            } catch {
+                // no sourcemap for this vendor chunk
+            }
+        }
+
+        return { files: manifest.files, assetNames, vendorAssetNames }
     } catch (error) {
         logger.warn(`Failed to read source manifest: ${error}`)
         return empty
@@ -1114,6 +1245,7 @@ async function serializeWithArtifact(
     metadataRecord: Record,
     metadataProps: string[],
     context: {
+        database: Database
         descendants: { query: (table: string) => Record[] }
         config: { scope: string; scopeId: string }
         transform: Transform
@@ -1293,6 +1425,42 @@ async function serializeWithArtifact(
                 ? `sys_attachment.table_sys_id=${artifactId}^sys_idNOT IN${currentDocIds.join(',')}`
                 : `sys_attachment.table_sys_id=${artifactId}`
         recordUpdate.ele('sys_attachment_doc', { action: 'delete_multiple', query: docQuery })
+
+        // Clean up stale source-artifact M2Ms for this artifact (e.g. when a vendor
+        // chunk hash changes, the M2M to the prior vendor asset must be removed).
+        //
+        // Query the full database, not page descendants: asset M2Ms are descendants
+        // of their sys_ux_lib_asset records, not of the page, so the page's
+        // descendants only have the page M2M. The NOT IN list must include every
+        // current-build M2M for this artifact, otherwise the sweep would also
+        // delete live entry/vendor M2Ms inserted by the asset XMLs.
+        //
+        // Skip DELETE-action rows: on a same-project package rebuild,
+        // generateRecordsFromDeletedKeys inserts DELETE rows for keys no longer
+        // registered (e.g. the prior vendor M2M). Adding their sys_ids to NOT IN
+        // would protect the stale rows on the platform — defeating the sweep.
+        const currentM2mIds = context.database
+            .query('sn_glider_source_artifact_m2m')
+            .filter((m2m) => {
+                if (m2m.isDeleted()) {
+                    return false
+                }
+                const srcArtifact = m2m.get('source_artifact')
+                const srcId = srcArtifact.isRecord()
+                    ? srcArtifact.asRecord().getId().getValue()
+                    : srcArtifact.toString().getValue()
+                return srcId === artifactId
+            })
+            .map((m2m) => m2m.getId().getValue())
+
+        const m2mQuery =
+            currentM2mIds.length > 0
+                ? `source_artifact=${artifactId}^sys_idNOT IN${currentM2mIds.join(',')}`
+                : `source_artifact=${artifactId}`
+        recordUpdate.ele('sn_glider_source_artifact_m2m', {
+            action: 'delete_multiple',
+            query: m2mQuery,
+        })
     })
 
     return {

package/src/ui-policy-plugin.ts

@@ -8,7 +8,7 @@ import {
     type Record,
     type Shape,
 } from '@servicenow/sdk-build-core'
-import { createSdkDocEntry, validateClientSideScript } from './utils'
+import { validateClientSideScript } from './utils'
 import { NowIdShape } from './now-id-plugin'
 
 // Define table names as constants since they're not exported from the core tables
@@ -93,7 +93,6 @@ const validateScriptProperty = (
 
 export const UiPolicyPlugin = Plugin.create({
     name: 'UiPolicyPlugin',
-    docs: [createSdkDocEntry('UiPolicy', ['sys_ui_policy'])],
     records: {
         [SYS_UI_POLICY]: {
             coalesce: ['table', 'short_description'],
@@ -108,128 +107,35 @@ export const UiPolicyPlugin = Plugin.create({
                 },
             },
             toShape(record, { descendants }) {
-                const actions = descendants
-                    .query(SYS_UI_POLICY_ACTION)
-                    .map((action) => {
-                        const fieldValue = action.get('field')?.ifString()?.getValue()
-                        if (!fieldValue) {
-                            return null // Skip actions without a field
-                        }
-
-                        const actionObj: {
-                            field: string
-                            visible?: boolean | 'ignore'
-                            readOnly?: boolean | 'ignore'
-                            mandatory?: boolean | 'ignore'
-                            cleared?: boolean
-                            table?: string
-                            value?: string
-                            fieldMessage?: string
-                            fieldMessageType?: string
-                            valueAction?: string
-                        } = {
-                            field: fieldValue,
-                        }
-
-                        // Convert ServiceNow string format to boolean | 'ignore'
-                        const visible = stringToBoolean(action.get('visible')?.ifString()?.getValue())
-                        const disabled = stringToBoolean(action.get('disabled')?.ifString()?.getValue())
-                        const mandatory = stringToBoolean(action.get('mandatory')?.ifString()?.getValue())
-
-                        // Only include visible if it's not 'ignore'
-                        if (visible !== undefined && visible !== 'ignore') {
-                            actionObj.visible = visible
-                        }
-
-                        // Convert 'disabled' to 'readOnly'
-                        // Only include 'readOnly' if it's not 'ignore'
-                        if (disabled !== undefined && disabled !== 'ignore') {
-                            actionObj.readOnly = disabled
-                        }
-
-                        // Only include mandatory if it's not 'ignore'
-                        if (mandatory !== undefined && mandatory !== 'ignore') {
-                            actionObj.mandatory = mandatory
-                        }
-
-                        const cleared = action.get('cleared')?.ifBoolean()?.getValue()
-                        if (cleared) {
-                            actionObj.cleared = cleared
-                        }
-
-                        // Add new optional fields - only if they have meaningful values
-                        const table = action.get('table')?.ifString()?.getValue()
-                        const parentTable = record.get('table')?.ifString()?.getValue()
-                        // Only include table if it's different from the parent policy's table
-                        if (table && table !== parentTable) {
-                            actionObj.table = table
-                        }
-
-                        const value = action.get('value')?.ifString()?.getValue()
-                        if (value) {
-                            actionObj.value = value
-                        }
-
-                        const fieldMessage = action.get('field_message')?.ifString()?.getValue()
-                        if (fieldMessage) {
-                            actionObj.fieldMessage = fieldMessage
-                        }
-
-                        const fieldMessageType = action.get('field_message_type')?.ifString()?.getValue()
-                        // Only include if it's not the default value 'none'
-                        if (fieldMessageType && fieldMessageType !== 'none') {
-                            actionObj.fieldMessageType = fieldMessageType
-                        }
-
-                        const valueAction = action.get('value_action')?.ifString()?.getValue()
-                        // Only include if it's not the default value 'ignore'
-                        if (valueAction && valueAction !== 'ignore') {
-                            actionObj.valueAction = valueAction
-                        }
-
-                        // Skip actions that have no meaningful properties (all are 'ignore')
-                        if (Object.keys(actionObj).length === 1) {
-                            return null // Only 'field' property exists, skip this action
-                        }
+                const actions = descendants.query(SYS_UI_POLICY_ACTION).map((action) => {
+                    return action.transform(({ $ }) => ({
+                        field: $,
+                        visible: $.map((v) => stringToBoolean(v?.asString()?.getValue())).def('ignore'),
+                        readOnly: $.from('disabled')
+                            .map((v) => stringToBoolean(v?.asString()?.getValue()))
+                            .def('ignore'),
+                        mandatory: $.map((v) => stringToBoolean(v?.asString()?.getValue())).def('ignore'),
+                        cleared: $.toBoolean().def(false),
+                        table: $.def(''),
+                        value: $.def(''),
+                        fieldMessage: $.from('field_message').def(''),
+                        fieldMessageType: $.from('field_message_type').def('none'),
+                        valueAction: $.from('value_action').def('ignore'),
+                    }))
+                })
 
-                        return actionObj
-                    })
-                    .filter((action) => action !== null) // Remove null actions
-
-                // Process related list actions
-                const relatedListActions = descendants
-                    .query(SYS_UI_POLICY_RL_ACTION)
-                    .map((rlAction) => {
-                        const rlActionObj: {
-                            list?: string
-                            visible?: boolean | 'ignore'
-                        } = {}
-
-                        const listValue = rlAction.get('list')?.ifString()?.getValue()
-                        if (listValue) {
-                            // Strip REL: prefix if present (transform ServiceNow → Fluent)
-                            // Users write plain GUIDs or table.field format in Fluent code
-                            if (listValue.startsWith('REL:')) {
-                                rlActionObj.list = listValue.substring(4) // Remove 'REL:' prefix
-                            } else {
-                                rlActionObj.list = listValue
+                const relatedListActions = descendants.query(SYS_UI_POLICY_RL_ACTION).map((rlAction) =>
+                    rlAction.transform(({ $ }) => ({
+                        list: $.map((v) => {
+                            if (v?.ifString()?.ifDefined()) {
+                                const listVal = v.asString().getValue()
+                                return listVal.startsWith('REL:') ? listVal.substring(4) : listVal
                             }
-                        }
-
-                        // Convert ServiceNow string format to boolean | 'ignore'
-                        const visible = stringToBoolean(rlAction.get('visible')?.ifString()?.getValue())
-                        if (visible !== undefined && visible !== 'ignore') {
-                            rlActionObj.visible = visible
-                        }
-
-                        // Skip if no meaningful properties (only $id exists)
-                        if (Object.keys(rlActionObj).length === 0) {
-                            return null
-                        }
-
-                        return rlActionObj
-                    })
-                    .filter((rlAction) => rlAction !== null) // Remove null actions
+                            return ''
+                        }).def(''),
+                        visible: $.map((v) => stringToBoolean(v?.asString()?.getValue())).def('ignore'),
+                    }))
+                )
 
                 return {
                     success: true,
@@ -278,7 +184,7 @@ export const UiPolicyPlugin = Plugin.create({
                                     order: $.from('order').toNumber().def(100),
                                     setValues: $.from('set_values').def(''),
                                     view: $.from('view').def(''),
-                                    actions: $.val(actions.length > 0 ? actions : undefined),
+                                    actions: $.val(actions).def([]),
                                     relatedListActions: $.val(
                                         relatedListActions.length > 0 ? relatedListActions : undefined
                                     ),
@@ -401,11 +307,10 @@ export const UiPolicyPlugin = Plugin.create({
                         const hasClearedProp = action.get('cleared')?.isBoolean() || false
 
                         if (!hasVisibleProp && !hasReadOnlyProp && !hasMandatoryProp && !hasClearedProp) {
-                            diagnostics.error(
+                            diagnostics.hint(
                                 action,
-                                `Action at index ${i} must specify at least one of: visible, readOnly, mandatory, or cleared`
+                                `Action at index ${i} has no effect — consider specifying at least one of: visible, readOnly, mandatory, or cleared`
                             )
-                            continue
                         }
 
                         const actionRecord = await factory.createRecord({
@@ -475,14 +380,12 @@ export const UiPolicyPlugin = Plugin.create({
                             }
                         }
 
-                        // At least one property must be specified (visible or list)
                         const hasVisibleProp = isValidActionValue(rlAction.get('visible'))
                         if (!hasVisibleProp && !listValue) {
-                            diagnostics.error(
+                            diagnostics.hint(
                                 rlAction,
-                                `Related list action at index ${i} must specify at least one of: list or visible`
+                                `Related list action at index ${i} has no effect — consider specifying at least one of: list or visible`
                             )
-                            continue
                         }
 
                         const rlActionRecord = await factory.createRecord({

package/src/user-preference-plugin.ts

@@ -1,6 +1,5 @@
 import { CallExpressionShape, Plugin } from '@servicenow/sdk-build-core'
 import { NowIdShape } from './now-id-plugin'
-import { createSdkDocEntry } from './utils'
 
 /**
  * Creates a User Preference (sys_user_preference).
@@ -17,7 +16,6 @@ import { createSdkDocEntry } from './utils'
  */
 export const UserPreferencePlugin = Plugin.create({
     name: 'UserPreferencePlugin',
-    docs: [createSdkDocEntry('UserPreference', ['sys_user_preference'])],
     records: {
         sys_user_preference: {
             toShape(record) {