@servicenow/sdk-build-plugins 4.4.0 → 4.5.0

package/src/sla-plugin.ts

@@ -1,5 +1,6 @@
 import { CallExpressionShape, Plugin, DurationShape } from '@servicenow/sdk-build-core'
 import { NowIdShape } from './now-id-plugin'
+import { createSdkDocEntry } from './utils'
 import {
     validateUserSpecifiedDuration,
     validateRelativeDuration,
@@ -36,6 +37,7 @@ const DEFAULT_DURATION_ON_PLATFORM = '1970-01-01 00:00:00'
  */
 export const SLAPlugin = Plugin.create({
     name: 'SLAPlugin',
+    docs: [createSdkDocEntry('Sla', ['contract_sla'])],
 
     records: {
         contract_sla: {

package/src/static-content-plugin.ts

@@ -91,6 +91,7 @@ const toNoOpShape = (record: Record) => {
 
 export const StaticContentPlugin = Plugin.create({
     name: 'StaticContentPlugin',
+    docs: [],
     records: {
         // TODO: remove when we have generic attachment support
         sys_attachment: {

package/src/table-plugin.ts

@@ -26,7 +26,7 @@ import { create } from 'xmlbuilder2'
 import type { XMLBuilder } from 'xmlbuilder2/lib/interfaces'
 import { addFieldsToColumn } from './column/column-helper'
 import { getLabelForDefaultLanguage } from './column/column-to-record'
-import { generateDeprecatedDiagnostics } from './utils'
+import { createSdkDocEntry, generateDeprecatedDiagnostics } from './utils'
 import isEqual from 'lodash/isEqual'
 
 type GlobalRecord<T extends string | number | symbol, U> = globalThis.Record<T, U>
@@ -370,6 +370,7 @@ const licensingAliases = {
 
 export const TablePlugin = Plugin.create({
     name: 'TablePlugin',
+    docs: [createSdkDocEntry('Table', ['sys_db_object'])],
     files: [
         {
             matcher: /\.xml$/,

package/src/ui-action-plugin.ts

@@ -8,9 +8,11 @@ import {
 } from '@servicenow/sdk-build-core'
 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: {

package/src/ui-page-plugin.ts

@@ -22,6 +22,7 @@ import { create } from 'xmlbuilder2'
 import { NowIdShape } from './now-id-plugin'
 import { CHUNK_SIZE, chunkData, generateId } from './static-content-plugin'
 import { sha256 } from './now-attach-plugin'
+import { createSdkDocEntry } from './utils'
 
 const parserOptions: X2jOptions = {
     ignoreAttributes: false,
@@ -158,10 +159,19 @@ const nodeTransformer = (nodes: any[]) => {
 
 export const UiPagePlugin = Plugin.create({
     name: 'UiPagePlugin',
+    docs: [createSdkDocEntry('UiPage', ['sys_ui_page'])],
     records: {
         sys_ui_page: {
             composite: true,
-            coalesce: ['endpoint'],
+            coalesce: (properties) => {
+                // Use endpoint for scoped pages (backward compatible), fall back to name for global scope
+                const endpoint = properties.get('endpoint').pipe((v) => v.ifDefined()?.toString().getValue())
+                if (endpoint) {
+                    return { endpoint }
+                }
+                const name = properties.get('name').pipe((v) => v.ifDefined()?.toString().getValue()) ?? 'NULL'
+                return { name }
+            },
             relationships: SOURCE_ARTIFACT_RELATIONSHIPS,
             async toShape(record, { descendants, fs, project, config, logger, diagnostics }) {
                 const shapeWithSourceArtifacts = await getShapeWithSourceArtifacts(record, descendants, {
@@ -178,6 +188,11 @@ export const UiPagePlugin = Plugin.create({
                     }
                 }
 
+                // For global scope, endpoint is empty in the DB — synthesize from name
+                const endpointValue = record.get('endpoint').toString().getValue()
+                const nameValue = record.get('name').toString().getValue()
+                const effectiveEndpoint = endpointValue || (nameValue ? `${nameValue}.do` : '')
+
                 return {
                     success: true,
                     value: new CallExpressionShape({
@@ -187,7 +202,7 @@ export const UiPagePlugin = Plugin.create({
                             record.transform(({ $ }) => ({
                                 $id: $.val(NowIdShape.from(record)),
                                 category: $.def(''),
-                                endpoint: $,
+                                endpoint: $.val(effectiveEndpoint).def(''),
                                 description: $.def(''),
                                 direct: $.toBoolean().def(false),
                                 html: $.def(''),
@@ -200,7 +215,7 @@ export const UiPagePlugin = Plugin.create({
             },
 
             async toFile(uiPage, { config, descendants, transform }) {
-                if (!uiPage.has('endpoint')) {
+                if (!uiPage.has('endpoint') && !uiPage.has('name')) {
                     return { success: false }
                 }
 
@@ -324,11 +339,20 @@ export const UiPagePlugin = Plugin.create({
                 const arg = callExpression.getArgument(0).asObject()
                 const endpoint = arg.get('endpoint').asString()
                 const scope = config.scope
-                if (scope !== 'global' && !isSNScope(scope) && !endpoint.getValue().startsWith(`${scope}_`)) {
+                const isGlobalScope = scope === 'global'
+                if (!isGlobalScope && !isSNScope(scope) && !endpoint.getValue().startsWith(`${scope}_`)) {
                     diagnostics.error(endpoint.getOriginalNode(), `endpoint must begin with '${scope}_'`)
                     return { success: false }
                 }
-                const name = endpoint.asString().getValue().replace(`${scope}_`, '').replace(/\.do$/, '')
+                // For global scope, name is the endpoint without .do (e.g., 'my-page.do' → 'my-page')
+                // For scoped, strip scope prefix and .do (e.g., 'x_test_boats.do' → 'boats')
+                const name = isGlobalScope
+                    ? endpoint.getValue().replace(/\.do$/, '')
+                    : endpoint.getValue().replace(`${scope}_`, '').replace(/\.do$/, '')
+                if (!name) {
+                    diagnostics.error(endpoint.getOriginalNode(), 'endpoint must include a page name before .do')
+                    return { success: false }
+                }
                 let html = arg.get('html').toString().getValue()
                 let sourceFilePaths: string[] = []
                 let assetNames: string[] = []
@@ -383,7 +407,7 @@ export const UiPagePlugin = Plugin.create({
                     explicitId: arg.get('$id'),
                     properties: arg.transform(({ $ }) => ({
                         name: $.val(name),
-                        endpoint: $.val(endpoint),
+                        endpoint: $.val(isGlobalScope ? '' : endpoint),
                         description: $,
                         direct: $.def(false),
                         category: $,
@@ -574,6 +598,8 @@ async function getShapeWithSourceArtifacts(
 
     if (htmlFileRelativePath && !context.project.isInFluentDir(originalFilePath)) {
         const endpoint = uiPageRecord.get('endpoint').toString().getValue()
+        const pageName = uiPageRecord.get('name').toString().getValue()
+        const effectiveEndpoint = endpoint || (pageName ? `${pageName}.do` : '')
         const description = uiPageRecord.get('description').toString().getValue()
         const category = uiPageRecord.get('category').toString().getValue()
         const direct = uiPageRecord.get('direct').toString().getValue()
@@ -587,7 +613,7 @@ async function getShapeWithSourceArtifacts(
 
             UiPage({
                 $id: Now.ID['${uiPageRecord.getId().getValue()}'],
-                endpoint: ${JSON.stringify(endpoint)},
+                endpoint: ${JSON.stringify(effectiveEndpoint)},
                 description: ${JSON.stringify(description)},
                 category: ${JSON.stringify(category)},
                 direct: ${direct},
@@ -596,7 +622,7 @@ async function getShapeWithSourceArtifacts(
                 processingScript: ${JSON.stringify(processingScript)},
             })
         `
-        const newFileName = endpoint.replace('.do', '.now.ts')
+        const newFileName = effectiveEndpoint.replace('.do', '.now.ts')
         const sourceFileShape = new SourceFileShape({
             source: uiPageRecord,
             path: `${path.join(fluentFileDirByTaxonomy, newFileName)}`,

package/src/ui-policy-plugin.ts

@@ -8,7 +8,7 @@ import {
     type Record,
     type Shape,
 } from '@servicenow/sdk-build-core'
-import { validateClientSideScript } from './utils'
+import { createSdkDocEntry, validateClientSideScript } from './utils'
 import { NowIdShape } from './now-id-plugin'
 
 // Define table names as constants since they're not exported from the core tables
@@ -93,6 +93,7 @@ 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,5 +1,6 @@
 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).
@@ -16,6 +17,7 @@ import { NowIdShape } from './now-id-plugin'
  */
 export const UserPreferencePlugin = Plugin.create({
     name: 'UserPreferencePlugin',
+    docs: [createSdkDocEntry('UserPreference', ['sys_user_preference'])],
     records: {
         sys_user_preference: {
             toShape(record) {

package/src/utils.ts

@@ -5,6 +5,7 @@ import {
     type Diagnostics,
     type Compiler,
     type PluginApiDoc,
+    type Record as FluentRecord,
 } from '@servicenow/sdk-build-core'
 
 export function toReference(shape: Shape) {
@@ -101,9 +102,36 @@ export function validateClientSideScript(script: string, compiler: Compiler): bo
     return isValid
 }
 
+/**
+ * Shows a diagnostic error when a field expects a valid GUID but receives an invalid value.
+ *
+ * @param inputReceived - The shape containing the invalid value
+ * @param fieldName - Name of the field being validated (e.g., 'annotationId', 'formatterRef')
+ * @param tableName - ServiceNow table name for the expected reference (e.g., 'sys_ui_annotation')
+ * @param diagnostics - Diagnostics collection to add the error to
+ *
+ * @example
+ * if (!isGUID(annotationSysId)) {
+ *     showGuidFieldDiagnostic(annotationIdField, 'annotationId', 'sys_ui_annotation', diagnostics)
+ * }
+ */
+export const showGuidFieldDiagnostic = (
+    inputReceived: Shape | undefined,
+    fieldName: string,
+    tableName: string,
+    diagnostics: Diagnostics
+) => {
+    if (inputReceived) {
+        const receivedValue = inputReceived.getValue()
+        diagnostics.error(
+            inputReceived,
+            `'${fieldName}' must be a valid GUID or a Record<'${tableName}'>. Received: '${receivedValue}'`
+        )
+    }
+}
+
 /**
  * Creates a documentation entry for first-party SDK plugins.
- * Using this helper ensures apiName and docPath are always in sync.
  *
  * @param apiName - The API name (e.g., 'BusinessRule', 'Acl')
  * @param tags - Keywords for categorization (typically includes the ServiceNow table name)
@@ -112,7 +140,19 @@ export function validateClientSideScript(script: string, compiler: Compiler): bo
 export function createSdkDocEntry(apiName: string, tags: string[]): PluginApiDoc {
     return {
         apiName,
-        docPath: `@servicenow/sdk/docs/${apiName}/${apiName}.md`,
         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.
+ */
+export function getFieldAsNumber(shape: FluentRecord, fieldName: string, defaultValue?: number): number | undefined {
+    const rawValue = shape.get(fieldName)?.getValue()
+    if (rawValue === undefined || rawValue === null || rawValue === '') {
+        return defaultValue
+    }
+    const parsed = Number(rawValue)
+    return Number.isNaN(parsed) ? defaultValue : parsed
+}

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

@@ -1,9 +1,11 @@
 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,6 +2,7 @@ import { Plugin, Record, RecordId, Shape } from '@servicenow/sdk-build-core'
 
 export const ViewPlugin = Plugin.create({
     name: 'ViewPlugin',
+    docs: [],
     records: {
         sys_ui_view: {
             coalesce: ['name'],

package/src/workspace-plugin.ts

@@ -7,6 +7,7 @@ import {
     type ObjectShape,
 } 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 {
@@ -41,6 +42,7 @@ 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: {

package/src/_types/eslint-plugin-es-x.d.ts

@@ -1,17 +0,0 @@
-declare module 'eslint-plugin-es-x/lib/rules/no-dynamic-import.js' {
-    import type { Rule } from 'eslint'
-    const rule: Rule.RuleModule
-    export default rule
-}
-
-declare module 'eslint-plugin-es-x/lib/rules/no-regexp-lookbehind-assertions.js' {
-    import type { Rule } from 'eslint'
-    const rule: Rule.RuleModule
-    export default rule
-}
-
-declare module 'eslint-plugin-es-x/lib/rules/no-regexp-unicode-property-escapes.js' {
-    import type { Rule } from 'eslint'
-    const rule: Rule.RuleModule
-    export default rule
-}