@servicenow/sdk-build-core 2.0.1

package/src/plugins/behaviors/Arranger.ts

@@ -0,0 +1,42 @@
+import { Document, DocumentPointer, LinkedDocument } from './Composer'
+import { Context } from '../Context'
+
+export type Arranged<Status extends 'unresolved' | 'resolved' = 'resolved'> = {
+    parent?: Status extends 'unresolved' ? DocumentPointer & Arranged<'unresolved'> : LinkedDocument & Arranged // Parent is always linked because document trees are processed from top to bottom
+}
+
+// TODO: Use this return type for all behaviors. It solves the ambiguity
+// between `undefined` as a valid return value and `undefined` as an indicator
+// that the input was not handled.
+export type Result<T> =
+    | {
+          handled: false
+          result?: never
+      }
+    | {
+          handled: true
+          result: T
+      }
+
+/**
+ * An arranger function is a function which accepts a document of a known
+ * kind as input and returns a pointer to its parent, if applicable.
+ *
+ * @see {@linkcode Document}
+ * @see {@linkcode DocumentPointer}
+ */
+export type ArrangerFunction<DocumentKind extends string = string> = (
+    document: Document<DocumentKind>,
+    context: Context
+) => Result<DocumentPointer | undefined>
+
+// This is only imported so it can be referenced in the JS doc below
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type { Plugin } from '../Plugin'
+
+/**
+ * @see {@linkcode Plugin#arrangers}
+ */
+export type Arrangers<DocumentKinds extends string = string> = {
+    [K in DocumentKinds]: ArrangerFunction<K>
+}

package/src/plugins/behaviors/Composer.ts

@@ -0,0 +1,124 @@
+import { SupportedNode } from '@servicenow/sdk-project'
+import { XmlData, PrimitiveData, Action, EntityData } from './extractors'
+import { Context } from '../Context'
+
+/**
+ * An unlinked document is a document that does not have an
+ * association with any AST node.
+ *
+ * @see {@linkcode Document}
+ */
+export type UnlinkedDocument<DocumentKind extends string = string> = Omit<Document<DocumentKind>, 'node'>
+
+/**
+ * A linked document is a document that has an association
+ * with an AST node.
+ *
+ * @see {@linkcode Document}
+ */
+export type LinkedDocument<DocumentKind extends string = string, Node extends SupportedNode = SupportedNode> = Document<
+    DocumentKind,
+    Node
+> & {
+    entity?: EntityData
+    node: Node
+}
+
+/**
+ * A document is a data structure that has a known kind, an ID,
+ * and an action (insert/update or delete). It may also have an
+ * associated AST node if the data originated from source code.
+ *
+ * @see {@linkcode LinkedDocument}
+ * @see {@linkcode UnlinkedDocument}
+ */
+export type Document<DocumentKind extends string = string, Node extends SupportedNode = SupportedNode> = {
+    guid: string
+    kind: DocumentKind
+    data: unknown
+    changedData?: unknown
+    xmlData?: unknown
+    node?: Node
+    action?: Action
+}
+
+/**
+ * A document pointer is an object that represents a document
+ * via its ID and kind. Document pointers can be resolved to
+ * actual documents after all documents have been composed.
+ *
+ * @see {@linkcode Document}
+ */
+export type DocumentPointer<DocumentKind extends string = string> = {
+    guid: string
+    kind: DocumentKind
+}
+
+/**
+ * A document map is an object where documents are accessible
+ * by their kind and ID. The keys of the object are document
+ * kinds, and the values are sub-objects where the keys are
+ * document IDs and the values are the corresponding documents.
+ *
+ * @see {@linkcode Document}
+ */
+export type DocumentMap = {
+    [kinds: string]: {
+        [guids: string]: Document
+    }
+}
+
+/**
+ * An entity composer function is a function that accepts a
+ * piece of entity data from the source code and returns one
+ * or more linked documents derived from that entity, or returns
+ * undefined to indicate that it did not handle the data.
+ *
+ * @see {@linkcode Entity}
+ * @see {@linkcode EntityData}
+ */
+export type EntityComposerFunction<Data extends Record<string, unknown> = Record<string, unknown>> = (
+    entityData: EntityData<Data>,
+    context: Context
+) => LinkedDocument | LinkedDocument[] | undefined
+
+/**
+ * An XML composer function is a function that accepts a piece
+ * of data from an XML file and returns one or more unlinked
+ * documents derived from that data, or returns undefined to
+ * indicate that it did not handle the data.
+ *
+ * @see {@linkcode PrimitiveData}
+ * @see {@linkcode XmlData}
+ */
+export type XmlComposerFunction<Data extends PrimitiveData = PrimitiveData> = (
+    xmlData: XmlData<Data>,
+    context: Context
+) => UnlinkedDocument | UnlinkedDocument[] | undefined
+
+// This is only imported so it can be referenced in the JS doc below
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type { Plugin } from '../Plugin'
+
+/**
+ * @see {@linkcode Plugin#composers}
+ */
+export type Composers = {
+    entity?: { [kind: string]: EntityComposerFunction }
+    xml?: { [kind: string]: XmlComposerFunction }
+}
+
+/**
+ * Utility which takes an unlinked document and a node and returns the
+ * same document linked to the provided node.
+ *
+ * @param document The {@linkcode UnlinkedDocument} to link
+ * @param node The AST node to link the document to
+ * @returns A {@linkcode LinkedDocument}
+ */
+export function linkDocument<const K extends string, const N extends SupportedNode>(
+    document: UnlinkedDocument<K>,
+    node: N
+): LinkedDocument<K, N> {
+    return { ...document, node }
+}

package/src/plugins/behaviors/Diagnostics.ts

@@ -0,0 +1,13 @@
+import * as ts from 'ts-morph'
+import { SupportedKindName, SupportedNodeByKindName } from '@servicenow/sdk-project'
+import { Context } from '../Context'
+import { FluentDiagnostic } from '../Diagnostic'
+
+export type DiagnosticsFunction<K extends SupportedKindName | 'Node' = SupportedKindName> = (
+    node: K extends SupportedKindName ? SupportedNodeByKindName<K> : K extends 'Node' ? ts.Node : any,
+    context: Context
+) => FluentDiagnostic[]
+
+export type Diagnostics<NodeKinds extends SupportedKindName | 'Node'> = {
+    [K in NodeKinds]: DiagnosticsFunction<K>
+}

package/src/plugins/behaviors/Generator.ts

@@ -0,0 +1,31 @@
+import { LinkedDocument, UnlinkedDocument } from './Composer'
+import { Arranged } from './Arranger'
+import { Context } from '../Context'
+
+/**
+ * A generator function is a function that accepts an unlinked document of
+ * a known kind as input and returns the same document as a linked document.
+ * In practice, this means the generator's job is to create new AST nodes
+ * for documents that are not linked to any node. Documents without nodes
+ * are usually from XML files containing records that aren't defined in the
+ * source code yet.
+ *
+ * @see {@linkcode UnlinkedDocument}
+ * @see {@linkcode LinkedDocument}
+ */
+export type GeneratorFunction<DocumentKind extends string = string> = (
+    document: UnlinkedDocument<DocumentKind> & Arranged,
+    context: Context,
+    linkedDocuments: LinkedDocument[]
+) => LinkedDocument<DocumentKind> | undefined
+
+// This is only imported so it can be referenced in the JS doc below
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type { Plugin } from '../Plugin'
+
+/**
+ * @see {@linkcode Plugin#generators}
+ */
+export type Generators<DocumentKinds extends string = string> = {
+    [K in DocumentKinds]: GeneratorFunction<K>
+}

package/src/plugins/behaviors/OwnedTables.ts

@@ -0,0 +1,5 @@
+import { Diagnostic } from '@servicenow/sdk-project'
+
+export type TableOwnership = {
+    [table: string]: { diagnosticLevel: Diagnostic.Level }
+}

package/src/plugins/behaviors/PostProcessor.ts

@@ -0,0 +1,6 @@
+import { Context } from '../Context'
+import { EntityData } from './extractors'
+
+export type PostProcessors = {
+    entities?: (entities: EntityData[], context: Context) => void
+}

package/src/plugins/behaviors/Serializer.ts

@@ -0,0 +1,39 @@
+import { Document } from './Composer'
+import { Arranged } from './Arranger'
+import { Context } from '../Context'
+
+/**
+ * A file is a data structure with a name, a target directory, and content
+ * as a string. The target directory must be the name of one of the magic
+ * directories that exist within a ServiceNow deployable app package.
+ */
+export type File = {
+    name: `${string}.xml`
+    directory: 'dictionary' | 'unload' | 'unload.demo' | 'update' | 'apply_once' | ''
+    content: string
+}
+
+/**
+ * A serializer function is a function which accepts a document of a known
+ * kind as input and returns one or more files derived from that document,
+ * or returns undefined to indicate it did not handle the document. In practice,
+ * this means generating the XML content that the build system will write to
+ * the filesystem during the final stages of a build.
+ *
+ * @see {@linkcode Document}
+ */
+export type SerializerFunction<DocumentKind extends string = string> = (
+    document: Document<DocumentKind> & Arranged,
+    context: Context
+) => File | File[] | undefined
+
+// This is only imported so it can be referenced in the JS doc below
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type { Plugin } from '../Plugin'
+
+/**
+ * @see {@linkcode Plugin#serializers}
+ */
+export type Serializers<DocumentKinds extends string = string> = {
+    [K in DocumentKinds]: SerializerFunction<K>
+}

package/src/plugins/behaviors/Transformer.ts

@@ -0,0 +1,32 @@
+import { SupportedKindName, SupportedNode, SupportedNodeByKindName } from '@servicenow/sdk-project'
+import { LinkedDocument } from './Composer'
+import { Arranged } from './Arranger'
+import { Context } from '../Context'
+
+/**
+ * A transformer function is a function which accepts a linked document of
+ * a known kind as input and returns a boolean indicating whether or not it
+ * handled the document. The implementation of a transformer function, if it
+ * chooses to handle the document, should perform the necessary transformations
+ * on the document's linked node to ensure the document's data is fully
+ * represented in the source code.
+ *
+ * @see {@linkcode LinkedDocument}
+ */
+export type TransformerFunction<DocumentKind extends string = string, Node extends SupportedNode = SupportedNode> = (
+    document: LinkedDocument<DocumentKind, Node> & Arranged,
+    context: Context
+) => boolean
+
+// This is only imported so it can be referenced in the JS doc below
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type { Plugin } from '../Plugin'
+
+/**
+ * @see {@linkcode Plugin#transformers}
+ */
+export type Transformers<DocumentKinds extends string = string> = {
+    [DK in DocumentKinds]: {
+        [NK in SupportedKindName]?: TransformerFunction<DK, SupportedNodeByKindName<NK>>
+    }
+}

package/src/plugins/behaviors/extractors/Data.ts

@@ -0,0 +1,247 @@
+import { SupportedNode } from '@servicenow/sdk-project'
+
+/**
+ * Actions indicate what should take place in the database when the XML file
+ * is loaded. The platform understands these three actions: insert/update,
+ * delete, and delete multiple.
+ */
+export type Action = 'INSERT_OR_UPDATE' | 'DELETE' | 'delete_multiple'
+
+/**
+ * Utility type for data passed to XML extractors for processing.
+ */
+export type Xml = {
+    filePath: string
+    data: any
+}
+
+/**
+ * Utility type to represent a simple object structure with primitive values.
+ */
+export type PrimitiveData = {
+    [x: string]: PrimitiveData | PrimitiveData[] | string | number | boolean | undefined
+}
+
+/**
+ * XML data is data from XML files (such as the parsed content of a record_update)
+ * which is not associated with any AST node.
+ */
+export class XmlData<D extends PrimitiveData = PrimitiveData> {
+    constructor(
+        public data: D,
+        readonly filePath: string,
+        readonly kind: string,
+        readonly action: Action = 'INSERT_OR_UPDATE'
+    ) {}
+}
+
+export type WrappedData<D> = {
+    [K in keyof D]: D[K] extends string
+        ? StringData<D[K]>
+        : D[K] extends number
+          ? NumberData<D[K]>
+          : D[K] extends boolean
+            ? BooleanData<D[K]>
+            : D[K] extends Array<unknown>
+              ? ArrayData<D[K]>
+              : D[K] extends Record<string, unknown>
+                ? ObjectData<D[K]>
+                : Data<D[K]>
+}
+
+export abstract class Data<D = unknown> {
+    constructor(private readonly node: SupportedNode) {}
+
+    /**
+     * @deprecated Using this for an array or object is bad practice because all of the elements/properties
+     * will be assigned the same node as the array/object itself. This makes it difficult to bidrectionally
+     * sync data created this way because you don't have the granularity required to know where each of the
+     * element/property values (and any nested values) came from.
+     */
+    static fromValue<const D>(value: D, node: SupportedNode): Data<D> {
+        if (value === undefined || value === null) {
+            return new UndefinedData(node) as Data<D> // TODO: How can we avoid this silly cast?
+        } else if (typeof value === 'string') {
+            return new StringData(value, node)
+        } else if (typeof value === 'number') {
+            return new NumberData(value, node)
+        } else if (typeof value === 'boolean') {
+            return new BooleanData(value, node)
+        } else if (Array.isArray(value)) {
+            return ArrayData.fromArrayValue(value, node)
+        } else if (!!value && typeof value === 'object') {
+            const obj = Object.fromEntries(Object.entries(value).filter(([key]) => typeof key === 'string'))
+            return ObjectData.fromObjectValue(obj as typeof obj & D, node)
+        } else {
+            throw new Error(
+                `Unsupported data type: ${value} (Type: ${typeof value}, Class: ${value?.constructor?.name})`
+            )
+        }
+    }
+
+    static isUndefined(data?: Data): data is UndefinedData {
+        return data instanceof UndefinedData
+    }
+
+    static isString(data?: Data): data is StringData {
+        return data instanceof StringData
+    }
+
+    static isNumber(data?: Data): data is NumberData {
+        return data instanceof NumberData
+    }
+
+    static isBoolean(data?: Data): data is BooleanData {
+        return data instanceof BooleanData
+    }
+
+    static isArray(data?: Data): data is ArrayData {
+        return data instanceof ArrayData
+    }
+
+    static isObject(data?: Data): data is ObjectData {
+        return data instanceof ObjectData
+    }
+
+    static isEntity(data?: Data): data is EntityData {
+        return data instanceof EntityData
+    }
+
+    abstract getValue(): D
+
+    getNode() {
+        return this.node
+    }
+}
+
+export class UndefinedData extends Data<undefined> {
+    constructor(node: SupportedNode) {
+        super(node)
+    }
+
+    getValue() {
+        return undefined
+    }
+}
+
+export class StringData<const D extends string = string> extends Data<D> {
+    constructor(
+        private readonly value: D,
+        node: SupportedNode
+    ) {
+        super(node)
+    }
+
+    getValue() {
+        return this.value
+    }
+}
+
+export class NumberData<const D extends number = number> extends Data<D> {
+    constructor(
+        private readonly value: D,
+        node: SupportedNode
+    ) {
+        super(node)
+    }
+
+    getValue() {
+        return this.value
+    }
+}
+
+export class BooleanData<const D extends boolean = boolean> extends Data<D> {
+    constructor(
+        private readonly value: D,
+        node: SupportedNode
+    ) {
+        super(node)
+    }
+
+    getValue() {
+        return this.value
+    }
+}
+
+export class ArrayData<const D extends unknown[] = unknown[]> extends Data<D> {
+    constructor(
+        private readonly elements: WrappedData<D>,
+        node: SupportedNode
+    ) {
+        super(node)
+    }
+
+    /**
+     * @deprecated Using this for arrays is bad practice because all of the array elements will be
+     * assigned the same node as the array itself. This makes it difficult to bidrectionally sync
+     * data created this way because you don't have the granularity required to know where each of
+     * the element values (and any nested values) came from.
+     */
+    static fromArrayValue<const D extends unknown[]>(value: D, node: SupportedNode): ArrayData<D> {
+        const elements = value.map((value) => Data.fromValue(value, node)) as WrappedData<D>
+
+        return new ArrayData(elements, node)
+    }
+
+    getValue() {
+        return this.elements.map((element) => element.getValue()) as D
+    }
+
+    getElements() {
+        return this.elements
+    }
+}
+
+export class ObjectData<const D extends Record<string, unknown> = Record<string, unknown>> extends Data<D> {
+    constructor(
+        private readonly properties: WrappedData<D>,
+        node: SupportedNode
+    ) {
+        super(node)
+    }
+
+    /**
+     * @deprecated Using this for objects is bad practice because all of the object properties will
+     * be assigned the same node as the object itself. This makes it difficult to bidrectionally sync
+     * data created this way because you don't have the granularity required to know where each of
+     * the property values (and any nested values) came from.
+     */
+    static fromObjectValue<const D extends Record<string, unknown>>(value: D, node: SupportedNode): ObjectData<D> {
+        const properties = Object.fromEntries(
+            Object.entries(value).map(([key, value]) => [key, Data.fromValue(value, node)])
+        ) as WrappedData<D>
+
+        return new ObjectData(properties, node)
+    }
+
+    getValue() {
+        return Object.fromEntries(Object.entries(this.properties).map(([key, value]) => [key, value.getValue()])) as D
+    }
+
+    getProperty<const K extends keyof D>(name: K) {
+        return this.properties[name]
+    }
+
+    getProperties() {
+        return this.properties
+    }
+}
+
+export class EntityData<const D extends Record<string, unknown> = Record<string, unknown>> extends ObjectData<D> {
+    constructor(
+        private readonly kind: string,
+        private readonly guid: string,
+        entity: ObjectData<D>,
+        node: SupportedNode
+    ) {
+        super(entity.getProperties(), node)
+    }
+
+    getKind() {
+        return this.kind
+    }
+
+    getGuid() {
+        return this.guid
+    }
+}

package/src/plugins/behaviors/extractors/Extractors.ts

@@ -0,0 +1,57 @@
+import { SupportedKindName, SupportedNodeByKindName } from '@servicenow/sdk-project'
+import { Data, EntityData, Xml, XmlData } from './Data'
+import { Context } from '../../Context'
+import { FluentDiagnostic } from '../../Diagnostic'
+
+export type ExtractionResult<D extends Data = Data> =
+    | {
+          handled: false
+      }
+    | {
+          handled: true
+          data: D[]
+          diagnostics: FluentDiagnostic[]
+      }
+
+/**
+ * An XML extractor function accepts an {@linkcode Xml} object and returns one or
+ * more pieces of {@linkcode XmlData} extracted from that object. The function may
+ * also return undefined to indicate that it did not handle the object.
+ */
+export type XmlExtractorFunction = (xml: Xml, context: Context) => XmlData | XmlData[] | undefined
+
+/**
+ * A raw extractor function accepts an AST node and returns one or more pieces of
+ * {@linkcode Data} extracted from that node which cannot be composed into documents
+ * on their own but could be part of an entity.
+ */
+export type RawExtractorFunction<N extends SupportedKindName | 'any' = SupportedKindName> = (
+    node: N extends SupportedKindName ? SupportedNodeByKindName<N> : any,
+    context: Context
+) => ExtractionResult<Data>
+
+/**
+ * An entity extractor function accepts an AST node and returns one or more pieces
+ * of {@linkcode EntityData} extracted from that node which can then be composed
+ * into documents.
+ */
+export type EntityExtractorFunction<N extends SupportedKindName | 'any' = SupportedKindName> = (
+    node: N extends SupportedKindName ? SupportedNodeByKindName<N> : any,
+    context: Context
+) => ExtractionResult<EntityData>
+
+// This is only imported so it can be referenced in the JS doc below
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type { Plugin } from '../../Plugin'
+
+/**
+ * @see {@linkcode Plugin#extractors}
+ */
+export type Extractors<
+    RawNodeKinds extends SupportedKindName | 'any',
+    EntityNodeKinds extends SupportedKindName | 'any',
+> = {
+    xml?: XmlExtractorFunction
+    raw?: { [K in RawNodeKinds]: RawExtractorFunction<K> }
+    entity?: { [K in EntityNodeKinds]: EntityExtractorFunction<K> }
+}

package/src/plugins/behaviors/extractors/index.ts

@@ -0,0 +1,2 @@
+export * from './Extractors'
+export * from './Data'

package/src/plugins/behaviors/index.ts

@@ -0,0 +1,9 @@
+export * from './extractors'
+export * from './Composer'
+export * from './Arranger'
+export * from './Serializer'
+export * from './Generator'
+export * from './Transformer'
+export * from './PostProcessor'
+export * from './Diagnostics'
+export * from './OwnedTables'

package/src/plugins/index.ts

@@ -0,0 +1,5 @@
+export { Plugin } from './Plugin'
+export { type Context, type HandledStates } from './Context'
+export * from './behaviors'
+export * from './util'
+export * from './Diagnostic'