@servicenow/sdk-build-core 3.0.3 → 4.0.0

package/dist/plugins/plugin.d.ts

@@ -0,0 +1,478 @@
+import { type SupportedKindName, type SupportedNode, type SupportedNodeByKindName, ts } from '../typescript';
+import { type ObjectShape, type Record, type Shape, type ShapeClass, type StringShape } from './shape';
+import type { File, OutputFile } from './file';
+import { Database } from './database';
+import type { Context as BaseContext } from './context';
+type Context = Omit<BaseContext, 'keys'>;
+export type Result<Value = unknown> = {
+    success: false;
+} | {
+    success: true;
+    value: Value;
+};
+export type CommitResult = {
+    success: boolean;
+};
+export type CommitFunction = (shape: Shape, target: ts.Node, ...plugins: Plugin[]) => Promise<void>;
+export type CommitContext = Context & {
+    commit: CommitFunction;
+};
+export type RecordContext = Context & {
+    readonly database: Database;
+    readonly descendants: Database;
+};
+export type Relationships = {
+    [table: string]: Relationship;
+};
+export type Relationship = {
+    /**
+     * Specifies how the tables are related:
+     *
+     * - String:   Name of the reference field on the child table pointing to the parent (or
+     *             vice versa for inverse relationships)
+     * - Object:   Key-value pairs where keys are column names on the child table and values
+     *             are the matching column names on the parent table (or vice versa for inverse
+     *             relationships)
+     * - Function: Takes the parent and child records as arguments and returns a boolean to
+     *             indicate whether the records are related or not (WARNING: Do not use this
+     *             unless absolutely necessary as it can negatively impact performance)
+     */
+    via: string | {
+        [column: string]: string;
+    } | ((parent: Record, child: Record) => boolean);
+    /**
+     * When true, the relationship direction is reversed - the parent references the child
+     * instead of the child referencing the parent
+     */
+    inverse?: boolean;
+    /**
+     * When true, the related record is considered part of the same logical entity as its
+     * parent. These records should be processed together as a unit.
+     */
+    descendant?: boolean;
+    /**
+     * Nested relationships that define how this table relates to other tables
+     */
+    relationships?: Relationships;
+};
+export type CoalesceStrategy = [string, ...string[]] | ((properties: ObjectShape) => globalThis.Record<string, string | StringShape> | ObjectShape);
+export type FileType = 'fluent' | 'module' | 'json' | 'unknown';
+export type PluginConfig<Nodes extends SupportedKindName[] = SupportedKindName[], Shapes extends ShapeClass[] = ShapeClass[], Records extends string[] = string[]> = {
+    /**
+     * The name of the plugin. Must end with "Plugin" suffix. This name is used in metrics
+     * and error messages.
+     */
+    name: `${string}Plugin`;
+    /**
+     * The TypeScript AST nodes this plugin handles. Plugins that do not introduce new
+     * syntax should not need to define any handlers here.
+     */
+    nodes?: {
+        [I in keyof Nodes]: {
+            /**
+             * The TypeScript node kind to handle. Must be one of the hard-coded set
+             * of supported kinds in the Fluent DSL.
+             */
+            node: Nodes[I];
+            /**
+             * File types this handler should run on. These are based on the file
+             * extension. If not specified, it runs on all file types.
+             */
+            fileTypes?: FileType[];
+            /**
+             * Indicates whether this node should be parsed as an entry point during
+             * the top-level AST traversal to produce output. (Default: false)
+             */
+            entryPoint?: boolean;
+            /**
+             * Converts a TypeScript node to a shape.
+             *
+             * This is the initial transformation step when processing source code.
+             * The function receives a TypeScript node of the specified kind and
+             * returns a shape derived from it. That shape can then be handled later
+             * by shape transforms defined in this plugin or some other plugin.
+             *
+             * @param node - The TypeScript node to transform
+             * @param context - Context object with useful services and information
+             * @returns A result indicating whether the transformation was successful
+             *          and, if so, the resulting shape
+             */
+            toShape?(node: SupportedNodeByKindName<Nodes[I]>, context: Context): Result<Shape> | Promise<Result<Shape>>;
+        };
+    };
+    /**
+     * The shapes this plugin handles. Each shape handler can implement the following:
+     *
+     * - Transform functions that turn shapes into records (toRecord)
+     * - Transform functions that turn shapes into more specialized subclasses of those shapes (toSubclass)
+     * - Commit functions that mutate TypeScript nodes to match shapes (commit)
+     * - Inspect functions that can examine shapes for diagnostic purposes (inspect)
+     */
+    shapes?: {
+        [I in keyof Shapes]: Shapes[I] extends ShapeClass<infer S> ? {
+            /**
+             * The shape class to handle.
+             */
+            shape: Shapes[I];
+            /**
+             * File types this handler should run on. These are based on the file
+             * extension. If not specified, it runs on all file types.
+             */
+            fileTypes?: FileType[];
+            /**
+             * Inspects a shape. Useful for validating the details of a shape created
+             * by another plugin and producing diagnostics.
+             *
+             * @param shape - The shape to inspect
+             * @param context - Context object with useful services and information
+             */
+            inspect?(shape: S, context: Context): void;
+            /**
+             * Transforms a shape into a more specific subclass. Plugins that introduce
+             * a shape which extends another shape should implement this. For example,
+             * many plugins implement support for entities based on call expressions,
+             * and therefore handle CallExpressionShape. Creating a subclass of that
+             * shape allows plugins to more easily handle their use case.
+             *
+             * NOTE: The shape returned by this function MUST be a subclass of the input
+             * shape. If it is not, an error will be thrown at runtime.
+             *
+             * @param shape - The shape to transform
+             * @param context - Context object with useful services and information
+             * @returns A result indicating whether the transformation was successful
+             *          and, if so, an instance of the subclass
+             */
+            toSubclass?(shape: S, context: Context): Result<S>;
+            /**
+             * Transforms a shape into a record. Almost all plugins should implement
+             * this, as it is the fundamental transformation step in the process of
+             * turning Fluent code into ServiceNow records. These records will then
+             * be serialized into XML as part of a build, or merged with incoming
+             * records as part of bidirectional sync.
+             *
+             * @param shape - The shape to transform
+             * @param context - Context object with useful services and information
+             * @returns A result indicating whether the transformation was successful
+             *          and, if so, the resulting record(s)
+             */
+            toRecord?(shape: S, context: Context): Result<Record> | Promise<Result<Record>>;
+            /**
+             * Mutates a target TypeScript node to match a given shape. Plugins that
+             * do not introduce new syntax should not need to implement this.
+             *
+             * NOTE: It is CRUCIAL that the commit function does not apply any changes
+             * to the target node other than what is absolutely necessary to match
+             * the shape. They should be "minimally invasive", preserving as much
+             * as possible of the original code, including comments and whitespace.
+             * Care must be taken to check if parts of the existing code are
+             * functionally equivalent to the incoming shape, even if they are not
+             * exactly the same.
+             *
+             * @param shape - The shape to commit
+             * @param target - The target TypeScript node to modify
+             * @param context - Context with useful services and information
+             * @returns A result indicating whether the commit was successful
+             */
+            commit?(shape: S, target: ts.Node, context: CommitContext): CommitResult | Promise<CommitResult>;
+        } : never;
+    };
+    /**
+     * The records this plugin handles. The keys of this object are the names of the tables to be
+     * handled, and the values are handlers which can implement the following:
+     *
+     * - Transform functions that turn records into shapes (toShape)
+     * - Transform functions that turn records into files (toFile)
+     * - Relationship mappings
+     * - Coalesce strategies
+     */
+    records?: {
+        [T in Records[number]]: {
+            /**
+             * Columns that compose the coalesce strategy for this table. If there is a strategy defined in
+             * the platform for this table, you must make sure this configuration matches it. If there isn't
+             * one defined in the platform, you can decide to either create a suitable one here or leave it
+             * undefined. Tables without coalesce strategies will rely on their GUIDs to determine identity.
+             *
+             * For advanced use cases where simple column-based coalesce strategies cannot be used, you may
+             * define a dynamic coalesce strategy by supplying a function that accepts the properties of a
+             * record and returns an object with the desired coalesce keys.
+             *
+             * Refer to CoalesceStrategies.java to find platform-defined coalesce strategies:
+             * https://code.devsnc.com/dev/glide/blob/master/glide/src/com/glide/script/coalesce/CoalesceStrategies.java
+             */
+            coalesce?: CoalesceStrategy;
+            /**
+             * You can think of the relationship between two tables as a parent-child relationship. Usually,
+             * the child references the parent via a foreign key. For example, sys_security_acl_role (child)
+             * references sys_security_acl (parent) via a reference column. This is the most basic type of
+             * relationship. In this case, the ACL plugin should handle the parent record and the children
+             * as part of the same entity. That's because the full definition of an ACL includes both the
+             * top-level sys_security_acl record AND the sys_security_acl_role M2M records which link it to
+             * its roles. This type of relationship, where a child record is part of a singular entity with
+             * its parent, is called a "descendant" relationship.
+             *
+             * sys_security_acl <- sys_security_acl_role (descendant relationship)
+             *
+             * Sometimes, relationships are the other way around, where the parent references the child. To
+             * continue the ACL example, sys_security_acl_role (parent) references sys_user_role (child) via
+             * a reference column. This is called an "inverse" relationship because it goes parent -> child
+             * instead of child -> parent. However, this would NOT be considered a "descendant" relationship
+             * because the role itself is not part of the ACL definition. The ACL and the role are related,
+             * but the role itself is its own separate entity.
+             *
+             * sys_security_acl_role <- sys_user_role (inverse non-descendant relationship)
+             *
+             * So far we've only explored relationships based on foreign keys (reference columns). In these
+             * cases your "via" would simply be the name of the reference column that connects them, either
+             * on the child table (normal relationship) or the parent (inverse relationship). However, it's
+             * also possible for two tables to be related by matching the values from one or more columns on
+             * both tables. For example, sys_db_object (parent) and sys_dictionary (child) are related by
+             * matching the "name" columns from each table. In other words, if a sys_db_object record has a
+             * value of "incident" in its "name" column, then any sys_dictionary records that also have the
+             * value "incident" in their "name" columns are its children. These children are also considered
+             * "descendants" because they are all part of the same table entity. In these cases, your "via"
+             * would be represented as key-value pairs instead of a single column name. The keys should be
+             * the names of columns on the child table, and the values should be the names of columns that
+             * should be matched on the parent table. (For "inverse" relationships, the key-value pairs are
+             * flipped.)
+             *
+             * sys_db_object <- sys_dictionary (descendant relationship by matching "name":"name")
+             */
+            relationships?: Relationships;
+            /**
+             * Transforms a record into a shape. Almost all plugins should implement this, as it is
+             * the fundamental transformation step in the process of turning ServiceNow records into
+             * Fluent code, or bidirectionally syncing changes to existing Fluent code.
+             *
+             * @param record - The record to transform
+             * @param context - Context with useful services and information
+             * @returns A result indicating whether the transformation was successful and, if so, the
+             *          resulting shape
+             */
+            toShape?(record: Record, context: RecordContext): Result<Shape> | Promise<Result<Shape>>;
+            /**
+             * Transforms a database record into output file(s). Plugins should only implement this
+             * if the records they handle must be serialized to some specialized non-standard format.
+             * Records that follow the usual ServiceNow format do NOT need to be handled here. This
+             * transformation is the last step in the build process.
+             *
+             * @param record - The record to transform
+             * @param context - Context with useful services and information
+             * @returns A result indicating whether the transformation was successful and, if so, the
+             *          resulting output file(s)
+             */
+            toFile?(record: Record, context: RecordContext): Result<OutputFile | OutputFile[]> | Promise<Result<OutputFile | OutputFile[]>>;
+        };
+    };
+    /**
+     * The files this plugin handles. Plugins that do not introduce new file types should not
+     * need to implement anything here.
+     */
+    files?: {
+        /**
+         * A regex pattern or predicate to apply to a file's path to determine if it should be handled by this plugin.
+         */
+        matcher?: RegExp | ((path: string, context: Context) => boolean | Promise<boolean>);
+        /**
+         * Indicates whether this file should be parsed as an entry point when generating output. (Default: false)
+         */
+        entryPoint?: boolean;
+        /**
+         * Transforms a file into record(s).
+         *
+         * @param file - The file to transform
+         * @param context - Context object with useful services and information
+         * @returns A result indicating whether the transformation was successful and, if so, the
+         *          resulting record(s)
+         */
+        toRecord?(file: File, context: Context): Result<Record> | Promise<Result<Record>>;
+    }[];
+};
+type SearchableRelationships = {
+    [table: string]: Relationships;
+};
+export declare class Plugin {
+    private readonly config;
+    private readonly nodeToShapeCache;
+    private readonly shapeToSubclassCache;
+    private readonly shapeToRecordCache;
+    private readonly relationships;
+    private readonly references;
+    private constructor();
+    private parseRelationships;
+    /**
+     * Creates a new Fluent plugin from the provided configuration.
+     *
+     * Plugins are the primary mechanism for extending the Fluent DSL and providing support for
+     * new types of ServiceNow entities. Plugins implement handlers responsible for parsing and
+     * transforming Fluent code, ServiceNow records, and any other files that exist within a
+     * Fluent project.
+     *
+     * The build system orchestrates the plugins together to carry a project through all the
+     * stages of building and bidirectionally syncing a Fluent project, invoking each plugin's
+     * handlers at the appropriate points in the process, and providing the relevant inputs and
+     * context.
+     *
+     * During a regular build, the stages are:
+     *
+     * 1. Traverse the full AST of all the Fluent code, transforming each node into a shape
+     * 2. Transform each shape into a more specific subclass of that shape
+     * 3. Transform each subclassed shape into one or more ServiceNow records
+     * 4. Serialize each record into an output file
+     *
+     * During bidirectional sync, the stages are:
+     *
+     * 1. Perform stage 1 from the regular build process to get the existing shapes
+     * 2. Perform stage 2 from the regular build process to subclass those existing shapes
+     * 3. Perform stage 3 from the regular build process to get the existing records
+     * 4. Parse input files (usually XML from a ServiceNow instance) to get the incoming records
+     * 5. Merge the incoming records into the existing records so that all changes are reflected
+     * 6. Transform each merged record into a shape
+     * 7. Commit each shape to the Fluent AST, generating new nodes as needed
+     *
+     * @example
+     * // Stages of a regular build
+     * const CoolPlugin = Plugin.create({
+     *     name: 'CoolPlugin',
+     *     nodes: [
+     *         {
+     *             node: 'CallExpression',
+     *             toShape(node) {
+     *                 // BUILD STAGE 1: A CallExpression node is transformed into a CallExpressionShape.
+     *             }
+     *         }
+     *     ],
+     *     shapes: [
+     *         {
+     *             shape: CallExpressionShape,
+     *             toSubclass(shape) {
+     *                 // BUILD STAGE 2: The CallExpressionShape from stage 1 is transformed into a CoolShape.
+     *             }
+     *         },
+     *         {
+     *             shape: CoolShape,
+     *             toRecord(shape) {
+     *                 // BUILD STAGE 3: The CoolShape from stage 2 is transformed into a cool_table record.
+     *             }
+     *         }
+     *     ],
+     *     records: {
+     *         cool_table: {
+     *             toFile(record) {
+     *                 // BUILD STAGE 4: The cool_table record from stage 3 is serialized into an output file.
+     *             }
+     *         }
+     *     },
+     * })
+     *
+     * @example
+     * // Stages of bidirectional sync
+     * const CoolPlugin = Plugin.create({
+     *     name: 'CoolPlugin',
+     *     nodes: [
+     *         {
+     *             node: 'CallExpression',
+     *             toShape(node) {
+     *                 // SYNC STAGE 1: An existing CallExpression node is transformed into a CallExpressionShape.
+     *             }
+     *         }
+     *     ],
+     *     shapes: [
+     *         {
+     *             shape: CallExpressionShape,
+     *             toSubclass(shape) {
+     *                 // SYNC STAGE 2: The existing CallExpressionShape from stage 1 is transformed into a CoolShape
+     *             },
+     *             commit(shape, target) {
+     *                 // SYNC STAGE 7: The new CoolShape from stage 6, which now contains the changes from the
+     *                 // incoming cool_table record, is committed to the original CallExpression node.
+     *                 //
+     *                 // NOTES:
+     *                 // - Since CoolShape extends CallExpressionShape, and there is no commit function
+     *                 //   for CoolShape, this commit function is used. If, for some reason, CoolShape
+     *                 //   needed to be committed differently than other CallExpressionShapes, then this
+     *                 //   plugin would need to implement a commit function for CoolShape.
+     *                 // - If the incoming cool_table record didn't already exist in the code, then the
+     *                 //   build system would generate an arbitrary new node before passing it into this
+     *                 //   commit function as the target. So the implementation should never assume that
+     *                 //   the target is a CallExpression node.
+     *             }
+     *         },
+     *         {
+     *             shape: CoolShape,
+     *             toRecord(shape) {
+     *                 // SYNC STAGE 3: The existing CoolShape from stage 2 is transformed into a cool_table record.
+     *             }
+     *         }
+     *     ],
+     *     files: [
+     *         {
+     *             extension: 'xml',
+     *             toRecord(file) {
+     *                 // SYNC STAGE 4: An incoming XML file with changes is parsed into a cool_table record.
+     *             }
+     *         }
+     *     ],
+     *     records: {
+     *         cool_table: {
+     *             toShape(record) {
+     *                 // SYNC STAGE 6: After the incoming cool_table record from stage 4 is merged into the
+     *                 // existing one from stage 3, the merged record is transformed back into a CoolShape.
+     *             }
+     *         }
+     *     },
+     * })
+     */
+    static create<const N extends SupportedKindName[], const S extends ShapeClass[]>(config: PluginConfig<N, S>): Plugin;
+    getName(): string;
+    getDescendants(parent: Record, database: Database): Record[];
+    getCoalesceStrategy(table: string): CoalesceStrategy | undefined;
+    getCoalesceTables(): string[];
+    getTables(relationships?: Relationships, tables?: string[]): Set<string>;
+    getReferenceColumns(table: string): {
+        [column: string]: string;
+    };
+    getRelationships(): SearchableRelationships;
+    flushCache(): void;
+    nodeToShape(node: SupportedNode, context: Omit<Context, 'self'>): Promise<Result<Shape>>;
+    commit(shape: Shape, target: ts.Node, context: Omit<CommitContext, 'self'>): Promise<CommitResult>;
+    shapeToSubclass<const S extends Shape>(shape: S, context: Omit<Context, 'self'>): Result<S>;
+    shapeToRecord(shape: Shape, context: Omit<Context, 'self'>): Promise<Result<Record>>;
+    private recordToShape0;
+    recordToShape({ record, database, context, }: {
+        record: Record;
+        database: Database;
+        context: Omit<Context, 'self'>;
+    }): Promise<Result<Shape>>;
+    recordsToShapes({ database, creatorOnly, changedOnly, mode, handledRecords, context, }: {
+        database: Database;
+        creatorOnly: boolean;
+        changedOnly?: boolean;
+        mode: 'explicit' | 'catch-all';
+        handledRecords: Database;
+        context: Omit<Context, 'self'>;
+    }): Promise<Result<Shape[]>>;
+    recordToFile(record: Record, context: Omit<RecordContext, 'self'>): Promise<Result<OutputFile | OutputFile[]>>;
+    recordsToFiles({ database, mode, handledGuids, context, }: {
+        database: Database;
+        mode: 'explicit' | 'catch-all';
+        handledGuids: Set<string>;
+        context: Omit<Context, 'self'>;
+    }): Promise<Result<OutputFile[]>>;
+    isEntryPoint(pathOrNode: string | SupportedNode, context: Omit<Context, 'self'>): Promise<boolean>;
+    fileToRecord(file: File, context: Omit<Context, 'self'>): Promise<Result<Record>>;
+    inspect(shape: Shape, context: Context): void;
+}
+export declare class Plugins {
+    private readonly plugins;
+    constructor(plugins: Plugin[]);
+    toArray(): Plugin[];
+    add(plugin: Plugin): void;
+    getCoalesceStrategy(table: string): CoalesceStrategy | undefined;
+    getCoalesceTables(): Set<string>;
+    getReferenceColumns(table: string): {
+        [column: string]: string;
+    };
+    isEntryPoint(pathOrNode: string | SupportedNode, context: Omit<Context, 'self'>): Promise<boolean>;
+}
+export {};