@servicenow/sdk-build-core 4.6.0 → 4.7.0

package/src/plugins/plugin.ts

@@ -5,17 +5,26 @@ import {
     type SupportedNodeByKindName,
     ts,
 } from '../typescript'
-import { DeletedShape, type ObjectShape, type Record, type Shape, type ShapeClass, type StringShape } from './shape'
+import {
+    CallExpressionShape,
+    DeletedShape,
+    type ObjectShape,
+    type Record,
+    type Shape,
+    type ShapeClass,
+    type StringShape,
+    VariableStatementShape,
+} 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 type { Context as BaseContext, Diagnostics } from './context'
 import { getFileType, isSNScope } from '../util'
-import { Cache } from './cache'
-import { NOW_FILE_EXTENSION } from '..'
+import { NOW_FILE_EXTENSION, NowConfig } from '..'
 import { path } from '@servicenow/sdk-build-core'
 
 type Context = Omit<BaseContext, 'keys'>
+const FAILURE = { success: false } as const
 
 export type Result<Value = unknown> =
     | {
@@ -93,29 +102,6 @@ export type CoalesceStrategy =
 
 export type FileType = 'fluent' | 'module' | 'json' | 'unknown'
 
-export type PluginApiDoc = {
-    /**
-     * The name of the API (e.g., 'BusinessRule', 'Acl', 'Table')
-     * This is the callee name used in fluent code.
-     */
-    apiName: string
-
-    /**
-     * Tags for categorizing and organizing the API documentation
-     */
-    tags: string[]
-}
-
-/**
- * Manifest structure for API documentation.
- */
-export type DocsManifest = {
-    [apiName: string]: {
-        docPath: string
-        tags: string[]
-    }
-}
-
 export type PluginConfig<
     Nodes extends SupportedKindName[] = SupportedKindName[],
     Shapes extends ShapeClass[] = ShapeClass[],
@@ -127,12 +113,6 @@ export type PluginConfig<
      */
     name: `${string}Plugin`
 
-    /**
-     * Documentation for the APIs provided by this plugin. This is used to automatically
-     * generate documentation that can be retrieved via the getDocsMetadata() method.
-     */
-    docs: PluginApiDoc[]
-
     /**
      * The TypeScript AST nodes this plugin handles. Plugins that do not introduce new
      * syntax should not need to define any handlers here.
@@ -427,7 +407,7 @@ export type PluginConfig<
         /**
          * 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>)
+        matcher?: RegExp | FileMatcher
 
         /**
          * Indicates whether this file should be parsed as an entry point when generating output. (Default: false)
@@ -444,6 +424,12 @@ export type PluginConfig<
          */
         toRecord?(file: File, context: Context): Result<Record> | Promise<Result<Record>>
     }[]
+
+    /**
+     * @deprecated This property is no longer read and will be removed in a
+     * future release.
+     */
+    docs?: any[]
 }
 
 function setCreator<V extends Product | Product[]>(creator: Plugin, result: Result<V>): Result<V> {
@@ -466,10 +452,229 @@ type SearchableReferences = {
     }
 }
 
+/**
+ * Recursively sets `sys_policy` on a record and all its descendants,
+ * skipping any record that already has `sys_policy` set by the plugin.
+ */
+function propagateSysPolicyToDescendants(record: Record, sysPolicyShape: Shape): Record {
+    const patched = record.get('sys_policy').isUndefined() ? record.merge({ sys_policy: sysPolicyShape }) : record
+
+    // flat() cannot substitute here: it collapses the entire descendant tree into a single array,
+    // discarding which records are direct children of which parent. This function rebuilds the
+    // hierarchy bottom-up via .with(), so it must operate one level at a time using getRelated().
+    const children = patched.getRelated()
+    if (children.length === 0) {
+        return patched
+    }
+
+    return patched.with(...children.map((child) => propagateSysPolicyToDescendants(child, sysPolicyShape)))
+}
+
+/**
+ * Auto-injects `sys_policy` into the record and all its descendants from the shape's
+ * `protectionPolicy` property, so that plugins don't need to explicitly map it.
+ * Only injects if `sys_policy` is not already set by the plugin, and only propagates
+ * if the root record's plugin did not already handle `sys_policy` itself.
+ */
+function mergeSysPolicyFromShape(shape: Shape, record: Record): Record {
+    if (!(shape instanceof CallExpressionShape)) {
+        return record
+    }
+
+    const source = shape.getArgument(0).ifObject()
+    if (!source) {
+        return record
+    }
+
+    const protectionPolicy = source.get('protectionPolicy')
+    if (protectionPolicy.isUndefined()) {
+        return record
+    }
+
+    // If the plugin already mapped sys_policy on the root record, skip propagation entirely.
+    // The plugin owns the protectionPolicy handling in this case.
+    if (record.get('sys_policy').isDefined()) {
+        return record
+    }
+
+    return propagateSysPolicyToDescendants(record, protectionPolicy)
+}
+
+/**
+ * Auto-injects `protectionPolicy` into the shape from the record's `sys_policy` field,
+ * so that plugins don't need to explicitly map it. Only injects if `protectionPolicy` is
+ * not already set by the plugin.
+ */
+function mergeProtectionPolicyFromRecord(record: Record, shape: Shape): Shape {
+    if (!(shape instanceof CallExpressionShape)) {
+        return shape
+    }
+
+    const firstArg = shape.getArgument(0).ifObject()
+    if (!firstArg || firstArg.get('protectionPolicy').isDefined()) {
+        return shape
+    }
+
+    const sysPolicy = record.get('sys_policy').ifString()?.getValue()
+    if (!sysPolicy) {
+        return shape
+    }
+
+    return new CallExpressionShape({
+        source: shape.getSource(),
+        callee: shape.getCallee(),
+        args: [firstArg.merge({ protectionPolicy: sysPolicy }), ...shape.getArguments().slice(1)],
+        exportName: shape.getExportName(),
+    })
+}
+
+/**
+ * Auto-injects `$meta.installMethod` into the shape based on the record's install category.
+ * When transforming from `unload.demo/`, `unload/`, or `apply_once/` directories, the generated
+ * Fluent code should include `$meta: { installMethod: 'demo' | 'first install' | 'once' }`.
+ * Only injects if `$meta.installMethod` is not already set by the plugin.
+ */
+function mergeMetaFromRecord(record: Record, shape: Shape): Shape {
+    if (!(shape instanceof CallExpressionShape)) {
+        return shape
+    }
+
+    const firstArg = shape.getArgument(0).ifObject()
+    const existingMeta = firstArg?.get('$meta').ifObject()
+    if (!firstArg || existingMeta?.get('installMethod').isDefined()) {
+        return shape
+    }
+
+    const installCategory = record.getInstallCategory()
+    let installMethod: 'demo' | 'first install' | 'once' | undefined
+    if (installCategory === 'unload.demo') {
+        installMethod = 'demo'
+    } else if (installCategory === 'unload') {
+        installMethod = 'first install'
+    } else if (installCategory === 'apply_once') {
+        installMethod = 'once'
+    }
+
+    if (!installMethod) {
+        return shape
+    }
+
+    return new CallExpressionShape({
+        source: shape.getSource(),
+        callee: shape.getCallee(),
+        args: [firstArg.merge({ $meta: { installMethod } }), ...shape.getArguments().slice(1)],
+        exportName: shape.getExportName(),
+    })
+}
+
+/**
+ * Injects `$override` properties from the Fluent shape into the record, so plugins don't
+ * need to explicitly map them. Only injects fields not already set by the plugin.
+ */
+function mergeOverrideFromShape(shape: Shape, record: Record, diagnostics: Diagnostics): Record {
+    if (!(shape instanceof CallExpressionShape)) {
+        return record
+    }
+    const override = shape.getArgument(0).ifObject()?.get('$override').ifObject()
+    if (!override) {
+        return record
+    }
+
+    const extra: { [key: string]: Shape } = {}
+    const overrideKeys = new Set<string>()
+    for (const [key, value] of override.entries()) {
+        if (key.startsWith('sys_')) {
+            diagnostics.warn(
+                value,
+                `$override: '${key}' starts with 'sys_' and will not be restored on transform — remove it or use a supported API property instead.`
+            )
+            continue
+        }
+        if (record.get(key).isDefined()) {
+            diagnostics.warn(
+                value,
+                `$override: '${key}' is already set by the plugin and will be ignored — use the corresponding API property instead.`
+            )
+            continue
+        }
+        overrideKeys.add(key)
+        extra[key] = value
+    }
+
+    const result = overrideKeys.size > 0 ? record.merge(extra) : record
+    return result.withOverrideKeys(overrideKeys)
+}
+
+/**
+ * Injects `$override` into the shape. Includes:
+ * - Custom fields (`u_*` / `x_*`) with non-empty values.
+ * - Any field that was explicitly in the existing record's `$override` — re-emitted with the
+ *   fresh DB value.
+ */
+function mergeOverrideFromRecord(record: Record, shape: Shape, accessed: Set<string>, existingRecord?: Record): Shape {
+    const inner = shape instanceof VariableStatementShape ? shape.getInitializer() : shape
+    const ce = inner instanceof CallExpressionShape ? inner : null
+    if (!ce) {
+        return shape
+    }
+
+    const firstArg = ce.getArgument(0).ifObject()
+    if (!firstArg || firstArg.get('$override').isDefined()) {
+        return shape
+    }
+
+    const existingOverrideKeys = existingRecord?.getOverrideKeys()
+    const override: globalThis.Record<string, Shape> = {}
+    for (const [key, value] of record.entries()) {
+        if (key.startsWith('sys_') || accessed.has(key)) {
+            continue
+        }
+        const isCustomField = key.startsWith('u_') || key.startsWith('x_')
+        if (!isCustomField && !existingOverrideKeys?.has(key)) {
+            continue
+        }
+        // Preserve empty strings when the key was explicitly put in $override previously —
+        // that's how users clear a field. Only skip empty strings for newly-discovered fields.
+        const wasExplicitlyOverridden = existingOverrideKeys?.has(key)
+        if (!value.isDefined() || (!wasExplicitlyOverridden && value.ifString()?.isEmpty())) {
+            continue
+        }
+        override[key] = value
+    }
+
+    if (Object.keys(override).length === 0) {
+        return shape
+    }
+
+    const modified = new CallExpressionShape({
+        source: ce.getSource(),
+        callee: ce.getCallee(),
+        args: [firstArg.merge({ $override: override }), ...ce.getArguments().slice(1)],
+        exportName: ce.getExportName(),
+    })
+
+    if (!(shape instanceof VariableStatementShape)) {
+        return modified
+    }
+    return new VariableStatementShape({
+        source: shape.getSource(),
+        variableName: shape.getVariableName(),
+        initializer: modified,
+        isExported: shape.isExported(),
+    })
+}
+
+type FileMatcher = (path: string, context: Context) => boolean | Promise<boolean>
+
+type EntryPoints = {
+    readonly nodes: Map<SupportedKindName, Set<FileType | '*'>>
+    readonly files: {
+        readonly plugin: Plugin
+        readonly matcher: RegExp | FileMatcher
+    }[]
+}
+
 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 = {}
 
@@ -630,23 +835,6 @@ export class Plugin {
         return this.config.name
     }
 
-    /**
-     * Get documentation metadata for APIs provided by this plugin.
-     */
-    getDocsMetadata(): { [apiName: string]: { tags: string[] } } | undefined {
-        if (!this.config.docs) {
-            return undefined
-        }
-
-        const manifest: { [apiName: string]: { tags: string[] } } = {}
-
-        for (const doc of this.config.docs) {
-            manifest[doc.apiName] = { tags: doc.tags }
-        }
-
-        return manifest
-    }
-
     getDescendants(parent: Record, database: Database): Record[] {
         return this.traverseDescendants(parent, database)
     }
@@ -778,38 +966,6 @@ export class Plugin {
         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.success ? entry.value : { success: false }
-        }
-
-        try {
-            for (const config of this.config.nodes ?? []) {
-                if (
-                    config.toShape &&
-                    getKindName(node) === config.node &&
-                    (!config.fileTypes ||
-                        config.fileTypes.includes(getFileType(node.getSourceFile().getFilePath(), context.project)))
-                ) {
-                    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) {
@@ -820,7 +976,7 @@ export class Plugin {
             }
         }
 
-        return { success: false }
+        return FAILURE
     }
 
     async getTarget(shape: Shape, context: Omit<Context, 'self'>): Promise<Result<ts.Node>> {
@@ -832,116 +988,70 @@ export class Plugin {
                 }
             }
         }
-
-        return { success: false }
+        return FAILURE
     }
 
-    async shapeToSubclass<const S extends Shape>(shape: S, context: Omit<Context, 'self'>): Promise<Result<S>> {
-        const entry = this.shapeToSubclassCache.get(shape)
-        if (entry) {
-            return entry.success ? (entry.value as Result<S>) : { success: false }
-        }
-
-        try {
-            for (const config of this.config.shapes ?? []) {
-                if (
-                    config.toSubclass &&
-                    shape.constructor === config.shape &&
-                    (!config.fileTypes ||
-                        config.fileTypes.includes(getFileType(shape.getOriginalFilePath(), context.project)))
-                ) {
-                    const result = setCreator(
-                        this,
-                        await 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.success ? entry.value : { success: false }
-        }
-
-        try {
-            for (const config of this.config.shapes ?? []) {
-                if (
-                    config.toRecord &&
-                    shape.is(config.shape) &&
-                    (!config.fileTypes ||
-                        config.fileTypes.includes(getFileType(shape.getOriginalFilePath(), context.project)))
-                ) {
-                    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>> {
+    private async recordToShape0(
+        record: Record,
+        context: Omit<RecordContext, 'self'>,
+        existingRecord?: Record
+    ): 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
-                }
+        for (const [configTable, recordConfig] of Object.entries(this.config.records ?? {})) {
+            if (configTable !== '*' && configTable !== table) {
+                continue
+            }
+            if (!recordConfig.toShape) {
+                continue
+            }
+
+            record.startTracking()
+            const result = setCreator(this, await recordConfig.toShape.bind(this)(record, { ...context, self: this }))
+            if (result.success) {
+                const accessed = record.getTrackedFields()
+                let value = mergeOverrideFromRecord(record, result.value, accessed, existingRecord)
+                value = mergeProtectionPolicyFromRecord(record, value)
+                value = mergeMetaFromRecord(record, value)
+                return { ...result, value }
             }
         }
 
-        return { success: false }
+        return FAILURE
     }
 
     async recordToShape({
         record,
         database,
+        existingDatabase,
         context,
     }: {
         record: Record
         database: Database
+        existingDatabase?: 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')),
-        })
+        const existingRecord = existingDatabase?.resolve(record.getId())
+        return this.recordToShape0(
+            record,
+            {
+                ...context,
+                database,
+                descendants: new Database(descendants.filter((r) => r.getAction() === 'INSERT_OR_UPDATE')),
+            },
+            existingRecord
+        )
     }
 
     async recordsToShapes({
         database,
+        existingDatabase,
         creatorOnly,
         changedOnly = false,
         mode,
@@ -949,6 +1059,7 @@ export class Plugin {
         context,
     }: {
         database: Database
+        existingDatabase?: Database
         creatorOnly: boolean
         changedOnly?: boolean
         mode: 'explicit' | 'catch-all'
@@ -1007,11 +1118,16 @@ export class Plugin {
                     }
                 }
 
-                const result = await this.recordToShape0(record, {
-                    ...context,
-                    database,
-                    descendants: nonDeletedDescendants,
-                })
+                const existingRecord = existingDatabase?.resolve(record.getId())
+                const result = await this.recordToShape0(
+                    record,
+                    {
+                        ...context,
+                        database,
+                        descendants: nonDeletedDescendants,
+                    },
+                    existingRecord
+                )
 
                 if (result.success === 'partial') {
                     for (const unhandledRecord of result.unhandledRecords) {
@@ -1041,7 +1157,7 @@ export class Plugin {
                             } else if (
                                 !descendant.getCreator() ||
                                 !record.getCreator() ||
-                                descendant.getCreator()!.getName() === record.getCreator()!.getName()
+                                descendant.getCreator()?.getName() === record.getCreator()?.getName()
                             ) {
                                 // This descendant is handled by the same plugin that handled the root record
                                 handledRecords.insert(descendant)
@@ -1054,7 +1170,7 @@ export class Plugin {
 
         if (unhandledRecords.length > 0) {
             context.logger.debug(
-                `Plugin ${this.getName()} deferred handling of records: ${unhandledRecords.map((r) => r.getTable() + '_' + r.getId().getValue()).join(', ')}`
+                `Plugin ${this.getName()} deferred handling of records: ${unhandledRecords.map((r) => `${r.getTable()}_${r.getId().getValue()}`).join(', ')}`
             )
             return { success: 'partial', value: shapes, unhandledRecords }
         }
@@ -1135,12 +1251,31 @@ export class Plugin {
                     const filePath = path.normalize(record.getOriginalFilePath())
                     if (isSNScope(context.config.scope) && filePath.endsWith(NOW_FILE_EXTENSION)) {
                         const relativePath = path.relative(path.join(context.config.fluentDir, 'if'), filePath)
-                        if (!relativePath.startsWith('..') && path.dirname(relativePath) !== '.') {
+                        const relativePathGenerated = path.relative(
+                            path.join(context.config.generatedDir, 'if'),
+                            filePath
+                        )
+                        if (
+                            !relativePath.startsWith('..') ||
+                            (!relativePathGenerated.startsWith('..') && path.dirname(relativePath) !== '.')
+                        ) {
+                            const subPath = relativePath.startsWith('..') ? relativePathGenerated : relativePath
+                            return {
+                                success: true,
+                                value: outputFiles.map((f) => ({
+                                    ...f,
+                                    ifDirectoryPackage: path.join('if', subPath.split(path.sep)[0]!),
+                                })),
+                            }
+                        }
+
+                        const hosted = NowConfig.getHostedDirectory(context.config, filePath)
+                        if (hosted) {
                             return {
                                 success: true,
                                 value: outputFiles.map((f) => ({
                                     ...f,
-                                    ifDirectoryPackage: path.join('if', path.dirname(relativePath)),
+                                    hostedPluginDir: hosted,
                                 })),
                             }
                         }
@@ -1151,7 +1286,7 @@ export class Plugin {
             }
         }
 
-        return { success: false }
+        return FAILURE
     }
 
     async recordsToFiles({
@@ -1210,38 +1345,44 @@ export class Plugin {
         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
-                }
+    getEntryPoints(): EntryPoints {
+        const entryPoints: EntryPoints = {
+            nodes: new Map(),
+            files: [],
+        }
 
-                const fileType = getFileType(pathOrNode.getSourceFile().getFilePath(), context.project)
-                if (config.fileTypes && !config.fileTypes.includes(fileType)) {
-                    continue
-                }
+        for (const config of this.config.nodes ?? []) {
+            if (!config.entryPoint) {
+                continue
+            }
 
-                return !!config.entryPoint
+            const fileTypes = entryPoints.nodes.get(config.node) ?? new Set()
+            if (config.fileTypes) {
+                // Plugin only accepts the node from certain file types
+                config.fileTypes.forEach((t) => fileTypes.add(t))
+            } else {
+                // Plugin accepts the node from any file type
+                fileTypes.add('*')
             }
-        } 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
-                }
+            entryPoints.nodes.set(config.node, fileTypes)
+        }
 
-                return !!config.entryPoint
+        for (const config of this.config.files ?? []) {
+            if (!config.entryPoint) {
+                continue
             }
+
+            if (!config.matcher) {
+                throw new Error(
+                    `Plugin "${this.getName()}" defines a file entry point with no matcher. This would cause all files to be treated as entry points.`
+                )
+            }
+
+            entryPoints.files.push({ plugin: this, matcher: config.matcher })
         }
 
-        return false
+        return entryPoints
     }
 
     async fileToRecord(file: File, context: Omit<Context, 'self'>): Promise<Result<Record>> {
@@ -1264,7 +1405,7 @@ export class Plugin {
             }
         }
 
-        return { success: false }
+        return FAILURE
     }
 
     inspect(shape: Shape, context: Omit<Context, 'self'>): void {
@@ -1286,34 +1427,142 @@ export class Plugin {
             }
         }
 
-        return { success: false }
+        return FAILURE
+    }
+
+    getConfig(): PluginConfig {
+        return this.config
     }
 }
 
-export class Plugins {
-    constructor(private readonly plugins: Plugin[]) {}
+type PluginEntry = {
+    plugin: Plugin
+    shapeCount: number
+    nodeToShapeCache: WeakMap<ts.ts.Node, Result<Shape>>
+    shapeToSubclassCache: WeakMap<Shape, Result<Shape>>
+    shapeToRecordCache: WeakMap<Shape, Result<Record>>
+}
+
+export class Plugins implements Iterable<Plugin> {
+    private plugins = new Map<string, PluginEntry>()
+
+    private nodeToShapeCache = new WeakMap<ts.ts.Node, Result<Shape>>()
+    private shapeToSubclassCache = new WeakMap<Shape, Shape>()
+    private shapeToRecordCache = new WeakMap<Shape, Result<Record>>()
+
+    private readonly entryPoints: EntryPoints = {
+        nodes: new Map(),
+        files: [],
+    }
+
+    constructor(plugins: Plugin[]) {
+        for (const plugin of plugins) {
+            this.plugins.set(plugin.getName(), Plugins.createEntry(plugin))
+        }
+
+        this.reload()
+    }
+
+    private static createEntry(plugin: Plugin): PluginEntry {
+        return {
+            plugin,
+            shapeCount: 0,
+            nodeToShapeCache: new WeakMap(),
+            shapeToSubclassCache: new WeakMap(),
+            shapeToRecordCache: new WeakMap(),
+        }
+    }
+
+    private get(plugin: string | Plugin): PluginEntry {
+        const name = plugin instanceof Plugin ? plugin.getName() : plugin
+        const entry = this.plugins.get(name)
+        if (entry) {
+            return entry
+        }
+
+        if (plugin instanceof Plugin) {
+            // Some plugins (mainly Flows) use "helper" plugins that are not actually registered. This is temporarily supporting that use case until we can get rid of those "helper" plugins.
+            return Plugins.createEntry(plugin)
+        }
 
-    toArray(): Plugin[] {
-        return this.plugins
+        throw new Error(`No such plugin with name "${name}"`)
     }
 
-    remove(name: string): void {
-        const index = this.plugins.findIndex((plugin) => plugin.getName() === name)
-        if (index !== -1) {
-            this.plugins.splice(index, 1)
+    *[Symbol.iterator](): Iterator<Plugin> {
+        for (const entry of this.plugins.values()) {
+            yield entry.plugin
+        }
+    }
+
+    reload(): void {
+        this.nodeToShapeCache = new WeakMap()
+        this.shapeToSubclassCache = new WeakMap()
+        this.shapeToRecordCache = new WeakMap()
+
+        this.entryPoints.nodes.clear()
+        this.entryPoints.files.length = 0
+
+        for (const entry of this.plugins.values()) {
+            entry.nodeToShapeCache = new WeakMap()
+            entry.shapeToSubclassCache = new WeakMap()
+            entry.shapeToRecordCache = new WeakMap()
+            entry.shapeCount = 0
+
+            const { nodes, files } = entry.plugin.getEntryPoints()
+            for (const [nodeKind, fileTypes] of nodes.entries()) {
+                const existing = this.entryPoints.nodes.get(nodeKind) ?? new Set()
+                for (const type of fileTypes) {
+                    existing.add(type)
+                }
+
+                this.entryPoints.nodes.set(nodeKind, existing)
+            }
+
+            this.entryPoints.files.push(...files)
         }
     }
 
     prepend(...plugins: Plugin[]): void {
-        this.plugins.unshift(...plugins)
+        const newMap = new Map<string, PluginEntry>()
+        for (const plugin of plugins) {
+            const name = plugin.getName()
+            newMap.set(name, Plugins.createEntry(plugin))
+            this.plugins.delete(name)
+        }
+
+        for (const [name, entry] of this.plugins.entries()) {
+            newMap.set(name, entry)
+        }
+
+        this.plugins = newMap
+        this.reload()
     }
 
     append(...plugins: Plugin[]): void {
-        this.plugins.push(...plugins)
+        for (const plugin of plugins) {
+            const name = plugin.getName()
+            this.plugins.delete(name)
+            this.plugins.set(name, Plugins.createEntry(plugin))
+        }
+
+        this.reload()
+    }
+
+    getShapeCountPerPlugin() {
+        return [...this.plugins.entries()].map(([name, { shapeCount }]) => ({
+            plugin: name.replace(/Plugin$/, ''), //Report just the names 'ACL', 'Record', etc for existing metrics compatibility
+            count: shapeCount,
+        }))
+    }
+
+    clearShapeCounts() {
+        for (const entry of this.plugins.values()) {
+            entry.shapeCount = 0
+        }
     }
 
     getCoalesceStrategy(table: string): CoalesceStrategy | undefined {
-        for (const plugin of this.plugins) {
+        for (const plugin of this) {
             const coalesceStrategy = plugin.getCoalesceStrategy(table)
             if (coalesceStrategy) {
                 return coalesceStrategy
@@ -1324,7 +1573,7 @@ export class Plugins {
     }
 
     isComposite(table: string): boolean {
-        for (const plugin of this.plugins) {
+        for (const plugin of this) {
             if (plugin.isComposite(table)) {
                 return true
             }
@@ -1335,7 +1584,7 @@ export class Plugins {
 
     getCoalesceTables(): Set<string> {
         const tables = new Set<string>()
-        for (const plugin of this.plugins) {
+        for (const plugin of this) {
             plugin.getCoalesceTables().forEach((t) => {
                 tables.add(t)
             })
@@ -1346,7 +1595,7 @@ export class Plugins {
 
     getReferenceColumns(table: string): { [column: string]: string } {
         const refColumnEntries: [string, string][] = []
-        for (const plugin of this.plugins) {
+        for (const plugin of this) {
             refColumnEntries.push(...Object.entries(plugin.getReferenceColumns(table)))
         }
 
@@ -1354,25 +1603,249 @@ export class Plugins {
     }
 
     async isEntryPoint(pathOrNode: string | SupportedNode, context: Omit<Context, 'self'>): Promise<boolean> {
-        for (const plugin of this.plugins) {
-            if (await plugin.isEntryPoint(pathOrNode, context)) {
+        if (ts.Node.isNode(pathOrNode)) {
+            const fileTypes = this.entryPoints.nodes.get(getKindName(pathOrNode))
+            if (!fileTypes || fileTypes.size <= 0) {
+                return false
+            } else if (fileTypes.has('*')) {
                 return true
+            } else {
+                return fileTypes.has(getFileType(pathOrNode.getSourceFile().getFilePath(), context.project))
+            }
+        } else {
+            for (const { plugin, matcher } of this.entryPoints.files) {
+                if (matcher instanceof RegExp && matcher.test(pathOrNode)) {
+                    return true
+                } else if (typeof matcher === 'function' && (await matcher(pathOrNode, { ...context, self: plugin }))) {
+                    return true
+                }
             }
         }
 
         return false
     }
 
-    getDocsMetadata(): { [apiName: string]: { tags: string[] } } {
-        return this.plugins.reduce(
-            (aggregated, plugin) => {
-                const pluginManifest = plugin.getDocsMetadata()
-                if (pluginManifest) {
-                    Object.assign(aggregated, pluginManifest)
+    async nodeToShape(
+        node: SupportedNode,
+        context: Omit<Context, 'self'>,
+        ...plugins: (string | Plugin)[]
+    ): Promise<Result<Shape>> {
+        if (plugins.length > 0) {
+            // Bypass global cache when requesting specific plugins
+            return this.nodeToShape0(node, context, ...plugins)
+        }
+
+        // We're not requesting specific plugins, so it's safe to use the global cache
+        const cached = this.nodeToShapeCache.get(node.compilerNode)
+        if (cached) {
+            return cached
+        }
+
+        try {
+            const result = await this.nodeToShape0(node, context)
+            this.nodeToShapeCache.set(node.compilerNode, result)
+            return result
+        } catch (e) {
+            this.nodeToShapeCache.set(node.compilerNode, FAILURE)
+            throw e
+        }
+    }
+
+    private async nodeToShape0(
+        node: SupportedNode,
+        context: Omit<Context, 'self'>,
+        ...plugins: (string | Plugin)[]
+    ): Promise<Result<Shape>> {
+        for (const entry of plugins.length > 0 ? plugins.map((plugin) => this.get(plugin)) : this.plugins.values()) {
+            const cached = entry.nodeToShapeCache.get(node.compilerNode)
+            if (cached) {
+                if (cached.success) {
+                    return cached
+                } else {
+                    continue
                 }
-                return aggregated
-            },
-            {} as { [apiName: string]: { tags: string[] } }
-        )
+            }
+
+            for (const config of entry.plugin.getConfig().nodes ?? []) {
+                if (
+                    config.toShape &&
+                    getKindName(node) === config.node &&
+                    (!config.fileTypes ||
+                        config.fileTypes.includes(getFileType(node.getSourceFile().getFilePath(), context.project)))
+                ) {
+                    try {
+                        const result = setCreator(
+                            entry.plugin,
+                            await config.toShape.bind(entry.plugin)(node, { ...context, self: entry.plugin })
+                        )
+
+                        entry.nodeToShapeCache.set(node.compilerNode, result)
+                        if (result.success) {
+                            entry.shapeCount++
+                            return result
+                        }
+                    } catch (error) {
+                        entry.nodeToShapeCache.set(node.compilerNode, FAILURE)
+                        context.logger.error(
+                            `Plugin "${entry.plugin.getName()}" failed to transform "${node.getKindName()}" node into shape:`,
+                            error
+                        )
+                    }
+                }
+            }
+        }
+
+        return FAILURE
+    }
+
+    async shapeToSubclass<const S extends Shape>(
+        shape: S,
+        context: Omit<Context, 'self'>,
+        ...plugins: (string | Plugin)[]
+    ): Promise<S> {
+        if (plugins.length > 0) {
+            // Bypass global cache when requesting specific plugins
+            return this.shapeToSubclass0(shape, context, ...plugins)
+        }
+
+        // We're not requesting specific plugins, so it's safe to use the global cache
+        const cached = this.shapeToSubclassCache.get(shape)
+        if (cached) {
+            return cached as S
+        }
+
+        const subclass = await this.shapeToSubclass0(shape, context)
+        this.shapeToSubclassCache.set(shape, subclass)
+        return subclass
+    }
+
+    private async shapeToSubclass0<const S extends Shape>(
+        shape: S,
+        context: Omit<Context, 'self'>,
+        ...plugins: (string | Plugin)[]
+    ): Promise<S> {
+        for (const entry of plugins.length > 0 ? plugins.map((plugin) => this.get(plugin)) : this.plugins.values()) {
+            const cached = entry.shapeToSubclassCache.get(shape)
+            if (cached) {
+                if (cached.success) {
+                    return cached.value as S
+                } else {
+                    continue
+                }
+            }
+
+            for (const config of entry.plugin.getConfig().shapes ?? []) {
+                if (
+                    config.toSubclass &&
+                    shape.constructor === config.shape &&
+                    (!config.fileTypes ||
+                        config.fileTypes.includes(getFileType(shape.getOriginalFilePath(), context.project)))
+                ) {
+                    try {
+                        const result = setCreator(
+                            entry.plugin,
+                            await config.toSubclass.bind(entry.plugin)(shape, { ...context, self: entry.plugin })
+                        ) as Result<S>
+
+                        entry.shapeToSubclassCache.set(shape, result)
+                        if (result.success) {
+                            if (result.value.constructor === config.shape) {
+                                throw new Error(
+                                    `Plugin "${entry.plugin.getName()}" tried to subclass "${config.shape.name}" to an instance of the same class. The result MUST be a subclass.`
+                                )
+                            }
+
+                            entry.shapeCount++
+                            return await this.shapeToSubclass(result.value, context, ...plugins)
+                        }
+                    } catch (error) {
+                        entry.shapeToSubclassCache.set(shape, FAILURE)
+                        context.logger.error(
+                            `Plugin "${entry.plugin.getName()}" failed to subclass "${shape.getKind()}" shape:`,
+                            error
+                        )
+                    }
+                }
+            }
+        }
+
+        return shape
+    }
+
+    async shapeToRecord(
+        shape: Shape,
+        context: Omit<Context, 'self'>,
+        ...plugins: (string | Plugin)[]
+    ): Promise<Result<Record>> {
+        if (shape.isRecord()) {
+            return { success: true, value: shape }
+        }
+
+        if (plugins.length > 0) {
+            // Bypass global cache when requesting specific plugins
+            return this.shapeToRecord0(shape, context, ...plugins)
+        }
+
+        // We're not requesting specific plugins, so it's safe to use the global cache
+        const cached = this.shapeToRecordCache.get(shape)
+        if (cached) {
+            return cached
+        }
+
+        const result = await this.shapeToRecord0(shape, context)
+        this.shapeToRecordCache.set(shape, result)
+        return result
+    }
+
+    private async shapeToRecord0(
+        shape: Shape,
+        context: Omit<Context, 'self'>,
+        ...plugins: (string | Plugin)[]
+    ): Promise<Result<Record>> {
+        for (const entry of plugins.length > 0 ? plugins.map((plugin) => this.get(plugin)) : this.plugins.values()) {
+            const cached = entry.shapeToRecordCache.get(shape)
+            if (cached) {
+                if (cached.success) {
+                    return cached
+                } else {
+                    continue
+                }
+            }
+
+            for (const config of entry.plugin.getConfig().shapes ?? []) {
+                if (
+                    config.toRecord &&
+                    shape.is(config.shape) &&
+                    (!config.fileTypes ||
+                        config.fileTypes.includes(getFileType(shape.getOriginalFilePath(), context.project)))
+                ) {
+                    try {
+                        const result = setCreator(
+                            entry.plugin,
+                            await config.toRecord.bind(entry.plugin)(shape, { ...context, self: entry.plugin })
+                        )
+
+                        entry.shapeToRecordCache.set(shape, result)
+                        if (result.success) {
+                            entry.shapeCount++
+                            result.value = mergeOverrideFromShape(
+                                shape,
+                                mergeSysPolicyFromShape(shape, result.value),
+                                context.diagnostics
+                            )
+                            return result
+                        }
+                    } catch (error) {
+                        entry.shapeToRecordCache.set(shape, FAILURE)
+                        context.logger.error(
+                            `Plugin "${entry.plugin.getName()}" failed to transform "${shape.getKind()}" shape into record:`,
+                            error
+                        )
+                    }
+                }
+            }
+        }
+
+        return FAILURE
     }
 }