@servicenow/sdk-build-core 3.0.2 → 4.0.0

package/src/plugins/Plugin.ts

@@ -1,278 +0,0 @@
-import { SupportedKindName } from '@servicenow/sdk-project'
-import {
-    Extractors,
-    Composers,
-    Serializers,
-    Transformers,
-    Generators,
-    Arrangers,
-    PostProcessors,
-    Diagnostics,
-    TableOwnership,
-} from './behaviors'
-
-import type {
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    EntityComposerFunction,
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    XmlComposerFunction,
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    ArrangerFunction,
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    SerializerFunction,
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    GeneratorFunction,
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    TransformerFunction,
-} from './behaviors'
-
-/**
- * A plugin is an object that defines any number of behaviors that will
- * be invoked by the build system during various operations.
- *
- * The order of build operations during a normal build (code to XML) is
- * as follows:
- *
- *   Extract -> Compose -> Arrange -> Serialize
- *
- * The order of build operations during a transform (XML to code, AKA
- * "bi-directional sync") is as follows:
- *
- *   Extract -> Compose -> Arrange -> Generate -> Transform
- *
- * During each operation, all plugins which define behaviors for that
- * operation will be invoked. Therefore, plugins should always "fail
- * fast" to minimize performance impact. For example, if a plugin defines
- * an extractor for calls to a function named "exampleFunction", that
- * plugin should first validate the function name and return immediately
- * if the name is anything but "exampleFunction".
- *
- * @see {@linkcode Extractors}
- * @see {@linkcode Composers}
- * @see {@linkcode Arrangers}
- * @see {@linkcode Serializers}
- * @see {@linkcode Generators}
- * @see {@linkcode Transformers}
- */
-export type Plugin<
-    DiagnosticsNodeKinds extends SupportedKindName | 'Node' = any,
-    FluentRawNodeKinds extends SupportedKindName = any,
-    ModuleRawNodeKinds extends SupportedKindName = any,
-    JsonRawNodeKinds extends SupportedKindName = any,
-    AnyRawNodeKinds extends SupportedKindName = any,
-    FluentEntityNodeKinds extends SupportedKindName = any,
-    ModuleEntityNodeKinds extends SupportedKindName = any,
-    JsonEntityNodeKinds extends SupportedKindName = any,
-    AnyEntityNodeKinds extends SupportedKindName = any,
-    ArrangerDocumentKinds extends string = any,
-    SerializerDocumentKinds extends string = any,
-    GeneratorDocumentKinds extends string = any,
-    TransformerDocumentKinds extends string = any,
-> = {
-    /**
-     * Name of the plugin
-     */
-    name: string
-
-    diagnostics?: Diagnostics<DiagnosticsNodeKinds>
-
-    /**
-     * ServiceNow tables that this plugin handles and should not be serialized
-     * by generic plugins, and the appropriate diagnostic level to enforce on
-     * this relationship
-     */
-    ownedTables?: TableOwnership
-
-    /**
-     * Plugins may define extractors which extract raw data or entity data from
-     * AST nodes, or XML data from parsed XML files. The build system will take
-     * any entity data produced by an extractor and pass it along to any plugin
-     * that implements a composer for that kind of entity.
-     *
-     * An extractors object is an object with any of the keys 'xml', 'raw', or
-     * 'entity', where the values of those keys are nested objects where each
-     * key is the name of a kind of AST node, and the value is one of the types
-     * of extractor functions.
-     *
-     * @example
-     *   const extractors = {
-     *       entity: {
-     *           CallExpression(node, context) { ... }
-     *           ClassDeclaration(node, context) { ... }
-     *       }
-     *   }
-     */
-    extractors?: Extractors<
-        FluentRawNodeKinds,
-        ModuleRawNodeKinds,
-        JsonRawNodeKinds,
-        AnyRawNodeKinds,
-        FluentEntityNodeKinds,
-        ModuleEntityNodeKinds,
-        JsonEntityNodeKinds,
-        AnyEntityNodeKinds
-    >
-
-    /**
-     * Plugins may define composers for both entity data (from the
-     * source code) and XML data (from XML files). The job of a
-     * composer is to turn a piece of extracted data into one or more
-     * documents which can then be serialized or transformed.
-     *
-     * A composers object that has two optional keys: 'entity' and 'xml'. The
-     * value of the 'xml' key is a {@linkcode XmlComposerFunction}. The value of
-     * the 'entity' key is another object where each key is the name of a kind
-     * of entity, and the value is a {@linkcode EntityComposerFunction}.
-     *
-     * @example
-     *   const composers = {
-     *       entity: {
-     *           MyFirstEntity(data, context) { ... }
-     *           MyOtherEntity(data, context) { ... }
-     *       },
-     *       xml: {
-     *           record(data, context) { ... }
-     *       }
-     *   }
-     */
-    composers?: Composers
-
-    /**
-     * Plugins may define arrangers which take documents and return their parents
-     * so that the build system can arrange them in a tree structure.
-     *
-     * An arrangers object is an object where each key is the name of a kind of
-     * document, and the value is a {@linkcode ArrangerFunction}.
-     *
-     * @example
-     *   const arrangers = {
-     *       MyFirstDocument(document, context) { ... },
-     *       MyOtherDocument(document, context) { ... }
-     *   }
-     */
-    arrangers?: Arrangers<ArrangerDocumentKinds>
-
-    /**
-     * Plugins may define serializers which turn documents into files which the
-     * build system will write to the filesystem as output.
-     *
-     * A serializers object is an object where each key is the name of a kind of
-     * document, and the value is a {@linkcode SerializerFunction}.
-     *
-     * @example
-     *   const serializers = {
-     *       MyFirstDocument(document, context) { ... },
-     *       MyOtherDocument(document, context) { ... }
-     *   }
-     */
-    serializers?: Serializers<SerializerDocumentKinds>
-
-    /**
-     * Plugins may define generators which create new nodes for documents that
-     * don't have nodes, usually because they were extracted from XML files and
-     * aren't defined yet in the source code. The build system will pass each
-     * document without a node to any plugin which implements a generator for
-     * that kind of document. These documents are then passed along to the
-     * transformers along with all the other documents which already had nodes.
-     *
-     * A generators object is an object where each key is the name of a kind of
-     * document, and the value is a {@linkcode GeneratorFunction}.
-     *
-     * @example
-     *   const generators = {
-     *       MyFirstDocument(document, context) { ... },
-     *       MyOtherDocument(document, context) { ... }
-     *   }
-     */
-    generators?: Generators<GeneratorDocumentKinds>
-
-    /**
-     * Plugins may define transformers which take linked documents and perform
-     * transformations on their linked nodes to ensure each document is fully
-     * represented in the source code.
-     *
-     * A transformers object is an object where each key is the name of a kind of
-     * document, and the value is another object where each key is the name of a
-     * kind of AST node, and the value is a {@linkcode TransformerFunction}.
-     *
-     * @example
-     *   const transformers = {
-     *       MyFirstDocument: {
-     *           CallExpression(document, context) { ... },
-     *           ClassDeclaration(document, context) { ... }
-     *       },
-     *       MyOtherDocument: {
-     *           CallExpression(document, context) { ... },
-     *           ClassDeclaration(document, context) { ... }
-     *       }
-     *   }
-     */
-    transformers?: Transformers<TransformerDocumentKinds>
-
-    /**
-     * Plugins may define post-processors for data from certain stages of the build
-     * process. For example, a post-processor for entities will be called after the
-     * extraction stage and will receive all entities extracted by all plugins.
-     * These can be used for arbitrary operations based on extracted data.
-     *
-     * @example
-     *   const postProcessors = {
-     *       entities(entities, context) { ... }
-     *   }
-     */
-    postProcessors?: PostProcessors
-}
-
-/**
- * Utility function to create a new {@linkcode Plugin} object. Provides
- * the simplest and most type-safe experience for defining a plugin, but
- * is not required.
- *
- * @param plugin The {@linkcode Plugin} configuration
- * @returns a {@linkcode Plugin} object
- */
-export function Plugin<
-    const DiagnosticsNodeKinds extends SupportedKindName | 'Node',
-    const FluentRawNodeKinds extends SupportedKindName,
-    const ModuleRawNodeKinds extends SupportedKindName,
-    const JsonRawNodeKinds extends SupportedKindName,
-    const AnyRawNodeKinds extends SupportedKindName,
-    const FluentEntityNodeKinds extends SupportedKindName,
-    const ModuleEntityNodeKinds extends SupportedKindName,
-    const JsonEntityNodeKinds extends SupportedKindName,
-    const AnyEntityNodeKinds extends SupportedKindName,
-    const SerializerDocumentKinds extends string,
-    const GeneratorDocumentKinds extends string,
-    const TransformerDocumentKinds extends string,
-    const P extends Plugin<
-        DiagnosticsNodeKinds,
-        FluentRawNodeKinds,
-        ModuleRawNodeKinds,
-        JsonRawNodeKinds,
-        AnyRawNodeKinds,
-        FluentEntityNodeKinds,
-        ModuleEntityNodeKinds,
-        JsonEntityNodeKinds,
-        AnyEntityNodeKinds,
-        SerializerDocumentKinds,
-        GeneratorDocumentKinds,
-        TransformerDocumentKinds
-    >,
->(
-    plugin: P &
-        Plugin<
-            DiagnosticsNodeKinds,
-            FluentRawNodeKinds,
-            ModuleRawNodeKinds,
-            JsonRawNodeKinds,
-            AnyRawNodeKinds,
-            FluentEntityNodeKinds,
-            ModuleEntityNodeKinds,
-            JsonEntityNodeKinds,
-            AnyEntityNodeKinds,
-            GeneratorDocumentKinds,
-            TransformerDocumentKinds
-        >
-) {
-    return plugin as P
-}

package/src/plugins/behaviors/Arranger.ts

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

package/src/plugins/behaviors/Composer.ts

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

package/src/plugins/behaviors/Diagnostics.ts

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

package/src/plugins/behaviors/Generator.ts

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

package/src/plugins/behaviors/OwnedTables.ts

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

package/src/plugins/behaviors/PostProcessor.ts

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

package/src/plugins/behaviors/Serializer.ts

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

package/src/plugins/behaviors/Transformer.ts

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