@servicenow/sdk-build-core 2.0.1

package/src/plugins/util/ConfigurationFunction.ts

@@ -0,0 +1,477 @@
+import { Logger } from '@servicenow/sdk-project'
+import {
+    ArrowFunction,
+    CallExpression,
+    FunctionExpression,
+    Identifier,
+    Node,
+    ObjectLiteralExpression,
+    PropertyAccessExpression,
+    PropertyAssignment,
+    SyntaxKind,
+    TemplateExpression,
+    ts,
+} from 'ts-morph'
+import { Context } from '../Context'
+import { EntityData, ObjectData } from '../behaviors'
+import { getCallExpressionName } from './CallExpression'
+
+export type ConfigEntity = {
+    inputObject: InputObject
+    configEntries: ConfigEntries
+}
+
+export type InputObject = {
+    $id: string | number
+    [name: string]: any
+}
+
+export type ConfigEntries = {
+    [index: `${number}`]: ConfigEntry
+}
+
+export type ConfigEntry = {
+    name: string
+    info: { [name: string]: any }
+}
+
+export type ComposerClass = {
+    prototype: any
+    [key: string]: any
+}
+
+// TODO: Just created this to avoid refactoring all of the ATF stuff. Should be removed
+// and the EntityData class should be used instead, if possible.
+export class ConfigurationFunctionEntityData extends EntityData {
+    constructor(
+        private readonly config: ConfigEntity,
+        node: CallExpression
+    ) {
+        super(
+            'test',
+            'NO_GUID_GENERATED', // TODO: Generate GUID?
+            new ObjectData({}, node),
+            node
+        )
+    }
+
+    override getValue() {
+        return this.config
+    }
+}
+
+/**
+ * This is an extractor used to extract configuration functions.
+ * This is an example of a configuration function:
+ * ```typescript
+ * import { table } from 'place'
+ * PlaceHolderFunction('Unique ID', (param) => {
+ *  param.foo({arg1: 'hey', arg2: table});
+ *  const output = param.bar({placeholder: 'value'});
+ *  param.baz({arg1: output.value1})
+ * })
+ * ```
+ */
+export class ConfigurationFunctionExtractor {
+    private rootNode: CallExpression
+    private context: Context
+    private composerClass: ComposerClass
+    private identifiers: (Identifier | null)[]
+
+    /**
+     *
+     * @param rootNode rootNode of AST where extraction begins
+     * @param context context from the plugin this is called in
+     * @param composerClass A class whose prototype will be used to validate the allowed functions within the configuration function
+     */
+    constructor(rootNode: CallExpression, context: Context, composerClass: ComposerClass) {
+        this.rootNode = rootNode
+        this.context = context
+        this.composerClass = composerClass
+        this.identifiers = []
+    }
+
+    /**
+     * Grabs the property access expression chain of a call expression, and protects against accidentally grabbing property access expressions in arguments of the call expression
+     */
+    private getPropChain(ce: CallExpression): PropertyAccessExpression[] {
+        // Do this to ensure we are only considering property access expressions that are apart of the chain and not potentially in the arguments of the function
+        const props = [ce.getFirstDescendantByKindOrThrow(SyntaxKind.PropertyAccessExpression)]
+        const childProps = (props[0] as PropertyAccessExpression).getDescendantsOfKind(
+            SyntaxKind.PropertyAccessExpression
+        )
+        if (childProps.length > 0) {
+            props.push(...childProps)
+        }
+        return props
+    }
+
+    /**
+     * Returns the first element of a property access chain
+     *   v
+     *   a.b.c.d({})
+     */
+    private getFirstProp(ce: CallExpression): Identifier {
+        // Need to use this instead of just grabbing descendents cause the arguments of the call expression can also potentially have property access expressions which we don't want to consider
+        const props = this.getPropChain(ce)
+        if (props.length === 1) {
+            const ids = props[0]?.getChildrenOfKind(SyntaxKind.Identifier) as Identifier[]
+            return ids[0] as Identifier
+        }
+        const lastProp = props[props.length - 1] as PropertyAccessExpression
+        return lastProp.getChildrenOfKind(SyntaxKind.Identifier)[0] as Identifier
+    }
+
+    /**
+     * Returns the last element of a property access chain
+     *
+     *         v
+     *   a.b.c.d({})
+     */
+    private getLastProp(ce: CallExpression): Identifier {
+        // Do not need special chain handling here like in getFirstProp cause we are always grabbing the property access expression from the top level regardless of chain length
+        const props = ce.getFirstDescendantByKindOrThrow(SyntaxKind.PropertyAccessExpression)
+        const ids = props.getChildrenOfKind(SyntaxKind.Identifier) as Identifier[]
+        return ids[ids.length - 1] as Identifier // Identifier is either the only one present or is the last of 2 so this should fetch it in either scenario
+    }
+
+    /**
+     * Validates that a call expression is valid. Will error if the call expression is inappropriately constructed for the configuration function
+     * @param ce
+     * @param parameterName
+     */
+    private isValidCallExpression(ce: CallExpression, paramId: Identifier) {
+        if (!paramId) {
+            throw Error('No parameter provided to configuration function')
+        }
+
+        // Ensure the line of the function call starts with the argument of the configuration function
+        const firstId = this.getFirstProp(ce)
+
+        if (firstId?.getText() !== paramId?.getText()) {
+            throw Error(
+                `Call expression does not begin with "${paramId.getText()}", instead began with "${firstId.getText()}"`
+            )
+        }
+
+        // Verify that the function call is actually a valid function call based on the composer class this will be used with
+        const lastId = this.getLastProp(ce)
+        const functionName = lastId.getText()
+        const nameIsValid = Object.getOwnPropertyNames(this.composerClass.prototype).some((funcName) => {
+            return funcName != 'constructor' && functionName.startsWith(funcName)
+        })
+        if (!nameIsValid) {
+            throw Error(`Call expression function does not exist on the object ${paramId.getText()}`)
+        }
+
+        // Verify that call expression has the expected number of arguments
+        const funcArgs = ce.getFirstDescendantByKind(SyntaxKind.SyntaxList)?.getChildren() as Node[]
+        if (!funcArgs) {
+            throw Error('Call expression had no arguments at all')
+        }
+
+        if (funcArgs.length != 1) {
+            throw Error('Call expressions only support a single argument')
+        }
+
+        if ((funcArgs[0] as Node).getKind() != SyntaxKind.ObjectLiteralExpression) {
+            throw Error('Call expression must have an object as its argument')
+        }
+    }
+
+    /**
+     * Returns the step number of the step containing a identifier which matches the type of the queried identfier
+     *
+     * If it cannot find the identifier, it returns -1
+     * @param identifier
+     * @param data
+     */
+    private findReferencedIdentifier(identifier: Identifier) {
+        const idName = identifier.getSymbol()?.getName()
+        // Identifier index lines up with step index, removed from step object so identifiers are not returned in extracted object
+        for (let i = 0; i < this.identifiers.length; i++) {
+            const identifier = this.identifiers[i]
+            // Maybe there's another way to more accurately identify but this should be fine?
+            const name = identifier?.getSymbol()?.getName()
+            if (name && idName && name == idName) {
+                return i
+            }
+        }
+        return -1
+    }
+
+    private getRootIdentifier(prop: PropertyAccessExpression): Identifier {
+        const children = prop.getChildrenOfKind(SyntaxKind.PropertyAccessExpression)
+        if (children.length == 0) {
+            const id = prop.getFirstChildByKind(SyntaxKind.Identifier)
+            if (!id) {
+                throw Error('Could not find identifier in property access expression')
+            }
+            return id
+        }
+        return this.getRootIdentifier(children[0] as PropertyAccessExpression)
+    }
+
+    private parseValue(valueNode: Node): any {
+        if (valueNode.getKind() == SyntaxKind.ArrayLiteralExpression) {
+            const values: any[] = []
+            const syntaxList = valueNode.getFirstDescendantByKind(SyntaxKind.SyntaxList)
+            if (!syntaxList) {
+                return
+            }
+            const children = syntaxList.getChildren()
+
+            for (const child of children) {
+                if (child.getKind() == SyntaxKind.CommaToken) {
+                    continue
+                }
+                const value = this.parseValue(child)
+                values.push(value)
+            }
+            return values
+        }
+
+        if (valueNode.getKind() == SyntaxKind.ObjectLiteralExpression) {
+            const objNode = valueNode as ObjectLiteralExpression
+            return this.objNodeToJSON(objNode)
+        }
+
+        if (valueNode.getKind() == SyntaxKind.PropertyAccessExpression) {
+            const propNode = valueNode as PropertyAccessExpression
+            const identifier = this.getRootIdentifier(propNode)
+            const refIdentifierIndex = this.findReferencedIdentifier(identifier)
+            if (refIdentifierIndex == -1) {
+                throw Error('Step corresponding to property access expression could not be found')
+            }
+
+            const parsedValue = valueNode.getText().split('.')
+            // Replace it just with a string here. Parsing into a real value will happen in the composer
+            return { __references: refIdentifierIndex, __value: parsedValue[parsedValue.length - 1] }
+        }
+
+        if (valueNode.getKind() == SyntaxKind.TemplateExpression) {
+            // console.info(`literal: ${(valueNode as TemplateExpression).getVal}`)
+            const templateNode = valueNode as TemplateExpression
+            const templateValue = [templateNode.getHead().getLiteralText()]
+            templateNode.getTemplateSpans().forEach((s) => {
+                templateValue.push(this.parseValue(s.getExpression()))
+                templateValue.push(s.getLiteral().getLiteralText())
+            })
+            return { __template: templateValue }
+        }
+
+        // A variety of Identifiers. Will be handled here
+        // TODO: This is swallowing diagnostics and not handling the case where no data was extracted
+        return this.context.extractAst(valueNode)['data'][0]?.getValue()
+    }
+
+    private getKVPair(prop: PropertyAssignment) {
+        const props = prop.getChildren()
+        const keyNode = props[0] as Node<ts.Node>
+        const valueNode = props[2] as Node<ts.Node>
+
+        const key = (keyNode as any).getLiteralValue ? (keyNode as any).getLiteralValue() : keyNode.getText()
+        const value = this.parseValue(valueNode)
+
+        if (typeof key !== 'undefined' && typeof value !== 'undefined') {
+            return { key, value }
+        }
+        return { key: undefined, value: undefined }
+    }
+
+    private objNodeToJSON(obj: ObjectLiteralExpression | undefined): { [name: string]: any } {
+        if (!obj) {
+            throw Error('objNodeToJSON received an undefined object node')
+        }
+        const syntaxList = obj.getFirstDescendantByKind(SyntaxKind.SyntaxList)
+
+        if (!syntaxList) {
+            throw Error('objNodeToJSON could not find a syntax list in the ObjectLiteralExpression')
+        }
+
+        const json = {}
+        syntaxList.getChildrenOfKind(SyntaxKind.PropertyAssignment).forEach((arg) => {
+            const propArg = arg
+            const { key, value } = this.getKVPair(propArg)
+            // TODO: What if the value is actually undefined?
+            if (key !== undefined && value !== undefined) {
+                json[key] = value
+            }
+        })
+        return json
+    }
+
+    private getName(node: CallExpression) {
+        // This may not be robust but should be a good enough
+        const lastProp = this.getLastProp(node)
+        return lastProp.getText()
+    }
+
+    private getConfigFunctionComponents(kind: string, node: CallExpression<ts.CallExpression>) {
+        kind
+        const configArgs = node.getArguments()
+        if (configArgs.length != 2) {
+            throw Error('The plugin must have exactly 2 arguments')
+        }
+
+        if ((configArgs[0] as any).getKind() != SyntaxKind.ObjectLiteralExpression) {
+            throw Error("The plugin's first argument was not an object")
+        }
+
+        if (
+            (configArgs[1] as any).getKind() != SyntaxKind.ArrowFunction &&
+            (configArgs[1] as any).getKind() != SyntaxKind.FunctionExpression
+        ) {
+            throw Error("The plugin's second argument was not a function")
+        }
+
+        const objectArg = configArgs[0] as ObjectLiteralExpression
+        const configFunction = configArgs[1] as ArrowFunction | FunctionExpression
+
+        // TODO: This is swallowing diagnostics and not handling the case where no data was extracted
+        const objectArgValue = this.context.extractAst(objectArg!)['data'][0]?.getValue()
+
+        if (!('$id' in objectArgValue)) {
+            throw Error('No $id defined in first argument')
+        }
+
+        const parameters = configFunction.getParameters()
+        // Checking the type is parameter is probably redundant but can not hurt
+        if (parameters.length != 1 || !parameters[0] || parameters[0].getKind() != SyntaxKind.Parameter) {
+            throw Error('Configuration function must have an parameter as its only argument')
+        }
+
+        const paramId = parameters[0].getChildrenOfKind(SyntaxKind.Identifier)[0] as Identifier
+        const block = configFunction.getFirstChildByKind(SyntaxKind.Block)
+        if (!block) {
+            throw Error(`Failed to find block in configuration function`)
+        }
+
+        const syntaxList = block.getFirstChildByKind(SyntaxKind.SyntaxList)
+        if (!syntaxList) {
+            throw Error(`Failed to find syntax list in configuration function`)
+        }
+        return { paramId, syntaxList, objectArgValue }
+    }
+
+    private extractCallExpression(node: Node, paramId: Identifier) {
+        const callExpressions = node.getDescendantsOfKind(SyntaxKind.CallExpression)
+
+        if (callExpressions.length == 0) {
+            throw Error(`Expression statement did not have any call expression`)
+        }
+
+        if (callExpressions.length > 1) {
+            throw Error(`Found more than one call expression inside of an expression statement`)
+        }
+
+        const callExpression = callExpressions[0] as CallExpression
+        this.isValidCallExpression(callExpression, paramId)
+        return callExpression
+    }
+
+    extractConfigFunction(
+        kind: string, // Name of function for now
+        logger: Logger
+    ): EntityData | undefined {
+        try {
+            return this.extractConfigFunctionUnsafe(kind, logger)
+        } catch (e) {
+            console.error('Could not extract configuration function: ', e)
+            // swallows error, maybe fully re-echo but probably should just swallow silently to behave as expected
+            return undefined
+        }
+    }
+
+    /**
+     * Returns a single entity of the kind specified which contains all data of nodes within the configuration function
+     *
+     * Will attempt to generalize this for use by flow team
+     * @param kind
+     * @param node
+     * @param context
+     * @returns
+     */
+    extractConfigFunctionUnsafe(
+        kind: string, // Name of function for now,
+        logger: Logger
+    ): EntityData | undefined {
+        // If this node is not the correct kind, return undefined. Some other extractor will handle it
+        const name = getCallExpressionName(this.rootNode).toLowerCase()
+        if (name !== kind) {
+            return undefined
+        }
+
+        // Below here we assume anything that makes it this far is being extracted by the right type of extractor so failing to get any other part will result in an error stopping compilation instead
+        const { paramId, syntaxList, objectArgValue } = this.getConfigFunctionComponents(kind, this.rootNode)
+        const config: ConfigEntity = { inputObject: objectArgValue, configEntries: {} }
+        const data = config.configEntries
+        let stepNumber = 0
+        syntaxList.getChildren().forEach((statement) => {
+            try {
+                switch (statement.getKind()) {
+                    case SyntaxKind.ExpressionStatement: {
+                        /**
+                         * (param) => {
+                         * param.foo({arg: 'value'}) <- Expression statement
+                         * }
+                         */
+                        // This formatting of casting is used throughout the class. Try to keep casting close to where the value is determined and then save it to a cast variable and use
+                        // that below. This prevents accidentally using a variable as multiple different types by forgetting to cast and also keeps casting near where type is determined
+                        // so its more clear why it is being cast
+                        const ce = this.extractCallExpression(statement, paramId)
+                        data[stepNumber++] = {
+                            name: this.getName(ce),
+                            info: this.objNodeToJSON(ce.getFirstDescendantByKind(SyntaxKind.ObjectLiteralExpression)),
+                        }
+                        this.identifiers.push(null)
+                        break
+                    }
+                    case SyntaxKind.VariableStatement: {
+                        /**
+                         * (param) => {
+                         * const output = param.foo({arg: 'value'}) <- Variable statement
+                         * }
+                         */
+                        const ce = this.extractCallExpression(statement, paramId)
+                        const variableDeclaration = statement.getFirstDescendantByKind(SyntaxKind.VariableDeclaration)
+
+                        if (!variableDeclaration) {
+                            throw Error('Could not find variable declaration in variable statement')
+                        }
+
+                        const assignment = variableDeclaration.getChildren() // Format: identifier, =, value
+                        const identifier = assignment[0] as Identifier
+                        const value = assignment[2] as CallExpression // Already been validated above to be a valid call expression
+
+                        data[stepNumber++] = {
+                            name: this.getName(ce),
+                            info: this.objNodeToJSON(
+                                value.getFirstDescendantByKind(SyntaxKind.ObjectLiteralExpression)
+                            ),
+                        }
+                        this.identifiers.push(identifier)
+                        break
+                    }
+                    case SyntaxKind.MultiLineCommentTrivia:
+                        /** This is a multiline comment */
+                        break
+                    case SyntaxKind.SingleLineCommentTrivia:
+                        // This is a single line comment
+                        break
+                    default:
+                        throw Error(
+                            `Found an invalid node in the configuration function block, found: ${
+                                statement?.getKindName() ? statement.getKindName() : 'Kind name undefined'
+                            }`
+                        )
+                }
+            } catch (e) {
+                // Provides easy context w/o having to worry about having blah.getText() in all errors
+                logger.error(`Encountered an error while parsing statement: ${statement.getText()}`)
+                throw e
+            }
+        })
+        return new ConfigurationFunctionEntityData(config, this.rootNode)
+    }
+}

package/src/plugins/util/ObjectLiteral.ts

@@ -0,0 +1,37 @@
+import * as ts from 'ts-morph'
+
+/**
+ * Retrieves the property assignment with the specified name and subpath from the given node.
+ * @param node - The node to search for the property assignment.
+ * @param property - The name of the property assignment to retrieve.
+ * @param subPath - Optional subpath to navigate within the property assignment.
+ * @returns The property assignment node if found, otherwise undefined.
+ */
+export function getPropertyAssignment(node: ts.Node | undefined, property: string, ...subPath: string[]) {
+    let current = node
+        ?.asKind(ts.SyntaxKind.ObjectLiteralExpression)
+        // get the property assignment with the specified name
+        ?.getProperty((p) => hasPropertyAssignment(p, property))
+        ?.asKind(ts.SyntaxKind.PropertyAssignment)
+
+    for (const pathPart of subPath) {
+        current = current
+            ?.getInitializerIfKind(ts.SyntaxKind.ObjectLiteralExpression)
+            // get the property assignment with the specified name
+            ?.getProperty((p) => hasPropertyAssignment(p, pathPart))
+            ?.asKind(ts.SyntaxKind.PropertyAssignment)
+    }
+
+    return current
+}
+
+/**
+ * Checks if the given property assignment has the specified path.
+ * @param property - The property assignment to check.
+ * @param path - The path to compare against.
+ * @returns True if the property assignment has the specified path, otherwise false.
+ */
+function hasPropertyAssignment(property: ts.ObjectLiteralElementLike | undefined, path: string): boolean {
+    const child = property?.getChildren().find((c) => ts.Node.isStringLiteral(c) || ts.Node.isIdentifier(c))
+    return child?.getSymbol()?.getEscapedName() === path
+}

package/src/plugins/util/index.ts

@@ -0,0 +1,4 @@
+export * from './CallExpression'
+export * from './CodeTransformation'
+export * from './ObjectLiteral'
+export * from './ConfigurationFunction'

package/src/util/Debug.ts

@@ -0,0 +1,46 @@
+import { inspect as nodeInspect } from 'util'
+import { Data, Document, File } from '../plugins/behaviors'
+import { Logger } from '@servicenow/sdk-project'
+
+export function inspect(val: unknown, depth = 2) {
+    return nodeInspect(val, {
+        colors: true,
+        compact: false,
+        depth,
+    })
+}
+
+export function debugData(data: ({ data: unknown } | Data)[], logger: Logger, message = 'DATA:') {
+    logger.info(message)
+    logger.info(
+        inspect(
+            data.map((d) => {
+                if (d instanceof Data) {
+                    return d.getValue()
+                } else {
+                    return d
+                }
+            }),
+            5
+        )
+    )
+}
+
+export function debugDocuments(documents: Document[], logger: Logger, message = 'DOCUMENTS:') {
+    logger.info(message)
+    logger.info(
+        inspect(
+            documents.map((d) => {
+                const { node, ...rest } = d
+                node
+                return rest
+            }),
+            5
+        )
+    )
+}
+
+export function debugFiles(files: File[], logger: Logger, message = 'FILES:') {
+    logger.info(message)
+    logger.info(inspect(files, 5))
+}

package/src/util/Util.ts

@@ -0,0 +1,21 @@
+import * as path from 'path'
+import { FileSystem } from '@servicenow/sdk-project'
+
+export const NOW_DIR = '.now'
+
+export function safeWriteFileToPath(
+    fs: FileSystem,
+    dirPath: string,
+    fileName: string,
+    content: string,
+    encoding: FileSystem.Encoding = 'utf-8'
+) {
+    createDirIfNotExists(dirPath, fs)
+    fs.writeFileSync(path.join(dirPath, fileName), content, { encoding: encoding })
+}
+
+export function createDirIfNotExists(dirPath: string, fs: FileSystem) {
+    if (!FileSystem.existsSync(fs, dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true })
+    }
+}

package/src/util/XMLJsonBuilder.ts

@@ -0,0 +1,64 @@
+export class XMLJsonBuilder {
+    private rootXmlElement: XMLJsonElement
+    constructor(version: string) {
+        this.rootXmlElement = new XMLJsonElement('_root')
+        this.rootXmlElement.addJsonObj('?xml', undefined, { version })
+    }
+
+    createRoot(element: string, text: string = '', attrs: Record<string, string | number | boolean> = {}) {
+        return this.rootXmlElement.addJsonObj(element, text, attrs)
+    }
+
+    buildJsonObj() {
+        const {
+            _root: { '#text': _rootText, ...jsonObj },
+        } = this.rootXmlElement.getData()
+        return jsonObj
+    }
+}
+
+export class XMLJsonElement {
+    private xmlEleMap: Map<string, XMLJsonElement[]> = new Map()
+
+    constructor(
+        private element: string,
+        private text: string = '',
+        private attrs: Record<string, string | number | boolean> = {},
+        private isCDATA: boolean = false
+    ) {}
+
+    addJsonObj(
+        element: string,
+        text: string = '',
+        attrs: Record<string, string | number | boolean> = {},
+        isCDATA: boolean = false
+    ) {
+        const xmlJsonObj = new XMLJsonElement(element, text, attrs, isCDATA)
+        if (!this.xmlEleMap.has(element)) {
+            this.xmlEleMap.set(element, [])
+        }
+        this.xmlEleMap.get(element)!.push(xmlJsonObj)
+        return xmlJsonObj
+    }
+
+    getData() {
+        const additionalElements: any = []
+        this.xmlEleMap.forEach((value, key) => {
+            if (value.length === 1) {
+                additionalElements.push({ ...value[0]!.getData() })
+                return
+            }
+            additionalElements.push({ [key]: value.map((value) => value.getData()[key]) })
+        })
+
+        const additionalObj = additionalElements.reduce((acc, ele) => ({ ...acc, ...ele }), {})
+
+        return {
+            [this.element]: {
+                ...(this.isCDATA ? { __cdata: this.text } : { '#text': this.text }),
+                ...Object.fromEntries(Object.entries(this.attrs).map(([k, v]) => [`@_${k}`, v])),
+                ...additionalObj,
+            },
+        }
+    }
+}