@servicenow/sdk-build-core 3.0.3 → 4.0.0

package/src/plugins/plugin.ts

@@ -0,0 +1,995 @@
+import {
+    getKindName,
+    type SupportedKindName,
+    type SupportedNode,
+    type SupportedNodeByKindName,
+    ts,
+} from '../typescript'
+import { DeletedShape, type ObjectShape, type Record, type Shape, type ShapeClass, type StringShape } from './shape'
+import type { File, OutputFile } from './file'
+import type { Product } from './product'
+import { Database, DiffDatabase } from './database'
+import type { Context as BaseContext } from './context'
+import { getFileType } from '../util'
+import { Cache } from './cache'
+
+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[]] // Simple column-based strategy
+    | ((properties: ObjectShape) => globalThis.Record<string, string | StringShape> | ObjectShape) // dynamic strategy
+
+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>>
+    }[]
+}
+
+function setCreator<V extends Product | Product[]>(creator: Plugin, result: Result<V>): Result<V> {
+    if (result.success) {
+        result.value = Array.isArray(result.value)
+            ? (result.value.map((r) => r.setCreator(creator)) as V)
+            : (result.value.setCreator(creator) as V)
+    }
+
+    return result
+}
+
+type SearchableRelationships = {
+    [table: string]: Relationships
+}
+
+type SearchableReferences = {
+    [table: string]: {
+        [column: string]: string
+    }
+}
+
+export class Plugin {
+    private readonly nodeToShapeCache = new Cache<ts.ts.Node, Result<Shape>>()
+    private readonly shapeToSubclassCache = new Cache<Shape, Result<Shape>>()
+    private readonly shapeToRecordCache = new Cache<Shape, Result<Record>>()
+    private readonly relationships: SearchableRelationships = {}
+    private readonly references: SearchableReferences = {}
+
+    private constructor(private readonly config: PluginConfig) {
+        for (const [table, config] of Object.entries(this.config.records ?? {})) {
+            this.parseRelationships([table, config.relationships])
+        }
+    }
+
+    private parseRelationships([table, relationships]: [string, Relationships | undefined]) {
+        if (table === '*' || !relationships) {
+            return
+        }
+
+        this.relationships[table] = { ...this.relationships[table], ...relationships }
+        for (const [subTable, subConfig] of Object.entries(relationships)) {
+            if (typeof subConfig.via === 'string') {
+                const [parent, child] = subConfig.inverse ? [subTable, table] : [table, subTable]
+                this.references[child] = { ...this.references[child], [subConfig.via]: parent }
+            }
+
+            this.parseRelationships([subTable, subConfig.relationships])
+        }
+    }
+
+    /**
+     * 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>) {
+        return new Plugin(config)
+    }
+
+    getName(): string {
+        return this.config.name
+    }
+
+    getDescendants(parent: Record, database: Database): Record[] {
+        const descendantRelationships = Object.entries(this.relationships[parent.getTable()] ?? {}).filter(
+            ([, { descendant }]) => descendant
+        )
+
+        const descendants: Record[] = []
+        const push = (children: Record | Record[] | undefined) => {
+            for (const child of [children].flat()) {
+                if (child) {
+                    descendants.push(child)
+                    descendants.push(...this.getDescendants(child, database))
+                }
+            }
+        }
+
+        for (const [childTable, { via, inverse = false }] of descendantRelationships) {
+            if (typeof via === 'string') {
+                if (inverse) {
+                    parent
+                        .get(via)
+                        .ifDefined()
+                        ?.toString()
+                        .pipe((v) => push(database.get(childTable, v.getValue())))
+                } else {
+                    push(database.query(childTable, { [via]: parent.toString().getValue() }))
+                }
+            } else if (typeof via === 'function') {
+                push(database.query(childTable).filter((child) => via(parent, child)))
+            } else {
+                push(
+                    database.query(
+                        childTable,
+                        Object.fromEntries(
+                            Object.entries(via).map((entry) => {
+                                const [parentColumn, childColumn] = inverse ? entry : [entry[1], entry[0]]
+                                return [childColumn, parent.get(parentColumn).getValue()]
+                            })
+                        )
+                    )
+                )
+            }
+        }
+
+        return descendants
+    }
+
+    getCoalesceStrategy(table: string): CoalesceStrategy | undefined {
+        return (this.config.records ?? {})[table]?.coalesce
+    }
+
+    getCoalesceTables(): string[] {
+        return Object.entries(this.config.records ?? {})
+            .filter(([_, val]) => val.coalesce)
+            .map(([table]) => table)
+    }
+
+    getTables(relationships?: Relationships, tables: string[] = []): Set<string> {
+        const tableEntries: any[] = relationships
+            ? Object.entries(relationships).filter(([, val]) => val.descendant)
+            : Object.entries(this.config.records ?? {}).filter(([, val]) => val.toShape)
+
+        tables.push(...tableEntries.filter(([table]) => table !== '*').map(([table]) => table))
+        tableEntries
+            .filter(([_, val]) => val.relationships)
+            .forEach(([_, val]) => this.getTables(val.relationships, tables))
+        return new Set(tables)
+    }
+
+    getReferenceColumns(table: string): { [column: string]: string } {
+        return this.references[table] ?? {}
+    }
+
+    getRelationships(): SearchableRelationships {
+        return this.relationships
+    }
+
+    flushCache(): void {
+        this.nodeToShapeCache.clear()
+        this.shapeToRecordCache.clear()
+    }
+
+    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()
+        }
+
+        try {
+            for (const config of this.config.nodes ?? []) {
+                if (
+                    config.toShape &&
+                    getKindName(node) === config.node &&
+                    (!config.fileTypes || config.fileTypes.includes(getFileType(node.getSourceFile().getFilePath())))
+                ) {
+                    const result = setCreator(this, await config.toShape.bind(this)(node, { ...context, self: this }))
+                    if (result.success) {
+                        return this.nodeToShapeCache.put(node.compilerNode, result)
+                    }
+                }
+            }
+
+            return this.nodeToShapeCache.put(node.compilerNode, { success: false })
+        } catch (e) {
+            throw this.nodeToShapeCache.error(node.compilerNode, e)
+        }
+    }
+
+    async commit(shape: Shape, target: ts.Node, context: Omit<CommitContext, 'self'>): Promise<CommitResult> {
+        for (const { shape: shapeClass, commit } of this.config.shapes ?? []) {
+            if (shape.is(shapeClass) && commit) {
+                const result = await commit.bind(this)(shape, target, { ...context, self: this })
+                if (result.success) {
+                    return result
+                }
+            }
+        }
+
+        return { success: false }
+    }
+
+    shapeToSubclass<const S extends Shape>(shape: S, context: Omit<Context, 'self'>): Result<S> {
+        const entry = this.shapeToSubclassCache.get(shape)
+        if (entry) {
+            return entry.isError() ? { success: false } : (entry.unwrap() as Result<S>)
+        }
+
+        try {
+            for (const config of this.config.shapes ?? []) {
+                if (
+                    config.toSubclass &&
+                    shape.constructor === config.shape &&
+                    (!config.fileTypes || config.fileTypes.includes(getFileType(shape.getOriginalFilePath())))
+                ) {
+                    const result = setCreator(
+                        this,
+                        config.toSubclass.bind(this)(shape, {
+                            ...context,
+                            self: this,
+                        })
+                    )
+
+                    if (result.success) {
+                        if (result.value.constructor === config.shape) {
+                            throw new Error(
+                                `Result of subclassing "${config.shape.name}" is an instance of the same class. The result MUST be a subclass.`
+                            )
+                        }
+
+                        return this.shapeToSubclassCache.put(shape, result as Result<S>)
+                    }
+                }
+            }
+
+            return this.shapeToSubclassCache.put(shape, { success: false })
+        } catch (e) {
+            throw this.shapeToSubclassCache.error(shape, e)
+        }
+    }
+
+    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()
+        }
+
+        try {
+            for (const config of this.config.shapes ?? []) {
+                if (
+                    config.toRecord &&
+                    shape.is(config.shape) &&
+                    (!config.fileTypes || config.fileTypes.includes(getFileType(shape.getOriginalFilePath())))
+                ) {
+                    const result = setCreator(this, await config.toRecord.bind(this)(shape, { ...context, self: this }))
+                    if (result.success) {
+                        return this.shapeToRecordCache.put(shape, result)
+                    }
+                }
+            }
+
+            return this.shapeToRecordCache.put(shape, { success: false })
+        } catch (e) {
+            throw this.shapeToRecordCache.error(shape, e)
+        }
+    }
+
+    private async recordToShape0(record: Record, context: Omit<RecordContext, 'self'>): Promise<Result<Shape>> {
+        if (record.getAction() !== 'INSERT_OR_UPDATE') {
+            return { success: true, value: new DeletedShape({ source: record }) }
+        }
+
+        const table = record.getTable()
+        for (const [configTable, { toShape }] of Object.entries(this.config.records ?? {})) {
+            if ((configTable === '*' || configTable === table) && toShape) {
+                const result = setCreator(this, await toShape.bind(this)(record, { ...context, self: this }))
+                if (result.success) {
+                    return result
+                }
+            }
+        }
+
+        return { success: false }
+    }
+
+    async recordToShape({
+        record,
+        database,
+        context,
+    }: {
+        record: Record
+        database: Database
+        context: Omit<Context, 'self'>
+    }): Promise<Result<Shape>> {
+        context.logger.debug(`Transforming record into shape: ${record.getTable()}.${record.getId().getValue()}`)
+
+        const descendants = this.getDescendants(record, database)
+        return this.recordToShape0(record, {
+            ...context,
+            database,
+            descendants: new Database(descendants.filter((r) => r.getAction() === 'INSERT_OR_UPDATE')),
+        })
+    }
+
+    async recordsToShapes({
+        database,
+        creatorOnly,
+        changedOnly = false,
+        mode,
+        handledRecords,
+        context,
+    }: {
+        database: Database
+        creatorOnly: boolean
+        changedOnly?: boolean
+        mode: 'explicit' | 'catch-all'
+        handledRecords: Database
+        context: Omit<Context, 'self'>
+    }): Promise<Result<Shape[]>> {
+        let success = false
+        const shapes: Shape[] = []
+
+        for (const [table, { toShape }] of Object.entries(this.config.records ?? {})) {
+            if (!toShape) {
+                continue
+            } else if (mode === 'explicit' && table === '*') {
+                continue
+            } else if (mode === 'catch-all' && table !== '*') {
+                continue
+            }
+
+            for (const record of table === '*' ? database.query() : database.query(table)) {
+                if (handledRecords.resolve(record.getId())) {
+                    continue
+                }
+
+                if (creatorOnly && record.getCreator() !== this) {
+                    continue
+                }
+
+                context.logger.debug(
+                    `Transforming record into shape: ${record.getTable()}.${record.getId().getValue()}`
+                )
+
+                const descendants = this.getDescendants(record, database)
+                if (changedOnly) {
+                    if (!(database instanceof DiffDatabase)) {
+                        throw new Error(
+                            `Tried to check for changed records while creating shapes, but the provided database does not support diffing.`
+                        )
+                    }
+
+                    if (![record, ...descendants].some((r) => database.isChanged(r))) {
+                        continue // If neither the record nor its descendants are in the diff, skip it
+                    }
+                }
+
+                const result = await this.recordToShape0(record, {
+                    ...context,
+                    database,
+                    descendants: new Database(descendants.filter((r) => r.getAction() === 'INSERT_OR_UPDATE')),
+                })
+
+                if (result.success) {
+                    success = true
+                    handledRecords.insert(record)
+                    descendants.forEach((d) => handledRecords.insert(d))
+                    shapes.push(...[result.value].flat())
+                }
+            }
+        }
+
+        return { success, value: shapes }
+    }
+
+    async recordToFile(
+        record: Record,
+        context: Omit<RecordContext, 'self'>
+    ): Promise<Result<OutputFile | OutputFile[]>> {
+        const table = record.getTable()
+        for (const [configTable, { toFile }] of Object.entries(this.config.records ?? {})) {
+            if ((configTable === '*' || configTable === table) && toFile) {
+                const result = await toFile.bind(this)(record, { ...context, self: this })
+                if (result.success) {
+                    return result
+                }
+            }
+        }
+
+        return { success: false }
+    }
+
+    async recordsToFiles({
+        database,
+        mode,
+        handledGuids,
+        context,
+    }: {
+        database: Database
+        mode: 'explicit' | 'catch-all'
+        handledGuids: Set<string>
+        context: Omit<Context, 'self'>
+    }): Promise<Result<OutputFile[]>> {
+        let success = false
+        const files: OutputFile[] = []
+
+        for (const [table, { toFile }] of Object.entries(this.config.records ?? {})) {
+            if (!toFile) {
+                continue
+            } else if (mode === 'explicit' && table === '*') {
+                continue
+            } else if (mode === 'catch-all' && table !== '*') {
+                continue
+            }
+
+            for (const record of table === '*' ? database.query() : database.query(table)) {
+                if (handledGuids.has(record.getId().getValue())) {
+                    continue
+                }
+
+                const descendants = this.getDescendants(record, database)
+                const result = await this.recordToFile(record, {
+                    ...context,
+                    database,
+                    descendants: new Database(descendants.filter((r) => r.getAction() === 'INSERT_OR_UPDATE')),
+                })
+
+                if (result.success) {
+                    success = true
+                    handledGuids.add(record.getId().getValue())
+                    descendants.forEach((r) => handledGuids.add(r.getId().getValue()))
+                    files.push(...[result.value].flat())
+                }
+            }
+        }
+
+        return { success, value: files }
+    }
+
+    async isEntryPoint(pathOrNode: string | SupportedNode, context: Omit<Context, 'self'>): Promise<boolean> {
+        if (ts.Node.isNode(pathOrNode)) {
+            for (const config of this.config.nodes ?? []) {
+                if (getKindName(pathOrNode) !== config.node) {
+                    continue
+                }
+
+                const fileType = getFileType(pathOrNode.getSourceFile().getFilePath())
+                if (config.fileTypes && !config.fileTypes.includes(fileType)) {
+                    continue
+                }
+
+                return !!config.entryPoint
+            }
+        } else {
+            for (const config of this.config.files ?? []) {
+                if (config.matcher instanceof RegExp && !config.matcher.test(pathOrNode)) {
+                    continue
+                }
+
+                if (
+                    typeof config.matcher === 'function' &&
+                    !(await config.matcher(pathOrNode, { ...context, self: this }))
+                ) {
+                    continue
+                }
+
+                return !!config.entryPoint
+            }
+        }
+
+        return false
+    }
+
+    async fileToRecord(file: File, context: Omit<Context, 'self'>): Promise<Result<Record>> {
+        for (const config of this.config.files ?? []) {
+            if (!config.toRecord) {
+                continue
+            }
+
+            if (config.matcher instanceof RegExp && !config.matcher.test(file.path)) {
+                continue
+            }
+
+            if (typeof config.matcher === 'function' && !config.matcher(file.path, { ...context, self: this })) {
+                continue
+            }
+
+            const result = setCreator(this, await config.toRecord.bind(this)(file, { ...context, self: this }))
+            if (result.success) {
+                return result
+            }
+        }
+
+        return { success: false }
+    }
+
+    inspect(shape: Shape, context: Context): void {
+        for (const config of this.config.shapes ?? []) {
+            if (shape.is(config.shape) && config.inspect) {
+                config.inspect.bind(this)(shape, context)
+            }
+        }
+    }
+}
+
+export class Plugins {
+    constructor(private readonly plugins: Plugin[]) {}
+
+    toArray(): Plugin[] {
+        return this.plugins
+    }
+
+    add(plugin: Plugin): void {
+        this.plugins.push(plugin)
+    }
+
+    getCoalesceStrategy(table: string): CoalesceStrategy | undefined {
+        for (const plugin of this.plugins) {
+            const coalesceStrategy = plugin.getCoalesceStrategy(table)
+            if (coalesceStrategy) {
+                return coalesceStrategy
+            }
+        }
+
+        return undefined
+    }
+
+    getCoalesceTables(): Set<string> {
+        const tables = new Set<string>()
+        for (const plugin of this.plugins) {
+            plugin.getCoalesceTables().forEach((t) => {
+                tables.add(t)
+            })
+        }
+
+        return tables
+    }
+
+    getReferenceColumns(table: string): { [column: string]: string } {
+        const refColumnEntries: [string, string][] = []
+        for (const plugin of this.plugins) {
+            refColumnEntries.push(...Object.entries(plugin.getReferenceColumns(table)))
+        }
+
+        return Object.fromEntries(refColumnEntries)
+    }
+
+    async isEntryPoint(pathOrNode: string | SupportedNode, context: Omit<Context, 'self'>): Promise<boolean> {
+        for (const plugin of this.plugins) {
+            if (await plugin.isEntryPoint(pathOrNode, context)) {
+                return true
+            }
+        }
+
+        return false
+    }
+}