@servicenow/sdk-build-plugins 4.6.1 → 4.7.1

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'],

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) {

package/src/utils.ts

@@ -4,7 +4,6 @@ import {
     type ObjectShape,
     type Diagnostics,
     type Compiler,
-    type PluginApiDoc,
     type Record as FluentRecord,
     type OutputFile,
     type Transform,
@@ -182,20 +181,6 @@ export async function generateChoiceSetFile(
     }
 }
 
-/**
- * Creates a documentation entry for first-party SDK plugins.
- *
- * @param apiName - The API name (e.g., 'BusinessRule', 'Acl')
- * @param tags - Keywords for categorization (typically includes the ServiceNow table name)
- * @returns A complete PluginApiDoc entry
- */
-export function createSdkDocEntry(apiName: string, tags: string[]): PluginApiDoc {
-    return {
-        apiName,
-        tags,
-    }
-}
-
 /**
  * Parses a number from a shape record field with fallback to default value.
  * Returns undefined if the field doesn't exist and no default is provided.

package/src/ux-list-menu-config-plugin.ts

@@ -1,11 +1,9 @@
 import { Plugin, CallExpressionShape, type Record } from '@servicenow/sdk-build-core'
 
 import { NowIdShape } from './now-id-plugin'
-import { createSdkDocEntry } from './utils'
 
 export const UxListMenuConfigPlugin = Plugin.create({
     name: 'UxListMenuConfigPlugin',
-    docs: [createSdkDocEntry('UxListMenuConfig', ['sys_ux_list_menu_config'])],
     records: {
         sys_ux_list_menu_config: {
             relationships: {

package/src/view-plugin.ts

@@ -2,7 +2,6 @@ import { Plugin, Record, RecordId, Shape, ts } from '@servicenow/sdk-build-core'
 
 export const ViewPlugin = Plugin.create({
     name: 'ViewPlugin',
-    docs: [],
     records: {
         sys_ui_view: {
             coalesce: ['name'],

package/src/workspace-plugin.ts

@@ -8,7 +8,6 @@ import {
     Database,
 } from '@servicenow/sdk-build-core'
 import { NowIdShape } from './now-id-plugin'
-import { createSdkDocEntry } from './utils'
 import { parsePagePropChromeTabJson, createChromeTabJsonStringForPageProp } from './workspace-plugin/chrome-tab'
 import { createPage } from './workspace-plugin/page'
 import {
@@ -43,7 +42,6 @@ type InnerTransformFromObjectShape = Parameters<Parameters<ObjectShape['transfor
 
 export const WorkspacePlugin = Plugin.create({
     name: 'WorkspacePlugin',
-    docs: [createSdkDocEntry('Workspace', ['sys_ux_page_registry'])],
     records: {
         sys_ux_page_registry: {
             relationships: {