@servicenow/sdk-build-core 4.2.0 → 4.3.0

package/src/plugins/data-shape.ts

@@ -1,4 +1,4 @@
-import { ObjectShape, ArrayShape, Shape, type StringShape } from './shape'
+import { CallExpressionShape, ObjectShape, Shape, StringShape } from './shape'
 import type { Source } from './product'
 import {
     durationFieldToXML,
@@ -20,10 +20,11 @@ export const DATA_HELPER_NAMES = {
 } as const
 
 /**
- * Base class for serializable data shapes that extend ObjectShape.
+ * Base class for data helper shapes that extend CallExpressionShape.
+ * These shapes represent call expressions like Duration(), Time(), etc.
  * Provides common equals implementation that compares via toString().
  */
-abstract class SerializableObjectShape extends ObjectShape {
+abstract class DataHelperShape extends CallExpressionShape {
     abstract override toString(): StringShape
 
     override equals(other: unknown): boolean {
@@ -38,50 +39,30 @@ abstract class SerializableObjectShape extends ObjectShape {
 }
 
 /**
- * Base class for serializable data shapes that extend ArrayShape.
- * Provides common equals implementation that compares via toString().
+ * Shape representing a duration value.
+ * Used with Duration() helper - represents Duration({ days, hours, minutes, seconds }) call expression.
  */
-abstract class SerializableArrayShape extends ArrayShape {
-    abstract override toString(): StringShape
-
-    override equals(other: unknown): boolean {
-        if (typeof other === 'string') {
-            return this.toString().getValue() === other
-        } else if (other instanceof Shape) {
-            return other.equals(this.toString().getValue())
+export class DurationShape extends DataHelperShape {
+    constructor({ source, value }: { source: Source; value: Duration | ObjectShape }) {
+        let durationValue: Duration
+        if (value instanceof ObjectShape) {
+            const picked = value.pick(['days', 'hours', 'minutes', 'seconds'])
+            durationValue = Object.fromEntries(
+                Object.entries(picked).map(([k, v]) => [
+                    k,
+                    Shape.from(source, v).asNumber(
+                        `fields in Duration object can only contain numbers, got ${typeof v}`
+                    ),
+                ])
+            ) as Duration
         } else {
-            return super.equals(other)
+            durationValue = value
         }
-    }
-}
-
-/**
- * Shape representing a duration value.
- * Used with Duration() helper - stores object with days, hours, minutes, seconds.
- */
-export class DurationShape extends SerializableObjectShape {
-    constructor({ source, value }: { source: Source; value: Duration }) {
-        super({ source, properties: value })
+        super({ source, callee: DATA_HELPER_NAMES.DURATION, args: [durationValue] })
     }
 
     getDuration(): Duration {
-        return super.getValue() as Duration
-    }
-
-    getDays(): number {
-        return this.getDuration().days ?? 0
-    }
-
-    getHours(): number {
-        return this.getDuration().hours ?? 0
-    }
-
-    getMinutes(): number {
-        return this.getDuration().minutes ?? 0
-    }
-
-    getSeconds(): number {
-        return this.getDuration().seconds ?? 0
+        return this.getArgument(0).asObject().getValue() as Duration
     }
 
     /**
@@ -94,51 +75,77 @@ export class DurationShape extends SerializableObjectShape {
         return Shape.from(this.getSource(), formatted).asString()
     }
 
-    static override from(source: Source, text: StringShape): DurationShape {
-        const duration = parseGlideDuration(text.getValue())
-        if (!duration) {
-            throw new Error(`Invalid duration value: ${text.getValue()}`)
+    static override from(source: Source, value: StringShape | ObjectShape): DurationShape {
+        if (value instanceof StringShape) {
+            const parsedValue = parseGlideDuration(value.getValue())
+            if (!parsedValue) {
+                throw new Error(`Invalid duration value: ${value.getValue()}`)
+            }
+            return new DurationShape({
+                source,
+                value: parsedValue,
+            })
         }
 
         return new DurationShape({
             source,
-            value: duration,
+            value: value,
+        })
+    }
+
+    /**
+     * Creates a DurationShape representing zero duration.
+     * Use this when the platform returns an empty or default duration value.
+     * @example DurationShape.zero(source) // Returns Duration({ seconds: 0 })
+     */
+    static zero(source: Source): DurationShape {
+        return new DurationShape({
+            source,
+            value: { seconds: 0 },
         })
     }
 }
 
 /**
  * Shape representing a time of day value.
- * Used with Time() helper - stores object with hours, minutes, seconds.
+ * Used with Time() helper - represents Time({ hours, minutes, seconds }, timezone?) call expression.
  */
-export class TimeShape extends SerializableObjectShape {
+export class TimeShape extends DataHelperShape {
     private readonly timeZone: string | undefined
 
-    constructor({ source, value, timeZone }: { source: Source; value: TimeOfDay; timeZone?: string | undefined }) {
-        super({ source, properties: value })
-        this.timeZone = timeZone ?? undefined
+    constructor({
+        source,
+        value,
+        timeZone,
+    }: { source: Source; value: TimeOfDay | ObjectShape; timeZone?: string | undefined }) {
+        let timeValue: TimeOfDay
+        if (value instanceof ObjectShape) {
+            const picked = value.pick(['hours', 'minutes', 'seconds'])
+            timeValue = Object.fromEntries(
+                Object.entries(picked).map(([k, v]) => [
+                    k,
+                    Shape.from(source, v).asNumber(`fields in Time object can only contain numbers, got ${typeof v}`),
+                ])
+            ) as TimeOfDay
+        } else {
+            timeValue = value
+        }
+        const args: unknown[] = [timeValue]
+        if (timeZone) {
+            args.push(timeZone)
+        }
+        super({ source, callee: DATA_HELPER_NAMES.TIME, args })
+        this.timeZone = timeZone
     }
 
     getTimeData(): TimeOfDay {
-        return super.getValue() as TimeOfDay
+        return this.getArgument(0).asObject().getValue() as TimeOfDay
     }
 
     getTimeZone(): string | undefined {
         return this.timeZone
     }
 
-    getHours(): number {
-        return this.getTimeData().hours ?? 0
-    }
-
-    getMinutes(): number {
-        return this.getTimeData().minutes ?? 0
-    }
-
-    getSeconds(): number {
-        return this.getTimeData().seconds ?? 0
-    }
-
     /**
      * Returns a StringShape with the ServiceNow serialized format.
      * @example '1970-01-01 14:30:00' for { hours: 14, minutes: 30 }
@@ -149,14 +156,22 @@ export class TimeShape extends SerializableObjectShape {
         return Shape.from(this.getSource(), formatted).toString()
     }
 
-    static override from(source: Source, text: StringShape, timeZone?: string): TimeShape {
-        const time = parseGlideTime(text.getValue(), timeZone)
-        if (!time) {
-            throw new Error(`Invalid time value: ${text.getValue()}`)
+    static override from(source: Source, value: StringShape | ObjectShape, timeZone?: string): TimeShape {
+        if (value instanceof StringShape) {
+            const parsedValue = parseGlideTime(value.getValue(), timeZone)
+            if (!parsedValue) {
+                throw new Error(`Invalid time value: ${value.getValue()}`)
+            }
+            return new TimeShape({
+                source,
+                value: parsedValue,
+                timeZone,
+            })
         }
+
         return new TimeShape({
             source,
-            value: time,
+            value: value,
             timeZone,
         })
     }
@@ -164,15 +179,15 @@ export class TimeShape extends SerializableObjectShape {
 
 /**
  * Shape representing a field list.
- * Used with FieldList() helper - stores array of field names.
+ * Used with FieldList() helper - represents FieldList(["field1", "field2"]) call expression.
  */
-export class FieldListShape extends SerializableArrayShape {
+export class FieldListShape extends DataHelperShape {
     constructor({ source, fields }: { source: Source; fields: Shape[] }) {
-        super({ source, elements: fields })
+        super({ source, callee: DATA_HELPER_NAMES.FIELD_LIST, args: [fields] })
     }
 
     getFields(): Shape[] {
-        return super.getElements()
+        return this.getArgument(0).asArray().getElements()
     }
 
     /**
@@ -198,19 +213,15 @@ export class FieldListShape extends SerializableArrayShape {
 
 /**
  * Shape representing a template value (ServiceNow encoded query format).
- * Used with TemplateValue() helper - stores object with field-value pairs.
+ * Used with TemplateValue() helper - represents TemplateValue({ field: value }) call expression.
  */
-export class TemplateValueShape extends SerializableObjectShape {
+export class TemplateValueShape extends DataHelperShape {
     constructor({ source, value }: { source: Source; value: globalThis.Record<string, unknown> }) {
-        super({ source, properties: value })
-    }
-
-    getFields(): string[] {
-        return Object.keys(this.getValue())
+        super({ source, callee: DATA_HELPER_NAMES.TEMPLATE_VALUE, args: [value] })
     }
 
-    getFieldValue(fieldName: string): unknown {
-        return this.getValue()[fieldName]
+    getTemplateValue(): ObjectShape {
+        return this.getArgument(0).asObject()
     }
 
     /**
@@ -220,8 +231,8 @@ export class TemplateValueShape extends SerializableObjectShape {
      * @example 'name=value^^with^^caret^EQ' for { name: 'value^with^caret' }
      */
     override toString(): StringShape {
-        const entries = Object.entries(this.getValue())
-        const encoded = entries
+        const templateValue = this.getTemplateValue().getValue()
+        const encoded = Object.entries(templateValue)
             .map(([key, value]) => {
                 // Escape single ^ as ^^ in values
                 const escapedValue = String(value).replace(/\^/g, '^^')

package/src/plugins/plugin.ts

@@ -25,6 +25,11 @@ export type Result<Value = unknown> =
           success: true
           value: Value
       }
+    | {
+          success: 'partial'
+          value: Value
+          unhandledRecords: Record[]
+      }
 
 export type CommitResult = { success: boolean }
 
@@ -92,6 +97,36 @@ export type CoalesceStrategy =
 
 export type FileType = 'fluent' | 'module' | 'json' | 'unknown'
 
+export type PluginApiDoc = {
+    /**
+     * The name of the API (e.g., 'BusinessRule', 'Acl', 'Table')
+     * This is the callee name used in fluent code.
+     */
+    apiName: string
+
+    /**
+     * Uses module-specifier path to the markdown documentation file for this API relative to the SDK root.
+     * For example, @servicenow/sdk/docs/BusinessRule/BusinessRule.md
+     */
+    docPath: string
+
+    /**
+     * Tags for categorizing and organizing the API documentation
+     */
+    tags: string[]
+}
+
+/**
+ * Manifest structure for API documentation.
+ * This is the opinionated format returned by getDocsMetadata().
+ */
+export type DocsManifest = {
+    [apiName: string]: {
+        docPath: string
+        tags: string[]
+    }
+}
+
 export type PluginConfig<
     Nodes extends SupportedKindName[] = SupportedKindName[],
     Shapes extends ShapeClass[] = ShapeClass[],
@@ -103,6 +138,12 @@ export type PluginConfig<
      */
     name: `${string}Plugin`
 
+    /**
+     * Documentation for the APIs provided by this plugin. This is used to automatically
+     * generate documentation that can be retrieved via the getDocsMetadata() method.
+     */
+    docs?: PluginApiDoc[]
+
     /**
      * The TypeScript AST nodes this plugin handles. Plugins that do not introduce new
      * syntax should not need to define any handlers here.
@@ -380,7 +421,12 @@ export type PluginConfig<
              * @returns A result indicating whether diffing was successful and, if so, a database
              *          containing only the changed records
              */
-            diff?: (existing: Database, incoming: Database, context: Context) => Promise<Result<Database>>
+            diff?: (
+                existing: Database,
+                incoming: Database,
+                descendants: Database,
+                context: Context
+            ) => Promise<Result<Database>>
         }
     }
 
@@ -595,6 +641,28 @@ export class Plugin {
         return this.config.name
     }
 
+    /**
+     * Get documentation metadata for APIs provided by this plugin.
+     * Returns a manifest object with raw (unresolved) documentation paths.
+     * Path resolution is handled by PluginRegistry.getDocsMetadata() using the isomorphic resolver.
+     */
+    getDocsMetadata(): DocsManifest | undefined {
+        if (!this.config.docs) {
+            return undefined
+        }
+
+        const manifest: DocsManifest = {}
+
+        for (const doc of this.config.docs) {
+            manifest[doc.apiName] = {
+                docPath: doc.docPath,
+                tags: doc.tags,
+            }
+        }
+
+        return manifest
+    }
+
     getDescendants(parent: Record, database: Database): Record[] {
         const descendantRelationships = Object.entries(this.relationships[parent.getTable()] ?? {}).filter(
             ([, { descendant }]) => descendant
@@ -720,7 +788,7 @@ export class Plugin {
     async nodeToShape(node: SupportedNode, context: Omit<Context, 'self'>): Promise<Result<Shape>> {
         const entry = this.nodeToShapeCache.get(node.compilerNode)
         if (entry) {
-            return entry.isError() ? { success: false } : entry.unwrap()
+            return entry.success ? entry.value : { success: false }
         }
 
         try {
@@ -773,7 +841,7 @@ export class Plugin {
     async shapeToSubclass<const S extends Shape>(shape: S, context: Omit<Context, 'self'>): Promise<Result<S>> {
         const entry = this.shapeToSubclassCache.get(shape)
         if (entry) {
-            return entry.isError() ? { success: false } : (entry.unwrap() as Result<S>)
+            return entry.success ? (entry.value as Result<S>) : { success: false }
         }
 
         try {
@@ -813,7 +881,7 @@ export class Plugin {
     async shapeToRecord(shape: Shape, context: Omit<Context, 'self'>): Promise<Result<Record>> {
         const entry = this.shapeToRecordCache.get(shape)
         if (entry) {
-            return entry.isError() ? { success: false } : entry.unwrap()
+            return entry.success ? entry.value : { success: false }
         }
 
         try {
@@ -910,6 +978,8 @@ export class Plugin {
                     continue
                 }
 
+                context.logger.debug(`Database contains ${database.query().length} records for transformation.`)
+
                 context.logger.debug(
                     `Transforming record into shape: ${record.getTable()}.${record.getId().getValue()}`
                 )
@@ -943,12 +1013,34 @@ export class Plugin {
                     descendants: nonDeletedDescendants,
                 })
 
+                // Track unhandled records to avoid marking them as handled
+                const unhandledRecords: Record[] = []
+                const unhandledRecordIds: string[] = []
+
+                if (result.success === 'partial') {
+                    for (const unhandledRecord of result.unhandledRecords) {
+                        unhandledRecords.push(unhandledRecord)
+                        unhandledRecordIds.push(unhandledRecord.getId().getValue())
+                    }
+                }
+
                 if (result.success) {
                     success = true
                     handledRecords.insert(record)
                     shapes.push(...[result.value].flat())
+
+                    // Mark all descendants as handled
                     for (const descendant of [...deletedDescendants, ...nonDeletedDescendants]) {
-                        handledRecords.insert(descendant)
+                        if (!unhandledRecordIds.includes(descendant.getId().getValue())) {
+                            handledRecords.insert(descendant)
+                        }
+                    }
+                    context.logger.debug(
+                        `Plugin ${this.getName()} deferred handling of records: ${unhandledRecords.map((r) => r.getTable() + '_' + r.getId().getValue()).join(', ')}`
+                    )
+
+                    if (unhandledRecords.length > 0) {
+                        return { success: 'partial', value: shapes, unhandledRecords }
                     }
                 }
             }
@@ -998,10 +1090,15 @@ export class Plugin {
                     ...[incoming.resolve(record.getId())].filter((r) => r !== undefined),
                     ...incoming.query().filter((r) => descendantsDatabase.resolve(r.getId()) !== undefined),
                 ]
-                const result = await diff.bind(this)(new Database(existingTree), new Database(incomingTree), {
-                    ...context,
-                    self: this,
-                })
+                const result = await diff.bind(this)(
+                    new Database(existingTree),
+                    new Database(incomingTree),
+                    new Database(descendants),
+                    {
+                        ...context,
+                        self: this,
+                    }
+                )
 
                 if (result.success) {
                     changedRecords.push(...result.value.query())
@@ -1245,4 +1342,14 @@ export class Plugins {
 
         return false
     }
+
+    getDocsMetadata(): DocsManifest {
+        return this.plugins.reduce((aggregated, plugin) => {
+            const pluginManifest = plugin.getDocsMetadata()
+            if (pluginManifest) {
+                Object.assign(aggregated, pluginManifest)
+            }
+            return aggregated
+        }, {} as DocsManifest)
+    }
 }

package/src/plugins/shape.ts

@@ -366,6 +366,10 @@ export class UndefinedShape extends Shape<undefined> {
     override toString(): StringShape {
         return Shape.from(this, '').asString()
     }
+
+    override getCode(): string {
+        return 'undefined'
+    }
 }
 
 export class DeletedShape extends UndefinedShape {}
@@ -473,6 +477,25 @@ export class PropertyAccessShape extends ResolvableShape {
     override getCode(): string {
         return this.elements.map((e) => e.getCode()).join('.')
     }
+
+    /**
+     * Override equals to compare property access paths instead of resolved values.
+     * This is important for datapill references where we need to compare the actual
+     * property paths (e.g., params.trigger.table_name vs params.trigger.current.user_name)
+     * rather than their resolved values (which would both be UnresolvedShape).
+     */
+    override equals(other: unknown): boolean {
+        if (other instanceof PropertyAccessShape) {
+            // Compare the property access paths element by element
+            const otherElements = other.getElements()
+            if (this.elements.length !== otherElements.length) {
+                return false
+            }
+            return this.elements.every((el, i) => el.getName() === otherElements[i]?.getName())
+        }
+        // Fall back to default behavior for non-PropertyAccessShape comparisons
+        return super.equals(other)
+    }
 }
 
 type StringContentType = 'plain' | 'cdata'
@@ -800,7 +823,7 @@ const coerceTo = (coerceToType: 'string' | 'number' | 'boolean' | 'cdata', value
     }
 }
 
-class Transform {
+export class ShapeTransform {
     constructor(
         private readonly shape: ObjectShape,
         private readonly resolve = true,
@@ -844,35 +867,35 @@ class Transform {
     }
 
     from(...properties: [string, ...string[]]) {
-        return new Transform(this.shape, this.resolve, properties, this._map, this._def, this._coerce)
+        return new ShapeTransform(this.shape, this.resolve, properties, this._map, this._def, this._coerce)
     }
 
     map(mapFunction: (...from: Shape[]) => unknown) {
-        return new Transform(this.shape, this.resolve, this._from, mapFunction, this._def, this._coerce)
+        return new ShapeTransform(this.shape, this.resolve, this._from, mapFunction, this._def, this._coerce)
     }
 
     val(value: unknown) {
-        return new Transform(this.shape, this.resolve, this._from, () => value, this._def, this._coerce)
+        return new ShapeTransform(this.shape, this.resolve, this._from, () => value, this._def, this._coerce)
     }
 
     def(value: unknown) {
-        return new Transform(this.shape, this.resolve, this._from, this._map, value, this._coerce)
+        return new ShapeTransform(this.shape, this.resolve, this._from, this._map, value, this._coerce)
     }
 
     toCdata() {
-        return new Transform(this.shape, this.resolve, this._from, this._map, this._def, 'cdata')
+        return new ShapeTransform(this.shape, this.resolve, this._from, this._map, this._def, 'cdata')
     }
 
     toString() {
-        return new Transform(this.shape, this.resolve, this._from, this._map, this._def, 'string')
+        return new ShapeTransform(this.shape, this.resolve, this._from, this._map, this._def, 'string')
     }
 
     toNumber() {
-        return new Transform(this.shape, this.resolve, this._from, this._map, this._def, 'number')
+        return new ShapeTransform(this.shape, this.resolve, this._from, this._map, this._def, 'number')
     }
 
     toBoolean() {
-        return new Transform(this.shape, this.resolve, this._from, this._map, this._def, 'boolean')
+        return new ShapeTransform(this.shape, this.resolve, this._from, this._map, this._def, 'boolean')
     }
 }
 
@@ -936,26 +959,37 @@ export class ObjectShape extends Shape<globalThis.Record<string, unknown>> {
         nonDefaultsOnly = false,
         resolve = true,
     }: ObjectPropertyOptions = {}): globalThis.Record<string, Shape> {
+        const result: globalThis.Record<string, Shape> = {}
+
         if (nonDefaultsOnly) {
-            const entries = Object.entries(this.setProperties).filter(
-                ([k, v]) => v.isDefined() && !v.equals(this.getDefault(k))
-            )
+            // Only include properties that differ from defaults
+            for (const k in this.setProperties) {
+                const v = this.setProperties[k]
+                if (v && v.isDefined() && !v.equals(this.getDefault(k))) {
+                    result[k] = resolve && v.isResolvable() ? v.resolve() : v
+                }
+            }
+            return result
+        }
 
-            return Object.fromEntries(
-                resolve ? entries.map(([k, v]) => [k, v.isResolvable() ? v.resolve() : v]) : entries
-            )
+        // Iterate set properties first to preserve ordering
+        for (const k in this.setProperties) {
+            const v = this.setProperties[k]
+            if (v) {
+                result[k] = resolve && v.isResolvable() ? v.resolve() : v
+            }
         }
 
-        // This logic may seem odd, but it's written this way to preserve the ordering of
-        // the set properties instead of using the ordering of the defaults.
-        const entries = [
-            ...Object.entries(this.setProperties),
-            ...Object.entries(this.defaultProperties).filter(
-                ([k]) => !this.setProperties[k] || this.setProperties[k].isUndefined()
-            ),
-        ]
+        for (const k in this.defaultProperties) {
+            if (!this.setProperties[k] || this.setProperties[k].isUndefined()) {
+                const v = this.defaultProperties[k]
+                if (v) {
+                    result[k] = resolve && v.isResolvable() ? v.resolve() : v
+                }
+            }
+        }
 
-        return Object.fromEntries(resolve ? entries.map(([k, v]) => [k, v.isResolvable() ? v.resolve() : v]) : entries)
+        return result
     }
 
     override getValue(nonDefaultsOnly = false): globalThis.Record<string, unknown> {
@@ -966,8 +1000,8 @@ export class ObjectShape extends Shape<globalThis.Record<string, unknown>> {
         const [property, next, ...rest] = typeof propertyOrPath === 'string' ? [propertyOrPath] : propertyOrPath
         const propertyAliases = [property, ...this.getAliases(property)]
         const properties = this.properties({ resolve })
-        const match = propertyAliases.find((p) => properties[p])
-        const value = match ? properties[match] : undefined
+        const match = propertyAliases.find((p) => p in properties)
+        const value = match !== undefined ? properties[match] : undefined
         return (
             (next ? value?.ifObject()?.get([next, ...rest], resolve) : value) ??
             new UndefinedShape({ source: this.getSource() })
@@ -1035,15 +1069,15 @@ export class ObjectShape extends Shape<globalThis.Record<string, unknown>> {
     }
 
     transform(
-        schema: (utils: { $: Transform; merge: typeof MERGE }) => {
-            [P in string | typeof MERGE]?: Transform
+        schema: (utils: { $: ShapeTransform; merge: typeof MERGE }) => {
+            [P in string | typeof MERGE]?: ShapeTransform
         },
         resolve = true
     ) {
         const properties = {}
         const defaults = {}
 
-        const definedSchema = schema({ merge: MERGE, $: new Transform(this, resolve) })
+        const definedSchema = schema({ merge: MERGE, $: new ShapeTransform(this, resolve) })
         for (const to of [...Object.keys(definedSchema), MERGE] as const) {
             if (definedSchema[to]) {
                 const result = definedSchema[to]._(to)
@@ -1099,7 +1133,7 @@ export class ObjectShape extends Shape<globalThis.Record<string, unknown>> {
                 } else if (a[key]?.equals(value)) {
                     // Don't overwrite properties that are equal
                 } else if (a[key]?.isObject() && value.isObject()) {
-                    a[key].merge(value) // Merge objects recursively
+                    a[key] = a[key].merge(value) // Merge objects recursively
                 } else {
                     a[key] = value
                 }